⚠️Blast API (blastapi.io) ends Oct 31. Migrate to Dwellir and skip Alchemy's expensive compute units.
Switch Today →
Skip to main content

chain_subscribeFinalizedHeads

Subscribes to GRANDPA-finalized headers. Each notification includes the header of the latest finalized block, allowing you to trigger compliance pipelines, zkSBT state snapshots, or cross-chain relays the moment finality lands.

Parameters​

This subscription does not accept parameters.

Notifications​

Each notification payload matches the structure returned by chain_getHeader and includes the subscription ID.

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 unsub = await api.rpc.chain.subscribeFinalizedHeads((header) => {
  const blockNumber = header.number.toNumber();
  console.log('Finalized block', blockNumber, header.hash.toHex());
});

// Later, when you want to stop listening
await unsub();

Raw JSON-RPC Frames​

// Subscription request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "chain_subscribeFinalizedHeads",
  "params": []
}

// Sample notification
{
  "jsonrpc": "2.0",
  "method": "chain_finalizedHead",
  "params": {
    "subscription": "0x1",
    "result": {
      "number": "0x62726a",
      "hash": "0x12dbd70ed24bffa8ecf8a0ac1a3ab639cdb4ce462f32fbfa33f33017dae6a604",
      "parentHash": "0xbec4859ed2032e0e046e7a78a3882c5ae8b7d51d16a083635d5b5ad309b30d12",
      "stateRoot": "0x84351d19940a55e597b6d8b95176bf0c900935fb7e268bad21c0ba1e91ea9eca"
    }
  }
}

Operational Tips​

  • Persist finalized headers in your indexer to anchor zkSBT attestations and compliance proofs.
  • For faster-but-unsafe previews, use chain_subscribeNewHeads and reconcile once finality arrives.
  • Keep track of the subscription handle returned by @polkadot/api so you can call it to unsubscribe when your process exits.