x402 Payment Flow: How Agents Settle USDC Per Request

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

Headers

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

The 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

The response will look similar to this:

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

Always capture requestId from error responses. It is the fastest way for the Meterlane support team to trace a specific request through the system.

Get Started

Agent Gateway

Stablecoin Corridor

Integrations

Account & Billing

x402 Payment Flow: How Agents Settle USDC Per Request

Request lifecycle

Headers

Network selection

Trying the demo route

Nonce replay protection

Error codes

​Request lifecycle

​Headers

​Network selection

​Trying the demo route

​Nonce replay protection

​Error codes

Request lifecycle

Headers

Network selection

Trying the demo route

Nonce replay protection

Error codes