API overview
One HTTP API, described by one OpenAPI 3.1 document, from which this reference, the SDK types and the plain-Markdown summary for agents are all generated.
The OpenAPI document is the authority for every route, field and error name. If a field is not in it, no client should depend on it. The types of all four SDKs are generated from it.
| Document | /openapi.yaml · /openapi.json |
| For agents | /api-reference.md |
| Errors | /errors · /errors.json |
CoRelayer runs on devnet only; nothing is deployed on mainnet yet.
Hosts
| Surface | URL |
|---|---|
| REST API | https://api.co-relayer.com/v1/… |
| Compatibility facade | https://api.co-relayer.com/health, /relayer/address/{erd}, /relay |
| x402 | https://api.co-relayer.com/v1/x402/*, /.well-known/x402 |
| MCP | https://mcp.co-relayer.com/mcp, /readonly |
| Staging (devnet) | https://devnet-api.co-relayer.com |
Regional hosts for client-side failover are published in GET /v1/network as directHosts. Take
them from there rather than hard-coding them: the failover list should be the operator's, not a
guess frozen into a build.
One process serves every surface. The compatibility, x402 and MCP surfaces are adapters in
front of POST /v1/relay — one validation pipeline, one signer boundary, one ledger. There is no
second relay path.
Versioning
| Major version | In the path: /v1. A breaking change creates /v2, and /v1 keeps running alongside it. |
| Non-breaking, allowed inside v1 | New routes, new optional request members, new response members, new values in enums documented as open. |
| Open enums | ErrorCode, NoticeKind, DetectorCode, ComponentId, PurchaseKind. |
| Frozen enums | IntentState, DeadReason, ResignAction, RelayMode, ServiceState, RelayerStateName, BillingClass, ExecStatus, AuthMode. |
| Breaking | Removing or renaming anything, changing a type, changing what an error code means, tightening documented validation. |
| Deprecation | Deprecation and Sunset headers plus a Link with rel="deprecation", well before removal. |
| The compatibility facade | Unversioned and frozen. Its shape belongs to third-party clients. |
The client contract: ignore unknown members, and handle an unknown error code by its HTTP
status and retryable. A client that raises on an unfamiliar code will break for no reason.
Several things version independently of the API, and none of them is coupled to it: the Relay Unit schedule, the rate-class policy, the pricing document, the lease layout and the webhook payload version.
The route groups
| Tag | What is in it | Auth |
|---|---|---|
| meta | Liveness, readiness, the OpenAPI document, the x402 descriptor, GET /v1/network | public |
| relay | Assign, relay, intent status, the per-intent stream, quote, validate | the transaction; presence proof for assign |
| pricing | The pricing document and the tariff history | public |
| purchase | The four prepare routes that build unsigned transactions | public |
| x402 | Top-up and purchase over HTTP 402 | x402 |
| registry | The relayer registry as the API mirrors it | public |
| status | Service state and incidents | public |
| account | Plan, quota, senders, purchases — mirrors of chain state | public |
| dashboard | Notices, usage, latency, per-account relayers and outages | native-auth or a read key |
| keys | Sponsor API keys | native-auth only |
| notifications | Webhooks, notification preferences, the account stream | native-auth only |
| compat | The frozen third-party facade | the transaction |
The dividing line for the public reads is one rule: a pure mirror of chain state is public; anything derived from our own ledger or configuration is private. Your quota is derivable from the chain, so it is public. Your per-transaction latency is our measurement of you, so it is not.
The shape of a call
curl -sS https://api.co-relayer.com/v1/pricing \
-H 'accept: application/json'
curl -sS https://api.co-relayer.com/v1/relay \
-H 'content-type: application/json' \
-H 'Idempotency-Key: order-7f2c0a41' \
-d '{"tx": { … }, "lease": "…"}'
Every response carries CoRelayer-Request-Id — the same value as a problem document's instance,
and the one to quote to support — and CoRelayer-Version, the API build.
The conventions that apply to every route are on their own page: Conventions.
Reading the reference
The Reference section of this sidebar is generated from the OpenAPI document, one page per operation, grouped by tag. Each page shows the parameters, the request schema, every response and the schemas they reference.
There is deliberately no "try it" console. A button that cannot reach anything is worse than no button; it will come back when an environment is public.
The compatibility facade
Three unversioned routes at the API root, with shapes fixed by a third-party starter kit:
| Route | Behaviour |
|---|---|
GET /health | {"status":"ok"} |
GET /relayer/address/{userAddress} | One relayer address, deterministic and long-lived, no lease. |
POST /relay | Takes a transaction naming any of our active or draining relayers in the right shard. Transaction-as-credential only. Stricter limits: one unit per second, minimum gas price, simulation always on, no modes. |
It exists because those clients cache a relayer address forever with no expiry. That is also why a relayer handed out here drains for a full month before it can retire: there is no way to tell those clients to look again. (Relayers)