Working code examples for consuming L402 APIs using the Lightning Network.
These examples use the public L402 endpoints at Lightning Faucet as the demo server.
L402 is an API monetization protocol that combines HTTP 402 (Payment Required) status codes with Lightning Network micropayments. It allows API providers to charge per-request using instant Bitcoin payments.
The protocol works like this:
- Request -- The client makes a request to a protected API endpoint.
- 402 Response -- The server returns HTTP 402 with a
WWW-Authenticateheader containing a macaroon (credential) and a Lightning invoice (payment request). - Pay -- The client pays the Lightning invoice using any Lightning wallet. Payment returns a preimage (proof of payment).
- Retry with proof -- The client retries the original request with an
Authorization: L402 <macaroon>:<preimage>header. - Access granted -- The server validates the macaroon and preimage, then returns the requested resource.
Client Server
| |
| GET /api/l402/joke |
| ---------------------------------> |
| |
| 402 Payment Required |
| WWW-Authenticate: L402 |
| macaroon="<base64>" |
| invoice="<bolt11>" |
| <--------------------------------- |
| |
| [Pay invoice via Lightning] |
| [Receive preimage] |
| |
| GET /api/l402/joke |
| Authorization: L402 |
| <macaroon>:<preimage> |
| ---------------------------------> |
| |
| 200 OK |
| { "joke": "..." } |
| <--------------------------------- |
These public L402 endpoints are provided by Lightning Faucet for testing and development:
| Endpoint | Price | Description |
|---|---|---|
https://lightningfaucet.com/api/l402/joke |
50 sats | Returns a random joke |
https://lightningfaucet.com/api/l402/fortune |
50 sats | Returns a fortune |
https://lightningfaucet.com/api/l402/quote |
10 sats | Returns an inspirational quote |
Browse the full catalog at the L402 API Registry.
cd python
pip install -r requirements.txt
python l402_client.pySee python/l402_client.py for the full example.
Requires Node.js 18+ (uses built-in fetch).
cd node
npm install
node l402_client.jsSee node/l402_client.js for the full example.
The examples above demonstrate the full L402 handshake but use a placeholder for the Lightning payment step. To actually pay invoices programmatically, you need a Lightning wallet with an API. Common options:
- LND -- Use
lncli payinvoiceor the gRPC/REST API (docs) - CLN (Core Lightning) -- Use
lightning-cli payor the JSON-RPC API - LDK -- Embed a Lightning node in your application (docs)
- Alby -- Browser extension and API for Lightning payments (getalby.com)
- Lightning Wallet MCP Server -- An AI-agent-friendly wallet for automated L402 payments:
See the lightning-wallet-mcp package for setup instructions.
npm install -g lightning-wallet-mcp
The macaroon in L402 is a bearer credential that encodes:
- Identifier -- A unique token ID
- Location -- The issuing server (e.g.,
lightningfaucet.com) - Caveats -- Restrictions such as:
payment_hash-- Links the macaroon to a specific Lightning invoiceexpiry-- When the credential expiresservice-- Which API service the macaroon grants access tocapabilities-- What operations are allowed
- Signature -- HMAC proof that the server issued this macaroon
The preimage (obtained by paying the invoice) serves as proof of payment. The server verifies that the preimage hashes to the payment_hash caveat in the macaroon, confirming the client paid.
- L402 Protocol Specification
- Lightning Faucet L402 Registry -- Browse available L402 APIs
- lightning-wallet-mcp -- MCP server for AI agents to make Lightning payments
- Lightning Faucet -- Bitcoin Lightning faucet, games, and L402 APIs
MIT