Skip to main content

MCP tools

The server lists twenty tools, and every one of them runs. Each one wraps one API route (two, where a single answer is more useful than two round trips) and runs it inside the server with your credentials, so the auth ring, the rate limit and the error of a tool are the route's.

Arguments marked ? are optional. Every tool returns the route's response as structured content; a failure returns the problem document instead.

Reading​

get_pricing​

{ "audience": "agent" }   // "human" | "agent", optional

Wraps GET /v1/pricing. Returns tiers, the tariff and its version, pay-as-you-go rates, rate classes and the document version. Amounts are decimal strings — parse them as decimals. Public. Available in the read-only edition.

get_network_status​

{}

Wraps GET /v1/network and GET /v1/status, and returns both as network and status: chain id, contract address, payment token, gas constants, round duration, direct hosts, the native-auth block, contract and swap-venue pause state, and the service state with its open incidents.

Use chainId from here to check every transaction you are about to sign. Public, read-only edition.

list_relayers​

{ "shard": 1 }   // optional

Wraps GET /v1/relayers. The registry as the API mirrors it. Verify an address against the contract before signing a transaction that names it — see getRelayerState. Public, read-only edition.

get_quota​

{ "address": "erd1…" }

Wraps GET /v1/account/{erd}/quota. Tier, cap, units used, period end, pay-as-you-go state. Public — a fleet agent can read the quota of the account sponsoring it without holding its key. Read-only edition.

get_account​

{ "address": "erd1…" }

Wraps GET /v1/account/{erd} plus the first page of /purchases, returned as account and purchases. Plan, credits, flags, authorised senders, recent purchases. Public, read-only edition.

get_tx_status​

{ "txHash": "…" }        // or
{ "intentId": "erd1…:41" }

Wraps GET /v1/relay/{id}, which resolves either form. Returns the full intent: state, whether it is final, the timestamps, the latency breakdown, the gateway acknowledgements, the block, the fee paid and the gas used. Public, read-only edition.

get_usage_history​

{ "fromMs": 1789000000000, "toMs": 1789600000000, "limit": 50, "account": "erd1…" }   // all optional

Wraps GET /v1/usage. One row per relayed transaction, newest first. Private — needs native-auth or a read-scoped key. Read-only edition.

get_notices​

{ "address": "erd1…", "sinceSeq": 17 }   // both optional

Wraps GET /v1/account/{erd}/notices. Without address, it reads the account of the credential you present. Scheduled tariff changes, cap thresholds, draining relayers, renewal outcomes. Poll with sinceSeq rather than walking pages. Private. Read-only edition.

search_docs​

{ "query": "relay unit formula" }

Searches the operations of the API: every route of the OpenAPI document, ranked by how many of your terms its name and path contain, with links to this site and to /llms.txt to read on. The only tool that wraps no API route. Public, read-only edition.

Estimating before committing​

quote_relay​

{ "transaction": { "nonce": 41, "value": "0", "receiver": "erd1…", "sender": "erd1…",
                   "gasPrice": 1000000000, "gasLimit": 150000, "data": "",
                   "chainID": "1", "version": 2 } }

Wraps POST /v1/quote. Returns ru, maxFeeAtto, moveGas, the Relay Unit schedule version, the tariff, the pay-as-you-go price per unit and how it would be billed. The units follow the published formula and vectors. Public, read-only edition.

validate_transaction​

{ "transaction": { /* unsigned or signed */ } }

Wraps POST /v1/validate. Runs the whole relay validation pipeline without a lease, without a reservation and without asking the signer for anything, and returns every problem a real relay would raise, plus ru, simulatedGas, expectedNonce and which account would be billed.

This is the tool to call before spending a signature. Public, read-only edition.

Preparing transactions for you to sign​

These build unsigned transactions. They are public — they grant nothing, because a transaction only matters once you have signed it.

prepare_subscribe​

{ "address": "erd1…", "tierId": 12, "months": 1, "payWith": "credits" }

Wraps POST /v1/subscribe/prepare. Returns a quote, the unsigned transaction with the relayer and gas bounds already set, and a lease. The quote lives 120 seconds and its maxPrice is part of the signed arguments.

