Docs
Supported ChainsAsset HubSubstrate APIChain Methods

chain_subscribeFinalizedHeads - Asset Hub RPC Method

Subscribe to finalized block headers on Asset Hub. Real-time notifications for blocks that have achieved finality.

Subscribe to receive notifications when blocks are finalized on Asset Hub. Finalized blocks are guaranteed to never be reverted, making this essential for applications requiring strong consistency.

Use Cases

  • Exchange deposits - Only credit funds after finalization for native stablecoin transfers (USDC, USDT), DOT staking and governance, and cross-chain asset management via XCM
  • Bridge operations - Wait for finality before cross-chain transfers
  • Critical state changes - Ensure irreversibility for important transactions

Request Parameters

Request

This method accepts no parameters.

Response Body

Response
parentHashHash

Parent block hash

numberBlockNumber

Block number

stateRootHash

State trie root hash

extrinsicsRootHash

Extrinsics trie root hash

digestDigest

Block digest with consensus logs

Code Examples

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

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

// Subscribe to finalized heads
const unsubscribe = await api.rpc.chain.subscribeFinalizedHeads((header) => {
  console.log(`Finalized block #${header.number}`);
  console.log(`  Hash: ${header.hash.toHex()}`);

  // Safe to consider this block permanent
  processConfirmedBlock(header);
});

// Later: unsubscribe()
Python
import asyncio
import websockets
import json

async def subscribe_finalized():
    uri = 'wss://api-asset-hub-polkadot.n.dwellir.com/YOUR_API_KEY'

    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            'jsonrpc': '2.0',
            'method': 'chain_subscribeFinalizedHeads',
            'params': [],
            'id': 1
        }))

        response = json.loads(await ws.recv())
        sub_id = response['result']
        print(f'Subscribed to finalized heads: {sub_id}')

        while True:
            message = json.loads(await ws.recv())
            if 'params' in message:
                header = message['params']['result']
                block_num = int(header['number'], 16)
                print(f"Finalized: #{block_num}")

asyncio.run(subscribe_finalized())

Finality Lag

Finalized blocks typically lag behind the best block by a few blocks due to GRANDPA consensus requirements. This is normal and ensures Byzantine fault tolerance.

chain_subscribeNewHeads

Subscribe to new block headers on Asset Hub. Real-time notifications for new blocks as they are produced.

state_getStorage

Query storage values on Asset Hub. Essential for reading chain state for native stablecoin transfers (USDC, USDT), DOT staking and governance, and cross-chain asset management via XCM.

On this page

Use Cases
Code Examples
Finality Lag
Related Methods