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

# Gateway Payments API: x402 Proxy Flow and Auth Headers

> How the x402 two-step payment flow works on the Meterlane Agent Gateway, including headers, 402 challenges, and paid proxy requests.

The Meterlane Agent Gateway implements the [x402 payment protocol](https://x402.org) to gate HTTP requests behind USDC micropayments. The flow is intentionally lightweight: your first request to a paid route returns a `402` with machine-readable payment requirements; you sign a USDC transfer, attach it as the `X-PAYMENT` header, and retry. The gateway verifies the payment with the facilitator, settles on-chain, and proxies your request to the upstream service — all within the same HTTP round trip.

***

## GET /gateway/:orgSlug/:routePath

The paid proxy endpoint. Every route you create is reachable at this pattern.

```http theme={null}
GET https://gateway.meterlane.app/gateway/{orgSlug}/{routePath}
```

### Path parameters

<ParamField path="orgSlug" type="string" required>
  Your organisation's URL slug, visible in the dashboard under **Settings → General**.
</ParamField>

<ParamField path="routePath" type="string" required>
  The route path you configured when creating the route, e.g. `weather/forecast`.
</ParamField>

### Request headers

<ParamField header="X-PAYMENT" type="string">
  Base64-encoded signed x402 payment payload. Omit this header on the first (probe) request to receive the `402` challenge. Include it on the retry to authorise payment and receive the proxied response.
</ParamField>

***

### Step 1 — Unpaid probe (`402 Payment Required`)

When you call a route without a valid `X-PAYMENT` header the gateway returns `402` and sets `X-Payment-Requirements` with a JSON object describing exactly what you need to pay.

<Steps>
  <Step title="Send an unpaid request">
    Call the route URL without any payment header to discover the requirements.

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

  <Step title="Receive the 402 challenge">
    The gateway responds with `402 Payment Required` and the `X-Payment-Requirements` header.

    ```http theme={null}
    HTTP/1.1 402 Payment Required
    X-Payment-Requirements: {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "resource": "https://gateway.meterlane.app/gateway/demo/demo",
      "description": "Demo route — $0.01 per request",
      "mimeType": "application/json",
      "payTo": "0xAbCd…1234",
      "maxTimeoutSeconds": 60,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USDC",
        "version": "2"
      }
    }
    ```

    The `maxAmountRequired` value is in the token's smallest unit (6 decimals for USDC), so `10000` equals `$0.01`.
  </Step>
</Steps>

***

### Step 2 — Paid request (`200 OK`)

Use the requirements to construct and sign an ERC-3009 `transferWithAuthorization` payload, then send it as the `X-PAYMENT` header.

<Steps>
  <Step title="Sign the payment">
    Use the x402 client library to sign a USDC transfer using the details from `X-Payment-Requirements`.

    ```typescript theme={null}
    import { signPayment } from "@meterlane/x402";

    const payment = await signPayment(wallet, paymentRequirements);
    ```
  </Step>

  <Step title="Retry with X-PAYMENT">
    Attach the signed payload as the `X-PAYMENT` header and resend the request.

    ```bash theme={null}
    curl -i https://gateway.meterlane.app/gateway/demo/demo \
      -H "X-PAYMENT: <base64-encoded-payload>"
    ```
  </Step>

  <Step title="Receive the proxied response">
    The gateway verifies the payment with the facilitator, settles on-chain, and forwards your request to the upstream. You receive the upstream's response directly.

    ```http theme={null}
    HTTP/1.1 200 OK
    Content-Type: application/json

    {
      "temperature": 22,
      "condition": "Sunny",
      "location": "San Francisco"
    }
    ```
  </Step>
</Steps>

***

### Full flow reference

```text theme={null}
Agent → Gateway          GET /gateway/org/route (no X-PAYMENT)
Gateway → Agent          402 + X-Payment-Requirements

Agent → Agent            Sign ERC-3009 transferWithAuthorization
Agent → Gateway          GET /gateway/org/route + X-PAYMENT

Gateway → Facilitator    Verify & settle payment
Facilitator → Gateway    OK

Gateway → Upstream       Proxy request
Upstream → Gateway       Response body
Gateway → Agent          200 + upstream body
```

***

## Error codes

The table below covers errors specific to the payment proxy path.

| Code              | HTTP Status | Cause                                                                                    |
| ----------------- | ----------- | ---------------------------------------------------------------------------------------- |
| `NONCE_REPLAY`    | 400         | The payment nonce in `X-PAYMENT` has already been used. Generate a fresh signed payment. |
| `ROUTE_NOT_FOUND` | 404         | No active route matches the requested `orgSlug` / `routePath` combination.               |
| `ORG_SUSPENDED`   | 403         | The organisation associated with this route has been suspended. Contact support.         |

<Note>
  Each payment nonce is single-use. If you retry an identical `X-PAYMENT` payload you will always receive `NONCE_REPLAY`. Your x402 client library handles nonce generation automatically on each signing call.
</Note>