XChain Platform Explorer: API Reference

Overview

The explorer exposes a REST API for querying all XChain Platform state. Every endpoint returns JSON and uses parameterized SQL internally to prevent injection.

All API URLs follow the pattern:

GET /{COIN}/api/{method}/{query}/{type}

Where:

• {COIN}: Coin prefix identifying the chain and network (e.g., BTC, TBTC, RDOGE)
• {method}: The data category (e.g., sends, balances, token)
• {query}: The search value (address, block index, token ticker, tx hash, action index)
• {type}: The filter type that determines how {query} is interpreted (e.g., address, block, token)

Coin Prefixes

Base URL

For the public XChain Platform (mainnet or testnet), query the hosted explorer directly:

https://explorer.xchain.io/{COIN}/api/

For a self-hosted or local explorer instance:

http://{host}:{port}/{COIN}/api/

The examples below use http://localhost:8080 for a self-hosted instance; against the public platform, substitute https://explorer.xchain.io (no port).

Response Format

API Response

All API endpoints return:

{
    "data": [ ... ],
    "total": 42,
    "runtime": "15ms"
}

Error Responses

Pagination

All list endpoints support pagination via query parameters:

Result limits:

• Most endpoints: max 100 results per page
• getBalances and getHolders: max 500 results per page

# Page 2 of sends, 25 per page, newest first
curl "http://localhost:8080/BTC/api/sends/bc1q.../address?page=2&limit=25&sortorder=DESC"

System Endpoints

Get Status

Returns configuration and sync health information for all supported and available coins.

GET /{COIN}/api/status

Parameters: None

Response:

{
    "data": {
        "supported": { "BTC": "BTC (mainnet)", "RBTC": "BTC (regtest)", ... },
        "available": { "BTC": "BTC (mainnet)" },
        "hub_config_fetched_at": "2026-06-13T12:00:00.000Z",
        "hub_config_age_seconds": 42,
        "last_block": { "BTC": 893000, "RBTC": 41 },
        "last_block_time": { "BTC": 1718280000, "RBTC": 1718080000 },
        "decoder_tip": { "BTC": 893000, "RBTC": 41 },
        "decoder_lag_blocks": { "BTC": 0, "RBTC": 0 },
        "tip_age_seconds": { "BTC": 120, "RBTC": 200120 },
        "stale": { "BTC": false, "RBTC": true },
        "chain_tip": { "BTC": 893000, "RBTC": 41 },
        "chain_lag_blocks": { "BTC": 0, "RBTC": 0 },
        "decoder_health": { "BTC": "healthy", "RBTC": "healthy" }
    }
}

The example above shows the gate in action: RBTC has a frozen tip, so it is stale and absent from available, while still listed in supported.

Freshness gate. The threshold behind stale is EXPLORER_TIP_MAX_AGE_S (6 hours by default), overridable per coin with EXPLORER_TIP_MAX_AGE_S_<COIN> and disabled entirely with 0. See configuration.md. A client that wants only current data should read available rather than supported, and treat a coin’s disappearance from available as a transient outage of this instance, not as the coin being unknown.

Get Network

Returns aggregate network statistics, coin identity/pricing, fee guidance, and finality settings.

GET /{COIN}/api/network

Parameters: None

Response:

{
    "data": {
        "totals": {
            "total_sends": 1234,
            "total_issues": 567,
            "total_orders": 89,
            "total_dispensers": 45
        },
        "network": {
            "block": 893000,
            "block_time": 1718280000,
            "unconfirmed": 3,
            "fee": { "low": 1, "medium": 2, "high": 5 }
        },
        "coin": {
            "name": "Bitcoin",
            "symbol": "BTC",
            "price": { "btc": "1.00000000", "usd": "68420.00" }
        },
        "xchain": {
            "name": "XChain",
            "symbol": "XCHAIN",
            "price": { "btc": "0.00000000", "usd": "0.00" }
        },
        "finality": { "BTC": 6, "LTC": 12, "DOGE": 60 }
    }
}

Token Endpoints

Get Token

Returns full token information for a single ticker.

GET /{COIN}/api/token/{tick}

Parameters:

Response fields: Token metadata including supply, max supply, decimals, owner address, description, lock states, mint parameters, and creation info.

Example:

curl http://localhost:8080/BTC/api/token/MYTOKEN

{
    "data": {
        "tick": "MYTOKEN",
        "max_supply": "1000000.00000000",
        "supply": "500000.00000000",
        "decimals": 8,
        "owner": "bc1q...",
        "description": "My token description",
        "lock_supply": 0,
        "lock_mint": 0,
        "lock_description": 0,
        "block_index": 800000,
        "action_index": 42
    }
}

