The getblocks message requests an inv message that provides block header hashes starting from a particular point in the block chain. It allows a peer which has been disconnected or started for the first time to get the data it needs to request the blocks it hasn’t seen.

Peers which have been disconnected may have stale blocks in their locally-stored block chain, so the “getblocks” message allows the requesting peer to provide the receiving peer with multiple header hashes at various heights on their local chain. This allows the receiving peer to find, within that list, the last header hash they had in common and reply with all subsequent header hashes.

Note: the receiving peer itself may respond with an “inv” message containing header hashes of stale blocks. It is up to the requesting peer to poll all of its peers to find the best block chain.

If the receiving peer does not find a common header hash within the list, it will assume the last common block was the genesis block (block zero), so it will reply with in “inv” message containing header hashes starting with block one (the first block after the genesis block).

The “getheaders” message is nearly identical to the “getblocks” message, with one minor difference: the inv reply to the “getblocks” message will include no more than 500 block header hashes; the headers reply to the “getheaders” message will include as many as 2,000 block headers.


Data Type






The protocol version number; the same as sent in the “version” message.

hash count



The number of header hashes provided not including the stop hash. There is no limit except that the byte size of the entire message must be below the “MAX_SIZE” limit; typically from 1 to 200 hashes are sent.

block header hashes



One or more block header hashes (32 bytes each) in internal byte order. Hashes should be provided in reverse order of block height, so highest-height hashes are listed first and lowest-height hashes are listed last.

stop hash



The header hash of the last header hash being requested; set to all zeroes to request an “inv” message with all subsequent header hashes (a maximum of 500 will be sent as a reply to this message; if you need more than 500, you will need to send another “getblocks” message with a higher-height header hash as the first entry in block header hash field).

The annotated hexdump below shows a “getblocks” message. (The message header has been omitted.)

71110100 ........................... Protocol version: 70001
02 ................................. Hash count: 2

105e55a16a14d31b0000000000000000 ... Hash #1

714bda7ce23bea0a0000000000000000 ... Hash #2

00000000000000000000000000000000 ... Stop hash