🛠️ Automation & Code Examples

This guide provides production-ready scripts to purchase, pay for, and provision a VPN tunnel programmatically using TunnelSats.

⚡ Quick Start Scripts

Choose your preferred environment to automate the VPN lifecycle.

Python (Requests)

Node.js (fetch)

Bash (cURL + jq)

Recommended for Integrators

Use this script if you are building a dashboard, an auto-renewal bot, or integrating TunnelSats into node management software.

Prerequisites

The "Full Lifecycle" Script

This script automates the Create -> Pay -> Claim flow with a client-held key: the WireGuard keypair is generated locally, its public half is registered at /create, and the private key never leaves your machine.

⚡ Bandwidth Top-Up Flow

For dedicated documentation on automated bandwidth resets, your own usage policy, and payment settlement, see ⚡ Bandwidth Top-Up ($1 Usage Reset).

💡 Important Considerations

Invoice Expiry

Lightning invoices and their associated paymentHash typically expire within 10 minutes. If payment is not detected within this window, the polling script will timeout, and you must generate a new subscription request.

WireGuard Keys

Generate your WireGuard keypair before /create and send its public key as wgPublicKey, then repeat the same key at /claim. Every provisioning path (payment webhook, status polling, /claim) then uses your key only: the server never generates or stores a private key for the order, and /claim returns the tunnel parameters (server, peer, vpnPort) with fullConfig: null. A claim with a different or missing key is rejected with HTTP 409.

Orders created without wgPublicKey are legacy: the server generates the keypair and /claim returns fullConfig. Supplying your own key only at /claim is not reliable, because the payment webhook may already have provisioned a server-generated key.

Case Sensitivity Reality

Status/Create/Renew: Use camelCase (e.g., paymentHash, subscriptionEnd).

Subscription List: Uses snake_case (e.g., payment_hash, subscription_end).
Always verify your JSON keys against the endpoint documentation.

⚡ Quick Start Scripts#

Prerequisites#

The "Full Lifecycle" Script#

⚡ Bandwidth Top-Up Flow#

💡 Important Considerations#

⚡ Quick Start Scripts

Prerequisites

The "Full Lifecycle" Script

⚡ Bandwidth Top-Up Flow

💡 Important Considerations