Gateway Payments API: x402 Proxy Flow and Auth Headers

The Meterlane Agent Gateway implements the x402 payment protocol 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.

GET https://gateway.meterlane.app/gateway/{orgSlug}/{routePath}

Path parameters

string

required

Your organisation’s URL slug, visible in the dashboard under Settings → General.

string

required

The route path you configured when creating the route, e.g. weather/forecast.

Request headers

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.

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.

Send an unpaid request

Call the route URL without any payment header to discover the requirements.

curl -i https://gateway.meterlane.app/gateway/demo/demo

Receive the 402 challenge

The gateway responds with 402 Payment Required and the X-Payment-Requirements header.

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

Sign the payment

Use the x402 client library to sign a USDC transfer using the details from X-Payment-Requirements.

import { signPayment } from "@meterlane/x402";

const payment = await signPayment(wallet, paymentRequirements);

Retry with X-PAYMENT

Attach the signed payload as the X-PAYMENT header and resend the request.

curl -i https://gateway.meterlane.app/gateway/demo/demo \
  -H "X-PAYMENT: <base64-encoded-payload>"

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/1.1 200 OK
Content-Type: application/json

{
  "temperature": 22,
  "condition": "Sunny",
  "location": "San Francisco"
}

Full flow reference

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.

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.

Gateway API

Corridor API

Gateway Payments API: x402 Proxy Flow and Auth Headers

GET /gateway/:orgSlug/:routePath

Path parameters

Request headers

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

Step 2 — Paid request (`200 OK`)

Full flow reference

Error codes

​GET /gateway/:orgSlug/:routePath

​Path parameters

​Request headers

​Step 1 — Unpaid probe (402 Payment Required)

​Step 2 — Paid request (200 OK)

​Full flow reference

​Error codes

GET /gateway/:orgSlug/:routePath

Path parameters

Request headers

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

Step 2 — Paid request (`200 OK`)

Full flow reference

Error codes