Explorer API

The explorer API is a read-only Rust/Axum service. Its current dataset is a deterministic sample ledger; successful responses identify it with meta.mode: "demo". It does not sign or broadcast transactions.

Try a request in the API playground →

Run the API

From the explorer repository:

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 only /api/v1/snapshot.

curl --fail 'http://127.0.0.1:3188/api/v1/validators?status=active&limit=10'

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	Distinct assets
/api/v1/accounts	Recorded accounts
/api/v1/migrations	Migration records
/api/v1/routes	Sample migration routes
/api/v1/search?q=...	Search across resource collections

Each collection also has a detail route: append its identifier, for example /api/v1/blocks/20416. Encode identifiers when constructing URLs.

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

{
  "data": [],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 0,
    "hasMore": false
  },
  "meta": {
    "mode": "demo",
    "source": "bundled-fixtures",
    "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.

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

Status	Meaning
400	Invalid query parameter or filter
404	No matching record
405	Unsupported HTTP method

Errors contain error.code, error.message, and meta.mode.

Handle API failure explicitly. Never turn a failed request into a zero balance or silently replace it with client-side fixtures.