blockchainHeadersSubscribe

Overview

The blockchain.headers.subscribe method allows clients to subscribe to new block headers as they are discovered on the network. This subscription is essential for applications that need real-time updates on blockchain changes without polling the server for the latest block.

Subscription

Upon subscribing, the client immediately receives the current blockchain tip's header. Following this initial response, the client will receive updates whenever new blocks are found.

Returns

The response and subsequent updates provide the header in a dictionary format:

Example Result

{
  "height": 520481,
  "hex": "00000020890208a0ae3a3892aa047c5468725846577cfcd9b512b50000000000000000005dc2b02f2d297a9064ee103036c14d678f9afc7e3d9409cf53fd58b82e938e8ecbeca05a2d2103188ce804c4"
}

Request Example

curl --location 'https://api.tatum.io/v3/blockchain/node/bitcoin-mainnet-electrs/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {API_KEY}' \
--data '{
    "method": "blockchain.headers.subscribe",
    "params": [],
    "id": 1,
    "jsonrpc": "2.0"
}'

// yarn add @tatumio/tatum

import { TatumSDK, BitcoinElectrs, Network } from '@tatumio/tatum'

const tatum = await TatumSDK.init<BitcoinElectrs>({ network: Network.BITCOIN_ELECTRS })

const subscribeHeaders = await tatum.rpc.subscribeBlockHeaders()

subscribeHeaders.on('data', (header) => {
  console.log('New Block Header:', header)
})

await tatum.destroy() // Destroy Tatum SDK - needed for stopping background jobs when done

Note

• Chain Reorganisations: Clients should handle potential blockchain reorganizations where the new chain tip may not directly extend the previous one. Clients must be prepared to identify the common ancestor and request any missing headers to maintain a consistent view of the chain state.
• Multiple Subscriptions: If a client attempts multiple subscriptions, only the first one is active; additional requests do not result in multiple sets of notifications.