Monetize an API with Lightning: L402 explained for API owners

L402 lets you charge for each API request with a Lightning payment, and it lets any client, including an AI agent, pay without an account or API key. An unpaid request gets 402 Payment Required with a Lightning invoice and a token. The client pays, gets a preimage as its receipt, and retries with the token and preimage. Your server checks one hash and serves the response. Lightning Labs describes L402 as "built with a focus on agentic commerce" (Lightning Labs).

This article is for API owners. It is part of How to sell your API to AI agents. If you'd rather see the buyer side, read Agentic payments explained.

Why charge per call at all?

API keys and monthly plans work for customers who sign up. Agents mostly don't. An agent that needs your endpoint once, in the middle of a task, can't fill in a signup form or wait for a human to approve a card. With L402, "credentials are purchased, not provisioned" (Lightning Labs, lightning-agent-tools). That turns every agent with a Lightning balance into a potential customer, which is what opening your API to the machine economy means in practice.

How L402 works, step by step

These steps follow the L402 protocol specification.

The client asks. GET /v1/forecast?lat=52.5&lon=13.4, no credentials.
You answer with a challenge. Status 402 Payment Required and a header:

`` WWW-Authenticate: L402 macaroon="<base64>", invoice="<bolt11>" ``

The macaroon is a token you mint. Its identifier commits to the payment hash of the Lightning invoice.

The client pays. It pays the BOLT11 invoice from any Lightning wallet and receives the preimage, the 32-byte secret whose SHA-256 is the payment hash. The spec says clients should check the invoice amount first and walk away if it is above their limit.
The client retries with proof.

`` Authorization: L402 <base64(macaroon)>:<hex(preimage)> ``

You verify and serve. Check the macaroon's HMAC chain against your root key, then check sha256(preimage) == payment hash. If both pass, serve the request. If not, return 401. The spec calls the hash check the recommended approach because it is stateless: no database lookup and no call to your Lightning node on the hot path.

What macaroons add

A macaroon is a bearer token that can carry caveats: restrictions such as an expiry, a service name, or a capability. Each caveat can only narrow what the token allows, never widen it (L402 spec). That makes the token a meter as well as a receipt. You decide whether one paid token buys one call or several.

Compatibility notes

LSAT. L402 used to be called LSAT. The spec says servers should send both scheme names in the challenge, and clients and servers must accept both in Authorization.
gRPC. gRPC responses always carry HTTP 200, so the L402 gRPC flow puts the challenge in trailing metadata instead of a 402 status.

Three ways to add L402 to your API

Option	What it is	Good when
Amazap seller starter kit	L402 seller code in Node and Python at /sell/starter	You want code you can read and change, wired for the Amazap /sell flow
Aperture	Lightning Labs' L402 reverse proxy for REST and gRPC backends. It sets prices per service and forwards paid requests (Aperture on GitHub)	You want to leave your app untouched and you run, or can connect to, an lnd node
Write it yourself	Mint invoices, mint macaroons, verify preimages	You have unusual pricing or an existing auth stack

Aperture needs an lnd node: either a direct connection to lnd's RPC or a Lightning Node Connect pairing phrase, per its sample config (sample-conf.yaml).

Where Amboss Payments fits

An L402 server needs two Lightning jobs done: create an invoice with a known payment hash, and (optionally) learn when it is paid. Amboss Payments' create_receive mutation returns a BOLT11 payment_request and its payment_hash (Amboss: Receive Payments). Your code mints a macaroon that commits to that hash and sends both in the 402 challenge. When the client comes back with the preimage, the hash check proves payment; Amboss webhooks (payment.completed) are there for your bookkeeping.

Amboss's docs describe the payments API itself, not L402. A Lightning macaroon, as the spec describes it, is your code. The starter kit signs an HMAC token bound to the payment hash instead, and checks the preimage locally. Amboss does not issue that token. Setup steps: Set up Amboss Payments for an L402 API.

Set up Amboss Payments

Disclosure: Amazap is an Amboss referral partner. Amazap earns a referral credit if you sign up through this link.

Mistakes that cost sales

Validating before challenging. If an unpaid request with no inputs gets 400, a directory probe never sees your price. Issue the 402 first.
Invoices that expire too fast. Amboss invoices default to 10 minutes unless you set expires_in_seconds (Amboss). Make sure the window covers a slow agent.
Charging before you can deliver. If your upstream is down, fail before issuing the invoice when you can.
Unclear token rules. Say whether a paid token is good for one call or many, and for how long.
Price drift. If your costs are in dollars and your invoice is in sats, recheck the sats price regularly. More in How to price an API for AI agents.

Next: get found

An L402 endpoint nobody can find earns nothing. Amazap's /sell flow probes your endpoint, reads the price from your invoice, and prefills a listing that agents can find through the Amazap MCP server at amazap.com/mcp. Walkthrough: List your L402 endpoint on Amazap. Comparing protocols first? See L402 vs x402 vs API keys. Selling a model you host yourself? See Sell your self-hosted AI model.

List your endpoint on Amazap

FAQ

What is L402?

L402 is Lightning Labs' protocol for paid APIs. A server answers an unpaid request with HTTP 402, a Lightning invoice, and a macaroon. The client pays, then retries with the macaroon and the payment preimage in the Authorization header, and the server verifies the payment with a hash check.

Is L402 the same as LSAT?

Yes. L402 was formerly called LSAT. The spec asks servers to send both scheme names in challenges and requires clients and servers to accept both in the Authorization header.

Do buyers need an account with my API?

No. Anyone who can pay a Lightning invoice can buy a call. The paid macaroon plus preimage is the credential.

How does my server know the invoice was paid?

The macaroon commits to the invoice's payment hash. If sha256 of the preimage the client sends equals that hash, the invoice was paid. This needs no database lookup, which the L402 spec recommends.

Do I need Aperture?

No. Aperture is one option: a reverse proxy from Lightning Labs that needs an lnd node. You can also use the Amazap seller starter kit in Node or Python, or write the L402 handling yourself.

Can L402 work with gRPC?

Yes. Because gRPC responses always return HTTP 200, the L402 gRPC flow sends the challenge in trailing metadata instead of a 402 status. Aperture supports both REST and gRPC backends.