> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meterlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 Payment Flow: How Agents Settle USDC Per Request

> Walk through the complete x402 request lifecycle — from the initial 402 challenge through ERC-3009 signing, on-chain settlement, and upstream proxying.

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

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant Gateway
  participant Facilitator
  participant Upstream

  Agent->>Gateway: GET /gateway/acme/summarize (no X-PAYMENT)
  Gateway->>Agent: 402 + X-Payment-Requirements

  Note over Agent: Agent reads amount, network, payTo<br/>from requirements and signs ERC-3009

  Agent->>Gateway: Retry GET /gateway/acme/summarize + X-PAYMENT
  Gateway->>Facilitator: Verify & settle payment
  Facilitator-->>Gateway: Settlement confirmed

  Gateway->>Upstream: Proxy original request
  Upstream-->>Gateway: Response body
  Gateway-->>Agent: 200 + upstream response body
```

## 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:

```json theme={null}
{
  "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 |

<Note>
  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.
</Note>

## Trying the demo route

You can inspect a real `402` response right now using curl. No account or API key required:

```bash theme={null}
curl -i https://gateway.meterlane.app/gateway/demo/demo
```

The response will look similar to this:

```http theme={null}
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:

```json theme={null}
{
  "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.