# 📢 Public

> Public endpoints that don’t require authentication.  
Use these to discover available servers and basic status info.  
Start here to get your **first 200 OK**.


![postman_ts_banner.jpeg](https://api.eu.apidog.com/api/v1/projects/361232/resources/339387/image-preview)
# TunnelSats API

Programmatic access to TunnelSats VPN subscriptions.

## ⚡ Quick Start

1. **List Servers**: `GET /servers` - See available locations.
    
2. **Create Subscription**: `POST /create` - Get a Lightning invoice.
    
3. **Pay**: Pay the invoice with any Lightning wallet.
    
4. **Claim**: `POST /claim` - Receive your WireGuard config.
    

## 💰 Pricing

| Duration | Price | Discount |
| --- | --- | --- |
| 1 month | $3.00 | \- |
| 3 months | $8.55 | 5% |
| 6 months | $16.20 | 10% |
| 12 months | $28.80 | **20%** |

_Prices converted to Sats at current BTC/USD rate._

## 🆔 Server IDs

| ID | Location |
| --- | --- |
| `us-east` | Ashburn, USA |
| `us-west` | Hillsboro, USA |
| `eu-de` | Nuremberg, DE |
| `asia-sg` | Singapore |
| `sa-br` | Sao Paulo, BR |

## 🎁 Referral Program

Include `referralCode` in `/create` for bonus months:

- 3mo plan → +1 month free
    
- 6mo plan → +2 months free
    
- 12mo plan → +3 months free
    

## 🔐 Authentication

**Most endpoints are public** - no auth needed to buy!

**For account endpoints** (`List My Subs`, `Sync`):

| Method | Header | How to Get |
| --- | --- | --- |
| **API Key** (recommended) | `Authorization: {{vault:bearer-token}}` | Dashboard → Settings → API Keys |
| **NIP-98** (advanced) | `Authorization: Nostr` | Requires Nostr signing (e.g. Alby extension) |

## ❓ FAQ

**Q: Do I need an API Key to buy a subscription?**  
A: No! The purchase flow is completely public. Keys are only for managing your account.

**Q: Where do I get an API Key?**  
A: Log in at tunnelsats.com → Dashboard → Settings → Generate API Key.

**Q: What's the difference between API Key and NIP-98?**  
A: API Keys are simple Bearer tokens. NIP-98 uses Nostr-signed events - useful for Nostr-native apps but requires cryptographic signing.

**Q: Can I use my own WireGuard keys?**  
A: Yes! Pass `wgPublicKey` in `/claim` to bring your own keys. Otherwise we generate them for you.

## ⏱️ Rate Limits

- Reads: 60/min
    
- Creates: 10/min
    
- Claims: 10/min
    

## 🖥️ Base URL

`https://tunnelsats.com`

Public endpoints that don’t require authentication.  
Use these to discover available servers and basic status info.  
Start here to get your **first 200 OK**.