L402 (Lightning HTTP 402) is an open protocol for paying for a web resource with Bitcoin over the Lightning Network. It is built on the HTTP status code 402 Payment Required and on small signed tokens called macaroons. A server answers an unpaid request with a 402 and a Lightning invoice; the client pays the invoice, then retries the request carrying the token and the payment proof. It lets a program, including an autonomous agent, pay per request without an account or a card.
At a glance
What it is
An open protocol for paying per web request with Bitcoin over Lightning
What it is built on
The HTTP 402 Payment Required status and signed tokens called macaroons
Why it matters
A program can pay for a request with no account and no card
Who it suits
Autonomous agents that need to transact without a human in the loop
Flow
How an L402 payment completes
An unpaid request is met with a 402 and an invoice. The client pays it over Lightning, then retries the same request carrying the token and the payment proof. Green is the paid retry that finally returns the resource.
1
Client requests a gated resourceno token yet, so the server cannot serve it
2
Server answers 402 with an invoice and a tokenthe macaroon, a small signed token tied to the invoice
3
Client pays the Lightning invoiceoff-chain, instant, no account needed
4
Client retries with the token and payment proofthe server checks both and returns the resource
What problem does L402 solve?
Most paywalls assume a person: you sign up, hand over a card, and the charge is
tied to your identity. None of that fits a program that needs to fetch one
resource and move on. L402 (Lightning HTTP 402) takes a different route. It reuses
an HTTP status code that has been reserved for exactly this since the early web,
the 402 Payment Required, and pairs it with a payment that settles over the
Lightning Network in moments. There is no account to create and no card to store.
The unit of payment is a single request.
The flow is short. A client asks for a gated resource. The server answers 402 and
hands back two things: a Lightning invoice, and a macaroon, which is a small
signed token that encodes what the payment is for. The client pays the invoice,
then sends the same request again, this time carrying the macaroon and a proof
that the invoice was paid. The server checks both and returns the resource. The
macaroon can be reused for further requests until its terms run out, so you do not
pay twice for the same grant.
Why does it matter for an agent?
Because it removes the human from the payment. An autonomous agent that holds its
own Lightning balance can meet a 402, read the invoice, pay it, and retry, all
without a person approving a charge or a card sitting behind it. The cost is
metered to the actual request rather than to a monthly plan nobody remembers
signing up for.
That is the part worth sitting with. A protocol built on a status code and a
signed token, with no central gateway, lets software pay software directly. It is
small, open, and it does not need to know who you are. For an agent acting on its
own, that is the difference between asking permission and simply transacting.
Check it yourself
curl -i https://example.com/l402-gated
Against an L402-gated endpoint the first response is a 402 Payment Required, and the WWW-Authenticate header carries the macaroon and the Lightning invoice you would pay. Read that header rather than the body.
L402 is
An open protocol any server or client can implement
Built on a standard HTTP status code, the 402 Payment Required
Pay-per-request, with no account and no stored card
Workable for an autonomous agent with its own Lightning balance
L402 is not
A single company's API or a closed payment gateway
A subscription or a login you set up once and reuse
Tied to a card network or a bank that needs your identity
On-chain; the payment settles over Lightning, off the blockchain