🛡️ Security & Authentication

TunnelSats provides three primary ways to authenticate and pay for requests. Understanding which one to use depends on whether you are building a centralized backend service, a privacy-first Nostr integration, or an autonomous AI agent.

🔑 1. API Keys (Bearer Token)

API Keys are the simplest way to authenticate and are recommended for most backend integrators.

Format: sk_live_[random_string]

Header: Authorization: Bearer sk_live_...

Best Practices

Never expose your API key in client-side code (Frontend).

Store keys in environment variables (.env.local).

Rotate your keys immediately if you suspect a leak.

💜 2. Nostr Auth (NIP-98)

For users who want to stay anonymous or integrate directly with the Nostr ecosystem, we support NIP-98 (HTTP Authentication for Nostr).

How it works

Create a "Kind 27235" event.

Sign it with your Nostr Private Key (nsec).

Base64-encode the signed event JSON.

Pass it in the header as: Authorization: Nostr [base64_encoded_event]

Generation Script (Bash + nostr-tool)

⚡ 3. Agent Payments (L402 Runtime & Experimental x402 Discovery Adapter)

For autonomous AI agents and bots that pay per tunnel over the Bitcoin Lightning Network without pre-registered accounts:

Endpoint: Autonomous Agent HTTP 402 Gateway (POST https://tunnelsats.com/api/v1)

Challenge (HTTP 402): Returns WWW-Authenticate: L402 macaroon="...", invoice="lnbc..." (interoperable binary V2 L402 macaroon) and PAYMENT-REQUIRED (experimental x402 v2 discovery adapter envelope with scheme: "l402", network: "bip122:000000000019d6689c085ae165831e93", asset: "SAT", and extra.adapterRole: "discovery").

Credential Header: Authorization: L402 <macaroon>:<preimage> (where SHA256(preimage) == paymentHash), or X-PAYMENT / PAYMENT-SIGNATURE base64 JSON carrying { "macaroon": "...", "preimage": "..." }.

See 🤖 Agent Payments: L402 & x402 Protocol for full Python, Node.js, and Bash examples.

🔒 4. Rate Limiting Strategy

Our API uses a two-layer rate-limiting system to protect the network.

Layer 1: Cloudflare WAF (Burst Limiter)

A blanket rule across all /api/public/* paths:

Limit: 10 requests per 10 seconds per IP

Action: Block (with 10s mitigation timeout)

Purpose: Prevents rapid bursts and DDoS attacks

Layer 2: Application Rate Limits (Per-Endpoint)

Each endpoint has its own limit enforced at the application layer:

Endpoint	Limit	Per
`GET /api/v1`	60/min	IP
`POST /api/v1`	10/min	IP
`GET /servers`	60/min	IP
`POST /create`	10/min	IP
`POST /claim`	10/min	IP
`GET /{paymentHash}`	60/min	IP
`POST /status`	30/min	IP
`POST /renew`	20/min	IP
`POST /bandwidth-reset`	10/min	IP
`POST /{paymentHash}/sync`	5/min	Subscription
`GET /list`	30/min	Account
`POST /ping/lookup`	5/min	IP
`POST /ping/test`	3/min	IP

Handling 429 Responses

When you receive an ERR_RATE_LIMIT_EXCEEDED (429), your application MUST implement exponential backoff:

🔑 1. API Keys (Bearer Token)#

Best Practices#

💜 2. Nostr Auth (NIP-98)#

How it works#

Generation Script (Bash + nostr-tool)#

⚡ 3. Agent Payments (L402 Runtime & Experimental x402 Discovery Adapter)#

🔒 4. Rate Limiting Strategy#

Layer 1: Cloudflare WAF (Burst Limiter)#

Layer 2: Application Rate Limits (Per-Endpoint)#

Handling 429 Responses#