Simulate Bundles

The custom RPC methods appear in the tenderly_ namespace.

Two methods execute a sequence of transactions against a given block without sending them on chain. Each transaction in the bundle executes on the state left by the previous one:

tenderly_simulateBundle returns the full decoded execution result for every transaction: logs, call trace, asset changes, and balance changes.
tenderly_estimateGasBundle executes the bundle the same way but returns only gas figures per transaction. Use it when you need exact gas values without the full simulation payload.

`tenderly_simulateBundle`

Simulates a bundle of transactions as it would execute on the given block and returns results for each transaction. Params

Transactions Transactions ARRAY: list of transactions in a bundle
- 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 bundle is simulated as part of. The bundle 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 bundle on the post-state of block N-1, as the first transactions 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 bundle inside a block, use the Simulation API bundle endpoint with transaction_index.

Example

Request
Shell
JavaScript
Request

example.json

{
  "id": 0,
  "jsonrpc": "2.0",
  "method": "tenderly_simulateBundle",
  "params": [
  [
{
  "from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "data": "0x095ea7b300000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001"
},
{
  "from": "0x20a5814b73ef3537c6e099a0d45c798f4bd6e1d6",
  "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "data": "0x23b872dd000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001"
}
  ],
  "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_simulateBundle",
"params": [
[
{
"from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
"to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"data": "0x095ea7b300000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001"
},
{
"from": "0x20a5814b73ef3537c6e099a0d45c798f4bd6e1d6",
"to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"data": "0x23b872dd000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001"
}
],
"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_simulateBundle", [
[

{
"from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
"to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"data": "0x095ea7b300000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001"
},
{
"from": "0x20a5814b73ef3537c6e099a0d45c798f4bd6e1d6",
"to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"data": "0x23b872dd000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001"
}
],
"0xF4D880",
]);

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

}

(async () => {
runSimulateTransaction();

})();

example.json

{
  "id": 0,
  "jsonrpc": "2.0",
  "result": [
{
  "status": true,
  "gasUsed": "0xb3a8",
  "cumulativeGasUsed": "0x0",
  "blockNumber": "0xf4d881",
  "type": "0x0",
  "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000002000000080000000000000000200000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000080000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000010200000800000000000000000000000000000000000000000000000000000",
  "logs": [
{
  "name": "Approval",
  "anonymous": false,
  "inputs": [
{
  "value": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "type": "address",
  "name": "src"
},
{
  "value": "0x20a5814b73ef3537c6e099a0d45c798f4bd6e1d6",
  "type": "address",
  "name": "guy"
},
{
  "value": "1",
  "type": "uint256",
  "name": "wad"
}
  ],
  "raw": {
  "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "topics": [
  "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
  "0x000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045",
  "0x00000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d6"
  ],
  "data": "0x0000000000000000000000000000000000000000000000000000000000000001"
}
}
  ],
  "trace": [
{
  "type": "CALL",
  "from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "gas": "0x5f58cbc",
  "gasUsed": "0x5f64",
  "value": "0x0",
  "input": "0x095ea7b300000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001",
  "decodedInput": [
{
  "value": "0x20a5814b73ef3537c6e099a0d45c798f4bd6e1d6",
  "type": "address",
  "name": "guy"
},
{
  "value": "1",
  "type": "uint256",
  "name": "wad"
}
  ],
  "method": "approve",
  "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "decodedOutput": [
{
  "value": true,
  "type": "bool",
  "name": ""
}
  ],
  "subtraces": 0,
  "traceAddress": [
  0
  ]
}
  ]
},
{
  "status": true,
  "gasUsed": "0x8a78",
  "cumulativeGasUsed": "0x0",
  "blockNumber": "0xf4d881",
  "type": "0x0",
  "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000000080000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000020000000000000000000800000000000000000000000010000000000000004000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000020000000200000800000000000000000000000000000000000000000000000000000",
  "logs": [
{
  "name": "Transfer",
  "anonymous": false,
  "inputs": [
{
  "value": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "type": "address",
  "name": "src"
},
{
  "value": "0x0000000000000000000000000000000000000000",
  "type": "address",
  "name": "dst"
},
{
  "value": "1",
  "type": "uint256",
  "name": "wad"
}
  ],
  "raw": {
  "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "topics": [
  "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
  "0x000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045",
  "0x0000000000000000000000000000000000000000000000000000000000000000"
  ],
  "data": "0x0000000000000000000000000000000000000000000000000000000000000001"
}
}
  ],
  "trace": [
{
  "type": "CALL",
  "from": "0x20a5814b73ef3537c6e099a0d45c798f4bd6e1d6",
  "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "gas": "0x5f58c3c",
  "gasUsed": "0x4874",
  "value": "0x0",
  "input": "0x23b872dd000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001",
  "decodedInput": [
{
  "value": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "type": "address",
  "name": "src"
},
{
  "value": "0x0000000000000000000000000000000000000000",
  "type": "address",
  "name": "dst"
},
{
  "value": "1",
  "type": "uint256",
  "name": "wad"
}
  ],
  "method": "transferFrom",
  "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "decodedOutput": [
{
  "value": true,
  "type": "bool",
  "name": ""
}
  ],
  "subtraces": 0,
  "traceAddress": [
  0
  ]
}
  ]
}
  ]
}

