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
Your organisation’s URL slug, visible in the dashboard under Settings → General.
The route path you configured when creating the route, e.g. weather/forecast.
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"
}
}
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.
