Simulate Bundles - Tenderly

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 number against which transaction should be simulated. 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

Example

example.json
example
example.js
example.json

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 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_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

example.json
example
response.json

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

​tenderly_simulateBundle

​tenderly_estimateGasBundle

`tenderly_simulateBundle`

`tenderly_estimateGasBundle`