Blockchain RPC Methods

Query blockchain data, blocks, transactions, and chain state using Bitcoin Core RPC methods

Blockchain RPC Methods

Blockchain RPCs provide access to Bitcoin blockchain data, including blocks, transactions, chain state, and UTXO information.

Chain Information

getblockchaininfo

Returns comprehensive information about the current state of the blockchain.

curl --user alice --data-binary '{"jsonrpc": "2.0", "id": "0", "method": "getblockchaininfo", "params": []}' \
  -H 'content-type: application/json' http://localhost:8332/

chain · string

Current network name (main, test, signet, regtest)

blocks · number

Current number of blocks processed

headers · number

Current number of headers validated

bestblockhash · string

Hash of the best (tip) block

difficulty · number

Current proof-of-work difficulty

time · number

Block time of the best block (Unix timestamp)

mediantime · number

Median time for the current best block

verificationprogress · number

Estimate of verification progress (0 to 1)

chainwork · string

Total amount of work in active chain (hex)

size_on_disk · number

Estimated size of the block and undo files on disk

pruned · boolean

Whether the blocks are subject to pruning

warnings · string

Any network and blockchain warnings

getblockcount

Returns the height of the most-work fully-validated chain.

bitcoin-cli getblockcount

result · number

The current block count (genesis block has height 0)

getbestblockhash

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

bitcoin-cli getbestblockhash

result · string

The block hash (hex-encoded)

getdifficulty

Returns the proof-of-work difficulty as a multiple of the minimum difficulty.

bitcoin-cli getdifficulty

result · number

The current difficulty

Block Operations

getblock

Returns information about a block at the given hash or height.

# Get block with transaction IDs
bitcoin-cli getblock "00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"

# Get block with full transaction details
bitcoin-cli getblock "00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09" 2

hash · string

Block hash (same as provided)

confirmations · number

Number of confirmations (-1 if block is not in main chain)

height · number

Block height

version · number

Block version

merkleroot · string

Merkle root hash

time · number

Block time (Unix timestamp)

mediantime · number

Median time past

nonce · number

Block nonce

bits · string

Difficulty target bits (hex)

difficulty · number

Difficulty

chainwork · string

Expected chain work (hex)

tx · array

Transaction IDs (verbosity 1) or full transaction objects (verbosity 2+)

previousblockhash · string

Hash of previous block

nextblockhash · string

Hash of next block (if available)

getblockhash

Returns the hash of the block at the given height.

bitcoin-cli getblockhash 1000

result · string

The block hash at the specified height

getblockheader

Returns information about a block header.

bitcoin-cli getblockheader "00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"

getblockstats

Computes per-block statistics for a given window.

bitcoin-cli getblockstats 1000 '["avgfee", "avgfeerate", "txs"]'

avgfee · number

Average fee in the block

avgfeerate · number

Average feerate (satoshis per virtual byte)

avgtxsize · number

Average transaction size

blockhash · string

Block hash

height · number

Block height

maxfee · number

Maximum fee in the block

maxfeerate · number

Maximum feerate

mintxsize · number

Minimum transaction size

totalfee · number

Total fees in the block

txs · number

Number of transactions (excluding coinbase)

Transaction Operations

gettxout

Returns details about an unspent transaction output (UTXO).

bitcoin-cli gettxout "txid" 1

bestblock · string

Hash of the block at tip of chain

confirmations · number

Number of confirmations

value · number

Transaction value in BTC

scriptPubKey · object

Script pubkey information including asm, hex, type, and address

coinbase · boolean

Whether this is a coinbase transaction

Returns null if the transaction output is spent or doesn’t exist.

gettxoutsetinfo

Returns statistics about the unspent transaction output set.

bitcoin-cli gettxoutsetinfo

height · number

Block height

bestblock · string

Best block hash

txouts · number

Number of unspent transaction outputs

total_amount · number

Total amount in BTC

getrawtransaction

Returns raw transaction data.

# Get raw transaction as hex
bitcoin-cli getrawtransaction "txid"

# Get detailed transaction information
bitcoin-cli getrawtransaction "txid" true

Chain State Queries

getchaintips

Returns information about all known chain tips.

bitcoin-cli getchaintips

Returns array of chain tips with:

height · number

Height of the chain tip

hash · string

Block hash of the tip

branchlen · number

Length of branch connecting tip to main chain (0 for main chain)

status · string

Status: active, valid-fork, valid-headers, headers-only, invalid

getchaintxstats

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

bitcoin-cli getchaintxstats 2016

verifychain

Verifies blockchain database integrity.

bitcoin-cli verifychain 4 1000

result · boolean

Whether verification passed

Waiting for Blocks

waitfornewblock

Waits for a new block and returns useful info about it.

bitcoin-cli -rpcclienttimeout=0 waitfornewblock

waitforblock

Waits for a specific block hash and returns useful info.

bitcoin-cli waitforblock "0000000000000000000065bda8f8a88f2e1e00d9a6887a43d640e52a4c7660f2" 1000

waitforblockheight

Waits for blockchain to reach a specific height.

bitcoin-cli waitforblockheight 700000 60000