Get Tokens

Returns a list of tokens filtered by various criteria.

GET /{COIN}/api/tokens/{query}/{type}

Parameters:

Type values:

Pagination: Supported

Example:

# All tokens owned by an address
curl "http://localhost:8080/BTC/api/tokens/bc1q.../address?limit=50"

# Search tokens by name
curl http://localhost:8080/BTC/api/tokens/MY/token

Balance & Address Endpoints

Get Balances

Returns all token balances held by an address.

GET /{COIN}/api/balances/{address}

Parameters:

Pagination: Supported (max 500 results)

Response: Array of balance objects with tick, balance amount, and token details.

Example:

curl http://localhost:8080/BTC/api/balances/bc1qexampleaddress

Get Address

Returns summary information for an address, including native-coin balance and UTXO counts sourced from the coin’s xchain-utxo-tracker (the explorer itself is DB-only and never talks to a node).

GET /{COIN}/api/address/{address}

Parameters:

Response fields: address, type, balances (confirmed/pending/received), utxos (confirmed/pending), estimated_value (btc/usd, from the hub price oracle; null when no price is available), tracker_available, mempool_ready.

tracker_available is false when no UTXO tracker is configured for the coin or it is unreachable; the balance and UTXO fields are then null (the UI shows “Unavailable”) rather than placeholder values.

Get Holders

Returns a ranked list of all holders for a given token.

GET /{COIN}/api/holders/{tick}

Parameters:

Pagination: Supported (max 500 results)

Response: Array of holder objects with address and balance, sorted by balance descending.

Example:

curl "http://localhost:8080/BTC/api/holders/MYTOKEN?limit=100"

Get Credits

Returns credit records (incoming tokens: transfers, mints, airdrops, dispenser releases, escrow releases).

GET /{COIN}/api/credits/{query}/{type}

Type values: block, address

Pagination: Supported

Get Debits

Returns debit records (outgoing tokens: transfers, destroys, fees, DEX funding).

GET /{COIN}/api/debits/{query}/{type}

Type values: block, address

Pagination: Supported

Get Escrows

Returns escrow records (tokens locked in DEX orders, dispensers, or swaps).

GET /{COIN}/api/escrows/{query}/{type}

Type values: block, address

Pagination: Supported

Transaction & History Endpoints

Get Transaction

Returns a decoded XChain transaction with all associated actions.

GET /{COIN}/api/transaction/{query}/{type}

Type values:

Response fields: tx_index, tx_hash, block_index, and an array of actions contained in the transaction.

Example:

curl http://localhost:8080/BTC/api/transaction/abc123.../tx_hash

Get Actions

Returns all actions across all types, with optional filters for block, transaction, and token.

GET /{COIN}/api/actions[?blockIndex=N&txid=TX_HASH&tick=TOKEN]

Query parameters:

Pagination: Supported

Response: Array of action objects, each including action_index, action (type name), action_format, source, block_index, timestamp, tx_hash, and tx_index.

Example:

# All actions in a block
curl "http://localhost:8080/BTC/api/actions?blockIndex=800000"

# All actions involving a token
curl "http://localhost:8080/BTC/api/actions?tick=MYTOKEN"

Get Action

Returns comprehensive details for a single XChain action by its action index. Includes the action record, associated credits, debits, escrows, and fees.

GET /{COIN}/api/action/{actionIndex}

Parameters:

Response: Full action detail including the action type, all fields, transaction info, block info, and all ledger entries (credits, debits, escrows, fees) associated with this action.

Example:

curl http://localhost:8080/BTC/api/action/42

Get Block

Returns block-level summary information.

GET /{COIN}/api/block/{blockIndex}

Parameters:

Response fields: block_index, block_hash, block_time, transaction count, and action summary.

Get History

Returns a unified history of all XChain activity matching the query. Combines all action types into a single chronological feed.

GET /{COIN}/api/history/{query}/{type}

Type values:

Pagination: Supported

Example:

# Recent history for an address
curl "http://localhost:8080/BTC/api/history/bc1q.../address?limit=50&sortorder=DESC"

# Recent global activity
curl "http://localhost:8080/BTC/api/history/0/recent?limit=20"

ACTION-Specific Endpoints

All ACTION-specific endpoints share the same URL pattern and accept pagination:

GET /{COIN}/api/{action_plural}/{query}/{type}

Each returns records of the corresponding ACTION type. The {type} parameter controls how {query} is interpreted.

Sends

Token transfer records.

GET /{COIN}/api/sends/{query}/{type}

Example:

