Single Simulations

Tenderly supports single transaction simulations via RPC and API. By default, simulations execute on the latest state of the chosen network. The Simulation API can also pin a historical block and a position within it (see Block number and transaction index). Dapps and wallets can use single simulations to give their users a way to dry-run transactions before committing real assets. This gives them a preview of the transaction execution along with the detailed balance and asset changes that have occurred. Transaction previews can help users build trust in dapps, approve only successful transactions, and prevent costly failures.

Simulate via RPC

Node RPC allows you to read blockchain data and send transactions. But you can also simulate transactions on the Node. The advantage of simulating via RPC is that you can perform all these operations through a single RPC URL.

Simulations via RPC or API are only available on supported networks. Check out the list of supported networks.

Retrieve your RPC URL and the access key from the Dashboard. Go to Node > Copy HTTPS URL of the desired network.

example

https://mainnet.gateway.tenderly.co/$TENDERLY_NODE_ACCESS_KEY

To simulate a single transaction via RPC, call the tenderly_simulateTransaction method. See RPC reference. Example

request
response.json

request

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": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
        "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
        "gas": "0x7a1200",
        "value": "0x0",
        "data": "0x095ea7b3000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1000000000000000000000000000000000000000000000000000000000000012b"
      },
      "0xfc497b"
    ]
  }'

response.json

{
  "id": 0,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "gasUsed": "0xb412",
    "cumulativeGasUsed": "0xb412",
    "blockNumber": "0xfc497b",
    "type": "0x0",
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000028000000000000000002000000000000000000000010000000000000000004000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000010000000000000000000000000040000000000000000000000000000800000",
    "logs": [
      {
        "name": "Approval",
        "anonymous": false,
        "inputs": [
          {
            "value": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
            "type": "address",
            "name": "src",
            "indexed": true
          },
          {
            "value": "0xf1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1",
            "type": "address",
            "name": "guy",
            "indexed": true
          },
          {
            "value": "299",
            "type": "uint256",
            "name": "wad",
            "indexed": false
          }
        ],
        "raw": {
          "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
          "topics": [
            "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
            "0x000000000000000000000000e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
            "0x000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1"
          ],
          "data": "0x000000000000000000000000000000000000000000000000000000000000012b"
        }
      }
    ],
    "trace": [
      {
        "type": "CALL",
        "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
        "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
        "gas": "0x79bdb0",
        "gasUsed": "0x5fc2",
        "value": "0x0",
        "input": "0x095ea7b3000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1000000000000000000000000000000000000000000000000000000000000012b",
        "decodedInput": [
          {
            "value": "0xf1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1",
            "type": "address",
            "name": "usr",
            "indexed": false
          },
          {
            "value": "299",
            "type": "uint256",
            "name": "wad",
            "indexed": false
          }
        ],
        "method": "approve",
        "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
        "decodedOutput": [
          {
            "value": true,
            "type": "bool",
            "indexed": false
          }
        ],
        "subtraces": 0,
        "traceAddress": []
      }
    ],
    "exposureChanges": [
      {
        "assetInfo": {
          "standard": "ERC20",
          "type": "Fungible",
          "contractAddress": "0x6b175474e89094c44da98b954eedeac495271d0f",
          "symbol": "dai",
          "name": "Dai",
          "logo": "https://coin-images.coingecko.com/coins/images/9956/large/Badge_Dai.png?1696509996",
          "decimals": 18,
          "dollarValue": "1"
        },
        "type": "Approve",
        "owner": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
        "spender": "0xf1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1",
        "rawAmount": "0x12b",
        "amount": "0.000000000000000299",
        "dollarValue": "0.000000000000000299"
      }
    ],
    "stateChanges": [
      {
        "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
        "storage": [
          {
            "slot": "0x6f18ad69436c83a0d8b2c05ee70fa64e30403b1755cc38ee9cb6245926b14b17",
            "previousValue": "0x0000000000000000000000000000000000000000000000000000000000000000",
            "newValue": "0x000000000000000000000000000000000000000000000000000000000000012b"
          }
        ]
      },
      {
        "address": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
        "nonce": {
          "previousValue": "0x0",
          "newValue": "0x1"
        }
      }
    ]
  }
}

Simulate via API

Use the simulate API endpoint to simulate a single transaction with different parameters.

