Skip to main content

chain_subscribeNewHeads - JSON-RPC Method

Description#

Establishes a WebSocket subscription that pushes real-time notifications whenever a new block header is imported by the Acala node. This method provides the fastest way to track chain activity, delivering header information as soon as blocks are produced and imported, even before finalization. The subscription remains active until explicitly unsubscribed, continuously streaming headers for all new blocks. This is essential for applications requiring immediate awareness of chain state changes, such as block explorers, trading bots, or monitoring services.

WebSocket Example (raw JSON-RPC)#

const ws = new WebSocket('wss://api-acala.n.dwellir.com/YOUR_API_KEY');
ws.onopen = () => {
  ws.send(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'chain_subscribeNewHeads', params: [] }));
};
ws.onmessage = (evt) => console.log(JSON.parse(evt.data));

@polkadot/api Example#

const unsub = await api.rpc.chain.subscribeNewHeads((h) => console.log(`#${h.number}`));

Parameters#

This method takes no parameters. The subscription begins immediately upon successful WebSocket connection and authentication.

Response Format#

Each notification contains a complete block header with the following key information:

  • Block Number: Sequential height of the block in the chain
  • Parent Hash: Hash of the previous block, forming the chain linkage
  • State Root: Merkle root of the state trie after block execution
  • Extrinsics Root: Merkle root committing to all extrinsics in the block
  • Digest: Consensus-related logs including seals, pre-runtime digests, and other validator data

The initial response includes a subscription ID used for managing the subscription lifecycle.

Use Cases#

  • Real-time Block Explorers: Display latest blocks immediately as they're produced
  • Transaction Monitoring: Watch for blocks that may contain pending transactions
  • Chain Analytics: Track block production rates and timing patterns in real-time
  • Event Streaming: Trigger immediate actions based on new block events
  • Network Monitoring: Detect chain activity anomalies or production delays
  • DApp Synchronization: Keep application state synchronized with the latest chain data

Best Practices#

Maintain persistent WebSocket connections with automatic reconnection logic to handle network interruptions. Remember that subscribed blocks are imported but not yet finalized, so they may be subject to reorganization in rare cases. For finality-sensitive operations, use chain_subscribeFinalizedHeads instead. Always properly unsubscribe when the subscription is no longer needed to free server resources. Handle the continuous stream asynchronously to avoid blocking your application's main thread.

Subscription Management#

Store the subscription ID returned in the initial response to enable graceful unsubscription. Use chain_unsubscribeNewHeads with this ID when you need to stop receiving notifications. Proper subscription cleanup is essential for production applications to prevent resource leaks and maintain optimal performance.