Skip to main content
Version: 1.0.0-draft.1

CoRelayer API

The CoRelayer HTTP API. The service also serves its API document at /openapi.json, with the same operation ids, schema names, property names and enums.

Conventions:

  • Every time value is Unix milliseconds as a JSON number (*Ms). Seconds appear only where an external standard requires them (Retry-After, RateLimit-Reset, x402 maxTimeoutSeconds).
  • atto-EGLD is always a decimal string (*Atto).
  • Operational endpoints carry micro-USDC (*Micro, *MicroUsdc), RU, gas and gasPrice as JSON integers (all below 2^53). The pricing documents (/v1/pricing, pricing.json, and the quotes of /v1/quote and /v1/subscribe/prepare) carry them as decimal strings.
  • Errors are RFC 9457 application/problem+json with the stable extension member code.
  • One request relays one transaction, and the user signs each transaction once.

Networks: mainnet and devnet staging run the same service and the same contract. Everything that differs between them is configuration: chain id (1 | D), payment token (USDC-c76f1f on mainnet, USDC-350c4e on devnet), contract / pair / wrapper addresses, API host, app origin and API-key environment (live | test). The on-chain part can be read from the contract's getConfig(). Token ids and chain ids in examples are the mainnet values. The contract owner and relayer addresses are the same on both networks. Everything signed or secret that could be replayed on the other network is therefore bound to one environment: leases, quotes, API keys, webhook secrets and ops flags (chainId + env inside the signed flag).

There are two API hosts, and each accepts what the other issued: quotes are stateless MACs, and x402 payment identifiers and logical idempotency keys are kept in a shared database.

Authentication​

Authorization: Bearer <address>.<body>.<signature> (MultiversX native-auth). Allowed origins: https://app.co-relayer.com, and the fixed string https://agent.co-relayer.com for headless agents (staging accepts the devnet equivalents). The token TTL is at most 3 600 s. On browser calls the HTTP Origin header must equal the origin in the token. Tokens with impersonate or multisig are refused. The token is never accepted in a URL. The block hash in the token must be a shard-1 block from the last 7 200 s. Headless agents can take one from GET /v1/network -> nativeAuth. Any other hash is answered with 401 TOKEN_INVALID and details.expectedShard = 1.

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

MultiversX-NativeAuth

License

MIT