REST API Documentation

Returns the calling key's tier, per-minute limit, and today's request total. The limit is shared by every key of the account; the total counts this key's requests only. Requires a key (401 otherwise). Response: {"key_prefix", "tier", "limit_per_min", "used_today", "reset_at"}.

Buys a higher tier for the calling key's account over x402, so every key of the account gets it, including keys created later; a key issued without an account gets it itself. Requires a key (401 otherwise).

1. Send it without an X402-Proof header. It answers 402 Payment Required, carrying the challenge both in an X402-Challenge header and in the JSON body.
2. Pay the challenge once.
3. Resend with X402-Proof: <proof> to get 200 and {"tier", "tier_expires_at", "txid", "amount_sats"}.

The target tier comes from ?tier= or a JSON body {"tier": "..."}, defaulting to the next purchasable tier above the key's current one. An open challenge is re-served rather than replaced. This route is exempt from the rate limiter, so a caller who has just exhausted their bucket can still upgrade. Other endpoints answer a rate-limited request with a 402 challenge only when the caller sends X-Payment-Accept: x402; otherwise they answer a plain 429.

Returns the current chain tip block.

Returns the latest block (alias for tip).

Returns a block by height or hash.

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.

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

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.

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

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

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

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

Returns a parsed transaction with inputs, outputs, and spend status. Use the always-present confirmed boolean (or block_height) to test confirmation: confirmations is omitted while a transaction is unconfirmed and only appears once it is mined.

Returns the raw transaction as a hex string.

Returns the raw transaction as binary.

Returns the merkle proof for a transaction in TSC format. Optional ?targetType= selects what target carries: merkleRoot (the default) or hash for the block hash. header returns 501 — the 80-byte header cannot be built here. Any other value returns 400.

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.

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.

Returns the first B:// file in the transaction without the caller naming an output index — this is what a bare b://<txid> reference resolves to, since the file is not always at output 0. Returns 404 if the transaction carries no B:// data.

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.

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.

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

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

Returns the confirmation status of a transaction.

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

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

Broadcasts a raw transaction. Body: {"rawtx": "hex"}. A 200 carries ARC's txStatus and accepted; check accepted, since a pending status (e.g. QUEUED) is still a 200. When ARC refuses this server's request rather than your transaction (authentication, rate limiting, a body cap), the answer is 502, or 503 with Retry-After when ARC is rate-limiting or timed out, never a 400: the transaction was not judged, so do not drop it.

Broadcasts up to 100 raw transactions in one request, as a JSON array of {"rawtx": "hex"} objects or one hex transaction per line. Each transaction spends one unit of your broadcast cap. The response holds one entry per transaction: check each entry's accepted, not the HTTP status.

Returns address info with balance and UTXO count.

Returns confirmed transaction history oldest→newest. Follow next_cursor with ?cursor=... to continue within a block; see Pagination above.

Returns paginated UTXOs for an address. Confirmed UTXOs only — unconfirmed change outputs still in the mempool are not included. Clients that spend unconfirmed change (e.g. faucets) should use the mempool-aware WoC-compatible endpoint /api/v1/bsv/main/address/<addr>/unconfirmed/unspent (bulk: POST /api/v1/bsv/main/addresses/unconfirmed/unspent). That list holds at most 1000 entries, the most recently added ones, and its error reads "truncated" when it was cut, unless the mempool tracker cannot vouch for the list, which carries a different error (see the WhatsonChain section below). The bulk form also stops at 5000 entries per request.

Returns just the balance for an address as a single confirmed balance field. Confirmed only — for a WoC-style {confirmed, unconfirmed} split, use the WoC-compatible /api/v1/bsv/main/address/<addr>/balance (or /confirmed/balance and the mempool-aware /unconfirmed/balance).

Returns the locking scripts associated with an address.

Returns BSV-21 token holdings for an address.

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

Returns a specific transaction output. A spent output carries spent_txid and spend_scope ("confirmed" or "unconfirmed"), the same mempool-aware signal as /txo/<txid>/<vout>/spend below. spend_scope is present only when the spender's block status was checked: it is omitted when that check failed or is backed off after a failure, while spent and spent_txid are still reported. Read a spent output without spend_scope as scope unknown, not as confirmed.

