Blockchain RPCs

getbestblockhash

Returns the hash of the best (tip) block in the most-work fully-validated chain.

btx-cli getbestblockhash

Returns a hex-encoded 256-bit block hash string. No parameters.

getblock

Returns data about a block given its hash. Verbosity controls the detail level.

Parameter	Type	Required	Description
blockhash	string (hex)	Yes	The block hash
verbosity	number	No (default 1)	0 = hex data, 1 = JSON object, 2 = JSON with tx details, 3 = JSON with tx details and prevout info

btx-cli getblock "00000000c937..." 1

Key response fields (verbosity 1+):

Field	Description
hash	The block hash
confirmations	Number of confirmations, or -1 if not on the main chain
height	Block height
size, weight	Block size in bytes and BIP 141 weight units
merkleroot	Merkle root of all transactions
tx	Array of transaction ids (verbosity 1) or full tx objects (2+)
nonce64	64-bit BTX nonce
matmul_digest	MatMul transcript digest
matmul_dim	MatMul matrix dimension (512 on mainnet)
seed_a, seed_b	MatMul matrix seeds A and B
target	Difficulty target
difficulty	Floating-point difficulty
chainwork	Cumulative chain work (hex)
previousblockhash	Hash of previous block
nextblockhash	Hash of next block (if available)

getblockcount

Returns the height of the most-work fully-validated chain. The genesis block has height 0.

btx-cli getblockcount

Returns a single integer. No parameters.

getblockhash

Returns the hash of the block at the given height in the best chain.

Parameter	Type	Required	Description
height	number	Yes	Block height index

btx-cli getblockhash 1000

Returns the hex-encoded block hash at the specified height.

getblockheader

Returns header data for the given block hash. When verbose is false, returns serialized hex-encoded header data.

Parameter	Type	Required	Description
blockhash	string (hex)	Yes	The block hash
verbose	boolean	No (default true)	true for JSON object, false for hex-encoded data

btx-cli getblockheader "00000000c937..."

Verbose response includes all standard header fields plus BTX-specific MatMul fields (nonce64, matmul_digest, matmul_dim, seed_a, seed_b, target).

getblockstats

Compute per-block statistics for a given block. Works on blocks in the active chain only.

Parameter	Type	Required	Description
hash_or_height	string/number	Yes	Block hash (hex) or height
stats	array	No	Restrict results to specific stat names

btx-cli getblockstats 1000

Response includes: avgfee, avgfeerate, avgtxsize, ins, outs, maxfee, maxfeerate, medianfee, minfee, subsidy, swtotal_size, swtotal_weight, swtxs, total_out, total_size, total_weight, totalfee, txs, utxo_increase, utxo_size_inc, and more.

getchaintips

Return information about all known chain tips, including the main chain and orphaned branches.

btx-cli getchaintips

Returns an array of objects, each containing:

• height — tip height
• hash — tip block hash
• branchlen — branch length (0 for the active chain)
• status — one of: active, valid-fork, valid-headers, headers-only, invalid

getchaintxstats

Compute statistics about the total number and rate of transactions in the chain.

Parameter	Type	Required	Description
nblocks	number	No	Number of blocks to average over (default: one month)
blockhash	string (hex)	No	Hash of the block that ends the window

btx-cli getchaintxstats 2016

Response includes txcount, txrate (tx/sec), window_final_block_hash, window_final_block_height, window_block_count, window_interval, and window_tx_count.

gettxout

Returns details about an unspent transaction output (UTXO).

Parameter	Type	Required	Description
txid	string (hex)	Yes	The transaction id
n	number	Yes	The output index (vout)
include_mempool	boolean	No (default true)	Whether to include the mempool

btx-cli gettxout "txid" 0

Returns bestblock, confirmations, value, scriptPubKey (with asm, hex, type, address), and coinbase flag. Returns null if the UTXO has been spent.

gettxoutsetinfo

Returns statistics about the unspent transaction output set. This call may take several minutes on large chains.

Parameter	Type	Required	Description
hash_type	string	No (default "hash_serialized_3")	Hash algorithm: hash_serialized_3, muhash, or none
hash_or_height	string/number	No	Block hash or height to compute stats at
use_index	boolean	No (default true)	Use coinstats index if available

btx-cli gettxoutsetinfo

Response includes height, bestblock, txouts, total_amount, bogosize, hash_serialized_3 or muhash, and disk_size.

verifychain

Verifies blockchain database integrity.

Parameter	Type	Required	Description
checklevel	number	No (default 3)	Verification thoroughness (0-4)
nblocks	number	No (default 6)	Number of blocks to check (0 = all)

btx-cli verifychain 4 100

Returns true if verification succeeds.

getblockfilter

Retrieve a BIP 157 compact block filter for a particular block. Requires -blockfilterindex=basic.

Parameter	Type	Required	Description
blockhash	string (hex)	Yes	The block hash
filtertype	string	No (default "basic")	Filter type name

btx-cli getblockfilter "00000000c937..."

Returns filter (hex-encoded filter data) and header (hex-encoded filter header).

invalidateblock

Permanently marks a block as invalid, as if it violated a consensus rule. Use reconsiderblock to reverse.

Parameter	Type	Required	Description
blockhash	string (hex)	Yes	Hash of the block to mark as invalid

btx-cli invalidateblock "00000000c937..."

Returns nothing on success. This will trigger a reorg if the invalidated block is in the active chain.

reconsiderblock

Removes invalidity status of a block and its descendants, then reconsiders them for the active chain.

Parameter	Type	Required	Description
blockhash	string (hex)	Yes	Hash of the block to reconsider

btx-cli reconsiderblock "00000000c937..."

Returns nothing on success.

waitforblock

Waits for a specific block hash and returns its height. Make sure to use btx-cli -rpcclienttimeout=0.

Parameter	Type	Required	Description
blockhash	string (hex)	Yes	Block hash to wait for
timeout	number	No (default 0)	Timeout in milliseconds. 0 means no timeout.

btx-cli -rpcclienttimeout=0 waitforblock "00000000c937..." 60000

Returns hash and height of the current tip when the condition is met or on timeout.

waitfornewblock

Waits for any new block and returns info about it. Returns the current block on timeout or exit.

Parameter	Type	Required	Description
timeout	number	No (default 0)	Timeout in milliseconds. 0 means no timeout.
current_tip	string (hex)	No	Block hash; waits until the chain tip differs from this value

btx-cli -rpcclienttimeout=0 waitfornewblock 60000

Returns hash and height.

waitforblockheight

Waits until the chain reaches (at least) the specified block height, then returns the current tip.

Parameter	Type	Required	Description
height	number	Yes	Block height to wait for
timeout	number	No (default 0)	Timeout in milliseconds. 0 means no timeout.

btx-cli -rpcclienttimeout=0 waitforblockheight 50000 120000

Returns hash and height of the current tip when the condition is met or on timeout.