REST API

BTX exposes an unauthenticated REST interface alongside the JSON-RPC interface. Enable it with the -rest flag when starting btxd. The REST API runs on the same port as RPC (default 19334 for mainnet).

./build-btx/bin/btxd -daemon -server -rest

No authentication is required. The same consistency guarantees as the RPC interface apply.

---

Format Options

Most endpoints support three output formats via file extension:

Extension	Content-Type	Description
.json	application/json	JSON object
.hex	text/plain	Hex-encoded binary
.bin	application/octet-stream	Raw binary

---

Blocks

Get Block

GET /rest/block/.

Returns a full block by hash. Responds with 404 if the block does not exist.

curl -s http://127.0.0.1:19334/rest/block/00000000000000...abc.json | jq .

Get Block (without transaction details)

GET /rest/block/notxdetails/.

Same as above but JSON responses contain only transaction hashes instead of full transaction objects.

Block Hash by Height

GET /rest/blockhashbyheight/.

Given a height, returns the hash of the block at that position in the best chain.

# Get the hash of block 50000
curl -s http://127.0.0.1:19334/rest/blockhashbyheight/50000.json | jq .

---

Block Headers

GET /rest/headers/.?count=

Returns COUNT block headers starting from the given hash, in upward direction. Defaults to 5. Returns empty if the block does not exist or is not in the active chain.

# Get 10 headers starting from a block hash
curl -s "http://127.0.0.1:19334/rest/headers/00000000...abc.json?count=10" | jq .

---

Transactions

GET /rest/tx/.

Returns a transaction by hash. Responds with 404 if not found.

By default, this endpoint searches only the mempool. To query confirmed transactions, enable the transaction index:

btxd -txindex=1 -rest

# Fetch a transaction as JSON
curl -s http://127.0.0.1:19334/rest/tx/abc123...def.json | jq .

---

Chain Info

GET /rest/chaininfo.json

Returns blockchain processing state. JSON only. Equivalent to the getblockchaininfo RPC.

curl -s http://127.0.0.1:19334/rest/chaininfo.json | jq .

---

Deployment Info

GET /rest/deploymentinfo.json
GET /rest/deploymentinfo/.json

Returns consensus deployment state at the current tip or at a specific block hash. JSON only. Equivalent to getdeploymentinfo.

---

Mempool

Mempool Info

GET /rest/mempool/info.json

Returns mempool statistics. JSON only. Equivalent to getmempoolinfo.

curl -s http://127.0.0.1:19334/rest/mempool/info.json | jq .

Mempool Contents

GET /rest/mempool/contents.json?verbose=&mempool_sequence=

Returns all transactions in the mempool. JSON only. Defaults to verbose=true and mempool_sequence=false. Equivalent to getrawmempool.

---

UTXO Set

GET /rest/getutxos/-/-/.../-.
GET /rest/getutxos/checkmempool/-/.../-.

Query the UTXO set for a list of outpoints. The /checkmempool/ variant also considers unconfirmed transactions.

# Check a specific UTXO (include mempool)
curl -s http://127.0.0.1:19334/rest/getutxos/checkmempool/b2cdfd7b...5d75-0.json | jq .

Example response:

{
  "chainHeight": 52347,
  "chaintipHash": "00000000fb01a7f3...",
  "bitmap": "1",
  "utxos": [
    {
      "height": 52100,
      "value": 8.8687,
      "scriptPubKey": {
        "asm": "...",
        "type": "pubkeyhash",
        "address": "..."
      }
    }
  ]
}

---

Block Filters

Get Block Filter

GET /rest/blockfilter//.

Returns the block filter for the given block and filter type. Responds with 404 if the block does not exist.

Block Filter Headers

GET /rest/blockfilterheaders//.?count=

Returns COUNT block filter headers starting from the given hash. Defaults to 5.

---

Spent Transaction Outputs

GET /rest/spenttxouts/.

Returns spent transaction output lists for each transaction in the block. Responds with 404 if the block does not exist or its undo data is unavailable.

---

Fee Estimates

GET /rest/fee//.json

MODE is one of unset, conservative, or economical. TARGET is the desired confirmation time in blocks.

# Get economical fee estimate for 6-block confirmation
curl -s http://127.0.0.1:19334/rest/fee/economical/6.json | jq .

---

Consistency Guarantees

The REST API provides the same consistency guarantees as the JSON-RPC interface. Responses reflect the state at the time the request is processed, but the chain tip may advance between requests.

---

Limitations

• Connection limits: Opening too many HTTP connections simultaneously can exhaust file descriptors and crash the node. Consider increasing your system's file descriptor limit and rate-limiting client connections.
• In-memory handling: Block requests are handled entirely in memory. Very large blocks may consume significant RAM.
• XSS risk: Running a web browser on the same machine with REST enabled can allow cross-site requests to read chain data via script tags targeting http://127.0.0.1:19334/rest/....

---

Default Ports

Network	RPC/REST Port
Mainnet	19334
Testnet	29334
Testnet4	48332
Signet	38332
Regtest	18443