chain_subscribeNewHeads - Acala RPC Method
Subscribe to new block headers on Acala. Real-time WebSocket notifications for every new block as it is produced — essential for monitoring, indexing, and event-driven applications on Polkadot's DeFi and liquidity hub with aUSD stablecoin and liquid staking (LDOT).
Subscribe to receive notifications when new block headers are produced on Acala. This WebSocket subscription provides real-time, push-based updates for each new block, making it more efficient than polling.
Why Acala? Build on Polkadot's DeFi and liquidity hub with aUSD stablecoin and liquid staking (LDOT) with $250M aUSD ecosystem fund, 150%+ LDOT TVL growth, micro gas fees payable in any token, and Coinbase Cloud partnership.
When to Use This Method
chain_subscribeNewHeads is essential for DeFi developers, stablecoin builders, and teams requiring cross-chain liquidity:
- Block Monitoring — Track new blocks in real time on Acala for decentralized stablecoin (aUSD), liquid DOT staking (LDOT), and cross-chain AMM DEX
- 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-acala.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 Acala 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 Acala:
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 Acala. Lightweight alternative to chain_getBlock for reading block metadata, parent hash, and state root on Polkadot's DeFi and liquidity hub with aUSD stablecoin and liquid staking (LDOT).
chain_subscribeFinalizedHeads
Subscribe to finalized block headers on Acala. Real-time WebSocket notifications for blocks that have achieved GRANDPA finality — essential for exchanges, bridges, and applications requiring irreversibility on Polkadot's DeFi and liquidity hub with aUSD stablecoin and liquid staking (LDOT).