Overview
API reference
The gateway's HTTP surface: agent routes, public discovery, operator routes and protocol mounts.
The gateway serves JSON over HTTP at merchant.publicBaseUrl — http://localhost:8080 in every example below. Routes split by audience, and the split is enforced.
Routes
| Route | Audience | Auth |
|---|---|---|
GET /health, GET /ready | probes | none |
GET /.well-known/agent-commerce | anyone | none |
GET /api/resources | anyone | none |
POST /api/resources/{id}/invoke | agents | payment, not authentication |
GET /api/receipts | operators | admin token |
GET /api/events | operators | admin token |
GET /api/payment-attempts, POST /api/payment-attempts/{id}/resolve | operators | admin token |
GET /api/transactions, GET /api/transactions/{id} | operators | admin token |
/mcp | agents | payment |
/a2a, /.well-known/agent-card.json | agents | payment; the card is public |
/acp/…, /.well-known/acp.json | agents | bearer token; discovery is public |
MCP, A2A and ACP routes exist only while those protocols are enabled.
Authentication
| Scheme | Header | Applies to |
|---|---|---|
| Operator | Authorization: Bearer <server.adminToken> | receipts, events, payment attempts and transactions; 404 when no token is configured |
| ACP | Authorization: Bearer <protocols.acp.auth.token> | every ACP checkout route |
| x402 payment | PAYMENT-SIGNATURE: <base64 proof> | paid resources over HTTP |
| MPP payment | Authorization: Payment <credential> | resources whose first enabled rail is MPP |
| Mandate | Agent-Authorization: <base64url envelope> | resources that require AP2 |
Tokens are compared in constant time. A token is never accepted as a query parameter.
Conventions
- Request bodies are JSON (
content-type: application/json), capped at 256 KiB. The invoke route also accepts plain text or an empty body. - Amounts are decimal strings in display units —
"0.01", never floats. - Timestamps are ISO 8601 strings.
- Resource invocation outcomes carry a gateway-generated
requestIdthat links logs, events and receipts. A valid clientX-Request-Id([A-Za-z0-9._:-]{1,64}) is logged for correlation; it does not replace the audit ID. - Browsers need an origin in
server.allowedOrigins; agent traffic gets no CORS headers. - Gateway failures use the error envelope; framework errors such as malformed JSON and unknown routes use their own format.