curl "http://localhost:8080/BTC/api/sends/bc1q.../address?limit=25&sortorder=DESC"

Issues

Token creation and update records (ISSUE action).

GET /{COIN}/api/issues/{query}/{type}

Mints

Token minting records.

GET /{COIN}/api/mints/{query}/{type}

Destroys

Token burn/destroy records.

GET /{COIN}/api/destroys/{query}/{type}

Orders

DEX order records (create, with status info).

GET /{COIN}/api/orders/{query}/{type}

Response includes: give/get coin, give/get tick, give/get amounts, expiration, status, and computed price fields.

Order Matches

Records of matched (filled) orders.

GET /{COIN}/api/order_matches/{query}/{type}

Order Cancels

Records of cancelled orders.

GET /{COIN}/api/order_cancels/{query}/{type}

Order Edits

Records of edited orders.

GET /{COIN}/api/order_edits/{query}/{type}

Order Expires

Records of expired orders.

GET /{COIN}/api/order_expires/{query}/{type}

COINPay

Native coin payment actions that fulfill ORDER_MATCH obligations.

GET /{COIN}/api/coinpays/{query}/{type}

Response includes: obligation action_index, coin amount, txid, vout, status, block, timestamp.

GET /{COIN}/api/coinpay_expires/{query}/{type}

GET /{COIN}/api/coinpay_obligations/{query}/{type}

Response includes: payer address, payee address, coin, coin amount, expiration timestamp, status (pending_coinpay/fulfilled/expired).

Dispensers

Vending-machine style token dispensers.

GET /{COIN}/api/dispensers/{query}/{type}

Response includes: give/get coin, give/get tick, give/get amounts, escrow amount, fiat pricing, status, expiration, allow/block lists.

Dispenses

Records of dispenser purchases (triggered when someone sends the required amount to a dispenser address).

GET /{COIN}/api/dispenses/{query}/{type}

Dispenser Cancels

GET /{COIN}/api/dispenser_cancels/{query}/{type}

Dispenser Closes

GET /{COIN}/api/dispenser_closes/{query}/{type}

Dispenser Edits

GET /{COIN}/api/dispenser_edits/{query}/{type}

Dispenser Expires

GET /{COIN}/api/dispenser_expires/{query}/{type}

Swaps

Cross-chain token swap records.

GET /{COIN}/api/swaps/{query}/{type}

Response includes: give/get coin, give/get tick, give/get amounts, get address, expiration, status, allow/block lists.

Swap Matches

GET /{COIN}/api/swap_matches/{query}/{type}

Swap Cancels

GET /{COIN}/api/swap_cancels/{query}/{type}

Swap Edits

GET /{COIN}/api/swap_edits/{query}/{type}

Swap Expires

GET /{COIN}/api/swap_expires/{query}/{type}

Bet Feeds (Betting Markets)

Parimutuel betting markets, created by the BET action (format 0). A market’s action_index IS its identifier: bets and oracle actions reference it as feed_action_index.

GET /{COIN}/api/bet_feeds/{query}/{type}
GET /{COIN}/api/bet_feeds

Response includes: action index, source (the oracle), label, outcomes, tick, fee (the oracle’s cut as a percent of the pot), deadline, refund window, expire_at, minimum amount, allow/block lists, details, feed status, closed_block, terminal_block, plus the usual block, transaction and status fields.

The unfiltered form returns the most recent markets across every source.

Get Bet Feed

A single market by the action index that created it.

GET /{COIN}/api/bet_feed/{action_index}

Returns the same fields as above, with outcomes split back into an array in wire order so a caller can render the options without re-parsing the stored comma-joined list.

Bets

Individual wagers placed on a market (BET format 2). A bet is final once confirmed: there is no bettor-side cancel.

GET /{COIN}/api/bets/{query}/{type}
GET /{COIN}/api/bets

Response includes: action index, feed action index, bettor address, outcome, tick, amount, bet status, settled_block.

Payouts credit the address that PLACED the bet, automatically at resolution. There is no claim action, so a settled bet shows up as a bet_status flip plus a credit, never as a user-submitted collection.

Oracle Track Record

The per-address record of whoever creates markets. This is what a bettor reads to judge an oracle before staking on one of their markets.

GET /{COIN}/api/oracle/{address}

Response includes: address, total_feeds, active_feeds (open plus closed), counts per lifecycle status, fees_earned per token (tick, resolves, amount), and a reputation_caveat string.

Fees are earned on the resolve path only: a void, a cancel and an expiry all pay the oracle nothing. The caveat field is returned because the record is per-address with no bonding, and addresses are free to create, so an empty history means unknown rather than safe.

