Lightning Network Payments

ngx_l402 implements the L402 protocol, enabling API monetization via Lightning Network payments. When a client hits a protected endpoint without a valid token, the module responds with 402 Payment Required and a Lightning invoice. The client pays the invoice, receives a preimage, and presents it alongside the macaroon to gain access.

Supported Backends

Configure the backend via the LN_CLIENT_TYPE environment variable:

See Environment Variables for the full list of per-backend settings.

Payment Flow

1. Client requests a protected endpoint (no auth header).
2. Module generates a macaroon and requests an invoice from the configured Lightning backend.
3. Module responds 402 Payment Required with:

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

4. Client pays the invoice and obtains the preimage.
5. Client retries with:

   Authorization: L402 <macaroon>:<preimage>
   

6. Module verifies the macaroon + preimage and returns 200 OK.

Authorization Header Format

Two formats are accepted:

The preimage in the classic format must be the 32-byte (256-bit) hex-encoded payment preimage corresponding to the invoice’s payment_hash.

Auto-Detect Payment (Server-Side Settlement Lookup)

With auto-detect enabled the client only needs to send the macaroon — no preimage required. The module queries your Lightning node directly to check whether the invoice is settled and retrieves the preimage from the node.

Enabling auto-detect

Add l402_auto_detect_payment on to any location {} block:

location /protected {
    l402                         on;
    l402_amount_msat_default     10000;
    l402_macaroon_timeout        0;
    l402_auto_detect_payment     on;   # ← enables server-side lookup
}

All boolean directives (l402, l402_auto_detect_payment) accept: on / off / true / false / 1 / 0 / yes / no (case-insensitive).

Client flow with auto-detect enabled

1. Client requests a protected endpoint → receives 402 Payment Required with a BOLT-11 invoice.
2. Client pays the invoice (no preimage handling needed).
3. Client retries with just the macaroon:

   Authorization: L402 <macaroon>
   

4. Module extracts the payment_hash from the macaroon identifier, queries the node, and — if the invoice is settled — uses the returned preimage to verify the macaroon signature.
5. On success the module returns 200 OK. If the invoice is not yet settled, it returns 402 Payment Required.

Preimage caching (Redis)

When Redis is configured (REDIS_URL), settled preimages are cached under the key l402:settled:<payment_hash_hex>. Subsequent requests for the same payment hash are served from the cache, avoiding repeated node round-trips.

Backend support matrix

Note

Even when l402_auto_detect_payment on is set, the classic L402 <macaroon>:<preimage> format is still accepted — auto-detect only activates when the client omits the preimage.

Wallet Compatibility

Warning

Some wallets (e.g. Wallet of Satoshi) return 48-byte non-standard preimages, which are not compatible with this module. Use a wallet that returns a standard 32-byte preimage.

Also Supported: Cashu eCash

In addition to Lightning, the module accepts Cashu eCash tokens via the X-Cashu header as an alternative payment method. See Cashu eCash Support for details.