eth_getUncleCountByBlockHash

eth_getUncleCountByBlockHash answers one narrow question about an Ethereum block identified by hash: how many uncles does it reference? You get back a single hex integer rather than full headers, which makes it the cheap probe to run before deciding whether to pull uncle details at all. On the chain's Proof-of-Work history the answer is 0x0, 0x1, or 0x2, since the protocol capped uncles at two per block. From The Merge onward (block 15537393 and up) PoS produces one block per slot with no ommers, so the count is always 0x0. Send the block hash to https://ethereum.therpc.io/YOUR_API_KEY on chain ID 1.

Use cases

• Gate eth_getUncleByBlockHashAndIndex calls on this count: if it comes back 0x0, skip the per-index fetches entirely and save the round trips.
• Aggregate the count across a span of pre-Merge blocks to build an uncle-rate time series, a classic signal for how congested and propagation-bound the PoW network was at a given period.

Parameters

Response

Example request

1curl https://ethereum.therpc.io/YOUR_API_KEY \
2  -X POST \
3  -H "Content-Type: application/json" \
4  -d '{
5    "jsonrpc": "2.0",
6    "method": "eth_getUncleCountByBlockHash",
7    "params": ["0x0000000000000000000000000000000000000000000000000000000000000000"],
8    "id": 1
9  }'

Try it live in the Ethereum playground.

Errors & troubleshooting

Common pitfalls

• Every post-Merge block returns 0x0, so a non-zero answer is only ever possible for PoW blocks below height 15537393. Treat this method as a historical instrument, not a live network metric.
• An unrecognized block hash yields null rather than 0x0. Distinguish the two in your code: null means the block was not found, while 0x0 means a known block with zero uncles.

Supported networks

• Mainnet — Chain ID: 1
• Sepolia — Chain ID: 11155111

See also

• eth_getUncleByBlockHashAndIndex
• eth_getUncleCountByBlockNumber
• eth_getBlockByHash

1curl https://ethereum.therpc.io/YOUR_API_KEY \
2  -X POST \
3  -H 'Content-Type: application/json' \
4  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getUncleCountByBlockHash","params":["0x0000000000000000000000000000000000000000000000000000000000000000"]}'