Sweeps

Records of SWEEP actions (transfer all assets to a destination).

GET /{COIN}/api/sweeps/{query}/{type}

Dividends

Proportional distribution records.

GET /{COIN}/api/dividends/{query}/{type}

Airdrops

Airdrop distribution records.

GET /{COIN}/api/airdrops/{query}/{type}

Broadcasts

On-chain broadcast/oracle data.

GET /{COIN}/api/broadcasts/{query}/{type}

Messages

On-chain encrypted or plaintext messages.

GET /{COIN}/api/messages/{query}/{type}

Files

On-chain file attachments.

GET /{COIN}/api/files/{query}/{type}

Response includes: file name, mime type, title, memo, and action metadata.

Callbacks

Token callback action records.

GET /{COIN}/api/callbacks/{query}/{type}

Sleeps

Address or token pause records.

GET /{COIN}/api/sleeps/{query}/{type}

Addresses

ADDRESS action records (address preference configuration).

GET /{COIN}/api/addresses/{query}/{type}

Batches

BATCH action records (multi-action transactions).

GET /{COIN}/api/batches/{query}/{type}

Links

Cross-chain link records.

GET /{COIN}/api/links/{query}/{type}

Lists

Address or tick list management records.

GET /{COIN}/api/lists/{query}/{type}

Fees

Fee records (XCHAIN gas token charges).

GET /{COIN}/api/fees/{query}/{type}

Mempool

Pending unconfirmed transaction data. Rows come from the decoder’s mempool_transactions table and are pre-validation: the decoder writes whatever it parses from a mempool transaction; the indexer may still reject it at confirmation time.

GET /{COIN}/api/mempool/{query}/{type}

Response fields: tx_hash, source, action (decoded action name), data (full pipe-delimited action string). No destination field, destinations are embedded in the data string.

Market Endpoints

The explorer provides market data endpoints for the on-chain DEX (ORDER-based trading).

List Markets

Returns all active trading pairs, or all markets involving a specific token.

GET /{COIN}/api/markets
GET /{COIN}/api/markets/{tick}

Parameters:

Response: Array of market objects with tick1, tick2, and pricing information.

Example:

# All markets
curl http://localhost:8080/BTC/api/markets

# Markets involving MYTOKEN
curl http://localhost:8080/BTC/api/markets/MYTOKEN

Get Market

Returns summary information for a specific trading pair.

GET /{COIN}/api/market/{tick1}/{tick2}

Parameters:

Response: Market summary with last price, volume, and price computed in both directions (tick1→tick2 and tick2→tick1).

Example:

curl http://localhost:8080/BTC/api/market/TOKENA/TOKENB

Get Market History

Returns trade history (filled orders) for a market pair. Optionally filter to a single address.

GET /{COIN}/api/market/{tick1}/{tick2}/history
GET /{COIN}/api/market/{tick1}/{tick2}/history/{address}

Parameters:

Pagination: Supported

Example:

# All trades for a pair
curl "http://localhost:8080/BTC/api/market/TOKENA/TOKENB/history?limit=50"

# Trades by a specific address
curl http://localhost:8080/BTC/api/market/TOKENA/TOKENB/history/bc1q...

Get Market Orders

Returns open orders for a market pair. Optionally filter to a single address.

GET /{COIN}/api/market/{tick1}/{tick2}/orders
GET /{COIN}/api/market/{tick1}/{tick2}/orders/{address}

Parameters:

Pagination: Supported

Example:

curl http://localhost:8080/BTC/api/market/TOKENA/TOKENB/orders

Get Market Orderbook

Returns the aggregated order book for a market pair, split into bids and asks.

GET /{COIN}/api/market/{tick1}/{tick2}/orderbook

Parameters:

Response:

{
    "data": {
        "asks": [
            { "price": "0.50", "amount": "100" },
            ...
        ],
        "bids": [
            { "price": "0.45", "amount": "200" },
            ...
        ]
    }
}

Example:

curl http://localhost:8080/BTC/api/market/TOKENA/TOKENB/orderbook

Governance (VOTE) Endpoints

VOTE actions create token-weighted polls, cast ballots, and delegate voting power. These endpoints read the indexer’s polls, votes, and poll_results tables. The web UI exposes them at /{COIN}/polls and /{COIN}/votes under the Governance nav entry.

List Polls

Returns a paginated list of polls.

GET /{COIN}/api/polls/{query}/{type}
GET /{COIN}/api/polls

Type values:

When called without {query}/{type}, returns recent polls (paginated).

Pagination: Supported

