⚡ Bandwidth Top-Up ($1 for +100GB)

This guide provides complete instructions and production-ready code examples to programmatically purchase and trigger an instant bandwidth reset (+100GB allowance) for your active WireGuard tunnel.

🎯 Overview

Each TunnelSats subscription includes 100 GB of high-speed bandwidth. When your node exceeds 70% bandwidth utilization (or runs out entirely and gets disabled), you can purchase a $1 USD Bandwidth Top-Up in Bitcoin Lightning (sats) without waiting for your monthly subscription renewal.

Node management packages (e.g., RaspiBlitz, Umbrel, Start9, Baremetal, LNDg) and automation daemons can monitor usage via /api/public/v1/subscription/status and automatically top up bandwidth when thresholds are reached.

📡 Endpoint Specification

`POST /api/public/v1/subscription/bandwidth-reset`

Authentication: None (Anonymous / Public API)

Rate Limit: 10 requests / minute per IP

Request Headers

Request Payload

{
  "wgPublicKey": "pWyZTQx8C4gzzgMVJHiN1ptI46wDtyJSMRa+wxtkXOM=",
  "serverId": "us-east"
}

Field	Type	Required	Description
`wgPublicKey`	`string`	Yes	44-character Base64 WireGuard public key of your node.
`serverId`	`string`	Yes	Server identifier, group domain (`eu-de`, `us-east`), or domain (`us3.tunnelsats.com`).

Response (200 OK)

{
  "invoice": "lnbc30000n1p...",
  "paymentHash": "a1b2c3d4e5f6...",
  "resetId": "d7b2277f-5990-4721-a565-6816babadc59",
  "amountSats": 3000,
  "amountUsd": "1.00",
  "currentUsagePercent": "85.4",
  "resetsThisMonth": 0,
  "maxResetsPerMonth": 2
}

Field	Type	Description
`invoice`	`string`	BOLT11 Lightning invoice for $1 USD equivalent in sats.
`paymentHash`	`string`	SHA256 payment hash for tracking invoice settlement.
`resetId`	`string`	Unique UUID tracking this bandwidth reset request.
`amountSats`	`number`	Invoice amount in satoshis calculated dynamically from real-time BTC price.
`amountUsd`	`string`	Fixed price (`"1.00"`).
`currentUsagePercent`	`string`	Current bandwidth consumption percentage on the VPN manager.
`resetsThisMonth`	`number`	Number of confirmed resets applied to this key in the current calendar month.
`maxResetsPerMonth`	`number`	Maximum allowed resets per month (`2`).

🛑 Business Rules & Validation

Rule	Constraint	Error Code	HTTP Status
Usage Threshold	Must exceed 70% bandwidth usage (`BANDWIDTH_WARNING_THRESHOLD_PERCENT`)	`ERR_INVALID_INPUT`	`400`
Active Subscription	Subscription must not be expired	`ERR_INVALID_INPUT`	`400`
Monthly Limit	Maximum 2 confirmed resets per calendar month per key	`ERR_RATE_LIMIT_EXCEEDED`	`429`
Server & Key	Key must exist on target server	`ERR_RESOURCE_NOT_FOUND`	`404`
Public Key Format	Must be a valid 44-character Base64 string	`ERR_INVALID_INPUT`	`400`

⚡ Settlement & Auto-Reenablement

Once the Lightning invoice is settled:

LNBits Webhook fires automatically to /api/webhooks/bandwidth-reset.

The backend contacts the respective WireGuard server manager and resets the bandwidth counter (bwReset: true).

If the peer key was disabled due to bandwidth exhaustion, it is automatically re-enabled immediately.

💻 Code Examples

Bash (cURL + jq + lncli)

Python (Requests)

Prerequisites

Requires curl, jq, and an active Lightning CLI (e.g. lncli, cln, alby-cli, or WebLN).

🎯 Overview#

📡 Endpoint Specification#

POST /api/public/v1/subscription/bandwidth-reset#

Request Headers#

Request Payload#

Response (200 OK)#

🛑 Business Rules & Validation#

⚡ Settlement & Auto-Reenablement#

💻 Code Examples#

🎯 Overview

📡 Endpoint Specification

`POST /api/public/v1/subscription/bandwidth-reset`

Request Headers

Request Payload

Response (200 OK)

🛑 Business Rules & Validation

⚡ Settlement & Auto-Reenablement

💻 Code Examples