For AI agents: a documentation index is available at /llms.txt. Markdown versions of pages are available by appending .md to any documentation URL.
Skip to main content

TRACE methods

The TRACE API is a more concise alternative to the DEBUG API.

note

The TRACE API is not enabled by default for JSON-RPC. Enable it using the --rpc-http-api or --rpc-ws-api option.

trace_block​

Provides transaction processing of type trace for the specified block.

note

Your node must be an archive node, or the requested block must be within the number of blocks retained when using Bonsai (by default, 512 from the head of the chain).

Parameters​

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

Returns​

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_block",
    "params": [
      "0x6"
    ],
    "id": 1
  }'

trace_call​

Executes the given call and returns a number of possible traces for it.

note

When using Bonsai, the requested block must be within the number of blocks retained (by default, 512 from the head of the chain).

Parameters​

  • call: object - Transaction call object.

    • from: data, 20 bytes - Address of the sender.

    • to: data, 20 bytes - Address of the action receiver.

    • gas: quantity, integer - Gas provided by the sender. eth_call consumes zero gas, but other executions might need this parameter. eth_estimateGas ignores this value.

    • gasPrice: quantity, integer - Gas price, in Wei, provided by the sender. The default is 0. Used only in non-EIP1559 transactions.

    • maxPriorityFeePerGas: quantity, integer - Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Can be used only in EIP1559 transactions. If used, must specify maxFeePerGas.

    • maxFeePerGas: quantity, integer - Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Can be used only in EIP1559 transactions. If used, must specify maxPriorityFeePerGas.

    • maxFeePerBlobGas: quantity, integer - Maximum fee the sender is willing to pay per blob gas. Only used for blob transactions introduced in EIP-4844.

    • nonce: quantity, integer - Number of transactions made by the sender before this one. The default is the sender's nonce.

    • value: quantity, integer - Value transferred, in Wei.

    • data: data - Hash of the method signature and encoded parameters. For details, see Ethereum Contract ABI. Must be equal to input if both parameters are provided.

    • input: data - Hash of the method signature and encoded parameters. For details, see Ethereum Contract ABI. Must be equal to data if both parameters are provided.

    • accessList: array - List of addresses and storage keys that the transaction plans to access. Used only in non-FRONTIER transactions.

    • strict: tag - Determines if the sender account balance is considered during gas estimation. If true, the sender's balance is checked against the transaction's gas parameters. This ensures the estimated gas reflects what the sender can actually afford. If false, the balance checks are skipped. The default is true.

    • blobVersionedHashes: array - List of references to blobs introduced in EIP-4844.

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

  • options: array of strings - List of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

Returns​

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_call",
    "params": [
      {
        "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
        "to": "0x0010000000000000000000000000000000000000",
        "gas": "0xfffff2",
        "gasPrice": "0xef",
        "value": "0x0",
        "data": "0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002",
        "nonce": "0x0"
      },
      [
        "trace"
      ],
      "latest"
    ],
    "id": 1
  }'

trace_callMany​

Performs multiple call traces on top of the same block. You can trace dependent transactions.

note

When using Bonsai, the requested block must be within the number of blocks retained (by default, 512 from the head of the chain).

Parameters​

  • options: array of strings - List of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

Returns​

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_callMany",
    "params": [
      [
        [
          {
            "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
            "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
            "value": "0x186a0"
          },
          [
            "trace"
          ]
        ],
        [
          {
            "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
            "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
            "value": "0x186a0"
          },
          [
            "trace"
          ]
        ]
      ],
      "latest"
    ],
    "id": 1
  }'

trace_filter​

Returns traces matching the specified filter. The maximum number of blocks you can supply to trace_filter is 1000 by default. You can adjust this limit using the --rpc-max-trace-filter-range option.

note

Your node must be an archive node, or the requested blocks must be within the number of blocks retained when using Bonsai (by default, 512 from the head of the chain).

Parameters​

  • traceFilterOptions: object - Trace filter options object.

  • fromBLock: String | Tag - Trace starts at this block.

  • toBlock: String | Tag - Trace stops at this block.

  • fromAddress: string - Include only traces sent from this address.

  • toAddress: string - Include only traces with this destination address.

  • after: quantity - The offset trace number.

  • count: integer - Number of traces to display in a batch.

Returns​

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_filter",
    "params": [
      {
        "fromBlock": "0x1",
        "toBlock": "0x21",
        "after": 2,
        "count": 2,
        "fromAddress": [
          "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"
        ]
      }
    ],
    "id": 415
  }'

trace_get​

Returns a trace at the given position.

note

Your node must be an archive node, or the requested transaction must be contained in a block within the number of blocks retained when using Bonsai (by default, 512 from the head of the chain).

Parameters​

  • transaction: string - Transaction hash.

  • indexPositions: array - Index positions of the traces.

Returns​

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_get",
    "params": [
      "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
      [
        "0x0"
      ]
    ],
    "id": 1
  }'

trace_rawTransaction​

Traces a call to eth_sendRawTransaction without making the call, returning the traces.

note

When using Bonsai, the requested transaction must be contained in a block within the number of blocks retained (by default, 512 from the head of the chain).

Parameters​

  • data - string - Raw transaction data.

  • options: array of strings - List of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

Returns​

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_rawTransaction",
    "params": [
      "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",
      [
        "trace"
      ]
    ],
    "id": 1
  }'

trace_replayBlockTransactions​

Provides transaction processing tracing per block.

note

When using Bonsai, the requested block must be within the number of blocks retained (by default, 512 from the head of the chain).

Parameters​

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

  • options: array of strings - List of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

Returns​

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_replayBlockTransactions",
    "params": [
      "0x12",
      [
        "trace",
        "vmTrace",
        "stateDiff"
      ]
    ],
    "id": 1
  }'

trace_transaction​

Provides transaction processing of type trace for the specified transaction.

note

Your node must be an archive node, or the requested transaction must be contained in a block within the number of blocks retained when using Bonsai (by default, 512 from the head of the chain).

Parameters​

  • transaction: string - Transaction hash.

Returns​

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_transaction",
    "params": [
      "0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7"
    ],
    "id": 1
  }'