Response fields: action, action_index, action_format, source, tick, end_block, options, max_selections, tally_mode, weight_mode, quorum, min_voters, question, poll_status, winning_option, total_weight, total_voters, quorum_met, min_voters_met, deposit_amount, callback_contract_index, callback_method, finalized_action_index, block_index, timestamp, tx_hash, tx_index, status.

Get Poll

Returns a single poll by its creating action index.

GET /{COIN}/api/poll/{actionIndex}

Get Poll Results

Returns the finalized per-option tallies for a poll (one row per option). Empty until the poll is finalized.

GET /{COIN}/api/poll/{actionIndex}/results

Response fields: poll_index, option_index, total_weight, voter_count, finalize_action_index, block_index, status.

List Votes

Returns a paginated list of ballots (one row per poll + voter + chosen option).

GET /{COIN}/api/votes/{query}/{type}

Type values:

Pagination: Supported

Response fields: action, action_index, action_format, source, poll_index, choice, share, memo, block_index, timestamp, tx_hash, tx_index, status.

Example:

# Recent polls
curl "http://localhost:8080/BTC/api/polls?limit=10"

# Ballots in poll 1234
curl "http://localhost:8080/BTC/api/votes/1234/poll"

ANCHOR Endpoints

ANCHOR actions are the periodic on-chain checkpoints published to the DOGE chain by the validator federation. These endpoints read the anchor_actions table.

List Anchors

Returns a paginated list of ANCHOR checkpoint records.

GET /{COIN}/api/anchors/{query}/{type}
GET /{COIN}/api/anchors

Parameters:

Type values:

When called without {query}/{type}, returns recent ANCHOR actions (paginated).

Pagination: Supported

Response fields: action, action_index, action_format, version, chain, network, block_index, block_hash, ledger_hash, actions_hash, contract_hash, checkpoint_seq, snapshot_block, state_root, state_root_version, block_merkle_root, block_merkle_version, validator_signatures, timestamp, tx_hash, tx_index, status.

Example:

# Recent ANCHOR actions
curl "http://localhost:8080/RDOGE/api/anchors?limit=10"

# ANCHOR actions for BTC chain
curl "http://localhost:8080/RDOGE/api/anchors/BTC/chain"

# ANCHOR actions for a specific block
curl "http://localhost:8080/RDOGE/api/anchors/800000/block"

Checkpoint Verification Endpoints

The explorer exposes quorum-signed state checkpoints for light-client verification. Checkpoint data is read from the hub-mirrored state_checkpoints table.

On nodes that maintain their own checkpoint mirror (self-sync mode, see the Configuration page), these endpoints return HTTP 503 with code MIRROR_NOT_BOOTSTRAPPED until the mirror’s first snapshot download completes, and afterwards include two extra response fields: mirror_bootstrapped (always true once serving) and mirror_lag_seconds (how far the mirror trails the hub’s feed). Operators can additionally opt into HTTP 503 MIRROR_STALE on excessive lag. Nodes reading an externally-maintained hub schema return neither the extra fields nor the 503s.

Hub-Mirror Status

GET /{COIN}/api/hub-mirror/status

Reports the self-synced mirror’s state for this coin, or { "enabled": false } when the coin is served from an externally-maintained schema.

Response:

{
    "enabled": true,
    "target": { "host": "localhost", "name": "XChain_Hub_Mirror" },
    "bootstrapDrained": true,
    "streamWatermark": 1751804000,
    "mirrorLagSeconds": 4
}

List Checkpoints

GET /{COIN}/api/checkpoints[?limit=N]

Returns the latest quorum-signed state checkpoints for the coin’s chain. Default limit is 10.

Response:

{
    "checkpoints": [ ... ],
    "count": 5
}

Verify Checkpoint

GET /{COIN}/api/checkpoint/{blockIndex}/verify

Re-verifies the checkpoint at blockIndex server-side and returns everything a client needs to verify it independently.

Response fields:

Returns HTTP 404 with { "error": "No checkpoint at this height", "code": "CHECKPOINT_NOT_FOUND" } when no checkpoint exists at the requested height.

Get Checkpoint Range

Returns a forward-ordered slice of quorum-signed checkpoints between two block heights. Intended for light-client forward-following: a client fetching the next N checkpoints after its last known one.

GET /{COIN}/api/checkpoints/range?from={fromBlock}&to={toBlock}

Query parameters:

Response:

{
    "checkpoints": [ { "chain": "BTC", "network": "mainnet", "block_index": 800000, ... }, ... ],
    "count": 5
}

