ngx-x402

Nginx module for the x402 HTTP micropayment protocol. Acts as a reverse proxy that adds x402 payment gates in front of existing APIs without modifying the backend.

Features

• Reverse proxy: Place in front of any HTTP API via proxy_pass
• x402 protocol: Full HTTP 402 Payment Required flow with Facilitator verification
• Multi-tenant: Different pay_to addresses per location block
• Dynamic pricing: Override prices at runtime via Redis
• Replay prevention: SHA256-based signature tracking in Redis with configurable TTL
• Prometheus metrics: /metrics endpoint for observability
• Browser support: HTML paywall page for browser requests, JSON for API clients
• Facilitator fallback: Configurable error/pass behavior when facilitator is unavailable

Quick Start

# First-time setup: copy the example config and edit x402_pay_to with your wallet address
cp nginx.conf.example nginx.conf

docker-compose up

Configuration

load_module /usr/lib/nginx/modules/libngx_x402.so;

http {
    server {
        location /api/weather {
            x402 on;
            x402_amount 0.001;
            x402_pay_to 0xYourWalletAddress;
            x402_facilitator_url https://x402.org/facilitator;
            x402_network base-sepolia;
            x402_description "Weather API";

            proxy_pass http://backend:3000/api/weather;
        }
    }
}

Directives

Dynamic Pricing via Redis

# Override price for a path
redis-cli SET /api/weather 0.005

# Price takes effect on next request (no nginx reload needed)

Building from Source

sudo apt-get install -y build-essential clang libclang-dev nginx
cargo build --release --features export-modules

The compiled module will be at target/release/libngx_x402.so.

License

Apache-2.0