chain_subscribeNewHeads - Bridge Hub RPC Method
Subscribe to new block headers on Bridge Hub. Real-time WebSocket notifications for every new block as it is produced — essential for monitoring, indexing, and event-driven applications on Polkadot's trustless bridging parachain with $75M+ TVL via Snowbridge to Ethereum.
Subscribe to receive notifications when new block headers are produced on Bridge Hub. This WebSocket subscription provides real-time, push-based updates for each new block, making it more efficient than polling.
Why Bridge Hub? Build on Polkadot's trustless bridging parachain with $75M+ TVL via Snowbridge to Ethereum with on-chain BEEFY/Beacon light clients (no multisigs), 100+ ERC-20 tokens supported, 24+ parachain integrations, and 1-2 minute transfer times.
When to Use This Method
chain_subscribeNewHeads is essential for cross-chain developers, bridge operators, and teams requiring trustless Ethereum-Polkadot transfers:
- Block Monitoring — Track new blocks in real time on Bridge Hub for trustless ETH and ERC-20 bridging, cross-chain messaging, and parachain-to-Ethereum asset transfers
- Event Indexing — Trigger processing pipelines when new blocks arrive
- Chain Synchronization — Keep external databases and systems in sync with the chain
- Dashboard Updates — Push live block data to monitoring dashboards
Code Examples
# WebSocket subscription (requires wscat or similar tool)
wscat -c wss://bridge-hub-polkadot-rpc.n.dwellir.com -x '{
"jsonrpc": "2.0",
"method": "chain_subscribeNewHeads",
"params": [],
"id": 1
}'Common Use Cases
1. Real-Time Block Indexer
Index new blocks and their events on Bridge Hub as they arrive:
async function indexBlocks(api, onBlock) {
const unsub = await api.rpc.chain.subscribeNewHeads(async (header) => {
const blockHash = header.hash;
const [block, events] = await Promise.all([
api.rpc.chain.getBlock(blockHash),
api.query.system.events.at(blockHash)
]);
const blockData = {
number: header.number.toNumber(),
hash: blockHash.toHex(),
parentHash: header.parentHash.toHex(),
extrinsicCount: block.block.extrinsics.length,
eventCount: events.length,
timestamp: Date.now()
};
await onBlock(blockData);
});
return unsub;
}2. Block Production Monitor
Detect block production delays on Bridge Hub:
async function monitorBlockProduction(api, expectedBlockTimeMs = 6000) {
let lastBlockTime = Date.now();
const threshold = expectedBlockTimeMs * 3;
const unsub = await api.rpc.chain.subscribeNewHeads((header) => {
const now = Date.now();
const elapsed = now - lastBlockTime;
if (elapsed > threshold) {
console.warn(
`Block #${header.number}: ${elapsed}ms since last block (expected ~${expectedBlockTimeMs}ms)`
);
} else {
console.log(`Block #${header.number}: ${elapsed}ms`);
}
lastBlockTime = now;
});
return unsub;
}3. Live Dashboard Feed
Stream block data to a WebSocket-connected frontend:
async function streamToClients(api, wss) {
const unsub = await api.rpc.chain.subscribeNewHeads(async (header) => {
const message = JSON.stringify({
type: 'new_block',
number: header.number.toNumber(),
hash: header.hash.toHex(),
parentHash: header.parentHash.toHex(),
stateRoot: header.stateRoot.toHex()
});
wss.clients.forEach((client) => {
if (client.readyState === 1) {
client.send(message);
}
});
});
return unsub;
}Subscription vs Polling
| Approach | Latency | Resource Usage | Use Case |
|---|---|---|---|
subscribeNewHeads | Immediate | Low (push-based) | Real-time monitoring, indexing |
Polling getHeader | Block time + poll interval | Higher (repeated requests) | Simple integrations, HTTP-only |
Error Handling
| Error Code | Description | Solution |
|---|---|---|
| -32603 | Internal error | Node may be syncing — retry connection |
| -32601 | Method not found | Verify the node supports WebSocket subscriptions |
| -32005 | Rate limit exceeded | Reduce subscription count per connection |
| Connection closed | WebSocket disconnected | Implement automatic reconnection with backoff |
Related Methods
chain_subscribeFinalizedHeads— Subscribe to finalized blocks only (for irreversible state)chain_getHeader— Get a specific block header by hashchain_getBlock— Get full block data with extrinsicschain_unsubscribeNewHeads— Unsubscribe from new heads
chain_getHeader
Get block header on Bridge Hub. Lightweight alternative to chain_getBlock for reading block metadata, parent hash, and state root on Polkadot's trustless bridging parachain with $75M+ TVL via Snowbridge to Ethereum.
chain_subscribeFinalizedHeads
Subscribe to finalized block headers on Bridge Hub. Real-time WebSocket notifications for blocks that have achieved GRANDPA finality — essential for exchanges, bridges, and applications requiring irreversibility on Polkadot's trustless bridging parachain with $75M+ TVL via Snowbridge to Ethereum.