Each checkpoint object contains the same fields as the response from GET /{COIN}/api/checkpoints: chain, network, block_index, block_hash, ledger_hash, actions_hash, contract_hash, checkpoint_seq, snapshot_block, state_root, state_root_version, block_merkle_root, block_merkle_version, and validator_signatures (parsed as a JSON array).

The result is capped at 500 checkpoints per request. If the range spans more than 500 checkpoint heights, only the first 500 are returned.

Returns HTTP 400 when from or to are missing, non-integer, or to < from.

Example:

# Checkpoints from block 800000 to 801000
curl "http://localhost:8080/BTC/api/checkpoints/range?from=800000&to=801000"

SPV Light-Client Proof Endpoints

These endpoints build read-only Merkle proofs that a light client verifies locally against a quorum-signed checkpoint’s committed state_root or block_merkle_root. The server never asks the client to trust its word; all verification happens client-side.

Proof endpoints require a full indexer DB with the state_tree_nodes table (not replicated by xchain-sync). A thin replica returns HTTP 501 with code NO_STATE_TREE.

Balance Proof

Returns a Sparse Merkle Tree (SMT) inclusion (or non-inclusion) proof for an address/tick balance, bound to the nearest signed checkpoint at or above the requested height.

GET /{COIN}/api/proof/balance/{address}/{tick}[?height=N]

Parameters:

Response (success):

{
    "proof": {
        "chain": "BTC", "network": "mainnet", "height": 800000,
        "address": "bc1q...", "tick": "MYTOKEN", "amount": "100.00000000",
        "smt_proof": { "key": "...", "leaf_value": "...", "compressed": [...] },
        "sub_root_path": { "index": 0, "siblings": [...] },
        "balances_root": "...", "stakes_root": "...",
        "state_root": "...", "state_root_version": 1
    },
    "checkpoint": { "block_index": 800000, "state_root": "...", "validator_signatures": [...], ... }
}

A non-held balance returns leaf_value: null (non-inclusion proof) and amount: "0".

Error codes:

Action Inclusion Proof

Returns a fixed-Merkle-tree inclusion proof for an action row within its block, bound to the checkpoint that commits that block’s block_merkle_root.

GET /{COIN}/api/proof/action/{actionIndex}

Parameters:

Response (success):

{
    "proof": {
        "chain": "BTC", "network": "mainnet", "height": 800000, "action_index": 42,
        "tx_index": 5, "action": "SEND",
        "leaf": "...",
        "merkle_proof": { "index": 3, "siblings": [...] },
        "block_merkle_root": "...", "block_merkle_version": 1
    },
    "checkpoint": { "block_index": 800000, "block_merkle_root": "...", "validator_signatures": [...], ... }
}

Error codes:

Validator-Set Proof

Returns SMT proofs for each validator’s stake weight, bound to the BTC checkpoint at the given snapshot height. BTC-only (the stakes_root is BTC-anchored per protocol spec).

GET /BTC/api/proof/validator-set?height={snapshotBlock}[&capabilities=oracle_publish,cross_chain]

Query parameters:

Notes:

• Requires INDEXER_API_URL to be configured (to fetch live stake weights). Returns HTTP 501 with code INDEXER_NOT_CONFIGURED otherwise.
• Returns HTTP 400 with code STAKES_BTC_ONLY when called on a non-BTC coin prefix.

Error codes:

Contract-State Proof

GET /{COIN}/api/proof/contract-state/{contractIndex}/{key}

Status: Not yet implemented. The contract state root is committed as EMPTY in state_root_version 1 (spec D1). This endpoint returns HTTP 501 with code UNSUPPORTED_VERSION until a future protocol version activates contract-state commitments.

Additional REST Endpoints

The following endpoints are registered and active. Detailed documentation is in the linked spec files.

Native-Coin Fee (Explorer Proxy)

GET /{COIN}/api/feequote?action=ISSUE&params=0|NEWTICK&source=...&feeOutputSats=...
GET /{COIN}/api/feeschedule
GET /{COIN}/api/preflight?action=SEND&params=...&source=...&feeMode=xchain|native
GET /{COIN}/api/oraclefeequote?oracleAddress=...&giveTick=...&fiatCode=USD&giveEscrow=1000

Proxied to the colocated indexer’s feequote / feeschedule / preflight / oraclefeequote JSON-RPC. Returns 503 when no INDEXER_API_URL is configured. See CONFIGURATION.md for INDEXER_API_URL_<COIN>_<NETWORK>.

