1. Announcements
TunnelSats Public Wireguard API
  • Announcements
    • 👋 About our team
    • 💫 What is TunnelSats?
    • 🚀 Introducing the TunnelSats Public API v1
    • 🧩 How the TunnelSats StartOS Package Uses the Public API
    • How TunnelSats Leverages Public APIs for Confined VPN Management
    • 🤖 Autonomous Agent Payments (L402 & x402) & Level 5 Agent-Native Architecture
  • 📡 Discovery
    • List Available WireGuard Servers & Regions
      GET
    • L402 Agent Payment Gateway Discovery Metadata
      GET
  • ⚡ Purchase
    • Create a New WireGuard Subscription (Invoice Generation)
      POST
    • Check Invoice Status & Polling by Payment Hash
      GET
    • Claim WireGuard Configuration After Payment Settlement
      POST
    • Autonomous Agent HTTP 402 Gateway (L402 Purchase + Claim)
      POST
  • 🔄 Lifecycle
    • Get Subscription & Bandwidth Status by WireGuard Public Key
      POST
    • Sync Subscription (Real-Time Server Refresh)
      POST
    • Renew an Existing VPN Subscription (Anonymous)
      POST
    • Request Bandwidth Top-Up ($1 Usage Reset)
      POST
  • 🔑 Account
    • List Account Subscriptions (Authenticated)
      GET
    • Create Referral Code
      POST
    • Get Referral Code
      GET
    • Referral History
      GET
  • 🔧 Tools
    • Lightning Node Network Address Discovery
      POST
    • Universal Connectivity & Latency Probe
      POST
  • Cookbook
    • 🛠️ Automation & Code Examples
    • 🐚 Bash One-Liners
    • 🚑 Node Health & Upkeep
    • ⚡ Bandwidth Top-Up ($1 Usage Reset)
    • 🛡️ Security & Authentication
    • 🎁 Referral Program: Earn Bonus Months
    • 🛑 Error Codes & Troubleshooting
    • 🤖 Agent Payments: L402 & x402 Protocol
  • Schemas
    • Server
    • InvoiceOrder
    • SubscriptionStatus
    • NodeLookup
    • ConnectivityResult
    • ApiError
    • ClaimResult
    • BandwidthResetResponse
    • PublicKeyStatusResponse
    • SubscriptionListItem
    • ReferralCode
    • ReferralHistory
    • BandwidthResetPaymentStatus
    • RenewalOrder
    • SyncResult
Tunnelsats Github
Tunnelsats Telegram
  1. Announcements

🤖 Autonomous Agent Payments (L402 & x402) & Level 5 Agent-Native Architecture

We are excited to announce that TunnelSats is now a Level 5 ("Agent-Native") web and API platform on Cloudflare's isitagentready.com readiness benchmark, launching our unified HTTP 402 Payment Required Agent Payment Gateway (/api/v1) over the Bitcoin Lightning Network.
Autonomous AI agents, MCP tools, and sovereign node scripts can now discover, price, pay for, and provision dedicated port-forwarded WireGuard VPN tunnels in a single HTTP 402 challenge-response cycle - with zero accounts, zero KYC, and zero server-side private key custody.

🏆 Level 5 ("Agent-Native") Discovery Stack#

TunnelSats now passes 100% of core agent-readiness checks (8/8) across discovery, content negotiation, and machine-readable authentication:
CapabilityEndpoint / HeaderStandard
API Cataloghttps://tunnelsats.com/.well-known/api-catalogRFC 9727 (application/linkset+json)
Link Discovery HeadersLink: </.well-known/api-catalog>; rel="api-catalog", </openapi.json>; rel="service-desc"...RFC 8288
Markdown Content NegotiationAccept: text/markdown -> Content-Type: text/markdown; charset=utf-8 + x-markdown-tokensRFC 9110 (Vary: Accept)
Content Signals & AI RulesContent-Signal: ai-train=no, search=yes, ai-input=yes + robots.txtAI Input & Search Policy
OpenAPI + L402 Discoveryhttps://tunnelsats.com/openapi.jsonOpenAPI 3.0.3 + x-service-info & x-l402-payment-info
Agent Auth Guidehttps://tunnelsats.com/auth.mdMachine-readable Auth (Bearer, NIP-98 Nostr, L402/x402)
LLM Documentation Indexhttps://tunnelsats.com/llms.txt & https://api.tunnelsats.com/llms.txtllms.txt Specification

⚡ Introducing the Unified HTTP 402 Agent Gateway (/api/v1)#

