Reference
API reference
All endpoints live under your gateway origin, for example https://gateway.tollgate402.com. Responses are JSON; amounts are decimal strings in USDG.
Endpoints
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /.well-known/x402 | Route catalog with prices and session terms | none |
| GET|POST | /x402/:route | Gated route; 402 without payment, 200 with X-PAYMENT | x402 |
| POST | /x402/sessions | Open a prepaid session for a route | x402 |
| GET | /x402/receipts/:nonce | Settlement receipt for a payment | API key |
| GET | /x402/stats | Gate hits, settlements and revenue counters | none |
| POST | /vault/secrets | Store or rotate a secret | admin |
| POST | /vault/broker | Make an upstream call with secret substitution | API key |
| GET | /agents/:id | Agent wallet, spend and reputation | API key |
| POST | /rpc | Read-only JSON-RPC proxy (eth_call, eth_getLogs, …) | none |
Authentication
Agent endpoints take Authorization: Bearer tg_live_…. Gated routes take X-PAYMENT, a base64-encoded signed PaymentIntent. Admin endpoints take the key set in TOLLGATE_ADMIN_KEY.
Receipt object
{
"nonce": "0x8f1c…e20b",
"route": "/x402/premium",
"amount": "0.01",
"asset": "USDG",
"payer": "0x3be1…07c4",
"payTo": "0x7A3f92bE01c4D58aF6e3B27d90C1a4E58f2Dc21E",
"network": "eip155:4663",
"tx": "0x9c4f…a1d2",
"block": 91016422,
"settledAt": "2026-10-17T13:25:04Z",
"latencyMs": 96
}Errors
| Status | Code | Meaning |
|---|---|---|
| 402 | payment_required | No or invalid X-PAYMENT; body holds a fresh challenge |
| 409 | nonce_replayed | This nonce was already settled |
| 410 | intent_expired | The PaymentIntent passed its validBefore |
| 429 | rate_limited | Per-agent limit hit; see Retry-After |
| 403 | vault_host_denied | Secret not allowed for this upstream host |