chain_subscribeNewHeads

Streams every new block header as soon as the node imports it (before GRANDPA finality). This is ideal for latency-sensitive dashboards and indexers that can tolerate short-lived forks.

Parameters

This subscription does not accept parameters.

Example (@polkadot/api)

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

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

const unsubscribe = await api.rpc.chain.subscribeNewHeads((header) => {
  console.log('New block', header.number.toNumber(), header.hash.toHex());
});

// Disconnect when done
await unsubscribe();

Raw Notification

{
  "jsonrpc": "2.0",
  "method": "chain_newHead",
  "params": {
    "subscription": "0x1",
    "result": {
      "number": "0x62726b",
      "hash": "0x0d9ccb8e2e8e6a33de2e9f0e9dfb0f80724dc5a548fdde8d93e5de1b0c8f3fce",
      "parentHash": "0x12dbd70ed24bffa8ecf8a0ac1a3ab639cdb4ce462f32fbfa33f33017dae6a604"
    }
  }
}

Operational Tips

• Pair with chain_getBlock to enrich headers with extrinsics and events.
• Reconcile against chain_subscribeFinalizedHeads to identify re-orged blocks.
• Apply backpressure in your consumer to avoid dropping notifications when block production spikes.

Related Methods

• chain_getHeader
• chain_subscribeFinalizedHeads
• chain_getBlock