To use Simulations on Virtual Environments, we recommend the Simulate RPC and Bundle Simulate RPC. Otherwise, you may use Virtual Environments Simulation API.

The URL must contain your account slug and the project slug. Follow this quick guide to find the slugs.

Simulation API endpoint on public network

https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate

Simulation API endpoint on a Virtual Environment

https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/vnets/{vnetId}/transactions/simulate

You also need to receive the API access token, which is sent with the headers. Learn how to generate the API access key here.

Request payload

Send a POST request to the API endpoint. For full details on the request payload, see the See API reference. The simulated payload is similar to the eth_call JSON RPC call. The fields below are required:

network_id (string): ID of the network where you want to run the simulation.
to (string): The recipient address of the transaction.
from (string): Address initiating the transaction.
input (string): Encoded contract method call data.
gas (number): Amount of gas provided for the simulation.

You can specify any sender address in the from field. Since Tenderly simulates unsigned transactions, you don’t need to own an account’s private key to simulate transactions from a specific sender.

You can also specify the simulation_type, which can be full, quick, or ABI. This field is not required since the default is set to full. Learn more about Simulation Modes.

Block number and transaction index

block_number and transaction_index select the state the transaction executes on. Both are optional integers.

Field	Value	State the transaction executes on
`block_number`	omitted or `null`	Pending block: the latest state available to the simulation backend.
`block_number`	`N` (0 or greater)	Block `N`. `0` is the genesis block.
`block_number`	negative	Relative to the head: `-1` is the block before the latest one, `-2` two blocks before. A value outside the chain’s range returns `UnknownBlockNumber`.
`transaction_index`	`0` (default)	Start of block `N`, before any of its transactions. Equal to the post-state of block `N-1`.
`transaction_index`	`1` to `count-1`	After the block’s transactions `0` to `index-1` have executed, in place of the transaction at that index.
`transaction_index`	`count` (the block’s transaction count)	After all transactions of block `N`, the block’s post-state.

Validation rules:

block_number is an integer. Block tags such as "latest" or "pending" are rejected with a 400 Bad request input parameters error.
transaction_index requires an explicit block_number. With the block omitted, a non-zero index is rejected with 400 Transaction index is not allowed when block number is pending.
An index greater than the block’s transaction count fails with transaction index too high: invalid transaction simulation. The index is not clamped, and there is no keyword for the end of the block.

To simulate on the post-state of the most recent block, read the block first and pass its transaction count as the index:

post-state of the latest block

const block = await provider.send("eth_getBlockByNumber", ["latest", false]);

const payload = {
  network_id: "1",
  from: "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
  to: "0x6b175474e89094c44da98b954eedeac495271d0f",
  input: "0x18160ddd",
  block_number: parseInt(block.number, 16),
  transaction_index: block.transactions.length,
};

The same fields drive the Tx Index control in the Simulator UI: At start of block is index 0, At tx is the chosen index, and At end of block is the block’s transaction count. When making API requests, add the X-Access-Key header with the value being the access token. Example Make sure to store the access key securely in a .env file.

request.ts
response.json

request.ts

dotenv.config();

const simulateTransaction = async () => {
  const { TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG, TENDERLY_ACCESS_KEY } = process.env;

  const simulation = await axios.post(
    `https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate`,
    {
      network_id: '1',
      block_number: 16533883,
      from: '0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2',
      to: '0x6b175474e89094c44da98b954eedeac495271d0f',
      gas: 8000000,
      gas_price: 0,
      value: 0,
      input: '0x095ea7b3000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1000000000000000000000000000000000000000000000000000000000000012b',
      simulation_type: 'quick',
    },
    {
      headers: {
        'X-Access-Key': TENDERLY_ACCESS_KEY as string,
      },
    },
  );

  console.log(simulation.data);
};

simulateTransaction();

response.json

