x402 OpenRouter Starter Tutorial

A step-by-step tutorial to publish a paid AI API with x402. You will:

• Configure your wallet address and API keys
• Run the server locally
• Expose it with ngrok
• Fund a Base Sepolia wallet
• Test free and paid endpoints with curl (and an optional auto-pay script)

Prerequisites

• Node.js and pnpm installed
• ngrok installed
• A Base-compatible wallet (MetaMask, Coinbase Wallet, etc.)
• An OpenRouter API key

1) Install dependencies

pnpm install

2) Create .env

Create a file named .env in the project root:

# Required: pay-to address (where you receive payments)
ADDRESS=0xYourWalletAddress

# Required: OpenRouter
OPENROUTER_API_KEY=your_openrouter_key
OPENROUTER_MODEL=openai/gpt-4o-mini

# Optional: network (default is testnet -> Base Sepolia)
X402_ENV=testnet

# Optional: payer wallet for client auto-pay tests
# If set, the test script can auto-pay using this private key
PRIVATE_KEY=0xYourPrivateKey

Notes:

• ADDRESS is the destination wallet for payments.
• Testnet uses Base Sepolia; mainnet uses Base. Set X402_ENV=mainnet to switch.
• If you set PRIVATE_KEY, the test script can auto-pay; ensure this wallet is funded.

3) Start the server

pnpm dev

The server listens on http://0.0.0.0:4021.

4) Start ngrok

In another terminal:

ngrok http 4021

Copy the forwarding URL, e.g. https://abc-123.ngrok-free.app.

5) Fund your wallet (testnet)

You need both:

• Base Sepolia ETH for gas
• Base Sepolia USDC (about $0.001 per paid request)

Use testnet faucets/bridges where available, then confirm balances at: https://sepolia.basescan.org/address/YourAddress

6) Test free endpoints with curl

Replace NGROK with your URL:

NGROK=https://abc-123.ngrok-free.app

curl "$NGROK/"
curl "$NGROK/config"

7) Test the paid endpoint with curl (see the 402 challenge)

curl -i -X POST "$NGROK/generate-text" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Hello! Tell me a fun fact."}'

You should see 402 Payment Required with payment headers (X-PAYMENT / WWW-Authenticate) describing the required payment ($0.001 USDC on the configured network, payTo = your ADDRESS).

8) Test the paid endpoint with auto-payment (optional)

If you set PRIVATE_KEY and funded that wallet:

npx tsx test-endpoint.ts paid $NGROK

The script uses wrapFetchWithPayment to read the 402 challenge, pay from the PRIVATE_KEY wallet, and retry. On success you get 200 with the AI response. If you see insufficient_funds, add USDC and a small amount of ETH on Base Sepolia to the payer wallet.

Other script commands:

# Free endpoints
npx tsx test-endpoint.ts free $NGROK

# Check payments and explorer links
npx tsx test-endpoint.ts check

9) Verify payments

Check the pay-to wallet (ADDRESS) on the explorer:

• Testnet: https://sepolia.basescan.org/address/YourAddress
• Mainnet: https://basescan.org/address/YourAddress

Each successful paid call shows an incoming USDC transfer (~$0.001) and the payer wallet shows gas spend.

How it works

1. Client calls POST /generate-text.
2. paymentMiddleware returns 402 with payment requirements (price, network, payTo).
3. An x402-capable client (for example wrapFetchWithPayment) builds a payment header and pays from the payer wallet.
4. The facilitator relays the transfer on-chain from payer to ADDRESS.
5. With proof of payment, the request is retried and the server returns the AI response.

Files to know

• src/server.ts — Express server and x402 payment middleware.
• src/prompt{edit}.ts — Customize prompts and model defaults.
• test-endpoint.ts — CLI tester; supports free, paid (auto-pay with PRIVATE_KEY), and payment checks.
• test-endpoint.sh — Curl-based quick test (shows payment headers).
• test-browser.html — Simple browser UI to call the endpoints (no auto-payment).

Common issues

• Missing .env values: ensure ADDRESS, OPENROUTER_API_KEY, OPENROUTER_MODEL.
• 402 insufficient_funds: fund the payer wallet with Base Sepolia USDC and a bit of ETH for gas.
• Wrong network: Base Sepolia is default; set X402_ENV=mainnet for Base mainnet and fund with real assets.

License

MIT