L402: Lightning HTTP 402 Protocol

L402 is an open protocol for paying for and authenticating access to APIs and services over the internet using the Lightning Network. Developed by Lightning Labs, it brings to life the long-dormant HTTP 402 Payment Required status code by combining macaroons (cryptographic bearer credentials) with Lightning Network micropayments.

How It Works

1. A client requests a paid resource from a server.
2. The server responds with 402 Payment Required, including an authentication macaroon and a Lightning invoice in the WWW-Authenticate header.
3. The client pays the invoice over Lightning, receiving a payment preimage as proof of payment.
4. The client re-sends the request with the macaroon and preimage in the Authorization header.
5. The server verifies the credential and serves the resource.

The macaroon cryptographically commits to the payment hash of the invoice, so the server can verify payment using only the macaroon and preimage. No database lookups or session state required.

WWW-Authenticate: L402 macaroon="<base64>", invoice="<bolt11>"
Authorization:    L402 <base64(macaroon)>:<hex(preimage)>

Why L402?

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. Macaroons support attenuation: a credential 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 macaroon and preimage, no centralized database needed. This makes L402 a natural fit for distributed systems and microservice architectures.

Agents and Agentic Commerce

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.

Specification

• Protocol Specification: HTTP and gRPC protocol details, formal definitions
• Macaroon Technical Specification: Detailed create/verify/attenuate implementation guide
• Agent Specification: Complete protocol in ~560 tokens for AI agent integration

Documentation

• Introduction: Motivation, lineage, and high-level overview
• Authentication Flow: Step-by-step walkthrough with diagrams
• Macaroon Minting & Verification: Macaroon format overview and caveat system

Implementations

• Aperture: gRPC/HTTP authentication reverse proxy using L402
• lsat-js: JavaScript utility library for working with L402 credentials
• boltwall: Node.js middleware-based authentication using L402

External Links

• Builder's Guide Documentation
• Macaroons: Cookies with Contextual Caveats (Google Research)
• HTTP/1.1 RFC, Section 6.5.2: 402 Payment Required