Explorer data semantics¶
Canonical chain identity¶
GET /api/v1/status returns chain_id and genesis (hash). Pin both; an explorer for another network will differ.
client is the node's web3_clientVersion.
Freshness¶
| Field | Meaning |
|---|---|
indexed_tip |
Highest block in the explorer database |
node_head |
Head reported by the node right now (null if unreachable) |
lag_blocks |
node_head − indexed_tip |
Indexed data (blocks, transactions, tokens, issuance, events) is as of indexed_tip. /address/{address}.balance_wei
is read live from the node at latest.
Reorganisations and finality¶
- The indexer follows the heaviest chain; when a heavier branch replaces non-finalized blocks it rewrites them and
records the reorganisation (
reorgs_handled). - A reorganisation below the recorded finalized checkpoint is never applied: the indexer raises a
finality_violationalarm (visible in/status.alarms) and stops indexing. That would indicate a consensus fault. - Treat everything above
finalized_heightas reversible.
Pagination and size limits¶
API v1 has no cursor or page parameters; query strings are ignored. Each list is a fixed newest-first window:
| Endpoint | Window |
|---|---|
/blocks |
25 blocks |
/issuance |
50 blocks |
/checkpoints |
100 observations |
/ai/events |
500 events |
/address/{address} |
50 transactions + 50 token transfers |
/mining |
statistics over 64 blocks |
For complete history use JSON-RPC (eth_getLogs in ≤ 5000-block ranges) or run your own explorer database.
Amounts and types¶
Wei and gwei values that may exceed 2^53 are decimal strings. Block numbers, timestamps (Unix seconds), gas and counts are integers. Addresses in responses are lower-case.
Errors¶
| HTTP | Body | When |
|---|---|---|
| 400 | {"error": "<message ≤ 200 chars>"} |
Path value not decimal or 0x-hex |
| 404 | {"error": "not found"} |
Unknown block/transaction, unknown route |
Every response carries Content-Type: application/json; charset=utf-8, X-Content-Type-Options: nosniff and a
restrictive Content-Security-Policy.
Sources at 72057fe3ec: explorer/openapi.yaml · explorer/pqwexplorer/web.py · explorer/README.md
Found a problem? Report a documentation issue · Build testnet-rc1+72057fe3ec