eth_getUncleCountByBlockHash

eth_getUncleCountByBlockHash looks up a block by its 32-byte hash and returns how many uncle (ommer) blocks it references, encoded as a 0x-prefixed hexadecimal string.

Uncles were a feature of Ethereum's proof-of-work era: stale blocks that were mined at nearly the same height as a canonical block and rewarded for their work. Since The Merge (proof-of-stake), Ethereum no longer produces uncles, so for any post-Merge block this method returns 0x0. The method remains available for inspecting historical pre-Merge blocks, where the count can be non-zero.

If no block matches the supplied hash (e.g. it belongs to an orphaned block, or the node has not yet seen it), the method returns null instead of an error. Always check for null before parsing the result as a number.

The method takes a single positional parameter.

When the block hash is unknown, the result is null:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

A missing block is not an error — it is reported as result: null (see above). See errors.md for the full error envelope and handling guidance.

JavaScript (fetch)

const res = await fetch("https://api.triport.io/v1/ethereum", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TRIPORT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "eth_getUncleCountByBlockHash",
    params: ["0xb9b8b8b1b0c9e6a0f3d4c5b6a7988e9d0c1b2a3948576f5e4d3c2b1a09876543"],
  }),
});


const { result } = await res.json();
console.log("uncle count:", result === null ? "block not found" : parseInt(result, 16));

TypeScript SDK (@triport/sdk)

import { Triport } from "@triport/sdk";


const client = new Triport({ apiKey: process.env.TRIPORT_API_KEY! });


const result = await client.ethereum.request<string | null>(
  "eth_getUncleCountByBlockHash",
  ["0xb9b8b8b1b0c9e6a0f3d4c5b6a7988e9d0c1b2a3948576f5e4d3c2b1a09876543"],
);
console.log("uncle count:", result === null ? "block not found" : parseInt(result, 16));

Python (triport-sdk)

import os
from triport import Triport


client = Triport(api_key=os.environ["TRIPORT_API_KEY"])


result = client.ethereum.request(
    "eth_getUncleCountByBlockHash",
    ["0xb9b8b8b1b0c9e6a0f3d4c5b6a7988e9d0c1b2a3948576f5e4d3c2b1a09876543"],
)
print("uncle count:", "block not found" if result is None else int(result, 16))

• The result is a hex string (or null), not a number — convert with base 16 before arithmetic.
• Post-Merge Ethereum does not produce uncles, so this method returns 0x0 for any block after the September 2022 transition to proof-of-stake. Non-zero counts only appear for historical pre-Merge blocks.
• Always handle the null case: an unknown or non-canonical block hash returns result: null rather than an error.
• Available on the free tier (eth_read_rpc category).
• Rate limiting is RPS-per-tier with burst; there is no daily quota. A -32003 rate_limited error means you should back off and retry shortly.
• To count uncles by block height instead of hash, use eth_getUncleCountByBlockNumber. To look up a block by hash, use eth_getBlockByHash.