An L402 authentication module for Nginx that enables Lightning Network-based monetization for your REST APIs (HTTP/1 and HTTP/2).

Supports LND, LNC, CLN, Eclair, LNURL, NWC, and BOLT12 backends.

For local contributor setup on macOS (Docker nginx recommended), see docs/macos-setup.md.

• Server-side auto-detect — Enable l402_auto_detect_payment on in nginx.conf and clients no longer need to include the preimage in the Authorization header. The module queries your Lightning node directly (LND, CLN, or Eclair) to confirm payment settlement.
• Classic preimage flow — Standard L402 <macaroon>:<preimage> header is always supported.
• Cashu eCash support — Accept Cashu tokens as an alternative payment method via the X-Cashu header.
• Redis caching — Settled preimages are cached in Redis to avoid repeated node lookups.
• Multi-tenant LNURL — Per-location LNURL addresses for multi-tenant deployments.

Full documentation is available at: https://dhananjaypurohit.github.io/ngx_l402/

• Installation
• Docker Setup
• Configuration & Environment Variables
• Cashu eCash Support
• Multi-Tenant
• Dry-Run (Shadow) Mode
• Building from Source

Requires NGINX 1.28.0 or later.

Pre-built binaries are provided for NGINX 1.28.0 only. For other versions, build from source:

docker build --build-arg NGX_VERSION=<your-version> -t ngx_l402 .

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

Test it:

curl http://localhost:8000/           # 200 OK
curl -i http://localhost:8000/protected  # 402 Payment Required

See CONTRIBUTING.md for guidelines.

MIT