Skip to main content
The custom RPC methods appear in the tenderly_ namespace.
Two methods execute a single transaction against a given block without sending it on chain:
  • tenderly_simulateTransaction returns the full decoded execution: logs, call trace, asset changes, and balance changes.
  • tenderly_estimateGas executes the transaction the same way but returns only gas figures. Use it when you need an exact gas value without the full simulation payload.

​
tenderly_simulateTransaction

Simulates transaction as it would execute on the given block. Params
  1. Transaction Transaction OBJECT
    • from (optional) STRING: hex encoded address
    • to STRING: hex encoded address
    • gas (optional) NUMBER
    • maxFeePerGas (optional) NUMBER max fee: The maximum total fee per gas the sender is willing to pay (includes the network / base fee and miner / priority fee) in wei
    • maxPriorityFeePerGas (optional) NUMBER max priority fee: Maximum fee per gas the sender is willing to pay to miners in wei
    • gasPrice (optional) NUMBER: The gas price willing to be paid by the sender in wei
    • value (optional) NUMBER
    • data (optional) STRING: hex encoded bytes
    • accessList (optional) ARRAY of Access list entry OBJECT
      • address STRING hex encoded address
      • storageKeys ARRAY of STRING representation of 32 byte hex encoded storage key
  2. Simulation Block Number (optional) The block number against which transaction should be simulated. Either:
    • STRING Block number
    • ENUM of Block tag earliest|finalized|safe|latest|pending
  3. State Overrides (optional) MAP: mapping from an account (address) to override specification
    • key STRING: the account this override applies to
    • value OBJECT: the override specification
      • nonce (optional) STRING: hex encoded 8 byte nonce override for the account
      • code (optional) STRING: data of the code override for the account
      • balance (optional) STRING: hex encoded 32 byte balance override for the account in wei
      • stateDiff (optional) MAP: mapping of storage key to storage value override
        • key STRING: the storage key
        • value STRING: the value override for the given storage key
  4. Block Overrides (optional) OBJECT: The set of header fields to override in a block.
    • number (optional) STRING: hex, overrides the block number
    • difficulty (optional) STRING: hex, overrides the block difficulty
    • time (optional) STRING: hex, overrides block timestamp
    • gasLimit (optional) STRING: hex, overrides gas limit
    • coinbase (optional) STRING: hex, overrides block miner
    • random (optional) STRING: hex, overrides the blocks extra data which feeds into the RANDOM opcode
    • baseFee (optional) STRING: hex, overrides block base fee
