eth_getUncleCountByBlockNumber

eth_getUncleCountByBlockNumber returns how many uncle blocks (also called ommers) are referenced by a given block, selected by block number (a 0x-prefixed hex integer) or by one of the named block tags. The count is returned as a 0x-prefixed hexadecimal string.

Uncles were a feature of Ethereum's proof-of-work consensus, where a valid block that lost the race to be canonical could still be referenced by a later block. Since the Merge (proof-of-stake), Ethereum no longer produces uncles, so this method always returns 0x0 for any post-Merge block. It is retained for compatibility with tools and clients that still inspect the uncle list. To read historical uncle counts, query a pre-Merge block number.

If you already have a block hash instead of a number, use the sibling method eth_getUncleCountByBlockHash. A request for a block that does not exist (e.g. a height beyond the current chain head) returns a result of null rather than an error.

Pass a single-element positional array.

"0x0" decodes to 0 uncles — the expected value for any post-Merge block.

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_getUncleCountByBlockNumber",
    params: ["latest"],
  }),
});


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

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_getUncleCountByBlockNumber",
  ["0x149e2c1"],
);
console.log("uncle count:", result === null ? null : 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_getUncleCountByBlockNumber",
    ["latest"],
)
print("uncle count:", None if result is None else int(result, 16))

• The result is a hex string — convert with base 16 before arithmetic.
• Post-Merge (proof-of-stake) Ethereum produces no uncles, so latest and any recent block return 0x0. Non-zero counts only appear for historical pre-Merge block numbers.
• A non-existent block returns result: null, not an error; check for null before parsing.
• eth_getUncleCountByBlockNumber is 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 look up the uncle count by block hash instead, use eth_getUncleCountByBlockHash. To fetch the full block, use eth_getBlockByNumber.