L402 Authentication

Lightning-native API authentication for Lightning Faucet endpoints

Overview

L402 (formerly LSAT) is an HTTP authentication protocol that uses Lightning Network payments as proof of access. Instead of API keys, you pay a small Lightning invoice and receive a macaroon token that grants access to the API.

How It Works

Request: Make an HTTP request to an L402-protected endpoint without credentials.
Challenge: The server responds with HTTP 402 Payment Required and a WWW-Authenticate header containing a macaroon and a Lightning invoice.
Pay: Pay the Lightning invoice using any Lightning wallet.
Retry: Repeat the request with an Authorization header containing the macaroon and payment preimage.
Access: The server validates the payment and returns the API response.

Authorization Header Format

Authorization: L402 <macaroon>:<preimage>

Where:

<macaroon> is the base64-encoded macaroon from the WWW-Authenticate header
<preimage> is the 64-character hex payment preimage obtained after paying the invoice

Important: The header prefix is L402 (not Bearer). The legacy prefix LSAT is also accepted.

402 Response Headers

When you hit a protected endpoint without valid credentials, the response includes:

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 macaroon="<base64>", invoice="<bolt11>"

Example Flow

1. Initial Request (no auth)

curl -X POST https://lightningfaucet.com/api/l402/fortune

2. Parse the 402 Response

# Response headers contain:
# WWW-Authenticate: L402 macaroon="eyJpZG...", invoice="lnbc..."
#
# Extract the macaroon and invoice values

3. Pay the Invoice

# Pay the bolt11 invoice with your Lightning wallet
# Save the payment preimage (64 hex chars)

4. Retry with L402 Auth

curl -X POST https://lightningfaucet.com/api/l402/fortune \
  -H "Authorization: L402 eyJpZG...:abc123def456..."

Available Endpoints

/api/l402/fortune - Random fortune (10-50 sats)
/api/l402/joke - Random joke (10-50 sats)
/api/l402/quote - Random quote (10-50 sats)
/api/l402/registry-submit - Submit an API to the registry (1,000 sats)

Common Issues

`invalid_auth_format`

The Authorization header must exactly match: L402 <macaroon>:<preimage>

One space between L402 and the macaroon
Macaroon must be valid base64 (characters: A-Za-z0-9+/=)
Colon separator between macaroon and preimage
Preimage must be exactly 64 hex characters (a-f0-9)
No URL-encoding of the base64 characters

`invalid_token`

The macaroon signature doesn't match or the payment hash doesn't correspond to the preimage. Ensure you're using the macaroon from the original 402 response paired with the preimage from that same payment.

Libraries & Tools

lightning-wallet-mcp - MCP server with built-in L402 support
l402 (Rust) - Rust L402 client library
Any HTTP client + Lightning wallet can implement L402 manually