REST API Reference

The REST API described here belongs to the optional dashboard service, not to CometBFT itself. It proxies selected RPC calls and adds convenience endpoints.

Base URL:

http://<dashboard-host>:8080

Core Endpoints

Node / Network

• GET /api/config
• GET /api/status
• GET /api/net_info
• GET /api/validators
• GET /api/validator_dashboard
• GET /api/consensus
• GET /api/monitoring

Blocks / Transactions

• GET /api/blockchain
• GET /api/block/{height}
• GET /api/block_results/{height}
• GET /api/tx/{hash}
• GET /api/unconfirmed_txs

For transaction lookups, the original submitted transaction and the execution result are separate:

• result.tx is the submitted transaction input
• result.tx_result.data is Xian's decoded execution output

Contracts / ABCI

• GET /api/contract/{name}
• GET /api/addresses
• GET /api/address/{address}
• GET /api/contracts
• GET /api/recent_events
• GET /api/abci_query/{path}

Important Notes

• the dashboard must be running for these routes to exist
• the dashboard is outside the consensus path
• the dashboard decodes ABCI value and key fields for convenience

Contract Source

GET /api/contract/currency

Returns the current contract source fetched through the node's query layer. When the contract keeps original source in __source__, the dashboard returns that original source text separately from the stored runtime form. If the original source is not available, the contract route still returns the stored runtime code, but the explorer labels it explicitly as runtime code instead of presenting it as source.

In the explorer UI, the contract page now renders that source with Python syntax highlighting, lets you jump from a listed function to its definition in the source pane, and enriches the page with runtime metadata such as owner, developer, deployer, creator/initiator, creation tx, and indexed reward totals when BDS is available.

GET /api/addresses?limit=50&offset=0

Returns the recent indexed sender set for the explorer address list. On BDS-enabled service nodes this is backed by the canonical sender-history index. If the connected node does not expose that indexed address query, the dashboard returns the route as unavailable instead of synthesizing address rows from some other data source.

GET /api/address/<address>?limit=50&offset=0

Returns indexed sender history for the address on BDS-enabled service nodes, plus the developer-reward aggregate for that same address when available.

For the canonical runtime form, query:

GET /api/abci_query/contract_code/currency

ABCI Query Pass-Through

The dashboard exposes arbitrary ABCI query paths under:

GET /api/abci_query/{path}

Examples:

GET /api/abci_query/get/currency.balances:alice
GET /api/abci_query/keys/currency.balances/limit=100
GET /api/abci_query/keys/currency.balances/limit=100/after=alice
GET /api/abci_query/get_next_nonce/<address>
GET /api/abci_query/contract/currency
GET /api/abci_query/contract_source/currency
GET /api/abci_query/contracts/limit=50/offset=0/sort=submitted_at/order=desc
GET /api/abci_query/contract_info/currency
GET /api/abci_query/contract_code/currency
GET /api/abci_query/contract_methods/currency
GET /api/abci_query/contract_vars/currency
GET /api/abci_query/health
GET /api/abci_query/simulate_tx/<hex_payload>
GET /api/abci_query/perf_status
GET /api/abci_query/masternodes_policy
GET /api/abci_query/masternodes_active
GET /api/abci_query/masternodes_candidates
GET /api/abci_query/masternodes_validator/<address>
GET /api/abci_query/masternodes_pending_unbonds/<address>
GET /api/abci_query/masternodes_open_votes/limit=50/offset=0

For paginated key scans over a contract hash prefix, the /keys/... form returns the suffixes under that prefix together with limit, after, next_after, and has_more. Use next_after as the cursor when you need to walk large hashes without loading every key at once.

Monitoring Summary

GET /api/monitoring

This route backs the dashboard's operator cards. It aggregates:

• the node's decoded /perf_status ABCI query
• the node's decoded /bds_status ABCI query when BDS is enabled
• CometBFT unconfirmed_txs

The dashboard home view combines that monitoring summary with:

• /api/status for sync state, validator identity, and latest block metadata
• /api/net_info for peer count and peer details
• /api/validators for live validator-set and voting-power visibility

