Skip to main content
Monad API method that streams new block headers starting when a block reaches the Proposed state in Monad’s consensus lifecycle, and again as the block advances. Each notification includes two Monad-specific fields, blockId and commitState, that let you follow a block through every stage of its lifecycle: Proposed → Voted → Finalized → Verified.
Monad’s real-time data behavior, including the commit state at which standard newHeads fires, is still evolving. For the authoritative spec, see the Monad WebSocket guide and block states documentation.
This subscription is unique to Monad. It is available over WebSocket on Chainstack Global Nodes for Monad Mainnet and Testnet.

Get your own node endpoint today

Start for free and get your app to production levels immediately. No credit card required.You can sign up with your GitHub, X, Google, or Microsoft account.

Parameters

  • string — the subscription type, monadNewHeads in this case.

Response

  • subscription — the subscription ID.
Each notification delivers a block object with the following fields. Monad-specific fields:
  • blockId — a 32-byte identifier unique to this specific block proposal. A proposal with the same number but a different blockId is a different proposal. Use this to deduplicate per-proposal when the same block number is emitted multiple times as its commitState advances.
  • commitState — the current state of the block in Monad’s commit lifecycle. One of Proposed, Voted, Finalized, or Verified.
Standard block header fields:
  • number — the block number, encoded as hexadecimal.
  • hash — the block hash.
  • parentHash — hash of the previous block.
  • sha3Uncles — hash of the list of uncles included in the block. Always 0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347 on Monad.
  • logsBloom — the bloom filter for the logs of the block.
  • transactionsRoot — the root of the transaction trie of the block.
  • stateRoot — the root of the final state trie of the block.
  • receiptsRoot — the root of the receipts trie of the block.
  • miner — the address of the block proposer.
  • difficulty — always 0x0 on Monad (proof-of-stake-based consensus).
  • totalDifficulty — always 0x0 on Monad.
  • extraData — arbitrary data field set by the proposer.
  • size — the size of this block in bytes, encoded as hexadecimal.
  • gasLimit — the maximum gas allowed in this block, encoded as hexadecimal.
  • gasUsed — the total gas used by all transactions in this block, encoded as hexadecimal.
  • timestamp — the Unix timestamp for when the block was proposed, encoded as hexadecimal.
  • mixHash — the previous RANDAO value.
  • nonce — always 0x0000000000000000 on Monad.
  • baseFeePerGas — EIP-1559 base fee per gas, encoded as hexadecimal.
  • withdrawalsRoot — Merkle root of withdrawals.
  • blobGasUsed — cumulative blob gas used, EIP-4844.
  • excessBlobGas — excess blob gas.
  • parentBeaconBlockRoot — parent beacon block root.
  • requestsHash — EIP-7685 execution requests hash.
The same block number will appear multiple times as its commitState advances — typically once each for Proposed, Voted, Finalized, and Verified. Blocks may also skip intermediate states and go directly to Finalized when consensus outpaces execution. Failed proposals are abandoned implicitly — there is no explicit failure notification.Deduplicate by blockId if you need one event per unique proposal, or by the pair (number, commitState) if you care about lifecycle transitions.

eth_subscribe("monadNewHeads") code examples

Note that subscriptions require a WebSocket connection and WebSocket cat for you to use this method in the console.Install WebSocket cat with:npm install -g wscat
This streams block headers for every commit-state transition of every block. Expect multiple notifications per block number.

Example notification

A typical stream for a single block, in order of arrival, might look like:
Send eth_unsubscribe with the returned subscription ID to close the stream.

monadNewHeads vs newHeads

Both subscription types work on Chainstack Monad nodes. Pick based on what you optimize for.
  • eth_subscribe("newHeads") — fires once per block, when the block is proposed and before it is finalized. Closest to the semantics of Ethereum’s newHeads. Use this when you want one event per block and do not need to know its commit state.
  • eth_subscribe("monadNewHeads") — fires at every state transition, starting at Proposed, the same moment newHeads fires. Each event adds the blockId and commitState fields. Use this when you need to know whether a block is still speculative or already finalized.
For broader event-monitoring patterns on Monad — including eth_subscribe("logs", {...}) and HTTP polling alternatives — see Monad: Monitoring events and transactions.

Use case

A practical use case for eth_subscribe("monadNewHeads") is any latency-sensitive application that acts on speculatively executed block state and then needs to know when that state is final:
  • Trading and MEV. Searchers and takers can trigger off-chain logic on a block at the Proposed state, then reconcile against the same blockId at Voted and Finalized for correctness.
  • Pre-confirmation UX. Wallets, explorers, and dashboards can surface “tentative” block data immediately on Proposed, then upgrade the display as the same blockId advances through Voted → Finalized, giving users end-to-end visibility into Monad’s commit lifecycle.
  • Infrastructure and consensus monitoring. Node operators and analytics platforms can track the exact cadence and distribution of block states to detect execution lag, skipped intermediate states, or abandoned proposals in real time.
Last modified on November 13, 2026