REST API Documentation

GET /block/tip

Returns the current chain tip block.

GET /block/latest

Returns the latest block (alias for tip).

GET /block/<id>

Returns a block by height or hash.

GET /block/<id>/protocols

Returns the protocol tag distribution for a block. Response: array of {"protocol", "name", "short", "color", "tx_count"} covering detected on-chain protocols (ORD, BSV21, MAP, B, etc.) within the block.

GET /blocks?from=&limit=

Returns a paginated list of blocks. Cursor-style: from is the upper-bound height (exclusive when paging back), limit defaults to 20, max 100.

GET /block/header/height/<height>/raw

Returns the raw 80-byte block header as binary (application/octet-stream) for a given height. Use /block/headers/latest for a hex-encoded variant.

GET /block/headers/latest

Returns the 80-byte block header of the current chain tip as a hex string.

GET /block/headers/resources

Returns JSON array of downloadable header chunk URLs (2016-block difficulty periods). Each entry has url and label fields.

GET /block/headers/<from>-<to>

Downloads concatenated raw 80-byte headers for a height range as binary. Max 2016 blocks per request. Useful for SPV header chain sync.

GET /block/count?minerId=<miner>

Returns the total number of blocks mined by a specific miner. Response: {"miner": "TAAL", "blocks": 12345}

GET /tx/<txid>

Returns a parsed transaction with inputs, outputs, and spend status.

GET /tx/<txid>/hex

Returns the raw transaction as a hex string.

GET /tx/<txid>/bin

Returns the raw transaction as binary.

GET /tx/<txid>/proof

Returns the merkle proof for a transaction.

GET /tx/<txid>/inscription/<vout>

Returns the inscription content embedded in the specified output. Served with the original MIME type (e.g. image/png, text/html). Returns 404 if no inscription exists at that output.

GET /tx/<txid>/nft/<vout>

