🛠️ 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)

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 and handles the current "Production Reality" of dual-key configurations.

⚡ Bandwidth Top-Up Flow

For dedicated documentation on automated bandwidth resets, threshold validation, and payment settlement, see ⚡ Bandwidth Top-Up.

💡 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

In the examples above, we leave wgPublicKey empty in the /claim request. This tells the TunnelSats server to generate a fresh keypair for you. If you prefer to use your own keys, include your Public Key (Base64) in the request body.

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