Alongside our existing multi-step Public API (/api/public/v1/subscription/create -> /claim) used by StartOS, Umbrel, and custom node dashboards, we have launched a unified HTTP 402 Payment Required gateway at https://tunnelsats.com/api/v1:

1. Safe Read-Only Discovery (GET /api/v1)#

Calling GET https://tunnelsats.com/api/v1 returns 200 OK with machine-readable discovery metadata and step-by-step instructions. Passive agent probes never trigger unpaid invoice spam or receive placeholder BOLT11 strings.

2. Interoperable Binary V2 L402 Challenge (POST /api/v1 -> HTTP 402)#

When an agent sends POST https://tunnelsats.com/api/v1 with { "serverId": "eu-de", "duration": 1, "wgPublicKey": "<44-char-base64>" } and no Authorization header, TunnelSats:
1.
Generates a live mainnet (lnbc) BOLT11 invoice via LNbits and cryptographically validates its secp256k1 recoverable signature, paymentHash, amountSats, and active expiry (expiresAt > now).
2.
Mints an interoperable binary format V2 macaroon (libmacaroons / gopkg.in/macaroon.v2 wire format) with the 66-byte L402 identifier (uint16be(0) || paymentHash[32] || tokenId[32]), signed by a unique encrypted per-order 32-byte root key (HKDF-SHA256 + AES-256-GCM).
3.
Embeds first-party caveats binding the exact order parameters (order_id, server_id, duration, amount_sats, tunnelsats_valid_until, and wg_public_key) and supports client-side first-party caveat attenuation (SatisfyPrevious subset narrowing on tunnelsats_valid_until, services, tunnelsats_capabilities, and tunnelsats_action).
4.
Returns HTTP 402 Payment Required with:
WWW-Authenticate: L402 macaroon="<base64_v2_macaroon>", invoice="lnbc..."
PAYMENT-REQUIRED: <base64_json> - an experimental x402 v2 discovery adapter envelope (x402Version: 2, scheme: "l402", CAIP-2 Bitcoin mainnet network: "bip122:000000000019d6689c085ae165831e93", asset: "SAT", extra.adapterRole: "discovery").

3. Preimage Redemption (Authorization: L402 <macaroon>:<preimage> -> HTTP 200)#

Once the agent pays the BOLT11 invoice over Lightning, the Lightning Network reveals the 32-byte preimage (SHA256(preimage) == paymentHash). The agent replays POST https://tunnelsats.com/api/v1 with:
TunnelSats verifies the V2 macaroon signature and caveats in constant time, verifies SHA256(preimage) === paymentHash, confirms invoice settlement, provisions the WireGuard peer on the target VPN server, and returns 200 OK with the tunnel configuration (server, peer, vpnPort, subscriptionEnd).
24-Hour Grace Window & Permanent Paid-Order Recovery
The live BOLT11 quote expires in ~1 hour (maxTimeoutSeconds), while the L402 macaroon's tunnelsats_valid_until caveat grants an additional 24-hour redemption grace window (invoiceExpiresAt + 86400). Even after 24 hours, any settled invoice remains permanently claimable via Claim WireGuard Configuration After Payment Settlement (POST /api/public/v1/subscription/claim with { "paymentHash": "<64-char-hex>", "wgPublicKey": "<base64_pubkey>" }).

🔐 Zero-Custody Client-Held WireGuard Keys#

Just like our StartOS and Umbrel integrations, the HTTP 402 gateway is built around client-held WireGuard keys:
1.
Your agent generates its X25519 keypair locally (wg genkey / wg pubkey).
2.
Only wgPublicKey is sent in POST /api/v1 and bound into the L402 macaroon (wg_public_key=<base64_pubkey>).
3.
TunnelSats provisions the peer using your public key and returns server + peer + vpnPort parameters (config: null). Your private key never touches our servers or network logs.

📚 Next Steps & Code Examples#

Ready to wire up an autonomous Lightning agent or MCP tool?
Read the new 🤖 Agent Payments: L402 & x402 Protocol Cookbook for complete copy-paste Python, Node.js / TypeScript, and Bash (curl + lncli) implementations.
Explore the API reference for L402 Agent Payment Gateway Discovery Metadata (GET /api/v1) and Autonomous Agent HTTP 402 Gateway (POST /api/v1).
Review 🛡️ Security & Authentication for a side-by-side comparison of API Keys (Bearer), Nostr Auth (NIP-98), and Agent Payments (L402 / x402).
Modified at 2026-10-16 19:46:21
Previous
How TunnelSats Leverages Public APIs for Confined VPN Management
Next
List Available WireGuard Servers & Regions
Built with