L402
TestnetL402 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 tracks L402 as a detection adapter; native Lightning settlement is in development and not currently available.
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's native L402 support is in development and not currently available. The Smart Proxy has an L402 detection adapter that verifies the HMAC-SHA256 macaroon signature chain, checks caveats (tool slug, expiry, amount), validates the preimage format, and records the invocation. In production, real Lightning invoices require a configured LND node (LND_REST_URL); without one, only mock invoices are generated 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 | Testnet |
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