Simulate Transactions with JSON-RPC Methods

The custom RPC methods appear in the tenderly_ namespace.

These methods run on Node RPC; see the full JSON-RPC reference for every method and network. 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

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
Simulation Block Number (optional) The block the transaction is simulated as part of. The transaction executes on the state at the start of that block, before any of the block’s own transactions. Either:
- STRING Block number
- ENUM of Block tag earliest|finalized|safe|latest|pending
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
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

Block parameter semantics. Block N executes the transaction on the post-state of block N-1, as the first transaction of block N. latest therefore excludes the head block’s own transactions and is one block behind eth_call with latest. There is no transaction index parameter, and a transactionIndex field in the block or block-overrides object is ignored. To execute on the post-state of block N, pass N+1. To position the transaction inside a block, use the Simulation API with transaction_index.

Example

Request
Shell
JavaScript
Request

example.json

{
  "id": 0,
  "jsonrpc": "2.0",
  "method": "tenderly_simulateTransaction",
  "params": [
    {
      "from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "data": "0xa9059cbb00000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001"
    },
    "0xF4D880"
  ]
}

example

curl https://mainnet.gateway.tenderly.co/$TENDERLY_NODE_ACCESS_KEY \
-X POST \
-H "Content-Type: application/json" \
-d \
'{
"id": 0,
"jsonrpc": "2.0",
"method": "tenderly_simulateTransaction",
"params": [
{
"from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
"to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"data": "0xa9059cbb00000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001"
},
"0xF4D880"
]
}'

example.js

// Installation Instructions: https://docs.ethers.io/v5/getting-started/#installing
const { ethers } = require('ethers');

async function runSimulateTransaction() {
// Initialize an ethers instance
const provider = new ethers.providers.JsonRpcProvider(
'https://goerli.gateway.tenderly.co/$TENDERLY_WEB3_GATEWAY_KEY',
);

// Execute method
const result = await provider.send('tenderly_simulateTransaction', [

{
from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
to: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
data: '0xa9059cbb00000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001',
},
'0xF4D880',
]);

// Print the output to console
console.log(result);
}

(async () => {
runSimulateTransaction();
})();

example.json

{
  "id": 0,
  "jsonrpc": "2.0",
  "result": {
  "status": true,
  "gasUsed": "0xc94e",
  "cumulativeGasUsed": "0x0",
  "blockNumber": "0x1103aae",
  "type": "0x0",
  "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000002000000080000000000000000000000000000000000000000000008000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000010000000000000004000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000000000000000000000000020000000000000000000000000000000000200000800000000000000000000000000000000000000000000000000000",
  "logs": [
{
  "name": "Transfer",
  "anonymous": false,
  "inputs": [
{
  "value": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "type": "address",
  "name": "src"
},
{
  "value": "0x20a5814b73ef3537c6e099a0d45c798f4bd6e1d6",
  "type": "address",
  "name": "dst"
},
{
  "value": "1",
  "type": "uint256",
  "name": "wad"
}
  ],
  "raw": {
  "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "topics": [
  "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
  "0x000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045",
  "0x00000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d6"
  ],
  "data": "0x0000000000000000000000000000000000000000000000000000000000000001"
}
}
  ],
  "trace": [
{
  "type": "CALL",
  "from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "gas": "0xbeb6dbc",
  "gasUsed": "0x750a",
  "value": "0x0",
  "input": "0xa9059cbb00000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001",
  "decodedInput": [
{
  "value": "0x20a5814b73ef3537c6e099a0d45c798f4bd6e1d6",
  "type": "address",
  "name": "dst"
},
{
  "value": "1",
  "type": "uint256",
  "name": "wad"
}
  ],
  "method": "transfer",
  "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "decodedOutput": [
{
  "value": true,
  "type": "bool",
  "name": ""
}
  ],
  "subtraces": 0,
  "traceAddress": [
  0
  ]
}
  ],
  "assetChanges": [
{
  "assetInfo": {
  "standard": "ERC20",
  "type": "Fungible",
  "contractAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "symbol": "weth",
  "name": "WETH",
  "logo": "https://assets.coingecko.com/coins/images/2518/large/weth.webp?1628852295",
  "decimals": 18,
  "dollarValue": "1834.6199951171875"
},
  "type": "Transfer",
  "from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "to": "0x20a5814b73ef3537c6e099a0d45c798f4bd6e1d6",
  "rawAmount": "0x1",
  "amount": "0.000000000000000001",
  "dollarValue": "0.0000000000000018346199951171875"
}
  ],
  "balanceChanges": [
{
  "address": "0x20a5814b73ef3537c6e099a0d45c798f4bd6e1d6",
  "dollarValue": "0.0000000000000018346199951171875",
  "transfers": [
  0
  ]
},
{
  "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "dollarValue": "-0.0000000000000018346199951171875",
  "transfers": [
  0
  ]
}
  ]
}
}

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 passed as the block parameter (the head block for latest)
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

Transaction Transaction OBJECT: same shape as in tenderly_simulateTransaction (from, to, gas, gasPrice, value, data, accessList)
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
State Overrides (optional) MAP: mapping from an account (address) to override specification, same shape as in tenderly_simulateTransaction
Block Overrides (optional) OBJECT: the set of header fields to override in a block, same shape as in tenderly_simulateTransaction

Example

Request
Shell
Response

example.json

{
  "id": 0,
  "jsonrpc": "2.0",
  "method": "tenderly_estimateGas",
  "params": [
    {
      "from": "0x8516feaea147ea0db64d1c5b97bb651ca5435155",
      "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "data": "0xa9059cbb0000000000000000000000003fc3c4c84bdd2db5ab2cc62f93b2a9a347de25fb00000000000000000000000000000000000000000000001869c36187f3430000",
      "value": "0x0"
    },
    "21285787"
  ]
}

example

curl https://mainnet.gateway.tenderly.co/$TENDERLY_NODE_ACCESS_KEY \
-X POST \
-H "Content-Type: application/json" \
-d \
'{
"id": 0,
"jsonrpc": "2.0",
"method": "tenderly_estimateGas",
"params": [
{
"from": "0x8516feaea147ea0db64d1c5b97bb651ca5435155",
"to": "0x6b175474e89094c44da98b954eedeac495271d0f",
"data": "0xa9059cbb0000000000000000000000003fc3c4c84bdd2db5ab2cc62f93b2a9a347de25fb00000000000000000000000000000000000000000000001869c36187f3430000",
"value": "0x0"
},
"21285787"
]
}'

response.json

{
  "id": 0,
  "jsonrpc": "2.0",
  "result": {
    "gas": "0x12579",
    "gasUsed": "0xff06"
  }
}

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

Getting Started

Simulator

Console

Monitor

Node RPC

AI Tools

Account & Settings

Simulate Transactions with JSON-RPC Methods

`tenderly_simulateTransaction`

`tenderly_estimateGas`

​tenderly_simulateTransaction

​tenderly_estimateGas

`tenderly_simulateTransaction`

`tenderly_estimateGas`