Turning nginx into a payment gateway for AI agents

• What is L402?
• Why does this matter?
• How L402 works
• In practice, the handshake looks like this:
• Enter nginx l402: Bringing L402 to the Edge
• What that buys you:
• Closing the Loop: Web server as the billing system

Ever since AI agents took off, one problem keeps resurfacing: How does an agent pay for things on the web?

Not sign up. Not open a browser and type in a credit card. Not commit to a $20/month subscription it might use twice. Pay autonomously, per request, for exactly what it consumes.

The web actually reserved space for this decades ago. HTTP status code 402 Payment Required has sat dormant in the spec since the early days of the internet - reserved “for future use,” waiting for a digital cash system that never arrived.

That future is finally showing up. In 2025, the 402 status code went from a curiosity to an active battleground: Cloudflare started experimenting with pay-per-crawl for AI bots, Coinbase launched the x402 protocol for stablecoin payments over HTTP, and a growing ecosystem of agent frameworks began treating “402” as a first-class response instead of an error.

This post is about L402 - the Lightning-based flavor of that idea - and ngx_l402, an open-source nginx module that lets you put a machine-payable paywall in front of any API with a few lines of config.

§What is L402?

L402 is an open-source payment and authentication protocol that lets services monetize API endpoints in a way AI agents can actually participate in. It uses the 402 status code as its handshake and Bitcoin’s Lightning Network as its payment rail.

If you’ve heard of x402, the goal is similar - machine-native, pay-per-request HTTP payments - but the mechanics differ. x402 settles in stablecoins on-chain, L402 settles over Lightning, which means instant finality, fees measured in fractions of a cent, and no dependency on any specific blockchain’s gas market. L402 also bundles its own authentication layer (more on that below), so payment and access control travel together in a single token.

§Why does this matter?

The internet’s billing infrastructure was built for humans: credit cards, sign-up forms, monthly subscriptions. Every one of those steps is a wall for an autonomous agent.

L402 replaces that with a pay-as-you-go model designed for machine-to-machine commerce. A client pays for exactly what it uses, when it uses it, down to a fraction of a cent - no account, no card on file, no contract.

§How L402 works

Under the hood, L402 combines two technologies: the Lightning Network for payments and macaroons for access control.

Lightning is a Layer 2 protocol on top of Bitcoin. It enables instant, near-zero-fee transactions off-chain while anchoring final settlement in Bitcoin’s consensus.

Macaroons are the more interesting half. A traditional API key is a static string - the server has to look it up in a database on every request to figure out who you are and what you’re allowed to do.

A macaroon embeds its own permission rules (called caveats) directly inside the token, and any holder can restrict its scope further without ever talking to the server. Hold a root token? You can hand your sub-agent a copy capped at 100 requests and expiring in an hour, and the restriction is cryptographically enforced - no server round-trip, no database write. The server validates the whole permission chain locally with math.

§In practice, the handshake looks like this:

The payment flow looks remarkably similar to HTTP authentication. Instead of responding to a 401 Unauthorized challenge with credentials, clients respond to a 402 Payment Required challenge with proof of payment.

1. The challenge (HTTP 402). An unauthenticated client hits a protected endpoint. The server returns 402 Payment Required with two things in the headers: a Lightning invoice specifying the exact price in satoshis, and a macaroon whose validity is locked until that invoice is paid.
2. The payment. The client’s Lightning wallet decodes the invoice and pays it off-chain. On settlement, the client receives a preimage - a secret value whose hash matches the payment hash in the invoice. It’s a cryptographic receipt: possessing the ‘preimage’ is proof the payment happened, verifiable by anyone with the invoice.
3. Stateless verification. The client resends the original request with the macaroon and preimage in the ‘Authorization’ header. The server checks the receipt against the macaroon, enforces any embedded caveats, and forwards the request to the backend. No user database lookup, no billing ledger query - the verification is entirely local.

This makes macaroons particularly attractive for AI agents. A parent agent can safely delegate a more restrictive token to a sub-agent, for example limiting it to 100 requests, one API endpoint, or one hour of validity - without asking the server to create a new account or API key.

§Enter nginx l402: Bringing L402 to the Edge

ngx_l402 is an open-source nginx module that handles this entire lifecycle at the reverse-proxy layer. Instead of writing payment logic into your application, you offload the handshake to the web server itself. This is arguably the biggest architectural advantage of ngx_l402.

Existing applications don’t need to understand Lightning, invoices, or Bitcoin at all. They simply receive authenticated HTTP requests after nginx has already verified payment.

Payments become infrastructure rather than application logic.

§What that buys you:

Drop-in monetization. Wrap any backend API - legacy or modern - in a machine-payable paywall by adding directives to your nginx config.

Backend isolation. Your application servers never touch Lightning, nodes, invoices, or macaroons. They receive plain, pre-authenticated HTTP requests only after nginx has confirmed payment.

Rust under the hood. The module is written in Rust, so token validation runs with compile-time memory safety and enough throughput to sit in front of heavy agent traffic.

Bring your own node. Invoice generation and settlement checks work against LND, CLN, Eclair, LNURL, NWC, and BOLT12 backends.

Here’s what a pay-per-request paywall looks like in production:

location /v1/weather {
    # Turn on L402 authentication for this location
    l402_auth on;
    
    # Define the cost per API call in millisatoshis (1000 msat = 1 sat)
    l402_amount_msat 10000;
    
    # Proxy passing directly to your standard, unauthenticated backend
    proxy_pass http://weather_backend_service;
}

That’s the entire integration! The backend behind has no idea Bitcoin exists.

§Closing the Loop: Web server as the billing system

Remember the problem we started with - How does an AI agent pay for things on the web?

By moving ‘payments’ out of the application and into the infrastructure layer, the question stops being an architectural headache. You don’t rebuild your APIs, you don’t manage user databases, and your backend stays clean.

The web server itself becomes the billing system - and the dormant 402 spec finally does the job it was reserved for.

🚀 Ready to take L402 for a spin?

ngx_l402 is fully open-source and actively evolving. Hack on it, read the docs, or star the repo to follow along here:

https://gitworkshop.dev/@DhananjayPurohit/relay.ngit.dev/ngx-l402