Explorer API
The explorer API is a read-only Rust/Axum service. It reads the live public lab devnet through one relay, the reference API node. Responses report meta.mode: "live" and meta.source: "node". The network has no value and may be reset. The explorer reflects one relay’s view and is not a source of truth for exchanges or custody. It does not sign or broadcast transactions.
Try a request in the API playground →
Run the API
Section titled “Run the API”From the explorer repository, set ICEROOT_RELAY to the relay API base URL, including /api. Independently verify the intended network and set ICEROOT_NETHASH to its 64-digit hex hash from /node/configuration. Then run:
cargo run --locked --manifest-path backend/Cargo.tomlThe default origin is http://127.0.0.1:3188. The API allows browser requests from the local docs origins. For a hosted docs site, set ICEROOT_API_CORS_ORIGINS to its exact origin; the explorer README describes the configuration. The Next.js frontend proxies the supported read-only /api/v1/ resource routes. Its browsers use the same origin. Cross-origin clients need an explicitly allowed origin.
Expose the API publicly only through a reverse proxy with header-read and idle timeouts, connection limits and per-client request limits. Keep the API listener private so clients cannot bypass them. The application timeout starts after request headers are parsed and does not limit how long a client takes to send them.
curl --fail 'http://127.0.0.1:3188/api/v1/validators?status=active&limit=10'Endpoints
Section titled “Endpoints”| Path | Returns |
|---|---|
/healthz | Process health and chain-connection status |
/api/v1/status | Mode, recorded height range, and counts |
/api/v1/snapshot | Complete explorer data and configuration |
/api/v1/blocks | Blocks, newest first |
/api/v1/transactions | Recorded transactions |
/api/v1/validators | Validators in rank order |
/api/v1/assets | Available asset records; multi-asset features are unavailable on this network |
/api/v1/accounts/{address} | Wallet balances, transactions and votes; the account list returns 404 because there is no account index |
/api/v1/migrations | Empty collection on this network |
/api/v1/routes | Empty collection on this network |
/api/v1/search?q=... | Search across resource collections |
Blocks, transactions, validators, assets and accounts have detail routes: append the record identifier, for example /api/v1/blocks/20416. Encode identifiers when constructing URLs.
Pagination and filtering
Section titled “Pagination and filtering”Lists support q, limit, and offset. The default page is limit=25&offset=0; limits range from 1 to 100. Offsets range from 0 to 1,000,000.
| Collection | Additional filters |
|---|---|
| Blocks | validator |
| Transactions | asset, account, validator, type, block |
| Validators | status=active|standby|resigned |
| Assets | origin=created|migrated |
| Migrations | asset, account, direction=in|out, route, state=0..3 |
Unknown parameters and invalid filter values return 400. Search requires a nonempty q, limited to 256 UTF-8 bytes.
Response shape
Section titled “Response shape”{ "data": [], "pagination": { "limit": 25, "offset": 0, "total": 0, "hasMore": false }, "meta": { "mode": "live", "source": "node", "network": "devnet", "updatedAt": null }}The response envelope depends on the endpoint:
- List:
data,pagination, andmeta. - Single record:
dataandmeta. - Snapshot:
data,config, andmeta. - Health: a small top-level object.
Successful metadata also includes the height, a UTC updatedAt timestamp, and identity, including the pinned nethash, network name, token, symbol and profile. A network change returns network_mismatch; there is no automatic chain switch. The JSON above illustrates the envelope, not a fetched response.
Pagination can include totalIsEstimate and complete. When complete is false, a bounded scan did not examine older records. Counts are not proof of complete chain history.
The backend refreshes about every 30 seconds by default. A tip older than 60 seconds is labelled stale in the explorer. Failed refreshes return 503; the browser retains previously received records and reports the disconnection. Six confirmations is the default depth for a confirmed label, not finality. Blocks and transactions remain not final on this chain.
Amounts are decimal strings. Preserve their precision instead of converting them to JavaScript floating-point numbers. A null updatedAt is not a freshness timestamp.
Errors
Section titled “Errors”| Status | Meaning |
|---|---|
400 | Invalid query parameter or filter |
404 | No matching record |
405 | Unsupported HTTP method |
429 | Read budget exhausted; respect Retry-After |
503 | Relay unavailable, network mismatch, or request timeout |
Backend errors contain error.code, error.message, and meta.mode. Web proxy errors may omit metadata. The public web proxy forwards status, snapshot, search, blocks, transactions, validators, assets and accounts. Health, config, migration and route endpoints require the standalone backend.
Handle API failure explicitly. Never turn a failed request into a zero balance or silently replace it with client-side fixtures.