chain_subscribeAllHeads - JSON-RPC Method

Subscribes to every imported block header over a WebSocket connection, including non-finalized fork heads. This is useful when you need the earliest possible view of block production rather than only finalized chain state.

The initial JSON-RPC response returns a subscription ID. Header payloads are delivered afterward as WebSocket notifications for that subscription.

Code Examples

This method requires a WebSocket connection and is not available over HTTP.

WebSocket (wscat)

wscat -c wss://api-bittensor-mainnet.n.dwellir.com/YOUR_API_KEY \
  -x '{
    "jsonrpc": "2.0",
    "method": "chain_subscribeAllHeads",
    "params": [],
    "id": 1
  }'

JavaScript

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

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

const unsub = await api.rpc.chain.subscribeAllHeads((header) => {
  console.log(`Imported block #${header.number}`);
  console.log(`Hash: ${header.hash?.toHex?.() ?? 'notification header'}`);
});

// Later: unsub();

Use Cases

• Fork-aware indexers -- Process every imported head, including temporary forks, before finalization settles.
• Latency-sensitive monitoring -- React to new blocks as soon as they are imported by the node.
• Chain analytics -- Observe short-lived fork activity or competing block candidates during periods of network churn.

Notes

• This subscription emits more updates than chain_subscribeNewHeads because it includes non-finalized heads.
• Cancel the subscription with chain_unsubscribeAllHeads when you no longer need updates.
• Use chain_subscribeFinalizedHeads if your workflow only cares about finalized blocks.

Related Methods

• chain_unsubscribeAllHeads -- Cancel this subscription
• chain_subscribeNewHeads -- Subscribe to canonical new heads
• chain_subscribeFinalizedHeads -- Subscribe to finalized heads only