CoRelayer for agents

If you are a program rather than a person, this page is the whole product. It is dense on purpose and self-contained on purpose: you may have arrived here from llms.txt without seeing any other page.

What CoRelayer does for you: it pays the MultiversX network fee for transactions you sign, so you never need to hold EGLD. You pay in USDC, either as a monthly plan or per request over x402. You sign each transaction exactly once.

On devnet only

CoRelayer runs on devnet only; nothing is deployed on mainnet yet.

Which networks are live, with their API hosts and contract addresses, is published at /.well-known/corelayer.json. A connection failure is a transport problem, not a protocol error: retry it as one.

Machine-readable entry points

URL	What it is
https://docs.co-relayer.com/llms.txt	This documentation, as a link index.
https://docs.co-relayer.com/llms-full.txt	This documentation, in full, as one text file.
https://docs.co-relayer.com/llms-agents.txt	Only the agent-relevant pages, in full.
https://docs.co-relayer.com/openapi.yaml · .json	The API, OpenAPI 3.1.
https://docs.co-relayer.com/api-reference.md	The API as plain Markdown, one section per operation.
https://docs.co-relayer.com/errors.json	Every error code, machine-readable.
https://docs.co-relayer.com/abi/corelayer.abi.json	The smart-contract ABI.
https://api.co-relayer.com/v1/network	Chain id, contract address, direct hosts, native-auth block.
https://api.co-relayer.com/v1/pricing	Live tiers and tariff.
https://api.co-relayer.com/.well-known/x402	x402 resource descriptor.
https://mcp.co-relayer.com/mcp · /readonly	MCP server, Streamable HTTP: twenty tools, each running the REST route it wraps; the MCP server lists them.

Any page on this site is also Markdown: append .md to its URL.

The minimum loop

1. GET  /v1/network                     → chainId, contract address
2. GET  /v1/account/{you}/quota         → do you have entitlement?
   if not → buy: POST /v1/x402/purchase  or  on-chain depositAndSubscribe
3. POST /v1/relay/assign {sender, proof} → relayer, lease, gas bounds
4. build tx with `relayer` set; SIGN ONCE
5. POST /v1/relay {tx, lease}            → intentId, txHash, state
6. GET  /v1/relay/{intentId}/events      → until final (or poll /v1/intents/{sender}/{nonce})

Step 4 is one signature. There is no variant set, no racing, no second signing. (One signature)

The rules that will bite you if you skip them

1. Compare chain ids. Our addresses are identical on devnet and mainnet. An address is not a network identifier. Compare chainId from /v1/network with the chainID of the transaction you are about to sign, and refuse on a mismatch.
2. Pin the contract address. Take it from your own configuration, never from an API response. The discovery files are convenience copies; where they disagree with your pin, your pin wins.
3. Verify the relayer on chain before signing: getRelayerState(relayer) must be active. Query a node that is not ours. Cache by registryVersion.
4. An error from POST /v1/relay means nothing was sent. No error is ever returned after the relayer signature exists.
5. On a timeout, re-send the identical bytes or query the intent. Never rebuild, never re-sign.
6. Branch on code, not on title or detail. The enum is open; handle an unknown code by its HTTP status and its retryable member.
7. Only sign again when resign says so. NONE, SAME_BYTES, NEW_SIGNATURE_SAME_NONCE — never infer it from a status code.
8. Set an idempotency key, one per logical action: Idempotency-Key header or intentKey in the body.
9. Never log tool arguments containing a signed transaction. A signed payload in a transcript is a payload someone else can hold.

Errors

Everything is an RFC 9457 problem document, application/problem+json, whose type is a page on this site:

{
  "type": "https://docs.co-relayer.com/errors/quota-exhausted",
  "title": "The plan's included Relay Units are used up.",
  "status": 429,
  "detail": "Cap of 1000 RU reached for the period ending 2026-10-19T00:00:00Z.",
  "instance": "req_01JB…",
  "code": "QUOTA_EXHAUSTED",
  "retryable": false,
  "resign": "NONE",
  "details": { "reason": "CAP_REACHED_PAYG_OFF" },
  "hint": "Turn on pay-as-you-go or upgrade the tier."
}

hint is written for you: one sentence naming the next action. Full catalogue: /errors and /errors.json. Handling patterns: Errors and retries.

Paying

Way	Shape	Read
On-chain plan	One depositAndSubscribe call, relayed free of charge, with a price ceiling you set	Buying a plan
x402	HTTP 402 challenge → pay → retry; settle-before-serve	x402
MCP	prepare_subscribe, buy_plan_x402, topup_x402, each running the route it wraps	MCP tools

An important sequencing rule: POST /v1/relay does not accept payments. Its 402 tells you where to pay. Pay first, then sign your payload transaction — a payment at nonce n would kill a payload you signed at nonce n.

Authentication

Ring	How	For
Public	nothing	Pricing, network, status, registry, intent status
Transaction-as-credential	the signed transaction itself	POST /v1/relay
Presence proof	sign corelayer/assign/v1|chainId|sender|serverTimeMs	POST /v1/relay/assign
Native-auth	MultiversX native-auth bearer token	Your own private reads
Sponsor key	X-Api-Key: crk_<env>_… on POST /v1/relay	Paying for other senders, such as every agent an operator runs: server-side only, Agent Pro and Agent Fleet (sponsor mode)
x402	PAYMENT-SIGNATURE header	Purchases

Details and exact message formats: Authentication.

Next

• A runnable end-to-end script: Quickstart
• Every discovery file and what is in it: Discovery
• The typed client: SDK