Retracer Cloud

Documentation

API reference

One base URL fronts indexed history, live streams and node RPC for every Arxium chain. An application needs one credential, not an indexer URL, a node URL and a key for each.

Base URLhttps://retracer-api.arxium.network

Quickstart

Create a key, put it in RETRACER_KEY, and ask for the chain's status. If blocks_behind is small, the index is caught up and every other route is ready to use.

curl -H "Authorization: Bearer $RETRACER_KEY" \
  "https://retracer-api.arxium.network/v1/chains/corechain-devnet/status"

Authentication

Send the key as a bearer token on every request: Authorization: Bearer rk_…. A key is issued for one chain, and using it on another returns 403. Only a key's SHA-256 is stored, so it is shown once, when you create it.

Keep keys on your servers. A key in a browser or mobile app is readable by anyone who has the app, and the gateway sends no CORS headers for that reason.

Indexed data

Everything under /v1/chains/{chain} is answered by Retracer, the Arxium indexer. All routes are GET. Paged routes take limit and a before… cursor from the last item of the previous page.

Chain

MethodPathDescription
GET/v1/chainsThe chains this key can reach.
GET/v1/chains/{chain}/statusIndexed height against the node's tip, and how far behind the index is.
GET/v1/chains/{chain}/statsChain-wide counters.
GET/v1/chains/{chain}/proposersBlock proposers.

Blocks & actions

MethodPathDescription
GET/v1/chains/{chain}/blocks?limit=&before=Indexed blocks, newest first, paginated.
GET/v1/chains/{chain}/blocks/{height|hash}One block.
GET/v1/chains/{chain}/actions?limit=&before_height=&before_index=&kind=&field=&value=Actions, filtered by kind or a field value.
GET/v1/chains/{chain}/actions/{action_hash}One action.
GET/v1/chains/{chain}/accounts/{address}/actions?limit=&role=One account's action history. role=from (sent, the default), to (received), or from,to for both in one page. Every action carries its block_timestamp.
GET/v1/chains/{chain}/search?q=Look up a height, hash or address.

State by height

Add at=H to read state as of block H; the default is the tip. Amounts are decimal strings, since the chain's u128 doesn't fit a JSON number.

MethodPathDescription
GET/v1/chains/{chain}/accounts/{address}?at=Balance, nonce, identity, asset holdings and stakes.
GET/v1/chains/{chain}/assets/{asset}/holders?at=&jurisdiction=&after=&limit=An asset's non-zero holders with compliance state.
GET/v1/chains/{chain}/validators/{address}Status, voting power, history, operator and slashes.
GET/v1/chains/{chain}/validators/uptime?from=&to=Validator uptime over a height range.
GET/v1/chains/{chain}/attestors?at=Registered attestors.
GET/v1/chains/{chain}/actions/dropped?sender=&before_height=&before_signature=&limit=Actions the producer rejected, with the reason.

Streaming

Three routes stream instead of paging: plain GETs answering text/event-stream, one JSON row per data: line, in the same shapes the paged routes return.

  • /v1/chains/{chain}/blocks/stream?from_height=N

    Every block. The event id is the height.

  • /v1/chains/{chain}/actions/stream?from_height=N&address=A

    Actions, optionally only those touching an address. The event id is height:index.

  • /v1/chains/{chain}/actions/dropped/stream?from_height=N&address=A

    Rejected actions, as the producer drops them. The event id is height:signature.

from_height is inclusive: it replays from storage, starting at that height, up to the tip, then continues live. Streams end: each lasts at most an hour, and a client that falls behind is cut off. Keep a cursor and reconnect with it; that cursor is what guarantees nothing is missed and nothing is handled twice.

  • blocks/stream: one event per height. Reconnect with from_height set to the last height you handled, plus one.
  • actions/stream and actions/dropped/stream: a block can hold several events, and a stream can end between two of them. Reconnect with from_height set to the last height you handled, not plus one, and skip the events you already handled at that height: those whose id is at or before your last height:index (actions), or whose signature you handled at that height (dropped).

Idle streams get a keep-alive comment every 15 seconds. Streams are capped by how many a key holds open at once, not by the request budget. The examples below resume an actions stream that way.

# One stream. When it ends, reconnect with from_height = the height of the
# last event you handled, and skip the ids you already handled.
curl -N -H "Authorization: Bearer $RETRACER_KEY" \
  "https://retracer-api.arxium.network/v1/chains/corechain-devnet/actions/stream?from_height=0"

Node RPC

/rpc/{chain}/… passes through to the chain's node with the prefix removed, for live state and submitting transactions. It uses the same key and the same budget as indexed data, so an application needs no node URL or node credential of its own.

Rate limits

Each key has a request budget over a 10-second window, set by its plan. Budgets are enforced per Cloudflare location and can overshoot slightly before the first 429. When the budget is spent the response is a 429 with:

HeaderMeaning
Retry-AfterSeconds to wait. After that, the budget is always back.
X-RateLimit-LimitRequests allowed per window for this key's plan.
X-RateLimit-Remaining0 on a 429.
X-RateLimit-ResetSeconds until the budget is back: an upper bound of one window.

Errors

Errors from the gateway are JSON: {"error": "…"}. Anything else comes from the indexer or node unchanged.

StatuserrorMeaning
401missing Authorization: Bearer <key>No bearer token was sent.
401unknown or revoked API keyThe key doesn't exist or was revoked. Revocation takes effect within about a minute.
403this key is for A, not BThe key was issued for a different chain than the one in the path.
404no such route on this gatewayThe path isn't under /v1/chains or /rpc.
429rate limit exceededThe key's request budget for this window is spent. Wait Retry-After seconds.
429already holding N of N concurrent streamsThe key holds as many open streams as its plan allows. Close one first.
502upstream unavailableThe indexer or node didn't answer. Safe to retry with backoff.
503no healthy Retracer for …Every indexer for the chain is failing its health check. See the status page.

Coming soon

SDKs Soon

TypeScript and Python clients with typed responses, streams and 429 handling built in.

OpenAPI through the gateway Soon

Retracer publishes an OpenAPI 3.1 document; serving it here lets you generate a client.

Multi-chain keys Soon

One key for several chains, for applications that span them.