Bitcoin Core getblockheader RPC: Header Verification Guide

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

Verbose and raw modes

verbose defaults true and returns JSON; false returns serialised header hex. Pin the mode and response schema. For raw mode, enforce exact expected header length for the historical consensus format, parse byte order correctly and double-hash the header to verify it matches the requested display hash.

Active membership

confirmations is positive on the active chain and minus one for a known non-active block. That state can change after a reorganisation. Pair the observation with current best tip and chainwork and avoid claiming an old side-branch header is invalid merely because it is not active.

Merkle root boundary

The header commits to a transaction Merkle root, but getblockheader provides no transactions or inclusion path. To prove inclusion, get the transaction, its Merkle branch and the exact active header, then verify under Bitcoin’s transaction-tree rules and check enough active-chain depth.

Time fields

time is the miner-selected header timestamp constrained by consensus ranges, while mediantime derives from prior blocks and is used by several rules. Neither is a precise real-world event clock. Historical publication or payment systems should use observed time separately and avoid equating header time with receipt time.

Target and work

bits encodes the proof-of-work target, difficulty is a human-facing ratio and chainwork accumulates expected work. Verify header proof of work and difficulty transitions rather than trusting formatted values. Preserve chainwork as a large integer, not a floating-point number.

Ancestry and neighbours

previousblockhash links ancestry; nextblockhash is contextual and generally meaningful for active-chain data known to the node. Walk previous hashes to validate a chain segment. Do not assume one returned next hash proves there are no competing children or known forks.

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

getblockheader exposes the compact proof-of-work and ancestry record, but its interpretation depends on active-chain context. Safe use verifies raw identity, work and links and get separate evidence for transaction inclusion.