Bitcoin Core getblockstats RPC: Per-Block Fee and UTXO Guide

This guide explains Bitcoin Core getblockstats RPC in plain English. It shows what the command does, what its result means and what it cannot prove.

Hash or height target

Accept an explicit block hash or integer height and record the node tip at query time. Height can map to another block after a reorganisation, while hash fixes identity. Compare returned blockhash with the expected active-chain block before storing a time series.

Selective statistics

The optional stats array limits returned values and can reduce work and payload. Use an allow-list of documented names, reject duplicates and unknown values and version dashboards. Do not request every field by default when only two operational metrics are needed.

Units and exclusions

All monetary amounts are satoshis. Average and percentile fee rates are satoshis per virtual byte. Transaction counts, sizes, weights and total outputs follow documented coinbase exclusions. Preserve integer units and definitions rather than converting early or comparing unlike metrics.

Percentile meaning

Fee-rate percentiles are calculated at specified weight-unit points, not simple percentiles over transaction count. Average, median, minimum and maximum can be distorted by a block’s particular composition. Keep the methodology with exported data and avoid treating one block as a fee recommendation.

Index and pruning limits

Pruning can make some heights unavailable. Without txindex, UTXO-size-increase and fee or fee-rate statistics may not work. Detect capabilities before bulk jobs and record missing as unavailable, not zero. Do not trigger a production reindex merely for an optional chart without planning.

Reorganisation handling

Store block hash, height and collection tip with every row. Recheck recent blocks after reorganisation depth and replace orphaned observations through an auditable correction. Statistics from a valid side-branch block are not active-chain history.

How specialists test it

Operators test the command on a non-production node first. They check a normal reply, an invalid request, a timeout and a restart. This shows what the response means and prevents one local result from being mistaken for a network-wide outcome.

Conclusion

getblockstats is a precise per-block analytical tool when identity, units and node capabilities are recorded. It is not a live fee estimator and its recent results must remain reorganisation-aware.