L402

Testnet

L402 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:

l402-example.tstypescript

// 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