Skip to main content
ARouter supports the x402 payment protocol, the open standard for HTTP-native payments. When an agent’s credit balance hits zero, the gateway returns 402 Payment Required with machine-readable payment instructions. An x402-compatible wallet can sign a USDC payment and retry the request — fully autonomous, no dashboard login required.

​
How It Works

  1. The agent sends a normal LLM request with its API key.
  2. The gateway detects insufficient credits and responds with HTTP 402 plus a PAYMENT-REQUIRED header containing payment options (amount, wallet address, network).
  3. The agent’s wallet signs a USDC payment matching one of the options.
  4. The agent retries the same request, adding the PAYMENT-SIGNATURE header.
  5. The gateway verifies the payment, credits the tenant account, and serves the LLM response.

​
Enabling x402

Set these environment variables on your ARouter gateway deployment:
VariableRequiredDefaultDescription
X402_ENABLEDYesfalseSet to true to enable x402 payments.
X402_WALLET_ADDRESSYes—Your USDC receiving wallet address.
X402_FACILITATOR_URLNohttps://x402.org/facilitatorx402 Facilitator endpoint for verify/settle.
X402_DEFAULT_TOPUPNo$5Default top-up amount per payment.
X402_TOPUP_AMOUNTSNo$1,$5,$10,$20Available top-up tiers.
X402_NETWORKSNoeip155:8453Supported networks (CAIP-2 format, comma-separated).
X402_MAX_TOPUPNo$100Maximum single payment amount.
When X402_ENABLED=false (the default), the gateway behaves exactly as before. The x402 middleware is a complete no-op with zero runtime overhead.

​
Supported Networks

NetworkCAIP-2 IdentifierToken
Base Mainneteip155:8453USDC
Base Sepolia (testnet)eip155:84532USDC
Solana Mainnetsolana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpUSDC
Solana Devnetsolana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1USDC

​
SDK Usage

​
Go SDK

import arouter "github.com/arouter-ai/arouter/sdks/golang"

client := arouter.NewClient(
    "https://api.arouter.com",
    "lr_live_xxxx",
    arouter.WithX402Signer(myEvmSigner), // auto-pays on 402
)

// This call will auto-retry with payment if credits are empty
resp, err := client.ChatCompletion(ctx, &arouter.ChatCompletionRequest{
    Model:    "openai/gpt-4o",
    Messages: []arouter.Message{{Role: "user", Content: "Hello"}},
})
Implement the X402Signer interface with the official x402 Go SDK for production-grade EVM or Solana signing.

​
Direct HTTP (curl)

Step 1 — Make the request (gets 402): 
curl -i https://api.arouter.com/v1/chat/completions \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o","messages":[{"role":"user","content":"Hello"}]}'
Response: 
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJhY2NlcHRzIjpbey...base64...
Content-Type: application/json

{"error":{"message":"insufficient credits, please top up your balance","type":"billing_error","code":"insufficient_credits"}}
Step 2 — Decode the PAYMENT-REQUIRED header, sign payment, retry: 
curl -i https://api.arouter.com/v1/chat/completions \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "PAYMENT-SIGNATURE: eyJzY2hlbWUiOi...signed-payload-base64..." \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

​
Payment Headers

HeaderDirectionDescription
PAYMENT-REQUIREDServer → ClientBase64-encoded payment options (amount, wallet, network).
PAYMENT-SIGNATUREClient → ServerBase64-encoded signed payment payload.
PAYMENT-RESPONSEServer → ClientBase64-encoded settlement result (on success/failure).

​
How Credits Work

  • x402 payments are deposited as credits into your tenant balance — the same pool used by Stripe and Helio payments.
  • All x402 transactions appear in the Billing page under transaction history with the x402_topup reference type.
  • The gateway deducts credits per-request as usual after the balance is topped up.

​
Security

  • Facilitator verification: Payments are cryptographically verified via the x402 Facilitator before credits are granted.
  • Amount cap: X402_MAX_TOPUP prevents unexpectedly large payments (default $100).
  • Idempotency: Each payment payload has a unique nonce — the same signature cannot be replayed.
  • Audit trail: All x402 top-ups are recorded in credit_transactions alongside Stripe/Helio payments.
  • Non-custodial: USDC goes directly to your wallet. The Facilitator never holds funds.