Skip to content
IceRootDocs

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 →

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:

Terminal window
cargo run --locked --manifest-path backend/Cargo.toml

The 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.

Terminal window
curl --fail 'http://127.0.0.1:3188/api/v1/validators?status=active&limit=10'
PathReturns
/healthzProcess health and chain-connection status
/api/v1/statusMode, recorded height range, and counts
/api/v1/snapshotComplete explorer data and configuration
/api/v1/blocksBlocks, newest first
/api/v1/transactionsRecorded transactions
/api/v1/validatorsValidators in rank order
/api/v1/assetsAvailable 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/migrationsEmpty collection on this network
/api/v1/routesEmpty 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.

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.

CollectionAdditional filters
Blocksvalidator
Transactionsasset, account, validator, type, block
Validatorsstatus=active|standby|resigned
Assetsorigin=created|migrated
Migrationsasset, 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.

{
"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, and meta.
  • Single record: data and meta.
  • Snapshot: data, config, and meta.
  • 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.

StatusMeaning
400Invalid query parameter or filter
404No matching record
405Unsupported HTTP method
429Read budget exhausted; respect Retry-After
503Relay 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.