Accept Lightning payments in front of any HTTP API.

How it works, in three requests.

L402 pairs two things: a macaroon (the access token) and a Lightning preimage (proof of payment), tied together by sha256(preimage) == paymentHash. The client — a human, a script, an AI agent — hits the endpoint, pays the returned invoice on Lightning, and retries with the macaroon and preimage. No accounts, no API keys, no chain confirmations.

# Hit the protected endpoint with no auth.
$ curl -i https://api.example.com/v1/chat

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 macaroon="AGIAJEemVQUTEyNCR0exk7ek...",
                  invoice="lnbc100n1p3xnhl2pp5..."

# The whole challenge lives in the WWW-Authenticate header:
# a macaroon (access token) + a BOLT-11 invoice to pay.

# Agent pays the invoice with any Lightning wallet.
# lncli (LND) shown here — Phoenix, Alby, NWC all work.
$ lncli payinvoice \
  --pay_req=lnbc100n1p3xnhl2pp5...

Payment hash: 9c3a2b1f8e7d6c5b4a39281706f5e4d3...
Payment preimage: 7a3c91b4e2d058...
Status: SUCCEEDED  ·  Fee: 0 sat  ·  Hops: 3

# sha256(preimage) == paymentHash → proof of payment.
# Verified locally at the edge — no callback to any third party.

# Repeat the request with macaroon + preimage.
$ curl -H "Authorization: L402 \
    $MACAROON:$PREIMAGE" \
  https://api.example.com/v1/chat

HTTP/1.1 200 OK
Content-Type: application/json

{
  "reply": "hello, agent.",
  "model": "gpt-4o-mini",
  "tokens": 42
}

Prefer privacy? Skip the invoice — pay with Cashu.

L402 is interactive: challenge, pay, retry. Cashu is bearer money — the client attaches an ecash token to the request itself and gets the resource in a single round trip. Tokens are blind-signed by the mint, so it can't link the token you spend to the wallet that bought it.

# No invoice round-trip. Attach a bearer token via X-Cashu.
$ curl -H "X-Cashu: cashuApGFtdWh0dHBzOi8vbWlu..." \
  https://api.example.com/v1/chat

HTTP/1.1 200 OK
Content-Type: application/json

# The gateway verified the token — offline in P2PK mode (NUT-12 DLEQ),
# or via a mint swap in standard mode — and proxied upstream.

// enable: CASHU_ECASH_SUPPORT=true · whitelist mints in production · P2PK mode for high traffic · back up the wallet's BIP39 phrase (NUT-13)

Three reasons it lives at the edge.

Also in the box

Self-describing APIs for autonomous agents.

ngx-l402 publishes a /.well-known/l402-services manifest — the agent-era equivalent of robots.txt. A client given only a hostname can discover which routes are paid, what they cost, and which payment backends are accepted, then pay and proceed — no API keys, no out-of-band integration, no human in the loop.

{
  "version": "1",
  "service": { "name": "Example API", "description": "Stock data, paid per request." },
  "payment_methods": [
    { "type": "lightning", "backend": "LNURL", "address": "api@getalby.com" },
    { "type": "cashu", "mints": ["https://mint.minibits.cash"], "p2pk_supported": true }
  ],
  "routes": [
    { "path": "/v1/chat", "price": { "type": "static", "amount_msat": 10000 } }
  ]
}

Run the gateway in 60 seconds.

Pre-built container, one docker command. The simplest setup needs no node: receive at an LNURL address, or into your own wallet over NWC. Swap in LND, LNC, CLN, BOLT12, or Eclair by changing env vars.

$ docker run -d --name l402-nginx -p 8000:8000 \
  -e LN_CLIENT_TYPE=LNURL \
  -e LNURL_ADDRESS=you@your-lnurl-server.com \
  -e ROOT_KEY=$(openssl rand -hex 32) \
  ghcr.io/ngx-l402/ngx-l402:latest

# Gateway listens on :8000.
# curl http://localhost:8000/             → 200 OK
# curl -i http://localhost:8000/protected → 402 Payment Required

1. 01

   Configure & run

   The image ships nginx, the module, and clients for all backends, with a default /protected route. Mount your own nginx.conf to define paid locations.

2. 02

   Hit the endpoint

   Any request to a protected route comes back as 402 Payment Required with a Lightning invoice in the WWW-Authenticate header.

3. 03

   Pay → preimage → 200

   Pay the invoice from any Lightning wallet. Retry with the preimage in the Authorization header — the gateway verifies locally and proxies through to your upstream.

How it compares.

L402 has a healthy ecosystem — but most tools live at a different layer: hosted platforms, or client libraries that pay endpoints. ngx-l402 is the self-hosted, non-custodial server side, as a module in the nginx you already run.

// Alby and l402-requests are L402 clients — they pay ngx-l402 endpoints, so they complement it rather than compete.
// snapshot as of September 2026 — these projects evolve. Spot something stale or unfair? open an issue.

Built to sit in front of money.

Questions.