L402
ReadyL402 Lightning Payments — Lightning Labs (Bitcoin)
Overview
L402 (formerly LSAT) is Lightning Labs' protocol for native Bitcoin Lightning payments over HTTP. It uses the HTTP 402 status code with Lightning invoices and cryptographic macaroons to enable fully pseudonymous, per-request payments. No API keys, no signup, no KYC — just pay-per-use via the Lightning Network. SettleGrid is the first multi-protocol billing platform with deep L402 support, allowing any AI tool to accept Bitcoin alongside fiat and stablecoin payments.
How It Works
The L402 flow begins when an agent calls a paid endpoint without credentials. The server returns HTTP 402 with a WWW-Authenticate header containing two components: a macaroon (a cryptographic bearer token with embedded caveats like expiry time, tool slug, and amount) and a Lightning invoice (a BOLT-11 payment request for the exact amount in satoshis).
The agent pays the Lightning invoice through the Bitcoin Lightning Network, which settles in seconds. Payment produces a preimage — the cryptographic proof of payment. The agent then re-sends the original request with an Authorization: L402 <macaroon>:<preimage> header.
The server verifies the macaroon's HMAC signature chain, checks that caveats are satisfied (correct tool, not expired, correct amount), and validates the preimage against the payment hash. If all checks pass, the request is processed.
Macaroons support delegation — an agent can add additional caveats (further restrictions) before passing the macaroon to a sub-agent, enabling hierarchical payment authorization without server interaction.
How SettleGrid Integrates
SettleGrid has a deep L402 integration with full macaroon minting and verification. Every tool on the platform can accept Lightning payments via the Smart Proxy. When an agent presents L402 credentials, SettleGrid verifies the HMAC-SHA256 macaroon signature chain, checks caveats (tool slug, expiry, amount), validates the preimage format, and records the invocation. If LND_REST_URL is configured, real Lightning invoices are generated via the LND REST API; otherwise, mock invoices are used for development.
Key Specs
| Protocol | L402 — L402 Lightning Payments |
| Backer | Lightning Labs (Bitcoin) |
| Detection Header | Authorization: L402 <macaroon>:<preimage> / Authorization: LSAT <macaroon>:<preimage> |
| Identity Type | pseudonymous (macaroon) |
| Payment Type | bitcoin-lightning |
| Status | Ready |
Code Example
Here is how a developer's tool works with L402 via SettleGrid:
// Agent paying for a SettleGrid tool via L402 (Bitcoin Lightning)
// Step 1: Call the endpoint — get a 402 with Lightning invoice
const initial = await fetch('https://settlegrid.ai/api/proxy/data-enrichment', {
method: 'POST',
headers: { 'x-settlegrid-protocol': 'l402' },
body: JSON.stringify({ domain: 'example.com' }),
})
// Returns 402 with WWW-Authenticate: L402 macaroon="...", invoice="lnbc..."
const { macaroon, invoice } = await initial.json()
// Step 2: Pay the Lightning invoice (via your LN wallet/node)
const preimage = await payLightningInvoice(invoice)
// Step 3: Re-send with L402 credentials
const result = await fetch('https://settlegrid.ai/api/proxy/data-enrichment', {
method: 'POST',
headers: {
'Authorization': `L402 ${macaroon}:${preimage}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ domain: 'example.com' }),
})Start monetizing with SettleGrid
Free forever — 50,000 ops/month, progressive take rate. Add billing to your L402 tool in under 5 minutes.
Get Started Free