TriportRPC
DashboardDocs

eth_getBlockByNumber

POSThttps://api.triport.io/v1/ethereum

Returns information about a block on the Ethereum chain, selected by block number or by a named block tag.

Ethereumeth_read_rpcfree 10 RPS · basic 20 RPS · pro 100 RPS · business 250 RPS

eth_getBlockByNumber returns the full block object for a given block, identified either by a 0x-prefixed hexadecimal block number or by one of the supported named tags. It is the standard way to read a historical or current block, including its header fields and its list of transactions.

The second parameter controls how much transaction detail comes back. When fullTransactions is false, the transactions array contains only transaction hashes (cheaper, smaller payload). When it is true, the array contains the fully expanded transaction objects for every transaction in the block.

If no block matches the requested number or tag — for example a height that has not been produced yet — the method returns null rather than an error. Always handle the null case before reading fields off the result.

Parameters

Pass a positional array of exactly two elements.

blockParameterstringrequired
A 0x-prefixed hex block number (e.g. 0x149e2c1) or one of the named tags: latest, earliest, pending, safe, finalized.
fullTransactionsbooleanrequired
If true, returns full transaction objects in transactions. If false, returns only transaction hashes.

Response

Response fields

FieldTypeDescription
numberstringBlock number as a 0x-prefixed hex string. null for pending blocks.
hashstring32-byte block hash. null for pending blocks.
parentHashstringHash of the parent block.
noncestring8-byte proof-of-work nonce. null for pending blocks.
sha3UnclesstringSHA3 of the uncles data in the block.
logsBloomstringBloom filter for the logs in the block. null for pending blocks.
transactionsRootstringRoot of the transaction trie.
stateRootstringRoot of the final state trie.
receiptsRootstringRoot of the receipts trie.
minerstringAddress of the block's fee/coinbase recipient.
difficultystringBlock difficulty (0x0 post-merge).
totalDifficultystringTotal difficulty of the chain up to this block.
extraDatastringExtra data field of the block.
sizestringBlock size in bytes, hex-encoded.
gasLimitstringMaximum gas allowed in the block.
gasUsedstringTotal gas used by all transactions in the block.
baseFeePerGasstringBase fee per gas (post-EIP-1559 blocks).
timestampstringUnix timestamp of block collation, hex-encoded.
transactionsarrayTransaction hashes (when fullTransactions is false) or full transaction objects (when true).
unclesarrayArray of uncle block hashes.

The full result is null when no block matches the requested number or tag.

Errors

CodeMeaningWhen it happens
-32001trial_expiredThe account's trial period has ended.
-32003rate_limitedThe per-tier RPS limit was exceeded. Back off and retry.

See errors.md for the full error envelope and handling guidance.

Examples

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


const { result } = await res.json();
if (result === null) {
  console.log("block not found");
} else {
  console.log("block", parseInt(result.number, 16), "tx count:", result.transactions.length);
}

TypeScript SDK (@triport/sdk)

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


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


// Fetch the latest block with full transaction objects.
const block = await client.ethereum.request<Record<string, unknown> | null>(
  "eth_getBlockByNumber",
  ["latest", true],
);


if (block) {
  console.log("block", parseInt(block.number as string, 16));
}

Python (triport-sdk)

import os
from triport import Triport


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


# Fetch a specific block by hex number, hashes only.
block = client.ethereum.request("eth_getBlockByNumber", ["0x149e2c1", False])


if block is None:
    print("block not found")
else:
    print("block", int(block["number"], 16), "tx count:", len(block["transactions"]))

Notes

  • All numeric block fields (number, gasUsed, timestamp, etc.) are hex strings — convert with base 16 before arithmetic.
  • A null result is normal, not an error: it means the requested block does not exist yet (e.g. a future height). Check for null before dereferencing.
  • Setting fullTransactions to true substantially increases the response size on busy blocks; prefer false when you only need transaction hashes.
  • eth_getBlockByNumber 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 find the current chain head before requesting a concrete block, call eth_blockNumber. To look a block up by its hash instead of its number, use eth_getBlockByHash.