preflight answers “would the indexer accept this action?” independently of native-fee support, returning { supported, valid, status, error, guardInert, feeExempt, denied, xchainFee, feeMode, feeTick, feeTokenBalance, feeAffordable, blockIndex, blockTime }. xchainFee is the protocol fee the action would owe as an XCHAIN-denominated decimal string, taken from the same dry-run that produced the verdict, so a confirm screen can disclose the fee without a second call to feequote (it is null when the run staged no fee record, and absent when no verdict was produced). Sizing a native-coin fee output still needs feequote, which prices that fee against the oracle.

The dry-run settles that fee the way feeMode says the real transaction will, because the two modes give different answers: xchain debits the payer’s XCHAIN balance (so a payer who cannot cover the fee is told invalid here, before signing anything), while native pays a coin output to the fee destination and never touches that balance. Omit feeMode to get the chain’s own default, which is native on LTC/DOGE (they have no XCHAIN fee lane) and the XCHAIN debit on BTC. feeTokenBalance reports the payer’s balance of feeTick at the quoted height, and feeAffordable says whether it covers xchainFee; feeAffordable is null in native mode, since that balance is not what pays.

oraclefeequote sizes the up-front native-coin output a Mode B dispenser owes the oracle operator it names in ORACLE_ADDRESS, returning { valid, error, oracleAddress, blockTime, requiredFeeNative, requiredFeeSats, belowDust, note }. The indexer computes it from the same code path it validates with, so an output sized from the quote is accepted on chain.

Price and Price Snapshots

GET /{COIN}/api/prices/{query}/{type}
GET /{COIN}/api/price_snapshots/{query}/{type}

USD-denominated prices and the raw PRICE v0 oracle snapshots (PBFT-signed) behind them. prices type values: block, address, source, token. price_snapshots type values: pair, round, status.

Cross-Chain Matches and Settlements

GET /{COIN}/api/cross_chain_matches/{query}/{type}
GET /{COIN}/api/cross_chain_settlements/{query}/{type}

Cross-chain DEX match and settlement records. type values for matches: match, block, status; for settlements: match, block.

VM / Contract Endpoints

GET /{COIN}/api/contracts[/{query}/{type}]
GET /{COIN}/api/contract/{TICK}
GET /{COIN}/api/contract/{TICK}/state[/{type}]
GET /{COIN}/api/contract/{TICK}/balance[/{type}]
GET /{COIN}/api/executions[/{query}/{type}]
GET /{COIN}/api/execution/{query}
GET /{COIN}/api/deploy_chunks