Renders the NFT at the specified output, resolving the seed-inscription chain (re-inscriptions follow the prior tx's inscription content). Served with the original MIME type. Returns 404 if no inscription is reachable from that output.

GET /tx/<txid>/bfile/<vout>

Returns the B:// file content embedded in the specified output. Served with the original MIME type. Returns 404 if no B:// data exists at that output.

GET /tx/<txid>/media/<vout>

Returns embedded media from the output, auto-detecting the format (inscription, B://, or other on-chain media). Served with the detected MIME type. Returns 404 if no media is found.

GET /tx/<txid>/beef

Returns a BRC-95 Atomic BEEF bundle (transaction + ancestor chain + merkle proofs) as binary. Used for SPV verification.

GET /tx/<txid>/beef/hex

Returns a BRC-95 Atomic BEEF bundle as a hex string.

GET /tx/<txid>/status

Returns the confirmation status of a transaction.

GET /tx/<txid>/propagation

Returns propagation status across BSV nodes — shows which nodes have seen the transaction and whether it is in mempool or confirmed.

GET /tx/<txid>/graph

Returns the transaction ancestry graph — a tree of input transactions and their ancestors. Useful for visualizing transaction lineage.

POST /tx/broadcast

Broadcasts a raw transaction. Body: {"rawtx": "hex"}

POST /tx/broadcast/multi

Broadcasts multiple raw transactions. Body: array of hex strings.

GET /address/<addr>

Returns address info with balance and UTXO count.

GET /address/<addr>/txs?page=

Returns paginated transaction history for an address.

GET /address/<addr>/utxos?page=

Returns paginated UTXOs for an address.

GET /address/<addr>/balance

Returns just the balance for an address.

GET /address/<addr>/scripts

Returns the locking scripts associated with an address.

GET /address/<addr>/tokens

Returns BSV-21 token holdings for an address.

GET /address/<addr>/token/<tokenId>/history

Returns token transfer history for a specific token at an address.

GET /txo/<txid>/<vout>

Returns a specific transaction output.

GET /txo/<txid>/<vout>/spend

Returns the spending transaction for an output, if spent.

GET /download/tx/<txid>

Downloads the raw transaction as a binary file.

GET /download/tx/<txid>/hex

Downloads the raw transaction as a hex text file.

GET /download/tx/<txid>/output/<index>

Downloads a specific output script as binary.

GET /download/tx/<txid>/output/<index>/hex

Downloads a specific output script as hex.

GET /download/tx/<txid>/input/<index>

Downloads a specific input script as binary.

GET /download/tx/<txid>/input/<index>/hex

Downloads a specific input script as hex.

GET /download/tx/<txid>/receipt

Downloads a PDF receipt for a transaction.

GET /download/address/<addr>/statement

Downloads a PDF statement of recent transactions for an address.

GET /search?q=

Auto-detects query type (txid, block hash/height, address) and returns a redirect.

GET /stats/summary

Returns chain summary (height, hashrate, difficulty, price, market cap).

GET /stats/network

Returns daily network statistics (blocks, txs, fees, hashrate).

GET /stats/mining

Returns mining pool distribution.

GET /stats/mining/histogram?period=<24h|7d|30d>

Returns time-bucketed mining data. Bucket sizes: 24h→1h, 7d→6h, 30d→1d. Response: array of {"bucket": "...", "miner": "TAAL", "blocks": 5}

GET /stats/props/histogram?period=<24h|7d|30d>

Returns time-bucketed block property averages (size, tx count, fees). Bucket sizes: 24h→1h, 7d→6h, 30d→1d.

GET /stats/protocols?days=<7>

Returns protocol tag counts from recent transactions. Response: array of {"protocol": "ord", "tx_count": 5000}

GET /stats/protocols/histogram?period=<24h|7d|30d>

Returns time-bucketed protocol tag counts. Bucket sizes: 24h→1h, 7d→6h, 30d→1d. Response: array of {"bucket": "...", "protocol": "ord", "tx_count": 5000}

GET /stats/richlist?page=

Returns paginated rich list.

GET /stats/price-history

Returns historical BSV price data.

GET /stats/chart/<metric>

Returns time-series data for a given stat metric. Valid metrics: tx_count, total_fees, avg_fee, avg_fee_rate, avg_tx_size, median_fee, median_tx_size, total_output_value, coin_days_destroyed, hashrate, difficulty, avg_block_size, total_size, avg_tx_rate, miners_revenue, circulating_supply, utxo_count, blockchain_size, total_tx_count, exchange_rate, mining. Supports ?days= query parameter (default 30, max 1095).

GET /exchangerate

Returns the current BSV exchange rate in USD.

GET /exchangerates

Returns BSV exchange rates in multiple currencies.

GET /mempool

Returns mempool summary (tx count, size, usage, min fee).

GET /mempool/stats

Returns mempool fee rate and size distribution histograms. Response includes tx_count, total_fee_bsv, avg_fee_bsv, fee_rate_buckets (sat/byte ranges), and size_buckets (byte ranges). Cached for 30 seconds.

GET /mempool/protocols

Returns detected protocol tags in mempool transactions with counts. Each entry has protocol, short, color, and count. Parses every mempool tx for protocol detection (ORD, BSV21, MAP, B, etc.). Cached for 60 seconds.

GET /miner/fees

Returns current mining fee statistics.

GET /policy

Returns the current fee policy.

POST /tools/decode

Decodes a raw transaction. Body: {"rawtx": "hex"}

GET /tools/script/decode?hex=

Decodes a script hex string.

GET /tools/address/<addr>

Converts an address between formats. Returns the base58, scripthash, and script hex for a given address.

GET /tools/peers

Returns the connected node peers (proxies the BSV node's getpeerinfo). Each entry includes addr, services, conntime, version, subver, and traffic counters.

GET /tokens?page=

Returns a paginated list of all BSV-21 tokens.

GET /token/<tokenId>

Returns details for a specific token (name, symbol, supply, holder count).

GET /token/<tokenId>/holders?page=

Returns paginated list of token holders with balances.

GET /token/<tokenId>/history?page=

Returns paginated token transfer history.

POST /address/tokens/balance

Multi-address batch token balances. Body: {"addresses": ["addr1", "addr2", ...]} (max 20 addresses per request). Returns an array keyed per address: {"address", "tokens": [{"token_id", "symbol", "decimals", "balance"}]}. Invalid or failed addresses return a per-item "error" with "tokens": [] rather than failing the whole batch.

POST /address/tokens/unspent

Multi-address batch unspent token outputs. Body: {"addresses": ["addr1", "addr2", ...]} (max 20 addresses per request). Returns an array keyed per address: {"address", "utxos": [{"txid", "vout", "token_id", "symbol", "decimals", "amount", "block_height"}]}. Each address returns up to 100 most-recent unspent token UTXOs. When the returned list is not guaranteed complete — the 100 cap was reached, or (in Pebble mode) the spent-status scan hit its work guard on an address with a very large spent-token history — the entry includes "incomplete": true; treat such a list as partial. Invalid or failed addresses return a per-item "error" with "utxos": [].

GET /health

Returns "ok" if the server is running. (Not under /api/v1 prefix.)