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, /stream | operators | admin token |
/mcp | agents | payment |
/a2a, /.well-known/agent-card.json | agents | payment |
/acp/…, /.well-known/acp.json | agents | bearer token |
A2A and ACP routes exist only while those protocols are enabled.
Authentication
| Scheme | Header | Applies to |
|---|---|---|
| Operator | Authorization: Bearer <server.adminToken> | receipts and events; 404 when no token is configured |
| ACP | Authorization: Bearer <protocols.acp.auth.token> | every ACP checkout route |
| Payment | PAYMENT-SIGNATURE: <base64 proof> | paid resources over HTTP |
| 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 KB. - Amounts are decimal strings in display units —
"0.01", never floats. - Timestamps are ISO 8601 strings.
X-Request-Idis accepted as[A-Za-z0-9._:-]{1,64}; every outcome carries arequestIdthat also appears in logs, events and receipts.- Browsers need an origin in
server.allowedOrigins; agent traffic gets no CORS headers. - Failures use one error envelope.