Returns the spending transaction for an output, if spent. Spend status is mempool-aware: a spent output also carries spendScope, which is "confirmed" when the spending transaction is in a block and "unconfirmed" when it is not in a block yet. An unconfirmed spend can still be dropped or double-spent, so wait for "confirmed" before treating it as final. spendScope is omitted when the output is spent but the spending transaction's block status could not be checked: spent and spentTxid are still reported, so read a spent output without spendScope as "scope unknown", not as confirmed. The outputs of /tx/<txid> carry the same signal as spend_scope, which is left out when an output is unspent or its scope could not be checked.

Downloads the raw transaction as a binary file.

Downloads the raw transaction as a hex text file.

Downloads a specific output script as binary.

Downloads a specific output script as hex.

Downloads a specific input script as binary.

Downloads a specific input script as hex.

Downloads a PDF receipt for a transaction. When the transaction's block or spend status could not be read it answers 503 with Retry-After and {"error": "Transaction status temporarily unavailable"} rather than print a guess.

Downloads a PDF statement of recent transactions for an address.

Downloads an address's recent transaction history as CSV, with the columns txid, block_height, block_hash, block_time, delta_satoshis, delta_bsv. Capped at the 100 most recent transactions, so treat it as a recent-activity export rather than a complete history.

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

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

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

Returns mining pool distribution.

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

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

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

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

Returns the paginated transaction list for a single protocol (same data as the /protocol/{key} HTML page), including the daily activity chart series. 404s if key is not a known protocol tag.

Returns daily tx-count history for a single protocol. days is clamped to 1–365 (default 90). Response: array of {"bucket": "...", "protocol": "ord", "tx_count": 5000}. 404s if key is not a known protocol tag.

Returns paginated rich list.

Returns historical BSV/USD prices, oldest first: [{"timestamp": ms, "price": usd}]. days defaults to 7, max 10000; history starts 2018-11-10 (the first daily close). Points are 5-minute for 1 day, hourly up to 90 days, daily beyond.

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 10000 — clamped to available history from genesis; long windows are downsampled).

Returns the current BSV exchange rate in USD.

Returns BSV exchange rates in multiple currencies.

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

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.

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.

Returns current mining fee statistics.

Returns the current fee policy.

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

Decodes a script hex string.

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

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

Returns a paginated list of all BSV-21 tokens.

Returns details for a specific token: id, symbol, decimals, icon, total_supply, circulating_supply, remaining_to_mint, holder_count, deploy_height, verified, suppressed and holders_refreshed_at. Every amount is a decimal string in the token's smallest unit — divide by 10^decimals for the display value. Amounts routinely exceed 2⁶³, so decode them as strings or big integers, never as a 64-bit number.

Returns paginated list of token holders with balances.

Returns paginated token transfer history.

Returns the token's icon inscription as an image, served with its original MIME type under a strict sandboxing CSP and cached immutably. Returns 404 when the token declares no icon or the icon inscription cannot be read.

Returns the token's deterministic 1sat fee address and live funding status: {"token_id", "fee_address", "fee_per_output", "status_available", "balance", "credits", "debits", "output_count", "is_active", "is_whitelisted", "is_blacklisted", "solicitable"}. The address is always present; the accounting fields are meaningful only when status_available is true. Gate any offer to pay on solicitable, which already folds in “status known and not blacklisted” — a bare "is_blacklisted": false is indistinguishable from “unknown”. A token this node does not have returns 404 rather than an address, so a mistyped id can never yield a valid-looking address whose deposits fund nothing.

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.

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": [].

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

Returns node-local observations cached in this process up to five seconds. It describes history relative to this node's committed data, not the network tip. This endpoint does not replace /health or existing read safety checks.

{"observed_at":"2026-09-08T19:00:00Z","history_state":"unknown","indexed_height":null,"committed_height":null,"history_reasons":["history_unavailable"],"token_maintenance_state":"unknown","token_maintenance_reasons":["maintenance_unavailable"]}

Registers a subscription. Form fields: selector, callback_url. Session-authenticated (dashboard form), not part of the /api/v1 surface.