L402 is an open protocol for paying for and authenticating access to APIs and
services over the internet using the Lightning Network. It brings to life the
long-dormant HTTP 402 Payment Required status code by combining cryptographic
authentication tokens with Lightning Network micropayments.
- A client requests a paid resource from a server.
- The server responds with
402 Payment Required, including an authentication token and a Lightning invoice in theWWW-Authenticateheader. - The client pays the invoice over Lightning, receiving a payment preimage as proof of payment.
- The client re-sends the request with the token and preimage in the
Authorizationheader. - The server verifies the credential and serves the resource.
The token cryptographically commits to the payment hash of the invoice, so the server can verify payment using only the token and preimage. No database lookups or session state required.
WWW-Authenticate: L402 version="0", token="<base64>", invoice="<bolt11>"
Authorization: L402 <base64(token)>:<hex(preimage)>
No accounts, no passwords. Users pay a Lightning invoice and receive a cryptographic credential. No email, no sign-up form, no personal data collected.
Pay-as-you-go. Instead of choosing between free tiers and monthly subscriptions, users pay for exactly what they use. A single API call can cost fractions of a cent.
Programmable credentials. When using macaroons as the token format (the recommended default), credentials support attenuation: a token holder can create a weaker version of their credential to share with others, restricting access to specific services, capabilities, or usage limits.
Stateless verification. Servers verify credentials using only the token and preimage, no centralized database needed. This makes L402 a natural fit for distributed systems and microservice architectures.
L402 is a natural fit for AI agents and autonomous software that need to discover, evaluate, and pay for services without human intervention. The credentials are machine-readable (structured HTTP headers), self-contained (no out-of-band registration or OAuth flows), and instantly obtainable (pay an invoice, get a credential, all in one HTTP round-trip). Agents can also delegate scoped sub-credentials to other agents via caveat attenuation.
In practice, an AI agent can autonomously discover an API, pay for access with Lightning, and immediately start making authenticated requests, all without a human in the loop. As agents increasingly transact with services (and each other) using real money, L402 provides the payment+authentication layer to make that work over open payment rails.
L402 is token-format agnostic: any token that commits to a payment hash works. Macaroons (HMAC-chain bearer credentials) are the recommended format because they support delegation and attenuation through caveats, stateless verification via HMAC chains, and service-level access control with tier encoding. See the Macaroon Minting & Verification chapter and the Macaroon Technical Specification for the full details.
This revision of the L402 specification aligns with bLIP-0026 and includes the following updates:
- Token generalization. The protocol is now token-format agnostic. The
WWW-Authenticateheader usestoken=instead of the formermacaroon=. Macaroons remain the recommended format. - Version system. A
version="0"parameter is now included in theWWW-Authenticatechallenge header, enabling future protocol evolution. - Backwards compatibility. Explicit rules for accepting both
L402/LSATscheme names andtoken=/macaroon=parameter names. - Security guidance. Expanded security considerations covering caveat-based token binding (IP, TLS fingerprint, origin domain).
- Agent specification. A new agent-spec.md provides the complete protocol in ~560 tokens (~420 words), designed for AI agent context windows.
- Introduction — Motivation and high-level overview
- Authentication Flow — Step-by-step walkthrough with diagrams
- Protocol Specification — HTTP and gRPC protocol details
- Macaroon Minting & Verification — Recommended token format overview
- Macaroon Technical Specification — Detailed create/verify/attenuate implementation guide
- Agent Specification — Complete protocol in ~560 tokens for AI agent integration