How L402 Turns Any HTTP Request Into a Payment

How L402 Turns Any HTTP Request Into a Payment

One status code. One round trip. Zero intermediaries.

There is a status code in the HTTP specification that has existed since 1998 and has almost never been used.

HTTP 402: Payment Required.

The original RFC describes it as "reserved for future use." For twenty-five years, it sat in the specification like a placeholder — a number with no implementation, no standard behavior, no ecosystem around it.

In 2020, Lightning Labs published the L402 protocol. For the first time, HTTP 402 had a real implementation. And what that implementation enabled changes the architecture of how machines pay for things.

The Problem L402 Solves

Before L402, adding payment to an API required one of two approaches.

The first approach: out-of-band payment. The developer subscribes to an API, pays a monthly fee via credit card, receives an API key, and includes that key in every request. The payment and the request are completely separate. The API key is a proxy for "this person has paid us recently." It works for humans on monthly billing cycles. It does not work for agents that need to pay per request, in real time, without a billing relationship.

The second approach: custom payment integration. The API provider builds a payment system into their infrastructure. The client integrates with that payment system before making requests. Every API has a different payment integration. Every client has to implement them all. The friction is enormous and the standardization is zero.

L402 solves both problems with a single elegant mechanism: it embeds payment into the HTTP request-response cycle itself, using a standard that any HTTP client can implement once and use everywhere.

How It Works — Step by Step

The L402 flow has four steps. It is worth understanding each one precisely.

Step 1: The initial request.

The agent sends a standard HTTP GET or POST request to an L402-enabled endpoint. No special headers. No prior payment. No subscription. Just a request.

GET /api/btc-price HTTP/1.1

Host: api.example.com

Step 2: The 402 response.

The server responds with HTTP 402 Payment Required. The response includes two things in the headers: a Lightning invoice and a macaroon.

HTTP/1.1 402 Payment Required

WWW-Authenticate: L402 token="...", invoice="lnbc210n1..."

Step 3: The payment.

The agent pays the Lightning invoice. This happens on the Lightning Network — peer to peer, in milliseconds, with no intermediary. The payment produces a preimage: a cryptographic secret that proves the invoice was paid. The agent combines the macaroon with the preimage to create the L402 token.

Step 4: The authenticated request.

The agent resends the original request with the L402 token in the Authorization header.

GET /api/btc-price HTTP/1.1

Host: api.example.com

Authorization: L402 <token>:<preimage>

The server verifies the token. The preimage proves the invoice was paid. The server returns the requested data.

Total elapsed time from Step 1 to Step 4: approximately 400 to 800 milliseconds. Payment confirmed. Data delivered. No human involved at any point.

Why This Architecture Is Correct

The elegance of L402 is not just that it works — it is that it works without introducing any new trust relationships.

In the standard API key model, the client trusts the server to honor the API key, and the server trusts the client to have actually paid for it. Both sides are trusting each other's record-keeping. If the server loses the database of valid API keys, or if the client's key is stolen, the trust breaks.

In the L402 model, neither side needs to trust the other's record-keeping. The proof of payment is cryptographic — it is derived from the Lightning Network's own settlement mechanism and cannot be forged. The server verifies the preimage against the invoice hash. The math either works or it doesn't.

This means L402 is stateless from the server's perspective. No database of subscribers. No account management. No billing system. Just an endpoint, a price, and a Lightning node to receive payment.

For API providers, this dramatically reduces infrastructure complexity. For agents, it dramatically reduces onboarding friction. There is no account to create, no API key to request, no subscription to manage. The agent pays and receives. That's the entire relationship.

The Macaroon — More Than a Receipt

The macaroon in L402 is worth understanding in more depth, because it enables something beyond simple proof of payment.

A macaroon is a cryptographic token with a specific property: it can be attenuated. The original macaroon issued by the server can be restricted — by the holder — to limit its scope in ways the server has pre-approved.

In the context of L402, this means a server can issue a macaroon that is valid for a specific endpoint, for a specific time window, for a specific number of uses. The client cannot expand the scope of the macaroon — only restrict it further.

This enables capability-based access control at the API level. A server might issue a macaroon valid for 100 requests to the price endpoint over 24 hours. The agent pays once, receives the macaroon, and can make up to 100 requests within the time window. Each request is authenticated by the macaroon without requiring a new Lightning payment.

For high-frequency agent workflows — where an agent queries the same endpoint thousands of times per hour — this batching capability is essential. The payment overhead is amortized across multiple requests, making the economics work even for very high-frequency, very low-value data feeds.

Implementing L402 in Agntik

In the Agntik SDK, L402 is fully abstracted. The developer does not need to implement the four-step flow manually. The pay() method handles everything.

const result = await agent.pay({

service: 'btc-price-realtime',

maxSats: 50

});

Under the hood, the SDK queries the Registry for the endpoint, sends the initial request, receives the 402 response, pays the invoice, constructs the L402 token, resends the request, and returns the response data to the caller.

From the developer's perspective, this is a single async function call that returns data. The payment is invisible — not because it doesn't happen, but because the infrastructure handles it correctly so the developer never has to think about it.

This is what we mean by zero friction in payment. L402 is not a workaround or a hack. It is the correct architecture for machine payments, and the Agntik SDK implements it so completely that its complexity becomes invisible.

Building an L402-Compatible Service

The other side of the equation is equally important: any developer can expose their API through L402 and immediately make it accessible to every agent using the Agntik Registry.

The registration is three lines of SDK:

await agent.register({

name: 'my-data-api',

description: 'Real-time financial data aggregator',

category: 'datos-financieros',

priceSats: 21,

endpoint: 'https://api.myservice.com/data'

});

Once registered, the service appears in the Registry. Any agent querying for services in the category will find it, ranked by score and price. The developer's API is now monetizable — by any agent, anywhere, without any bilateral relationship, without any subscription management, without any invoice generation.

The first time an agent pays for the service, the Registry score starts building. Every subsequent payment increments the score. Over time, the score becomes a permanent, verifiable asset that reflects the actual quality of the service as experienced by real economic actors.

What L402 Makes Possible

The implications of L402 extend beyond any single use case.

Any API endpoint can become a micropayment-enabled service in minutes. This means the long tail of specialized data, computation, and intelligence that has never been economically viable to monetize through subscription pricing — because the market is too small, the usage too infrequent, the billing overhead too high — can now charge per-request at prices that match the value delivered.

A highly specialized academic dataset that ten agents might query per day, at 500 sats per query, is now a viable business. Without L402, it would require a subscription product, a payment processor, an invoicing system, and a customer service function. With L402, it requires a Lightning node and an endpoint.

This is the long tail of the agent economy — thousands of specialized services that will never be large enough for traditional software pricing but are enormously valuable to the agents that need them. L402 is the mechanism that makes that long tail economically viable.

And the Agntik Registry is where those services get discovered.

Next: Build your first autonomous agent with Agntik in 10 minutes →