Use it for explorer/operator UX. For canonical reads, keep using CometBFT RPC and direct ABCI query paths.

Explorer Views

The built-in explorer routes are:

GET /explorer
GET /explorer/contracts
GET /explorer/addresses
GET /explorer/events

• /explorer is the block explorer view
• /explorer/contracts lists deployed contracts, sorted by creation date by default, with optional client-side switching to name sorting
• /explorer/addresses lists recent indexed addresses and also acts as the address drill-down entrypoint; selecting an address shows its indexed submitted transactions and lets you open each tx detail again
• /explorer/events lists recent indexed contract events when BDS is enabled

The dashboard also accepts an optional rpc query parameter for peer-targeted inspection through the same UI:

GET /explorer?rpc=http://10.0.0.25:26657

The backend only allows the default node RPC or currently connected peer RPC targets, so this stays scoped to known network peers instead of acting as a generic proxy.

For the standard localnet layout (node-0, node-1, … with host-port stride 100), the dashboard also infers host-routable peer RPC URLs so peer switching works from a host-local dashboard process instead of falling back to container-internal addresses.

When BDS is enabled, additional query paths are available under the same ABCI query surface. These are still node queries, but backed by the optional BDS index instead of the raw current-state driver.

These indexed reads are eventually consistent. The validator finalizes the block first, then the BDS worker persists the indexed payload asynchronously. So raw /get/... reads reflect current state immediately, while BDS-backed history/index queries may lag briefly behind the latest committed block. To make this resilient without keeping disk I/O in the validator hot path, BDS now keeps newly finalized blocks in an in-memory pending buffer and persists them in strict contiguous height order. If the indexed head is missing a height, BDS fetches the missing blocks from local CometBFT RPC in the background while newer live blocks remain pending.

That means BDS can safely receive new block data while it is still catching up:

• if live block N+2 arrives while N+1 is missing, N+2 stays pending
• the catch-up worker fetches and builds N+1
• BDS persists N+1, then N+2, preserving a single canonical chain order

The local spool is still available for offline maintenance, snapshot import, and explicit recovery workflows, but it is no longer the primary live-path durability mechanism.

Current BDS-backed ABCI query paths include:

GET /api/abci_query/bds_status
GET /api/abci_query/bds_spool/limit=50/offset=0
GET /api/abci_query/perf_status
GET /api/abci_query/blocks/limit=50/offset=0
GET /api/abci_query/block/123
GET /api/abci_query/block_by_hash/<hash>
GET /api/abci_query/tx/<hash>
GET /api/abci_query/txs_for_block/123
GET /api/abci_query/addresses/limit=50/offset=0
GET /api/abci_query/txs_by_sender/<address>/limit=50/offset=0
GET /api/abci_query/txs_by_contract/<contract>/limit=50/offset=0
GET /api/abci_query/contract_summary/<contract>
GET /api/abci_query/events_for_tx/<hash>
GET /api/abci_query/events/<contract>/<event>/limit=50/offset=0
GET /api/abci_query/events/<contract>/<event>/limit=50/after_id=500
GET /api/abci_query/token_balances/<address>/limit=100/offset=0
GET /api/abci_query/token_balances/<address>/limit=100/offset=0/include_zero=true
GET /api/abci_query/shielded_output_tags/<tag>/limit=50/offset=0
GET /api/abci_query/shielded_output_tags/<tag>/limit=50/after_id=500/kind=sync_hint
GET /api/abci_query/shielded_wallet_history/<tag>/limit=50/after_note_index=0
GET /api/abci_query/shielded_wallet_history/<tag>/limit=50/after_note_index=0/kind=sync_hint
GET /api/abci_query/recent_events/limit=50/offset=0
GET /api/abci_query/developer_rewards/<recipient_key>
GET /api/abci_query/state/<prefix>/limit=50/offset=0
GET /api/abci_query/state_history/<key>/limit=50/offset=0
GET /api/abci_query/state_for_tx/<hash>
GET /api/abci_query/state_for_block/123
GET /api/abci_query/contracts/limit=50/offset=0
GET /api/abci_query/state_patch_bundles
GET /api/abci_query/scheduled_state_patches/123
GET /api/abci_query/state_patches
GET /api/abci_query/state_patches_for_block/123
GET /api/abci_query/state_patch/<hash>
GET /api/abci_query/state_changes_for_patch/<hash>

