debug_traceBlockByNumber

debug_traceBlockByNumber re-executes all transactions in a single Polygon block — selected by block number or by a block tag — against the historical state at that block, and returns the Geth-style EVM trace produced for each transaction. The result is an array with one trace entry per transaction, in block order. This is the per-block, Geth-namespace counterpart to the single-transaction debug_traceCall; for the Parity-style equivalent see trace_block, whose output schema is different.

Use it when you need to inspect the execution of an entire block at once — for example to index every internal call in a block (MEV / DeFi analytics), to attribute gas usage across transactions, or to reconstruct state transitions for forensic and compliance review. 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 available on the Pro tier and above. It is rate limited per tier (3 RPS on Pro, 10 RPS on Business) with a short burst allowance; there is no daily quota. Tracing a full Polygon block is an expensive operation — a typical mainnet block contains dozens to hundreds of transactions, each expanding into many trace frames, so responses are heavy (commonly 100 KB–2 MB) and latency is measured in seconds, not milliseconds. Prefer a specific tracer with tight options, and keep concurrency low.

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

Response fields

Other shared envelope codes may also apply: -32001 trial_expired, -32005 unauthorized (missing/invalid key), and -32601 method_unknown. 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/polygon", {
  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: ["0x3A2F4C0", { 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.polygon.request("debug_traceBlockByNumber", [
  "0x3A2F4C0",
  { tracer: "callTracer" },
]);

Python (triport-sdk)

import os
from triport import Triport


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


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

• Geth shape ≠ Parity shape. This method returns the Geth call-frame format. The Parity-style alternative, trace_block, returns a flat array of {action, result, subtraces, traceAddress, type} frames instead. An indexer that consumes both should normalize the two schemas; they are useful together for cross-verification in forensic work.
• Heavy payload, seconds of latency. A busy Polygon block traces into thousands of frames. Without a tracer the verbose opcode-level struct-log format is returned, which can be very large — specifying callTracer yields a compact call-tree view that is usually what integrations want. Keep concurrency low and expect multi-second responses for full blocks.
• The first parameter accepts a block tag (latest, earliest) or a 0x-prefixed hex block number — pass whichever you have. Tracing latest is the common real-time path-detection use case; historic block numbers are used for backfilling and indexing.
• To trace a call that is not yet on chain, use debug_traceCall.