> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# subscribe ("newBlockHeaders") | Ethereum
> Reference docs for the subscribe ("newBlockHeaders") JSON-RPC method on the Ethereum blockchain, available via Chainstack JSON-RPC nodes.
Subscription equivalent to [eth\_newBlockFilter](/reference/ethereum-newblockfilter). `subscribe("newBlockHeaders")` allows developers to subscribe to real-time updates about new block headers on the Ethereum blockchain; the application will receive notifications whenever a new block is added to the blockchain. The notification will include information about the new block, such as its block number, hash, and timestamp.
## Parameters
* `string` — a keyword identifying the type of event to subscribe to, `newBlockHeaders` in this case. In ethers.js v6 this maps to the `"block"` event on a `WebSocketProvider`.
* `function` — a listener function that will be called every time a new block is received. With ethers.js v6, the listener receives the block number of the newly added block.
## Response
* `object`— a block object with the following fields:
* `number` — the block number of the requested block, encoded as hexadecimal. `null` if the block is pending.
* `hash` — the block hash of the requested block. `null` if the block pending.
* `parenthash` — hash of the previous block used to generate the current block. Also known as the 'parent block'.
* `nonce` — the hash used to demonstrate proof-of-work. `null` if the block pending. It returns `0x0000000000000000` when the consensus is proof-of-stake.
* `sha3uncles` — the hash of the list of uncles included in the block. It is used to identify the block uniquely and to verify the integrity of the block's data.
* `logsbloom` — the bloom filter for the logs of the block, a data structure that allows for efficient membership testing of elements in a set, in this case, the logs included in the block. `null` if pending.
* `transactionsroot` — the root of the transaction trie of the block. The `transactionsRoot` field allows Ethereum nodes to verify the integrity of the transactions in a block.
* `stateroot` — the root of the final state trie of the block. The `stateroot` field is included in the block header and is used to verify the integrity of the state at the time the block was processed
* `receiptsroot` — the root of the receipts trie of the block. A 32-byte hash of the root node of the receipts trie of all transactions in the block. It is used to verify the integrity of the receipts data for all transactions in the block.
* `miner` — the address of the miner receiving the reward.
* `difficulty` — a measure of how hard it is to find a valid block for the Ethereum blockchain. It is a number that increases as more miners join the network and more blocks are added to the chain, encoded as hexadecimal.
* `totaldifficulty` — the cumulative sum of the difficulty of all blocks that have been mined in the Ethereum network since the inception of the network. It measures the overall security and integrity of the Ethereum network.
* `extradata` — extra data included in a block by the miner who mined it. It often includes messages or other information related to the block.
* `size` — the size of this block in bytes as an integer value, encoded as hexadecimal.
* `gaslimit` — the maximum gas allowed in this block, encoded as hexadecimal.
* `gasused` — the total used gas by all transactions in this block, encoded as hexadecimal.
* `timestamp` — the Unix timestamp for when the block was collated.
* `transactions` — an array of transaction objects. See [eth\_getTransactionByHash](/reference/ethereum-gettransactionbyhash) for the exact shape.
* `uncles` — an array of uncle hashes.
## `subscribe("newBlockHeaders")` code example
Note that subscriptions require a WebSocket connection. Use a `WebSocketProvider` in ethers.js v6.
Use the provider event API to attach listeners to the provider:
* `provider.on("block", listener)` — fires for each new block and passes the block number to the listener.
* `provider.on("error", listener)` — fires if an error is detected on the connection.
* `provider.off("block", listener)` — removes a single listener for the `"block"` event.
* `provider.removeAllListeners()` — removes every listener, which effectively unsubscribes.
```javascript index.js theme={"system"}
const { ethers } = require("ethers");
const NODE_URL = "CHAINSTACK_WSS_ENDPOINT";
const provider = new ethers.WebSocketProvider(NODE_URL);
async function subscribeToNewBlocks() {
try {
// Subscribe to new blocks by listening for the 'block' event
provider.on("block", handleNewBlock);
provider.on("error", handleError);
console.log("Connected to the 'block' event");
} catch (error) {
console.error(`Error subscribing to new blocks: ${error}`);
}
}
// Listener functions to react to the different events
// Listener that fetches and logs the full block for each new block number
async function handleNewBlock(blockNumber) {
const blockHeader = await provider.getBlock(blockNumber);
console.log("New block header:", blockHeader);
}
// Listener that logs any errors that occur
function handleError(error) {
console.error("Error when subscribing to new block header:", error);
}
subscribeToNewBlocks();
```
## Use case
A practical use case for `subscribe("newBlockHeaders")` is a DApp that continuously listens for new block headers, then isolates the block number and `baseFeePerGas` for analytics purposes.
The following is an implementation of this concept using ethers.js v6 subscriptions:
```javascript index.js theme={"system"}
const { ethers } = require("ethers");
const NODE_URL = "CHAINSTACK_WSS_URL";
const provider = new ethers.WebSocketProvider(NODE_URL);
let blockCount = 0;
async function subscribeToNewBlocks() {
try {
// Subscribe to new blocks by listening for the 'block' event
provider.on("block", handleNewBlock);
provider.on("error", handleError);
console.log("Subscribed to the 'block' event");
} catch (error) {
console.error(`Error subscribing to new blocks: ${error}`);
}
}
async function unsubscribeFromNewBlocks() {
await provider.removeAllListeners();
console.log("Successfully unsubscribed from new blocks");
return process.exit(1);
}
/* Listener functions to react to the different events */
// Listener that extracts block number and base fee per gas from the received block
async function handleNewBlock(blockNumber) {
const blockHeader = await provider.getBlock(blockNumber);
const baseFeePerGas = ethers.formatUnits(blockHeader.baseFeePerGas, "gwei");
blockCount++;
console.log(
`Block number: ${blockNumber} \nBase Fee per Gas: ${baseFeePerGas} Gwei \n`
);
if (blockCount === 100) {
unsubscribeFromNewBlocks();
}
}
// Listener that logs any errors that occur
function handleError(error) {
console.error(`Error receiving new blocks: ${error}`);
}
subscribeToNewBlocks();
```
This code subscribes to new blocks by listening for the `"block"` event on a `WebSocketProvider`. Attaching a listener with `provider.on("block", ...)` starts the subscription and invokes the listener for every new block.
The code defines two listener functions that are attached to the provider: `handleNewBlock` and `handleError`. The `handleNewBlock` function is called when a new block is received; it fetches the full block with `provider.getBlock` and extracts the block number and base fee per gas, formatting the latter to gwei with `ethers.formatUnits`. The `handleError` function is called when an error occurs, and it logs an error message.
This code includes an `unsubscribeFromNewBlocks` function which removes the listeners with `provider.removeAllListeners` and quits the program using `return process.exit(1)` after it received 100 new blocks. This is to demonstrate its use.
Finally, the code calls the `subscribeToNewBlocks` function, which creates the subscription and attaches the event listeners. When a new block header is received, the `handleNewBlock` function is called to extract the block data and log it to the console.