Operator-oriented BDS inspection:

• /bds_status reports worker state, queue depth, spool size, indexed head, lag relative to the node's current block height, connection-pool posture, filesystem storage metrics, and warning/error alerts.
• catching_up is the meaningful “still behind” signal. queue_depth may stay nonzero while the service is otherwise caught up, so treat indexed height, spool state, DB health, and catching_up as the primary recovery signals.
• when present, the nested pool object reports size, idle, in_use, min_size, max_size, and utilization
• /bds_spool lists the block payloads currently present on the local spool for offline recovery or maintenance workflows.
• /perf_status reports the node's current execution/performance snapshot, including recent block timing and tracer metadata.
• /token_balances/<address> returns the BDS-backed token portfolio for one address. By default it omits zero balances; add include_zero=true when you need the full indexed token set for that address.
• /shielded_wallet_history/<tag> is the preferred shielded light-wallet sync feed. /shielded_output_tags/<tag> is the lower-level tag index used by tooling that needs direct access to tagged output rows.

Cursor-based event consumption:

• /events/<contract>/<event>/limit=.../after_id=... returns events with strictly larger BDS event IDs in ascending order.
• Use after_id for resumable consumers and long-running watchers.
• The older offset form is still useful for ad hoc browsing, but after_id is the better shape for application event consumers.

Shielded wallet history:

• /shielded_wallet_history/<tag>/limit=.../after_note_index=... is the protocol-shaped light-wallet recovery feed for shielded note wallets.
• it returns the canonical note-commitment sequence in note_index order and only exposes output_payload for outputs whose indexed tag matches the requested tag
• use kind=sync_hint for the normal wallet path; kind=discovery_tag is also accepted for lower-level tooling
• use after_note_index as the durable cursor for resumable wallet sync

Developer reward aggregation:

• /developer_rewards/<recipient_key> returns the cumulative indexed developer_reward total for that recipient across contract executions.
• The payload also includes reward row count, distinct transaction count, distinct rewarded source-contract count, and first/last indexed block and timestamp fields.
• Developer rewards are attributed across participating contracts by metered execution share, not only to the top-level transaction contract.
• This is a BDS-backed aggregate. It requires BDS to be enabled on the node and reflects the indexed view, not an unindexed raw-state scan.

Current catch-up behavior:

• during live operation, BDS keeps new finalized blocks pending in memory and backfills any missing heights from local CometBFT RPC automatically
• if the node or database restarts, BDS resumes from the indexed head and continues catch-up from local or remote CometBFT RPC
• the local spool remains useful for explicit offline recovery and imported payloads, but it is not required for ordinary live catch-up
• for full historical backfill, use xian-bds-reindex against local or remote CometBFT RPC
• if the local node has already pruned away the required block history, local reindex is no longer enough and an archival RPC source or imported BDS snapshot is needed

Use the raw node paths for authoritative current state:

GET /api/abci_query/get/<state_key>
GET /api/abci_query/contract/<name>
GET /api/abci_query/contract_methods/<name>
GET /api/abci_query/contract_vars/<name>
GET /api/abci_query/get_next_nonce/<address>
GET /api/abci_query/simulate_tx/<hex_payload>
GET /api/abci_query/perf_status
GET /api/abci_query/state_patch_bundles
GET /api/abci_query/scheduled_state_patches/123

State patch query split:

• /state_patch_bundles returns the node's local governed patch bundle inventory and does not require BDS
• /scheduled_state_patches/<height> returns the node's on-chain view of approved scheduled patches for that height and does not require BDS
• /state_patches... and /state_changes_for_patch/... are BDS-backed historical/indexed views of patches that were actually applied