chain_subscribeNewHeads - Moonbeam RPC Method
Subscribe to new block headers on Moonbeam. Real-time WebSocket notifications for every new block as it is produced — essential for monitoring, indexing, and event-driven applications on the cross-chain connected EVM platform on Polkadot with $65M+ TVL and 100+ projects.
Subscribe to receive notifications when new block headers are produced on Moonbeam. This WebSocket subscription provides real-time, push-based updates for each new block, making it more efficient than polling.
Why Moonbeam? Build on the cross-chain connected EVM platform on Polkadot with $65M+ TVL and 100+ projects with full EVM compatibility on Polkadot, native XCM cross-chain messaging, 10K+ TPS, 24% staking APR, and $0.015 transaction costs.
When to Use This Method
chain_subscribeNewHeads is essential for cross-chain dApp developers, Polkadot builders, and teams requiring multi-chain interoperability:
- Block Monitoring — Track new blocks in real time on Moonbeam for cross-chain DeFi, multi-chain dApps, and Ethereum-to-Polkadot bridging via XCM, Axelar, LayerZero, and Wormhole
- 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://api-moonbeam.n.dwellir.com/YOUR_API_KEY -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 Moonbeam 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 Moonbeam:
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 Moonbeam. Lightweight alternative to chain_getBlock for reading block metadata, parent hash, and state root on the cross-chain connected EVM platform on Polkadot with $65M+ TVL and 100+ projects.
chain_subscribeFinalizedHeads
Subscribe to finalized block headers on Moonbeam. Real-time WebSocket notifications for blocks that have achieved GRANDPA finality — essential for exchanges, bridges, and applications requiring irreversibility on the cross-chain connected EVM platform on Polkadot with $65M+ TVL and 100+ projects.