Example
example.json
{
  "id": 0,
  "jsonrpc": "2.0",
  "method": "tenderly_simulateTransaction",
  "params": [
    {
      "from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "data": "0xa9059cbb00000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001"
    },
    "0xF4D880"
  ]
}
Result Simulation result OBJECT
  • status NUMBER: either 1 (success) or 0 (failure)
  • gasUsed NUMBER: The amount of gas used by this specific transaction alone
  • cumulativeGasUsed NUMBER: the total amount of gas used when this transaction was executed in the block
  • blockNumber NUMBER: the block number in which this transaction was simulated
  • type NUMBER: transaction type, 0x00 for legacy transactions, 0x01 for access list types, 0x02 for dynamic fees
  • logsBloom STRING: bloom filter for light clients to quickly retrieve related logs
  • logs: an array of emitted events ARRAY of OBJECT
    • name STRING: event name
    • anonymous BOOLEAN: indicates if event is anonymous
    • inputs: array of decoded log arguments ARRAY of decoded logs OBJECT
      • name STRING: event argument name
      • type STRING: event argument type from Solidity type system
      • value (optional) STRING string representation value of the argument; interpret according to the type field
    • raw OBJECT: raw logs
      • address STRING hex encoded address: address of the contract emitting the log
      • topics ARRAY of STRING 32 hex encoded bytes
      • data STRING hex encoded string representing event data
  • trace: Trace ARRAY of OBJECT
    • type STRING type: trace item type - either CALL| CALLCODE| STATICCALL| DELEGATECALL| CREATE| CREATE2| SELFDESTRUCT
    • from STRING: hex encoded address
    • to STRING: hex encoded address
    • gas STRING: hex encoded unsigned 64 byte integer representing event gas
    • gasUsed STRING: hex encoded unsigned 64 byte integer representing event gasUsed
    • value STRING: hex encoded unsigned 64 byte integer representing event value in wei
    • error STRING: low-level error from virtual machine
    • errorReason STRING: extracted error reason in case of revert
    • input STRING: hex encoded string representation of raw input bytes for the trace point
    • method STRING: invoked contract method
    • decodedInput : decoded input for the invoked method - ARRAY of decoded in argument OBJECT
      • value STRING: string representation value of the argument; interpret according to the type field.
      • type STRING: the Solidity type of this argument
      • name STRING: the name of this argument
    • output STRING: raw trace output
    • decodedOutput : decoded output of the invoked method - ARRAY of decoded out argument OBJECT
      • value STRING: string representation value of the argument; interpret according to the type field.
      • type STRING: the Solidity type of this argument
      • name STRING: the name of this argument
    • subtraces NUMBER: number of child traces
    • traceAddress : trace position ARRAY of NUMBER
  • assetChanges ARRAY:
    • type STRING type of asset change, can be transfer, mint, burn
    • from STRING: address of the sender (empty for mint transfers)
    • to STRING: address of the receiver (empty for burn transfers)
    • amount STRING: the amount of the token that was transferred
    • rawAmount STRING: raw amount transfer for the token
    • dollarValueSTRING: dollar value of the transferred token
    • assetInfoOBJECT: asset information
      • standard STRING: supported token standards: ERC20, ERC721, NativeCurrency
      • type STRING: the token type: Native, Fungible, Non-Fungible
      • contractAddressSTRING : address of the contract
      • symbol STRING: token symbol
      • name STRING: token name
      • logo STRING: URL for the token icon
      • decimals NUMBER: number of decimals in the token
      • dollarValueSTRING: dollar value of a single token
  • balanceChanges ARRAY: an array of balance changes - cumulated asset changes
    • address STRING address
    • dollarValue STRING: dollar value of cumulated asset changes
    • transfers ARRAY: array of asset changes indexes

​
tenderly_estimateGas

Calculates an exact gas estimate for the given transaction, with optional simulation-style state and block overrides. The estimate is based on a fully executed transaction, even when the specified gas is insufficient, so the returned value is accurate. In contrast, eth_estimateGas might revert and yield an underestimation. Differences from tenderly_simulateTransaction:
  • Both methods execute the transaction the same way against the given block, and both accept the same state and block overrides.
  • tenderly_simulateTransaction returns the full decoded execution result: logs, call trace, asset changes, and balance changes.
  • tenderly_estimateGas returns only two gas figures: the recommended gas limit and the gas actually consumed. Use it when you only need gas values; use tenderly_simulateTransaction when you need to preview the transaction’s effects.
Params
  1. Transaction Transaction OBJECT: same shape as in tenderly_simulateTransaction (from, to, gas, gasPrice, value, data, accessList)
  2. Simulation Block Number (optional) The block number against which the transaction should be executed. Either:
    • STRING Block number
    • ENUM of Block tag earliest|finalized|safe|latest|pending
  3. State Overrides (optional) MAP: mapping from an account (address) to override specification, same shape as in tenderly_simulateTransaction
  4. Block Overrides (optional) OBJECT: the set of header fields to override in a block, same shape as in tenderly_simulateTransaction
Example
example.json
{
  "id": 0,
  "jsonrpc": "2.0",
  "method": "tenderly_estimateGas",
  "params": [
    {
      "from": "0x8516feaea147ea0db64d1c5b97bb651ca5435155",
      "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "data": "0xa9059cbb0000000000000000000000003fc3c4c84bdd2db5ab2cc62f93b2a9a347de25fb00000000000000000000000000000000000000000000001869c36187f3430000",
      "value": "0x0"
    },
    "21285787"
  ]
}
Result Gas estimate OBJECT
  • gas STRING: hex-encoded recommended gas limit to set on the transaction (includes a safety margin over the gas actually consumed)
  • gasUsed STRING: hex-encoded amount of gas actually consumed by the executed transaction