{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "CoRelayer API", "version": "1.0.0-draft.1", "summary": "Gasless Relayed-V3 transaction service on MultiversX - native API, compat facade, x402 purchase flow and dashboard read models.", "description": "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.\n\nConventions:\n- Every time value is Unix **milliseconds** as a JSON number (`*Ms`). Seconds appear only where an\n external standard requires them (`Retry-After`, `RateLimit-Reset`, x402 `maxTimeoutSeconds`).\n- atto-EGLD is always a decimal string (`*Atto`).\n- Operational endpoints carry micro-USDC (`*Micro`, `*MicroUsdc`), RU, gas and gasPrice as JSON\n integers (all below 2^53). The pricing documents (`/v1/pricing`, `pricing.json`, and the quotes of\n `/v1/quote` and `/v1/subscribe/prepare`) carry them as decimal strings.\n- Errors are RFC 9457 `application/problem+json` with the stable extension member `code`.\n- One request relays one transaction, and the user signs each transaction once.\n\nNetworks: mainnet and devnet staging run the same service and the same contract. Everything that\ndiffers between them is configuration: chain id (`1` | `D`), payment token (`USDC-c76f1f` on mainnet,\n`USDC-350c4e` on devnet), contract / pair / wrapper addresses, API host, app origin and API-key\nenvironment (`live` | `test`). The on-chain part can be read from the contract's `getConfig()`.\nToken ids and chain ids in examples are the mainnet values.\nThe contract owner and relayer addresses are the same on both networks. Everything signed or secret that\ncould be replayed on the other network is therefore bound to one environment: leases, quotes, API\nkeys, webhook secrets and ops flags (`chainId` + `env` inside the signed flag).\n\nThere are two API hosts, and each accepts what the other issued: quotes are stateless MACs, and x402\npayment identifiers and logical idempotency keys are kept in a shared database.\n", "termsOfService": "https://co-relayer.com/terms", "contact": { "name": "CoRelayer", "url": "https://co-relayer.com", "email": "support@co-relayer.com" }, "license": { "name": "MIT", "identifier": "MIT" } }, "servers": [ { "url": "https://api.co-relayer.com", "description": "MultiversX mainnet (chainID \"1\")" }, { "url": "https://devnet-api.co-relayer.com", "description": "Devnet staging (chainID \"D\"). It runs the same service and wallets as mainnet and swaps through the\nreal devnet xExchange venue.\n" } ], "tags": [ { "name": "meta", "description": "Health, discovery documents, network parameters." }, { "name": "relay", "description": "Native relay API (assign, relay, intent status, per-intent SSE)." }, { "name": "pricing", "description": "Machine-readable pricing and quotes." }, { "name": "purchase", "description": "Builders of unsigned contract calls (deposit, subscribe, flags, senders)." }, { "name": "x402", "description": "x402 v2 purchase flow, paymentFlow \"upfront\"." }, { "name": "registry", "description": "Off-chain mirror of the on-chain relayer registry (convenience, not authority)." }, { "name": "status", "description": "Component status and incident feed." }, { "name": "account", "description": "Public mirror of on-chain account state plus the derived quota." }, { "name": "dashboard", "description": "Private read models of an account (usage, latency, notices, served-by relayers, outages)." }, { "name": "keys", "description": "Sponsor API keys." }, { "name": "notifications", "description": "Webhooks, e-mail preferences, SSE stream." }, { "name": "compat", "description": "Drop-in facade for OpenClaw / Moltbot starter-kit agents. Unversioned and frozen." } ], "security": [], "paths": { "/healthz": { "get": { "tags": [ "meta" ], "operationId": "getHealthz", "summary": "Liveness of the API process.", "x-corelayer-auth": [ "public" ], "responses": { "200": { "description": "Process is alive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/readyz": { "get": { "tags": [ "meta" ], "operationId": "getReadyz", "summary": "Whether this API host is ready to take traffic. It reports not ready while the host restores its state after a restart.", "x-corelayer-auth": [ "public" ], "responses": { "200": { "description": "Ready to take traffic.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/openapi.json": { "get": { "tags": [ "meta" ], "operationId": "getOpenApi", "summary": "The API's OpenAPI description, as JSON.", "x-corelayer-auth": [ "public" ], "responses": { "200": { "description": "OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/x402": { "get": { "tags": [ "meta", "x402" ], "operationId": "getX402Descriptor", "summary": "x402 resource descriptor at the conventional well-known path.", "x-corelayer-auth": [ "public" ], "responses": { "200": { "description": "Descriptor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Descriptor" } } } } } } }, "/v1/network": { "get": { "tags": [ "meta" ], "operationId": "getNetwork", "summary": "Chain parameters the client needs to build a transaction, swap-venue state, measured latency per shard.", "description": "Chain constants are re-read from the gateway's `/network/config` every epoch. Latency figures are\nmeasured values only; nothing is estimated.\n`nativeAuth` carries a recent **shard-1** block hash for headless agents. A native-auth token must\nembed a shard-1 block hash, because the API checks it against its own record of recent shard-1 blocks\nwithout calling a gateway.\n`contractPause` reflects the contract's `getPauseState()` and `swapVenue` reflects the exchange venue.\nThey are separate conditions with separate error codes: `CONTRACT_PAUSED` and `SWAP_VENUE_PAUSED`.\n", "x-corelayer-auth": [ "public" ], "responses": { "200": { "description": "Network view.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Network" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/relay/assign": { "post": { "tags": [ "relay" ], "operationId": "assignRelayer", "summary": "Assign one relayer in the sender's shard and issue a lease. Nothing is reserved yet.", "description": "Call it just before the user signs: the relayer address goes into the transaction, so the user signs\nonce. `renewFor` renews the lease for a transaction that is already signed, so a slow signer does not\nhave to sign again. `cancel` returns a lease for a cancel transaction, pinned to that nonce.\nRate limits: 10/s per IP, and 2/s per sender with a burst of 10.\n\nThe caller must prove it controls the sender, in one of two ways:\n- a presence proof: the sender's own key signs the message\n `corelayer/assign/v1|||`, where `serverTimeMs` is within\n +/- 30 000 ms of the server clock. The signature is a raw Ed25519 signature over the UTF-8 bytes of the\n message, without the MultiversX signed-message prefix that a wallet's `signMessage` adds. Set\n `proof.kind` to `sponsor` when a sponsor API key will pay for the relay, and to `key` otherwise. The\n sender's key signs both kinds;\n- a native-auth bearer token whose address equals `sender`.\n\nThis route does not read `X-Api-Key`, and a sponsor API key never proves presence: it goes on\n`POST /v1/relay`, where it selects the account that pays.\n\nA missing proof gives `401 ASSIGN_PROOF_REQUIRED`; a bad or stale one gives `401 ASSIGN_PROOF_INVALID`.\nThe prepare routes of the free purchase flow issue their own `FREE` lease and need no proof.\n", "x-corelayer-auth": [ "presence-proof", "native-auth" ], "security": [ {}, { "nativeAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignRequest" } } } }, "responses": { "200": { "description": "Assignment.", "headers": { "CoRelayer-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "`ASSIGN_PROOF_REQUIRED` or `ASSIGN_PROOF_INVALID` (`details.serverTimeMs` = signer clock), or a token error of the `Unauthorized` class.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`RESIGN_REQUIRED` (renewFor relayer no longer renewable) or `NOTHING_TO_CANCEL`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "`NO_RELAYER_AVAILABLE`, `SIGNER_UNAVAILABLE` or `SIGNER_FENCED`; carries `Retry-After`.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/relay": { "post": { "tags": [ "relay" ], "operationId": "relayTransaction", "summary": "Submit one user-signed Relayed-V3 transaction for co-signing and broadcast.", "description": "The idempotency key is `(tx.sender, tx.nonce)` plus the SHA-256 of the canonical signing bytes.\nPosting the same bytes again returns the stored response with `duplicate: true` and never creates a\nsecond reservation or a second broadcast. Unknown body members are rejected. `variants`,\n`transactions` and `alternates` give `VARIANTS_NOT_SUPPORTED`: one request carries one transaction,\nsigned once.\nOnce the transaction is co-signed (state `COSIGNED`), the answer is always 200 or 202.\nAuthentication: the signed transaction is the credential when the sender has an account or is an\nauthorised sender on chain. Relaying for arbitrary senders needs a sponsor API key.\n\nOptional **logical idempotency key** (header `Idempotency-Key` or body member `intentKey`; if you send\nboth, the header is used). It is stored per `(sender, key)` for\n86 400 000 ms. The same key with different bytes or a different nonce, while the first intent is not\n`DEAD`, gives `409 INTENT_ALREADY_SUBMITTED` carrying the first intent. After `DEAD` the key is free\nagain. The same key with the same bytes is an ordinary replay. The key can only reject a request, so\nit never contradicts the idempotency key above. Send one key per user action, so that a retry after a\ntimeout cannot relay the same action twice.\n\nFree relays: a short list of calls to the CoRelayer contract is relayed free of charge. `GET /v1/pricing`\npublishes it as `howToBuy.freeOperations`. A free call to the contract while it is paused (`paused` or\n`deposits_paused`, sender is not the owner) gives `503 CONTRACT_PAUSED` before anything is co-signed.\n", "x-corelayer-auth": [ "tx", "sponsor-key" ], "security": [ {}, { "sponsorKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayRequest" } } } }, "responses": { "200": { "description": "Co-signed and acknowledged by at least one gateway (state BROADCAST or later).", "headers": { "CoRelayer-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayResponse" } } } }, "202": { "description": "Co-signed, no gateway acknowledgement within 800 ms (state COSIGNED). Re-broadcast continues server-side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`NO_ENTITLEMENT`. Carries a `PAYMENT-REQUIRED` header that points at `POST /v1/x402/topup`.", "headers": { "PAYMENT-REQUIRED": { "$ref": "#/components/headers/PaymentRequired" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "description": "`RELAYER_RETIRED` (only when no lease flow exists; otherwise `RESIGN_REQUIRED`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/relay/{id}": { "get": { "tags": [ "relay" ], "operationId": "getRelay", "summary": "Intent status by intent id (`:`) or by transaction hash.", "description": "Resolver in front of `GET /v1/intents/{sender}/{nonce}` (authoritative) and `GET /v1/tx/{hash}`. Same response schema.", "x-corelayer-auth": [ "public" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Intent id `erd1...:41` or a 64-hex transaction hash.", "schema": { "oneOf": [ { "$ref": "#/components/schemas/IntentId" }, { "$ref": "#/components/schemas/TxHash" } ] } } ], "responses": { "200": { "description": "Intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intent" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/relay/{id}/events": { "get": { "tags": [ "relay" ], "operationId": "streamRelay", "summary": "Server-sent events for one intent until it is terminal and final, or 120 000 ms elapsed.", "description": "Event name `intent`, data = `Intent`. `id:` is the per-intent sequence. The server closes the\nstream after the first event with `final: true`, after a terminal `DEAD`/`REJECTED`, or after\n120 000 ms (the client then falls back to polling `GET /v1/relay/{id}`).\n", "x-corelayer-auth": [ "public" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/IntentId" }, { "$ref": "#/components/schemas/TxHash" } ] } }, { "$ref": "#/components/parameters/LastEventId" } ], "responses": { "200": { "description": "Event stream.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/intents/{sender}/{nonce}": { "get": { "tags": [ "relay" ], "operationId": "getIntent", "summary": "Authoritative, cross-host intent status keyed by (sender, nonce).", "x-corelayer-auth": [ "public" ], "parameters": [ { "name": "sender", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "nonce", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intent" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/tx/{hash}": { "get": { "tags": [ "relay" ], "operationId": "getTx", "summary": "Convenience lookup by transaction hash. Terminal state is still decided by (sender, nonce) and chain facts.", "x-corelayer-auth": [ "public" ], "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TxHash" } } ], "responses": { "200": { "description": "Intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intent" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/quote": { "post": { "tags": [ "relay", "pricing" ], "operationId": "quoteRelay", "summary": "RU weight and price of a transaction (signed or unsigned). No reservation, no signer call.", "x-corelayer-auth": [ "public" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRelayRequest" } } } }, "responses": { "200": { "description": "Relay quote (pricing-family types, decimal strings).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayQuote" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/validate": { "post": { "tags": [ "relay" ], "operationId": "validateTransaction", "summary": "Run the relay checks (static checks, signatures, account and nonce, simulation) without a lease, a reservation or a co-signature.", "description": "Backs the MCP tool `validate_transaction`. Rate limit 2/s per IP because it may trigger a gateway simulation.", "x-corelayer-auth": [ "public" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateRequest" } } } }, "responses": { "200": { "description": "Validation report. `ok=false` lists the problems that `POST /v1/relay` would return.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/pricing": { "get": { "tags": [ "pricing" ], "operationId": "getPricing", "summary": "Live machine-readable pricing document (contract views, cache <= 6 000 ms).", "description": "The same document as the static file `https://co-relayer.com/pricing.json` and the MCP resource\n`corelayer://pricing`. Its complete JSON Schema is `https://co-relayer.com/schemas/pricing-v1.json`.\nMoney, RU, gas and atto values are decimal strings here.\n", "x-corelayer-auth": [ "public" ], "parameters": [ { "name": "audience", "in": "query", "description": "Filter `tiers[]` by audience.", "schema": { "type": "string", "enum": [ "human", "agent" ] } } ], "responses": { "200": { "description": "Pricing document.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingDocument" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/pricing/tariff-history": { "get": { "tags": [ "pricing" ], "operationId": "getTariffHistory", "summary": "Append-only tariff history mirrored from the contract view `getTariffHistory`.", "x-corelayer-auth": [ "public" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Page of tariff entries, newest first.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TariffEntry" } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/subscribe/prepare": { "post": { "tags": [ "purchase" ], "operationId": "prepareSubscribe", "summary": "Quote a plan purchase and build the unsigned contract call with a relayer and lease pre-filled.", "description": "Returns a price quote (valid for 120 000 ms, `maxPrice == priceMicroUsdc`), one unsigned transaction\n(`depositAndSubscribe` when USDC must be paid, `subscribe` when credits cover the price) and the\nassignment to submit it with. The purchase transaction is relayed free of charge.\nThe quote is **stateless**: `quoteMac` is an HMAC over its canonical JSON, and `quoteId` is derived\nfrom the MAC. The same inputs inside one TTL bucket give the same id on either API host, and nothing\nis stored. `503 CONTRACT_PAUSED` while the CoRelayer contract is paused (it is deployed paused), and\n`503 SWAP_VENUE_PAUSED` while the exchange venue is paused. Nothing is built in either case.\n", "x-corelayer-auth": [ "public" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareSubscribeRequest" } } } }, "responses": { "200": { "description": "Quote + unsigned transaction + assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedPurchase" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/deposit/prepare": { "post": { "tags": [ "purchase" ], "operationId": "prepareDeposit", "summary": "Build the unsigned `deposit` / `depositFor` call (USDC -> credits).", "x-corelayer-auth": [ "public" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareDepositRequest" } } } }, "responses": { "200": { "description": "Unsigned transaction + assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedTransaction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/flags/prepare": { "post": { "tags": [ "purchase" ], "operationId": "prepareSetFlags", "summary": "Build unsigned `setAutoRenew`, `setPayg` or `releaseEscrow` calls for an existing account (relayed free within the flag-call limits).", "description": "Flag calls are relayed free of charge, up to 10 per 24 h and 30 per 30 days per account.\n`setPayg` is encoded with four arguments: `enabled, budget, auto_topup, max_payg_price`.\n`renew: true` builds `renew(address)`, the dashboard's \"Renew now\". It is free only when the argument\nis the sender's own account, so `address` is both the sender and the argument.\nWhen the free allowance is used up, the response carries `free: false` and `ru`, and the call is\nbilled as a normal relay. An address that cannot be billed gets `429 RATE_LIMITED` with\n`details.scope = free_flow`.\n`503 CONTRACT_PAUSED` while the contract's global pause is set.\n", "x-corelayer-auth": [ "public" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareFlagsRequest" } } } }, "responses": { "200": { "description": "One unsigned transaction per requested change, consecutive nonces, one assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedTransactions" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "`NO_ENTITLEMENT` (details.reason NO_ACCOUNT) - flag calls are co-signed only for addresses that already have an on-chain account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/senders/prepare": { "post": { "tags": [ "purchase" ], "operationId": "prepareSenders", "summary": "Build unsigned `addSenders` / `removeSenders` calls.", "description": "`addSenders` is **never** relayed free. It is billed to the account as a normal relay and carries the\non-chain per-sender fee, which makes mass-creating senders expensive. `removeSenders` has no fee and\nis relayed free: it is how a payer cuts off a compromised sender key. The response members `free`,\n`ru` and `feeMicroUsdc` say which case applies; show them instead of working the rule out yourself.\n\n`addSenders(max_fee, senders...)`: the route fills the first argument `max_fee` with the quoted fee,\nso `PreparedTransaction.feeMicroUsdc` **equals** `contractCall.args[0]`. It is the ceiling the user\nsigns. A higher on-chain fee at execution reverts with `ERR_PRICE_ABOVE_MAX`, reported as\n`409 PRICE_ABOVE_MAX`. An increase of `sender_fee_ru` takes effect only 172 800 000 ms after it is set\n(`SENDER_FEE_NOTICE_MS`). `GET /v1/pricing` does not publish a pending `sender_fee_ru`: the fee this route quotes in `feeMicroUsdc` is the one in force when it answers, and it is the ceiling the user signs.\n", "x-corelayer-auth": [ "public" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareSendersRequest" } } } }, "responses": { "200": { "description": "Unsigned transaction + assignment + fee preview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedTransaction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/x402/supported": { "get": { "tags": [ "x402" ], "operationId": "getX402Supported", "summary": "x402 v2 `supported` document - kinds, extensions and `signers` (our active relayers per CAIP-2 pattern).", "x-corelayer-auth": [ "public" ], "responses": { "200": { "description": "Supported kinds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Supported" } } } } } } }, "/v1/x402/topup": { "post": { "tags": [ "x402" ], "operationId": "x402Topup", "summary": "x402 v2 purchase of credits (`deposit` / `depositFor`). Unpaid request -> 402 challenge, paid retry -> settle before serve.", "description": "These rules hold on both API hosts, and the same rules apply to `/v1/x402/purchase`:\n- `accepted` is verified by **recomputing `extra.quoteMac`**, never by a lookup, because the challenge\n may have been issued by the other API host.\n- The payment record keyed by `extensions[\"payment-identifier\"].id` is written to the database\n **before** anything is co-signed. If the database is unreachable the answer is\n `503 UPSTREAM_UNAVAILABLE` and nothing is co-signed. The same id with the same payload returns the\n stored result; the same id with another payload gives `402 PAYMENT_INVALID`.\n- `503 CONTRACT_PAUSED` / `503 SWAP_VENUE_PAUSED` are answered before any co-signature.\n- `asset`, `network` and `payTo` are the values of the serving network (`USDC-c76f1f` / `multiversx:1`\n on mainnet, `USDC-350c4e` / `multiversx:D` on devnet staging).\n", "x-corelayer-auth": [ "x402" ], "parameters": [ { "$ref": "#/components/parameters/PaymentSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402TopupRequest" } } } }, "responses": { "200": { "description": "Payment executed successfully on chain and the `deposit` event was mirrored.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PurchaseResult" } } } }, "202": { "description": "Co-signed and broadcast, completion exceeds the HTTP budget (8 000 ms). Poll `GET /v1/x402/payments/{paymentId}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Pending" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/x402/purchase": { "post": { "tags": [ "x402" ], "operationId": "x402Purchase", "summary": "x402 v2 purchase of a plan in one payment (`depositAndSubscribe(tier_id, months, max_price, ref)`).", "description": "The beneficiary is always the payer (contract rule). `ref` = the quote id, bound under the payer's\nsignature. Quote verification, payment-identifier persistence and the pause answers follow the\ncross-host rules listed under `POST /v1/x402/topup`.\n", "x-corelayer-auth": [ "x402" ], "parameters": [ { "$ref": "#/components/parameters/PaymentSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PurchaseRequest" } } } }, "responses": { "200": { "description": "Payment executed and `subscribed` event mirrored.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PurchaseResult" } } } }, "202": { "description": "Pending, poll.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Pending" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/x402/payments/{paymentId}": { "get": { "tags": [ "x402" ], "operationId": "getX402Payment", "summary": "Poll a pending x402 payment by its `payment-identifier`.", "x-corelayer-auth": [ "public" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128 } } ], "responses": { "200": { "description": "Final result (success or failure); `PAYMENT-RESPONSE` header is set.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PurchaseResult" } } } }, "202": { "description": "Still pending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Pending" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/relayers": { "get": { "tags": [ "registry" ], "operationId": "listRelayers", "summary": "Off-chain mirror of the relayer registry. Balances are never exposed here.", "description": "The contract view `getRelayerState` is the authority. Agents should verify a relayer through a gateway that CoRelayer does not run (https://docs.co-relayer.com/concepts/verify-a-relayer).", "x-corelayer-auth": [ "public" ], "parameters": [ { "name": "shard", "in": "query", "schema": { "$ref": "#/components/schemas/Shard" } }, { "name": "state", "in": "query", "schema": { "$ref": "#/components/schemas/RelayerStateName" } } ], "responses": { "200": { "description": "Registry mirror.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayerRegistry" } } } } } } }, "/v1/relayers/{address}": { "get": { "tags": [ "registry" ], "operationId": "getRelayerPublic", "summary": "One relayer with its state history and public service statistics.", "x-corelayer-auth": [ "public" ], "parameters": [ { "$ref": "#/components/parameters/RelayerAddress" } ], "responses": { "200": { "description": "Relayer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayerPublicDetail" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/status": { "get": { "tags": [ "status" ], "operationId": "getStatus", "summary": "Component status, measured latency per shard, 90-day daily availability, float status label per shard, open incidents.", "description": "The same document is published every 60 000 ms as `https://status.co-relayer.com/feed/status.json`.\nNext to it are `/feed/incidents.json` (the first page of `GET /v1/incidents`) and\n`/feed/telemetry.json` (`latency30d` + `availabilityDaily90`). They are three files because they have\ndifferent cache lifetimes, and the status page renders each one on its own.\nSynthetic probe traffic is excluded from every public counter. Percentages are measured over past\ntraffic and carry no service-level guarantee.\n`floatPerShard` is a status label, never a balance.\n", "x-corelayer-auth": [ "public" ], "responses": { "200": { "description": "Status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } } } }, "/v1/incidents": { "get": { "tags": [ "status" ], "operationId": "listIncidents", "summary": "Public incident feed, newest first.", "x-corelayer-auth": [ "public" ], "parameters": [ { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" }, { "name": "shard", "in": "query", "schema": { "$ref": "#/components/schemas/Shard" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/IncidentStatus" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Page of incidents.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/incidents/{incidentId}": { "get": { "tags": [ "status" ], "operationId": "getIncident", "summary": "One public incident with all updates.", "x-corelayer-auth": [ "public" ], "parameters": [ { "$ref": "#/components/parameters/IncidentId" } ], "responses": { "200": { "description": "Incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/me": { "get": { "tags": [ "account", "dashboard" ], "operationId": "getMe", "summary": "The accounts the token's address can open in the dashboard.", "description": "Lists the accounts the token's address owns or is an authorised sender of. Each account's `role` picks\nthe full dashboard (`role: owner`) or the read-only authorised-sender mode (`role: sender`).\n", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "responses": { "200": { "description": "Identity view of the token address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/account/{erd}": { "get": { "tags": [ "account" ], "operationId": "getAccount", "summary": "Mirror of the on-chain account record (credits, escrow, plan blocks, flags). Pure chain mirror, therefore public.", "x-corelayer-auth": [ "public" ], "parameters": [ { "$ref": "#/components/parameters/Erd" } ], "responses": { "200": { "description": "Account mirror.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/{erd}/quota": { "get": { "tags": [ "account" ], "operationId": "getQuota", "summary": "Derived service state of an account (\"halted\" lives here, never on-chain). Evaluated in shard-1 chain time.", "description": "`{erd}` may also be an authorised sender. The response then describes the account that would be\nbilled for that sender, and `resolvedFrom` says how that account was found.\n", "x-corelayer-auth": [ "public" ], "parameters": [ { "$ref": "#/components/parameters/Erd" } ], "responses": { "200": { "description": "Quota. An address without an account answers 200 with `state = NO_ACCOUNT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quota" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/account/{erd}/senders": { "get": { "tags": [ "account" ], "operationId": "listSenders", "summary": "On-chain authorised senders of the account (mirror of `senderAdded` / `senderRemoved`).", "x-corelayer-auth": [ "public" ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Page of senders, oldest authorisation first (the serving order).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuthorizedSender" } } } } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/{erd}/purchases": { "get": { "tags": [ "account", "dashboard" ], "operationId": "listPurchases", "summary": "Money timeline of the account - deposits, plan purchases, renewals, skipped renewals, escrow moves, PAYG settlements, sender fees, grants.", "description": "Built only from finalised contract events, so it is public. Newest first.", "x-corelayer-auth": [ "public" ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "name": "kind", "in": "query", "description": "Comma-separated filter.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseKind" } }, "style": "form", "explode": false }, { "$ref": "#/components/parameters/Format" }, { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Page of purchase events (`format=csv` streams all matching rows without a cursor).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseEvent" } } } } ] } }, "text/csv": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/{erd}/notices": { "get": { "tags": [ "dashboard", "notifications" ], "operationId": "listNotices", "summary": "Pollable notices - account notices plus global ones (tariff, RU schedule, incidents).", "x-corelayer-auth": [ "native-auth", "sponsor-key" ], "security": [ { "nativeAuth": [] }, { "sponsorKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "name": "sinceSeq", "in": "query", "description": "Return notices with `seq` greater than this value (agents poll with the last seen seq).", "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "unacknowledged", "in": "query", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Page of notices, newest first.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Notice" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/account/{erd}/notices/ack": { "post": { "tags": [ "dashboard", "notifications" ], "operationId": "ackNotices", "summary": "Acknowledge notices up to a sequence number (idempotent).", "x-corelayer-auth": [ "native-auth", "sponsor-key" ], "security": [ { "nativeAuth": [] }, { "sponsorKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "upToSeq" ], "properties": { "upToSeq": { "type": "integer", "format": "int64", "minimum": 0 } } } } } }, "responses": { "204": { "description": "Acknowledged." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/account/{erd}/relayers": { "get": { "tags": [ "dashboard" ], "operationId": "listServingRelayers", "summary": "\"Their relayers\" under just-in-time assignment = the relayers that served this account, with counts and on-chain state.", "x-corelayer-auth": [ "native-auth", "sponsor-key" ], "security": [ { "nativeAuth": [] }, { "sponsorKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" } ], "responses": { "200": { "description": "Relayers that served the account in the window (default last 30 days).", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "fromMs", "toMs" ], "properties": { "fromMs": { "$ref": "#/components/schemas/TimestampMs" }, "toMs": { "$ref": "#/components/schemas/TimestampMs" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ServingRelayer" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/account/{erd}/outages": { "get": { "tags": [ "dashboard" ], "operationId": "listAccountOutages", "summary": "Public incidents that overlapped the account's traffic, with the account's own impact numbers.", "x-corelayer-auth": [ "native-auth", "sponsor-key" ], "security": [ { "nativeAuth": [] }, { "sponsorKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Page of outages.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AccountOutage" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/usage": { "get": { "tags": [ "dashboard" ], "operationId": "listUsage", "summary": "Full transaction history of an account - every terminal intent incl. `DEAD` - with per-transaction latency breakdown in ms.", "description": "The account's transaction history, one row per transaction hash. It holds **every terminal intent,\nincluding `DEAD` ones** (with `deadReason`). `billed` says whether the transaction was billed; the\nbilling members are null when it was not.\nRows are keyed by transaction hash. A `DEAD` intent that was replaced by a cancel or a re-sign shares\nits `(sender, senderNonce)` slot with the replacement that executed, and only the executed one is\nbilled. The replaced transaction stays in the history with `status: dead` and `billed: false`.\n`includeInFlight=true` puts the account's non-terminal intents first (flagged `inFlight`), plus the\n`REJECTED` submissions of the last 30 days (`state: REJECTED`, `rejectCode`, never a signature).\nOrder: `executedBlockTsMs` descending (the terminal timestamp for rows without a block), then `txHash`.\n", "x-corelayer-auth": [ "native-auth", "sponsor-key" ], "security": [ { "nativeAuth": [] }, { "sponsorKey": [] } ], "parameters": [ { "name": "account", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "sender", "in": "query", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "relayer", "in": "query", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "status", "in": "query", "description": "Comma-separated terminal statuses (`dead` = terminal without execution, never billed).", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UsageStatus" } }, "style": "form", "explode": false }, { "name": "state", "in": "query", "description": "Comma-separated intent states; only meaningful with `includeInFlight=true` (in-flight and `REJECTED` rows).", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IntentState" } }, "style": "form", "explode": false }, { "name": "shard", "in": "query", "description": "Comma-separated sender shards.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Shard" } }, "style": "form", "explode": false }, { "name": "minInclusionMs", "in": "query", "description": "Only rows whose `latency.inclusionMs` is at least this value (slow-transaction filter).", "schema": { "type": "integer", "minimum": 0 } }, { "name": "q", "in": "query", "description": "Prefix match on `txHash`, `sender`, `receiver` or `function` (3 to 64 characters, treated as text).", "schema": { "type": "string", "minLength": 3, "maxLength": 64 } }, { "name": "billingClass", "in": "query", "schema": { "$ref": "#/components/schemas/BillingClass" } }, { "name": "periodId", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "apiKeyId", "in": "query", "schema": { "type": "string" } }, { "name": "includeInFlight", "in": "query", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/Format" }, { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Page of usage rows.", "headers": { "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRow" } } } } ] } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/usage/summary": { "get": { "tags": [ "dashboard" ], "operationId": "getUsageSummary", "summary": "Usage versus cap - period totals plus a bucketed time series (RU, tx count, fail count, latency percentiles), top senders and receivers.", "description": "RU and money totals count **billed rows only** (`billed = true`). `DEAD` and `REJECTED` rows appear\nin `totals.txCountByStatus` and nowhere else, so the totals always equal the sum of the\n`GET /v1/usage` rows with `billed = true`.\nGrouped latency analytics are served by `GET /v1/usage/latency`.\n", "x-corelayer-auth": [ "native-auth", "sponsor-key" ], "security": [ { "nativeAuth": [] }, { "sponsorKey": [] } ], "parameters": [ { "name": "account", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "periodId", "in": "query", "description": "Default = current period.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "bucket", "in": "query", "schema": { "type": "string", "enum": [ "hour", "day" ], "default": "day" } }, { "$ref": "#/components/parameters/FromMs" }, { "$ref": "#/components/parameters/ToMs" } ], "responses": { "200": { "description": "Summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/usage/latency": { "get": { "tags": [ "dashboard" ], "operationId": "getUsageLatency", "summary": "Latency analytics of an account - percentiles, server-side histogram bins and sampled points per group (shard, relayer, sender or gateway).", "description": "Served from pre-aggregated per-minute and per-hour latency histograms, grouped by `relayer`, `sender`\nor `first_ack_gateway`. `samples[]` holds at most 48 sampled points per group, for a strip plot.\nOnly measured values are returned: a group without data is absent, never estimated. Synthetic probes\nare excluded.\n", "x-corelayer-auth": [ "native-auth", "sponsor-key" ], "security": [ { "nativeAuth": [] }, { "sponsorKey": [] } ], "parameters": [ { "name": "account", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "window", "in": "query", "description": "Look-back window ending now. `1h` and `24h` read the 1-minute rollup, `7d` and `30d` the 1-hour rollup.", "schema": { "type": "string", "enum": [ "1h", "24h", "7d", "30d" ], "default": "24h" } }, { "name": "groupBy", "in": "query", "schema": { "type": "string", "enum": [ "shard", "relayer", "sender", "gateway" ], "default": "shard" } } ], "responses": { "200": { "description": "Grouped latency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageLatency" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/usage/{txHash}": { "get": { "tags": [ "dashboard" ], "operationId": "getUsageRow", "summary": "One row of the transaction history: the billing details when it was billed, the latency breakdown, the settlement batch and the gateway acknowledgements.", "x-corelayer-auth": [ "native-auth", "sponsor-key" ], "security": [ { "nativeAuth": [] }, { "sponsorKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/TxHashPath" } ], "responses": { "200": { "description": "Usage row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageRow" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/usage/{txHash}/proof": { "get": { "tags": [ "dashboard" ], "operationId": "getUsageProof", "summary": "Merkle inclusion proof of a ledger row against the on-chain `usage_root` of its settlement batch.", "x-corelayer-auth": [ "native-auth", "sponsor-key" ], "security": [ { "nativeAuth": [] }, { "sponsorKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/TxHashPath" } ], "responses": { "200": { "description": "Proof. Verifiable with SHA-256 only, against the `usageSettled` event of `batchId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageProof" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Row exists but is not yet committed in a root (next root-only batch is at most 3 600 000 ms away).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/account/{erd}/keys": { "get": { "tags": [ "keys" ], "operationId": "listApiKeys", "summary": "Sponsor API keys of the account (secrets are never returned again).", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" } ], "responses": { "200": { "description": "Keys.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "keys" ], "operationId": "createApiKey", "summary": "Mint a sponsor API key. The secret is shown exactly once.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreate" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/v1/account/{erd}/keys/{keyId}": { "patch": { "tags": [ "keys" ], "operationId": "updateApiKey", "summary": "Change label or policy of a key.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/KeyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyUpdate" } } } }, "responses": { "200": { "description": "Updated key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } }, "delete": { "tags": [ "keys" ], "operationId": "revokeApiKey", "summary": "Revoke a key. Effective on every host within 2 000 ms; in-flight reservations complete and bill the account.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/KeyId" } ], "responses": { "204": { "description": "Revoked." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/{erd}/webhooks": { "get": { "tags": [ "notifications" ], "operationId": "listWebhooks", "summary": "Webhook endpoints of the account.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" } ], "responses": { "200": { "description": "Webhooks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "notifications" ], "operationId": "createWebhook", "summary": "Register an HTTPS webhook endpoint. The signing secret is shown exactly once.", "description": "The URL must use https on port 443 and resolve to a public unicast address, which is checked again on every connection. Redirects are not followed. Any other URL gives `WEBHOOK_URL_NOT_ALLOWED`.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { "201": { "description": "Created, includes `secret`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/v1/account/{erd}/webhooks/{webhookId}": { "get": { "tags": [ "notifications" ], "operationId": "getWebhook", "summary": "One webhook endpoint.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "Webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "notifications" ], "operationId": "updateWebhook", "summary": "Change URL, event types or enabled flag.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/WebhookId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } } }, "responses": { "200": { "description": "Updated webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } }, "delete": { "tags": [ "notifications" ], "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/{erd}/webhooks/{webhookId}/test": { "post": { "tags": [ "notifications" ], "operationId": "testWebhook", "summary": "Send a signed `webhook.test` event now and return the delivery result.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "Delivery attempt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/account/{erd}/webhooks/{webhookId}/rotate-secret": { "post": { "tags": [ "notifications" ], "operationId": "rotateWebhookSecret", "summary": "Issue a new signing secret. The old secret stays valid for 86 400 000 ms; deliveries carry both signatures meanwhile.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "New secret, shown once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/{erd}/webhooks/{webhookId}/deliveries": { "get": { "tags": [ "notifications" ], "operationId": "listWebhookDeliveries", "summary": "Delivery log of the last 30 days, newest first.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" }, { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Page of deliveries.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/{erd}/notifications": { "get": { "tags": [ "notifications" ], "operationId": "getNotificationPrefs", "summary": "Notification preferences (thresholds, e-mail channel, per-kind switches).", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" } ], "responses": { "200": { "description": "Preferences.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPrefs" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "put": { "tags": [ "notifications" ], "operationId": "putNotificationPrefs", "summary": "Replace notification preferences. A new e-mail address stays `pending` until its verification link is opened.", "x-corelayer-auth": [ "native-auth" ], "security": [ { "nativeAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Erd" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPrefsUpdate" } } } }, "responses": { "200": { "description": "Stored preferences.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPrefs" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/v1/stream/tickets": { "post": { "tags": [ "notifications" ], "operationId": "createStreamTicket", "summary": "Single-use ticket for clients that cannot send an Authorization header (native EventSource). TTL 30 000 ms.", "x-corelayer-auth": [ "native-auth", "sponsor-key" ], "security": [ { "nativeAuth": [] }, { "sponsorKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "account" ], "properties": { "account": { "$ref": "#/components/schemas/Address" }, "topics": { "type": "array", "items": { "$ref": "#/components/schemas/StreamTopic" } } } } } } }, "responses": { "201": { "description": "Ticket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ticket", "expiresAtMs" ], "properties": { "ticket": { "type": "string" }, "expiresAtMs": { "$ref": "#/components/schemas/TimestampMs" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/stream": { "get": { "tags": [ "notifications", "dashboard" ], "operationId": "streamAccount", "summary": "Server-sent events for one account (intents, quota, account mirror, notices, incidents, pricing).", "description": "Auth: send the `Authorization` header from a streaming HTTP client. From a browser `EventSource`,\nuse a single-use `ticket` query parameter instead. A native-auth token is never accepted in a URL.\nEvent names are the `StreamTopic` values plus `reset`, and every client must handle `reset`.\n`data:` is one `StreamEvent` JSON object. `id:` is `..`: `hostId` is `a` or\n`b` (the core host), `bootEpoch` is the start time of that API process in Unix ms, and `seq` counts\nthis account's events on that host.\n`Last-Event-ID` replays up to 300 000 ms or 1 000 events. The server sends `event: reset` first\nwhen the `Last-Event-ID` is older than that window, comes from the other API host, or comes from\nbefore a server restart. On `reset`, reload your data. Each host numbers its own events, so an ID\nfrom one host cannot be resumed on the other.\nThe server coalesces at 4 to 10 Hz and sends a comment line every 15 000 ms as keep-alive.\n", "x-corelayer-auth": [ "native-auth", "sponsor-key", "ticket" ], "security": [ { "nativeAuth": [] }, { "sponsorKey": [] }, { "streamTicket": [] } ], "parameters": [ { "name": "account", "in": "query", "description": "Required with header auth; implied by the ticket otherwise.", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "topics", "in": "query", "description": "Comma-separated; default all.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StreamTopic" } }, "style": "form", "explode": false }, { "$ref": "#/components/parameters/LastEventId" } ], "responses": { "200": { "description": "Event stream of `StreamEvent` objects.", "content": { "text/event-stream": { "schema": { "type": "string" }, "x-corelayer-event-schema": { "$ref": "#/components/schemas/StreamEvent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/health": { "get": { "tags": [ "compat" ], "operationId": "compatHealth", "summary": "Compat health probe of the OpenClaw relayer interface.", "x-corelayer-auth": [ "public" ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "const": "ok" } } } } } } } } }, "/relayer/address/{userAddress}": { "get": { "tags": [ "compat" ], "operationId": "compatRelayerAddress", "summary": "Deterministic, long-lived relayer address for a sender (rendezvous hash over the shard's active relayers). No lease.", "x-corelayer-auth": [ "public" ], "parameters": [ { "name": "userAddress", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" } } ], "responses": { "200": { "description": "Relayer address.", "content": { "application/json": { "schema": { "type": "object", "required": [ "relayerAddress" ], "properties": { "relayerAddress": { "$ref": "#/components/schemas/Address" } } } } } }, "404": { "description": "Invalid address. Body keeps the kit's `error` string and is also a valid problem document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatError" } } } } } } }, "/relay": { "post": { "tags": [ "compat" ], "operationId": "compatRelay", "summary": "Compat relay. Accepts a transaction naming any of our active or draining same-shard relayers. First receipt only.", "description": "The signed transaction is the only credential. Limits are stricter than on `POST /v1/relay`: 1 RU/s\nper sender with a burst of 5, `gasPrice == min`, simulation always on, `gasLimit <= 60 000 000`, and\nno replacement modes. The handler takes an internal lease of 5 000 ms inside the request.\nOnly the statuses 200/400/403/404/429/500 are emitted. `challengeNonce` is accepted and ignored.\n", "x-corelayer-auth": [ "tx" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction" ], "properties": { "transaction": { "$ref": "#/components/schemas/TransactionPlain" }, "challengeNonce": { "type": "string", "description": "Ignored. Kept so unmodified kit clients validate." } } } } } }, "responses": { "200": { "description": "Co-signed. `txHash` is returned as soon as the commit point is passed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "txHash" ], "properties": { "txHash": { "$ref": "#/components/schemas/TxHash" } } } } } }, "400": { "description": "Any validation failure, and `RELAYER_RETIRED` (body explains clearing `.relayer_cache.json`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatError" } } } }, "403": { "description": "`NO_ENTITLEMENT` or `SENDER_NOT_AUTHORIZED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatError" } } } }, "429": { "description": "`QUOTA_EXHAUSTED`, `RATE_LIMITED`, `GAS_BUDGET_EXCEEDED`, `TOO_MANY_IN_FLIGHT`. `error` starts with \"Quota exceeded\" for quota cases.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatError" } } } }, "500": { "description": "Everything else (including 503-class conditions of the native path).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatError" } } } } } } } }, "webhooks": { "accountEvent": { "post": { "tags": [ "notifications" ], "operationId": "webhookAccountEvent", "summary": "Outbound delivery of one event to a customer endpoint.", "description": "At-least-once; the consumer de-duplicates on `id`. Order is not guaranteed; `seq` orders events of\none account. Signature header:\n`CoRelayer-Webhook-Signature: v1=`\nwhere `id` = the value of the `CoRelayer-Webhook-Id` header = the event `id`\n(two comma-separated `v1=` values during a secret rotation). Reject when\n`|now - CoRelayer-Webhook-Timestamp| > 300 000 ms`. Any 2xx within 5 000 ms is success; the body is\nignored. Retries at 10 000, 60 000, 300 000, 1 800 000, 3 600 000, 7 200 000, 14 400 000,\n28 800 000 and 28 800 000 ms after the previous attempt (10 attempts, about 23 h).\nThe endpoint is disabled after 604 800 000 ms of continuous failure and a `webhook.disabled`\nnotice is raised.\n", "parameters": [ { "name": "CoRelayer-Webhook-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "CoRelayer-Webhook-Timestamp", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/TimestampMs" } }, { "name": "CoRelayer-Webhook-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Delivered." } } } } }, "components": { "securitySchemes": { "nativeAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "MultiversX-NativeAuth", "description": "`Authorization: Bearer
..` (MultiversX native-auth).\nAllowed origins: `https://app.co-relayer.com`, and the fixed string `https://agent.co-relayer.com`\nfor headless agents (staging accepts the devnet equivalents). The token TTL is at most 3 600 s.\nOn browser calls the HTTP `Origin` header must equal the origin in the token. Tokens with\n`impersonate` or `multisig` are refused. The token is never accepted in a URL.\nThe block hash in the token must be a shard-1 block from the last 7 200 s. Headless agents can take\none from `GET /v1/network` -> `nativeAuth`. Any other hash is answered with `401 TOKEN_INVALID` and\n`details.expectedShard = 1`.\n" }, "sponsorKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "`crk___` - env `live` or `test`, 256-bit secret, stored as keyed hash, shown\nonce. Scopes `relay` and `read`. A key with scope `relay` lets the account pay for arbitrary\nsenders within the key policy (mandatory receiver allow-list, per-sender RU per day).\nServer-side secret; never to be embedded in a browser or mobile client.\n" }, "streamTicket": { "type": "apiKey", "in": "query", "name": "ticket", "description": "Single-use, 30 000 ms, opens exactly one read-only SSE stream for one account." } }, "parameters": { "Erd": { "name": "erd", "in": "path", "required": true, "description": "Bech32 account address.", "schema": { "$ref": "#/components/schemas/Address" } }, "RelayerAddress": { "name": "address", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" } }, "TxHashPath": { "name": "txHash", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TxHash" } }, "KeyId": { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z2-7]{12}$" } }, "WebhookId": { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9A-Za-z]{10,26}$" } }, "IncidentId": { "name": "incidentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^inc_[0-9A-Za-z]{10,26}$" } }, "Limit": { "name": "limit", "in": "query", "description": "Page size, default 50, maximum 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "description": "Opaque cursor from `nextCursor`. Bound to the filter set that produced it; otherwise `CURSOR_INVALID`.", "schema": { "type": "string", "maxLength": 512 } }, "FromMs": { "name": "fromMs", "in": "query", "description": "Inclusive lower bound, Unix ms (chain time for ledger data).", "schema": { "$ref": "#/components/schemas/TimestampMs" } }, "ToMs": { "name": "toMs", "in": "query", "description": "Exclusive upper bound, Unix ms.", "schema": { "$ref": "#/components/schemas/TimestampMs" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "16 to 128 visible ASCII characters. Stored 86 400 000 ms. Same key + same body returns the stored response; same key + different body gives `IDEMPOTENCY_KEY_REUSED`.", "schema": { "type": "string", "minLength": 16, "maxLength": 128 } }, "IdempotencyKeyOptional": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional logical idempotency key of the relay path (equivalent to the body member `intentKey`),\n16 to 128 visible ASCII characters, one per user action. Stored per `(sender, key)` for\n86 400 000 ms (24 hours). Same key with different bytes or nonce while the\nfirst intent is not `DEAD` -> `409 INTENT_ALREADY_SUBMITTED` carrying the first intent; after `DEAD`\nthe key is free again. It only ever rejects; the natural key `(sender, nonce)` stays authoritative.\n", "schema": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[\\x21-\\x7E]+$" } }, "Format": { "name": "format", "in": "query", "description": "`csv` streams every matching row as `text/csv` (no cursor, capped at 1 000 000 rows). Cells that start with = + - @ are prefixed with an apostrophe, so spreadsheet apps do not run them as formulas.", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } }, "LastEventId": { "name": "Last-Event-ID", "in": "header", "required": false, "description": "On the account stream, a `StreamEventId` (`..`). An ID from another host or from before a restart is answered with `event: reset` first. On the per-intent stream, the per-intent sequence number.", "schema": { "type": "string" } }, "PaymentSignature": { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 - base64 of a JSON `X402PaymentPayload`. Absent on the unpaid request.", "schema": { "type": "string" } } }, "headers": { "RequestId": { "description": "Request id, also the `instance` of a problem document and the log correlation id.", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds (HTTP standard). Millisecond precision is in `details.retryAfterMs` of the problem body.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimitLimit": { "description": "Requests (or RU on the relay path) allowed in the current window.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Remaining units in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the window resets (IETF RateLimit header fields).", "schema": { "type": "integer" } }, "CacheControl": { "description": "Public documents are cacheable for at most 6 s.", "schema": { "type": "string", "examples": [ "public, max-age=6" ] } }, "ETag": { "description": "Strong validator of the document.", "schema": { "type": "string" } }, "Link": { "description": "`; rel=\"next\"` when another page exists.", "schema": { "type": "string" } }, "PaymentRequired": { "description": "x402 v2 - base64 of a JSON `X402PaymentRequired`.", "schema": { "type": "string" } }, "PaymentResponse": { "description": "x402 v2 - base64 of a JSON `X402SettlementResponse`.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "`MALFORMED_REQUEST`, `VARIANTS_NOT_SUPPORTED`, `RELAYER_SIGNATURE_PRESENT`, `CHAIN_ID_MISMATCH`, `TX_VERSION_UNSUPPORTED`, `TX_OPTIONS_UNSUPPORTED`, `LEASE_MISSING`, `CURSOR_INVALID`.", "headers": { "CoRelayer-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unauthorized": { "description": "`UNAUTHENTICATED`, `TOKEN_INVALID` (`details.expectedShard = 1` when the native-auth block hash is not a shard-1 block), `TOKEN_EXPIRED`, `CHALLENGE_INVALID`, `API_KEY_INVALID`, `STREAM_TICKET_INVALID`, `ASSIGN_PROOF_REQUIRED`, `ASSIGN_PROOF_INVALID`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "`FORBIDDEN`, `ORIGIN_NOT_ALLOWED`, `API_KEY_SCOPE`, `ACCOUNT_SUSPENDED`, `LEASE_INVALID`, `RECEIVER_NOT_ALLOWED`, `SENDER_NOT_AUTHORIZED`, `DEPLOY_NOT_ALLOWED`, `FREE_FLOW_BARRED`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "`NOT_FOUND`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "`LEASE_MISMATCH`, `LEASE_EXPIRED`, `NONCE_PIN_MISMATCH`, `RESIGN_REQUIRED`, `RESIGN_SAME_NONCE`, `INTENT_ALREADY_EXECUTED`, `NOTHING_TO_CANCEL`, `NONCE_TOO_LOW`, `NONCE_IN_FLIGHT`, `NONCE_GAP`, `PRICE_ABOVE_MAX`, `QUEUED_BLOCK_EXISTS`, `DOWNGRADE_NOT_IMMEDIATE`, `PAYG_PRICE_ABOVE_MAX`, `QUOTE_EXPIRED`, `LIMIT_REACHED`, `IDEMPOTENCY_IN_PROGRESS`, `INTENT_ALREADY_SUBMITTED` (logical idempotency key; carries the first `intent`), `FREE_FLOW_BUSY`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PayloadTooLarge": { "description": "`PAYLOAD_TOO_LARGE` - request body above 131 072 bytes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unprocessable": { "description": "`REPLACEMENT_UNDERPRICED`, `RELAYER_UNKNOWN`, `RELAYER_SHARD_MISMATCH`, `GAS_PRICE_OUT_OF_RANGE`, `GAS_LIMIT_TOO_LOW`, `GAS_LIMIT_TOO_HIGH`, `GAS_OVERPROVISIONED`, `DATA_TOO_LARGE`, `SENDER_SIGNATURE_INVALID`, `GUARDIAN_*`, `INSUFFICIENT_SENDER_BALANCE`, `SIMULATION_FAILED`, `UNSUPPORTED_TX_FIELD`, `TIER_NOT_PURCHASABLE`, `DEPOSIT_BELOW_MIN`, `DEPOSIT_ABOVE_MAX`, `WEBHOOK_URL_NOT_ALLOWED`, `IDEMPOTENCY_KEY_REUSED`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PaymentRequired": { "description": "x402 challenge (unpaid request) or failed payment (`PAYMENT-RESPONSE` with `success=false`). Also used for `INSUFFICIENT_CREDITS`.", "headers": { "PAYMENT-REQUIRED": { "$ref": "#/components/headers/PaymentRequired" }, "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "`RATE_LIMITED`, `GAS_BUDGET_EXCEEDED`, `HOURLY_BURN_EXCEEDED`, `TOO_MANY_IN_FLIGHT`, `QUOTA_EXHAUSTED` (the latter without `Retry-After`; `details.reason` = `CAP_REACHED_PAYG_OFF` | `PAYG_ESCROW_EMPTY`).", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Internal": { "description": "`INTERNAL` - only before the commit point.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unavailable": { "description": "`SWAP_VENUE_PAUSED` (the exchange venue is paused), `CONTRACT_PAUSED` (the CoRelayer contract is paused: `paused` or `deposits_paused`; it is never reported as `SWAP_VENUE_PAUSED`), `SWAP_BUDGET_EXHAUSTED`, `FREE_FLOW_UNAVAILABLE`, `NO_RELAYER_AVAILABLE`, `UPSTREAM_UNAVAILABLE` (the x402 routes also return it when they cannot read their payment records), `SIGNER_UNAVAILABLE`, `SIGNER_FENCED`, `SIGNER_TIMEOUT`. All are answered before the commit point.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Address": { "type": "string", "description": "MultiversX bech32 address.", "pattern": "^erd1[02-9ac-hj-np-z]{58}$", "examples": [ "erd1mf4u0jr6786wtz7s7dj6gmpyfafg8e0exh5wvye5cygvvxyyxhpsmj8q0e" ] }, "TxHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "IntentId": { "type": "string", "description": "`:` - the natural intent key (sender, nonce).", "pattern": "^erd1[02-9ac-hj-np-z]{58}:[0-9]{1,20}$" }, "TimestampMs": { "type": "integer", "format": "int64", "minimum": 0, "description": "Unix time in milliseconds." }, "DurationMs": { "type": "integer", "format": "int64", "minimum": 0 }, "MicroUsdc": { "type": "integer", "format": "int64", "minimum": 0, "description": "micro-USDC (6 decimals) as JSON integer - operational endpoints." }, "Ru": { "type": "integer", "format": "int64", "minimum": 0, "description": "Relay Units." }, "AttoEgld": { "type": "string", "pattern": "^[0-9]+$", "description": "atto-EGLD as decimal string." }, "DecimalString": { "type": "string", "pattern": "^[0-9]+$", "description": "Non-negative integer as decimal string (pricing document family)." }, "Hex32": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "Shard": { "type": "integer", "enum": [ 0, 1, 2 ] }, "Page": { "type": "object", "required": [ "items", "hasMore" ], "properties": { "items": { "type": "array", "items": {} }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } } }, "Health": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok", "starting", "draining", "degraded" ] }, "version": { "type": "string" }, "host": { "type": "string" }, "chainId": { "type": "string" } } }, "ErrorCode": { "type": "string", "description": "Stable machine-readable error code. The enum is open: treat an unknown code by its HTTP status and\n`retryable`.\n`CONTRACT_PAUSED` (503, `resign: SAME_BYTES`, retryable) means the CoRelayer contract itself is\npaused (`paused` / `deposits_paused`; contract errors `ERR_PAUSED` / `ERR_DEPOSITS_PAUSED`). The relay\npath, the prepare routes, the purchase pre-check and x402 can all return it.\n`SWAP_VENUE_PAUSED` means only the exchange venue is paused.\n", "enum": [ "MALFORMED_REQUEST", "VARIANTS_NOT_SUPPORTED", "RELAYER_SIGNATURE_PRESENT", "CHAIN_ID_MISMATCH", "TX_VERSION_UNSUPPORTED", "TX_OPTIONS_UNSUPPORTED", "LEASE_MISSING", "LEASE_INVALID", "LEASE_MISMATCH", "LEASE_EXPIRED", "NONCE_PIN_MISMATCH", "RESIGN_REQUIRED", "RESIGN_SAME_NONCE", "REPLACEMENT_UNDERPRICED", "INTENT_ALREADY_EXECUTED", "NOTHING_TO_CANCEL", "NONCE_TOO_LOW", "NONCE_IN_FLIGHT", "NONCE_GAP", "TOO_MANY_IN_FLIGHT", "RELAYER_UNKNOWN", "RELAYER_SHARD_MISMATCH", "RELAYER_RETIRED", "GAS_PRICE_OUT_OF_RANGE", "GAS_LIMIT_TOO_LOW", "GAS_LIMIT_TOO_HIGH", "GAS_OVERPROVISIONED", "DATA_TOO_LARGE", "RECEIVER_NOT_ALLOWED", "SENDER_SIGNATURE_INVALID", "GUARDIAN_SIGNATURE_INVALID", "GUARDIAN_REQUIRED", "GUARDIAN_MISMATCH", "GUARDIAN_IS_RELAYER", "INSUFFICIENT_SENDER_BALANCE", "SIMULATION_FAILED", "SWAP_VENUE_PAUSED", "CONTRACT_PAUSED", "ASSIGN_PROOF_REQUIRED", "ASSIGN_PROOF_INVALID", "FREE_FLOW_BUSY", "FREE_FLOW_BARRED", "FREE_FLOW_UNAVAILABLE", "INTENT_ALREADY_SUBMITTED", "HOURLY_BURN_EXCEEDED", "SIGNER_TIMEOUT", "NO_ENTITLEMENT", "SENDER_NOT_AUTHORIZED", "QUOTA_EXHAUSTED", "RATE_LIMITED", "GAS_BUDGET_EXCEEDED", "NO_RELAYER_AVAILABLE", "UPSTREAM_UNAVAILABLE", "SIGNER_UNAVAILABLE", "SIGNER_FENCED", "INTERNAL", "PRICE_ABOVE_MAX", "TIER_NOT_PURCHASABLE", "QUEUED_BLOCK_EXISTS", "DOWNGRADE_NOT_IMMEDIATE", "INSUFFICIENT_CREDITS", "DEPOSIT_BELOW_MIN", "DEPOSIT_ABOVE_MAX", "SWAP_BUDGET_EXHAUSTED", "PAYG_PRICE_ABOVE_MAX", "DEPLOY_NOT_ALLOWED", "UNSUPPORTED_TX_FIELD", "QUOTE_EXPIRED", "RENEW_NOT_APPLICABLE", "UNAUTHENTICATED", "TOKEN_INVALID", "TOKEN_EXPIRED", "ORIGIN_NOT_ALLOWED", "CHALLENGE_INVALID", "API_KEY_INVALID", "API_KEY_SCOPE", "STREAM_TICKET_INVALID", "FORBIDDEN", "ACCOUNT_SUSPENDED", "NOT_FOUND", "PAYLOAD_TOO_LARGE", "CURSOR_INVALID", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENCY_IN_PROGRESS", "LIMIT_REACHED", "WEBHOOK_URL_NOT_ALLOWED", "PAYMENT_REQUIRED", "PAYMENT_INVALID", "PAYMENT_FAILED" ] }, "ResignAction": { "type": "string", "enum": [ "NONE", "SAME_BYTES", "NEW_SIGNATURE_SAME_NONCE" ] }, "Problem": { "type": "object", "description": "RFC 9457 problem document with CoRelayer extension members.", "required": [ "type", "title", "status", "code", "retryable" ], "properties": { "type": { "type": "string", "format": "uri", "description": "`https://docs.co-relayer.com/errors/`" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string", "description": "Request id." }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "retryable": { "type": "boolean" }, "resign": { "$ref": "#/components/schemas/ResignAction" }, "hint": { "type": "string", "description": "One sentence that tells an agent what to do next." }, "intent": { "type": "object", "required": [ "sender", "nonce", "state" ], "properties": { "sender": { "$ref": "#/components/schemas/Address" }, "nonce": { "type": "integer", "format": "int64" }, "state": { "$ref": "#/components/schemas/IntentState" }, "txHash": { "$ref": "#/components/schemas/TxHash" } } }, "details": { "type": "object", "additionalProperties": true, "description": "Code-specific. Fixed members: nonce errors `onchainNonce`, `poolLastNonce`, `expectedNonce`,\n`occupiedBy` (own|foreign), `pinnedNonce`; `LEASE_EXPIRED.renewable`; replacement errors\n`minGasPrice`; limit errors `limit`, `actual`, `bound` (min|max); `SIMULATION_FAILED.returnMessage`;\n`NO_ENTITLEMENT.reason` (NO_ACCOUNT|PERIOD_LAPSED); `QUOTA_EXHAUSTED.reason`\n(CAP_REACHED_PAYG_OFF|PAYG_ESCROW_EMPTY) + `periodEndMs`; 429/503 `retryAfterMs`;\n`pricingUrl`, `x402Url` on 402/429 quota errors; `ASSIGN_PROOF_*.serverTimeMs`;\n`TOKEN_INVALID.expectedShard` (= 1); `FREE_FLOW_BUSY.reason` (INTENT_IN_FLIGHT|PENDING_TX);\n`FREE_FLOW_BARRED.untilMs`; `RATE_LIMITED.scope` (account|platform);\n`CONTRACT_PAUSED.scope` (all|deposits).\n" }, "assignment": { "$ref": "#/components/schemas/Assignment" } }, "additionalProperties": true }, "CompatError": { "description": "Problem document plus the `error` string, the only member the Moltbot kit surfaces.", "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "pricing": { "type": "string", "format": "uri" } } } ] }, "AssignRequest": { "type": "object", "additionalProperties": false, "required": [ "sender" ], "description": "Request body of `POST /v1/relay/assign`.", "properties": { "sender": { "$ref": "#/components/schemas/Address" }, "proof": { "type": "object", "description": "Proof that the caller controls the sender. Required unless a native-auth bearer token of `sender` is\npresented. `signature` is an Ed25519 signature, made by the sender's own key, over the UTF-8 bytes of the\nmessage `corelayer/assign/v1|||`. Sign the bytes directly: a wallet's\n`signMessage` adds the MultiversX signed-message prefix first, and that signature does not verify.\n`kind` is `sponsor` when a sponsor API key will pay for the relay (sent as `X-Api-Key` on\n`POST /v1/relay`), and `key` otherwise. The sender's key signs both kinds.\nIt signs a message: there is no nonce and no wallet prompt, and the user still signs the transaction\nonly once. The server verifies it, and it can be used once per `(sender, serverTimeMs)`.\n", "additionalProperties": false, "required": [ "kind", "serverTimeMs", "signature" ], "properties": { "kind": { "type": "string", "enum": [ "key", "sponsor" ] }, "serverTimeMs": { "$ref": "#/components/schemas/TimestampMs", "description": "Within +/- 30 000 ms of the signer clock (`GET /v1/network.serverTimeMs`)." }, "signature": { "type": "string", "pattern": "^[0-9a-f]{128}$" } } }, "renewFor": { "$ref": "#/components/schemas/Address", "description": "Relayer named in an already signed transaction; returns a RENEWAL lease for it." }, "cancel": { "type": "object", "additionalProperties": false, "required": [ "nonce" ], "properties": { "nonce": { "type": "integer", "format": "int64", "minimum": 0 } } } } }, "Assignment": { "type": "object", "required": [ "assignmentId", "relayer", "shard", "lease", "leaseExpiresAtMs", "serverTimeMs", "chainId", "minGasPrice", "maxGasPrice", "extraGasRelayed", "extraGasGuarded", "registryVersion" ], "properties": { "assignmentId": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "The ID of this assignment, as 24 lowercase hex characters." }, "relayer": { "$ref": "#/components/schemas/Address" }, "shard": { "$ref": "#/components/schemas/Shard" }, "lease": { "type": "string", "description": "Lease token v1, base64url without padding, 192 characters.", "minLength": 192, "maxLength": 192 }, "leaseExpiresAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "serverTimeMs": { "$ref": "#/components/schemas/TimestampMs" }, "chainId": { "type": "string" }, "minGasPrice": { "type": "integer", "format": "int64" }, "maxGasPrice": { "type": "integer", "format": "int64" }, "extraGasRelayed": { "type": "integer" }, "extraGasGuarded": { "type": "integer" }, "expectedNonce": { "type": "integer", "format": "int64", "description": "Advisory; present when a fresh nonce view exists." }, "pinNonce": { "type": "integer", "format": "int64", "description": "Present only on re-sign and cancel leases." }, "registryVersion": { "type": "integer", "format": "int64", "description": "The contract's `getRegistryVersion()` value this assignment was made from. Use it in the cache key when you verify the relayer on chain." } } }, "TransactionPlain": { "type": "object", "description": "The 17 proxy fields of a MultiversX transaction. Unknown members give `UNSUPPORTED_TX_FIELD`.", "additionalProperties": false, "required": [ "nonce", "value", "receiver", "sender", "gasPrice", "gasLimit", "chainID", "version", "signature", "relayer" ], "properties": { "nonce": { "type": "integer", "format": "int64", "minimum": 0 }, "value": { "type": "string", "pattern": "^[0-9]+$" }, "receiver": { "$ref": "#/components/schemas/Address" }, "sender": { "$ref": "#/components/schemas/Address" }, "senderUsername": { "type": "string", "description": "base64" }, "receiverUsername": { "type": "string", "description": "base64" }, "gasPrice": { "type": "integer", "format": "int64", "minimum": 1 }, "gasLimit": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 600000000 }, "data": { "type": "string", "description": "base64" }, "chainID": { "type": "string" }, "version": { "type": "integer", "enum": [ 1, 2 ] }, "options": { "type": "integer", "enum": [ 0, 1, 2, 3 ] }, "guardian": { "$ref": "#/components/schemas/Address" }, "signature": { "type": "string", "pattern": "^[0-9a-f]{128}$" }, "guardianSignature": { "type": "string", "pattern": "^[0-9a-f]{128}$" }, "relayer": { "$ref": "#/components/schemas/Address" }, "relayerSignature": { "type": "string", "maxLength": 0, "description": "Must be absent or empty (`RELAYER_SIGNATURE_PRESENT`)." } } }, "UnsignedTransaction": { "type": "object", "description": "Transaction built by a prepare endpoint. The wallet adds only the signature(s). Read `nonce` back from the signed transaction, because some wallets raise it to the account's current nonce.", "required": [ "nonce", "value", "receiver", "sender", "gasPrice", "gasLimit", "chainID", "version" ], "properties": { "nonce": { "type": "integer", "format": "int64" }, "value": { "type": "string" }, "receiver": { "$ref": "#/components/schemas/Address" }, "sender": { "$ref": "#/components/schemas/Address" }, "gasPrice": { "type": "integer", "format": "int64" }, "gasLimit": { "type": "integer", "format": "int64" }, "data": { "type": "string", "description": "base64" }, "chainID": { "type": "string" }, "version": { "type": "integer" }, "options": { "type": "integer" }, "guardian": { "$ref": "#/components/schemas/Address" }, "relayer": { "$ref": "#/components/schemas/Address" } } }, "RelayMode": { "type": "string", "enum": [ "normal", "cancel", "replace" ], "default": "normal" }, "RelayRequest": { "type": "object", "additionalProperties": false, "required": [ "tx", "lease" ], "properties": { "tx": { "$ref": "#/components/schemas/TransactionPlain" }, "lease": { "type": "string" }, "mode": { "$ref": "#/components/schemas/RelayMode" }, "simulate": { "type": "boolean", "description": "Simulate before co-signing. On by default for human tiers and the free flow; agent tiers can opt out." }, "account": { "$ref": "#/components/schemas/Address", "description": "Optional. Bill this account, provided it has authorised the sender on chain." }, "intentKey": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[\\x21-\\x7E]+$", "description": "Optional idempotency key for this user action, 16 to 128 visible ASCII characters. It is the same key as the `Idempotency-Key` header; if you send both, the header is used. Reusing it with different bytes or another nonce, while the first intent is not `DEAD`, gives `409 INTENT_ALREADY_SUBMITTED`." } } }, "IntentState": { "type": "string", "enum": [ "ASSIGNED", "RECEIVED", "REJECTED", "ACCEPTED", "COSIGNED", "BROADCAST", "EXECUTED_OK", "EXECUTED_FAIL", "DEAD", "EXPIRED_LOCALLY_STILL_VALID" ] }, "DeadReason": { "type": "string", "enum": [ "NONCE_CONSUMED_FOREIGN", "REPLACED_BY_CANCEL", "REPLACED_BY_RESIGN", "REPLACED_BY_PEER", "INVALID_BYTES" ] }, "StuckReason": { "type": "string", "enum": [ "RELAYER_UNDERFUNDED", "CHAIN_STALLED", "NOT_IN_POOL" ] }, "GatewayAck": { "type": "object", "required": [ "gateway", "ms" ], "properties": { "gateway": { "type": "string", "description": "The ID of the gateway that acknowledged the transaction, such as `G1`." }, "ms": { "type": "integer", "description": "Milliseconds from `cosignedAtMs` to the acknowledgement." }, "via": { "type": "string", "enum": [ "owner", "peer", "witness" ], "description": "Which node sent it." } } }, "RelayResponse": { "type": "object", "required": [ "intentId", "txHash", "relayer", "state", "ru", "receivedAtMs", "cosignedAtMs", "acks" ], "properties": { "intentId": { "$ref": "#/components/schemas/IntentId" }, "txHash": { "$ref": "#/components/schemas/TxHash" }, "relayer": { "$ref": "#/components/schemas/Address" }, "state": { "$ref": "#/components/schemas/IntentState" }, "ru": { "$ref": "#/components/schemas/Ru" }, "receivedAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "cosignedAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "broadcastAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "acks": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayAck" } }, "duplicate": { "type": "boolean", "description": "True on an idempotent replay of identical bytes." }, "account": { "$ref": "#/components/schemas/Address" }, "billing": { "type": "object", "properties": { "authMode": { "$ref": "#/components/schemas/AuthMode" }, "ruCapReserved": { "$ref": "#/components/schemas/Ru" }, "ruPaygReserved": { "$ref": "#/components/schemas/Ru" } } }, "stuckReason": { "$ref": "#/components/schemas/StuckReason" }, "advisory": { "type": "string", "description": "Set when the state is `EXPIRED_LOCALLY_STILL_VALID`. It tells the user that broadcasting has stopped, that the transaction has not executed but is still valid, and that using its nonce (with Cancel or any other transaction) makes it impossible." }, "statusUrl": { "type": "string", "format": "uri" }, "eventsUrl": { "type": "string", "format": "uri" } } }, "LatencyBreakdown": { "type": "object", "description": "All values in milliseconds. A value is null when its timestamp is unknown, for example on a row the\nservice recovered after a restart.\nacceptToCosignMs = cosignedAtMs - receivedAtMs; cosignToBroadcastMs = broadcastAtMs - cosignedAtMs;\naddedMs = broadcastAtMs - receivedAtMs;\ninclusionMs = executedBlockTsMs - receivedAtMs;\nfinalityMs = finalizedAtMs - executedBlockTsMs; totalMs = finalizedAtMs - receivedAtMs;\nroundsToInclusion = ceil(inclusionMs / roundDurationMs).\n", "properties": { "acceptToCosignMs": { "type": [ "integer", "null" ] }, "cosignToBroadcastMs": { "type": [ "integer", "null" ] }, "addedMs": { "type": [ "integer", "null" ] }, "inclusionMs": { "type": [ "integer", "null" ] }, "finalityMs": { "type": [ "integer", "null" ] }, "totalMs": { "type": [ "integer", "null" ] }, "roundsToInclusion": { "type": [ "integer", "null" ] }, "crossShard": { "type": "boolean" } } }, "Intent": { "type": "object", "required": [ "intentId", "sender", "nonce", "state", "final" ], "properties": { "intentId": { "$ref": "#/components/schemas/IntentId" }, "sender": { "$ref": "#/components/schemas/Address" }, "nonce": { "type": "integer", "format": "int64" }, "txHash": { "$ref": "#/components/schemas/TxHash" }, "relayer": { "$ref": "#/components/schemas/Address" }, "shard": { "$ref": "#/components/schemas/Shard" }, "receiver": { "$ref": "#/components/schemas/Address" }, "function": { "type": [ "string", "null" ], "description": "First data segment when printable ASCII, else null. Rendered as text, never as HTML." }, "state": { "$ref": "#/components/schemas/IntentState" }, "final": { "type": "boolean", "description": "True when the executing block is final - the billing trigger." }, "rejectCode": { "$ref": "#/components/schemas/ErrorCode" }, "deadReason": { "$ref": "#/components/schemas/DeadReason" }, "stuckReason": { "$ref": "#/components/schemas/StuckReason" }, "corrected": { "type": "boolean", "description": "Reconciliation turned DEAD into EXECUTED_*." }, "mode": { "$ref": "#/components/schemas/RelayMode" }, "ru": { "$ref": "#/components/schemas/Ru" }, "account": { "$ref": "#/components/schemas/Address" }, "includedInBlock": { "type": "object", "properties": { "shard": { "$ref": "#/components/schemas/Shard" }, "nonce": { "type": "integer", "format": "int64" }, "hash": { "$ref": "#/components/schemas/Hex32" } } }, "receivedAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "cosignedAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "broadcastAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "executedBlockTsMs": { "type": [ "integer", "null" ], "format": "int64" }, "finalizedAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "latency": { "$ref": "#/components/schemas/LatencyBreakdown" }, "acks": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayAck" } }, "feePaidAtto": { "$ref": "#/components/schemas/AttoEgld" }, "gasUsed": { "type": "integer", "format": "int64" }, "advisory": { "type": "string" }, "explorerUrl": { "type": "string", "format": "uri" } } }, "QuoteRelayRequest": { "type": "object", "additionalProperties": false, "required": [ "tx" ], "properties": { "tx": { "type": "object", "description": "Signed or unsigned transaction; only `sender`, `gasLimit`, `gasPrice`, `data`, `options`, `guardian` are read.", "additionalProperties": true }, "account": { "$ref": "#/components/schemas/Address" } } }, "RelayQuote": { "type": "object", "required": [ "ru", "maxFeeAtto", "ruScheduleVersion", "tariff", "paygPricePerRu", "priceMicroUsdc" ], "properties": { "ru": { "$ref": "#/components/schemas/DecimalString" }, "maxFeeAtto": { "$ref": "#/components/schemas/DecimalString" }, "moveGas": { "$ref": "#/components/schemas/DecimalString" }, "ruScheduleVersion": { "type": "integer" }, "tariff": { "$ref": "#/components/schemas/DecimalString" }, "paygPricePerRu": { "$ref": "#/components/schemas/DecimalString" }, "priceMicroUsdc": { "$ref": "#/components/schemas/DecimalString", "description": "Non-zero only when the RU would be billed as PAYG." }, "billedAs": { "type": "string", "enum": [ "grant", "bonus", "cap", "payg", "free", "none" ] } } }, "ValidateRequest": { "type": "object", "additionalProperties": false, "required": [ "tx" ], "properties": { "tx": { "$ref": "#/components/schemas/TransactionPlain" }, "simulate": { "type": "boolean", "default": true }, "account": { "$ref": "#/components/schemas/Address" } } }, "ValidateResponse": { "type": "object", "required": [ "ok", "problems" ], "properties": { "ok": { "type": "boolean" }, "problems": { "type": "array", "items": { "$ref": "#/components/schemas/Problem" } }, "ru": { "$ref": "#/components/schemas/Ru" }, "maxFeeAtto": { "$ref": "#/components/schemas/AttoEgld" }, "moveGas": { "type": "integer", "format": "int64" }, "simulatedGas": { "type": [ "integer", "null" ], "format": "int64" }, "expectedNonce": { "type": [ "integer", "null" ], "format": "int64" }, "wouldBill": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Address" }, "authMode": { "$ref": "#/components/schemas/AuthMode" }, "billedAs": { "type": "string", "enum": [ "grant", "bonus", "cap", "payg", "free", "none" ] } } } } }, "Network": { "type": "object", "required": [ "chainId", "roundDurationMs", "minGasPrice", "maxGasPrice", "minGasLimit", "gasPerDataByte", "extraGasRelayed", "extraGasGuarded", "gasPriceModifier", "maxGasPerTransaction", "contract", "serverTimeMs", "swapVenue", "shards" ], "properties": { "chainId": { "type": "string", "enum": [ "1", "D" ], "description": "Chain id of the serving network. Clients build the assign presence proof with it (`corelayer/assign/v1|||`), key their contract-address pin and relayer-verification cache by it, and must refuse to sign when it differs from the `chainID` of the transaction or from `network.chainId` in `pricing.json`. The owner, the relayers and possibly the contract address are the same on devnet and mainnet, so an address never tells the networks apart." }, "caip2": { "type": "string", "examples": [ "mvx:1", "mvx:D" ] }, "roundDurationMs": { "type": "integer" }, "minGasPrice": { "type": "integer", "format": "int64" }, "maxGasPrice": { "type": "integer", "format": "int64", "description": "2 x minGasPrice. A normal submission may not use a higher gas price." }, "minGasLimit": { "type": "integer" }, "gasPerDataByte": { "type": "integer" }, "extraGasRelayed": { "type": "integer" }, "extraGasGuarded": { "type": "integer" }, "gasPriceModifier": { "type": "string" }, "maxGasPerTransaction": { "type": "integer", "format": "int64" }, "readAtEpoch": { "type": "integer" }, "contract": { "type": [ "string", "null" ], "description": "CoRelayer contract address, for convenience. Pin the address in your own configuration; your pin wins if the two disagree." }, "ruScheduleVersion": { "type": "integer" }, "serverTimeMs": { "$ref": "#/components/schemas/TimestampMs" }, "chainTimeMs": { "$ref": "#/components/schemas/TimestampMs", "description": "timestampMs of the newest shard-1 block ingested." }, "swapVenue": { "type": "object", "required": [ "paused", "checkedAtMs" ], "properties": { "paused": { "type": "boolean" }, "pairState": { "type": "integer" }, "wrapperPaused": { "type": "boolean" }, "tokenPaused": { "type": "boolean" }, "checkedAtMs": { "$ref": "#/components/schemas/TimestampMs" } } }, "contractPause": { "type": "object", "description": "The CoRelayer contract's `getPauseState()`, re-read every 6 000 ms. `all` or `deposits` true -> purchase routes answer `CONTRACT_PAUSED`. The contract is deployed paused.", "required": [ "all", "deposits", "checkedAtMs" ], "properties": { "all": { "type": "boolean" }, "deposits": { "type": "boolean" }, "checkedAtMs": { "$ref": "#/components/schemas/TimestampMs" } } }, "paymentToken": { "type": "string", "description": "ESDT identifier from the contract configuration: `USDC-c76f1f` on mainnet, `USDC-350c4e` on devnet staging.", "examples": [ "USDC-c76f1f" ] }, "nativeAuth": { "type": "object", "description": "Recent shard-1 block for headless agents that build a native-auth token themselves. Tokens must\nembed a shard-1 block hash (security scheme `nativeAuth`). Refreshed with every ingested shard-1 block.\n", "required": [ "blockHash", "blockTsMs", "shard" ], "properties": { "blockHash": { "$ref": "#/components/schemas/Hex32" }, "blockTsMs": { "$ref": "#/components/schemas/TimestampMs" }, "shard": { "type": "integer", "const": 1 }, "origin": { "type": "string", "format": "uri", "description": "The fixed headless-agent origin string to put into the token (`https://agent.co-relayer.com` on mainnet)." } } }, "shards": { "type": "array", "items": { "$ref": "#/components/schemas/ShardLatency" } }, "directHosts": { "type": "array", "description": "Regional API hosts to fail over to when the main host does not answer:\n`https://fsn.api.co-relayer.com` and `https://hel.api.co-relayer.com` (devnet has its own). They\nsend the same CORS headers as the main host, so browsers can use them.\n", "items": { "type": "string", "format": "uri" } } } }, "ShardLatency": { "type": "object", "required": [ "shard", "status" ], "properties": { "shard": { "$ref": "#/components/schemas/Shard" }, "status": { "$ref": "#/components/schemas/ComponentStatus" }, "activeRelayers": { "type": "integer" }, "relays24h": { "type": "integer", "description": "Customer relays of this shard in the last 86 400 000 ms; synthetic probes excluded." }, "windowMs": { "$ref": "#/components/schemas/DurationMs" }, "samples": { "type": "integer" }, "inclusionP50Ms": { "type": [ "integer", "null" ] }, "inclusionP95Ms": { "type": [ "integer", "null" ] }, "inclusionP99Ms": { "type": [ "integer", "null" ] }, "addedP50Ms": { "type": [ "integer", "null" ] }, "addedP99Ms": { "type": [ "integer", "null" ] }, "lastBlockTsMs": { "$ref": "#/components/schemas/TimestampMs" }, "stalled": { "type": "boolean" } } }, "PricingDocument": { "type": "object", "description": "The pricing document. Its complete JSON Schema is `https://co-relayer.com/schemas/pricing-v1.json`.\nThis schema types the top-level keys and the tier record, and leaves the rest to that schema.\n", "required": [ "schema", "documentVersion", "updatedAtMs", "network", "source", "paymentToken", "refundable", "tariff", "relayUnit", "admission", "deposit", "lifecycle", "payg", "rateClasses", "tiers", "howToBuy", "links" ], "properties": { "schema": { "type": "string", "format": "uri" }, "documentVersion": { "type": "integer" }, "updatedAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "network": { "type": "object", "additionalProperties": true, "description": "Each network publishes its own pricing document. Compare `network.chainId` with the `chainID` of every transaction you sign.", "examples": [ { "caip2": "mvx:1", "x402Network": "multiversx:1", "chainId": "1", "roundDurationMs": 600 }, { "caip2": "mvx:D", "x402Network": "multiversx:D", "chainId": "D", "roundDurationMs": 600 } ] }, "source": { "type": "object", "additionalProperties": true, "description": "`source.views` lists the contract views the document is generated from: `getConfig`, `getPricingConfig`, `getTiers`, `getTariff`, `getRuSchedule`, `getRateClasses`, `getSwapBudget`." }, "paymentToken": { "type": "object", "additionalProperties": true, "description": "Read from the contract's `getConfig()`: `USDC-c76f1f` on mainnet, `USDC-350c4e` on devnet." }, "refundable": { "type": "boolean", "const": false }, "tariff": { "type": "object", "required": [ "unit", "effective", "version", "pending", "pendingEffectiveMs", "rules", "formulas" ], "properties": { "unit": { "type": "string" }, "effective": { "$ref": "#/components/schemas/DecimalString" }, "version": { "type": "integer" }, "effectiveSinceMs": { "$ref": "#/components/schemas/TimestampMs" }, "pending": { "type": [ "string", "null" ] }, "pendingEffectiveMs": { "type": [ "integer", "null" ], "format": "int64" }, "rules": { "type": "object", "additionalProperties": true }, "formulas": { "type": "object", "additionalProperties": true } } }, "relayUnit": { "type": "object", "additionalProperties": true }, "admission": { "type": "object", "additionalProperties": true }, "deposit": { "type": "object", "additionalProperties": true }, "lifecycle": { "type": "object", "additionalProperties": true }, "payg": { "type": "object", "additionalProperties": true }, "rateClasses": { "type": "object", "required": [ "policyVersion", "classes" ], "properties": { "policyVersion": { "type": "integer" }, "classes": { "type": "array", "items": { "$ref": "#/components/schemas/RateClass" } } } }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/PricingTier" } }, "howToBuy": { "type": "object", "additionalProperties": true, "description": "How to buy a plan. `howToBuy.freeOperations` lists the contract calls that are relayed free of charge. `howToBuy.onChain.gasLimit` and `gasLimitFlags` are measured on each network, so the values differ between devnet and mainnet." }, "links": { "type": "object", "additionalProperties": true } } }, "RateClass": { "type": "object", "required": [ "rateClass", "ruPerSecSustained", "ruPerSecBurst", "gasLimitPerSecPerShard" ], "description": "One entry of `rateClasses.classes[]`. The limits the API applies never exceed the on-chain `getRateClasses()` table.", "properties": { "rateClass": { "type": "integer", "minimum": 1 }, "ruPerSecSustained": { "type": "integer" }, "ruPerSecBurst": { "type": "integer" }, "gasLimitPerSecPerShard": { "$ref": "#/components/schemas/DecimalString" }, "gasBurst": { "$ref": "#/components/schemas/DecimalString" }, "maxGasLimit": { "$ref": "#/components/schemas/DecimalString" }, "maxRuPerTx": { "$ref": "#/components/schemas/DecimalString", "description": "Per-transaction RU ceiling of the class, including the data term: 15 for classes 1 and 6, 25 for classes 2-5. `admission.maxRuPerTx` is the largest value of any class (`admission.maxRuPerTxNote`)." }, "ruPerHour": { "type": "integer" } }, "examples": [ { "rateClass": 1, "ruPerSecSustained": 1, "ruPerSecBurst": 15, "gasLimitPerSecPerShard": "20000000", "gasBurst": "200000000", "maxGasLimit": "100000000", "maxRuPerTx": "15", "ruPerHour": 300 } ] }, "PricingTier": { "type": "object", "required": [ "tierId", "slug", "name", "audience", "status", "periodMs", "capRu", "priceUnits", "paygBps", "price", "paygPricePerRu", "maxSenders", "flags", "rateClass", "slaClass", "successorTierId", "singlePaymentPurchasable" ], "properties": { "tierId": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "audience": { "type": "string", "enum": [ "human", "agent" ] }, "status": { "type": "string", "enum": [ "draft", "active", "legacy", "retired" ] }, "available": { "type": "boolean", "description": "False while a listed tier cannot be bought. On mainnet, tiers 4, 5 and 13 stay `draft` until the relayer float for their rate class is funded; all eight tiers are active on devnet." }, "unavailableReason": { "type": "string", "enum": [ "CAPACITY" ], "description": "Present only when `available` is false." }, "periodMs": { "$ref": "#/components/schemas/DurationMs" }, "capRu": { "$ref": "#/components/schemas/DecimalString" }, "priceUnits": { "$ref": "#/components/schemas/DecimalString" }, "paygBps": { "type": "integer" }, "price": { "$ref": "#/components/schemas/DecimalString" }, "paygPricePerRu": { "$ref": "#/components/schemas/DecimalString" }, "pendingPrice": { "$ref": "#/components/schemas/DecimalString" }, "pendingPaygPricePerRu": { "$ref": "#/components/schemas/DecimalString" }, "maxSenders": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "agent", "payg_allowed", "priority_lane", "dedicated_pool", "sponsor_any_sender", "custom" ] } }, "rateClass": { "type": "integer" }, "slaClass": { "type": "string", "enum": [ "best-effort", "standard", "priority", "dedicated" ] }, "successorTierId": { "type": [ "integer", "null" ] }, "singlePaymentPurchasable": { "type": "boolean" }, "note": { "type": "string" } } }, "TariffEntry": { "type": "object", "required": [ "version", "tariff", "effectiveMs" ], "properties": { "version": { "type": "integer", "description": "The tariff version, counting from 1. A usage row names the tariff it was billed under in `tariffIdx`." }, "tariff": { "$ref": "#/components/schemas/DecimalString" }, "effectiveMs": { "$ref": "#/components/schemas/TimestampMs" }, "materialisedMs": { "type": [ "integer", "null" ], "format": "int64" } } }, "SubscribeQuote": { "type": "object", "description": "A price quote, with amounts as decimal strings. **Stateless:** `quoteMac` authenticates the canonical\nJSON (RFC 8785) of all other members, so any API host can verify a quote it did not issue by\nrecomputing the MAC. No quote is stored; two prepare calls simply give two valid quotes. The MAC key\ndiffers per environment, so a devnet quote never verifies on mainnet.\n", "required": [ "quoteId", "quoteMac", "tierId", "months", "tariff", "tariffVersion", "tariffEffectiveMs", "priceMicroUsdc", "maxPrice", "pendingTariff", "issuedAtMs", "expiresAtMs" ], "properties": { "quoteId": { "type": "string", "pattern": "^q_[0-9A-Z]{10}$", "description": "At most 12 ASCII bytes, because it becomes the `ref` of the contract call and data bytes are billed at full gas price. It is `q_` followed by the first 10 Crockford base32 characters of an HMAC, keyed with the service's quote key, over `corelayer/quote-id/v1` followed by the canonical JSON of every member except `quoteId` and `quoteMac`. Any API host can recompute it." }, "quoteMac": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "HMAC-SHA256 with the service's quote key over `corelayer/quote/v1` followed by the canonical JSON of every other member, `quoteId` included. Base64url without padding." }, "tierId": { "type": "integer" }, "months": { "type": "integer", "minimum": 0, "maximum": 12 }, "tariff": { "$ref": "#/components/schemas/DecimalString" }, "tariffVersion": { "type": "integer" }, "tariffEffectiveMs": { "$ref": "#/components/schemas/TimestampMs" }, "priceMicroUsdc": { "$ref": "#/components/schemas/DecimalString" }, "maxPrice": { "$ref": "#/components/schemas/DecimalString" }, "pendingTariff": { "type": [ "string", "null" ] }, "issuedAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "expiresAtMs": { "$ref": "#/components/schemas/TimestampMs" } } }, "PrepareSubscribeRequest": { "type": "object", "additionalProperties": false, "required": [ "address", "tierId" ], "properties": { "address": { "$ref": "#/components/schemas/Address", "description": "Buyer = sender = account." }, "tierId": { "type": "integer" }, "months": { "type": "integer", "minimum": 0, "maximum": 12, "default": 1, "description": "0 only for a no-period tier." }, "payWith": { "type": "string", "enum": [ "auto", "usdc", "credits" ], "default": "auto", "description": "`auto` uses credits first and pays only the difference in USDC." }, "extraDepositMicroUsdc": { "$ref": "#/components/schemas/DecimalString", "description": "USDC paid above the price stays as credits." }, "gasless": { "type": "boolean", "default": true } } }, "PrepareDepositRequest": { "type": "object", "additionalProperties": false, "required": [ "address", "amountMicroUsdc" ], "properties": { "address": { "$ref": "#/components/schemas/Address", "description": "Payer = sender." }, "amountMicroUsdc": { "$ref": "#/components/schemas/DecimalString" }, "beneficiary": { "$ref": "#/components/schemas/Address", "description": "Present -> `depositFor(beneficiary)`." }, "gasless": { "type": "boolean", "default": true } } }, "PrepareFlagsRequest": { "type": "object", "additionalProperties": false, "required": [ "address" ], "minProperties": 2, "properties": { "address": { "$ref": "#/components/schemas/Address" }, "autoRenew": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "renewTierId": { "type": "integer", "description": "0 = same tier." }, "maxRenewPriceMicroUsdc": { "$ref": "#/components/schemas/DecimalString", "description": "Required and > 0 when enabled." } } }, "payg": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "budgetMicroUsdc": { "$ref": "#/components/schemas/DecimalString" }, "maxPaygPriceMicroUsdc": { "$ref": "#/components/schemas/DecimalString", "description": "0 = no ceiling." }, "autoTopup": { "type": "boolean" } } }, "releaseEscrow": { "type": "boolean" }, "renew": { "type": "boolean", "description": "Build `renew(address)` for the caller's own account (\"Renew now\"). It is relayed free because the argument is the sender. The predicted outcome is `AccountQuota.autoRenew.predictedOutcome`; the route refuses with `409 RENEW_NOT_APPLICABLE` (`details.predictedOutcome`) when that outcome is anything but `OK` or `QUEUED_STARTED`, so no free relay is spent on a call that would change nothing." }, "gasless": { "type": "boolean", "default": true } } }, "PrepareSendersRequest": { "type": "object", "additionalProperties": false, "required": [ "address", "action", "senders" ], "properties": { "address": { "$ref": "#/components/schemas/Address" }, "action": { "type": "string", "enum": [ "add", "remove" ] }, "senders": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/Address" } } } }, "PreparedTransaction": { "type": "object", "required": [ "transaction", "summary", "free" ], "properties": { "transaction": { "$ref": "#/components/schemas/UnsignedTransaction" }, "assignment": { "$ref": "#/components/schemas/Assignment", "description": "Absent when `gasless=false`." }, "summary": { "type": "string", "description": "Human and LLM readable description of what will be signed." }, "instructions": { "type": "string", "description": "Next steps - sign once, read the nonce back, POST /v1/relay with the lease." }, "free": { "type": "boolean", "description": "True when the call is on the free list and is relayed free of charge. Show this value to the user instead of working it out yourself." }, "ru": { "$ref": "#/components/schemas/Ru" }, "feeMicroUsdc": { "$ref": "#/components/schemas/DecimalString", "description": "On-chain fee debited from credits (addSenders)." }, "contractCall": { "type": "object", "required": [ "endpoint", "args" ], "properties": { "endpoint": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Hex-encoded arguments in order." }, "tokenTransfer": { "type": "object", "properties": { "token": { "type": "string" }, "amount": { "$ref": "#/components/schemas/DecimalString" } } } } } } }, "PreparedTransactions": { "type": "object", "required": [ "transactions", "summary" ], "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/PreparedTransaction" } }, "assignment": { "$ref": "#/components/schemas/Assignment" }, "summary": { "type": "string" } } }, "PreparedPurchase": { "allOf": [ { "$ref": "#/components/schemas/PreparedTransaction" }, { "type": "object", "required": [ "quote", "payMicroUsdc", "fromCreditsMicroUsdc" ], "properties": { "quote": { "$ref": "#/components/schemas/SubscribeQuote" }, "payMicroUsdc": { "$ref": "#/components/schemas/DecimalString" }, "fromCreditsMicroUsdc": { "$ref": "#/components/schemas/DecimalString" } } } ] }, "X402Descriptor": { "type": "object", "required": [ "x402Version", "resources", "supported" ], "properties": { "x402Version": { "type": "integer", "const": 2 }, "resources": { "type": "array", "items": { "type": "object", "required": [ "url", "method", "description" ], "properties": { "url": { "type": "string", "format": "uri" }, "method": { "type": "string" }, "description": { "type": "string" } } } }, "supported": { "type": "string", "format": "uri" }, "pricing": { "type": "string", "format": "uri" }, "docs": { "type": "string", "format": "uri" } } }, "X402Supported": { "type": "object", "required": [ "kinds", "extensions", "signers" ], "properties": { "kinds": { "type": "array", "items": { "type": "object", "required": [ "x402Version", "scheme", "network" ], "properties": { "x402Version": { "type": "integer", "const": 2 }, "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string", "enum": [ "multiversx:1", "mvx:1", "multiversx:D", "mvx:D" ] }, "extra": { "type": "object", "additionalProperties": true } } } }, "extensions": { "type": "array", "items": { "type": "string" } }, "signers": { "type": "object", "description": "CAIP-2 pattern -> active relayer addresses (fee payers).", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } } }, "X402TopupRequest": { "type": "object", "additionalProperties": false, "required": [ "payer", "amountMicroUsdc" ], "properties": { "payer": { "$ref": "#/components/schemas/Address" }, "beneficiary": { "$ref": "#/components/schemas/Address" }, "amountMicroUsdc": { "$ref": "#/components/schemas/DecimalString" } } }, "X402PurchaseRequest": { "type": "object", "additionalProperties": false, "required": [ "payer", "tierId" ], "properties": { "payer": { "$ref": "#/components/schemas/Address" }, "tierId": { "type": "integer" }, "months": { "type": "integer", "minimum": 0, "maximum": 12, "default": 1 } } }, "X402Requirements": { "type": "object", "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds", "extra" ], "properties": { "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string" }, "amount": { "$ref": "#/components/schemas/DecimalString" }, "asset": { "type": "string", "examples": [ "USDC-c76f1f" ], "description": "Payment token of the serving network, from the contract configuration (`USDC-c76f1f` on mainnet, `USDC-350c4e` on devnet staging)." }, "payTo": { "$ref": "#/components/schemas/Address" }, "maxTimeoutSeconds": { "type": "integer", "const": 120, "description": "Seconds by the x402 standard; the millisecond truth is `extra.quoteExpiresAtMs`." }, "extra": { "type": "object", "required": [ "assetTransferMethod", "paymentFlow", "scFunction", "arguments", "gasLimit", "gasPrice", "relayer", "lease", "leaseExpiresAtMs", "chainId", "quoteId", "quoteMac", "quoteExpiresAtMs", "dataTemplate" ], "properties": { "quoteMac": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "HMAC-SHA256 (base64url) over the canonical JSON (RFC 8785) of this whole requirements object, with\n`extra.quoteMac`, `extra.lease` and `extra.leaseExpiresAtMs` removed.\nOn the paid retry, `accepted` is verified by recomputing this MAC on whichever API host receives\nit, never by lookup. The lease is left out because the server may renew it at the paid retry, and it\ncarries its own HMAC. Domain-separation prefix: `corelayer/x402-quote/v1`. The MAC covers\n`extra.quoteId` and, for plans, the embedded `extra.quote` (which carries its own `quoteMac`).\n" }, "assetTransferMethod": { "type": "string", "const": "esdt" }, "paymentFlow": { "type": "string", "const": "upfront" }, "scFunction": { "type": "string", "enum": [ "deposit", "depositFor", "depositAndSubscribe" ] }, "arguments": { "type": "array", "items": { "type": "string" }, "description": "Hex arguments after the function name." }, "gasLimit": { "type": "integer", "format": "int64" }, "gasPrice": { "type": "integer", "format": "int64", "description": "Equality with minGasPrice on the free purchase flow." }, "relayer": { "$ref": "#/components/schemas/Address" }, "lease": { "type": "string" }, "leaseExpiresAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "registryVersion": { "type": "integer", "format": "int64" }, "expectedNonce": { "type": "integer", "format": "int64" }, "chainId": { "type": "string" }, "quoteId": { "type": "string" }, "quoteExpiresAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "quote": { "$ref": "#/components/schemas/SubscribeQuote" }, "dataTemplate": { "type": "string" }, "name": { "type": "string" }, "decimals": { "type": "integer" } } } } }, "X402PaymentRequired": { "type": "object", "required": [ "x402Version", "resource", "accepts" ], "properties": { "x402Version": { "type": "integer", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "mimeType": { "type": "string" } } }, "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/X402Requirements" } }, "extensions": { "type": "object", "additionalProperties": true } } }, "X402PaymentPayload": { "type": "object", "required": [ "x402Version", "accepted", "payload" ], "properties": { "x402Version": { "type": "integer", "const": 2 }, "resource": { "type": "object", "additionalProperties": true }, "accepted": { "$ref": "#/components/schemas/X402Requirements" }, "payload": { "type": "object", "description": "The signed transaction fields of `TransactionPlain` (relayer set before signing, `relayerSignature` absent) plus optional `validAfter` / `validBefore` (enforced server-side only).", "additionalProperties": true }, "extensions": { "type": "object", "required": [ "payment-identifier" ], "properties": { "payment-identifier": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "minLength": 16, "maxLength": 128 } } } }, "additionalProperties": true } } }, "X402SettlementResponse": { "type": "object", "required": [ "success", "transaction", "network" ], "properties": { "success": { "type": "boolean" }, "errorReason": { "type": "string" }, "payer": { "$ref": "#/components/schemas/Address" }, "transaction": { "type": "string", "description": "Tx hash, empty string on failure." }, "network": { "type": "string" }, "amount": { "$ref": "#/components/schemas/DecimalString" } } }, "X402PurchaseResult": { "type": "object", "required": [ "paymentId", "success" ], "properties": { "paymentId": { "type": "string" }, "success": { "type": "boolean" }, "errorReason": { "type": "string" }, "txHash": { "$ref": "#/components/schemas/TxHash" }, "intentId": { "$ref": "#/components/schemas/IntentId" }, "account": { "$ref": "#/components/schemas/Address" }, "creditedMicroUsdc": { "$ref": "#/components/schemas/DecimalString" }, "quota": { "$ref": "#/components/schemas/Quota" }, "relayEndpoint": { "type": "string", "format": "uri" }, "assignEndpoint": { "type": "string", "format": "uri" } } }, "X402Pending": { "type": "object", "required": [ "status", "paymentId", "transaction", "poll" ], "properties": { "status": { "type": "string", "const": "pending" }, "paymentId": { "type": "string" }, "transaction": { "$ref": "#/components/schemas/TxHash" }, "poll": { "type": "string", "format": "uri" }, "retryAfterMs": { "$ref": "#/components/schemas/DurationMs" } } }, "RelayerStateName": { "type": "string", "enum": [ "registered", "active", "draining", "retired" ] }, "RelayerPublic": { "type": "object", "required": [ "address", "shard", "state", "weight", "operatorId", "slaClass" ], "properties": { "address": { "$ref": "#/components/schemas/Address" }, "shard": { "$ref": "#/components/schemas/Shard" }, "state": { "$ref": "#/components/schemas/RelayerStateName" }, "stateCode": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Frozen on-chain discriminant of `RelayerState`." }, "weight": { "type": "integer" }, "operatorId": { "type": "integer" }, "slaClass": { "type": "integer", "enum": [ 0, 1, 2, 3 ] }, "brandName": { "type": "string" }, "stateChangedAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "retiresAtMs": { "type": [ "integer", "null" ], "format": "int64", "description": "Earliest retirement of a draining relayer (compat deprecation window)." } } }, "RelayerRegistry": { "type": "object", "required": [ "contract", "registryVersion", "relayers" ], "properties": { "contract": { "type": [ "string", "null" ] }, "registryVersion": { "type": "integer", "format": "int64" }, "mirroredAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "relayers": { "type": "array", "items": { "$ref": "#/components/schemas/RelayerPublic" } } } }, "RelayerPublicDetail": { "allOf": [ { "$ref": "#/components/schemas/RelayerPublic" }, { "type": "object", "properties": { "registeredAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "stateHistory": { "type": "array", "items": { "type": "object", "required": [ "state", "atMs" ], "properties": { "state": { "$ref": "#/components/schemas/RelayerStateName" }, "atMs": { "$ref": "#/components/schemas/TimestampMs" }, "txHash": { "$ref": "#/components/schemas/TxHash" } } } }, "served24h": { "type": "integer" }, "served30d": { "type": "integer" }, "inclusionP50Ms": { "type": [ "integer", "null" ] }, "explorerUrl": { "type": "string", "format": "uri" } } } ] }, "ComponentStatus": { "type": "string", "enum": [ "operational", "degraded", "partial_outage", "major_outage", "maintenance" ] }, "ComponentId": { "type": "string", "enum": [ "api", "relay-shard-0", "relay-shard-1", "relay-shard-2", "signer", "gateway-g1", "gateway-g2", "gateway-g3", "chain", "swap-venue", "contract", "settlement", "mcp", "dashboard", "webhooks" ] }, "Status": { "type": "object", "required": [ "status", "updatedAtMs", "components", "shards", "openIncidents" ], "properties": { "status": { "$ref": "#/components/schemas/ComponentStatus" }, "updatedAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "components": { "type": "array", "items": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "$ref": "#/components/schemas/ComponentId" }, "status": { "$ref": "#/components/schemas/ComponentStatus" }, "sinceMs": { "$ref": "#/components/schemas/TimestampMs" } } } }, "shards": { "type": "array", "items": { "$ref": "#/components/schemas/ShardLatency" } }, "availability30d": { "type": [ "number", "null" ], "description": "Measured share of valid relay requests that got BROADCAST or a correct 4xx. Null until 30 days of data exist." }, "availabilityDaily90": { "type": "array", "maxItems": 90, "description": "One entry per UTC day, oldest first: the 90-day bar strip of the status page. `availabilityPct` is the measured value for that day, and null for days without data (before launch, or no valid request).", "items": { "type": "object", "required": [ "dayStartMs", "availabilityPct", "incidents" ], "properties": { "dayStartMs": { "$ref": "#/components/schemas/TimestampMs" }, "availabilityPct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "incidents": { "type": "integer", "minimum": 0, "description": "Published incidents that overlapped the day." } } } }, "latency30d": { "type": "array", "description": "Per shard, measured over the last 30 days (or since `measuredFromMs` when younger). Probe traffic excluded.", "items": { "type": "object", "required": [ "shard", "samples" ], "properties": { "shard": { "$ref": "#/components/schemas/Shard" }, "samples": { "type": "integer" }, "measuredFromMs": { "$ref": "#/components/schemas/TimestampMs" }, "inclusionP50Ms": { "type": [ "integer", "null" ] }, "inclusionP95Ms": { "type": [ "integer", "null" ] }, "inclusionP99Ms": { "type": [ "integer", "null" ] }, "addedP50Ms": { "type": [ "integer", "null" ] }, "addedP99Ms": { "type": [ "integer", "null" ] } } } }, "floatPerShard": { "type": "array", "description": "Health of the relayers' EGLD float per shard, as a **status label only**. Balances and exposure are never published.", "items": { "type": "object", "required": [ "shard", "status" ], "properties": { "shard": { "$ref": "#/components/schemas/Shard" }, "status": { "type": "string", "enum": [ "ok", "low", "critical" ] } } } }, "relays24h": { "type": "integer", "description": "Customer relays in the last 86 400 000 ms (24 hours), without CoRelayer's own health probes." }, "openIncidents": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } } } }, "IncidentStatus": { "type": "string", "enum": [ "investigating", "identified", "monitoring", "resolved" ] }, "IncidentImpact": { "type": "string", "enum": [ "none", "degraded", "partial_outage", "major_outage", "maintenance" ] }, "IncidentUpdateEntry": { "type": "object", "required": [ "atMs", "status", "message", "author" ], "properties": { "atMs": { "$ref": "#/components/schemas/TimestampMs" }, "status": { "$ref": "#/components/schemas/IncidentStatus" }, "message": { "type": "string", "maxLength": 2000 }, "author": { "type": "string", "enum": [ "system", "owner" ] } } }, "Incident": { "type": "object", "required": [ "id", "status", "impact", "source", "components", "shards", "title", "startedAtMs", "updates" ], "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/IncidentStatus" }, "impact": { "$ref": "#/components/schemas/IncidentImpact" }, "source": { "type": "string", "enum": [ "detector", "manual" ] }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentId" } }, "shards": { "type": "array", "items": { "$ref": "#/components/schemas/Shard" } }, "title": { "type": "string", "maxLength": 200 }, "startedAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "detectedAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "publishedAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "resolvedAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "durationMs": { "type": [ "integer", "null" ], "format": "int64" }, "updates": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentUpdateEntry" } }, "metrics": { "type": "object", "properties": { "affectedIntents": { "type": "integer" }, "failedIntents": { "type": "integer" }, "parkedIntents": { "type": "integer" }, "worstInclusionMs": { "type": [ "integer", "null" ] } } } } }, "ServiceState": { "type": "string", "description": "Service state derived by the backend from chain and usage data. There is no matching on-chain flag.", "enum": [ "ACTIVE_CAP", "ACTIVE_PAYG", "RENEWAL_PENDING", "HALTED_CAP", "HALTED_PAYG_EMPTY", "LAPSED", "NO_ACCOUNT", "SUSPENDED" ] }, "BillingClass": { "type": "string", "enum": [ "cap", "payg", "mixed", "free", "internal", "goodwill" ] }, "ExecStatus": { "type": "string", "description": "Execution status of a billed transaction. This enum will not change. A `DEAD` intent is never billed, so `dead` is not a value here; see `UsageStatus`.", "enum": [ "executed_ok", "executed_fail", "invalid" ] }, "UsageStatus": { "type": "string", "description": "Terminal status of a transaction in the usage history: the `ExecStatus` values plus `dead`. `dead`\nmeans it ended without executing (replaced by a cancel, a re-sign or a competing transaction, nonce\nconsumed elsewhere, invalid bytes). A `dead` transaction is never billed; `deadReason` says which case\napplies. `REJECTED` submissions have no status: they appear only with `includeInFlight=true`, as\n`state: REJECTED` + `rejectCode`, with `status` null.\n", "enum": [ "executed_ok", "executed_fail", "invalid", "dead" ] }, "AuthMode": { "type": "string", "enum": [ "own_account", "authorized_sender", "api_key", "free_list", "internal" ] }, "PlanBlock": { "type": "object", "description": "A plan block as the contract stores it (`PlanBlockV1`).", "required": [ "blockId", "tierId", "tier", "kind", "startMs", "endMs", "periodMs", "months", "capRu", "tariffAtPurchase", "paygPriceMicro", "maxSenders", "pricePaidMicro" ], "properties": { "blockId": { "type": "integer", "format": "int64" }, "tierId": { "type": "integer" }, "tier": { "type": "string", "description": "Tier slug." }, "kind": { "type": "string", "enum": [ "New", "Queued", "Upgrade", "AutoRenew" ] }, "startMs": { "$ref": "#/components/schemas/TimestampMs" }, "endMs": { "type": [ "integer", "null" ], "format": "int64", "description": "Null for a no-period (floating) block." }, "periodMs": { "$ref": "#/components/schemas/DurationMs" }, "months": { "type": "integer" }, "capRu": { "$ref": "#/components/schemas/Ru" }, "bonusRu": { "$ref": "#/components/schemas/Ru" }, "tariffAtPurchase": { "$ref": "#/components/schemas/MicroUsdc" }, "paygPriceMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "floating": { "type": "boolean" }, "maxSenders": { "type": "integer" }, "pricePaidMicro": { "$ref": "#/components/schemas/MicroUsdc" } } }, "Account": { "type": "object", "required": [ "address", "accountId", "creditsMicro", "escrowMicro", "flags", "senderCount", "mirror" ], "properties": { "address": { "$ref": "#/components/schemas/Address" }, "accountId": { "type": "integer", "format": "int64" }, "onchainState": { "type": "string", "enum": [ "NONE", "FUNDED", "ACTIVE", "ENDED" ] }, "creditsMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "escrowMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "paygBudgetMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "maxPaygPriceMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "maxRenewPriceMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "renewTierId": { "type": "integer" }, "flags": { "type": "object", "required": [ "autoRenew", "paygEnabled" ], "properties": { "autoRenew": { "type": "boolean" }, "paygEnabled": { "type": "boolean" }, "paygAutoTopup": { "type": "boolean" }, "paygClosing": { "type": "boolean" } } }, "paygDisabledAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "current": { "oneOf": [ { "$ref": "#/components/schemas/PlanBlock" }, { "type": "null" } ] }, "queued": { "oneOf": [ { "$ref": "#/components/schemas/PlanBlock" }, { "type": "null" } ] }, "periodId": { "type": "integer" }, "grant": { "type": "object", "properties": { "ru": { "$ref": "#/components/schemas/Ru" }, "expiryMs": { "$ref": "#/components/schemas/TimestampMs" } } }, "senderCount": { "type": "integer" }, "lastSeq": { "type": "integer", "format": "int64" }, "mirror": { "type": "object", "required": [ "eventSeq", "blockTsMs" ], "properties": { "eventSeq": { "type": "integer", "format": "int64" }, "blockTsMs": { "$ref": "#/components/schemas/TimestampMs" } } } } }, "Quota": { "type": "object", "description": "Quota of an account: service state, current period, cap, grant, PAYG, auto-renew, credits, senders and rate limits.", "required": [ "state", "halted", "chainTimeMs" ], "properties": { "state": { "$ref": "#/components/schemas/ServiceState" }, "halted": { "type": "boolean", "description": "True for HALTED_CAP, HALTED_PAYG_EMPTY, LAPSED, NO_ACCOUNT, SUSPENDED." }, "chainTimeMs": { "$ref": "#/components/schemas/TimestampMs" }, "account": { "$ref": "#/components/schemas/Address", "description": "The account that would be billed." }, "resolvedFrom": { "$ref": "#/components/schemas/AuthMode", "description": "How the billed account was found." }, "period": { "type": "object", "properties": { "id": { "type": "integer" }, "startMs": { "$ref": "#/components/schemas/TimestampMs" }, "endMs": { "type": [ "integer", "null" ], "format": "int64" }, "tier": { "type": "string" }, "tierId": { "type": "integer" } } }, "cap": { "type": "object", "properties": { "ru": { "$ref": "#/components/schemas/Ru" }, "used": { "$ref": "#/components/schemas/Ru" }, "reserved": { "$ref": "#/components/schemas/Ru" }, "left": { "$ref": "#/components/schemas/Ru" }, "bonusLeft": { "$ref": "#/components/schemas/Ru" }, "carryOver": { "$ref": "#/components/schemas/Ru", "description": "Unused cap carried over from the previous plan on an upgrade. It expires with the first period of the new plan." } } }, "grant": { "type": "object", "description": "Owner-granted RU, consumed first.", "properties": { "left": { "$ref": "#/components/schemas/Ru" }, "expiryMs": { "$ref": "#/components/schemas/TimestampMs" } } }, "payg": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "pricePerRuMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "floating": { "type": "boolean" }, "escrowMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "unsettledMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "reservedMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "leftRu": { "$ref": "#/components/schemas/Ru" }, "budgetMicro": { "$ref": "#/components/schemas/MicroUsdc" } } }, "autoRenew": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maxRenewPriceMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "nextPriceMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "predictedOutcome": { "type": "string", "enum": [ "OK", "NOT_DUE", "NOT_ENABLED", "PRICE", "CREDITS", "TIER_INACTIVE", "QUEUED_STARTED", "NO_ACCOUNT", "PAUSED" ], "description": "Outcome that the contract view `quoteRenew` predicts for the next renewal. The values are the contract's nine `RenewOutcome` names in upper snake case (`Ok, NotDue, NotEnabled, Price, Credits, TierInactive, QueuedStarted, NoAccount, Paused`)." } } }, "creditsMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "senders": { "type": "object", "properties": { "count": { "type": "integer" }, "max": { "type": "integer" } } }, "rate": { "$ref": "#/components/schemas/RateClass", "description": "Per-account ceilings of the tier's rate class." }, "settlement": { "type": "object", "properties": { "lastSeq": { "type": "integer", "format": "int64" }, "lastBatchId": { "type": "integer", "format": "int64" }, "lagMs": { "$ref": "#/components/schemas/DurationMs" } } } } }, "AuthorizedSender": { "type": "object", "required": [ "sender", "addedAtMs", "served" ], "properties": { "sender": { "$ref": "#/components/schemas/Address" }, "addedAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "served": { "type": "boolean", "description": "False when the entry is beyond `max_senders` after a downgrade (oldest entries are served)." } } }, "PurchaseKind": { "type": "string", "description": "One value per contract event that moves money or entitlement of an account, plus `carryOver`, which\nthe backend records off-chain when an upgrade carries unused units over. A `carryOver` row carries\nthe `eventSeq` and `txHash` of the `subscribed` event it belongs to.\n`carryApplied` is a reserved on-chain event name that the current contract never emits. It stays in\nthe enum so that a later contract version needs no API change. Open enum.\n", "enum": [ "deposit", "subscribed", "renewed", "autoRenewSkipped", "autoRenewSet", "paygSet", "escrowMoved", "paygSettled", "senderAdded", "senderRemoved", "creditsGranted", "ruGranted", "carryOver", "carryApplied" ] }, "PurchaseEvent": { "type": "object", "required": [ "kind", "eventSeq", "txHash", "timestampMs" ], "properties": { "kind": { "$ref": "#/components/schemas/PurchaseKind" }, "eventSeq": { "type": "integer", "format": "int64" }, "txHash": { "$ref": "#/components/schemas/TxHash" }, "timestampMs": { "$ref": "#/components/schemas/TimestampMs" }, "payer": { "$ref": "#/components/schemas/Address" }, "amountMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "creditsAfterMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "escrowAfterMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "tierId": { "type": "integer" }, "periodId": { "type": "integer" }, "months": { "type": "integer" }, "startMs": { "$ref": "#/components/schemas/TimestampMs" }, "endMs": { "type": [ "integer", "null" ], "format": "int64" }, "tariff": { "$ref": "#/components/schemas/MicroUsdc" }, "reason": { "type": "string", "description": "Skip reason, escrow cause, or grant reason." }, "ref": { "type": "string", "description": "Opaque `ref` of the purchase (quote id), as text when printable." }, "egldOutAtto": { "$ref": "#/components/schemas/AttoEgld", "description": "Deposits only - swap output (public chain fact)." }, "data": { "type": "object", "additionalProperties": true, "description": "Remaining decoded event fields." }, "explorerUrl": { "type": "string", "format": "uri" } } }, "NoticeKind": { "type": "string", "enum": [ "credits.low", "cap.threshold", "cap.reached", "payg.escrow_low", "payg.escrow_empty", "service.halted", "service.resumed", "renewal.upcoming", "renewal.succeeded", "renewal.skipped", "plan.lapsed", "plan.queued_started", "deposit.credited", "grant.received", "grant.expiring", "senders.changed", "tariff.scheduled", "tariff.activated", "tariff.cancelled", "ru_schedule.scheduled", "ru_schedule.activated", "tier.status_changed", "relayer.draining", "incident.opened", "incident.updated", "incident.resolved", "intent.expired_locally", "intent.final", "api_key.created", "api_key.revoked", "webhook.disabled", "webhook.test", "account.suspended" ] }, "Notice": { "type": "object", "required": [ "id", "seq", "kind", "severity", "scope", "createdAtMs", "title", "message" ], "properties": { "id": { "type": "string" }, "seq": { "type": "integer", "format": "int64", "description": "Per-account, strictly increasing." }, "kind": { "$ref": "#/components/schemas/NoticeKind" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "scope": { "type": "string", "enum": [ "account", "global" ] }, "createdAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "effectiveAtMs": { "type": [ "integer", "null" ], "format": "int64", "description": "When the change this notice announces takes effect, in Unix milliseconds, for example the start of a scheduled tariff. Null when the notice announces no change." }, "expiresAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "acknowledgedAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "title": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "links": { "type": "array", "items": { "type": "object", "required": [ "rel", "href" ], "properties": { "rel": { "type": "string" }, "href": { "type": "string", "format": "uri" } } } } } }, "UsageRow": { "type": "object", "description": "One row per transaction hash, from the transaction history joined with the billing ledger. `inFlight`\nrows come from the live intent journal. A slot `(sender, senderNonce)` can therefore appear twice, as\na `dead` row and as the replacement that executed; only the executed hash is billed. `billed = true`\nmeans a ledger row exists for this `txHash`. The **billing members** (`ledgerId`, `periodId`,\n`tariffIdx`, `ruScheduleVersion`, `ruCap`, `ruPayg`, `billingClass`, `paygPriceMicro`,\n`paygDebitMicro`, `settlement`) are null or absent when `billed = false`. A `DEAD` intent is never\nbilled but stays in the history. `ru` is the weight computed when the transaction was accepted, and\nis present on every row.\n", "required": [ "txHash", "sender", "senderNonce", "account", "relayer", "shard", "ru", "billed" ], "properties": { "ledgerId": { "type": [ "integer", "null" ], "format": "int64" }, "billed": { "type": "boolean", "description": "True when this transaction was billed. RU and money totals count only rows with `billed = true`." }, "inFlight": { "type": "boolean" }, "state": { "$ref": "#/components/schemas/IntentState" }, "rejectCode": { "$ref": "#/components/schemas/ErrorCode", "description": "Only on `state: REJECTED` rows (last 30 days, `includeInFlight=true`)." }, "txHash": { "$ref": "#/components/schemas/TxHash" }, "sender": { "$ref": "#/components/schemas/Address" }, "senderNonce": { "type": "integer", "format": "int64" }, "account": { "$ref": "#/components/schemas/Address" }, "authMode": { "$ref": "#/components/schemas/AuthMode" }, "apiKeyId": { "type": [ "string", "null" ] }, "relayer": { "$ref": "#/components/schemas/Address" }, "shard": { "$ref": "#/components/schemas/Shard" }, "receiver": { "$ref": "#/components/schemas/Address" }, "function": { "type": [ "string", "null" ] }, "periodId": { "type": [ "integer", "null" ] }, "tariffIdx": { "type": [ "integer", "null" ] }, "ruScheduleVersion": { "type": [ "integer", "null" ] }, "ru": { "$ref": "#/components/schemas/Ru" }, "ruCap": { "anyOf": [ { "$ref": "#/components/schemas/Ru" }, { "type": "null" } ] }, "ruPayg": { "anyOf": [ { "$ref": "#/components/schemas/Ru" }, { "type": "null" } ] }, "billingClass": { "anyOf": [ { "$ref": "#/components/schemas/BillingClass" }, { "type": "null" } ] }, "paygPriceMicro": { "anyOf": [ { "$ref": "#/components/schemas/MicroUsdc" }, { "type": "null" } ] }, "paygDebitMicro": { "anyOf": [ { "$ref": "#/components/schemas/MicroUsdc" }, { "type": "null" } ] }, "status": { "description": "Null on in-flight and `REJECTED` rows.", "anyOf": [ { "$ref": "#/components/schemas/UsageStatus" }, { "type": "null" } ] }, "deadReason": { "description": "Present only with `status = dead`.", "anyOf": [ { "$ref": "#/components/schemas/DeadReason" }, { "type": "null" } ] }, "gasLimit": { "type": "integer", "format": "int64" }, "gasPrice": { "type": "integer", "format": "int64" }, "dataLen": { "type": "integer" }, "guarded": { "type": "boolean" }, "maxFeeAtto": { "$ref": "#/components/schemas/AttoEgld" }, "feePaidAtto": { "$ref": "#/components/schemas/AttoEgld" }, "gasUsed": { "type": "integer", "format": "int64" }, "blockNonce": { "type": "integer", "format": "int64" }, "blockHash": { "$ref": "#/components/schemas/Hex32" }, "executedBlockTsMs": { "$ref": "#/components/schemas/TimestampMs", "description": "Chain time of the executing block. On a `dead` row - which has no executing block - the chain time (sender shard) at which the intent was decided terminal, so the keyset order `(executedBlockTsMs DESC, txHash DESC)` stays total; `blockNonce` / `blockHash` are absent there." }, "receivedAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "cosignedAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "broadcastAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "finalizedAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "latency": { "$ref": "#/components/schemas/LatencyBreakdown" }, "recovered": { "type": "boolean" }, "late": { "type": "boolean" }, "settlement": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "not_applicable", "unsettled", "settled", "written_off" ] }, "batchId": { "type": [ "integer", "null" ], "format": "int64" }, "seq": { "type": [ "integer", "null" ], "format": "int64" }, "rootBatchId": { "type": [ "integer", "null" ], "format": "int64", "description": "Batch whose `usage_root` commits this row." } } }, "duringIncidents": { "type": "array", "items": { "type": "string" } }, "explorerUrl": { "type": "string", "format": "uri" } } }, "UsageSummary": { "type": "object", "required": [ "account", "periodId", "totals", "buckets" ], "properties": { "account": { "$ref": "#/components/schemas/Address" }, "periodId": { "type": "integer" }, "periodStartMs": { "$ref": "#/components/schemas/TimestampMs" }, "periodEndMs": { "type": [ "integer", "null" ], "format": "int64" }, "capRu": { "$ref": "#/components/schemas/Ru" }, "totals": { "type": "object", "properties": { "txCount": { "type": "integer" }, "failCount": { "type": "integer" }, "ruCap": { "$ref": "#/components/schemas/Ru" }, "ruPayg": { "$ref": "#/components/schemas/Ru" }, "ruGrant": { "$ref": "#/components/schemas/Ru" }, "paygDebitMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "settledMicro": { "$ref": "#/components/schemas/MicroUsdc" }, "capUsedPct": { "type": "number" }, "projectedCapExhaustionMs": { "type": [ "integer", "null" ], "format": "int64", "description": "Linear projection from the last 7 days; null when the cap is not projected to run out inside the period." }, "inclusionP50Ms": { "type": [ "integer", "null" ] }, "inclusionP95Ms": { "type": [ "integer", "null" ] }, "inclusionP99Ms": { "type": [ "integer", "null" ] }, "txCountByStatus": { "type": "object", "description": "Number of rows per terminal status, unbilled rows included. `txCount`, RU and money totals count billed rows only.", "properties": { "executed_ok": { "type": "integer" }, "executed_fail": { "type": "integer" }, "invalid": { "type": "integer" }, "dead": { "type": "integer" }, "rejected": { "type": "integer" } } } } }, "topSenders": { "type": "array", "maxItems": 10, "description": "Top 10 senders of the window by RU (billed rows).", "items": { "$ref": "#/components/schemas/UsageTopEntry" } }, "topReceivers": { "type": "array", "maxItems": 10, "description": "Top 10 receivers of the window by RU (billed rows).", "items": { "$ref": "#/components/schemas/UsageTopEntry" } }, "bucket": { "type": "string", "enum": [ "hour", "day" ] }, "buckets": { "type": "array", "items": { "type": "object", "required": [ "startMs", "txCount", "ru" ], "properties": { "startMs": { "$ref": "#/components/schemas/TimestampMs" }, "txCount": { "type": "integer" }, "failCount": { "type": "integer" }, "ru": { "$ref": "#/components/schemas/Ru" }, "ruPayg": { "$ref": "#/components/schemas/Ru" }, "inclusionP50Ms": { "type": [ "integer", "null" ] }, "inclusionP95Ms": { "type": [ "integer", "null" ] }, "inclusionP99Ms": { "type": [ "integer", "null" ] } } } } } }, "UsageTopEntry": { "type": "object", "required": [ "address", "txCount", "ru" ], "properties": { "address": { "$ref": "#/components/schemas/Address" }, "txCount": { "type": "integer" }, "ru": { "$ref": "#/components/schemas/Ru" }, "failCount": { "type": "integer" } } }, "UsageLatency": { "type": "object", "description": "Grouped latency analytics (`GET /v1/usage/latency`), built from pre-aggregated latency histograms.\nOnly measured values are returned. Percentile members are null when a group has fewer than\n20 samples, because a percentile of a handful of points says little.\n", "required": [ "account", "window", "groupBy", "fromMs", "toMs", "groups" ], "properties": { "account": { "$ref": "#/components/schemas/Address" }, "window": { "type": "string", "enum": [ "1h", "24h", "7d", "30d" ] }, "groupBy": { "type": "string", "enum": [ "shard", "relayer", "sender", "gateway" ] }, "fromMs": { "$ref": "#/components/schemas/TimestampMs" }, "toMs": { "$ref": "#/components/schemas/TimestampMs" }, "sloTargetInclusionP99Ms": { "type": [ "integer", "null" ], "description": "Published SLO target, when one is published; else null." }, "groups": { "type": "array", "items": { "type": "object", "required": [ "key", "count", "inclusion", "added", "bins", "samples" ], "properties": { "key": { "type": "string", "description": "Shard number, relayer address, sender address, or gateway id (`G1`, `G2`, `G2b`, `G3`) = the gateway of the first acknowledgement." }, "label": { "type": "string", "description": "Display label (relayer brand name, shard name). Text, never HTML." }, "count": { "type": "integer" }, "inclusion": { "$ref": "#/components/schemas/LatencyPercentiles" }, "added": { "$ref": "#/components/schemas/LatencyPercentiles" }, "bins": { "type": "array", "description": "Server-side histogram of `inclusionMs`; `count` = samples with `inclusionMs <= leMs` and above the previous bin. The last bin has `leMs = null` (overflow).", "items": { "type": "object", "required": [ "leMs", "count" ], "properties": { "leMs": { "type": [ "integer", "null" ] }, "count": { "type": "integer" } } } }, "samples": { "type": "array", "maxItems": 48, "description": "Sampled points for the strip plot (reservoir sample kept in the rollup; at most 48 per group).", "items": { "type": "object", "required": [ "atMs", "inclusionMs", "txHash" ], "properties": { "atMs": { "$ref": "#/components/schemas/TimestampMs" }, "inclusionMs": { "type": "integer" }, "txHash": { "$ref": "#/components/schemas/TxHash" } } } } } } } } }, "LatencyPercentiles": { "type": "object", "properties": { "p50Ms": { "type": [ "integer", "null" ] }, "p95Ms": { "type": [ "integer", "null" ] }, "p99Ms": { "type": [ "integer", "null" ] } } }, "Me": { "type": "object", "description": "Login-routing read model (`GET /v1/me`).", "required": [ "address", "shard", "accounts" ], "properties": { "address": { "$ref": "#/components/schemas/Address" }, "shard": { "$ref": "#/components/schemas/Shard" }, "accounts": { "type": "array", "description": "The address's own account first (when it exists), then the accounts that authorised it as a sender, oldest authorisation first.", "items": { "type": "object", "required": [ "erd", "role" ], "properties": { "erd": { "$ref": "#/components/schemas/Address" }, "role": { "type": "string", "enum": [ "owner", "sender" ] } } } } } }, "UsageProof": { "type": "object", "required": [ "txHash", "batchId", "usageRoot", "leafHash", "leaf", "path", "settleTxHash" ], "properties": { "txHash": { "$ref": "#/components/schemas/TxHash" }, "batchId": { "type": "integer", "format": "int64" }, "windowEndMs": { "$ref": "#/components/schemas/TimestampMs" }, "usageRoot": { "$ref": "#/components/schemas/Hex32" }, "usageChainHead": { "$ref": "#/components/schemas/Hex32" }, "settleTxHash": { "$ref": "#/components/schemas/TxHash", "description": "The `settleUsage` transaction whose `usageSettled` event carries the root." }, "leafHash": { "$ref": "#/components/schemas/Hex32" }, "leaf": { "type": "object", "description": "Preimage fields of the leaf, in hashing order (leaf = sha256(0x00 || ...)). See https://docs.co-relayer.com/contract/usage-proofs.", "additionalProperties": true }, "path": { "type": "array", "items": { "type": "object", "required": [ "side", "hash" ], "properties": { "side": { "type": "string", "enum": [ "left", "right" ] }, "hash": { "$ref": "#/components/schemas/Hex32" } } } } } }, "ServingRelayer": { "type": "object", "required": [ "address", "shard", "state", "txCount", "lastServedAtMs" ], "properties": { "address": { "$ref": "#/components/schemas/Address" }, "shard": { "$ref": "#/components/schemas/Shard" }, "state": { "$ref": "#/components/schemas/RelayerStateName" }, "brandName": { "type": "string" }, "txCount": { "type": "integer" }, "failCount": { "type": "integer" }, "ru": { "$ref": "#/components/schemas/Ru" }, "firstServedAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "lastServedAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "sharePct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Share of the account's served transactions in the window." }, "failRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "`failCount / txCount`; null when `txCount` = 0." }, "inclusionP50Ms": { "type": [ "integer", "null" ] }, "inclusionP95Ms": { "type": [ "integer", "null" ] }, "weeklyRanks": { "type": "array", "description": "Rank of this relayer by served count among the account's relayers, per ISO week of the window (bump chart). Rank 1 = most served; weeks without traffic are omitted.", "items": { "type": "object", "required": [ "weekStartMs", "rank" ], "properties": { "weekStartMs": { "$ref": "#/components/schemas/TimestampMs" }, "rank": { "type": "integer", "minimum": 1 }, "txCount": { "type": "integer" } } } }, "currentAssignment": { "type": "boolean", "description": "True when the rendezvous hash currently maps one of the account's senders to this relayer." }, "explorerUrl": { "type": "string", "format": "uri" } } }, "AccountOutage": { "type": "object", "required": [ "incident", "affectedIntents" ], "properties": { "incident": { "$ref": "#/components/schemas/Incident" }, "affectedIntents": { "type": "integer", "description": "Intents of this account received while the incident was open on an affected shard." }, "failedRequests": { "type": "integer", "description": "Requests answered 5xx." }, "parkedIntents": { "type": "integer" }, "slowIntents": { "type": "integer", "description": "Inclusion above the published p99 target." }, "worstInclusionMs": { "type": [ "integer", "null" ] } } }, "ApiKeyPolicy": { "type": "object", "additionalProperties": false, "properties": { "receiverAllowList": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Address" }, "description": "Contracts your users may call at your expense. Required and non-empty for scope `relay`." }, "functionAllowList": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, "maxRuPerSenderPerDay": { "$ref": "#/components/schemas/Ru" }, "maxRuPerDay": { "$ref": "#/components/schemas/Ru" }, "ipAllowList": { "type": "array", "maxItems": 20, "items": { "type": "string", "description": "CIDR." } } } }, "ApiKey": { "type": "object", "required": [ "keyId", "label", "scopes", "policy", "createdAtMs", "status" ], "properties": { "keyId": { "type": "string" }, "label": { "type": "string", "maxLength": 80 }, "prefix": { "type": "string", "description": "`crk_live__` plus the first 4 secret characters." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "relay", "read" ] } }, "policy": { "$ref": "#/components/schemas/ApiKeyPolicy" }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "createdAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "lastUsedAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "revokedAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "ruToday": { "$ref": "#/components/schemas/Ru" } } }, "ApiKeyCreate": { "type": "object", "additionalProperties": false, "required": [ "label", "scopes" ], "properties": { "label": { "type": "string", "maxLength": 80 }, "scopes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "relay", "read" ] } }, "policy": { "$ref": "#/components/schemas/ApiKeyPolicy" } } }, "ApiKeyUpdate": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string", "maxLength": 80 }, "policy": { "$ref": "#/components/schemas/ApiKeyPolicy" } } }, "ApiKeyCreated": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "Full key `crk___`. Shown once." } } } ] }, "Webhook": { "type": "object", "required": [ "webhookId", "url", "events", "enabled", "createdAtMs" ], "properties": { "webhookId": { "type": "string" }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/NoticeKind" } }, "enabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ] }, "createdAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "lastSuccessAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "lastFailureAtMs": { "type": [ "integer", "null" ], "format": "int64" }, "consecutiveFailures": { "type": "integer" } } }, "WebhookCreate": { "type": "object", "additionalProperties": false, "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https://" }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/NoticeKind" } } } }, "WebhookUpdate": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https://" }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/NoticeKind" } }, "enabled": { "type": "boolean" } } }, "WebhookCreated": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "`whsec_` + 43 base64url characters. Shown once." } } } ] }, "WebhookDelivery": { "type": "object", "required": [ "deliveryId", "eventId", "kind", "attempt", "atMs", "outcome" ], "properties": { "deliveryId": { "type": "string" }, "eventId": { "type": "string" }, "kind": { "$ref": "#/components/schemas/NoticeKind" }, "attempt": { "type": "integer" }, "atMs": { "$ref": "#/components/schemas/TimestampMs" }, "outcome": { "type": "string", "enum": [ "delivered", "http_error", "timeout", "tls_error", "dns_error", "blocked_address", "redirect_refused" ] }, "httpStatus": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "nextAttemptAtMs": { "type": [ "integer", "null" ], "format": "int64" } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "apiVersion", "network", "account", "seq", "createdAtMs", "data" ], "properties": { "id": { "type": "string", "description": "Stable across retries; de-duplication key." }, "type": { "$ref": "#/components/schemas/NoticeKind" }, "apiVersion": { "type": "string", "const": "v1" }, "network": { "type": "string", "enum": [ "mvx:1", "mvx:D" ] }, "account": { "$ref": "#/components/schemas/Address" }, "seq": { "type": "integer", "format": "int64" }, "createdAtMs": { "$ref": "#/components/schemas/TimestampMs" }, "data": { "description": "`Notice` for notice kinds, `Intent` for `intent.*`, `Incident` for `incident.*`.", "oneOf": [ { "$ref": "#/components/schemas/Notice" }, { "$ref": "#/components/schemas/Intent" }, { "$ref": "#/components/schemas/Incident" } ] } } }, "NotificationPrefs": { "type": "object", "required": [ "thresholds", "kinds", "email" ], "properties": { "thresholds": { "type": "object", "properties": { "capPct": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 100 }, "default": [ 80, 100 ] }, "creditsLowMicro": { "$ref": "#/components/schemas/MicroUsdc", "description": "0 = automatic (credits below the next renewal price)." }, "escrowLowPct": { "type": "integer", "default": 20 }, "renewalUpcomingMs": { "$ref": "#/components/schemas/DurationMs", "description": "Default 259 200 000 (72 h)." } } }, "kinds": { "type": "object", "description": "Per-kind switch. `tariff.scheduled`, `renewal.skipped`, `service.halted` cannot be switched off for the notices feed.", "additionalProperties": { "type": "boolean" } }, "email": { "type": "object", "required": [ "status" ], "properties": { "address": { "type": [ "string", "null" ], "format": "email" }, "status": { "type": "string", "enum": [ "none", "pending", "verified" ] }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/NoticeKind" } } } } } }, "NotificationPrefsUpdate": { "type": "object", "additionalProperties": false, "properties": { "thresholds": { "type": "object", "additionalProperties": true }, "kinds": { "type": "object", "additionalProperties": { "type": "boolean" } }, "email": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": [ "string", "null" ], "format": "email" }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/NoticeKind" } } } } } }, "StreamTopic": { "type": "string", "enum": [ "intent", "quota", "account", "notice", "incident", "pricing" ] }, "StreamEventId": { "type": "string", "pattern": "^[ab]\\.[0-9]{13}\\.[0-9]+$", "description": "SSE `id:` / `Last-Event-ID` = `..`: `hostId` = `a` | `b` (core host),\n`bootEpoch` = start of that API process in Unix ms, `seq` = per-account\nsequence on that host. A host that receives an id with a foreign `hostId` or an older `bootEpoch`\nalways answers with `event: reset` first - it never compares `seq` values across hosts or boots.\n", "examples": [ "a.1789000000000.4127" ] }, "StreamEvent": { "type": "object", "description": "`data:` of one frame of `GET /v1/stream`. The frame's `id:` line is a `StreamEventId`; `seq` repeats\nits last component. Events are hints to refetch or patch - the REST read models stay authoritative;\n`reset` means refetch all of them.\n", "required": [ "topic", "seq", "atMs", "data" ], "properties": { "topic": { "type": "string", "enum": [ "intent", "quota", "account", "notice", "incident", "pricing", "reset" ] }, "id": { "$ref": "#/components/schemas/StreamEventId" }, "seq": { "type": "integer", "format": "int64" }, "atMs": { "$ref": "#/components/schemas/TimestampMs" }, "data": { "description": "The payload, chosen by `topic`: an `Intent`, `Quota`, `Account`, `Notice` or `Incident`, the pricing tariff object, or `{}` for `reset`.", "anyOf": [ { "$ref": "#/components/schemas/Intent" }, { "$ref": "#/components/schemas/Quota" }, { "$ref": "#/components/schemas/Account" }, { "$ref": "#/components/schemas/Notice" }, { "$ref": "#/components/schemas/Incident" }, { "type": "object", "additionalProperties": true } ] } } } } } }