prepare_deposit​

{ "address": "erd1…", "amountUsdc": "25", "beneficiary": "erd1…" }

Wraps POST /v1/deposit/prepare. Minimum one USDC.

prepare_set_flags​

{ "address": "erd1…", "payg": true, "autoRenew": false, "releaseEscrow": false, "renew": false }

Wraps POST /v1/flags/prepare. Builds the on-chain call for pay-as-you-go, auto-renew, escrow release or an immediate renewal. Remember that auto-renew requires a non-zero max_renew_price — zero never means unlimited.

prepare_senders​

{ "address": "erd1…", "action": "add", "senders": ["erd1…"] }

Wraps POST /v1/senders/prepare. The result states the fee as feeMicroUsdc, which is the max_fee argument you will be signing. Adding senders costs Relay Units; removing them is free.

Relaying​

get_relayer_for_sender​

{
  "sender": "erd1…",
  "proof": { "kind": "key", "serverTimeMs": 1789000000000, "signature": "…hex…" },  // or "sponsor"
  "renewFor": "erd1…",   // optional: renew the lease for a relayer already in your signed bytes
  "cancelNonce": 41      // optional: a lease for cancelling that nonce
}

Wraps POST /v1/relay/assign. The agent signs the presence-proof message corelayer/assign/v1|<chainId>|<sender>|<serverTimeMs> with its own key — the MCP server never holds one. The signature is a raw Ed25519 signature over the bytes of the message, without the MultiversX message prefix a wallet's signMessage adds, and the sender's key makes it for kind: "key" and kind: "sponsor" alike (the presence proof). Returns the full assignment, lease included, and an instructions string: set relayer before signing, add the relayed-transaction gas, sign once, and verify the relayer's registry state on chain first. (Verify a relayer) Read-only edition.

relay_transaction​

{
  "transaction": { /* signed, `relayer` set, no relayerSignature */ },
  "lease": "…",
  "mode": "normal",                  // "normal" | "cancel" | "replace"
  "account": "erd1…",                // optional: bill this account
  "waitFor": "in_block"              // "accepted" | "in_block" | "finalized"
}

Wraps POST /v1/relay, then reads GET /v1/relay/{id} until the intent reaches the state you asked for, or for at most thirty seconds — after which it returns the last state it read rather than failing.

Sets an idempotency key automatically, one per call.

Signed transaction in the arguments

Do not log the arguments of this tool. The result and every error omit the signed transaction, the signature, the guardian signature and the lease on purpose; the arguments are your host's responsibility. See the MCP overview.

relay_batch​

{ "transactions": [ /* ≤ 16, same sender, consecutive nonces */ ], "lease": "…" }

Several transactions over one multi-use lease, submitted in order, stopping at the first error. The result says how many were relayed and holds each answer in order. There is no REST equivalent, deliberately: one request, one intent keeps every error attributable. The same logging warning applies.

Paying over x402​

buy_plan_x402​

{ "payer": "erd1…", "tierId": 12, "months": 1 }

Wraps POST /v1/x402/purchase. The first call returns the challenge in the tool result, as paymentRequired. Call the tool again with the payment in _meta["x402/payment"]; it is sent to the route as the PAYMENT-SIGNATURE header, and the tool returns the route's answer.

topup_x402​

{ "payer": "erd1…", "amountUsdc": "25", "beneficiary": "erd1…" }

Wraps POST /v1/x402/topup. Same exchange. Minimum one USDC.

Both are settle before serve: the answer arrives when the payment is final and the contract event has been observed — or, if that takes longer than the budget, as a 202 with a payment id to poll. (x402)

Errors​

A tool failure is the problem document, as structured content:

{
  "type": "https://docs.co-relayer.com/errors/quota-exhausted",
  "title": "The plan's included Relay Units are used up.",
  "status": 429,
  "code": "QUOTA_EXHAUSTED",
  "retryable": false,
  "resign": "NONE",
  "hint": "Turn on pay-as-you-go or upgrade the tier."
}

Branch on code; handle an unknown code by status and retryable; only sign again when resign says so. (Errors and retries)

On this page