chain_subscribeNewHeads

Description

Subscribes to notifications for every new block imported by the node. Each update includes the block header so you can monitor chain progress, trigger indexers, or feed analytics pipelines.

Parameters

This subscription does not take parameters.

Returns

Each notification contains:

Field	Type	Description
parentHash	string	Hash of the parent block
number	string	Block number encoded as hex
stateRoot	string	State trie root
extrinsicsRoot	string	Extrinsics root
digest	object	Digest logs

Subscription Example

{
  "jsonrpc": "2.0",
  "method": "chain_subscribeNewHeads",
  "params": [],
  "id": 1
}

Sample Notification

{
  "jsonrpc": "2.0",
  "method": "chain_subscribeNewHeads",
  "params": {
    "result": {
      "parentHash": "0x2b35e249b7bb267e2a6a786f346ff9a383f6fec2bf2f606045c2cfa5d338e9e8",
      "number": "0x9055ee",
      "stateRoot": "0x8440501a34445deca91eb0f3a2a5fb9c66b2d1b62060fb9127c31435ac0066a8",
      "extrinsicsRoot": "0xfe5036ad098f495de005059f695ca574814695efdbc6b7649b1bade7a4e88f68",
      "digest": {
        "logs": [
          "0x0661757261208a2c7a1100000000",
          "0x0452505352903006d1651014effe612aeb9e2bed207fca849e69a1d4594bdab580afc68677458a62ad06"
        ]
      }
    },
    "subscription": 1
  }
}

JavaScript Usage

import { ApiPromise, WsProvider } from '@polkadot/api';

const provider = new WsProvider('wss://api-bifrost-polkadot.n.dwellir.com/YOUR_API_KEY');
const api = await ApiPromise.create({ provider });

const unsub = await api.rpc.chain.subscribeNewHeads((header) => {
  console.log(`New block #${header.number.toString()} (${header.hash.toHex()})`);
});

// Later, to stop listening
// await unsub();

Tips

• Pair with state_getStorage for incremental indexing (fetch storage deltas per block).
• Use chain_subscribeFinalizedHeads when you only care about finalized blocks.