Result Simulations result ARRAY: list of simulation results in a bundle

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_estimateGasBundle`

Calculates exact gas estimates for the given list of transactions, with optional simulation-style state and block overrides. Like tenderly_estimateGas, each estimate is based on a fully executed transaction, so the returned values are accurate where eth_estimateGas might revert and yield an underestimation. Transactions execute in order, each on the state left by the previous one. Differences from tenderly_simulateBundle:

Both methods execute the bundle the same way against the given block, and both accept the same state and block overrides.
tenderly_simulateBundle returns the full decoded execution result for every transaction: logs, call trace, asset changes, and balance changes.
tenderly_estimateGasBundle returns only two gas figures per transaction: the recommended gas limit and the gas actually consumed. Use it when you only need gas values; use tenderly_simulateBundle when you need to preview the bundle’s effects.

Params

Transactions Transactions ARRAY: list of transactions in a bundle, same shape as in tenderly_simulateBundle
Simulation Block Number (optional) The block number against which the bundle 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_simulateBundle
Block Overrides (optional) OBJECT: the set of header fields to override in a block, same shape as in tenderly_simulateBundle

Example

Request
Shell
Response

example.json

{
  "id": 0,
  "jsonrpc": "2.0",
  "method": "tenderly_estimateGasBundle",
  "params": [
    [
      {
        "from": "0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0",
        "to": "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
        "data": "0x095ea7b30000000000000000000000009008d19f58aabd9ed0d60971565aa8510560ab410000000000000000000000000000000000000000000000000c1291a92f17a100"
      },
      {
        "from": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",
        "to": "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
        "data": "0x23b872dd0000000000000000000000007f39c581f595b53c5cb19bd0b3f8da6c935e2ca00000000000000000000000009008d19f58aabd9ed0d60971565aa8510560ab410000000000000000000000000000000000000000000000000c1291a92f17a100"
      },
      {
        "from": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",
        "to": "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
        "data": "0x095ea7b30000000000000000000000007f39c581f595b53c5cb19bd0b3f8da6c935e2ca00000000000000000000000000000000000000000000000000c1291a92f17a100"
      },
      {
        "from": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",
        "to": "0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0",
        "data": "0xea598cb00000000000000000000000000000000000000000000000000c1291a92f17a100"
      }
    ],
    "latest"
  ]
}

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_estimateGasBundle",
"params": [
[
{
"from": "0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0",
"to": "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
"data": "0x095ea7b30000000000000000000000009008d19f58aabd9ed0d60971565aa8510560ab410000000000000000000000000000000000000000000000000c1291a92f17a100"
},
{
"from": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",
"to": "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
"data": "0x23b872dd0000000000000000000000007f39c581f595b53c5cb19bd0b3f8da6c935e2ca00000000000000000000000009008d19f58aabd9ed0d60971565aa8510560ab410000000000000000000000000000000000000000000000000c1291a92f17a100"
},
{
"from": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",
"to": "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
"data": "0x095ea7b30000000000000000000000007f39c581f595b53c5cb19bd0b3f8da6c935e2ca00000000000000000000000000000000000000000000000000c1291a92f17a100"
},
{
"from": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41",
"to": "0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0",
"data": "0xea598cb00000000000000000000000000000000000000000000000000c1291a92f17a100"
}
],
"latest"
]
}'

response.json

{
  "id": 0,
  "jsonrpc": "2.0",
  "result": [
    { "gas": "0x12579", "gasUsed": "0xff06" },
    { "gas": "0x10918", "gasUsed": "0xb551" },
    { "gas": "0xa621", "gasUsed": "0x6625" },
    { "gas": "0x10649", "gasUsed": "0xb249" }
  ]
}

Result Gas estimates ARRAY: list of gas estimates, one per transaction in the bundle

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

`tenderly_simulateBundle`

`tenderly_estimateGasBundle`

​tenderly_simulateBundle

​tenderly_estimateGasBundle

`tenderly_simulateBundle`

`tenderly_estimateGasBundle`