debug_traceBlockByNumber

POST

A debugging tool that allows you to trace chain state changes caused by transactions and the history of actual calls for a specific block, by configuring a tracer and using the information it provides.

🚧 Getting a 429 error? Check your subscription plan!

429 errors can occur when you exceed the Throughput limit of your subscription plan.

For example, the Starter plan has a limit of 300 CU per second, so calling an API that consumes 350 CU while on the Starter plan may result in a 429 error.

Check the CU consumption of the APIs you use on the Compute Unit Costs page, and consider upgrading to a higher plan if you need more Throughput!

👉 Go to Compute Unit Costs page

param[0]

blockNumberOrTagstringrequired

Use either block number or block tag to specify a block.

Block number: Hexadecimal string (e.g. "0x1")
Block tag: Enum string (e.g. "latest", "earliest", "pending")
- earliest: The oldest available block on the chain.
- finalized: A recently finalized block that can no longer be changed. Primarily used in proof-of-stake (PoS) blockchains.
- safe: A recent block considered safe by the network (immune to reorgs).
- latest: The most recent block on the chain (may be subject to reorgs).
- pending: The next block to be mined, including pending transactions in the mempool.

param[1]

traceOptionObjectobjectrequired

Object for trace option configuration.

tracerstring

A field that specifies the tracer type, set to either "callTracer" or "prestateTracer".1. callTracer: Used to inspect the execution path and results of executed transactions. Provides information such as the call stack, return values, gas consumption, and revert reasons, and can trace the process of function calls and interactions with smart contracts. Depending on the execution option (onlyTopCall), you can trace all nested calls of a specific call.2. prestateTracer: A tool that traces the pre-state before a specific transaction or block is executed. Records account state and contract code before transaction execution, allowing you to analyze state changes before and after execution. prestateTracer is used to trace smart contract state changes and interactions between accounts.

tracerConfigobject

Object for tracer configuration. Uses the boolean "onlyTopCall" option; when set to true, traces only the main call. When set to false, traces down to the sub-call level.

onlyTopCallboolean

Responses

fromstring

Caller address

gasstring

Gas limit set for the call (hex)

gasUsedstring

Actual gas used (hex)

tostring

Callee address

inputstring

Call input data (hex)

outputstring

Call return data (hex)

valuestring

Amount of ETH transferred (hex, in wei)

typestring

Call type (CALL, CREATE, STATICCALL, etc.)

callsarray

List of internal sub-calls

errorstring

Error message if execution failed

revertReasonstring

Revert reason if the transaction was reverted

codestringrequired

Code identifying the cause of the failed request.

messagestringrequired

Detailed message including the name and value of the invalid parameter.

{
  "code": "ERROR_CODE",
  "message": "Unauthorized"
}

X-API-KEY

cURL

curl -X POST 'https://arbitrum-mainnet.nodit.io' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: nodit-demo' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "debug_traceBlockByNumber",
    "params": [
      "latest",
      {
        "tracer": "callTracer",
        "tracerConfig": {
          "onlyTopCall": true
        }
      }
    ]
  }'