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.
https://retracer-api.arxium.networkQuickstart
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
| Method | Path | Description |
|---|---|---|
| GET | /v1/chains | The chains this key can reach. |
| GET | /v1/chains/{chain}/status | Indexed height against the node's tip, and how far behind the index is. |
| GET | /v1/chains/{chain}/stats | Chain-wide counters. |
| GET | /v1/chains/{chain}/proposers | Block proposers. |
Blocks & actions
| Method | Path | Description |
|---|---|---|
| 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.
| Method | Path | Description |
|---|---|---|
| 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=NEvery block. The event id is the height.
/v1/chains/{chain}/actions/stream?from_height=N&address=AActions, optionally only those touching an address. The event id is height:index.
/v1/chains/{chain}/actions/dropped/stream?from_height=N&address=ARejected 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 withfrom_heightset to the last height you handled, plus one.actions/streamandactions/dropped/stream: a block can hold several events, and a stream can end between two of them. Reconnect withfrom_heightset 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 lastheight: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:
| Header | Meaning |
|---|---|
| Retry-After | Seconds to wait. After that, the budget is always back. |
| X-RateLimit-Limit | Requests allowed per window for this key's plan. |
| X-RateLimit-Remaining | 0 on a 429. |
| X-RateLimit-Reset | Seconds 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.
| Status | error | Meaning |
|---|---|---|
| 401 | missing Authorization: Bearer <key> | No bearer token was sent. |
| 401 | unknown or revoked API key | The key doesn't exist or was revoked. Revocation takes effect within about a minute. |
| 403 | this key is for A, not B | The key was issued for a different chain than the one in the path. |
| 404 | no such route on this gateway | The path isn't under /v1/chains or /rpc. |
| 429 | rate limit exceeded | The key's request budget for this window is spent. Wait Retry-After seconds. |
| 429 | already holding N of N concurrent streams | The key holds as many open streams as its plan allows. Close one first. |
| 502 | upstream unavailable | The indexer or node didn't answer. Safe to retry with backoff. |
| 503 | no 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.