Every request to a gateway route goes through a two-step cycle: the gateway first challenges the agent for payment, then — once a valid signed payment is attached — verifies settlement on-chain and proxies the request to your upstream. The entire round-trip is transparent to the agent’s caller and typically completes in under a second. Understanding this flow helps you build agents that handle payment challenges gracefully and diagnose errors quickly.
Request lifecycle
| Header | Direction | Purpose |
|---|
X-PAYMENT | Request | Base64-encoded signed payment payload (ERC-3009 transferWithAuthorization) |
X-Payment-Requirements | Response (402) | JSON object describing the amount in USDC, the payee address, and the target network |
Idempotency-Key | Management API requests | Prevents duplicate route creation or configuration changes on retry |
X-Payment-Requirements response tells the agent exactly what to sign. A typical requirements object looks like this:
{
"scheme": "exact",
"network": "eip155:84532",
"payTo": "0xYourReceiverAddress",
"maxAmountRequired": "10000",
"asset": "0x...",
"extra": {}
}
maxAmountRequired is denominated in the token’s smallest unit (USDC uses 6 decimals, so 10000 = $0.01).
Network selection
The gateway routes your payment to the correct network based on your route’s configuration.
| Network | Chain ID | When to use |
|---|
| Base Sepolia | eip155:84532 | Development and sandbox testing |
| Base mainnet | eip155:8453 | Production — live USDC payments |
The public facilitator at https://x402.org/facilitator always targets Base Sepolia. To accept live USDC on Base mainnet, configure your route with "network": "eip155:8453" and use a production-mode facilitator.
Trying the demo route
You can inspect a real 402 response right now using curl. No account or API key required:
curl -i https://gateway.meterlane.app/gateway/demo/demo
HTTP/2 402
content-type: application/json
x-payment-requirements: {"scheme":"exact","network":"eip155:84532","payTo":"0x...","maxAmountRequired":"1000","asset":"0x..."}
{
"error": "Payment required",
"accepts": [
{
"scheme": "exact",
"network": "eip155:84532",
"payTo": "0x...",
"maxAmountRequired": "1000"
}
]
}
Nonce replay protection
The gateway tracks every payment nonce it has processed. Once a signed payment nonce has been used, any attempt to replay the same signed payload is rejected. This prevents double-spending on a single authorization.
Error codes
All error responses share the same shape:
{
"code": "NONCE_REPLAY",
"message": "This payment nonce has already been used.",
"requestId": "3f2a1b4c-..."
}
| Code | HTTP status | Meaning |
|---|
NONCE_REPLAY | 402 | The signed payment nonce was already consumed — generate a fresh authorization |
NOT_FOUND | 404 | No active route matches the requested path under this org slug |
ORG_SUSPENDED | 403 | The organization’s account is suspended |
PLAN_LIMIT_EXCEEDED | 402 | Monthly request limit for the organization’s plan has been reached |
MISCONFIGURED | 503 | The organization has no receiver wallet configured |
UPSTREAM_TIMEOUT | 504 | Your upstream did not respond within the allowed time window |
UPSTREAM_UNAVAILABLE | 503 | No healthy upstream target could be reached |
INTERNAL_ERROR | 500 | Unexpected gateway error — include requestId when contacting support |
requestId from error responses. It is the fastest way for the Meterlane support team to trace a specific request through the system. 
