debug_traceBlockByNumber

debug_traceBlockByNumber re-executes all transactions contained in a single block — selected by block number or by a block tag — against the historical state at that block, and returns the EVM trace produced for each transaction. This is the per-block equivalent of tracing one transaction with debug_traceTransaction: the result is an array with one trace entry per transaction, in block order.

Use it when you need to inspect the execution of an entire block at once — for example to audit every internal call in a block, to attribute gas usage across transactions, or to reconstruct state transitions for analytics. By default the node uses the built-in opcode-level (struct-log) tracer; pass a tracer in the options object to switch to a higher-level tracer such as callTracer or prestateTracer.

This is a debug-namespace method and is available on the Pro tier and above. It is rate limited per tier (5 RPS on Pro, 15 RPS on Business) with a short burst allowance; there is no daily quota. Tracing a full block is an expensive operation — for older blocks or struct-log output the call can return a large response, so prefer a specific tracer and tight options when you can.

Positional parameters: a required block reference, plus an optional trace configuration object.

Response fields

See the shared error envelope reference for the full error object shape and handling guidance.

JavaScript (fetch)

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


const { result } = await res.json();
console.log(result.length, "transactions traced");

TypeScript SDK (@triport/sdk)

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


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


const traces = await triport.eth.request("debug_traceBlockByNumber", [
  "0x10D4F",
  { tracer: "callTracer" },
]);

Python (triport-sdk)

import os
from triport import Triport


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


traces = triport.eth.request(
    "debug_traceBlockByNumber",
    ["0x10D4F", {"tracer": "callTracer"}],
)
print(len(traces), "transactions traced")

• The first parameter accepts a block tag (latest, earliest) or a 0x-prefixed hex block number — pass whichever you have. To trace a block by its hash instead, use debug_traceBlockByHash.
• To trace a single transaction rather than a whole block, use debug_traceTransaction; to trace a call that is not yet on chain, use debug_traceCall.
• Without a tracer, the response uses the verbose opcode-level struct-log format, which can be very large for busy blocks. Specifying callTracer yields a compact, call-tree view that is usually what integrations want.