Smart contract (DEPLOY / CALL) data. contracts and executions type values: block, address, contract (or source for contracts). Single-contract detail, sandbox state, and per-contract token balance via the contract/* routes. deploy_chunks lists chunked upload records for large contracts.

Deposit and Withdrawal Endpoints

GET /{COIN}/api/deposits/{query}/{type}
GET /{COIN}/api/withdrawals/{query}/{type}

Contract deposit and withdrawal records. type values: block, address, source, contract.

Staking and Validator Endpoints

GET /{COIN}/api/stakes[/{query}/{type}]
GET /{COIN}/api/validators
GET /{COIN}/api/delegations/{query}/{type}
GET /{COIN}/api/delegation_revocations[/{query}/{type}]
GET /{COIN}/api/rewards/{query}/{type}
GET /{COIN}/api/collects[/{query}/{type}]
GET /{COIN}/api/full_node_verifications[/{query}/{type}]
GET /{COIN}/api/contract_stakes[/{query}/{type}]
GET /{COIN}/api/contract_unstakes[/{query}/{type}]
GET /{COIN}/api/contract_delegations[/{query}/{type}]
GET /{COIN}/api/slash_events[/{query}/{type}]

Validator federation data. stakes and delegations type values: block, address, source. rewards type values: address, source. delegation_revocations (DELEGATE v2/v3 signing-key revocations) and collects (COLLECT validator reward claims) type values: block, address, source. full_node_verifications type values: block, epoch, pubkey, address. Contract-targeted staking (contract_stakes, contract_unstakes, contract_delegations) and slash_events support types: block, address, contract.

Hub Federation and Governance Endpoints

GET /{COIN}/api/validator_capabilities[/{query}/{type}]
GET /{COIN}/api/governance_proposals[/{query}/{type}]
GET /{COIN}/api/governance_votes[/{query}/{type}]
GET /{COIN}/api/capability_slash_events[/{query}/{type}]
GET /{COIN}/api/oracle_prices[/{query}/{type}]

Hub-only federation state read from the co-located hub DB (tables that have no on-chain action; the validator registry itself is surfaced on-chain via /{COIN}/api/validators). validator_capabilities type values: capability, pubkey. governance_proposals type values: status, parameter, proposal. governance_votes type values: proposal, voter. capability_slash_events (SLASH wire actions) type values: block, capability, pubkey, address. oracle_prices (user-published PRICE v1 rows, hub-mirrored) type values: token, address.

Attestation Endpoints

GET /{COIN}/api/attestations[/{query}/{type}]

ATTEST v0 requests and v1 responses from the attests table. type values: block, address, contract.

Cross-Chain Call Endpoints

GET /{COIN}/api/xcalls[/{query}/{type}]
GET /{COIN}/api/xcall/{callId}

VM-emitted cross-chain call records (XCALL). xcalls type values: block, contract, status. Single-call lifecycle lookup via xcall/{callId}.

Controller-Bound Token Endpoints

GET /{COIN}/api/controllers

Controller bind/unbind event stream for controller-bound tokens. See protocol/Controller_Bound_Tokens.md.

Project Registry

GET /{COIN}/api/project/{TICK}

Returns the current roster for a project token (tick). See protocol/Project_Registry.md.

Public Key Lookup

GET /{COIN}/api/pubkey/{address}

Returns the on-chain-observed public key for address, or null if not yet seen.

Token Search Types

The /{COIN}/api/tokens/{query}/{type} endpoint accepts the additional type value nft, which restricts results to NFT-enabled tokens. All other type values (block, address, token, subtoken) are unchanged.

File Raw Endpoint

GET /{COIN}/api/file/{actionIndex}/raw

Returns the raw bytes for a FILE action.

• Gated file: returns the AES-256-GCM ciphertext (12-byte nonce || ciphertext || 16-byte GCM tag) as application/octet-stream. Holders decrypt client-side after receiving the symmetric key via an ECIES MESSAGE.
• Non-gated file: returns the stored bytes from the colocated decoder DB, served inline for safe media MIME types (image, audio, video, PDF, JSON). Unsafe types (HTML, SVG, XML, scripts, unknown) are forced to download as application/octet-stream. This is the resolution target for TIS data_ref entries using the action:<index> scheme, enabling NFT artwork to render directly in the browser.

Returns HTTP 404 when the actionIndex is unknown or the decoder DB is unreachable. Returns HTTP 400 for a non-numeric actionIndex.

Relay and Icon Routes

GET  /relay?url={url}
GET  /icon/{path}

/relay fetches a remote JSON or PNG resource on behalf of the browser (a same-origin CORS proxy for TIS metadata and token icons hosted off-chain). Pass the target URL as the url query parameter. Private/loopback/metadata addresses are blocked. /icon/{path} serves cached token icon images. Both are non-coin-prefixed and registered at the root level.

Machine-Readable Spec

GET /openapi.json

OpenAPI 3.1 specification for all explorer REST endpoints. Regenerated by docs/openapi.build.js; kept in sync with the route tables by test/unit/openapi-coverage.test.js.

DataTables Explorer Endpoints

In addition to the REST API, the explorer provides a parallel set of endpoints designed for the web UI’s jQuery DataTables integration. These endpoints use cursor-based pagination and return arrays instead of objects for compact transmission.

URL Pattern

GET /{COIN}/explorer/{method}/{query}/{type}

Response Format

{
    "recordsTotal": 42,
    "recordsFiltered": 42,
    "data": [
        [1, "field1|field2|field3", 100],
        ...
    ],
    "runtime": "12ms"
}

Data arrays use pipe-delimited strings for multi-value fields.

Pagination Parameters

Available Explorer Endpoints

All REST API action endpoints have a corresponding Explorer endpoint:

Additional Explorer-only endpoints:

Search

The search endpoint supports multi-entity searching:

GET /{COIN}/explorer/search/{query}/{type}

JSON-RPC 2.0 Interface

The explorer also exposes a JSON-RPC 2.0 endpoint for programmatic access:

POST / (root path)
Content-Type: application/json

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "ping",
    "params": {}
}

Available Methods

Note: The JSON-RPC interface currently exposes only the ping method. The REST API is the primary interface for data queries.

Complete Endpoint Quick Reference

Single-Item Endpoints

Market Endpoints

List Endpoints (all support /{query}/{type} and pagination)

VM / Contract List Endpoints

Staking and Validator List Endpoints

ANCHOR and Attestation and Cross-Chain Call List Endpoints

Price and Oracle List Endpoints

Cross-Chain DEX List Endpoints

Governance List Endpoints

Copyright © 2025–2026 Dankest, LLC

Based on XChain Platform by Dankest, LLC – https://dankest.llc

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) with a commercial license available for proprietary use.

You may use, modify, and distribute this material under the terms of the License. See LICENSE and NOTICE for full terms. See the licensing overview.