Skip to content
ReferenceTestnet: yesMainnet: Not availableSoftware: Core bad4a06ea · protocol pqwerai-v8-testnet/1Updated

Explorer REST reference

Served by explorer/pqwexplorer/web.py from the indexed, reorganisation-safe database. Every endpoint is GET, unauthenticated and read-only. This schema is the contract tested by scripts/devhub/explorer_contract_test.py; an endpoint absent from it does not exist.

Canonical chain identity. GET /status returns chain_id and genesis; clients must pin both.

Freshness. Data comes from the indexed tip (indexed_tip). lag_blocks = node_head - indexed_tip. Account balances (/address/{address}) are read live from the node at latest; everything else is indexed.

Reorganisations. The indexer replaces non-finalized blocks when a heavier branch wins (records in reorgs_handled). A reorganisation below the recorded finalized checkpoint is never applied: the indexer records a finality_violation alarm (/status.alarms) and stops. Treat data above finalized_height as reversible.

Pagination and size limits. API v1 has no cursor or page parameters. List endpoints return a fixed newest-first window: blocks 25, issuance 50, checkpoints 100, ai/events 500, address transactions and token transfers 50 each, mining statistics over the last 64 blocks. Query strings are ignored.

Amounts. All wei/gwei amounts that can exceed 2^53 are decimal strings.

Errors. 400 with {"error": "<message>"} for malformed path values, 404 with {"error": "not found"} for unknown resources and routes.

Base URL: http://127.0.0.1:8089/api/v1 (local explorer). A public explorer endpoint is not yet authorized.

Download OpenAPI 3.1 Postman collection

Endpoint Summary
GET /status Chain identity, indexer freshness, finality and alarms
GET /blocks Latest 25 indexed blocks (newest first)
GET /block/{key} One block by decimal number, 0x-hex number or 32-byte hash
GET /tx/{hash} One transaction with receipt status and decoded token transfers
GET /address/{address} Live balance, mined blocks, latest 50 transactions and 50 token transfers
GET /supply Exact issuance counters at the indexed tip (79.2% PoW / 19.8% PoS / 1% founder)
GET /issuance Per-block issuance for the latest 50 blocks
GET /mining GhostRider mining statistics over the latest 64 blocks
GET /validators Latest Smartnode validator snapshot (as returned by g4_validators)
GET /checkpoints Latest 100 observed finalized/justified checkpoints
GET /tokens Detected ERC-20 / ERC-721 contracts
GET /ai/events Latest 500 AI-market contract events decoded by signature

GET /status

Chain identity, indexer freshness, finality and alarms.

Status Body
200 Status 
curl -s http://127.0.0.1:8089/api/v1/status
Response fields
Field Type Notes
chain_id * integer | null
genesis * string | null
indexed_tip * integer
node_head * integer | null
lag_blocks * integer | null
client * string | null
finalized_height * integer | null
finalized_hash * string | null
justified_height * integer | null
reorgs_handled * integer
alarms * array

GET /blocks

Latest 25 indexed blocks (newest first).

Status Body
200 array of BlockSummary (max 25) 
curl -s http://127.0.0.1:8089/api/v1/blocks
Response fields
Field Type Notes
number * integer
hash * string
miner * string
ts * integer Unix seconds
difficulty * string
tx_count * integer
gas_used * integer

GET /block/{key}

One block by decimal number, 0x-hex number or 32-byte hash.

  • Path parameter key — pattern ^([0-9]+|0x[0-9a-fA-F]+)$
Status Body
200 Block
400 Error —
404 Error — 
curl -s http://127.0.0.1:8089/api/v1/block/<key>
Response fields
Field Type Notes
number * integer
hash * string
parent * string
miner * string
ts * integer
difficulty * string
gas_used * integer
gas_limit * integer
base_fee * string
tx_count * integer
state_root * string
minted * string Lifetime minted wei at this block
pow * string
pos * string
founder * string
fee_burn * string
txs * array
issued_in_block_wei string Absent for block 0
founder_in_block_wei string Absent for block 0

GET /tx/{hash}

One transaction with receipt status and decoded token transfers.

  • Path parameter hash — pattern ^0x[0-9a-fA-F]{64}$
Status Body
200 Transaction
400 Error —
404 Error — 
curl -s http://127.0.0.1:8089/api/v1/tx/<hash>
Response fields
Field Type Notes
hash * string
block * integer
idx * integer
from * string
to * string | null
contract * string | null Created contract address
value * string
gas_used * integer
gas_price * string
status * integer
input_bytes * integer
logs * integer
token_transfers * array

GET /address/{address}

Live balance, mined blocks, latest 50 transactions and 50 token transfers.

  • Path parameter address — pattern ^0x[0-9a-fA-F]{40}$
Status Body
200 Address
400 Error — 
curl -s http://127.0.0.1:8089/api/v1/address/<address>
Response fields
Field Type Notes
address * string
balance_wei * string | null Live balance at latest; null if the node is unreachable
blocks_mined * integer
is_founder * boolean
txs * array
token_transfers * array

GET /supply

Exact issuance counters at the indexed tip (79.2% PoW / 19.8% PoS / 1% founder).

Status Body
200 Supply 
curl -s http://127.0.0.1:8089/api/v1/supply
Response fields
Field Type Notes
at_block integer
minted_wei string
genesis_supply_wei string
issued_since_genesis_wei string
pow_issued_wei string
pos_issued_wei string
founder_issued_wei string
fee_burn_wei string
circulating_wei string
founder_address string | null

GET /issuance

Per-block issuance for the latest 50 blocks.

Status Body
200 array of IssuanceRow (max 50) 
curl -s http://127.0.0.1:8089/api/v1/issuance
Response fields
Field Type Notes
block * integer
issued_wei * string
pow_wei * string
pos_wei * string
founder_wei * string

GET /mining

GhostRider mining statistics over the latest 64 blocks.

Status Body
200 Mining 
curl -s http://127.0.0.1:8089/api/v1/mining
Response fields
Field Type Notes
window_blocks integer
mean_interval_s number
hashrate_estimate number difficulty / mean interval; an estimate
miners object

GET /validators

Latest Smartnode validator snapshot (as returned by g4_validators).

Status Body
200 array of Validator 
curl -s http://127.0.0.1:8089/api/v1/validators
Response fields
Field Type Notes
id * string
owner * string
key * string
pending_key boolean
stake_gwei * integer
delegated_gwei integer
activation_epoch integer
status * string

GET /checkpoints

Latest 100 observed finalized/justified checkpoints.

Status Body
200 array of Checkpoint (max 100) 
curl -s http://127.0.0.1:8089/api/v1/checkpoints
Response fields
Field Type Notes
observed_head * integer
finalized_height * integer
finalized_hash * string
justified_height * integer
justified_hash * string

GET /tokens

Detected ERC-20 / ERC-721 contracts.

Status Body
200 array of Token 
curl -s http://127.0.0.1:8089/api/v1/tokens
Response fields
Field Type Notes
address * string
kind * string
first_block * integer

GET /ai/events

Latest 500 AI-market contract events decoded by signature.

Status Body
200 array of AiEvent (max 500) 
curl -s http://127.0.0.1:8089/api/v1/ai/events
Response fields
Field Type Notes
block * integer
event * string
contract * string
tx * string
topics * string JSON-encoded topic list as stored
data * string

Sources at 72057fe3ec: explorer/openapi.yaml · explorer/pqwexplorer/web.py

Found a problem? Report a documentation issue · Build testnet-rc1+72057fe3ec