{
  "transaction": {
    "hash": "0x7c1a33fb449b8d4eb5ec042d94d1c7ce2a5acae05f02af58ce4fd8b5c6beaf0a",
    "block_hash": "",
    "block_number": 16533883,
    "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
    "gas": 8000000,
    "gas_price": 0,
    "gas_fee_cap": 0,
    "gas_tip_cap": 0,
    "cumulative_gas_used": 0,
    "gas_used": 46098,
    "effective_gas_price": 0,
    "input": "0x095ea7b3000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1000000000000000000000000000000000000000000000000000000000000012b",
    "nonce": 0,
    "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
    "index": 0,
    "value": "0x",
    "access_list": null,
    "status": true,
    "addresses": null,
    "contract_ids": null,
    "network_id": "1",
    "timestamp": "2023-02-01T12:11:23Z",
    "function_selector": "",
    "l1_block_number": 0,
    "l1_timestamp": 0,
    "deposit_tx": false,
    "system_tx": false,
    "sig": {
      "v": "0x0",
      "r": "0x0",
      "s": "0x0"
    },
    "transaction_info": {
      "contract_id": "eth:1:0x6b175474e89094c44da98b954eedeac495271d0f",
      "block_number": 16533883,
      "transaction_id": "0x7c1a33fb449b8d4eb5ec042d94d1c7ce2a5acae05f02af58ce4fd8b5c6beaf0a",
      "contract_address": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "method": null,
      "parameters": null,
      "intrinsic_gas": 21584,
      "refund_gas": 0,
      "call_trace": {
        "hash": "0x7c1a33fb449b8d4eb5ec042d94d1c7ce2a5acae05f02af58ce4fd8b5c6beaf0a",
        "contract_name": "",
        "function_pc": 0,
        "function_op": "CALL",
        "absolute_position": 0,
        "caller_pc": 0,
        "caller_op": "CALL",
        "call_type": "CALL",
        "address": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
        "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
        "from_balance": "0",
        "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
        "to_balance": "0",
        "value": "0",
        "block_timestamp": "0001-01-01T00:00:00Z",
        "gas": 7978416,
        "gas_used": 24514,
        "intrinsic_gas": 21584,
        "storage_address": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
        "input": "0x095ea7b3000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1000000000000000000000000000000000000000000000000000000000000012b",
        "nonce_diff": [
          {
            "address": "0xe2E2E2e2e2e2E2E2E2E2e2E2e2E2E2e2e2e2E2e2",
            "original": "0",
            "dirty": "1"
          }
        ],
        "state_diff": [
          {
            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "soltype": null,
            "original": null,
            "dirty": null,
            "raw": [
              {
                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "key": "0x6f18ad69436c83a0d8b2c05ee70fa64e30403b1755cc38ee9cb6245926b14b17",
                "original": "0x0000000000000000000000000000000000000000000000000000000000000000",
                "dirty": "0x000000000000000000000000000000000000000000000000000000000000012b"
              }
            ]
          }
        ],
        "logs": [
          {
            "name": "",
            "anonymous": false,
            "inputs": null,
            "raw": {
              "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
              "topics": [
                "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
                "0x000000000000000000000000e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
                "0x000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1"
              ],
              "data": "0x000000000000000000000000000000000000000000000000000000000000012b"
            },
            "trace_index": null
          }
        ],
        "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
        "decoded_output": null,
        "network_id": "1",
        "calls": null
      },
      "stack_trace": null,
      "logs": [
        {
          "name": "",
          "anonymous": false,
          "inputs": null,
          "raw": {
            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "topics": [
              "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
              "0x000000000000000000000000e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
              "0x000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1"
            ],
            "data": "0x000000000000000000000000000000000000000000000000000000000000012b"
          },
          "trace_index": null
        }
      ],
      "balance_diff": null,
      "nonce_diff": [
        {
          "address": "0xe2E2E2e2e2e2E2E2E2E2e2E2e2E2E2e2e2e2E2e2",
          "original": "0",
          "dirty": "1"
        }
      ],
      "state_diff": [
        {
          "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
          "soltype": null,
          "original": null,
          "dirty": null,
          "raw": [
            {
              "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
              "key": "0x6f18ad69436c83a0d8b2c05ee70fa64e30403b1755cc38ee9cb6245926b14b17",
              "original": "0x0000000000000000000000000000000000000000000000000000000000000000",
              "dirty": "0x000000000000000000000000000000000000000000000000000000000000012b"
            }
          ]
        }
      ],
      "raw_state_diff": null,
      "console_logs": null,
      "asset_changes": null,
      "balance_changes": [],
      "created_at": "2023-02-01T12:11:23Z"
    },
    "method": "",
    "decoded_input": null,
    "call_trace": [
      {
        "call_type": "CALL",
        "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
        "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
        "gas": 7978416,
        "gas_used": 24514,
        "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
        "input": "0x095ea7b3000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1000000000000000000000000000000000000000000000000000000000000012b",
        "output": "0x0000000000000000000000000000000000000000000000000000000000000001"
      }
    ]
  },
  "simulation": {
    "id": "cc4d422b-149c-4043-83ec-d2670c9ffe2c",
    "project_id": "dfdc391a-a15d-4590-9aef-8691259c7df4",
    "owner_id": "7d5e8b1f-8bf8-4eae-a70f-fb7d354b1cc2",
    "network_id": "1",
    "block_number": 16533883,
    "transaction_index": 0,
    "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
    "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
    "input": "0x095ea7b3000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1000000000000000000000000000000000000000000000000000000000000012b",
    "gas": 8000000,
    "gas_price": "0",
    "gas_used": 46098,
    "value": "0",
    "status": true,
    "access_list": null,
    "queue_origin": "",
    "block_header": {
      "number": "0xfc497b",
      "hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "stateRoot": "0x3a3fd616aa768fc45b78d02fbd216e6a49a19153f92a091f5c4e9a2bbe494ef1",
      "parentHash": "0x57067724ea963c92291770db13ff945f9b7e11689d2494ba318cea6cdab1c2e2",
      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "transactionsRoot": "0x912f0d5b52a308205d1c1a9b15409cbd455b414ac2d2bcb5b13ef01a5b4a41d8",
      "receiptsRoot": "0xfdc2b958b59f3ded07e132764112429f8e2827ed0e1d67954e05ee1be5e7e203",
      "logsBloom": "0xb0abe9644746d77234090df88b0c836b0d2966107c87597c568582618cc4c773104a2da2b011d90310a8db958c13cb208f196333ba08bb86625b405301beaf22028a2193076aaf7ffb0b64eb77ea6827ec293ac4fb754b719744ff2dd9813d751e5808704bc645bf31107e8472742879cd7acb090b643d4cc27986da095ced5c028143df0223190d1d515345a7e2b1a33333b52587c0c688e57e06e8a390493faff909012981eb860ea2ebc1153684e025c27e2460ae28db74e35eb260fbf8e9522c805356b1022928e8b408235e5e824d7483ecf4ba985a9b470c760c58e06716f0fc28003633d86c35ba840f3512c480039004724dd25a9e599898fab73cf3",
      "timestamp": "0x63da56eb",
      "difficulty": "0x0",
      "gasLimit": "0x1c9c380",
      "gasUsed": "0xcb7693",
      "miner": "0xdafea492d9c6733ae3d56b7ed1adb60692c98bc5",
      "extraData": "0x496c6c756d696e61746520446d6f63726174697a6520447374726962757465",
      "mixHash": "0x43f7931adf192e8addc95bfae45f9db586434110ef7eac2d765e4a4b9ed6de4e",
      "nonce": "0x0000000000000000",
      "baseFeePerGas": "0x32c42d070",
      "size": "0x0",
      "totalDifficulty": "0x0",
      "uncles": null,
      "transactions": null
    },
    "deposit_tx": false,
    "system_tx": false,
    "nonce": 0,
    "addresses": null,
    "contract_ids": null,
    "shared": false,
    "created_at": "2024-01-08T17:30:06.992859393Z"
  },
  "contracts": [],
  "generated_access_list": []
}

Explore use cases

Preview transaction outcomes: Identify and fix issues that could cause transactions to fail.
Asset and balance changes: Get exact dollar values for all balance and asset changes that will happen.
Gas estimation: Accurately predict the gas costs before sending the transaction.
State overrides: Modify blockchain conditions like timestamps and contract data to test different scenarios.

Getting Started

Simulator

Console

Monitor

Node RPC

AI Tools

Account & Settings

Single Simulations

Simulate via RPC

Simulate via API

Request payload

Block number and transaction index

Explore use cases

Where to go next

Bundled simulations

Simulate via SDK

​Simulate via RPC

​Simulate via API

​Request payload

​Block number and transaction index

​Explore use cases

​Where to go next

Bundled simulations

Simulate via SDK

Simulate via RPC

Simulate via API

Request payload

Block number and transaction index

Explore use cases

Where to go next