How to structure an HTTP API that accepts Lightning micropayments via L402, including token design, rate limiting, and real-world tradeoffs.
L402 API Design Patterns: Selling Services for Sats
What L402 Is
L402 is an authentication scheme built on HTTP 402 ("Payment Required") and Lightning Network invoices.
Flow:
- Client requests a protected resource
- Server returns 402 + a Macaroon + BOLT11 invoice
- Client pays the invoice
- Client presents the paid Macaroon as a Bearer token
- Server validates Macaroon + payment preimage → grants access
No accounts. No API keys. No subscription billing. Just HTTP with money.
Pricing Tiers
| Tier | Price | Access | |------|-------|--------| | Demo | 0 sats | Single call, limited output | | Basic | 1000 sats | 10 calls, standard models | | Pro | 5000 sats | 100 calls, all models |
The demo tier reduces friction to zero. Most users who try the demo buy the paid tier.
Rate Limiting Without Accounts
Each paid Macaroon encodes a call budget. The server decrements a counter per call. No state needed beyond a nonce check to prevent replay.
Lightning Backend Options
- LND — most mature, REST/gRPC API
- Core Lightning — lighter, plugin ecosystem
- NWC — Nostr Wallet Connect, delegate to a managed wallet
NWC via Alby is the simplest starting point: just call makeInvoice() and lookupInvoice().
Why This Pattern Works
Traditional API monetization: sign up, add credit card, wait for approval, get a key, integrate the SDK.
L402: try it → pay 1000 sats → use it immediately. The barrier is low enough that curious developers actually convert.