# Verify Contracts via Dashboard
Source: https://docs.tenderly.co/contract-verification/dashboard

Learn how to verify smart contracts publicly and privately in the browser through the Tenderly Dashboard.

<Info>
  **Works on:** public networks (mainnets and testnets). To verify a contract on a Virtual Environment, see [Deploy and verify contracts](/virtual-environments/develop/deploy-contracts).
</Info>

Verify smart contracts from your browser in the Tenderly Dashboard. This is the fastest path when you're not using Hardhat or Foundry; if you are, the [Hardhat](/contract-verification/hardhat) or [Foundry](/contract-verification/foundry) workflows automate this.

## Prerequisites

To verify a contract, you need to provide:

* **The source code**
* **The exact compiler settings** used to compile the deployed version

You can upload the source code in several ways through the Dashboard:

* **JSON Upload**: paste the JSON metadata generated by the Solidity compiler.
* **ABI Upload**: paste the contract ABI.
* **Contract Source Upload**: paste source code directly, upload a single source file, or upload an entire project directory. The directory option works best for contracts that import other contracts.

## Public and private verification

When verifying a contract, you choose between two visibility modes:

* **Public**: the contract source is visible to anyone using Tenderly.
* **Private**: the contract source is only visible inside the project you verified it in.

The **Verification** column on the Contracts list shows a contract's current status: `Unverified`, `Public`, or `Private`.

## Dashboard contract verification guide

After you've [added an unverified contract](/developer-explorer/contracts) to a Tenderly project, here are the steps to verify it using the Dashboard.

<Steps>
  <Step title="Find the unverified contract">
    Open the contract's page. An unverified contract shows a banner with a **Verify Contract** button.

    <img alt="Unverified contract banner with Verify Contract button" />
  </Step>

  <Step title="Choose visibility">
    Select **Public** or **Private**. Private is selected by default, and scopes the verified source to the current project.

    <img alt="Verify Contract visibility step" />
  </Step>

  <Step title="Choose the upload method">
    Pick one of:

    * **JSON Upload**
    * **ABI Upload**
    * **Contract Source Upload**, which opens a submenu: **Paste Source Code**, **Upload Source File**, or **Upload Project Directory**.

      <img alt="Verify Contract source code upload method choice" />

      <img alt="Contract Source Upload submenu" />

    If you paste source directly, give the file a name and paste the contract source into the editor.

    <img alt="Paste source code screen" />
  </Step>

  <Step title="Select the contract">
    If the upload contains several contracts, pick the one matching the address shown in the previous step. If any imports are missing, the Dashboard prompts you to add them before continuing.

    <img alt="Choose a Deployed Contract step" />
  </Step>

  <Step title="Set the compiler settings">
    Fill in the compiler version, optimizer settings (enabled / runs), EVM version, ViaIR, and library address pairs if your contract uses linked libraries. Any mismatch with the deployed bytecode will fail verification.

    <img alt="Compiler Settings step filled in" />
  </Step>

  <Step title="Finish">
    Click **Finish** to submit. The contract's verification status and info panel update immediately.

    <img alt="Contract page after successful private verification" />
  </Step>
</Steps>

## How to verify smart contracts in bulk

If you have several unverified contracts in your project, click **Verify All Contracts** on the Contracts list. This opens the **Verify multiple contracts** dialog, listing every unverified contract with a **Make Private** toggle and an **Add source** button per row.

<img alt="Verify multiple contracts dialog" />

Click **Add source** next to each contract and supply the upload, compiler settings, and visibility as in the [single-contract flow](#dashboard-contract-verification-guide) above. The bottom **Verify** button stays disabled until every row has a source, then submits all of them at once.


# Smart Contract Verification Using Foundry
Source: https://docs.tenderly.co/contract-verification/foundry

Verify Foundry-deployed contracts on public networks through Tenderly's verification API, privately or publicly, with forge verify-contract.

<Info>
  **Works on:** public networks (mainnets and testnets). To verify contracts on a Virtual Environment, see [Deploy and verify contracts](/virtual-environments/develop/deploy-contracts) and [Verify proxy contracts with Foundry](/virtual-environments/develop/verify-proxy-contracts).
</Info>

Tenderly verifies smart contracts deployed with Foundry's `forge create`, `forge script`, and `forge verify-contract` commands through its Etherscan-compatible verification API. Verification is either private (the source is visible only inside your Tenderly project) or public (visible to anyone with the link).

## Before you begin

You need your Tenderly account and project [slugs](/platform/account/projects/slug), a [Tenderly access key](/platform/account/projects/api-tokens) (Dashboard → Account Settings → Authorization), and a funded account on the target network.

Tenderly's verifier matches the metadata hash the Solidity compiler appends to deployed bytecode against the source you submit. Keep the metadata in the compiled output, and pin the compiler settings so they can't drift between deploy time and verify time:

```toml title="foundry.toml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc_version = "0.8.24"
optimizer = true
optimizer_runs = 200

# Required for Tenderly contract verification:
# keep the CBOR metadata so the verifier can match the on-chain bytecode hash.
cbor_metadata = true
bytecode_hash = "ipfs"
```

`cbor_metadata = true` and `bytecode_hash = "ipfs"` are Foundry's defaults, but some templates strip them; `bytecode_hash = "none"` breaks verification. Compiler-setting drift between deploy and verify causes `Bytecode does not match deployed contract` failures.

The examples below use Base Sepolia (chain ID `84532`). Set up the environment:

```bash title=".env" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
BASE_SEPOLIA_RPC=https://sepolia.base.org
PRIVATE_KEY=...                           # a funded key on the target network

TENDERLY_ACCOUNT=...                      # your account slug
TENDERLY_PROJECT=...                      # your project slug
TENDERLY_ACCESS_KEY=...                   # from Account Settings -> Authorization

TENDERLY_PRIVATE_VERIFIER_URL=https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT}/project/${TENDERLY_PROJECT}/etherscan/verify/network/84532
TENDERLY_PUBLIC_VERIFIER_URL=${TENDERLY_PRIVATE_VERIFIER_URL}/public
```

## Verifier URL

Every Foundry verification command takes `--verifier-url` pointing at Tenderly's verification API, and `--etherscan-api-key $TENDERLY_ACCESS_KEY` for authentication:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://api.tenderly.co/api/v1/account/$TENDERLY_ACCOUNT/project/$TENDERLY_PROJECT/etherscan/verify/network/$NETWORK_ID
```

Each URL segment maps to a value you can read off the Dashboard:

| Segment                     | What it is                                                                                                                          |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `account/$TENDERLY_ACCOUNT` | Your Tenderly account (user or organization) [slug](/platform/account/projects/slug). Case-sensitive.                               |
| `project/$TENDERLY_PROJECT` | The project the verified contract is filed under.                                                                                   |
| `network/$NETWORK_ID`       | The chain the contract is deployed on, as a decimal chain ID (`1` for Ethereum Mainnet, `8453` for Base, `84532` for Base Sepolia). |
| no suffix                   | Private verification: the contract is visible only inside your project.                                                             |
| `/public` suffix            | Public verification: the contract source is visible to anyone with the link, no Tenderly login required.                            |

## Private verification

Privately verified contracts are visible only to your project's members, under **Contracts** in the Dashboard.

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
COUNTER_ADDRESS=0x...   # the deployed contract address

forge verify-contract $COUNTER_ADDRESS src/Counter.sol:Counter \
  --verifier-url       $TENDERLY_PRIVATE_VERIFIER_URL \
  --etherscan-api-key  $TENDERLY_ACCESS_KEY \
  --constructor-args   $(cast abi-encode "constructor(uint256)" 7) \
  --watch
```

`forge verify-contract` expects constructor arguments **already ABI-encoded**; use `cast abi-encode` to produce them. `--watch` polls the verifier until verification finishes and prints the result.

<Note>
  Foundry's output prints a `URL: https://etherscan.io/address/...` line on success. This is a display quirk of the Etherscan-compatible flow; the contract was verified at Tenderly, not Etherscan. Confirm in the Dashboard under **Contracts**.
</Note>

## Public verification

Swap the verifier URL for the `/public`-suffixed variant; nothing else changes. The verified source page becomes reachable by anyone with the link, without a Tenderly login.

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge verify-contract $COUNTER_ADDRESS src/Counter.sol:Counter \
  --verifier-url       $TENDERLY_PUBLIC_VERIFIER_URL \
  --etherscan-api-key  $TENDERLY_ACCESS_KEY \
  --constructor-args   $(cast abi-encode "constructor(uint256)" 7) \
  --watch
```

<Warning>
  Public verification is irreversible. A contract verified publicly stays public. Private and public verifications are independent records: to make a privately verified contract public, re-verify it against the `/public` URL.
</Warning>

## Deploy and verify in one step

`forge create` and `forge script` accept the same flags inline, so deployment and verification run as one command. Unlike `forge verify-contract`, both take constructor arguments as raw values and ABI-encode them for you:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge create src/Counter.sol:Counter \
  --rpc-url            $BASE_SEPOLIA_RPC \
  --private-key        $PRIVATE_KEY \
  --broadcast \
  --verify \
  --verifier-url       $TENDERLY_PRIVATE_VERIFIER_URL \
  --etherscan-api-key  $TENDERLY_ACCESS_KEY \
  --constructor-args   7
```

<Warning>
  Put `--constructor-args` last. It greedily consumes the rest of the command line, so any flag placed after it is treated as another constructor argument.
</Warning>

For multi-contract deployments, use `forge script` with `--slow`; every contract the script deploys is verified automatically with its constructor arguments taken from the broadcast log. Without [`--slow`](https://www.getfoundry.sh/reference/forge/script?highlight=slow#forge-script), broadcast batching can submit a transaction before the previous one is confirmed, which can race the verification step:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge script script/Deploy.s.sol:DeployScript \
  --rpc-url            $BASE_SEPOLIA_RPC \
  --private-key        $PRIVATE_KEY \
  --broadcast --slow \
  --verify \
  --verifier-url       $TENDERLY_PRIVATE_VERIFIER_URL \
  --etherscan-api-key  $TENDERLY_ACCESS_KEY
```

## Verify a contract you didn't deploy

When a contract is verified on a public explorer (Etherscan, Basescan) but not in your Tenderly project, clone the verified source locally with [`forge clone`](https://www.getfoundry.sh/reference/forge/clone) and re-verify it through Tenderly's API:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge clone $CONTRACT_ADDRESS -e $ETHERSCAN_API_KEY --chain 1
```

`forge clone` downloads the verified source from the source chain's Etherscan-compatible API (use the matching explorer's key for each chain), reconstructs the project layout, and pins the compiler settings the original deployer used. Run `forge build` in the cloned directory to confirm it compiles; import-resolution errors usually trace back to `remappings.txt`.

Then verify against Tenderly:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge verify-contract $CONTRACT_ADDRESS src/MyContract.sol:MyContract \
  --verifier-url       $TENDERLY_PRIVATE_VERIFIER_URL \
  --etherscan-api-key  $TENDERLY_ACCESS_KEY \
  --watch
```

If verification fails with `Bytecode does not match deployed contract`, pass the original compiler settings explicitly. All of them are listed on the explorer page where the contract is already verified, under the contract source code section:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge verify-contract $CONTRACT_ADDRESS src/MyContract.sol:MyContract \
  --verifier-url       $TENDERLY_PRIVATE_VERIFIER_URL \
  --etherscan-api-key  $TENDERLY_ACCESS_KEY \
  --compiler-version   v0.8.27+commit.40a35a09 \
  --optimizer-runs     10000 \
  --evm-version        prague \
  --constructor-args   $ENCODED_ARGS \
  --watch
```

### Contracts that live in the `lib` directory

`forge build` only compiles what's reachable from `src/`. A contract that exists solely inside a `lib/` dependency (a proxy, a standard ERC implementation) never enters the build cache, and `forge verify-contract` fails with:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Error: Failed to get standard json input
- cannot resolve file at "lib/openzeppelin-contracts-upgradeable/lib/..."
```

Create a one-line `src/Imports.sol` that imports the contract, then rebuild:

```solidity title="src/Imports.sol" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {TransparentUpgradeableProxy} from "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol";
```

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge build --force
```

`Imports.sol` is never sent to the verifier; it only forces the compiler to cache the contract and its dependencies. Then verify using the contract's full `lib/` path, since that's where the source physically lives.

For a `TransparentUpgradeableProxy` you didn't deploy, the constructor is `(address _logic, address initialOwner, bytes _data)`, and most of it can be reconstructed from chain state:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 1. _logic: the implementation address (ERC-1967 slot)
cast implementation $PROXY_ADDRESS --rpc-url $RPC_URL

# 2. initialOwner: owner of the ProxyAdmin contract
cast admin $PROXY_ADDRESS --rpc-url $RPC_URL                      # returns the ProxyAdmin
cast call $PROXY_ADMIN "owner()(address)" --rpc-url $RPC_URL      # returns initialOwner

# 3. _data: the initialize() calldata from the deployment transaction
#    (decode the factory calldata on the explorer; initialize(address) is selector 0xc4d66de8)

ENCODED_ARGS=$(cast abi-encode "constructor(address,address,bytes)" $LOGIC $INITIAL_OWNER $DATA)

forge verify-contract $PROXY_ADDRESS \
  lib/openzeppelin-contracts-upgradeable/lib/openzeppelin-contracts/contracts/proxy/transparent/TransparentUpgradeableProxy.sol:TransparentUpgradeableProxy \
  --verifier-url       $TENDERLY_PRIVATE_VERIFIER_URL \
  --etherscan-api-key  $TENDERLY_ACCESS_KEY \
  --compiler-version   v0.8.27+commit.40a35a09 \
  --optimizer-runs     200 \
  --evm-version        shanghai \
  --constructor-args   $ENCODED_ARGS \
  --watch
```

Compiler version, optimizer runs, and EVM version come from the explorer page of the already-verified implementation. If the implementation isn't verified anywhere, fall back to the deploying project's `foundry.toml` or deployment scripts.

## Troubleshooting

| Symptom                                                              | Likely cause                                                                                                                                                          | Fix                                                                                                                                                                                                                     |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unauthorized`                                                       | Missing or wrong `--etherscan-api-key`, or the access key was revoked.                                                                                                | Generate a new [access key](/platform/account/projects/api-tokens) and re-set `TENDERLY_ACCESS_KEY`.                                                                                                                    |
| `not found`                                                          | Wrong account slug, project slug, or chain ID in the verifier URL.                                                                                                    | Re-check each URL segment. The account slug is case-sensitive.                                                                                                                                                          |
| `Bytecode does not match deployed contract`                          | The submitted source compiled differently than what's deployed: an `optimizer_runs` mismatch, a different `solc_version` or EVM version, or a stripped metadata hash. | Pin `solc_version`, `optimizer`, `optimizer_runs`, and `bytecode_hash` in `foundry.toml`, or pass `--compiler-version --optimizer-runs --evm-version` explicitly. Run `forge clean && forge build` before re-verifying. |
| `Failed to deserialize content`                                      | The verifier returned an error string Foundry can't parse, usually wrapping an upstream auth or path error.                                                           | Re-check the URL and re-run with `-vvvv` to see the raw response.                                                                                                                                                       |
| `Failed to get standard json input - cannot resolve file at lib/...` | The contract is never imported from `src/`, so it's missing from the build cache.                                                                                     | Create a `src/Imports.sol` that imports it, then `forge build --force`. See [Contracts that live in the `lib` directory](#contracts-that-live-in-the-lib-directory).                                                    |
| `Dry run enabled, not broadcasting transaction` on `forge create`    | `--broadcast` not passed, or swallowed by `--constructor-args`.                                                                                                       | Move `--constructor-args` to be the last flag.                                                                                                                                                                          |
| Only the first contract verifies on `forge script`                   | RPC race: the second transaction was submitted before the first receipt.                                                                                              | Add `--slow`.                                                                                                                                                                                                           |
| Verification succeeds but the contract doesn't appear in the project | Wrong project slug in the verifier URL.                                                                                                                               | Re-verify with the correct slug. The contract is filed under whichever project the URL pointed at.                                                                                                                      |


# Smart Contract Verification Using Hardhat
Source: https://docs.tenderly.co/contract-verification/hardhat

Learn how to use the Tenderly-Hardhat plugin to perform automatic and manual smart contract verification.

<Info>
  **Works on:** Virtual Environments and public networks (mainnets and testnets). The same plugin handles both; point it at the right network in `hardhat.config.ts`.
</Info>

The Tenderly-Hardhat plugin verifies contracts deployed from Hardhat against [Virtual Environments](/virtual-environments/overview) or [public networks](/platform/supported-networks). Use **automatic verification** to verify on every deploy, or **manual verification** to call `tenderly.verify()` explicitly from your scripts.

<Note>
  On public networks, the plugin verifies **publicly by default**. To verify privately (visible only inside your project/organization), set `privateVerification: true` in `hardhat.config.ts`. See [Configure authentication and verification visibility](#configure-authentication-and-verification-visibility).
</Note>

## Versions and compatibility

Depending on the Ethers version you're using with Hardhat, you need to download the corresponding version of the Tenderly-Hardhat plugin.

<Warning>
  It's highly recommended to switch to Ethers 6 and use the latest version of the Tenderly-Hardhat plugin for security
  and performance reasons, as well as additional features.
</Warning>

| Your stack                                                                                                                                                                                                                        | Hardhat version | Tenderly-Hardhat plugin version                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------ |
| [Ethers 6+](https://www.npmjs.com/package/ethers/v/6.0.0), with [Hardhat Ignition](https://hardhat.org/ignition/docs/getting-started#overview) or [hardhat-verify](https://www.npmjs.com/package/@nomicfoundation/hardhat-verify) | **`^2.22.6`**   | [`@tenderly/hardhat-tenderly@^2.6.0`](https://www.npmjs.com/package/@tenderly/hardhat-tenderly)        |
| [Ethers 5+](https://www.npmjs.com/package/ethers/v/5.0.0) with [hardhat-verify](https://www.npmjs.com/package/@nomicfoundation/hardhat-verify)                                                                                    | **`< 2.19.0`**  | [`@tenderly/hardhat-tenderly@1.8.0`](https://www.npmjs.com/package/@tenderly/hardhat-tenderly/v/1.8.0) |

Verifying against current Virtual Environment RPC URLs (the region and `org/project/slug` forms shown in the dashboard) requires plugin version **2.6.0 or newer**.

## Verification methods

The Tenderly-Hardhat plugin supports three methods for contract verification.

* **[Automatic verification](#automatic-verification)** (**recommended**): Simply import and set up the plugin. This method is ideal for verification during deployment because the process is fully automated. Automatic verification works with plain hardhat deployment setup, as well as using [hardhat-ignition](https://hardhat.org/ignition/docs/getting-started#overview). Control automatic verification by using the **`TENDERLY_AUTOMATIC_VERIFICATION`** environment variable.

* **[Manual verification](#manual-verification)** (low-code): Offers an explicit verification step within your code, which is useful for scenarios like **post-deployment verification**, **conditional verification** (e.g. only after a failing test), or **verifying factory contracts' instances**.

* **[Verbose manual verification](#verbose-manual-verification)** (high-code): Provides detailed control over the verification process, specifying library addresses, source codes, and compiler configurations. This is necessary for verifying multiple contracts with varying compiler versions or settings.

## Examples

The best way to explore the automatic verification process is to go through an example that you can in [our GitHub repo](https://github.com/Tenderly/hardhat-tenderly/tree/master/examples/contract-verification/).

All the examples use the sample `Greeter` contract. Browse the example projects directly:

* [Ethers 6 examples](https://github.com/Tenderly/hardhat-tenderly/tree/master/examples/contract-verification/ethers-v6)
* [Ethers 5 examples](https://github.com/Tenderly/hardhat-tenderly/tree/master/examples/contract-verification/ethers-v5)

## Tenderly-Hardhat plugin setup

Follow the steps below to install and initialize the Tenderly-Hardhat plugin.

<Steps>
  ### Install

  Install the Tenderly-Hardhat plugin and add it as a dependency.

  <Tabs>
    <Tab title="Ethers 6 (plugin v2.x)">
      ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      yarn add -D @tenderly/hardhat-tenderly@^2.6.0
      ```
    </Tab>

    <Tab title="Ethers 5 (plugin v1.x)">
      ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      yarn add -D @tenderly/hardhat-tenderly@^1.8.0
      ```
    </Tab>
  </Tabs>

  ### Log into Tenderly CLI

  The plugin requires you to be logged into the [Tenderly CLI](https://github.com/Tenderly/tenderly-cli).

  <Tabs>
    <Tab title="macOS">
      ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      curl https://raw.githubusercontent.com/Tenderly/tenderly-cli/master/scripts/install-macos.sh | sudo sh
      ```
    </Tab>

    <Tab title="Linux">
      ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      curl https://raw.githubusercontent.com/Tenderly/tenderly-cli/master/scripts/install-linux.sh | sudo sh
      ```
    </Tab>
  </Tabs>

  Use this command to check if you're logged in already:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  tenderly whoami
  ```

  To log in, run:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  tenderly login
  ```

  ### Initialize

  Include the Tenderly-Hardhat package in your `hardhat.config.ts` or `hardhat.config.js` file with a simple import
  statement and call the setup method.

  <Note>
    Make sure to import `@tenderly/hardhat-tenderly` after other packages, such as
    `@nomicfoundation/hardhat-toolbox`, `@nomiclabs/hardhat-ethers`, `@openzeppelin/hardhat-upgrades` and similar.
  </Note>

  <Note>
    Only on plugin versions older than 2.4.0 (Ethers 6) and 1.10.0 (Ethers 5) do you need to call **`tdly.setup()`** to initialize the plugin. On current versions the import alone initializes it, and `tdly.setup()` is a no-op:

    ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    tdly.setup({automaticVerifications: !!process.env.TENDERLY_AUTOMATIC_VERIFICATION});
    ```
  </Note>

  ```ts title="hardhat.config.ts" showLineNumbers {2} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import "@nomicfoundation/hardhat-toolbox";
  import "@tenderly/hardhat-tenderly";

  const config: HardhatUserConfig = {
    solidity: "0.8.19",
  };

  export default config;
  ```

  ### Configure authentication and verification visibility

  You need to configure Tenderly by passing account information and verification visibility.

  * The **`privateVerification`** config parameter is the single visibility switch: `true` keeps the source code visible
    only to your project collaborators or organization; omitted or `false` verifies publicly (the default).
  * The plugin reads no visibility environment variable. If you want an environment-variable workflow, wire one into
    `privateVerification` yourself, as below with `TENDERLY_PRIVATE_VERIFICATION` (the convention the
    [official examples](https://github.com/Tenderly/hardhat-tenderly/tree/master/examples/contract-verification) use).

  Configure Tenderly by adding the following code snippet to the `hardhat.config.ts` file:

  ```ts title="hardhat.config.ts" showLineNumbers {3 - 12} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  const config: HardhatUserConfig = {
    solidity: "0.8.19",
    tenderly: {
      username: "your-account-slug",
      project: "your-project-slug",

      // true: contract visible only inside your project.
      // Omitting or setting to false verifies publicly (the default).
      // TENDERLY_PRIVATE_VERIFICATION is plain dotenv wiring, not a
      // variable the plugin reads itself.
      privateVerification: process.env.TENDERLY_PRIVATE_VERIFICATION === "true",
    },
  };

  export default config;
  ```

  ### Set up your deployment

  With the Tenderly-Hardhat plugin set up in your Hardhat project, you can verify contracts deployed to various
  development and production networks:

  * **[Public mainnets or testnets](/platform/supported-networks)** via [Node RPC](/node-rpc/overview)
  * **[Virtual Environments](/virtual-environments/overview)** for development, staging, and demoing

  <Note>
    When deploying with Hardhat Ignition, set `TENDERLY_AUTOMATIC_VERIFICATION=true` and pass a `--deployment-id`:
    the plugin verifies every contract from the deployment through `hre.tenderly.verify()`. The `etherscan`
    configuration below is needed only for the standalone `npx hardhat verify` and `npx hardhat ignition verify`
    commands on public networks.
  </Note>

  <Tabs>
    <Tab title="With Hardhat Ignition">
      ```ts title="hardhat.config.ts" showLineNumbers {8-12, 24-38} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      const config: HardhatUserConfig = {
        solidity: "0.8.19",
        networks: {
          mainnet_base: {
            url: "https://base.gateway.tenderly.co",
            chainId: 8453,
          },
          tenderly_base_testnet: {
            // your Tenderly Virtual Environment RPC
            url: "https://virtual.base.eu.rpc.tenderly.co/872ac073-1de1-4422-b01d-8d057781d77d",
            chainId: 73571,
          },
        },
        tenderly: {
          username: "your-account-slug",
          project: "your-project-slug",

          // true: contract visible only inside your project.
          // Omitting or setting to false verifies publicly (the default).
          // TENDERLY_PRIVATE_VERIFICATION is plain dotenv wiring, not a
          // variable the plugin reads itself.
          privateVerification: process.env.TENDERLY_PRIVATE_VERIFICATION === "true",
        },
        etherscan: {
          // Tenderly access key (not an Etherscan API key)
          apiKey: process.env.TENDERLY_ACCESS_KEY,
          customChains: [
            {
              network: "mainnet_base",
              chainId: 8453,
              urls: {
                // Drop the trailing /public to verify into your project privately.
                apiURL: "https://api.tenderly.co/api/v1/account/your-account-slug/project/your-project-slug/etherscan/verify/network/8453/public",
                browserURL: "https://dashboard.tenderly.co",
              },
            },
          ],
        },
      };

      export default config;
      ```
    </Tab>

    <Tab title="Standard setup">
      ```ts title="hardhat.config.ts" showLineNumbers {9-13, 15-24} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      const config: HardhatUserConfig = {
        solidity: "0.8.19",
        networks: {
          mainnet_base: {
            url: "https://base.gateway.tenderly.co",
            chainId: 8453,
          },
          tenderly_base_testnet: {
            // your Tenderly Virtual Environment RPC
            url: "https://virtual.base.eu.rpc.tenderly.co/872ac073-1de1-4422-b01d-8d057781d77d",
            chainId: 73571,
          },
        },
        tenderly: {
          username: "your-account-slug",
          project: "your-project-slug",

          // true: contract visible only inside your project.
          // Omitting or setting to false verifies publicly (the default).
          // TENDERLY_PRIVATE_VERIFICATION is plain dotenv wiring, not a
          // variable the plugin reads itself.
          privateVerification: process.env.TENDERLY_PRIVATE_VERIFICATION === "true",
        },
      };

      export default config;
      ```
    </Tab>
  </Tabs>
</Steps>

In the following sections, you'll learn how to verify contracts using the different verification methods.

## Automatic verification

Automatic verification occurs seamlessly when you deploy a contract using Ethers.js. The automatic verification approach will perform the verification automatically after collecting the compiler settings, the deployed contract's address, and the source code.

Automatic verification is **enabled by default**. To disable it, set the **`TENDERLY_AUTOMATIC_VERIFICATION`** environment variable recognized by the plugin to `false`.

The Tenderly-Hardhat plugin will verify contracts when it detects that the contract has been deployed, and Ethers has received the receipt of the deployment transaction.

To enable this, you need to **`await`** for deployment when you deploy contracts using Ethers' helper methods **`ethers.deployContract()`** and **`ethers.getContractFactory()`**, by calling **`waitForDeployment()`** or **`deployed()`** on the contract instance, respectively.

<Warning>
  You need to capture the reference to the contract object returned by the **`waitForDeployment()`** (Ethers 6) and
  **`deployed()`** (Ethers 5) if you intend to interact with that contract.
</Warning>

<Steps>
  ### Modify the deployment script

  <Tabs>
    <Tab title="Ethers 6">
      Modify the Hardhat script to capture the value returned from **`waitForDeployment()`**.

      ```diff title='deploy.ts' theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

      export async function main() {
      console.log("🖖🏽[ethers] Deploying and Verifying Greeter in Tenderly");

      -   const greeter = await ethers.deployContract("Greeter", ["Hello, Hardhat!"]);
      +   let greeter = await ethers.deployContract("Greeter", ["Hello, Hardhat!"]);

      -   await greeter.waitForDeployment();
      +   greeter = await greeter.waitForDeployment();

      const greeterAddress = await greeter.getAddress();
      console.log("{Greeter} deployed to", greeterAddress);
      }

      main().catch((error) => {
      console.error(error);
      process.exitCode = 1;
      });
      ```

      In more compact form:

      ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      const greeter = await (
      await ethers.deployContract("Greeter", ["Hello, Hardhat!"])
      ).waitForDeployment();
      ```
    </Tab>

    <Tab title="Ethers 5">
      The best way to explore how the automatic verification process works is to go through an example in [our
      GitHub repo](https://github.com/Tenderly/hardhat-tenderly/tree/master/examples/contract-verification/ethers-v5).

      This example uses our sample `Greeter` contract.

      Modify the Hardhat script to capture the value returned from **`deployed()`**.

      ```diff title='deploy.ts' theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

      export async function main() {
      console.log("🖖🏽[ethers] Deploying and Verifying Greeter in Tenderly");

      const Greeter = await ethers.getContractFactory("Greeter");

      -   const greeter = await Greeter.deploy("Hello, Hardhat!");
      +   let greeter = await Greeter.deploy("Hello, Hardhat!");

      -   await greeter.deployed();
      +   greeter = await greeter.deployed();

      const greeterAddress = await greeter.address;
      console.log("{Greeter} deployed to", greeterAddress);
      }

      main().catch((error) => {
      console.error(error);
      process.exitCode = 1;
      });
      ```

      In more compact form:

      ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      const greeter = await (
      await Greeter.deploy("Hello, Hardhat!")
      ).deployed();
      ```
    </Tab>
  </Tabs>

  ### Run the script

  Automatic verification is enabled by default. The commands below set **`TENDERLY_AUTOMATIC_VERIFICATION`** explicitly
  so each run's behavior is unambiguous.

  Run the script with the commands below. The link to the verified contract will be displayed in the Terminal output.

  <Tabs>
    <Tab title="Hardhat Ignition (Virtual Environment)">
      ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      TENDERLY_AUTOMATIC_VERIFICATION=true \
      npx hardhat ignition deploy ./ignition/modules/Lock.ts --network virtual_base --deployment-id deploy-to-virtual-base
      ```

      <Note>
        Make sure to add **`--deployment-id`** with a specific value when running the command.
      </Note>
    </Tab>

    <Tab title="Hardhat (Virtual Environment)">
      ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      TENDERLY_AUTOMATIC_VERIFICATION=true \
      npx hardhat run scripts/deploy.ts --network virtual_base
      ```
    </Tab>

    <Tab title="Public network">
      When deploying to a public mainnet or testnet, specify whether you want public or private verification. Make sure your `hardhat.config.ts` wires this variable into `privateVerification`, as shown above.

      ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      TENDERLY_PRIVATE_VERIFICATION=true \ # Verify privately. Omit to verify publicly (the default).
      TENDERLY_AUTOMATIC_VERIFICATION=true \
      npx hardhat run scripts/deploy.ts --network mainnet_base
      ```
    </Tab>
  </Tabs>
</Steps>

### Verifying proxy contracts

**Automatic verification of proxy contracts** deployed and upgraded with `hardhat-upgrades` is possible with the following versions of `@tenderly/hardhat-tenderly` package:

* **>= 1.10.0**
* **>= 2.1.0**

For versions **`1.x.x < 1.10.0`** and **`2.x.x < 2.1.0`** follow the [proxy verification guide](/contract-verification/hardhat-proxy).

## Manual verification

Low-code verification through **`tenderly.verify()`** allows you to be explicit about the exact point of verification within a deployment script or a Hardhat test.

This method is particularly beneficial for:

* Verifying previously deployed contracts through custom scripts.
* Verifying instances created by factory contracts.
* Enhancing test runs by selectively verifying contracts at the end of a failing suite (`after`), which speeds up execution.

To manually control the verification, disable automatic verification by changing the **`TENDERLY_AUTOMATIC_VERIFICATION`** to **`false`** when running scripts.

### The `verify` function

The **`verify()`** function takes an object where you must provide the:

* **`name`** of the contract
* **`address`** where the contract is deployed
* **`libraries`** (optional) used by the contract

The Tenderly-Hardhat plugin will pick up the existing compiler configuration and contract source code to perform the verification of the contracts you've specified.

<Note>
  It's necessary to invoke **`verify()`** after the contract has been deployed.

  If you're performing a verification alongside to deployment, you have to **`await`** for **`waitForDeployment()`** in
  the case of Ethers 6, and **`deployed()`** in the case of Ethers 5.
</Note>

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
let greeter = await ethers.deployContract("Greeter", ["Hello, Hardhat!"]);
greeter = await greeter.waitForDeployment();

await tenderly.verify({
  name: 'Greeter',
  address: await greeter.getAddress(),
  libraries: {
    AwsomeLib: "0x...",
  }
});
```

If you're verifying multiple contracts, the function has variadic arguments:

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
let greeter = await ethers.deployContract("Greeter", ["Hello, Hardhat!"]);
greeter = await greeter.waitForDeployment();

const counter = await (await ethers.deployContract("Counter", [42])).waitForDeployment();

await tenderly.verify(
  {
    name: 'Greeter',
    address: await greeter.getAddress(),
  },
  {
    name: 'Counter',
    address: await counter.getAddress(),
    libraries: {
        KickAssLib: "0x...",
    }
  },
);
```

<Steps>
  ### Disable automatic verification

  Automatic verification is enabled by default. Switch it off for a run by setting the `TENDERLY_AUTOMATIC_VERIFICATION` environment variable to `false`:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  TENDERLY_AUTOMATIC_VERIFICATION=false npx hardhat run scripts/deploy.ts --network virtual_base
  ```

  <Note>
    On plugin versions older than 2.4.0 (Ethers 6) and 1.10.0 (Ethers 5), disable it in `hardhat.config.ts` instead: `tdly.setup({ automaticVerifications: false })`.
  </Note>

  ### Modify the deployment script

  This uses the same examples as in automatic verification, but this time with the **`tenderly.verify()`** method to verify the contract.

  <Tabs>
    <Tab title="Ethers 6">
      ```diff title="deploy.ts" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
          + import { tenderly } from "hardhat";

          async function main() {
          console.log("🖖🏽[ethers] Deploying and Verifying Greeter in Tenderly");

          -   const greeter = await ethers.deployContract("Greeter", ["Hello, Manual Hardhat!",]);
          +   let greeter = await ethers.deployContract("Greeter", ["Hello, Manual Hardhat!",]);

          -   await greeter.waitForDeployment();
          +   greeter = await greeter.waitForDeployment();

          const address = await greeter.getAddress();
          console.log("Manual Simple: {Greeter} deployed to:", address);

          +    await tenderly.verify({
          +        address,
          +        name: "Greeter",
          +    });
        }

          main().catch((error) => {
          console.error(error);
          process.exitCode = 1;
        });
      ```
    </Tab>

    <Tab title="Ethers 5">
      ```diff title="deploy.ts" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
          + import { tenderly } from "hardhat";

          async function main() {
          console.log("🖖🏽[ethers] Deploying and Verifying Greeter in Tenderly");

          const Greeter = await ethers.getContractFactory("Greeter");

          -   const greeter = await Greeter.deploy("Hello, Manual Hardhat!");
          +   let greeter = await Greeter.deploy("Hello, Manual Hardhat!");

          -   await greeter.deployed();
          +   greeter = await greeter.deployed();

          const address = await greeter.address;
          console.log("Manual Simple: {Greeter} deployed to:", address);

          await tenderly.verify({
          address,
          name: "Greeter",
        });
        }

          main().catch((error) => {
          console.error(error);
          process.exitCode = 1;
        });
      ```
    </Tab>
  </Tabs>

  ### Run the script

  When running Hardhat scripts, you can set the **`TENDERLY_AUTOMATIC_VERIFICATION`** environment variable to `false` to disable automatic verification.

  <Tabs>
    <Tab title="Virtual Environment">
      ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      TENDERLY_AUTOMATIC_VERIFICATION=false \
      npx hardhat run scripts/deploy.ts --network virtual_base
      ```
    </Tab>

    <Tab title="Public network">
      When deploying to a public mainnet or testnet, specify whether you want public or private verification.

      ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      TENDERLY_PRIVATE_VERIFICATION=true \ # Verify privately. Omit to verify publicly (the default).
      TENDERLY_AUTOMATIC_VERIFICATION=false \
      npx hardhat run scripts/deploy.ts --network mainnet_base
      ```
    </Tab>
  </Tabs>
</Steps>

## Verbose manual verification

The method **`verifyMultiCompilerAPI()`** gives you full control over the verification process, allowing you to specify every detail of the verification process.

This is **rarely recommended** but can be useful if you're verifying contracts compiled with different compiler versions or configurations.

The fully controlled verification method allows you to explicitly:

* Specify the source code of the contracts (**`sources`**)
* Set compilation arguments (**`compiler`**)
* Set linked libraries (**`libraries`**)

The following example demonstrates how to perform a fully controlled verification.

```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
await tenderly.verifyMultiCompilerAPI({
  contracts: [
    {
      contractToVerify: 'Greeter',
      sources: {
        'contracts/Greeter.sol': {
          name: 'Greeter',
          code: readFileSync('contracts/Greeter.sol', 'utf-8').toString(),
        },
        'hardhat/console.sol': {
          name: 'console',
          code: readFileSync('node_modules/hardhat/console.sol', 'utf-8').toString(),
        },
      },
      // solidity format compiler with a little modification at libraries param
      compiler: {
        version: '0.8.17',
        settings: {
          optimizer: {
            enabled: true,
            runs: 200,
          },
        },
        libraries: {
          'path/to/lib.sol': {
            addresses: {
              LibName1: '0x...',
              LibName2: '0x...',
            },
          },
        },
      },
      networks: {
        [NETWORK_ID]: {
          address: greeterAddress,
        },
      },
    },
  ],
});
```

### Verification arguments

The **`verifyMultiCompilerAPI()`** method takes one argument -- an array of contract objects. Each contract object consists of the following:

|                    |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contractToVerify` | string | The name of the contract is to be verified. *This can be a short name like `Greeter` or a fully qualified contract name like `contracts/A/Greeter.sol:Greeter`.*                                                                                                                                                                                                                                                                                                      |
| `sources`          | map    | A map of all sources that are needed to compile the contract. The key of the map is a source path to the contract, whereas the value is an object containing the name and UTF-8-encoded contract source. `js sources: { 'contracts/Greeter.sol': { name: 'Greeter', code: readFileSync('contracts/Greeter.sol', 'utf-8').toString(), }, 'hardhat/console.sol': { name: 'console', code: readFileSync('node_modules/hardhat/console.sol', 'utf-8').toString(), }, }, ` |
| `networks`         | map    | A map containing all deployment addresses on multiple networks. `js { networks: { [NETWORK_ID]: { address: greeterAddress, }, }, } `                                                                                                                                                                                                                                                                                                                                  |
| `libraries`        | map    | A map containing information about deployments of libraries. The key is the relative path to the library source, relative to the `contracts` folder. `js compiler.settings.libraries = { "path/to/lib.sol": { addresses: { "LibName1": "0x...", "LibName2": "0x..." } } } `                                                                                                                                                                                           |


# Verifying Proxy Contracts
Source: https://docs.tenderly.co/contract-verification/hardhat-proxy

Follow this step-by-step guide to learn about verifying proxy smart contracts using the Tenderly-Hardhat plugin.

<Info>
  **Works on:** public networks (mainnets and testnets). To verify proxy contracts on a [Virtual Environment](/virtual-environments/overview), follow [Verify proxy contracts with Foundry](/virtual-environments/develop/verify-proxy-contracts).
</Info>

This guide will walk you through proxy contract verification using `@tenderly/hardhat-tenderly`.

## Requirements

Automatic proxy verification works out of the box on `@tenderly/hardhat-tenderly`:

* **`>= 1.10.0`** (Ethers 5 line)
* **`>= 2.1.0`** (Ethers 6 line)

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
npm update @tenderly/hardhat-tenderly
```

It only works when you deploy proxies with [`@openzeppelin/hardhat-upgrades`](https://docs.openzeppelin.com/upgrades-plugins/api-hardhat-upgrades). [Hardhat Ignition](https://hardhat.org/ignition/docs/getting-started#overview) is **not supported** for proxy verification yet.

If you're on a lower plugin version and can't upgrade, use the [manual workaround](#workaround-for-lower-versions) below.

## Automatic verification

The plugin verifies three proxy patterns: `TransparentUpgradeableProxy`, `UUPSUpgradeableProxy`, and `BeaconProxy`.

<Steps>
  ### Set the auto-populate flag

  Under the hood the plugin drives `@nomicfoundation/hardhat-verify` with the `@openzeppelin/hardhat-upgrades` extension. Setting `TENDERLY_AUTOMATIC_POPULATE_HARDHAT_VERIFY_CONFIG=true` lets the plugin populate `@nomicfoundation/hardhat-verify`'s verification URL for you. The handoff authenticates with your [access key](/platform/account/projects/api-tokens), so `TENDERLY_ACCESS_KEY` must be set as well.

  ```bash title=".env" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  TENDERLY_AUTOMATIC_POPULATE_HARDHAT_VERIFY_CONFIG=true
  TENDERLY_ACCESS_KEY=your-access-key
  ```

  ### Write deployment script

  For a clearer view, you can check out [this GitHub repo](https://github.com/Tenderly/hardhat-tenderly/tree/master/examples/contract-verification/ethers-v6) and go to **`scripts/proxy/`** to see the full example.

  <Tabs>
    <Tab title="Automatic">
      Deploy the proxy as usual using `deployProxy` from the **`@openzeppelin/hardhat-upgrades`** extension.

      <Warning>
        You must capture the object returned by the **`waitForDeployment`** function to interact with it further.
      </Warning>

      Under the hood, the automatic verification is implemented by wrapping the **`deployProxy`**, and waiting for completion of the deployment.

      ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

      async function main() {
          console.log(
              "🖖🏽[ethers] Deploying TransparentUpgradeableProxy with VotingLogic as implementation on Tenderly.",
          );

          const VotingLogic = await ethers.getContractFactory("VotingLogic");
          let proxyContract = await upgrades.deployProxy(VotingLogic);
          proxyContract = await proxyContract.waitForDeployment();

          const proxyAddress = await proxyContract.getAddress();

          console.log("VotingLogic proxy deployed to:", proxyAddress);
          console.log(
              "VotingLogic impl deployed to:",
              await getImplementationAddress(ethers.provider, proxyAddress),
          );
      }

      main().catch((error) => {
          console.error(error);
          process.exitCode = 1;
      });
      ```
    </Tab>

    <Tab title="Manual">
      Verifying the proxy with the manual verification method is done after the proxy contract has been deployed, by calling the **`tenderly.verify()`** function.

      ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

      async function main() {
          console.log(
              "🖖🏽[ethers] Deploying TransparentUpgradeableProxy with VotingLogic as implementation on Tenderly.",
          );

          const VotingLogic = await ethers.getContractFactory("VotingLogic");
          let proxyContract = await upgrades.deployProxy(VotingLogic);
          proxyContract = await proxyContract.waitForDeployment();

          const proxyAddress = await proxyContract.getAddress();

          console.log("VotingLogic proxy deployed to:", proxyAddress);
          console.log(
              "VotingLogic impl deployed to:",
              await getImplementationAddress(ethers.provider, proxyAddress),
          );

          await tenderly.verify({
              name: "TransparentUpgradeableProxy",
              address: proxyAddress,
          });
      }

      main().catch((error) => {
          console.error(error);
          process.exitCode = 1;
      });
      ```
    </Tab>
  </Tabs>

  ### Run the script

  Automatic verification is enabled by default, so no extra variable is needed to turn it on. Specify whether you want [public or private verification](/contract-verification/hardhat#configure-authentication-and-verification-visibility):

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  TENDERLY_AUTOMATIC_POPULATE_HARDHAT_VERIFY_CONFIG=true \
  TENDERLY_PRIVATE_VERIFICATION=true \ # Verify privately. Omit to verify publicly (the default).
  npx hardhat run scripts/deploy.ts --network mainnet_base
  ```
</Steps>

## Workaround for lower versions

When using `@tenderly/hardhat-tenderly` at versions **`< 1.10.0`** and **`< 2.1.0`**, this workaround will enable automatic verification.

You need to verify the following:

* The proxy contract (e.g. OpenZeppelin's proxies)
* Implementation behind the proxy
* Any dependencies the implementation has
* New implementation instances deployed with upgrades

The verification process varies depending on the proxy contract type and the implementation.

<figure>
  <img alt="Tenderly Docs" />

  <figcaption />
</figure>

### Overview

In this guide, we'll use [an example Hardhat project](https://github.com/Tenderly/tenderly-examples) and the **`@tenderly/hardhat-tenderly`** plugin to demonstrate the verification of OpenZeppelin's [UUPSUpgradeable](https://docs.openzeppelin.com/contracts/4.x/api/proxy#UUPSUpgradeable), [TransparentUpgradeableProxy](https://docs.openzeppelin.com/contracts/4.x/api/proxy#TransparentUpgradeableProxy), and [BeaconProxy](https://docs.openzeppelin.com/contracts/4.x/api/proxy#BeaconProxy) alternatives.

<Warning>
  Proxy contracts need to be [verified manually](/contract-verification/hardhat#manual-verification). On the plugin versions this workaround targets (older than 2.4.0 on the Ethers 6 line and 1.10.0 on the Ethers 5 line), turn off automatic verification in `hardhat.config.ts`:

  ```typescript title="hardhat.config.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  // use manual verification
  tdly.setup({ automaticVerifications: false });
  ```
</Warning>

To obtain the address of the deployed implementation, use the **`@openzeppelin/upgrades-core`** package and **`getImplementationAddress`** function.

Verifying the proxy implementation is usually straightforward; verify it just like any other contract.

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
await tenderly.verify({
  // the new implementation contract
  name: 'VaultV2',
  // the address where implementation is deployed
  address: await getImplementationAddress(ethers.provider, await proxy.getAddress()),
});
```

To verify the proxy instance, you need to complete these two preliminary steps:

1. [Load the exact smart contract of the proxy](#loading-proxy-contracts) depending on the type of proxy you're using, so it gets compiled. You'll need to import the proxy contracts through the compiler by creating a dummy .sol file.
2. [Modify **`hardhat.config.ts`**](#configuring-solidity-compiler-overrides) to specify the settings OpenZepplin contracts were compiled with.

Once these steps are completed, you can proceed to verify the proxy just as you would any other contract.

```ts title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
await tenderly.verify({
  name: 'ERC1967Proxy', // or TransparentUpgradeableProxy or BeaconProxy
  address: await proxy.getAddress(),
});
```

<Steps>
  ### Clone the example repo

  ```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  git clone git@github.com:Tenderly/tenderly-examples.git
  cd contract-verifications
  npm i
  ```

  ### Set up the Tenderly CLI

  ```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  brew tap tenderly/tenderly && brew install tenderly
  tenderly login
  ```

  See the [Tenderly CLI repo](https://github.com/Tenderly/tenderly-cli) for non-Homebrew install options.

  ### Configure Hardhat

  In `hardhat.config.ts`, set `tenderly.username` and `tenderly.project` to your [project and username slugs](/platform/account/projects/slug).

  ### Create a Virtual Environment

  The fastest way to deploy and verify contracts is on a [Virtual Environment](/virtual-environments/overview).

  In the [Tenderly Dashboard](https://dashboard.tenderly.co), open **Virtual Environments** and create a new one. Pick the base network to fork from and a Chain ID, then copy the **Admin RPC URL** from the Virtual Environment's details page.

  Add the RPC URL to your `.env` file:

  ```bash title=".env" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  TENDERLY_VIRTUAL_TESTNET_RPC=https://virtual.<network>.rpc.tenderly.co/<your-uuid>
  ```

  Then reference it in `hardhat.config.ts`:

  ```typescript title="hardhat.config.ts" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  networks: {
    virtualMainnet: {
      url: process.env.TENDERLY_VIRTUAL_TESTNET_RPC!,
      chainId: 73571, // the Chain ID you set when creating the Virtual Environment
    },
  },
  ```

  For a full walkthrough see the [Virtual Environment quickstart](/virtual-environments/quickstart).

  ### Run the tests

  ```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  rm -rf .openzeppelin && npx hardhat test --network virtualMainnet
  ```

  <Note>When redeploying contracts, remove the **`.openzeppelin`** folder first. It caches information about proxies and their implementations.</Note>

  ### Load the proxy contracts

  To verify the proxy contract, create a **`DummyProxy.sol`** file and import the OpenZepplin proxy contracts you're working with. In doing so, these contracts are loaded and have passed through the compiler, enabling you to reference the exact contract source of the proxy during verification.

  ```sol theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  // SPDX-License-Identifier: MIT
  pragma solidity ^0.8.17;


  abstract contract ERC1967ProxyAccess is ERC1967Proxy {}
  abstract contract UpgradableBeaconAccess is UpgradeableBeacon {}
  abstract contract BeaconProxyAccess is BeaconProxy {}
  abstract contract TransparentUpgradeableProxyAccess is TransparentUpgradeableProxy {}
  ```

  ### Configure Solidity compiler overrides

  <Note>
    The following overrides map was derived for **`@openzeppelin/contracts-upgradeable`** version **`4.9.1`**.
    They may differ for other versions of the package.
  </Note>

  After compiling Openzepplin's proxy contracts, you also need to specify the following:

  * Version of the Solidity compiler that was used to compile the contracts
  * Optimization settings used by Openzepplin's upgrades plugin when performing proxy deployment/upgrades

  <Warning>
    The **`hardhat-tenderly`** plugin uses both the source code of smart contracts and compiler settings
    for verification. If either of these settings is incorrect, the verification will fail.
  </Warning>

  Add the following **`overrides`** map to the **`config.solidity`** section of your Hardhat User config object.

  ```ts title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  const config: HardhatUserConfig = {
    solidity: {
      compilers: [{ version: '0.8.18' } /* OTHER COMPILER VERSIONS*/],
      overrides: {
        '@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol': {
          version: '0.8.9',
          settings: {
            optimizer: {
              enabled: true,
              runs: 200,
            },
          },
        },
        '@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol': {
          version: '0.8.9',
          settings: {
            optimizer: {
              enabled: true,
              runs: 200,
            },
          },
        },

        '@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol': {
          version: '0.8.9',
          settings: {
            optimizer: {
              enabled: true,
              runs: 200,
            },
          },
        },
        '@openzeppelin/contracts/proxy/beacon/BeaconProxy.sol': {
          version: '0.8.9',
          settings: {
            optimizer: {
              enabled: true,
              runs: 200,
            },
          },
        },
        'contracts/proxy.sol': {
          version: '0.8.9',
          settings: {
            optimizer: {
              enabled: true,
              runs: 200,
            },
          },
        },
      },
    },
    /* OTHER CONFIG */
  };
  ```
</Steps>

## Verify by proxy type

These code samples show how to verify the implementation and the proxy for OpenZeppelin's three proxy patterns. The examples use a proxied `Vault` contract that references an ERC-20 token (`TToken`).

### UUPS proxy

To verify the UUPS proxy and the underlying information, call the **`hardhat-tenderly`** plugin twice:

1. To verify the implementation, you need to provide the following:

* **`name`** of your proxied contract (in our case **`Vault`**)
* Address where the contract was deployed using the **`getImplementationAddress`** method from **`@openzeppelin/upgrades-core`**.

2. To verify the proxy, provide the following:

* **`ERC1967Proxy`** as the proxy contract **`name`**
* Address of the proxy **`proxy.address`**

```ts title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
await tenderly.verify(
  {
    name: 'Vault',
    address: await getImplementationAddress(ethers.provider, await proxy.getAddress()),
  },
  {
    name: 'ERC1967Proxy',
    address: await proxy.getAddress(),
  },
);
```

#### Complete Code Sample

Here's a complete Hardhat test that does the following:

* Deploys the **`TToken`** (needed for the vault)
* Deploys **`Vault`** as a proxy, initialized with the **`TToken`** contract
* Verifies the proxy (**`ERC1967Proxy`**) instance deployed at **`await proxy.getAddress()`**
* Verifies the implementation instance **`Vault`**, deployed at **`getImplementationAddress(ethers.provider, await proxy.getAddress())`**
* Upgrades the proxy to **`VaultV2`**

```ts title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

describe('Vault', () => {
  it('uups proxy deployment and verification', async () => {
    const VaultFactory = await ethers.getContractFactory('Vault');
    const TokenFactory = await ethers.getContractFactory('TToken');

    let token = await ethers.deployContract('TToken');
    token = await token.waitForDeployment();
    const tokenAddress = await token.getAddress();

    await tenderly.verify({
      name: 'TToken',
      address: tokenAddress,
    });

    let proxy = await upgrades.deployProxy(VaultFactory, [tokenAddress], {
      kind: 'uups',
    });
    await proxy.waitForDeployment();
    const proxyAddress = await proxy.getAddress();

    console.log('Deployed UUPS ', {
      proxy: proxyAddress,
      implementation: await getImplementationAddress(ethers.provider, proxyAddress),
    });

    await tenderly.verify(
      {
        name: 'Vault',
        address: await getImplementationAddress(ethers.provider, proxyAddress),
      },
      {
        name: 'ERC1967Proxy',
        address: proxyAddress,
      },
    );

    // upgrade
    const vaultV2Factory = await ethers.getContractFactory('VaultV2');
    proxy = (await upgrades.upgradeProxy(proxy, vaultV2Factory, {
      kind: 'uups',
    })) as Vault;

    await proxy.waitForDeployment();

    console.log('Upgraded UUPS ', {
      proxy: proxyAddress,
      implementation: await getImplementationAddress(ethers.provider, proxyAddress),
    });

    await tenderly.verify({
      name: 'VaultV2',
      address: await getImplementationAddress(ethers.provider, proxyAddress),
    });
  });
});
```

### Transparent proxy

To verify the Transparent proxy and the underlying information, call **`hardhat-tenderly`** while passing two contracts: **`Vault`** for the implementation, and **`TransparentUpgradeableProxy`** for the proxy itself.

```ts title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
await tenderly.verify(
  {
    name: 'Vault',
    address: await getImplementationAddress(ethers.provider, await proxy.getAddress()),
  },
  {
    name: 'TransparentUpgradeableProxy',
    address: await proxy.getAddress(),
  },
);
```

1. To verify the implementation, provide the following:

* **`name`** of your proxied contract (in our case **`Vault`**)
* Address where the contract was deployed, using the **`getImplementationAddress`** method from **`@openzeppelin/upgrades-core`**.

2. To verify the proxy, provide the following:

* **`TransparentUpgradeableProxy`** as the proxy contract **`name`**
* Address of the proxy **`await proxy.getAddress()`**

#### Complete Code Sample

```ts title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

describe('Vault', () => {
  it('transparent upgradable proxy deployment and verification', async () => {
    const VaultFactory = await ethers.getContractFactory('Vault');
    const TokenFactory = await ethers.getContractFactory('TToken');

    let token = await ethers.deployContract('TToken');
    token = await token.waitForDeployment();
    const tokenAddress = await token.getAddress();

    await tenderly.verify({
      name: 'TToken',
      address: tokenAddress,
    });

    let proxy = await upgrades.deployProxy(VaultFactory, [tokenAddress], {
      kind: 'transparent',
    });
    await proxy.waitForDeployment();
    const proxyAddress = await proxy.getAddress();

    console.log('Deployed transparent', {
      proxy: proxyAddress,
      implementation: await getImplementationAddress(ethers.provider, proxyAddress),
    });

    await tenderly.verify(
      {
        name: 'Vault',
        address: await getImplementationAddress(ethers.provider, proxyAddress),
      },
      {
        name: 'TransparentUpgradeableProxy',
        address: proxyAddress,
      },
    );

    // upgrade
    const vaultV2Factory = await ethers.getContractFactory('VaultV2');

    proxy = (await upgrades.upgradeProxy(proxy, vaultV2Factory, {
      kind: 'transparent',
    })) as Vault;

    await proxy.waitForDeployment();

    console.log('Upgraded transparent ', {
      proxy: proxyAddress,
      implementation: await getImplementationAddress(ethers.provider, proxyAddress),
    });

    await tenderly.verify({
      name: 'VaultV2',
      address: await getImplementationAddress(ethers.provider, proxyAddress),
    });
  });
});
```

### Beacon proxy

To verify the Beacon proxy and the underlying information, you have to verify two contracts: the **`Vault`** (implementation) and OpenZepplin's **`UpgradableBeacon`**:

```ts title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
await tenderly.verify(
  {
    name: 'Vault',
    address: await getImplementationAddressFromBeacon(ethers.provider, await beacon.getAddress()),
  },
  {
    name: 'UpgradeableBeacon',
    address: await beacon.getAddress(),
  },
);
```

#### Complete Code Sample

```ts title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

describe('Vault', () => {
  it('beacon proxy deployment and verification', async () => {
    const VaultFactory = await ethers.getContractFactory('Vault');
    const TokenFactory = await ethers.getContractFactory('TToken');

    let token = await ethers.deployContract('TToken');
    token = await token.waitForDeployment();
    const tokenAddress = await token.getAddress();

    await tenderly.verify({
      name: 'TToken',
      address: tokenAddress,
    });

    let beacon = (await upgrades.deployBeacon(VaultFactory)) as UpgradeableBeacon;

    await beacon.waitForDeployment();
    const beaconAddress = await beacon.getAddress();

    let vault = await upgrades.deployBeaconProxy(beacon, VaultFactory, [tokenAddress], {
      initializer: 'initialize',
    });
    await vault.waitForDeployment();

    console.log('Deployed beacon ', {
      proxy: beaconAddress,
      implementation: await getImplementationAddressFromBeacon(ethers.provider, beaconAddress),
      beacon: beaconAddress,
    });

    await tenderly.verify(
      {
        name: 'Vault',
        address: await getImplementationAddressFromBeacon(ethers.provider, beaconAddress),
      },
      {
        name: 'UpgradeableBeacon',
        address: beaconAddress,
      },
    );

    const vaultV2Factory = await ethers.getContractFactory('VaultV2');

    // upgrade
    vault = await upgrades.deployBeaconProxy(beacon, vaultV2Factory, [tokenAddress]);

    await upgrades.upgradeBeacon(beaconAddress, vaultV2Factory, {});

    console.log('Upgraded beacon ', {
      proxy: beaconAddress,
      implementation: await getImplementationAddressFromBeacon(ethers.provider, beaconAddress),
      beacon: beaconAddress,
    });

    await tenderly.verify({
      name: 'VaultV2',
      address: await getImplementationAddressFromBeacon(ethers.provider, beaconAddress),
    });
  });
});
```


# Smart Contract Verification
Source: https://docs.tenderly.co/contract-verification/overview

Verify a smart contract on Tenderly to decode its transactions, events, and state changes, and debug execution against the original Solidity source.

Contract verification submits the source code of a deployed contract so Tenderly can match it against the on-chain bytecode. Once verified, Tenderly can decode that contract's transactions, events, and state changes in:

* **Decoded transactions**: call traces, events, state changes, and gas usage become human-readable.
* **Debugger**: step through execution against the original Solidity, set priorities, and comment on traces.
* **Gas profiler**: line-level gas attribution against the source.
* **Sharing**: share verified contracts with collaborators and auditors.

Without verification you'll see raw bytecode in every Tenderly tool that touches that contract.

## Pick a method

For verification on **public networks** (mainnets and testnets), pick the guide that matches your tooling:

* [Dashboard](/contract-verification/dashboard): browser-only verification from the Tenderly Dashboard.
* [Foundry](/contract-verification/foundry): `forge verify-contract` and deploy-and-verify with `forge create` / `forge script`.
* [Hardhat](/contract-verification/hardhat): the `@tenderly/hardhat-tenderly` plugin, automatic or manual.
* [Hardhat (proxy contracts)](/contract-verification/hardhat-proxy): UUPS, Transparent, and Beacon proxies.

To verify contracts on a **Virtual Environment**, see [Deploy and verify contracts](/virtual-environments/develop/deploy-contracts) and [Verify proxy contracts with Foundry](/virtual-environments/develop/verify-proxy-contracts) under Virtual Environments.

## Public vs private visibility

On **public networks** you choose between two visibility modes:

* **Public verification.** Source is visible to everyone on Tenderly and propagated to public verification registries.
* **Private verification.** Source is visible only inside your Tenderly project and organization.

On **Virtual Environments** verifications are always scoped to your project and organization. There is no public mode; see [Deploy and verify contracts](/virtual-environments/develop/deploy-contracts).

| Who can see the verified source | Public verification (public network) | Private verification (public network) | Virtual Environment |
| ------------------------------- | :----------------------------------: | :-----------------------------------: | :-----------------: |
| All Tenderly users              |                   ✓                  |                                       |                     |
| Project collaborators           |                   ✓                  |                   ✓                   |          ✓          |
| Organization members            |                   ✓                  |                   ✓                   |          ✓          |

How to switch to private mode depends on the method:

* **Hardhat**: set `tenderly.privateVerification: true` in `hardhat.config.ts`. See [Hardhat setup](/contract-verification/hardhat#configure-authentication-and-verification-visibility).
* **Foundry**: append `/public` to the verifier URL to verify publicly, omit it to verify privately. See [Foundry verifier URL](/contract-verification/foundry#verifier-url).
* **Dashboard**: toggle **Make Private** in the verification dialog. See [Dashboard verification](/contract-verification/dashboard#public-and-private-verification).


# Commenting & Prioritizing Traces
Source: https://docs.tenderly.co/debugger/commenting

Comment on any execution trace and set priorities so your team can flag and discuss the calls that matter during debugging.

Collaboration can be complex and time-consuming when you go through various contracts and Execution Traces ([**Function Trace and Call Trace**](/debugger/execution-overview)). That is why you can comment on any trace, as well as set priorities.

Click the speech-bubble icon next to a trace node in the execution tree to open its comment panel on the right side of the Debugger. The panel header shows the number of comments on that trace (for example, "0 comments on `exactInputSingle`"), and you can post a reply from the box at the bottom of the panel.

<img alt="" />

When you select a trace, you can clearly prioritize it. In the top right of the trace window you can see the option ***Set priority*** right next to [*View in Debugger*](/debugger/overview) button - clicking on it opens a dropdown from which you can select the priority you want for that particular trace and it will stay marked for all users that have access to the project until manually changed. Selecting *None* for the priority of a trace removes the markings.

Lastly, clicking on the three dots next to *Set priority* opens up a dropdown where you can [view the contract source](/simulator-ui/editing-contract-source).

<img alt="" />

All the comment and priority features persist through both Transaction Overview and Debugger views in your dashboard.

<img alt="" />

You can delete your own comments from the comment panel.

<img alt="" />


# Dev Toolkit Browser Extension
Source: https://docs.tenderly.co/debugger/dev-toolkit

Dev Toolkit browser extension gives one-click access to Tenderly debugging tools on any block explorer to analyze on-chain data.

Tenderly Dev Toolkit is a browser extension that gives you one-click access to Tenderly’s powerful exploration and debugging tools on any block explorer. Open any transaction in the Tenderly Dashboard to explore, analyze, and debug on-chain data in a human-readable format.

<iframe title="YouTube video player" />

Once you install the extension, you can access Virtual Environments, Debugger, Simulator, Gas Profiler, and other functionalities from a toolbar on any block explorer.

Download the extension from the Chrome store here:

<Card title="Dev Toolkit Browser Extensionn" href="" />

## Using Tenderly Dev Toolkit

Use Tenderly Dev Toolkit in your everyday workflows to speed up on-chain exploration and debugging. Open any transaction in Tenderly to use the following functionalities:

* **Run on Virtual Environment:** Execute any transaction in a new [Virtual Environment](/virtual-environments/overview) synced with the latest mainnet state to run further tests and experiments.
* **Simulate:** [Simulate successful or failed transactions](/simulator-ui/overview) with updated inputs, parameters, and contract code to preview their execution and expected outcomes.
* **Debug:** Use a [trace-by-trace Debugger](/debugger/overview) to identify where and why an error occurred and edit the contract code to try out a fix right away.
* **View trace:** [Inspect transaction execution](/developer-explorer/inspect-transaction/overview) using the most detailed, searchable stack trace displaying opcodes, event logs, storage variables, and gas usage.
* **View state changes:** [Analyze state changes](/developer-explorer/inspect-transaction/overview#state-changes) that happened during transaction execution, analyzing events and variables in both decoded and raw format.
* **View gas usage:** Get a [granular breakdown of gas usage](/debugger/gas-profiler) per individual function call and optimize code to save valuable resources.


# Evaluate Expressions with Advanced Debugger
Source: https://docs.tenderly.co/debugger/evaluate-expression

Evaluate Solidity expressions in a transaction's execution trace, inspecting state variables, mappings, dynamic arrays, and function results in Debugger.

Evaluate Expression is a tool in [Debugger](/debugger/overview) that allows you to evaluate expressions in the execution trace. You can assess complex expressions in smart contracts, including dynamic arrays, mappings, state variables, functions, and both global and local variables. Learn more about [how Evaluate works](https://blog.tenderly.co/how-use-evaluate-expression-speed-debugging).

To access the Evaluate feature, click on any transaction, then go to the **Debugger**, and click on the **Evaluate** button.

<img alt="" />

<img alt="" />

<img alt="" />

The Evaluate feature currently supports Solidity contracts. Choose any expression you want to evaluate, paste it into the box and hit the **Evaluate** button:

<img alt="" />

<img alt="" />

<img alt="" />

This works for both simple and complex expressions:

<img alt="" />

<img alt="" />

Learn more about other [Debugger features](/debugger/overview#stack-traces) and [searching the call trace](/developer-explorer/inspect-transaction/overview#search-the-call-trace).


# Execution Overview
Source: https://docs.tenderly.co/debugger/execution-overview

Get a bird's-eye view of a transaction with the function trace, call trace, contracts, events, state changes, and gas profiler in one place.

<img alt="Successful Transaction" />

<img alt="Failed Transaction" />

Execution Overview - think of it as the bird's-eye view of the transaction. At a glance, you can see the exact code paths of all of the Smart Contracts that participated in a given transaction. You can open the transactions from the images above by clicking [**here (successful)**](https://dashboard.tenderly.co/tx/mainnet/0x1ca07994d823e4198d7517d828d99e2064f3204501284d5348ca8c11e3be53d8) and [**here (failed)**](https://dashboard.tenderly.co/tx/mainnet/0xe0ca90fba27e63cd8550565fa8d57559f76b67f5e7d8b8dbb150752a48cb87d2).

In the first tab - **Transaction Overview** - you can see and navigate through all of the elements of the transaction. Moreover, you can instantly (Re)Simulate the transaction by clicking the button in the top right, using different parameters, or even changing the source code to observe the outcome - [**read more about Simulations here**](/simulator-ui/overview).

<img alt="" />

From the Overview Tab tab, you can instantly jump into Contract Sources or Debugger to see what happened:

<img alt="" />

If you're looking into a failed transaction, you can now **jump straight to all fail points by clicking the red warning icon and then clicking on the line that failed**:

<img alt="" />

<img alt="" />

You can also search the Execution Trace, as well as easily navigate it with your keyboard arrows:

<img alt="" />

<img alt="" />

### Call and Function Trace

In the Execution Trace section, you'll find a dropdown menu right next to the search field. By default, it's set to **Function Trace**, which means it will show all external and internal calls that happened in this transaction.

<img alt="" />

For a better overview of key calls, switch it to **Call Trace**, which shows only external calls that happened in the transaction.

<img alt="" />

<Info>
  You can **comment and prioritize any trace you want**, either for yourself or to make
  collaboration in the project easier. You can [**read more about it
  here**](/debugger/commenting).
</Info>

This feature is available in [**Debugger**](/debugger/overview) as well. Now, let's say you want to really dig really deep into your (or any other) Transaction. Let's go through each of the tabs available.

### Contracts

When you're in the **Transaction Overview** tab, in the upper navigation, you can click **Contracts** to see all of the contracts that have been involved in a certain transaction:

<img alt="" />

By clicking on a contract, you can view its source code:

<img alt="" />

### Events

Smart Contract Events are the de-facto way of notifying interested parties that some event has occurred. The Logs themselves also contain valuable information in addition to the information that a particular event has occurred.

<img alt="" />

When we click the **Events** tab, we can see all of the Events that were [emitted during a transaction](https://dashboard.tenderly.co/tx/mainnet/0x98a8a99daec2823836ac155003ec7c798ded926a86e1c165716dd0d0ea5133a0). What is even better is that **the event parameters are already decoded and shown in a human-readable format**. No more time wasted decoding hex strings to see what happened. You can also filter the Events by Name and Smart Contract.

### State Changes

As Smart Contracts are getting more and more complex, the states of those smart contracts are getting more complex as well.

<img alt="" />

Here we see that not only does Tenderly show the state variables that were changed, but also **all of them are decoded for your convenience**. **And yes, structures are decoded correctly as well**.

You can see that transaction and its intricacies [here](https://dashboard.tenderly.co/tx/mainnet/0x98a8a99daec2823836ac155003ec7c798ded926a86e1c165716dd0d0ea5133a0).

### Debugger

Debugging stack traces is an important part of any developer's workflow both locally and in production. By clicking on the **Debugger** tab, you'll be able to deep-dive into everything that happened with your (or any other) transaction.

<img alt="" />

**The stack trace above shows the exact line of code where the transaction failed**. From there, you can click **Debug Error** and find the issue in no time. Check out[ **how to use Tenderly Debugger**](/debugger/overview) and [**investigate failed transactions**](/debugger/overview)!

### Gas Profiler

<img alt="" />

The chart you see in the image above is called a flame graph. It's a common way to show the usage of a resource like a CPU. You can find the example above [here](https://dashboard.tenderly.co/tx/mainnet/0x98a8a99daec2823836ac155003ec7c798ded926a86e1c165716dd0d0ea5133a0).

Each line shows the sum cost of the lines beneath it. If you click on any of the lines (functions), you can see a detailed breakdown of the gas cost of the functions that were invoked.

<img alt="" />

You can finally see which functions are using the most gas and pick the right parts of your code to optimize.


# Gas Profiler
Source: https://docs.tenderly.co/debugger/gas-profiler

Break down gas consumption per function with an interactive flame chart, spot the most expensive calls, and optimize gas usage in Debugger.

Gas Profiler gives you a breakdown of gas consumption, revealing how each function within a contract uses gas during execution. When combined with Debugger and Simulator, Gas Profiler makes up the core of the Developer Explorer.

<img alt="Gas profiler" />

## Getting started with Gas Profiler

1. Open any transaction from the transaction listing page. Try this [example transaction](https://dashboard.tenderly.co/tx/1/0x1696cfc031695003b8a58f0379c7f111b34c7612a67681354dc57cb5853c5c63/gas-usage).

2. Navigate to **Gas Profiler** in the top menu to access an interactive flame chart with detailed gas usage breakdowns for each called function, including internal transactions.

3. Click on any function to reveal a detailed view of its gas usage.

4. For deeper insights, [open the transaction in Debugger](/debugger/overview) to pinpoint the exact line of code in the Solidity file responsible for execution.

<img alt="Gas profiler" />

### Optimizing gas usage

1. Clicking on a function call in the flame chart displays detailed gas usage information in the lower pane.

2. If you suspect a function requires gas optimization, click the **View in Debugger** button to dive into the code and optimize it to reduce gas usage.

3. To verify that the changes help reduce gas usage, you can simulate the same transaction with the changed code and compare the gas profiling result.

#### Total gas vs actual gas

**Total Gas** represents the overall gas cost of execution, encompassing the sum of gas costs associated with all invoked opcodes.

**Actual Gas** denotes the net gas cost of the execution. When multiplied by the `gas_price`, it provides the exact amount you would pay for this execution in wei.

The formula for calculating Actual Gas: `actual_gas_used = total_gas - gas_refund`.

Blockchain users receive rewards for clearing up storage, manifested in the form of [gas refunds](https://github.com/wolflo/evm-opcodes/blob/main/gas.md#a0-3-gas-refunds) for `SSTORE` invocations that effectively "delete" existing stored data. These gas refunds are subtracted from the Total Gas, resulting in the Actual Gas used.


# Investigating a Failed Transaction
Source: https://docs.tenderly.co/debugger/guides/failed-transaction

Trace a reverted transaction to its root cause using the call trace, Debugger, and Evaluate, then verify the fix by re-simulating it.

In this guide, we'll investigate the root cause of transaction failure and verify the fix.

We'll look into a [Uniswap transaction](https://www.tdly.co/tx/1/0xbe082dcc8ae59868f5b2330173902bb88c6643b5c2fdf0d8a9f43d03dbca0c36). This transaction attempts to `swapExactTokensForTokens`.

<Steps>
  ### Paste the transaction hash in search of Tenderly dashboard

  Transaction hash: `0xbe082dcc8ae59868f5b2330173902bb88c6643b5c2fdf0d8a9f43d03dbca0c36`

  ### Explore the error

  The revert happened in `swapExactTokensForTokens`, checking a condition involving `amountOutMin` that is an input parameter. It reverted with the following error message:
  Error message: `UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT`

  From the inputs section, we can see that `amountOutMin` had value `1102820622890207119`.

  <img alt="" />

  ### Explore revert condition

  Hop into the [debugger view](https://dashboard.tenderly.co/tx/1/0xbe082dcc8ae59868f5b2330173902bb88c6643b5c2fdf0d8a9f43d03dbca0c36/debugger?trace=0.1). Notice that require involves `amounts[amounts.length - 1]`.

  <img alt="" />

  ### Evaluate the expression

  To get the value of this expression, you can use Evaluate:

  1. Make sure debugger is at the line of revert,
  2. Paste the expression \`amounts\[amounts.length - 1],
  3. press "Evaluate" button.

  The value is:
  The value is `1029855063181377015`.

  <img alt="" />

  ### Obtain the value from call information

  You can also extract the value of the expression in question by analyzing the function that produced the value:

  1. Move the debugger to the [`getAmountsOut`](https://dashboard.tenderly.co/tx/1/0xbe082dcc8ae59868f5b2330173902bb88c6643b5c2fdf0d8a9f43d03dbca0c36/debugger?trace=0.0) from the Execution trace on the left
  2. Find the `output` in the lower pane
  3. Since the expression `amounts[amounts.length - 1]` gets the last element of the array, we conclude that the value in question is `1029855063181377015`.

  <img alt="" />

  ### Potential solution

  This transaction would have succeeded if the value of `amountOutMin` was `1029855063181377015`.

  ### Verifying the solution

  To verify the solution, click the "Re-Simulate" button:

  1. Paste the value `1029855063181377015` to the second argument
  2. Click **Simulate**.

  The simulation has succeeded, meaning we found the correct argument value.

  <Info>
    Swap transactions are time-sensitive, they take into account the `block.timestamp` value.
    Simulations are by default executed on the original block and at the original timestamp.
    Only if you need custom block and timestamp values, you can use block header overrides for that purpose.
  </Info>
</Steps>


# Investigating a Hack (Cover Protocol)
Source: https://docs.tenderly.co/debugger/guides/hack-investigation

Analyze the Cover Protocol exploit in Tenderly by importing the contract, simulating the deposit, and tracing the cache bug in Debugger.

This example will showcase briefly how Tenderly can be used to analyze and even prevent hacks such as what happened with the [Cover Protocol](https://twitter.com/CoverProtocol).

The Cover Protocol got hacked because of the inability of code to update the cache in storage. This could have potentially been prevented by using an [**setting up alerts on important functions**](/monitoring/alerts/introduction) like deposit/withdrawal and particular state changes to prevent an attack.

In order to manually analyze the hack, we need to [**import the smart contract**](/developer-explorer/contracts) `Blacksmith` in which the vulnerability was found. If you know the exact name of the affected protocol or vulnerable contract you can also search for it directly.

![](https://lh3.googleusercontent.com/BVJobjB-JHrSGyTHuC7v3cPLBbaUnNJH3pda8uJrHU2qCSV6ms-84BC614vdozpemjg5FO8J4cu-B9RjTTLfYWRQyBneYVBbLy5fv5_OQA1N-svrza9ZF6Q6xsUA5o37YyYPnaP4)

<Warning>
  Note - you can only search for contracts which have been publicly verified on Tenderly or
  Etherscan. [**Read more about how to verify a contract on Tenderly right
  here.**](/contract-verification/overview)
</Warning>

If the contract is not publicly verified, you can do it yourself in order to be able to use it with Tenderly. If the project is open-source (like Cover), you can go to the project's [GitHub repo](https://github.com/CoverProtocol/cover-token-mining), find the contract you want to use (and its source code) and verify it yourself.

![](https://lh4.googleusercontent.com/vWVW6dAj1J6d83juyoXZ3cR9DTMmVgXu9PYHUUL4_Mv5LRAJ8wnXSckv72tEv-C96zOeutweZaLAx4OEaVBon1PkZOGMBmPwKLlTBJuPEAaPkZSDjwwtip3Kzx1d8B-UzYA7wRkE)

![](https://lh4.googleusercontent.com/C6BHcXHp8NHQmkb7kJP2vwNDi86mVgb-GyHb5Fp9OtddF3anpTTCdkERiNXAGYXnuhippPJKPuxf6a9RW1GIu91nECQWoV033C7gg1GHnz5tsoEP3BkkcMMiAHDCUspbmMz-BVUf)

Now that we have the contract we want to import to Tenderly, go to your Dashboard and click on the **Contracts** tab on the left, and then on the **Add Contract** button in the top right:

<img alt="" />

You can either upload and verify the contract's code through your Dashboard, or via the CLI [\[more info here\]](/contract-verification/overview):

<img alt="" />

<img alt="" />

Now, after importing and verifying the contract let us analyze the hack itself. We know that the bug existed in the deposit function's cache so we simulate that function. As we can see on the screenshot below, after execution it failed with the `Blacksmith: pool does not exist`.

![](https://lh5.googleusercontent.com/JlFsuawkRAxjCnd7sHefFA9n-WpUOPMWIlnXb_IBOrdvQI8OFvRvTsWPH02p9qy1tmqDf8HnwVgJM2hK3x2iAmvWXNLj-qNLqDzyUmBBG4nbRAmkjfkpRGkh8748cFr052jEoaBL)

Now, let's open this error in Tenderly Debugger. On line 118 we see `Pool memory pool = pools[_lpToken];` in the deposit function where data is cached, and later updated on line 125 where we see `_claimCoverRewards(pool, miner);`

The contract used the cache data because the data itself stayed in memory; that’s why later the contract calculated the function using that data. Cache was not updated which resulted in this hack:

```solidity title="example.sol" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
miner.rewardWriteoff = miner.amount.mul(pool.accRewardsPerToken).div(CAL_MULTIPLIER);
```

```solidity title="example.sol" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
miner.bonusWriteoff = miner.amount.mul(bonusToken.accBonusPerToken).div(CAL_MULTIPLIER);
```

![](https://lh3.googleusercontent.com/6jPAgWs9ZLNkM7PzW_g-0kR0Wy5kYMtk80huWk_KzsfpF7WBTrhE3VIWvPTI0bwVQmR25TLsARV-Ea3f2mK_kwcYESQEjxKebHv19YbNEuG-Jr0MJQ4t_LsxV-Q83rB_SC1NGV1v)

```solidity title="example.sol" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function deposit(address _lpToken, uint256 _amount) external override {
    require(block.timestamp >= START_TIME, "Blacksmith: not started");
    require(_amount > 0, "Blacksmith: amount is 0");

    Pool memory pool = pools[_lpToken];

    require(pool.lastUpdatedAt > 0, "Blacksmith: pool does not exists");
    require(IERC20(_lpToken).balanceOf(msg.sender) >= _amount, "Blacksmith: insufficient balance");

    updatePool(_lpToken);

    Miner storage miner = miners[_lpToken][msg.sender];
    BonusToken memory bonusToken = bonusTokens[_lpToken];

    _claimCoverRewards(pool, miner);
    _claimBonus(bonusToken, miner);

    miner.amount = miner.amount.add(_amount);

    // update writeoff to match current acc rewards/bonus per token
    miner.rewardWriteoff = miner.amount.mul(pool.accRewardsPerToken).div(CAL_MULTIPLIER);
    miner.bonusWriteoff = miner.amount.mul(bonusToken.accBonusPerToken).div(CAL_MULTIPLIER);

    IERC20(_lpToken).safeTransferFrom(msg.sender, address(this), _amount);
    emit Deposit(msg.sender, _lpToken, _amount);
}

```

* A new pool was approved for liquidity mining, merely hours before the hack. This pool is perfectly normal but since it was new, the blacksmith contract didn’t have any LP token of this pool.
* The attacker deposited some tokens of this pool into the Blacksmith contract.
* The Blacksmith contract keeps track of rewards on a per-token basis. If a lot of tokens are locked, the per-token reward will be small. If very few tokens are locked, the per-token reward will be large. The relevant variable is called `accRewardsPerToken` and is calculated as `totalPoolRewards / totalTokenBalance`.
* The attacker then withdrew almost all of the LP tokens from the Blacksmith contract, reducing the `totalTokenBalance` amount to almost zero.
* The attacker then deposited some tokens of this pool again into the Blacksmith contract. This is where the bug showed its true colors. Since the `totalTokenBalance` was reduced a lot in the previous transaction, the newly calculated `accRewardsPerToken` shot up. The contract uses `rewardWriteoff` to keep the effect of `accRewardsPerToken` in check. However, due to the bug, the old (small) value of `accRewardsPerToken` was used when calculating the `rewardWriteoff` value. Due to this, the large value of `accRewardsPerToken` remained unchecked.
* The attacker then withdrew their rewards. Since there was a large, unchecked value in `accRewardsPerToken`, the total reward paid out of the system got inflated and the **contract ended up minting 40,796,131,214,802,500,000 COVER tokens**.

<Note>
  Thanks to Mudit Gupta for the last part of this hack breakdown - [read more about it on his
  blog](https://mudit.blog/cover-protocol-hack-analysis-tokens-minted-exploit/) :)
</Note>


# How to Use Tenderly Debugger
Source: https://docs.tenderly.co/debugger/overview

Step through transaction execution line by line, inspect state changes, and identify the exact revert point in any smart contract with Tenderly Debugger.

The Tenderly Debugger steps through an EVM transaction's execution, one call and source line at a time, exposing the execution trace, stack, contract state, and the exact point where a transaction reverts. Use it to find why a transaction failed, inspect contract state at any step, and replay a transaction against verified Solidity source.

Watch this quick video to learn the basics of using Debugger and follow the quickstart below for a detailed feature walkthrough.

[Watch on Loom →](https://www.loom.com/share/09413e8a867f4ddeaa41a5080d771895?sid=b8f60cda-fcb8-401b-ba9a-8bb69630fe9a)

## Debugger quickstart

To use the Debugger, you need to start from a specific transaction. Try this [example transaction](https://dashboard.tenderly.co/tx/0x1696cfc031695003b8a58f0379c7f111b34c7612a67681354dc57cb5853c5c63/debugger?trace=0.2.6.21.1\&pk_vid=4405d1610803d9751776942168287f02).

1. Go to the **Transactions** tab on the left side or search for a transaction hash in the top Explorer bar.
2. Click the **Debugger** button located at the top right.

The Debugger interface is comprised of four main panels:

<img alt="Debugger panels" />

* **Execution trace** (top left): Displays the sequence of calls made during the transaction.
* **Smart contract source code** (top right): Shows the code of the contract being interacted with.
* **Stack trace** (bottom left): Lists the methods called leading up to the current function.
* **Call information** (bottom right): Provides detailed info about the current call.

## Execution trace

The **Execution Trace** section lets you see every call made during a transaction's life cycle. A handy toggle allows you to filter the view between the full trace or just the `CALL`s and `DELEGATECALL`s.

You can also leave comments directly on any part of the trace, useful for collaboration or personal notes.

<img alt="Debugger panels" />

## Stack trace

The **Stack Trace** offers a look at the methods that have been invoked leading up to the active function call, giving you a clearer picture of the transaction's flow.

## Decoding call information

Here, you get decoded details about the current call in the transaction's execution trace in JSON format. This includes:

* Invoked function's name
* Opcodes (`JUMP`, `CALL`, `DELEGATECALL`, `STATICCALL`, `CREATE2`, `CREATE`, `REVERT`, `JUMPDEST`)
* Contract and caller addresses, plus the caller's balance
* Decoded inputs and outputs
* Gas usage stats, showing total gas used, gas consumed by the current function, and remaining gas

## Navigating through the call trace

Jumping through the call trace and code lines is straightforward with the Debugger's navigation buttons.

**Next/Previous** moves you through the call trace, while **Step Up** and **Step Over** help you navigate the stack trace and call levels.

<img alt="Debugger panels" />

## Evaluating expressions

The **Evaluate** feature allows you to test out expressions directly within the Debugger. This is perfect for checking global variables, contract variables, function arguments, and local variables.

<img alt="Eval modal" />

The current version of **Evaluate** supports expressions in the form of arrays and structs. Tuples are not supported so they can't be evaluated.

<img alt="Debugger + expressions visible for Eval" />


# War Room Aid Kit
Source: https://docs.tenderly.co/debugger/war-room-aid-kit

Use Tenderly's Call Trace, Expression Evaluation, and annotation system to diagnose hacks and critical incidents faster with your team.

Diagnosing Web3 errors is complex and hard, that’s why development teams have adopted War Rooms in response to high-stakes errors and hacks. With Tenderly you can now adopt a War Room procedure and be ready when the problem arises.

**Detect issues faster**

If the number of contracts in the transaction is greater than 30 then [**Call Trace**](/debugger/overview) will be automatically triggered. You can switch it yourself if you’re only interested in seeing external calls that are usually crucial for the attack. Use [**Expression Evaluation**](/debugger/evaluate-expression) to better understand the whole context of the transaction and simplify debugging process.

**Collaborate and prioritize**

With the new annotation system, you can leave comments on the exact line of code you think caused the issue. Annotations can be used to make team collaboration more efficient or to leave a note for yourself so you don’t forget it later. You can also set a priority for traces you want inspected first.

### Tenderly in War Rooms

Get familiar with the features that can help you understand and debug your code faster and collaborate with your team:

<Card title="Tenderly War Rooms: The Aid Kit You Need in Time-Sensitive Scenarios" href="" />

### Anatomy of a Good Emergency Procedure

We tapped into Yearn Finance’s best-in-class procedures to give you an overview of the War Room best practice:

<Card title="The Anatomy of a Good Emergency Procedure [Yearn Finance Case Study]" href="" />


# Aave V3
Source: https://docs.tenderly.co/defi-modules/aave

Protocol-native pages for Aave V3 reserves: reserve header metrics, APY charts, classified transactions, and Allocation, Performance, and Risk views.

When you navigate to a recognized Aave V3 reserve, Tenderly renders a reserve page instead of the generic contract view. The page identifies the reserve by protocol, reserve name, and version (for example, Aave USDC Reserve V3), and links to the underlying token.

<Card title="Open a live Aave V3 pool in Tenderly Console" href="https://dashboard.tenderly.co/contract/mainnet/0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2/protocol-overview?view=market" />

## Reserve header

The header presents the following reserve metrics:

| Metric         | Description                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------- |
| Total supplied | Amount supplied against the supply cap, in dollars and tokens, with the utilization percentage |
| Supply APY     | Current annualized yield for suppliers                                                         |
| Total borrowed | Amount borrowed against the borrow cap, with the utilization percentage                        |
| Borrow APY     | Current annualized rate paid by borrowers                                                      |
| Reserve factor | Share of interest routed to the Aave treasury                                                  |

Next to the metrics, a chart plots **Supply APY** or **Borrow APY** over a selectable time range, with the average APY for the selected window.

## Transactions

The Transactions tab lists recent reserve activity. Each transaction is classified with an Aave action label: **Supply**, **Borrow**, **Repay**, or **Withdraw**. The table shows the transaction hash, the user wallet, the action, the time, and the amount in both tokens and dollars.

<img alt="Aave V3 USDC reserve showing total supplied, supply and borrow APY, reserve factor, the supply APY chart, and transactions classified as Supply, Borrow, Repay, and Withdraw" />

## Protocol overview

The Protocol overview tab is split into three views: Allocation, Performance, and Risk.

### Allocation

The Allocation view renders a **Reserve backing** table with the reserve, its backing value, the supply cap, the borrow cap, and the average variable borrow APY. A Backing chart below the table plots the backing value over time.

<img alt="Aave V3 reserve Allocation view showing the Reserve backing table with backing value, supply cap, borrow cap, and average variable borrow APY" />

### Performance

The Performance view plots the **Liquidity index**, the cumulative interest accrued by the reserve since inception. Below the chart, a Returns panel lists the instant supply APY, instant borrow APY, and the trailing 7-day and 30-day APY values, and a Fees panel shows the reserve factor.

<img alt="Aave V3 reserve Performance view showing the liquidity index chart, instant and trailing APY values, and the reserve factor" />

### Risk

The Risk view surfaces the reserve's governance and access control state:

* **Pool roles**: the ACL Admin, ACL Manager, and Emergency Admin addresses.
* **Risk curation**: the Risk Admin and Risk Stewards addresses, where configured.
* **Access**: a table mapping each adjustable parameter (such as the supply cap and borrow cap) to the role that can change it.

<img alt="Aave V3 reserve Risk view showing pool roles, risk curation addresses, and the access table mapping parameters to the roles that control them" />


# Morpho
Source: https://docs.tenderly.co/defi-modules/morpho

Protocol-native pages for Morpho vaults. Vault metrics, deposit and share price charts, classified transactions, and Allocation, Performance, Risk views.

When you navigate to a recognized Morpho vault, Tenderly renders a vault page instead of the generic contract view. The page identifies the vault by protocol, vault name, and version (for example, Morpho Steakhouse Prime USDC V2), and links to the underlying token.

<Card title="Open a live Morpho vault in Tenderly Console" href="https://dashboard.tenderly.co/contract/mainnet/0xbeef088055857739C12CD3765F20b7679Def0f51/protocol-overview?view=market" />

## Vault header

The header presents the following vault metrics:

| Metric             | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| Total Deposits     | Dollar and token value deposited in the vault               |
| Liquidity          | Value available for immediate withdrawal                    |
| Exposure           | Number of markets the vault allocates to, with market icons |
| Net APY            | Current annualized yield net of fees                        |
| Pending governance | Count of pending governance actions on the vault            |

Next to the metrics, a chart plots the vault over time with three views: **Deposits**, **Net APY**, and **Share Price**. A denomination toggle switches values between the underlying token and USD, and a time range selector adjusts the window.

## Transactions

The Transactions tab lists recent vault activity. Each transaction is classified with a vault action label: **Deposit** or **Withdraw**. The table shows the transaction hash, the user wallet, the action, the time, and the amount in both tokens and dollars.

<img alt="Morpho vault page showing the protocol badge, total deposits, liquidity, market exposure, net APY, pending governance, and transactions classified as Deposit and Withdraw" />

## Protocol overview

The Protocol overview tab is split into four views: Allocation, Performance, Risk, and User distribution.

### Allocation

The Allocation view renders an **Exposure** table listing every market the vault allocates to. For each market the table shows the allocation value, market liquidity, underlying liquidity, utilization, the absolute and relative caps, and the market APY. A chart below the table plots allocation over time, toggleable between absolute value and percentage.

<img alt="Morpho vault Allocation view showing the Exposure table with per-market allocation, liquidity, utilization, caps, and APY" />

### Performance

The Performance view plots the **Position unit price**, the value of one vault share in the underlying token, with the current share price stated above the chart. Below it, a Returns panel lists the instant APY and the trailing 7-day, 30-day, and 90-day APY values, and a Fees panel shows the vault's performance fee and management fee.

<img alt="Morpho vault Performance view showing the position unit price chart, instant and trailing APY values, and the performance and management fees" />

### Risk

The Risk view surfaces the vault's governance and timelock configuration:

* **Vault roles**: the Owner, Curator, and Guardian addresses.
* **Risk curation**: the allocator addresses authorized to rebalance the vault.
* **Timelocks**: a table mapping each governance function (such as `addAdapter` or `removeAdapter`) to its timelock duration, including functions with no timelock and functions that have been abdicated.

<img alt="Morpho vault Risk view showing vault roles, allocator addresses, and the timelocks table mapping governance functions to their durations" />

### User distribution

The User distribution view lists the vault's depositors. For each wallet the table shows the deposit amount in the underlying token and its percentage of total deposits. Wallet addresses link to their wallet pages.

<img alt="Morpho vault User distribution view listing depositor wallets with deposit amounts and percentage of total deposits" />


# DeFi Modules
Source: https://docs.tenderly.co/defi-modules/overview

Protocol-aware UI surfaces Tenderly renders automatically for recognized addresses, covering Protocol overview, Wallet 360, and transaction classification.

DeFi Modules are protocol-specific UI surfaces that Tenderly renders when an address or transaction is recognized as belonging to a supported protocol. Instead of displaying raw ABI calls, hex-encoded event logs, and storage slots, Tenderly resolves the protocol context and presents the data using that protocol's own terminology, structure, and metrics.

Recognition is automatic and requires no configuration. When you navigate to a supported address, the module activates and the protocol-native view replaces the generic contract view. The underlying raw data remains accessible on the same page.

<img alt="Morpho vault page showing the protocol badge, total deposits, liquidity, market exposure, net APY, pending governance, and classified transactions" />

***

## Surfaces

Each supported protocol activates up to three surfaces. All three surfaces are driven by the same underlying module definition, so data is consistent across views.

### Protocol overview

A dedicated page rendered for each recognized pool, vault, or reserve. The page includes a protocol badge identifying the contract, a set of protocol-native metrics in the header (such as total supplied, borrow APY, utilization, and reserve factor), a time-series chart for the primary metric, and a list of related entities. Governance state and pending proposals are surfaced inline where applicable.

The Protocol overview tab is available alongside the standard Transactions, Relationships, and Alerts tabs on any recognized address page.

<img alt="Aave V3 USDC reserve showing total supplied, supply and borrow APY, reserve factor, the supply APY chart, and classified transactions" />

### Wallet 360

A wallet-scoped view of positions held in a supported protocol. Accessed via the Wallet 360 tab on a protocol page, it shows the wallet's balance, deposits, and borrows over time as a chart, and lists each open position with its token, deposit amount, current APY, health factor after the last transaction, earned interest, collateral status, and claimable rewards.

To view Wallet 360 data, use the Impersonate wallet function to select or enter a wallet address. Wallet 360 data reflects the on-chain state of that wallet's positions within the current protocol.

Coverage varies by protocol: Aave V3 shows deposit and borrow positions with the health factor after the last transaction, Uniswap V3 shows directly held LP positions via the NFT Position Manager, and Morpho shows borrow and lend positions.

<img alt="Wallet 360 tab on the Aave V3 USDC reserve showing balance, deposits, borrows chart, and open positions table" />

### Transaction classification

Transactions involving a supported protocol are classified and labeled in the transaction list and transaction detail view. Each transaction is assigned a human-readable action type (for example: Supply, Borrow, Repay, and Withdraw on Aave, Deposit and Withdraw on Morpho, or Buy and Sell labels for Uniswap swaps) and attributed to the correct protocol. Multi-step transactions that touch multiple contracts are grouped under a single classified action. Raw decoded event logs remain visible beneath the classification.

<img alt="Recent activity on the Uniswap V3 WBTC/ETH pool with each transaction classified as Buy WBTC or Sell WBTC, alongside the wallet, USD value, and token amounts" />

***

## Supported protocols

Each protocol page documents the module in detail: the header metrics, the charts, and what each tab renders.

<CardGroup>
  <Card title="Aave V3" href="/defi-modules/aave">
    Reserve pages with supply and borrow metrics, APY charts, classified transactions, and Allocation, Performance, and Risk views.
  </Card>

  <Card title="Uniswap V3" href="/defi-modules/uniswap">
    Pool pages with price, volume, and liquidity charts, classified Buy and Sell swaps, and market depth metrics.
  </Card>

  <Card title="Morpho" href="/defi-modules/morpho">
    Vault pages with deposit and share price charts, market allocation, timelocks, and user distribution.
  </Card>
</CardGroup>

***

## Virtual Environments

DeFi Modules are also active on [Virtual Environments](/virtual-environments/overview). A Virtual Environment forked from a network where a protocol is supported inherits the live protocol state, and the same module surfaces are available within the Virtual Environment.


# Uniswap V3
Source: https://docs.tenderly.co/defi-modules/uniswap

Protocol-native pages for Uniswap V3 pools: header metrics, price, volume, and liquidity charts, classified swap transactions, and pool quality metrics.

When you navigate to a Uniswap V3 pool contract on a supported network, Tenderly recognizes the address and renders a pool page instead of the generic contract view. The page identifies the pool by protocol, token pair, and version, and presents pool data using Uniswap terminology.

<Card title="Open a live Uniswap pool in Tenderly Console" href="https://dashboard.tenderly.co/contract/mainnet/0x4585fe77225b41b697c938b018e2ac67ac5a20c0/protocol-overview" />

## Pool header

The header identifies the contract as a Uniswap V3 pool and shows the token pair (for example, WBTC / ETH), the protocol version tag, the network, and the pool address. A toggle next to the pair name inverts the token pair display, which flips the quote direction of the price chart and pair rate.

The header presents the following pool metrics:

| Metric           | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| Fee APR (24H)    | Annualized return from trading fees over the last 24 hours     |
| Active liquidity | Dollar value of liquidity active at the current price          |
| TVL              | Total dollar value locked in the pool                          |
| Pool balances    | Current holdings of each token in the pair, with a ratio bar   |
| Volume (24H)     | Dollar volume traded in the last 24 hours, with the swap count |
| Fees (24H)       | Dollar value of fees generated in the last 24 hours            |

Next to the metrics, a chart plots the pool over time with three views: **Price** (the pair exchange rate, with the current rate and percentage change), **Volume**, and **Liquidity**. A time range selector adjusts the window from one day up to all time.

## Transactions

The Transactions tab lists recent pool activity. Each swap is classified with a directional label, **Buy** or **Sell**, expressed against the base token (for example, Buy WBTC or Sell WBTC), instead of a raw `swap` call signature.

The table shows the transaction hash, the wallet that initiated the swap, the classification label, the time, the USD value, and the amount of each token in the pair. Transaction hashes link to the transaction detail page, and wallet addresses link to the wallet page.

<img alt="Recent activity on a Uniswap V3 WBTC/ETH pool with each transaction classified as Buy WBTC or Sell WBTC, alongside the wallet, USD value, and token amounts" />

## Protocol overview

The Protocol overview tab presents pool quality and market depth metrics:

| Metric             | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| Spot vs TWAP       | Deviation between the spot price and the time-weighted average price |
| Oracle cardinality | Number of observation slots in the pool's price oracle               |
| Swaps (24H)        | Swap count over the last 24 hours                                    |
| Pool age           | Time since pool creation                                             |

Two market depth panels quantify how the pool absorbs trades:

* **Pressure to move price ±1%**: the dollar value of buying or selling required to move the pool price up or down by one percent.
* **Price impact at standard sizes**: the percentage price impact of trades at $10K, $100K, $1M, and $10M.

<img alt="Uniswap V3 pool Protocol overview tab showing spot vs TWAP, oracle cardinality, swap count, pool age, pressure to move price, and price impact at standard sizes" />


# Smart Contracts
Source: https://docs.tenderly.co/developer-explorer/contracts

Add contracts to a Tenderly project, inspect their source, transactions, and state, and detect proxies automatically.

Learn how to add a smart contract to a project and keep track of its transactions in the Dashboard. When you add a contract, you'll see a list of all historical transactions (direct and internal) linked to that contract.

<img alt="Contract page header info and tabs" />

## How to add a contract to a project

1. Navigate to **Contracts** in the side menu.
2. Click **Add Contract**.
3. Enter the contract address, select its deployment network, assign a name, and click **Add Contract**.

<img alt="Adding a contract" />

Try adding one of these contracts to your project to get started. Open the contract in Tenderly, click the **Add to Project** button and add it to an existing project. Learn [how to create projects in Tenderly here](/platform/account/projects/overview).

* [Uniswap Router](https://www.tdly.co/contract/1/0x1cf9cbe70a84137c696f98587a9b06f7fa2b71b4): `0x1cf9cbe70a84137c696f98587a9b06f7fa2b71b4`
* [veCurveVault proxy](https://www.tdly.co/contract/1/0xc5bddf9843308380375a611c18b50fb9341f502a): `0xc5bddf9843308380375a611c18b50fb9341f502a`

## Looking up any verified contract

The Dashboard's search functionality allows you to locate any verified contract deployed on any of the [95 supported networks](/platform/supported-networks), whether or not it's in one of your projects.

<img alt="Searching for a contract" />

1. Paste the contract's address or name in the top menu search bar.
2. Select the contract from the search results.

<img alt="Search results dropdown" />

This opens the same contract details page described below, reached via a `/contract/<network>/<address>` URL instead of a project path. A handful of project-only elements are missing since the contract isn't in a project yet: there's no **Tags** field, the `...` menu only has **View in Public Explorer**, and the header shows **Add to Project** instead of **Convert to Proxy**.

<img alt="Public contract lookup header" />

To add the contract to a project, click **Add to Project** and choose your target project.

## Contract details

Opening a contract, whether from your project's **Contracts** page or from a lookup, shows a header info panel followed by six tabs: **Transactions**, **Simulations**, **Source code**, **Read/Write**, **Events**, and **Multichain assets**.

The header info panel shows the network, contract type (`Contract` or `Proxy Contract`), ETH balance and value, deployment address and transaction, deployment timestamp, tags, verification status and type, optimizations and optimization runs, Solidity version, compiler, and EVM version. The `...` menu next to the contract name has **View in Public Explorer**, [**Hide from transaction listing**](#hide-a-contract-from-the-transaction-listing), and **Remove contract**.

<img alt="Contract header menu" />

### Transactions

Lists every direct and internal transaction involving the contract, with the same filters as a wallet's transaction list: **All**, **Direct**, **Internal**, **Token asset transfers**, and **NFT asset transfers**, plus Columns and Filters controls.

<img alt="Transactions tab with filters" />

### Simulations

Shows the contract's simulated transaction history, and lets you launch a new [simulation](/simulator-ui/overview) directly against the contract.

### Source code

Shows the verified source across six sub-tabs: **Source Code**, **Compiler Settings**, **Contract ABI**, **Contract Creation Code**, **Deployed Bytecode**, and **Contract Source Map**.

<img alt="Source code tab with sub-tabs" />

### Read/Write

Lists every contract function, grouped into **Read** and **Write** sub-tabs, with a Connect Wallet button, a function search box, and per-function actions: run it, copy as cURL, read at a specific block, open in Simulator, share, or view in source.

<img alt="Read/Write tab" />

Proxy contracts get two additional sub-tabs, **Read as Proxy** and **Write as Proxy**, which call the functions through the proxy's delegated implementation. See [Proxy contracts](#proxy-contracts) below.

### Events

Lists decoded events emitted by the contract, with an event type filter, a block range filter, a "Hide zero values" switch, and an expand-all option.

### Multichain assets

Shows the contract's token and NFT balances across networks, with Token/NFT sub-tabs, a group-by option, a "Hide zero balances" switch, and a search box.

<img alt="Multichain assets tab" />

## Adding tags to contracts

When working with multiple contracts, you need a way to keep them organized. This is where tags come in handy. You can add a tag to a contract by clicking the **Add Tag** link.

Tags also enable you to monitor multiple contracts or wallets grouped under a single tag using Alerts.

<img alt="Tagging contracts" />

## Monitoring contracts with Alerts

Click **Create Alert** from a contract's page to set up an [Alert](/monitoring/alerts/introduction) for it. See the [Alerting Quickstart Guide](/monitoring/alerts/tutorials/quickstart) for the full setup flow and [Alert Types, Targets, and Parameters](/monitoring/alerts/types) for the available triggers.

Alerts are evaluated only for transactions involving your project's contracts and wallets, so the address an Alert targets must be added to the project first.

## Hide a contract from the transaction listing

Every contract you add to a project has its transactions included in the project-wide [Transactions view](/developer-explorer/transaction-listing). For high-traffic contracts added only as Alert targets, such as an ERC-20 token contract you monitor for transfers, this can make the Transactions view noisy.

To exclude a contract's transactions from the project-wide view, open the contract, click the `...` menu in the upper right corner, and select **Hide from transaction listing**. To include it again, select **Show in transaction listing** from the same menu. You can also hide or show multiple contracts at once by selecting them on the project's **Contracts** page and using the **Disable transaction listing** and **Enable transaction listing** toolbar actions.

Hiding a contract only affects the project-wide Transactions view:

* The contract's own **Transactions** tab still lists all of its transactions.
* [Alerts](/monitoring/alerts/introduction) and [Web3 Actions](/monitoring/web3-actions/introduction) targeting the contract keep working; hiding has no effect on monitoring.

Wallets have the same option, labeled **Hide Wallet** in the wallet's `...` menu (see [Wallets](/developer-explorer/wallets)).

## Proxy contracts

Tenderly detects [EIP-1967](https://eips.ethereum.org/EIPS/eip-1967) and [EIP-1167](https://eips.ethereum.org/EIPS/eip-1167) proxies automatically. A detected proxy shows `Type: Proxy Contract` and an **Implementation** field with the current delegate address.

<img alt="Proxy contract header, single implementation" />

When Tenderly has recorded more than one implementation address over time, an icon next to the Implementation field opens a **Proxy Contract Implementations** dialog listing the current implementation followed by prior ones, most recent first.

<img alt="Proxy contract header with implementation history icon" />

<img alt="Proxy Contract Implementations dialog" />

Proxy contracts also get **Read as Proxy** and **Write as Proxy** sub-tabs on the Read/Write tab, calling functions through the delegated implementation instead of the proxy itself.

<img alt="Read as Proxy / Write as Proxy tabs" />

### Non-standard proxy implementations

For non-standard solutions, you'll need to manually convert the contract to a proxy.

Click the **Convert to Proxy** button on the top right of the contract's page.

<img alt="Contract proxy button" />

**Set the storage slot** containing the implementation address, or **pick a view function** that returns the implementation address.

<img alt="Contract proxy modal" />


# Fund Flow
Source: https://docs.tenderly.co/developer-explorer/inspect-transaction/fund-flow

Visualize token transfers as an interactive graph. Trace asset paths, filter by token or address, inspect net positions, and jump to the execution trace.

The **Fund Flow** tab on any transaction page renders all token transfers as an interactive directed graph. You can follow the entire flow of token transfers within a transaction, from the first to the last step. Inspect which addresses (represented as nodes) were involved, apply filters to focus on an exact token path, and jump straight to a function call from the graph.

Open a transaction in the [Tenderly Explorer](/developer-explorer/overview) and click the **Fund Flow** tab to see the graph.

<video>
  <source type="video/mp4" />
</video>

Fund Flow supports all standard transfer types:

| Transfer type         | Source                                    |
| --------------------- | ----------------------------------------- |
| ERC-20                | `Transfer(from, to, value)` event         |
| ERC-721 (NFTs)        | `Transfer(from, to, tokenId)` event       |
| ERC-1155              | `TransferSingle` / `TransferBatch` events |
| Native ETH (external) | Transaction value field                   |
| Native ETH (internal) | Internal `CALL` with value > 0            |
| WETH wrap/unwrap      | `Deposit` / `Withdrawal` events           |

<Note>
  Fund Flow displays the same data as the [Tokens Transferred](/developer-explorer/inspect-transaction/overview#tokens-transferred) list, rendered as a graph. Use it when a transaction involves many intermediary hops and a visual layout makes the flow easier to follow.
</Note>

## Timeline navigation

The timeline bar at the bottom of the graph lets you step through transfers in execution order. Each step highlights the active transfer edge and the two addresses involved, building up a visual history as you advance.

* **Right arrow**: advance to the next transfer
* **Left arrow**: go back to the previous transfer
* Past transfers remain visible at reduced opacity, giving you the "story so far"

<video>
  <source type="video/mp4" />
</video>

## Address details and net positions

Click any node to open a side panel with:

* **Address identity**: type (EOA, contract, proxy), verification status, labels, and ENS name
* **Transfers**: every inflow and outflow involving that address within this transaction, each with its sequence number and counterparty
* **Net position**: the total balance change per token, converted to USD, so you can instantly see the balance of a particular address at the end of the transaction.

<video>
  <source type="video/mp4" />
</video>

### Label and color-code addresses

You can assign custom labels and colors to any address directly from the graph. Labels persist across your project workspace, so key contracts are recognizable in every transaction you inspect.

<video>
  <source type="video/mp4" />
</video>

## Jump to execution trace

Click any transfer edge and select **Jump to Trace** to open the exact function call in the [execution trace](/developer-explorer/inspect-transaction/overview#decoded-call-trace). The trace opens within the graph context so you can inspect the low-level call right away.

<video>
  <source type="video/mp4" />
</video>

## Search

Use the search bar to find any element in the graph by:

* Address (full or partial)
* Contract name or label
* Token symbol
* Transfer amount

Matches are highlighted in place and the graph auto-pans to center the result.

<video>
  <source type="video/mp4" />
</video>

## Filtering

Apply filters to isolate specific paths throughout the transaction:

| Filter            | Options                                                         |
| ----------------- | --------------------------------------------------------------- |
| **Token**         | Select specific tokens or token types (ERC-20, ERC-721, native) |
| **Address**       | Filter by specific address or address type (EOA, contract)      |
| **Transfer type** | Mint, burn, or transfer                                         |

<video>
  <source type="video/mp4" />
</video>

### Quick filter from the graph

Each transfer edge in the graph has an inline filter icon. Click it to instantly scope the view to that transfer's token and path, without opening the filter panel. This is the fastest way to isolate a specific token flow while exploring the graph.

When filters are active, the timeline applies to the scoped view, letting you trace specific addresses, tokens, and transfer types.

<video>
  <source type="video/mp4" />
</video>

## When to use Fund Flow

Fund Flow is most useful for transactions with complex token routing:

* **DEX swaps** routed through multiple pools or aggregators
* **Flash loans** where borrowed assets flow through several contracts before repayment
* **Arbitrage and MEV** transactions where spotting circular flows or sandwich patterns is critical
* **Multi-step DeFi** operations (e.g., borrow, swap, provide liquidity in a single transaction)
* **Security investigations** where you need to quickly identify which addresses gained or lost assets


# Transactions
Source: https://docs.tenderly.co/developer-explorer/inspect-transaction/overview

A guide to managing and analyzing transactions in the Tenderly Dashboard for development and monitoring.

Tenderly gives you the most detailed overview of the transaction execution details. For each transaction, Tenderly extracts the following data and more: General information, [Decoded call trace](#decoded-call-trace), [Tokens transferred](#tokens-transferred), [Fund Flow](#fund-flow), [Contracts involved](#involved-contracts), [State changes](#state-changes), [Emitted events](#emitted-events), [Gas used](#gas-used), and more.

[Watch on Loom →](https://www.loom.com/share/05325e45c232445b992214da8c6ba179?sid=e10e8812-874d-42ad-9def-ea47f8e6a13d)

From the transaction overview page, you can also access [Debugger](/debugger/overview) to dig deeper into the stack trace and smart contract source code. You can also use the [Simulator](/simulator-ui/overview) to modify the numerous transaction parameters and simulate the outcomes against the latest state of the network.

<img alt="Transaction Overview" />

## Decoded call trace

The decoded call trace panel allows you to inspect the various opcodes, including inputs and outputs: `JUMP`, `CALL`, `DELEGATECALL`, `STATICCALL`, `CREATE2`, `CREATE`, `REVERT`, `JUMPDEST`, `SLOAD`, and `SSTORE`. Learn more about EVM [opcodes here](https://ethervm.io/).

<img alt="Decoded Call Trace" />

You also have control over how much data about the call trace is displayed in the Dashboard. Toggle the **Full Trace**, **Storage Acces**s, and **Event Logs** to include and exclude information from the call trace.

### Search the call trace

You can search through the entire call trace to quickly find specific opcodes, functions, and variables. The search option also works if you need to find send and receiver addresses, Solidity files, and contracts.

<img alt="Search call trace" />

By default, the search matches across all categories. Use the dropdown next to the search field to scope the search to a single category: **OpCode**, **From**, **To**, **Function**, **File**, or **Contract**. Click a search result to jump to the matching line in the call trace and view the surrounding source code.

<img alt="Trace search categories" />

### Storage access

Click the **Storage Access** toggle to include the `SLOAD` and `SSTORE` opcodes, the storage slot accessed, and any changes in value in the call trace.

<img alt="Storage access" />

### Event logs

Toggle the **Events Log** option to include the log opcodes `log0` to `log4` in the call trace. Enabling this option will display the events that have happened in the transaction.

<img alt="Event logs" />

### Prioritization

When inspecting the call trace, you might want to set the **priority for individual elements** to **High**, **Medium**, or **Low**. Hover over any element in the call trace and click on the line graph icon to set or remove the priority.

<img alt="Call trace priority" />

The prioritization feature is helpful when you notice a problematic call in the trace and want to alert your team to investigate.

To leave comments on individual trace elements, open the transaction in [Debugger](/debugger/overview): see [Commenting & Prioritizing Traces](/debugger/commenting).

## Tokens transferred

The **Tokens Transfers** panel shows all the asset transfers that happened with the transaction, including balance and asset changes converted into dollars using CoinGecko data.

<img alt="Asset Changes" />

## Fund Flow

The **Fund Flow** tab visualizes all token transfers as an interactive directed graph. Each address is a node, each transfer is an edge, and the layout shows the complete path assets took during execution. Use it to trace multi-hop swaps, flash loans, or any transaction where a flat transfer list is hard to follow.

<Card title="Fund Flow" href="" />

## Involved contracts

The **Contracts** tab contains a list of all the contracts that were involved in the transaction execution. Click on a specific contract to inspect its source code.

<img alt="Involved Contracts" />

## Emitted events

The **Events** tab lists all events that happened as a result of the transaction. This is the same data as what you see when the Events Logs toggle is turned on in the call trace. The format of the data displayed is different. If the contract is verified, you'll see decoded data, but raw data is also available.

<img alt="Emitted Events" />

## State changes

The **State** tab shows all events or variables that have in some way altered the state of the blockchain. This includes old and new values. All the data is decoded but you can also view the raw state changes.

<img alt="State Changes" />

<Note>
  You can get the data about state changes via RPC. Learn more about the
  [`tenderly_trace`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_traceTransaction),
  [`tenderly_simulate`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction) and
  [`tenderly_simulateBundle`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateBundle) RPC methods.
</Note>

## Gas Profiler

The **Gas Profiler** tab provides a visual way to see how, where, and how much gas was used to execute a transaction. This data is displayed in the form of a flame chart with details about gas usage broken down by function and opcode.

<img alt="Gas Profiler" />

You can click on any of the functions or opcodes to dig deeper into how gas was used.

Click on **View in Debugger** when you're ready to start debugging problematic functions and optimizing how your smart contract consumes gas. The Gas Profiler gives you insights into gas used and total gas used.

Check out this detailed guide to learn how to use Gas Profiler and how gas consumption is calculated:

<Card title="How to Use Gas Profiler" href="" />


# Developer Explorer
Source: https://docs.tenderly.co/developer-explorer/overview

Inspect and debug contracts, wallets, and transactions across all Tenderly-supported networks with Developer Explorer tools.

Developer Explorer is a suite of Web3 development tools that allow you to inspect and debug transactions coming from any contract or wallet. These tools are available across all the [networks supported on Tenderly](/platform/supported-networks).

<CardGroup>
  <Card title="Transaction Listing" href="/developer-explorer/transaction-listing">
    View all the transactions coming from your contracts and wallets in a unified list.
  </Card>

  <Card title="Inspect Transaction" href="/developer-explorer/inspect-transaction/overview">
    Analyze transaction details, call trace, state changes, events, and more.
  </Card>

  <Card title="Debugger" href="/debugger/overview">
    Identify and fix smart contract issues efficiently with a visual debugging tool.
  </Card>

  <Card title="Gas Profiler" href="/debugger/gas-profiler">
    Examine contract gas usage by function and opcode visually with a flame chart.
  </Card>

  <Card title="Simulator UI" href="/simulator-ui/overview">
    Test transaction outcomes by adjusting parameters and simulating results.
  </Card>

  <Card title="Alerts" href="/monitoring/alerts/introduction">
    Receive real-time notifications about events on your contracts or wallets.
  </Card>
</CardGroup>

## Getting started with Developer Explorer

<img alt="Transaction Overview" />

To unlock the power of Developer Explorer, you first need to add a contract or wallet to a Tenderly project. Start with these guides to learn [how to add and manage contracts](/developer-explorer/contracts) and [how to add and manage wallets](/developer-explorer/wallets).

Tenderly will pull all the transactions from those contracts and wallets and display them on the [Transaction Listing](/developer-explorer/transaction-listing) page. This gives you an easy overview of the activity and allows you to:

* [Inspect individual transactions](/developer-explorer/inspect-transaction/overview)
* [Debug transaction errors](/debugger/overview)
* [Check gas usage](/debugger/gas-profiler)


# Simulation Mode in the Explorer
Source: https://docs.tenderly.co/developer-explorer/simulation-mode

How the Explorer behaves when Simulation Mode is active, where to enter it from Explorer pages, and where the full Simulation Mode documentation lives.

Simulation Mode is a persistent "act-as-this-wallet" context. When it is active, Explorer pages render and simulate as the impersonated wallet: contract Read/Write pages auto-fill the `From` address, wallet pages expose one-click impersonation, and transaction pages let you re-simulate as that wallet.

This page covers the Explorer surfaces wired into Simulation Mode. For the session model, balance overrides, state settings, and the Sim Mode panel itself, see the full [Simulation Mode](/simulator-ui/simulation-mode) documentation.

## Entering Simulation Mode from the Explorer

There are two entry points:

* **Top bar**: click **Enter Simulation Mode** and pick a wallet and network. The button is available on every Explorer page.
* **Wallet detail pages**: an **Impersonate** button sits between Create Alert and Simulate. It activates Simulation Mode pre-filled with that wallet, with no picker step.

Once active, the top-bar button is replaced with a `SIMULATING` pill showing the wallet's identity icon, abbreviated address, and total USD balance. The context follows you across pages until you exit.

## Explorer surfaces wired into Simulation Mode

| Surface                       | Behavior when Sim Mode is active                                                                                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contract Read/Write pages** | A purple banner indicates Sim Mode is active. The Write button is hidden and **Simulate** becomes the primary action. The `From` field auto-fills with the impersonated wallet. |
| **Transaction detail**        | The Re-Simulate dropdown gains a **Re-simulate as \[wallet]** option, so you can replay any transaction as the impersonated wallet.                                             |
| **Wallet detail pages**       | The **Impersonate** button activates Sim Mode for that wallet directly.                                                                                                         |

If you open a page on a network different from your active session, a banner offers a one-click **Switch Sim Mode to \[network]**. Read and Write actions are disabled until you switch.

## Relation to the Simulator

Simulation Mode and the [Simulator](/simulator-ui/overview) are complementary:

* **Simulation Mode** is a session: simulations accumulate, each run sees the state the previous ones produced, and the wallet context persists across Explorer pages.
* The **Simulator** is where you build and run individual simulations and multi-step bundles. With Sim Mode active, the Simulator pre-fills the sender as the impersonated wallet and successful runs append to the session log.

## See also

* [Simulation Mode](/simulator-ui/simulation-mode): the full session model, Tokens tab, balance overrides, and state settings.
* [Simulator UI](/simulator-ui/overview): single simulations and bundles.
* [Wallets in the Explorer](/developer-explorer/wallets): adding and managing wallets.


# Transaction Listing
Source: https://docs.tenderly.co/developer-explorer/transaction-listing

A guide to managing and analyzing transactions in the Tenderly Dashboard for development and monitoring.

Once you add a contract or wallet from any supported network, all the transactions coming from those assets will be displayed in the Dashboard. This makes it easy to keep track of everything in one place. You can also use filters to sort and find the transactions that are most important to you, which can be helpful both during development and monitoring.

[Watch on Loom →](https://www.loom.com/share/ec9c8aac4ca24bb19226b6dd96606f97?sid=07229573-c019-42d8-8a6c-8a89acdefbb3)

To see all your project's transactions, go to the **Transactions** page. Here, you can apply filters and sort transactions to hone in on the information most relevant to you.

Click on the **Filters** button to access the filtering and sorting options.

<img alt="Transaction Filtering Overview" />

Transactions can be filtered by their:

* **Status** (success, [pending](/developer-explorer/inspect-transaction/overview#mempool-pending-transactions), failed)
* **Type** (internal and direct)
* **Contract addresses** involved
* **Function** called
* **Network** (95 networks supported)
* **Date** or date range
* **Tag**, matching any [tag you've added](/developer-explorer/wallets#adding-tags-to-wallets) to a contract or wallet

<img alt="Detailed Transaction Filtering" />


# Wallets
Source: https://docs.tenderly.co/developer-explorer/wallets

Add wallets to a Tenderly project, inspect their balances and transactions, and filter activity by tag.

Learn how to add a wallet to your project and keep track of its transactions in the Dashboard. When you add a wallet to a project, you'll see a list of all historical transactions linked to that particular wallet.

<img alt="Wallet page header info and tabs" />

## Adding a wallet to your project

Navigate to the **Wallets** section from the side menu and click on **Add Wallet**.

<img alt="Add wallet" />

Enter an address into the search field. It returns one result row per network that address has been seen on, each labeled **Wallet** or **Contract** depending on what's deployed there, and either kind can be selected and imported.

<img alt="Add Wallet search results, including a Contract-labeled row" />

Select the row you want and click **Import Wallets**.

Once imported, you can view all the transactions associated with the wallet in the Dashboard, simulate transactions, or [create Alerts](/monitoring/alerts/introduction) for it.

## Looking up any wallet

The Dashboard's search functionality allows you to find any wallet on any of the [95 supported networks](/platform/supported-networks), whether or not it's in one of your projects.

1. Enter the wallet's address in the top menu search bar.
2. Select the wallet from the search results.

<img alt="Find wallet" />

This opens the same wallet details page described below, reached via a `/wallet/<network>/<address>` URL instead of a project path. The header gains an **Add to Project** button alongside Share, Create Alert, Impersonate, and Simulate, and the `...` menu only has **View in Public Explorer**. The Transactions tab also drops the Success/Failed checkboxes and Columns/Filters controls, using simple numbered pagination instead of the project view's continuous list.

<img alt="Public wallet lookup header" />

To add the wallet to a project, click **Add to Project** and choose your target project.

## Wallet details

Opening a wallet, whether from your project's **Wallets** page or from a lookup, shows a header info panel followed by three tabs: **Transactions**, **Simulations**, and **Multichain assets**.

The header info panel shows the network, ETH balance and dollar value, token holdings, and NFT holdings. Unlike contracts, a wallet's info panel has no Tags field: tagging lives on the Wallets list page instead (see [Adding tags to wallets](#adding-tags-to-wallets) below). The `...` menu next to the wallet address has **View in Public Explorer**, **Hide Wallet**, and **Remove Wallet**. **Hide Wallet** excludes the wallet's transactions from the project-wide [Transactions view](/developer-explorer/transaction-listing) without affecting the wallet's own Transactions tab or any [Alerts](/monitoring/alerts/introduction) targeting it; select **Show Wallet** from the same menu to include them again.

<img alt="Wallet header menu" />

### Transactions

Lists every direct and internal transaction involving the wallet, with the same filters as a contract's transaction list: **All**, **Direct**, **Internal**, **Token asset transfers**, and **NFT asset transfers**, plus Columns and Filters controls.

### Simulations

Shows the wallet's simulated transaction history, and lets you launch a new [simulation](/simulator-ui/overview) directly against it.

### Multichain assets

Shows the wallet's holdings across networks over three sub-tabs: **Multichain positions**, **Token**, and **NFT**. Multichain positions is wallet-specific: a net-worth bar broken down by DeFi protocol (for example Uniswap v3 or Aave v3), with each protocol expandable to its individual positions.

<img alt="Multichain positions tab" />

The Token and NFT sub-tabs have the same Group by, "Hide zero balances", and search controls as a contract's Multichain assets tab.

<img alt="Multichain assets, Token tab" />

## Adding tags to wallets

When working with multiple wallets, you need a way to keep them organized. On the **Wallets** list page, click **Add tag** on a wallet's row to open the tagging dialog.

<img alt="Tagging a wallet" />

Tags also enable you to monitor multiple contracts or wallets grouped under a single tag using Alerts, and you can filter by tag from the **Filters** panel on the main [Transactions page](/developer-explorer/transaction-listing): open Filters and select a value from the **Tag** dropdown.

<img alt="Filters panel with Tag field" />

The transaction list then only shows rows where the tagged contract or wallet is the sender or recipient.

<img alt="Transactions filtered by tag" />

## Monitoring wallets with Alerts

Click **Create Alert** from a wallet's page to set up an [Alert](/monitoring/alerts/introduction) for it. See the [Alerting Quickstart Guide](/monitoring/alerts/tutorials/quickstart) for the full setup flow and [Alert Types, Targets, and Parameters](/monitoring/alerts/types) for the available triggers.


# Tenderly Documentation: Simulate, Debug, and Monitor Onchain
Source: https://docs.tenderly.co/introduction

Tenderly is the simulation company for onchain operations, helping risk, engineering, and finance teams model every move before capital is exposed.

Tenderly is the simulation-powered platform for running blockchain systems across 100+ networks. Engineering, finance, and risk teams use it to model every transaction, financial strategy, deployment, and integration against the real, live state of their systems before capital is exposed, and to operate with full context in production.

With Tenderly as a single operational layer, teams can:

* **Simulate:** preview the exact outcome of any transaction, multi-step workflow, or cross-chain deployment against live network state, before anything is committed.
* **Understand:** inspect every transaction, contract, and asset movement with the most granular execution data onchain, decoded into human-readable context.
* **Respond:** monitor every condition that matters across your systems and act fast to mitigate critical incidents.

## How Tenderly enables onchain flows

Tenderly is a blockchain operations platform powered by a simulation engine and deep transaction tracing and decoding capabilities. It consists of several products covering the entire operational flow.

### Simulator: model every action before it's final

See the exact outcome of a transaction, a multi-step workflow, or an entire cross-chain deployment against real network state, with full control over every parameter.

<CardGroup>
  <Card title="Virtual Environments" icon="flask" href="/virtual-environments/overview">
    Production-mirroring environments with state sync, unlimited faucet, cheatcodes, and a shareable explorer.
  </Card>

  <Card title="Simulation API" icon="play" href="/simulations/overview">
    Dry-run any transaction or bundle with state diffs, asset changes, and gas estimates.
  </Card>

  <Card title="Simulator UI" icon="window" href="/simulator-ui/overview">
    Build, edit, and re-run simulations in the dashboard with state overrides and source edits.
  </Card>
</CardGroup>

### Console: gain complete context for onchain activity

Understand and analyze not just what happened onchain, but why it happened, with the most comprehensive, actionable insights and decoded data for verified and unverified contracts alike.

<CardGroup>
  <Card title="Explorer" icon="magnifying-glass" href="/developer-explorer/overview">
    Search assets, addresses, and transactions across 100+ chains.
  </Card>

  <Card title="Debugger" icon="bug" href="/debugger/overview">
    Step through any transaction opcode-by-opcode, evaluate expressions, find the revert.
  </Card>

  <Card title="Fund Flow" icon="arrow-right-arrow-left" href="/developer-explorer/inspect-transaction/fund-flow">
    Follow capital movement through any transaction, with decoded context.
  </Card>

  <Card title="Gas Profiler" icon="gauge-high" href="/debugger/gas-profiler">
    Visual gas breakdown per function call, with access list recommendations.
  </Card>

  <Card title="DeFi Modules" icon="layer-group" href="/defi-modules/overview">
    Health, risk, and activity of the lending protocols your product depends on.
  </Card>
</CardGroup>

### Monitor: detect early and respond to onchain events

Monitor a range of onchain conditions relevant to your system to catch early signal of unexpected behavior and respond quickly to mitigate incidents.

<CardGroup>
  <Card title="Alerts" icon="bell" href="/monitoring/alerts/introduction">
    Watch addresses, contracts, and events. Route to Slack, webhooks, PagerDuty, and more.
  </Card>

  <Card title="Web3 Actions" icon="bolt" href="/monitoring/web3-actions/introduction">
    Custom response flows triggered by onchain events, from notifications to automated responses.
  </Card>

  <Card title="Webhooks" icon="share-nodes" href="/monitoring/alerts/destinations/overview">
    Deliver alert payloads to your own endpoints and systems.
  </Card>
</CardGroup>

### Node RPC: scale onchain usage on a high-performance infrastructure

<CardGroup>
  <Card title="Node RPC" icon="cloud" href="/node-rpc/overview">
    Production-grade RPC across 75+ networks with built-in simulations and gas estimation.
  </Card>

  <Card title="Supported Networks" icon="globe" href="/platform/supported-networks">
    All 100+ chains, with chain IDs and per-product capability coverage.
  </Card>
</CardGroup>

## Start here

<CardGroup>
  <Card title="Virtual Environment quickstart" icon="rocket" href="/virtual-environments/quickstart">
    Spin up a simulation environment and integrate it with your tooling, CI/CD, or app.
  </Card>

  <Card title="Simulation API quickstart" icon="code" href="/simulations/quickstart">
    Send your first simulation and read back the full outcome.
  </Card>

  <Card title="What you get" icon="gift" href="/what-you-get">
    Platform capabilities for production teams, plus what's included with a free account.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Find every endpoint across Simulator, Virtual Environments, Alerts, and more.
  </Card>
</CardGroup>


# Using Alerts API
Source: https://docs.tenderly.co/monitoring/alerts/api

Configure simple and compound alerting rules programmatically with the Tenderly Alerts API, covering each expression type and multi-condition combinations.

This guide covers setting up both simple and complex alerting rules using Tenderly's API. We'll explore each expression type and then combine them into sophisticated monitoring solutions.

<Card title="Alerting API reference" href="/api-reference" />

## Introduction

Tenderly's Alert API allows you to create simple and complex Alerts.
A simple alert consists of one rule, for example `method_call` will get triggered when a transaction invokes your public or external method. A complex alert can have several conditions, and will get triggered when all of them are met. For example, an alert with `method_call` and `state_change` will trigger when a transaction calls the given method and updates the specified storage slot.

When defining an Alert using the API, you need to specify the following:

* **delivery channels** that get notified when alerting rule is triggered. See more about [Delivery Channels](/api-reference).
* **expressions** array that will trigger the alert when all conditions represented by individual expressions are met.

<Note>
  Email, Discord, and Sentry delivery channels can be created via the API (`POST /api/v1/account/{accountId}/delivery-channel`). Slack, Telegram, and PagerDuty channels require the OAuth/bot connection flow and can be created only via the Dashboard. All channels can be fetched using the [API](/api-reference).
</Note>

## Authentication

Before creating alerts, you'll need to set up authentication and identify your project:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    const TENDERLY_API_KEY = 'your_api_key';
    const PROJECT_SLUG = 'your_project_slug';
    const ACCOUNT_ID = 'me';  // Use 'me' or your specific account ID

    // Base configuration for axios
    const baseConfig = {
      baseURL: 'https://api.tenderly.co/api/v1',
      headers: {
        'X-Access-Key': TENDERLY_API_KEY,
        'Content-Type': 'application/json'
      }
    };
    ```
  </Tab>

  <Tab title="Shell">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    export TENDERLY_API_KEY="your_api_key"
    export PROJECT_SLUG="your_project_slug"
    export ACCOUNT_ID="me"  # Use 'me' or your specific account ID
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import requests

    TENDERLY_API_KEY = 'your_api_key'
    PROJECT_SLUG = 'your_project_slug'
    ACCOUNT_ID = 'me'  # Use 'me' or your specific account ID

    # Base configuration for requests
    base_url = 'https://api.tenderly.co/api/v1'
    headers = {
        'X-Access-Key': TENDERLY_API_KEY,
        'Content-Type': 'application/json'
    }
    ```
  </Tab>
</Tabs>

## Expression Types

You can use different expression types for specifying Alerts' trigger rules.

| Expression Type                | Monitoring                                                                   | Main Use Case                             | Required Arguments                                                                                                                                 | Optional Arguments                                                                                                                                                                   |
| ------------------------------ | ---------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `method_call`                  | Specific function calls in contracts (direct or internal transactions apply) | Track when important functions are called | - `address`: Contract address; `signature`: Object with `function_name` and `input_types` (ordered ABI input types, e.g. `["address", "uint256"]`) | - `transaction_type`: "any" (default), "direct", "source", or "internal"; `parameter_conditions`: Array of conditions; `not`: boolean                                                |
| `whitelisted_caller_addresses` | For calls from specific addresses                                            | Allow-list based access control           | - `addresses`: Array of Ethereum addresses                                                                                                         | None                                                                                                                                                                                 |
| `blacklisted_caller_addresses` | For calls from blocked addresses                                             | Block-list based access control           | - `addresses`: Array of Ethereum addresses                                                                                                         | None                                                                                                                                                                                 |
| `contract_address`             | Specific contract interactions                                               | Track all interactions with a contract    | - `address`: Contract address                                                                                                                      | - `transaction_type`: "direct", "source", or "internal"; when omitted, both direct and internal calls match                                                                          |
| `network`                      | Events on specific networks                                                  | Multi-chain monitoring                    | - `network_id`: Network/chain ID                                                                                                                   | None                                                                                                                                                                                 |
| `tag`                          | Contracts with specific tags                                                 | Group-based monitoring                    | - `tag`: Tag string                                                                                                                                | - `transaction_type`: "direct", "source", or "internal"; when omitted, behaves like "internal"                                                                                       |
| `tx_status`                    | Transaction success/failure                                                  | Track failed transactions                 | None                                                                                                                                               | - `transaction_success`: boolean                                                                                                                                                     |
| `tx_value`                     | Transaction value                                                            | Track large transfers                     | - `transaction_value`: Amount in wei; `operator`: Comparison operator                                                                              | None                                                                                                                                                                                 |
| `emitted_log`                  | Contract events                                                              | Track specific events                     | - `address`: Contract address; `event_name`: Event name; `event_id`: Event signature                                                               | - `match_any`: boolean (match logs from any contract); `match_non_project_contracts`: boolean; `decode_events`: boolean; `parameter_conditions`: Array of conditions; `not`: boolean |
| `state_change`                 | Contract state changes                                                       | Track storage changes                     | - `address`: Contract address; `parameter_conditions`: Array of conditions                                                                         | - `match_any`: boolean (match state changes on any contract); `match_non_project_contracts`: boolean; `not`: boolean; comparison options (threshold, percentage)                     |
| `view_function`                | Read-only function results                                                   | Track computed values                     | - `address`: Contract address; `input`: ABI encoded function data; `network_id`: Network ID                                                        | - `parameter_condition`: Value comparison; `not`: boolean                                                                                                                            |
| `eth_balance`                  | ETH balance changes                                                          | Track balance thresholds                  | - `address`: Contract address; `threshold`: Balance in wei                                                                                         | - `operator`: Comparison operator (default `<=`); `not`: boolean                                                                                                                     |
| `erc20_transfer_matcher`       | ERC20 transfer consistency                                                   | Validate transfer mechanics               | - `address`: Token address; `log_name`: Event name; `balances`: State variable name                                                                | None                                                                                                                                                                                 |

### Notes

* These are all the expression types the API accepts. A payload with any other `type` value is rejected with a `400` ("Expressions are not in the right format").
* All expressions within an alert are AND-ed: the alert fires only when every expression matches the same transaction. To monitor independent conditions, create a separate alert for each.
* For comparison operators (`operator`), valid values are: `>`, `>=`, `<`, `<=`, `==`, `!=`, `contains`, `notContains`
* Parameter types (`parameter_type`) include: `uint`, `int`, `bool`, `address`, `string`, `slice`, `array`, `tuple`, `fixed_bytes`, `bytes`, `hash`, `function`
* The expression types `emitted_log`, `erc20_transfer_matcher`, `eth_balance`, `tx_value`, `method_call`, `state_change`, `tx_status`, and `view_function` support an optional `not: true` field that negates the match
* `eth_balance` fires only when a transaction moves the balance across the threshold (from non-matching to matching), not on every transaction while the condition holds
* All addresses must be valid Ethereum addresses (`0x` prefixed, 40 hex chars)
* Wei values should be passed as strings to handle large numbers
* Network IDs should match the target blockchain (e.g., "1" for Ethereum mainnet)

For more details, explore the [Alerting API reference](/api-reference).

## Simple expressions examples

Explore examples of setting up simple expression rules.

### 1. Method Call Monitoring

**Use Case**: Monitor specific function calls in your smart contract.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    const methodCallAlert = {
      name: "Critical Function Call Alert",
      description: "Monitors calls to critical functions",
      enabled: true,
      expressions: [{
        type: "method_call",
        expression: {
          address: "0xe592427a0aece92de3edee1f18e0157c05861564",
          signature: {
            function_name: "unwrapWETH9", // name of the function to match
            input_types: ["uint256", "address"] // ordered ABI input types
          }
        }
      },
      {
          "type": "contract_address",
          "expression": {
              "address": "0xe592427a0aece92de3edee1f18e0157c05861564"
          }
      }
      ],
      delivery_channels: [{
        id: "your_channel_id",
        enabled: true
      }]
    };

    await axios.post(
      `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
      methodCallAlert,
      baseConfig
    );
    ```
  </Tab>

  <Tab title="Shell">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl -X POST "https://api.tenderly.co/api/v1/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert" \
    --header "Content-Type: application/json" \
    --header "X-Access-Key: ${TENDERLY_API_KEY}" \
    --data-raw '{
      "name": "Critical Function Call Alert",
      "description": "Monitors calls to critical functions",
      "enabled": true,
      "expressions": [
        {
        "type": "method_call",
          "expression": {
            "address": "0xe592427a0aece92de3edee1f18e0157c05861564",
            "signature": {
              "function_name": "unwrapWETH9",
              "input_types": ["uint256", "address"]
            }
          }
        },
        {
          "type": "contract_address",
          "expression": {
              "address": "0xe592427a0aece92de3edee1f18e0157c05861564"
          }
        }
      ],
      "delivery_channels": [{
        "id": "your_channel_id",
        "enabled": true
      }]
    }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    method_call_alert = {
        "name": "Critical Function Call Alert",
        "description": "Monitors calls to critical functions",
        "enabled": True,
        "expressions": [{
            "type": "method_call",
            "expression": {
                "address": "0xe592427a0aece92de3edee1f18e0157c05861564",
                "signature": {
                    "function_name": "unwrapWETH9",
                    "input_types": ["uint256", "address"]
                }
            }
        },
         {
              "type": "contract_address",
              "expression": {
                  "address": "0xe592427a0aece92de3edee1f18e0157c05861564"
              }
            }],
        "delivery_channels": [{
            "id": "your_channel_id",
            "enabled": True
        }]
    }

    response = requests.post(
        f"{base_url}/account/{ACCOUNT_ID}/project/{PROJECT_SLUG}/alert",
        headers=headers,
        json=method_call_alert
    )
    ```
  </Tab>
</Tabs>

### 2. State Change Monitoring

**Use Case**: Monitor changes in contract state variables, especially useful for tracking critical parameters like paused state or balance thresholds.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    const stateChangeAlert = {
      name: "Critical State Change Alert",
      description: "Monitors important state changes",
      enabled: true,
      expressions: [{
        type: "state_change",
        expression: {
          address: "0x1234....",
          parameter_conditions: [
            {
              parameter_name: "pause",
              parameter_type: "bool",
              compare_change: true
            },
            {
              parameter_name: "totalSupply",
              parameter_type: "uint",
              compare_percentage: true,
              comparison_value: "5",
              operator: ">="
            }
          ]
        }
      }],
      delivery_channels: [{
        id: "your_channel_id",
        enabled: true
      }]
    };

    await axios.post(
      `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
      stateChangeAlert,
      baseConfig
    );
    ```
  </Tab>

  <Tab title="Shell">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl -X POST "https://api.tenderly.co/api/v1/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert" \
    --header "Content-Type: application/json" \
    --header "X-Access-Key: ${TENDERLY_API_KEY}" \
    --data-raw '{
      "name": "Critical State Change Alert",
      "description": "Monitors important state changes",
      "enabled": true,
      "expressions": [{
        "type": "state_change",
        "expression": {
          "address": "0x1234....",
          "parameter_conditions": [
            {
              "parameter_name": "pause",
              "parameter_type": "bool",
              "compare_change": true
            },
            {
              "parameter_name": "totalSupply",
              "parameter_type": "uint",
              "compare_percentage": true,
              "comparison_value": "5",
              "operator": ">="
            }
          ]
        }
      }],
      "delivery_channels": [{
        "id": "your_channel_id",
        "enabled": true
      }]
    }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    state_change_alert = {
        "name": "Critical State Change Alert",
        "description": "Monitors important state changes",
        "enabled": True,
        "expressions": [{
            "type": "state_change",
            "expression": {
                "address": "0x1234....",
                "parameter_conditions": [
                    {
                        "parameter_name": "pause",
                        "parameter_type": "bool",
                        "compare_change": True
                    },
                    {
                        "parameter_name": "totalSupply",
                        "parameter_type": "uint",
                        "compare_percentage": True,
                        "comparison_value": "5",
                        "operator": ">="
                    }
                ]
            }
        }],
        "delivery_channels": [{
            "id": "your_channel_id",
            "enabled": True
        }]
    }

    response = requests.post(
        f"{base_url}/account/{ACCOUNT_ID}/project/{PROJECT_SLUG}/alert",
        headers=headers,
        json=state_change_alert
    )
    ```
  </Tab>
</Tabs>

### 3. Event Monitoring

**Use Case**: Monitor specific events emitted by your contracts, with parameter filtering.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    const eventAlert = {
      name: "Large Transfer Event Alert",
      description: "Monitors large transfer events",
      enabled: true,
      expressions: [{
        type: "emitted_log",
        expression: {
          address: "0x1234....",
          event_name: "Transfer",
          event_id: "0x241ea03ca20251805084d27d4440371c34a0b85ff108f6bb5611248f73818b80",
          parameter_conditions: [
            {
              parameter_name: "amount",
              parameter_type: "uint",
              operator: ">=",
              comparison_value: "1000000000000000000" // 1 ETH
            }
          ],
          decode_events: true
        }
      }],
      delivery_channels: [{
        id: "your_channel_id",
        enabled: true
      }]
    };

    await axios.post(
      `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
      eventAlert,
      baseConfig
    );
    ```
  </Tab>

  <Tab title="Shell">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl -X POST "https://api.tenderly.co/api/v1/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert" \
    --header "Content-Type: application/json" \
    --header "X-Access-Key: ${TENDERLY_API_KEY}" \
    --data-raw '{
      "name": "Large Transfer Event Alert",
      "description": "Monitors large transfer events",
      "enabled": true,
      "expressions": [{
        "type": "emitted_log",
        "expression": {
          "address": "0x1234....",
          "event_name": "Transfer",
          "event_id": "0x241ea03ca20251805084d27d4440371c34a0b85ff108f6bb5611248f73818b80",
          "parameter_conditions": [
            {
              "parameter_name": "amount",
              "parameter_type": "uint",
              "operator": ">=",
              "comparison_value": "1000000000000000000"
            }
          ],
          "decode_events": true
        }
      }],
      "delivery_channels": [{
        "id": "your_channel_id",
        "enabled": true
      }]
    }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    event_alert = {
        "name": "Large Transfer Event Alert",
        "description": "Monitors large transfer events",
        "enabled": True,
        "expressions": [{
            "type": "emitted_log",
            "expression": {
                "address": "0x1234....",
                "event_name": "Transfer",
                "event_id": "0x241ea03ca20251805084d27d4440371c34a0b85ff108f6bb5611248f73818b80",
                "parameter_conditions": [
                    {
                        "parameter_name": "amount",
                        "parameter_type": "uint",
                        "operator": ">=",
                        "comparison_value": "1000000000000000000"
                    }
                ],
                "decode_events": True
            }
        }],
        "delivery_channels": [{
            "id": "your_channel_id",
            "enabled": True
        }]
    }

    response = requests.post(
        f"{base_url}/account/{ACCOUNT_ID}/project/{PROJECT_SLUG}/alert",
        headers=headers,
        json=event_alert
    )
    ```
  </Tab>
</Tabs>

### 4. Native ETH Balance Monitoring

**Use Case**: Alert when an address's native ETH balance falls below a threshold, for example a relayer or operations wallet that must stay funded. Scope the alert to a network and an address, then compare the native balance against the threshold (in wei).

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    const balanceAlert = {
      name: "Low ETH balance alert",
      description: "Alerts when the native ETH balance falls below 0.1 ETH",
      enabled: true,
      expressions: [
        // Scope to a specific network
        {
          type: "network",
          expression: {
            network_id: "1" // Ethereum mainnet
          }
        },
        // Scope to the watched address
        {
          type: "contract_address",
          expression: {
            address: "0x3b8c2f1a9d7e4605c8a1b2d3e4f5061728394a5b"
          }
        },
        // Trigger when the native balance drops below the threshold
        {
          type: "eth_balance",
          expression: {
            address: "0x3b8c2f1a9d7e4605c8a1b2d3e4f5061728394a5b",
            threshold: "100000000000000000", // 0.1 ETH in wei
            operator: "<"
          }
        }
      ],
      delivery_channels: [{
        id: "your_channel_id",
        enabled: true
      }]
    };

    await axios.post(
      `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
      balanceAlert,
      baseConfig
    );
    ```
  </Tab>

  <Tab title="Shell">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl -X POST "https://api.tenderly.co/api/v1/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert" \
    --header "Content-Type: application/json" \
    --header "X-Access-Key: ${TENDERLY_API_KEY}" \
    --data-raw '{
      "name": "Low ETH balance alert",
      "description": "Alerts when the native ETH balance falls below 0.1 ETH",
      "enabled": true,
      "expressions": [
        {
          "type": "network",
          "expression": {
            "network_id": "1"
          }
        },
        {
          "type": "contract_address",
          "expression": {
            "address": "0x3b8c2f1a9d7e4605c8a1b2d3e4f5061728394a5b"
          }
        },
        {
          "type": "eth_balance",
          "expression": {
            "address": "0x3b8c2f1a9d7e4605c8a1b2d3e4f5061728394a5b",
            "threshold": "100000000000000000",
            "operator": "<"
          }
        }
      ],
      "delivery_channels": [{
        "id": "your_channel_id",
        "enabled": true
      }]
    }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    balance_alert = {
        "name": "Low ETH balance alert",
        "description": "Alerts when the native ETH balance falls below 0.1 ETH",
        "enabled": True,
        "expressions": [
            {
                "type": "network",
                "expression": {
                    "network_id": "1"
                }
            },
            {
                "type": "contract_address",
                "expression": {
                    "address": "0x3b8c2f1a9d7e4605c8a1b2d3e4f5061728394a5b"
                }
            },
            {
                "type": "eth_balance",
                "expression": {
                    "address": "0x3b8c2f1a9d7e4605c8a1b2d3e4f5061728394a5b",
                    "threshold": "100000000000000000",
                    "operator": "<"
                }
            }
        ],
        "delivery_channels": [{
            "id": "your_channel_id",
            "enabled": True
        }]
    }

    response = requests.post(
        f"{base_url}/account/{ACCOUNT_ID}/project/{PROJECT_SLUG}/alert",
        headers=headers,
        json=balance_alert
    )
    ```
  </Tab>
</Tabs>

## Complex Alert Examples

Explore examples of showing complex expression rules. The alert will get triggered when every expression in the `expressions` array is satisfied.

### 1. Security Monitoring System

**Use Case**: Comprehensive security monitoring combining multiple conditions:

* Monitor admin function calls
* Track large value transfers
* Watch for blacklisted addresses
* Alert on state changes to critical parameters

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    const securityAlert = {
      name: "Security Monitoring System",
      description: "Comprehensive security monitoring for contract",
      enabled: true,
      expressions: [
        {
          "type": "contract_address",
          "expression": {
              "address": "0xe592427a0aece92de3edee1f18e0157c05861564"
          }
        },
        // Admin function monitoring
        {
          type: "method_call",
          expression: {
            address: "0xe592427a0aece92de3edee1f18e0157c05861564",
            signature: {
              function_name: "transferOwnership",
              input_types: ["address"]
            }
          }
        },
        // Blacklist checking
        {
          type: "blacklisted_caller_addresses",
          expression: {
            addresses: [
              "0xblacklisted1...",
              "0xblacklisted2..."
            ]
          }
        },
        // Large value transfers
        {
          type: "tx_value",
          expression: {
            transaction_value: "100000000000000000000", // 100 ETH
            operator: ">"
          }
        },
        // Critical state changes
        {
          type: "state_change",
          expression: {
            address: "0x1234....",
            parameter_conditions: [
              {
                parameter_name: "pause",
                parameter_type: "bool",
                compare_change: true
              },
              {
                parameter_name: "owner",
                parameter_type: "address",
                compare_change: true
              }
            ]
          }
        }
      ],
      delivery_channels: [{
        id: "your_channel_id",
        enabled: true
      }]
    };

    await axios.post(
      `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
      securityAlert,
      baseConfig
    );
    ```
  </Tab>

  <Tab title="Shell">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl -X POST "https://api.tenderly.co/api/v1/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert" \
    --header "Content-Type: application/json" \
    --header "X-Access-Key: ${TENDERLY_API_KEY}" \
    --data-raw '{
      "name": "Security Monitoring System",
      "description": "Comprehensive security monitoring for contract",
      "enabled": true,
      "expressions": [
       {
          "type": "contract_address",
          "expression": {
              "address": "0xe592427a0aece92de3edee1f18e0157c05861564"
          }
        },
        {
          "type": "method_call",
          "expression": {
            "address": "0xe592427a0aece92de3edee1f18e0157c05861564",
            "signature": {
              "function_name": "transferOwnership",
              "input_types": ["address"]
            }
          }
        },
        {
          "type": "blacklisted_caller_addresses",
          "expression": {
            "addresses": [
              "0xblacklisted1...",
              "0xblacklisted2..."
            ]
          }
        },
        {
          "type": "tx_value",
          "expression": {
            "transaction_value": "100000000000000000000",
            "operator": ">"
          }
        },
        {
          "type": "state_change",
          "expression": {
            "address": "0x1234....",
            "parameter_conditions": [
              {
                "parameter_name": "pause",
                "parameter_type": "bool",
                "compare_change": true
              },
              {
                "parameter_name": "owner",
                "parameter_type": "address",
                "compare_change": true
              }
            ]
          }
        }
      ],
      "delivery_channels": [{
        "id": "your_channel_id",
        "enabled": true
      }]
    }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    security_alert = {
        "name": "Security Monitoring System",
        "description": "Comprehensive security monitoring for contract",
        "enabled": True,
        "expressions": [
         {
            "type": "contract_address",
            "expression": {
                "address": "0xe592427a0aece92de3edee1f18e0157c05861564"
            }
          },
            {
                "type": "method_call",
                "expression": {
                    "address": "0xe592427a0aece92de3edee1f18e0157c05861564",
                    "signature": {
                        "function_name": "transferOwnership",
                        "input_types": ["address"]
                    }
                }
            },
            {
                "type": "blacklisted_caller_addresses",
                "expression": {
                    "addresses": [
                        "0xblacklisted1...",
                        "0xblacklisted2..."
                    ]
                }
            },
            {
                "type": "tx_value",
                "expression": {
                    "transaction_value": "100000000000000000000",
                    "operator": ">"
                }
            },
            {
                "type": "state_change",
                "expression": {
                    "address": "0x1234....",
                    "parameter_conditions": [
                        {
                            "parameter_name": "pause",
                            "parameter_type": "bool",
                            "compare_change": True
                        },
                        {
                            "parameter_name": "owner",
                            "parameter_type": "address",
                            "compare_change": True
                        }
                    ]
                }
            }
        ],
        "delivery_channels": [{
            "id": "your_channel_id",
            "enabled": True
        }]
    }

    response = requests.post(
        f"{base_url}/account/{ACCOUNT_ID}/project/{PROJECT_SLUG}/alert",
        headers=headers,
        json=security_alert
    )
    ```
  </Tab>
</Tabs>

### 2. DeFi Protocol Monitor

**Use Case**: Monitor a DeFi pool for:

* Large trades/swaps
* Liquidity changes
* Failed transactions

Because expressions within an alert are AND-ed, each condition is a separate alert. The examples below create three alerts in one go.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    const defiAlerts = [
      // Alert 1: large swaps via events
      {
        name: "Large Swaps",
        description: "Swap events moving 1000+ tokens out of the pool",
        enabled: true,
        expressions: [{
          type: "emitted_log",
          expression: {
            address: "0xpool_address",
            event_name: "Swap",
            event_id: "0x...", // Swap event signature
            parameter_conditions: [
              {
                parameter_name: "amountOut",
                parameter_type: "uint",
                operator: ">=",
                comparison_value: "1000000000000000000000" // 1000 tokens
              }
            ],
            decode_events: true
          }
        }],
        delivery_channels: [{ id: "your_channel_id", enabled: true }]
      },
      // Alert 2: liquidity changes
      {
        name: "Liquidity Shift",
        description: "Pool reserves moved by 10% or more",
        enabled: true,
        expressions: [{
          type: "state_change",
          expression: {
            address: "0xpool_address",
            parameter_conditions: [
              {
                parameter_name: "reserve0",
                parameter_type: "uint",
                compare_percentage: true,
                comparison_value: "10",
                operator: ">="
              },
              {
                parameter_name: "reserve1",
                parameter_type: "uint",
                compare_percentage: true,
                comparison_value: "10",
                operator: ">="
              }
            ]
          }
        }],
        delivery_channels: [{ id: "your_channel_id", enabled: true }]
      },
      // Alert 3: failed transactions on the pool
      {
        name: "Failed Transactions",
        description: "Failed transactions involving the pool",
        enabled: true,
        expressions: [
          {
            type: "contract_address",
            expression: { address: "0xpool_address" }
          },
          {
            type: "tx_status",
            expression: { transaction_success: false }
          }
        ],
        delivery_channels: [{ id: "your_channel_id", enabled: true }]
      }
    ];

    for (const alert of defiAlerts) {
      await axios.post(
        `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
        alert,
        baseConfig
      );
    }
    ```
  </Tab>

  <Tab title="Shell">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    # Alert 1: large swaps via events
    curl -X POST "https://api.tenderly.co/api/v1/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert" \
    --header "Content-Type: application/json" \
    --header "X-Access-Key: ${TENDERLY_API_KEY}" \
    --data-raw '{
      "name": "Large Swaps",
      "description": "Swap events moving 1000+ tokens out of the pool",
      "enabled": true,
      "expressions": [{
        "type": "emitted_log",
        "expression": {
          "address": "0xpool_address",
          "event_name": "Swap",
          "event_id": "0x...",
          "parameter_conditions": [
            {
              "parameter_name": "amountOut",
              "parameter_type": "uint",
              "operator": ">=",
              "comparison_value": "1000000000000000000000"
            }
          ],
          "decode_events": true
        }
      }],
      "delivery_channels": [{ "id": "your_channel_id", "enabled": true }]
    }'

    # Alert 2: liquidity changes
    curl -X POST "https://api.tenderly.co/api/v1/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert" \
    --header "Content-Type: application/json" \
    --header "X-Access-Key: ${TENDERLY_API_KEY}" \
    --data-raw '{
      "name": "Liquidity Shift",
      "description": "Pool reserves moved by 10% or more",
      "enabled": true,
      "expressions": [{
        "type": "state_change",
        "expression": {
          "address": "0xpool_address",
          "parameter_conditions": [
            {
              "parameter_name": "reserve0",
              "parameter_type": "uint",
              "compare_percentage": true,
              "comparison_value": "10",
              "operator": ">="
            },
            {
              "parameter_name": "reserve1",
              "parameter_type": "uint",
              "compare_percentage": true,
              "comparison_value": "10",
              "operator": ">="
            }
          ]
        }
      }],
      "delivery_channels": [{ "id": "your_channel_id", "enabled": true }]
    }'

    # Alert 3: failed transactions on the pool
    curl -X POST "https://api.tenderly.co/api/v1/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert" \
    --header "Content-Type: application/json" \
    --header "X-Access-Key: ${TENDERLY_API_KEY}" \
    --data-raw '{
      "name": "Failed Transactions",
      "description": "Failed transactions involving the pool",
      "enabled": true,
      "expressions": [
        {
          "type": "contract_address",
          "expression": { "address": "0xpool_address" }
        },
        {
          "type": "tx_status",
          "expression": { "transaction_success": false }
        }
      ],
      "delivery_channels": [{ "id": "your_channel_id", "enabled": true }]
    }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    defi_alerts = [
        # Alert 1: large swaps via events
        {
            "name": "Large Swaps",
            "description": "Swap events moving 1000+ tokens out of the pool",
            "enabled": True,
            "expressions": [{
                "type": "emitted_log",
                "expression": {
                    "address": "0xpool_address",
                    "event_name": "Swap",
                    "event_id": "0x...",
                    "parameter_conditions": [
                        {
                            "parameter_name": "amountOut",
                            "parameter_type": "uint",
                            "operator": ">=",
                            "comparison_value": "1000000000000000000000"
                        }
                    ],
                    "decode_events": True
                }
            }],
            "delivery_channels": [{"id": "your_channel_id", "enabled": True}]
        },
        # Alert 2: liquidity changes
        {
            "name": "Liquidity Shift",
            "description": "Pool reserves moved by 10% or more",
            "enabled": True,
            "expressions": [{
                "type": "state_change",
                "expression": {
                    "address": "0xpool_address",
                    "parameter_conditions": [
                        {
                            "parameter_name": "reserve0",
                            "parameter_type": "uint",
                            "compare_percentage": True,
                            "comparison_value": "10",
                            "operator": ">="
                        },
                        {
                            "parameter_name": "reserve1",
                            "parameter_type": "uint",
                            "compare_percentage": True,
                            "comparison_value": "10",
                            "operator": ">="
                        }
                    ]
                }
            }],
            "delivery_channels": [{"id": "your_channel_id", "enabled": True}]
        },
        # Alert 3: failed transactions on the pool
        {
            "name": "Failed Transactions",
            "description": "Failed transactions involving the pool",
            "enabled": True,
            "expressions": [
                {
                    "type": "contract_address",
                    "expression": {"address": "0xpool_address"}
                },
                {
                    "type": "tx_status",
                    "expression": {"transaction_success": False}
                }
            ],
            "delivery_channels": [{"id": "your_channel_id", "enabled": True}]
        }
    ]

    for alert in defi_alerts:
        response = requests.post(
            f"{base_url}/account/{ACCOUNT_ID}/project/{PROJECT_SLUG}/alert",
            headers=headers,
            json=alert
        )
    ```
  </Tab>
</Tabs>

### 3. ERC20 Token Monitor

**Use Case**: Token monitoring including:

* Transfer consistency checks
* Large transfer monitoring
* Total supply changes

Like the previous example, each condition is its own alert.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    const tokenAlerts = [
      // Alert 1: Transfer event consistency
      {
        name: "Transfer Consistency",
        description: "Transfer events inconsistent with balance changes",
        enabled: true,
        expressions: [{
          type: "erc20_transfer_matcher",
          expression: {
            address: "0xtoken_address",
            log_name: "Transfer",
            balances: "balances"
          }
        }],
        delivery_channels: [{ id: "your_channel_id", enabled: true }]
      },
      // Alert 2: large transfers
      {
        name: "Large Transfers",
        description: "Transfers of 1000+ tokens",
        enabled: true,
        expressions: [{
          type: "emitted_log",
          expression: {
            address: "0xtoken_address",
            event_name: "Transfer",
            event_id: "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
            parameter_conditions: [
              {
                parameter_name: "value",
                parameter_type: "uint",
                operator: ">=",
                comparison_value: "1000000000000000000000" // 1000 tokens
              }
            ]
          }
        }],
        delivery_channels: [{ id: "your_channel_id", enabled: true }]
      },
      // Alert 3: total supply changes
      {
        name: "Supply Change",
        description: "totalSupply moved by 1% or more",
        enabled: true,
        expressions: [{
          type: "state_change",
          expression: {
            address: "0xtoken_address",
            parameter_conditions: [
              {
                parameter_name: "totalSupply",
                parameter_type: "uint",
                compare_percentage: true,
                comparison_value: "1",
                operator: ">="
              }
            ]
          }
        }],
        delivery_channels: [{ id: "your_channel_id", enabled: true }]
      }
    ];

    for (const alert of tokenAlerts) {
      await axios.post(
        `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
        alert,
        baseConfig
      );
    }
    ```
  </Tab>

  <Tab title="Shell">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    # Alert 1: Transfer event consistency
    curl -X POST "https://api.tenderly.co/api/v1/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert" \
    --header "Content-Type: application/json" \
    --header "X-Access-Key: ${TENDERLY_API_KEY}" \
    --data-raw '{
      "name": "Transfer Consistency",
      "description": "Transfer events inconsistent with balance changes",
      "enabled": true,
      "expressions": [{
        "type": "erc20_transfer_matcher",
        "expression": {
          "address": "0xtoken_address",
          "log_name": "Transfer",
          "balances": "balances"
        }
      }],
      "delivery_channels": [{ "id": "your_channel_id", "enabled": true }]
    }'

    # Alert 2: large transfers
    curl -X POST "https://api.tenderly.co/api/v1/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert" \
    --header "Content-Type: application/json" \
    --header "X-Access-Key: ${TENDERLY_API_KEY}" \
    --data-raw '{
      "name": "Large Transfers",
      "description": "Transfers of 1000+ tokens",
      "enabled": true,
      "expressions": [{
        "type": "emitted_log",
        "expression": {
          "address": "0xtoken_address",
          "event_name": "Transfer",
          "event_id": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
          "parameter_conditions": [
            {
              "parameter_name": "value",
              "parameter_type": "uint",
              "operator": ">=",
              "comparison_value": "1000000000000000000000"
            }
          ]
        }
      }],
      "delivery_channels": [{ "id": "your_channel_id", "enabled": true }]
    }'

    # Alert 3: total supply changes
    curl -X POST "https://api.tenderly.co/api/v1/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert" \
    --header "Content-Type: application/json" \
    --header "X-Access-Key: ${TENDERLY_API_KEY}" \
    --data-raw '{
      "name": "Supply Change",
      "description": "totalSupply moved by 1% or more",
      "enabled": true,
      "expressions": [{
        "type": "state_change",
        "expression": {
          "address": "0xtoken_address",
          "parameter_conditions": [
            {
              "parameter_name": "totalSupply",
              "parameter_type": "uint",
              "compare_percentage": true,
              "comparison_value": "1",
              "operator": ">="
            }
          ]
        }
      }],
      "delivery_channels": [{ "id": "your_channel_id", "enabled": true }]
    }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    token_alerts = [
        # Alert 1: Transfer event consistency
        {
            "name": "Transfer Consistency",
            "description": "Transfer events inconsistent with balance changes",
            "enabled": True,
            "expressions": [{
                "type": "erc20_transfer_matcher",
                "expression": {
                    "address": "0xtoken_address",
                    "log_name": "Transfer",
                    "balances": "balances"
                }
            }],
            "delivery_channels": [{"id": "your_channel_id", "enabled": True}]
        },
        # Alert 2: large transfers
        {
            "name": "Large Transfers",
            "description": "Transfers of 1000+ tokens",
            "enabled": True,
            "expressions": [{
                "type": "emitted_log",
                "expression": {
                    "address": "0xtoken_address",
                    "event_name": "Transfer",
                    "event_id": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                    "parameter_conditions": [
                        {
                            "parameter_name": "value",
                            "parameter_type": "uint",
                            "operator": ">=",
                            "comparison_value": "1000000000000000000000"
                        }
                    ]
                }
            }],
            "delivery_channels": [{"id": "your_channel_id", "enabled": True}]
        },
        # Alert 3: total supply changes
        {
            "name": "Supply Change",
            "description": "totalSupply moved by 1% or more",
            "enabled": True,
            "expressions": [{
                "type": "state_change",
                "expression": {
                    "address": "0xtoken_address",
                    "parameter_conditions": [
                        {
                            "parameter_name": "totalSupply",
                            "parameter_type": "uint",
                            "compare_percentage": True,
                            "comparison_value": "1",
                            "operator": ">="
                        }
                    ]
                }
            }],
            "delivery_channels": [{"id": "your_channel_id", "enabled": True}]
        }
    ]

    for alert in token_alerts:
        response = requests.post(
            f"{base_url}/account/{ACCOUNT_ID}/project/{PROJECT_SLUG}/alert",
            headers=headers,
            json=alert
        )
    ```
  </Tab>
</Tabs>


# Intro to Alerts
Source: https://docs.tenderly.co/monitoring/alerts/introduction

Listen for on-chain events and receive real-time notifications via email, Slack, PagerDuty, and other alert destinations.

<Note>
  Alerts are available on the paid plan. To enable them for your account, [contact our sales team](https://tenderly.co/contact-us).
</Note>

Tenderly Alerting listens for events on the blockchain and sends real-time notifications to your desired destination when the event occurs. This can be email, your favorite messaging app, an incident monitoring system, or webhooks and Web3 Actions.

With Tenderly Alerting, you can stay informed about desired or undesired events related to transitions, wallets, smart contracts, or any other activity on the network. This enables you to identify and resolve smart contract transaction issues faster. Alerts can also aid in the early detection of operational, code, or security issues.

With[ Alerts API](/monitoring/alerts/api), you can create complex triggering conditions.

Follow these quick links to skip ahead and get started with Tenderly Alerting:

* [**Quickstart guide**](/monitoring/alerts/tutorials/quickstart)
* [**How to set up webhooks for alerting**](/monitoring/alerts/tutorials/webhooks)
* [**Using Alerting API**](/monitoring/alerts/api).
* [**Alert triggers and targets**](/monitoring/alerts/types)
* [**Alert destinations**](/monitoring/alerts/destinations/overview)

<iframe />

## Anatomy of an Alert

Each Alert requires three elements to be configured before it can be enabled:

* **Alert Type:** On-chain event that triggers Tenderly to send you a notification. There are 12 alert trigger types to choose from.
* **Alert Target:** Addresses you want Tenderly to monitor, as well as other settings such as the network, project, and tags.
* **Alert Destination:** Service for receiving notifications about a specific event. One Alert can send notifications to multiple destinations. There are 8 destination types where you can send and receive notifications.

## Alert trigger types overview

Below is a list of all 12 alert trigger types and a brief description of each. Click the link to explore configuration details.

| Trigger Type                                                                  | Description                                                                    | Common Use Case                                          |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------- |
| [**Successful Transaction**](/monitoring/alerts/types#successful-transaction) | Fires when a transaction is successfully mined.                                | Monitor contract calls or wallet activity.               |
| [**Failed Transaction**](/monitoring/alerts/types#failed-transaction)         | Fires when a transaction fails to be mined.                                    | Early detection of usage or code issues.                 |
| [**Function Call**](/monitoring/alerts/types#function-call)                   | Fires when a specific `external` or `public` function is called on a contract. | Track specific contract interactions.                    |
| [**Event Emitted**](/monitoring/alerts/types#event-emitted)                   | Fires when a specific event is emitted from a contract.                        | Monitor ERC-20 approvals, transfers, etc.                |
| [**Event Parameter**](/monitoring/alerts/types#event-parameter)               | Fires when an event argument matches a condition you define.                   | Alert when a transfer amount exceeds a threshold.        |
| [**ERC20 Token Transfer**](/monitoring/alerts/types#erc20-token-transfer)     | Fires when an ERC-20 Transfer event is emitted.                                | Track token movements to/from an address.                |
| [**Allowlisted Callers**](/monitoring/alerts/types#allowlisted-callers)       | Fires when an address NOT on your allowlist calls a contract.                  | Detect unauthorized callers.                             |
| [**Blocklisted Callers**](/monitoring/alerts/types#blocklisted-callers)       | Fires when an address on your blocklist calls a contract.                      | Monitor known bad actors or unauthorized wallets.        |
| [**Balance Change**](/monitoring/alerts/types#balance-change)                 | Fires when a native token balance matches a condition after a transaction.     | Know when to top up a keeper or bot wallet.              |
| [**Transaction Value**](/monitoring/alerts/types#transaction-value)           | Fires when the value of a transaction matches a condition in wei.              | Track high-value transactions.                           |
| [**State Change**](/monitoring/alerts/types#state-change)                     | Fires when a numeric state variable in a contract changes.                     | Monitor multisig confirmation count or config variables. |
| [**View Function**](/monitoring/alerts/types#view-function)                   | Fires when the return value of a `view` function changes after a transaction.  | Track ERC-20 balances via `balanceOf`.                   |

## Alert Destinations overview

All these alert triggers can be configured to send real-time notifications to a place where it’s convenient for your team.

Receive notifications in your favorite messaging app:

* [**Email**](/monitoring/alerts/destinations/account-scoped#email-destination)
* [**Slack**](/monitoring/alerts/destinations/account-scoped#slack-destination)
* [**Telegram**](/monitoring/alerts/destinations/account-scoped#telegram-destination)
* [**Discord**](/monitoring/alerts/destinations/account-scoped#discord-destination)

Send alert data to other Tenderly systems:

* [**Web3 Actions**](/monitoring/alerts/destinations/project-scoped#web3-actions)
* [**Webhooks**](/monitoring/alerts/destinations/project-scoped#webhooks)

Send alert data to third-party incident and error monitoring platforms like:

* [**Sentry**](/monitoring/alerts/destinations/account-scoped#sentry-destination)
* [**PagerDuty**](/monitoring/alerts/destinations/account-scoped#pagerduty-destination)

Learn [how to set up each Alert Destination](/monitoring/alerts/destinations/overview) here.

## What can you do with Tenderly Alerting?

Tenderly Alerting offers value in a variety of circumstances. Whenever you require a dependable alerting system for on-chain activities that can notify you of potential risks or threats, you can rely on Tenderly Alerting.

* **Monitor on-chain activity:** Alerts can be used as a monitoring tool to track user activity on smart contracts, such as failed or successful transactions or state changes. This is useful in scenarios when you need to keep track of specific events or changes in the blockchain environment.
* **Detect suspicious behavior:** Alerts can inform you about suspicious behavior on your smart contracts or wallets, such as security breaches or fraudulent activity. This helps you to take appropriate action to protect your assets and prevent losses.
* **Respond faster in emergency situations:** Alerts also help you detect errors, security issues, or failed transactions. This is useful in situations when you need to take action to resolve a problem immediately after it happens.
* **Ensure greater visibility for your team:** You can configure each Alert to your specifications, including setting the location for notifications convenient for your team.
* **Enable automated processes:** Use Alerts as triggers for Web3 Actions to build custom automated processes that allow you to react automatically to on-chain events with custom code.


# Alert Types, Targets, and Parameters
Source: https://docs.tenderly.co/monitoring/alerts/types

Set up and configure alert types from the Tenderly Dashboard to get notified when specific on-chain events occur on your contracts.

To create and enable an Alert, you need to specify and configure the following components:

* **Alert Type:** On-chain event that triggers Tenderly to send you a notification. There are 12 alert triggers to choose from.
* **Alert Target:** Address or addresses you want to monitor. The Target options are the same across all Alert Types and include:
  * **Address:** Monitor a single address.
  * **Network:** Monitor all addresses deployed on a network of your choice.
  * **Project:** Monitor all addresses that are part of a project on Tenderly.
  * **Tag:** Monitor all contracts and wallets labeled with the specific tag.
* **Alert Parameters:** Additional settings specific to the selected Alert Type.
* **Alert Destination:** The place where you want to receive notifications. One Alert can send notifications to multiple destinations. There are 8 destinations where you can send and receive notifications.

<Note>
  Alerts are evaluated only for transactions involving your project's contracts and wallets, so the address you want to monitor must be [added to the project](/developer-explorer/contracts) first. Adding an address also includes its transactions in the project's [Transactions view](/developer-explorer/transaction-listing). To monitor a high-traffic address without the noise, add it and [hide it from the transaction listing](/developer-explorer/contracts#hide-a-contract-from-the-transaction-listing); hiding has no effect on Alerts.
</Note>

The rest of this document focuses on different Alert Types.

<Note>
  Read the [Alerting Quickstart guide](/monitoring/alerts/tutorials/quickstart) to learn
  the steps for setting up an example Alert and enabling it.
</Note>

## Successful Transaction

<Frame>
  <img alt="Parameters for the Successful Transaction Alert" />
</Frame>

The Successful Transaction alert sends a notification when a new transaction is created and added to the blockchain. This alert is commonly used for monitoring transactions that call a specific smart contract or transactions sent or received by a specific wallet.

To create a Successful Transaction alert, complete the following steps:

1. **Select Successful Transaction** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a single address.
3. **Choose the address of the smart contract** from the dropdown.
4. [**Set the Destination**](/monitoring/alerts/destinations/overview) by creating a new one or select one you previously created.
5. **Click Save** to get notified when a transaction goes through successfully.

## Failed Transaction

<Frame>
  <img alt="Parameters for the Failed Transaction Alert" />
</Frame>

The Failed Transaction alert sends a notification when a transaction fails to get added to the blockchain. This alert is commonly used for early detection of usage issues for wallets, smart contracts, and dapps.

To create a Failed Transaction alert, complete the following steps:

1. **Select Failed Transaction** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a single address.
3. **Choose the address of the smart contract** from the dropdown.
4. [**Set the Destination**](/monitoring/alerts/destinations/overview) by creating a new one or select one you previously created.
5. **Click Save** to get notified when a transaction fails.

## Function Call

<Frame>
  <img alt="Parameters for the Function Call Alert" />
</Frame>

The Function Call alert sends a notification when a specific `external` or `public` function is called from a selected smart contract. Notifications will be sent when the function is first called in a transaction, and each time it's called during the execution via internal calls.

To create a Function Call alert, complete the following steps:

1. **Select Function Call** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a smart contract deployed on a specific address.
3. **Choose the address of the smart contract** from the dropdown.
4. **Select the function** you want to monitor. Tenderly will extract all available functions from the smart contract.
5. [**Set the Destination**](/monitoring/alerts/destinations/overview) by creating a new one or select one you previously created.
6. **Click Save** to get notified when the function gets called from your smart contract.

## Event Emitted

<Frame>
  <img alt="Parameters for the Event Emitted Alert" />
</Frame>

The Event Emitted alert sends a notification when a specific event is emitted from the selected smart contract. For example, you can use this alert to monitor an ERC-20 token and get notified when a third-party address is approved to spend the balance.

To create an Event Emitted alert, complete the following steps:

1. **Select Event Emitted** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a smart contract deployed on a specific address.
3. **Choose the address of the smart contract** from the dropdown.
4. **Select the event function** you want to monitor from the list of available events.
5. [**Set the Destination**](/monitoring/alerts/destinations/overview) by creating a new one or select one you previously created.
6. **Click Save** to get notified when the event function emits an event.

## Event Parameter

<Frame>
  <img alt="Parameters for the Event Parameter Alert" />
</Frame>

The Event Parameter alert sends a notification when an event argument matches the set conditions. For example, you can use this alert to monitor an ERC-20 token and get notified when a third-party address is approved to spend a balance higher than the threshold value.

To create an Event Parameter alert, complete the following steps:

1. **Select Event Parameter** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a smart contract deployed on a specific address.
3. **Choose the address of the smart contract** from the dropdown.
4. **Select the event function** you want to monitor from the list of available events.
5. **Choose the argument** from the list of arguments that the selected event function requires. Some events can have multiple arguments. Tenderly will pull in all the required arguments automatically.
6. **Select the comparator operator** (e.g., equal to, not equal to, etc.).
7. **Enter the comparison value** (e.g., integer, address, etc.) you want to compare the argument value against.
8. [**Set the Destination**](/monitoring/alerts/destinations/overview) by creating a new one or select one you previously created.
9. **Click Save** to get notified when the argument in the event function matches the conditions you defined.

## ERC20 Token Transfer

<Frame>
  <img alt="Parameters for the ERC20 Token Transfer Alert" />
</Frame>

The ERC20 Token Transfer will send you a notification when an ERC-20 transfer event is emitted from a smart contract. This alert is useful when you want to keep track of token transfers from one address to another.

To create an ERC-20 Token Transfer alert, complete the following steps:

1. **Select ERC20 Token Transfer** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a smart contract deployed on a specific address.
3. **Choose the address of the smart contract** from the dropdown.
4. **Set the directional value**, tokens **coming to** or **going from** the selected address.
5. **Enter the address** that corresponds to the directional value.
6. [**Set the Destination** ](/monitoring/alerts/destinations/overview)by creating a new one or select one you previously created.
7. **Click Save** to get notified when an ERC-20 token transfer event occurs.

## Allowlisted Callers

<Frame>
  <img alt="Parameters for the Allowlisted Alert" />
</Frame>

The Allowlisted Callers alert allows you to add familiar addresses and receive notifications only when addresses that are not on the list call a smart contract.

To create an Allowlisted Callers alert, complete the following steps:

1. **Select Allowlisted Callers** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a smart contract deployed on a specific address.
3. **Choose the address of the smart contract** from the dropdown.
4. **Enter the address(es)** you are familiar with and want to exclude from monitoring.
5. [**Set the Destination**](/monitoring/alerts/destinations/overview) by creating a new one or select one you previously created.
6. **Click Save** to get notified when someone outside the list of addresses you created calls your smart contract.

## Blocklisted Callers

<Frame>
  <img alt="Parameters for the Blocklisted Alert" />
</Frame>

The Blocklisted Caller alert allows you to add unwanted addresses and only receive a notification when those addresses send a transaction to the selected Target. This alert can be used to monitor when unauthorized addresses try to call your multisig wallet or contract.

To create a Blocklisted Callers alert, complete the following steps:

1. **Select Blocklisted Callers** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a smart contract or wallet deployed on a specific address.
3. **Choose the address of the smart contract** from the dropdown.
4. **Enter the address(es)** you want to keep an eye on and get notified when they take action on your smart contract or wallet.
5. [**Set the Destination**](/monitoring/alerts/destinations/overview) by creating a new one or select one you previously created.
6. **Click Save** to get notified when someone on the list of addresses you created calls your smart contract.

## Balance Change

<Frame>
  <img alt="Parameters for the Balance Change Alert" />
</Frame>

The Balance Change alert notifies when the network's native currency balance of a specific address matches conditions after a transaction is executed. This alert can be useful to know when you need to top up your wallet (like bots or keepers).

To create a Balance Change alert, complete the following steps:

1. **Select Balance Change** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a smart contract or wallet deployed on a specific address.
3. **Choose the address of the smart contract or wallet** from the dropdown.
4. **Select the comparator operator** (e.g., equal to, not equal to, etc.).
5. **Set the balance threshold value in wei.** This alert is triggered only when a transaction sets the balance of an address to a value that satisfies set conditions. It is not triggered when the balance is in the state of satisfied conditions.
6. [**Set the Destination**](/monitoring/alerts/destinations/overview) by creating a new one or select one you previously created.
7. **Click Save** to get notified when the network's native currency balance on your smart contract or wallet matches the threshold conditions you defined.

## Transaction Value

<Frame>
  <img alt="Parameters for the Transaction Value Alert" />
</Frame>

The Transaction Value alert notifies you when the value of a transaction involving a wallet or smart contract matches some value in wei.

To create a Transaction Value alert, complete the following steps:

1. **Select Transaction Value** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a smart contract or wallet deployed on a specific address.
3. **Select the comparator operator** (e.g., equal to, greater than, etc.).
4. **Enter the value in wei** that you want to compare against.
5. [**Set the Destination**](/monitoring/alerts/destinations/overview) by creating a new one or select one you previously created.
6. **Click Save** to get notified when the value of a transaction coming from the wallet or smart contract matches the value in wei you specified.

## State Change

<Frame>
  <img alt="Parameters for the State Change Alert" />
</Frame>

The State Change alert notifies you when a numeric (int/uint) state variable in a smart contract is changed. With this alert, you can get notifications when the number of required confirmations in a multisig increases or decreases. Similarly, you can observe any other configuration-like state variable of a smart contract.

To create a State Change alert, complete the following steps:

1. **Select State Change** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a smart contract or wallet deployed on a specific address.
3. **Select the state variable** from the smart contract that you want to monitor.
4. **Configure additional parameters** for the selected state variable. Depending on the data type of the state variable, you need to configure additional parameters to tell Tenderly how to compare the property value of the state variable to what you want:
   * **Threshold passed:** Triggers when the property value passes a threshold. You’ll get only one alert each time the value passes the threshold.
   * **Percentage change:** Triggers when the property value increases or decreases by a percentage you set.
   * **Criteria:** Triggers when the new property value set by a transaction matches the comparison criteria.
   * **Value changed:** Triggers the alert whenever the property value changes.
5. [**Set the Destination**](/monitoring/alerts/destinations/overview) by creating a new one or select one you previously created.
6. **Click Save** to get notified when the state variable in the smart contract changes.

## View Function

<Frame>
  <img alt="Parameters for the View Function Alert" />
</Frame>

The View Function alert notifies you when the return value of a selected `view` function in a smart contract is changed by a transaction. For example, you can track when the balance of a particular address of an ERC-20 token changes by using the `balanceOf('0x...')` view function.

To create a View Function alert, complete the following steps:

1. **Select View Function** from the list of Alert Types.
2. From the Target section, **select Address** to monitor a smart contract or wallet deployed on a specific address.
3. **Choose the smart contract address.**
4. From the list of declared view functions, **select the view function** that you want to monitor. You will have to specify any arguments view function may require.
5. **Configure additional parameters** depending on the data type returned by the view function.
   1. **Threshold passed:** Define the threshold and get alerted when the return value passes the threshold value. You also need to define the comparator type (less than, equal to, etc.) and the value with which to make the comparison. You’ll get only one alert each time the value passes the threshold.
   2. **Percentage change:** Define the percentage and get alerted when the changes by a certain percentage. You also need to define the comparator type and the value with which to make the comparison.
   3. **Criteria:** Define any type of criteria that you want using the different comparator operators and get notified when the criteria are met.
   4. **Value changed:** Get notified whenever the return value changes in any way.
6. [**Set the Destination**](/monitoring/alerts/destinations/overview) by creating a new one or select one you previously created.
7. **Click Save** to get notified when the return value of a view function you selected changes compared to the previous block.


# Basic Concepts & FAQs
Source: https://docs.tenderly.co/platform/sdk/concepts

Learn the basic concepts and get answers to the most common questions related to the Tenderly SDK.

### What's a Tenderly project (project slug)?

Project slugs are unique identifiers for each project you create with Tenderly. It’s automatically created from the project's name by converting it to lowercase and replacing spaces with hyphens. The SDK uses project slugs to reference and manage projects when interacting with the Tenderly API.

**Guides**

* [How to obtain the project slug/name](/platform/account/projects/slug#project-name-or-slug)

### What's a Tenderly account (username and organization slug)?

An account represents a user or an organization on Tenderly. Each account has a unique username (for individual users) or organization slug (for organizations). The SDK uses these identifiers to specify the owner of a project, wallet, or contract when making requests to the Tenderly API.

**Guides**

* [How to obtain the account name](/platform/account/projects/slug#username)
* [How to obtain the organization name](/platform/account/projects/slug#organization-name)

### What’s the difference between a wallet and a contract?

**A wallet** is a user-controlled account that stores and manages digital assets like cryptocurrencies. Wallets can initiate transactions, interact with smart contracts, and receive assets.

**A contract** is a smart contract deployed on the blockchain. It contains code that executes automatically when certain conditions are met or when a transaction invokes it. While wallets are primarily used to manage assets, smart contracts are used to define the rules and logic of dapps and can interact with other contracts or wallets.

### What's a simulation?

A simulation is a way to test transactions, interactions, and contract executions in a controlled environment without actually executing them on-chain. By simulating transactions, you can test and validate smart contract bug fixes or code updates, replay failed transactions to identify the cause of a problem, and preview the expected outcomes.

The Tenderly SDK provides utilities for simulating individual transactions and bundled transactions from code via the API. To learn more about how Tenderly's Simulation API works, check out the [Simulation API documentation page](/simulations/quickstart).

### Usage

SDK usage is counted against your account's request capacity, just like direct API or RPC calls. To discuss capacity, [contact our sales team](https://tenderly.co/contact-us).


# Practical Examples
Source: https://docs.tenderly.co/platform/sdk/examples

Integrate the Tenderly SDK into your projects faster with the help of these practical examples that you can modify to fit your specific needs.

These examples assume you have already installed and initialized the [Tenderly SDK](/platform/sdk/introduction). All practical examples can be found in the official [`tenderly-sdk`](https://github.com/Tenderly/tenderly-sdk) GitHub repo in the `/examples` directory:

<Card title="Tenderly SDK Examples" href="" />


# Intro to Tenderly SDK
Source: https://docs.tenderly.co/platform/sdk/introduction

With the Tenderly SDK, simulate single transactions or bundles, manage contracts and wallets, and verify contracts from your code.

The Tenderly SDK is a TypeScript library that provides a set of useful utilities, enabling you to move faster through the different development stages using Tenderly.

It allows you to simulate transactions, simulate transaction bundles, manage contracts and wallets, and verify smart contracts from your code. The SDK is particularly useful for blockchain developers who want to integrate Tenderly's powerful tools into their dapp or development workflow.

### Introduction

The Tenderly SDK provides an easy-to-use interface for interacting with Tenderly via its API.

**Key features of the SDK include:**

* [Simulating transactions](/platform/sdk/simulating-transactions)
* [Managing and verifying contracts](/platform/sdk/managing-contracts)
* [Managing wallets](/platform/sdk/managing-wallets)

### Installation

The Tenderly SDK is available as an [npm package](https://www.npmjs.com/package/@tenderly/sdk). Install it by running the following command in your project directory:

**npm**

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
npm install @tenderly/sdk
```

**yarn**

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
yarn add @tenderly/sdk
```

**pnpm**

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pnpm add @tenderly/sdk
```

### Quickstart

The example below shows you how to do a simple simulation in less than 5 minutes. To learn more about the concepts behind the SDK, see [Tenderly SDK FAQs](/platform/sdk/concepts).

#### Initializing the SDK

To use the Tenderly SDK, you must first import the necessary libraries and create a new instance of the **`Tenderly`** class. This is where you pass in your Tenderly configuration details.

The configuration object should include your account name, project name, access key, and network.

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

const tenderlyInstance = new Tenderly({
  accountName: 'my-account',
  projectName: 'my-project',
  accessKey: 'my-access-key',
  network: Network.MAINNET, // Replace with the appropriate network
});
```

If you don’t want to hardcode sensitive information like API keys, you can use environment variables to store this information, like so:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

const tenderlyInstance = new Tenderly({
  accountName: process.env.TENDERLY_ACCOUNT_NAME,
  projectName: process.env.TENDERLY_PROJECT_NAME,
  accessKey: process.env.TENDERLY_ACCESS_KEY,
  network: Network.MAINNET, // Replace with the appropriate network
});
```

<Note>
  The list of [supported networks](/platform/supported-networks) can be
  found here.
</Note>

#### How to get the account name, project slug, and secret key

Follow these step-by-step guides to obtain the necessary configuration details:

* [How to obtain the account name](/platform/account/projects/slug#username)
* [How to obtain the organization name](/platform/account/projects/slug#organization-name)
* [How to obtain the project slug/name](/platform/account/projects/slug#project-name-or-slug)
* [How to find, create, and manage API keys](/platform/account/projects/api-tokens)

### Example transaction simulation

The SDK provides a **`Simulator`** class for simulating transactions. To run a simulation, call the **`simulateTransaction`** method in the **`simulator`** namespace on the Tenderly instance:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const transaction = await tenderly.simulator.simulateTransaction({
  transaction: {
    from: callerAddress,
    to: counterContract,
    gas: 20000000,
    gas_price: '19419609232',
    value: 0,
    input: counterContractAbiInterface.encodeFunctionData('inc', []),
  },
  blockNumber: 3237677,
});
```

The code above produces the following result:

```js title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  status: true,
  gasUsed: '46838',
  cumulativeGasUsed: undefined,
  blockNumber: '3237677',
  type: undefined,
  logsBloom: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAACAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAA==',
  logs: [ { raw: [Object] } ],
  trace: [
    {
      type: 'CALL',
      from: '0xDBcB6Db1FFEaA10cd157F985a8543261250eFA46',
      to: '0x93Cc0A80DE37EC4A4F97240B9807CDdfB4a19fB1',
      gas: '19978936',
      gas_used: '25774',
      value: '0',
      input: '0x371303c0',
      trace_address: [Array]
    }
  ]
}
```

### Next steps

For more guidance on running simulations with the Tenderly SDK, give these tutorials a go and learn how to simulate both individual and bundled transactions.

<CardGroup>
  <Card title="How to Simulate Transactions with Tenderly SDK" href="/platform/sdk/tutorials/simulate-transactions" />

  <Card title="How to Perform Simulation Bundles with Tenderly SDK" href="/platform/sdk/tutorials/simulation-bundles" />
</CardGroup>

And as you continue learning how the Tenderly SDK works, we recommend taking at look at these helpful resources:

<CardGroup>
  <Card title="How to manage wallets" href="/platform/sdk/managing-wallets" />

  <Card title="Practical examples and code snippets" href="/platform/sdk/examples" />

  <Card title="Basic Concepts" href="/platform/sdk/concepts" />
</CardGroup>


# Managing Contracts
Source: https://docs.tenderly.co/platform/sdk/managing-contracts

Use these code snippet examples to add, update, remove, and verify smart contracts using the Tenderly SDK.

The [Tenderly SDK](/platform/sdk/introduction) provides a `ContractRepository` class for managing contracts associated with your Tenderly project. The `ContractRepository` allows you to add, update, and remove contracts, as well as verify them.

With the Tenderly SDK initialized, you can use the **`contracts`** namespace to access the **`ContractRepository`** instance. To manage the wallets in the same project, see [Managing Wallets](/platform/sdk/managing-wallets).

### Adding a contract

To add a new contract, use the `add` method of the **`contracts`** namespace:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
try {
  const contractAddress = '0x742d35Cc6634C0532925a3b844Bc454e4438f44e';
  const contract = await tenderly.contracts.add(contractAddress, {
    displayName: 'MyContract',
  });

  console.log('Added contract:', addedContract);
} catch (error) {
  console.error('Error adding contract:', error);
}
```

### Updating a contract

To update an existing contract, use the **`update`** method of the **`contracts`** namespace:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
try {
  const contractAddress = '0x742d35Cc6634C0532925a3b844Bc454e4438f44e';
  const contract = await tenderly.contracts.update(contractAddress, {
    displayName: 'My Contract',
  });
  console.log('Updated contract:', contract);
} catch (error) {
  console.error('Error updating contract:', error);
}
```

### Removing a contract

To remove a contract, use the `remove` method of the **`contracts`** namespace:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
try {
  const contractAddress = '0x742d35Cc6634C0532925a3b844Bc454e4438f44e';
  await tenderly.contracts.remove(contractAddress);
  console.log('Contract removed successfully');
} catch (error) {
  console.error('Error removing contract:', error);
}
```

### Verifying a contract

To verify a contract, you can use **`verify`** method of the **`contracts`** namespace.

There are three examples that show the usage of `tenderly.contracts.verify` method:

* First example shows the verification of a simple `Counter` contract with no dependencies.
* Second example shows the verification of a `MyToken` contract that has multiple dependencies which are other contracts.
* Third example shows the verification of a `LibraryToken` contract that has a library dependency.

You can find these examples in the [examples folder](https://github.com/Tenderly/tenderly-sdk/tree/master/examples/contractVerification) of our `tenderly-sdk` repo along with the instructions on how to start them. Here will be shown only a `MyToken` contract with a few dependencies so you can see how to import them:

```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const myTokenAddress = `0x1a273A64C89CC45aBa798B1bC31B416A199Be3b3`.toLowerCase() as Web3Address;
const ROOT_FOLDER = `examples/contractVerification/withDependencies/contracts`;

const tenderly = new Tenderly({
  accessKey: process.env.TENDERLY_ACCESS_KEY || ``,
  accountName: process.env.TENDERLY_ACCOUNT_NAME || ``,
  projectName: process.env.TENDERLY_PROJECT_NAME || ``,
  network: Network.SEPOLIA,
});

const result = await tenderly.contracts.verify(myTokenAddress, {
  config: {
    mode: `public`,
  },
  contractToVerify: `${ROOT_FOLDER}/MyToken.sol:MyToken`,
  solc: {
    version: `v0.8.19`,
    sources: {
      [`${ROOT_FOLDER}/MyToken.sol`]: {
        content: readFileSync(`${ROOT_FOLDER}/MyToken.sol`, `utf8`),
      },
      [`@openzeppelin/contracts/token/ERC20/ERC20.sol`]: {
        content: readFileSync(`${ROOT_FOLDER}/ERC20.sol`, `utf8`),
      },
      [`@openzeppelin/contracts/token/ERC20/IERC20.sol`]: {
        content: readFileSync(`${ROOT_FOLDER}/IERC20.sol`, `utf8`),
      },
      [`@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol`]: {
        content: readFileSync(`${ROOT_FOLDER}/IERC20Metadata.sol`, `utf8`),
      },
      [`@openzeppelin/contracts/utils/Context.sol`]: {
        content: readFileSync(`${ROOT_FOLDER}/Context.sol`, `utf8`),
      },
    },
    settings: {
      optimizer: {
        enabled: true,
        runs: 200,
      },
    },
  },
});

console.log(`Result:`, result);
```


# Managing Wallets
Source: https://docs.tenderly.co/platform/sdk/managing-wallets

Use these code snippet examples to add, update, remove, and fetch wallets using the Tenderly SDK.

The [Tenderly SDK](/platform/sdk/introduction) provides a **`WalletRepository`** class for managing wallets associated with your project. The **`WalletRepository`** allows you to add, update, and remove wallets.

Once you have initialized the Tenderly SDK, you can use the **`wallets`** namespace to access the **`WalletRepository`** instance. For the equivalent contract operations, see [Managing Contracts](/platform/sdk/managing-contracts).

### Adding a wallet

To add a new wallet, use the **`add`** method of the **`wallets`** namespace:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
try {
  const walletAddress = '0x742d35Cc6634C0532925a3b844Bc454e4438f44e';
  const addedWallet = await tenderly.wallets.add(walletAddress, {
    displayName: 'My Wallet',
  });
  console.log('Added wallet:', addedWallet);
} catch (error) {
  console.error('Error adding wallet:', error);
}
```

### Updating a wallet

To update an existing wallet, use the **`update`** method of the **`wallets`** namespace:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
try {
  const walletAddress = '0x742d35Cc6634C0532925a3b844Bc454e4438f44e';
  const updatedWallet = await tenderly.wallets.update(walletAddress, {
    displayName: 'My Wallet',
  });
  console.log('Updated wallet:', updatedWallet);
} catch (error) {
  console.error('Error updating wallet:', error);
}
```

### Removing a wallet

To remove a wallet, use the **`remove`** method of the **`wallets`** namespace:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
try {
  const walletAddress = '0x742d35Cc6634C0532925a3b844Bc454e4438f44e';
  await tenderly.wallets.remove(walletAddress);
  console.log('Wallet removed successfully');
} catch (error) {
  console.error('Error removing wallet:', error);
}
```

### Fetching wallets

To fetch wallets associated with your project, use the **`getAll`** method of the **`wallets`** namespace:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
try {
  const allWallets = await tenderly.wallets.getAll();
  console.log('All wallets:', allWallets);
} catch (error) {
  console.error('Error fetching wallets:', error);
}
```

### Fetching a single wallet

To fetch a single wallet by its ID, use the **`get`** method of the **`wallets`** namespace:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
try {
  const walletAddress = '0x742d35Cc6634C0532925a3b844Bc454e4438f44e';
  const wallet = await tenderly.wallets.get(walletAddress);
  console.log('Fetched wallet:', wallet);
} catch (error) {
  console.error('Error fetching wallet:', error);
}
```


# Simulating Transactions
Source: https://docs.tenderly.co/platform/sdk/simulating-transactions

Use these code snippet examples to execute individual and bundled transactions using the Tenderly SDK.

The [Tenderly SDK](/platform/sdk/introduction) provides a **`Simulator`** class for simulating transactions. For a guided walkthrough, see the [simulate transactions tutorial](/platform/sdk/tutorials/simulate-transactions). To run a simulation, call the **`simulateTransaction`** method in the **`simulator`** namespace on the **`tenderly`** instance:

```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const transaction = await tenderly.simulator.simulateTransaction({
  transaction: {
    from: callerAddress,
    to: counterContract,
    gas: 20000000,
    gas_price: '19419609232',
    value: 0,
    input: counterContractAbiInterface.encodeFunctionData('inc', []),
  },
  blockNumber: 3237677,
});
```

You can also simulate a bundle of transactions by calling the **`simulateBundle`** method:

```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const simulations = await tenderly.simulator.simulateBundle({
  transactions: [
    {
      from: fromWalletAddress,
      to: myTokenAddress,
      gas: 0,
      gas_price: '0',
      value: 0,
      input: myTokenAbiInterface.encodeFunctionData('approve', [toWalletAddress, 1234567890]),
    },
    {
      from: toWalletAddress,
      to: myTokenAddress,
      gas: 0,
      gas_price: '0',
      value: 0,
      input: myTokenAbiInterface.encodeFunctionData('transferFrom', [
        fromWalletAddress,
        toWalletAddress,
        1234567890,
      ]),
    },
  ],
  blockNumber: 3262454,
  overrides: {
    [myTokenAddress]: {
      state: {
        [`_balances[${fromWalletAddress}]`]: '1234567891',
      },
    },
  },
});
```


# Simulate Transactions via SDK
Source: https://docs.tenderly.co/platform/sdk/tutorials/simulate-transactions

Learn how to execute a simple transaction simulation using the Tenderly SDK.

In this tutorial, you'll learn how to run a transaction simulation using the Tenderly SDK. Simulations allow you to test the behavior of your transactions without sending them on-chain. Learn more about Tenderly's [Transaction Simulator here](/simulations/quickstart).

### Prerequisites

* Node.js installed on your machine
* [Tenderly account with an API key](/platform/account/projects/api-tokens)
* [Project set up in the Tenderly Dashboard](/platform/account/projects/slug)

<Info>
  Use this link to [sign up for
  Tenderly](https://dashboard.tenderly.co/register?utm_source=homepage).
</Info>

### Step 1: Initialize a new Node.js project

Create a new directory for your project, navigate to it in the terminal, and initialize a new Node.js project:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
mkdir tenderly-simulation
cd tenderly-simulation
npm init -y
```

### Step 2: Install Tenderly SDK

Install the [Tenderly SDK npm package](https://www.npmjs.com/package/@tenderly/sdk) as a dependency in your Node.js project:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
npm install @tenderly/sdk
```

### Step 3: Import the Tenderly SDK and configure it

Create a new file named **`index.js`** in your project directory, and add the following code to import the Tenderly SDK and configure it with your Tenderly account details:

```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const { Network, Tenderly } = require('@tenderly/sdk');

const tenderly = new Tenderly({
  accountName: 'your-account-name',
  projectName: 'your-project-name',
  accessKey: 'your-access-key',
  network: Network.MAINNET, // Replace with the appropriate network
});
```

Make sure to replace **`your-account-name`**, **`your-project-name`**, and **`your-access-key`** with your actual Tenderly account information.

<Note>
  Follow these guides to [obtain the configuration
  details](/platform/sdk/introduction#how-to-get-the-account-name-project-slug-and-secret-key).
</Note>

### Step 4: Define the transaction details

Next, define the transaction details for the simulation.

Add the following code to **`index.js`**:

```js title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const transactionParameters = {
  from: '0x0000000000000000000000000000000000000000',
  to: '0x1f98431c8ad98523631ae4a59f267346ea31f984',
  input: '0xa1671295000000000000000000000000dac17f958d2ee523a2206206994597c13d831ec7000000000000000000000000152649ea73beab28c5b49b26eb48f7ead6d4c8980000000000000000000000000000000000000000000000000000000000000bb8',
  value: '0',
  gas: 8000000,
  gas_price: '0',
};

const simulation = {
  transaction: transactionParameters,
  blockNumber: 18813657, // simulation's target block number
  //overrides: {...} // optional state overrides field
};

```

Replace the **`from`**, **`to`**, **`input`**, **`value`**, **`gas`**, and **`gas_price`** fields with your desired transaction details. The **`override`** field is optional and allows you to override the state of specific contracts in the simulation.

<Warning>
  Make sure that the specified block number actually exists on the selected network.
</Warning>

### Step 5: Run the transaction simulation

Now, use the Tenderly SDK's **`simulateTransaction`** method to run the transaction simulation.

Add the following code to **`index.js`**:

```js title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
(async () => {
  try {
    const simulationResult = await tenderly.simulator.simulateTransaction(simulation);
    console.log('Simulation result:', simulationResult);
  } catch (error) {
    console.error('Error running simulation:', error);
  }
})();
```

This code runs an asynchronous function that calls the **`simulateTransaction`** method and logs the simulation result to the console.

### Step 6: Execute the script

Save the **`index.js`** file and run the script using the following command:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
node index.js
```

If the transaction simulation is successful, you'll see the simulation result printed in the console.

That's it! You've now learned how to run a transaction simulation using the Tenderly SDK.


# Simulation Bundles with SDK
Source: https://docs.tenderly.co/platform/sdk/tutorials/simulation-bundles

Learn how to execute a transaction bundle with Simulation Bundles using the Tenderly SDK.

In this tutorial, you'll learn how to use the Tenderly SDK to simulate bundled transactions. A bundled transaction is a collection of multiple transactions that are simulated as a unit.

Bundled transactions are often used in DeFi protocols and other applications to simulate the process of performing complex operations that involve multiple contract interactions.

<Note>Transactions from a bundle are simulated on the same blocks.</Note>

We'll simulate the usage of Uniswap for swapping a particular amount of DAI for WETH, and show the execution status of simulated transactions, and calculate the total gas used.

Here are the transactions needed to achieve this:

1. **Simulate minting of 2 DAI** so the swapper has some assets to swap. Alternatively, if you have DAI, you can skip this and just do transaction 2.
2. **Approve UniswapV3Router** to use DAI.
3. **Do the swap**. Call `UniswapV2Router.exactInputSingle` to perform the swap.

For the 1st transaction to run successfully, the sender needs to be a ward of DAI stablecoin. Since most of us aren't, we'll see how to use State Overrides to "become a ward" within the context of the Bundled Simulation.

### Prerequisites

* Node.js installed on your machine
* [Tenderly account with an API key](/platform/account/projects/api-tokens)
* [Project set up in the Tenderly Dashboard](/platform/account/projects/slug)

### Step 1: Set up the project

Create a new npm project, install dependencies, and configure Typescript by pasting the following commands into your terminal:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
mkdir tenderly-sdk-simulations
cd tenderly-sdk-simulations
npm init -y
yarn add @tenderly/sdk ethers
yarn add --dev typescript ts-node @types/node  dotenv
echo '{
  "compilerOptions": {
  "module": "commonjs",
  "esModuleInterop": true,
  "target": "es6",
  "moduleResolution": "node",
  "sourceMap": true,
  "outDir": "dist"
  "moduleResolution": "node16",
  },
  "lib": ["es2015"]
}' > tsconfig.json

mkdir src
touch src/swap.ts
code .
```

### Step 2: Call the Simulation API

Copy the complete runnable example from below and paste it into the `swap.ts` file.

Transactions are determined by functions `mint2DaiTx`, `approveUniswapV3RouterTx`, and `swapSomeDaiForWethTx`:

```ts title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

const fakeWardAddressEOA = '0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2';
const daiOwnerEOA = '0xe58b9ee93700a616b50509c8292977fa7a0f8ce1';
const daiAddressMainnet = '0x6b175474e89094c44da98b954eedeac495271d0f';
const uniswapV3SwapRouterAddressMainnet = '0xe592427a0aece92de3edee1f18e0157c05861564';
const wethAddressMainnet = '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2';

(async () => {
  const tenderly = new Tenderly({
    accessKey: 'access key',
    accountName: 'your account name',
    projectName: 'project-name-hyphenated',
    network: Network.MAINNET,
  });

  const simulatedBundle = await tenderly.simulator.simulateBundle({
    blockNumber: 0x103a957,
    transactions: [
      // TX1: Mint 2 DAI for daiOwnerEOA.
      // For minting to happen, we must do a state override so fakeWardAddress EOA is considered a ward for this simulation (see overrides)
      mint2DaiTx(),
      // TX2: daiOwnerEOA approves 1 DAI to uniswapV3SwapRouterAddressMainnet
      approveUniswapV3RouterTx(),
      // TX3: Perform a uniswap swap of 1/3 ETH
      swapSomeDaiForWethTx(),
    ],
    overrides: {
      [daiAddressMainnet]: {
        state: {
          // make DAI think that fakeWardAddress is a ward for minting
          [`wards[${fakeWardAddressEOA}]`]:
            '0x0000000000000000000000000000000000000000000000000000000000000001',
        },
      },
    },
  });
  const totalGasUsed = simulatedBundle
    .map(simulation => simulation.gasUsed)
    .reduce((total, gasUsed) => total + gasUsed);

  console.log('Total gas used:', totalGasUsed);

  simulatedBundle.forEach((simulation, idx) => {
    console.log(
      `Transaction ${idx} at block ${simulation.blockNumber}`,
      simulation.status ? 'success' : 'failed',
    );
  });

  console.log(JSON.stringify(simulatedBundle, null, 2));
})();

function mint2DaiTx(): TransactionParameters {
  return {
    from: fakeWardAddressEOA,
    to: daiAddressMainnet,
    gas: 0,
    gas_price: '0',
    value: 0,
    input: daiEthersInterface().encodeFunctionData('mint', [daiOwnerEOA, parseEther('2')]),
  };
}

function approveUniswapV3RouterTx(): TransactionParameters {
  return {
    from: daiOwnerEOA,
    to: daiAddressMainnet,
    gas: 0,
    gas_price: '0',
    value: 0,
    input: daiEthersInterface().encodeFunctionData('approve', [
      uniswapV3SwapRouterAddressMainnet,
      parseEther('1'),
    ]),
  };
}

function swapSomeDaiForWethTx(): TransactionParameters {
  return {
    from: daiOwnerEOA,
    to: uniswapV3SwapRouterAddressMainnet,
    gas: 0,
    gas_price: '0',
    value: 0,
    input: uniswapRouterV2EthersInterface().encodeFunctionData('exactInputSingle', [
      {
        tokenIn: daiAddressMainnet,
        tokenOut: wethAddressMainnet,
        fee: '10000',
        recipient: daiOwnerEOA,
        deadline: (1681109951 + 10 * 365 * 24 * 60 * 60 * 1000).toString(),
        amountIn: '33000000000000000',
        amountOutMinimum: '763124874493',
        sqrtPriceLimitX96: '0',
      },
    ]),
  };
}

function daiEthersInterface() {
  // @formatter:off
  const daiAbi=[
    {constant:false,inputs:[{internalType:'address',name:'src',type:'address',},{internalType:'address',name:'dst',type:'address',},{internalType:'uint256',name:'wad',type:'uint256',},],name:'transferFrom',outputs:[{internalType:'bool',name:'',type:'bool',},],payable:false,stateMutability:'nonpayable',type:'function',},
    {constant:false,inputs:[{internalType:'address',name:'usr',type:'address',},{internalType:'uint256',name:'wad',type:'uint256',},],name:'approve',outputs:[{internalType:'bool',name:'',type:'bool',},],payable:false,stateMutability:'nonpayable',type:'function',},
    {constant:false,inputs:[{internalType:'address',name:'usr',type:'address',},{internalType:'uint256',name:'wad',type:'uint256',},],name:'mint',outputs:[],payable:false,stateMutability:'nonpayable',type:'function',}
  ];

  return new Interface(daiAbi);
  // @formatter:on
}

function uniswapRouterV2EthersInterface() {
  // @formatter:off
  const swapRouterAbi = [
    {inputs: [ {internalType: 'address', name: '_factory', type: 'address',}, {internalType: 'address', name: '_WETH9', type: 'address',}, ], stateMutability: 'nonpayable', type: 'constructor',},
    {inputs: [], name: 'WETH9', outputs: [ {internalType: 'address', name: '', type: 'address',}, ], stateMutability: 'view', type: 'function',},
    {inputs: [ {components: [ {internalType: 'bytes', name: 'path', type: 'bytes',}, {internalType: 'address', name: 'recipient', type: 'address',}, {internalType: 'uint256', name: 'deadline', type: 'uint256',}, {internalType: 'uint256', name: 'amountIn', type: 'uint256',}, {internalType: 'uint256', name: 'amountOutMinimum', type: 'uint256',}, ], internalType: 'struct ISwapRouter.ExactInputParams', name: 'params', type: 'tuple',}, ], name: 'exactInput', outputs: [ {internalType: 'uint256', name: 'amountOut', type: 'uint256',}, ], stateMutability: 'payable', type: 'function',},
    {inputs: [ {components: [ {internalType: 'address', name: 'tokenIn', type: 'address',}, {internalType: 'address', name: 'tokenOut', type: 'address',}, {internalType: 'uint24', name: 'fee', type: 'uint24',}, {internalType: 'address', name: 'recipient', type: 'address',}, {internalType: 'uint256', name: 'deadline', type: 'uint256',}, {internalType: 'uint256', name: 'amountIn', type: 'uint256',}, {internalType: 'uint256', name: 'amountOutMinimum', type: 'uint256',}, {internalType: 'uint160', name: 'sqrtPriceLimitX96', type: 'uint160',}, ], internalType: 'struct ISwapRouter.ExactInputSingleParams', name: 'params', type: 'tuple',}, ], name: 'exactInputSingle', outputs: [ {internalType: 'uint256', name: 'amountOut', type: 'uint256',}, ], stateMutability: 'payable', type: 'function',},
    {inputs: [ {components: [ {internalType: 'bytes', name: 'path', type: 'bytes',}, {internalType: 'address', name: 'recipient', type: 'address',}, {internalType: 'uint256', name: 'deadline', type: 'uint256',}, {internalType: 'uint256', name: 'amountOut', type: 'uint256',}, {internalType: 'uint256', name: 'amountInMaximum', type: 'uint256',}, ], internalType: 'struct ISwapRouter.ExactOutputParams', name: 'params', type: 'tuple',}, ], name: 'exactOutput', outputs: [ {internalType: 'uint256', name: 'amountIn', type: 'uint256',}, ], stateMutability: 'payable', type: 'function',},
    {inputs: [ {components: [ {internalType: 'address', name: 'tokenIn', type: 'address',}, {internalType: 'address', name: 'tokenOut', type: 'address',}, {internalType: 'uint24', name: 'fee', type: 'uint24',}, {internalType: 'address', name: 'recipient', type: 'address',}, {internalType: 'uint256', name: 'deadline', type: 'uint256',}, {internalType: 'uint256', name: 'amountOut', type: 'uint256',}, {internalType: 'uint256', name: 'amountInMaximum', type: 'uint256',}, {internalType: 'uint160', name: 'sqrtPriceLimitX96', type: 'uint160',}, ], internalType: 'struct ISwapRouter.ExactOutputSingleParams', name: 'params', type: 'tuple',}, ], name: 'exactOutputSingle', outputs: [ {internalType: 'uint256', name: 'amountIn', type: 'uint256',}, ], stateMutability: 'payable', type: 'function',},
    {inputs: [], name: 'factory', outputs: [ {internalType: 'address', name: '', type: 'address',}, ], stateMutability: 'view', type: 'function',},
    {inputs: [ {internalType: 'bytes[]', name: 'data', type: 'bytes[]',}, ], name: 'multicall', outputs: [ {internalType: 'bytes[]', name: 'results', type: 'bytes[]',}, ], stateMutability: 'payable', type: 'function',},
    {inputs: [], name: 'refundETH', outputs: [], stateMutability: 'payable', type: 'function',},
    {inputs: [ {internalType: 'address', name: 'token', type: 'address',}, {internalType: 'uint256', name: 'value', type: 'uint256',}, {internalType: 'uint256', name: 'deadline', type: 'uint256',}, {internalType: 'uint8', name: 'v', type: 'uint8',}, {internalType: 'bytes32', name: 'r', type: 'bytes32',}, {internalType: 'bytes32', name: 's', type: 'bytes32',}, ], name: 'selfPermit', outputs: [], stateMutability: 'payable', type: 'function',},
    {inputs: [ {internalType: 'address', name: 'token', type: 'address',}, {internalType: 'uint256', name: 'nonce', type: 'uint256',}, {internalType: 'uint256', name: 'expiry', type: 'uint256',}, {internalType: 'uint8', name: 'v', type: 'uint8',}, {internalType: 'bytes32', name: 'r', type: 'bytes32',}, {internalType: 'bytes32', name: 's', type: 'bytes32',}, ], name: 'selfPermitAllowed', outputs: [], stateMutability: 'payable', type: 'function',},
    {inputs: [ {internalType: 'address', name: 'token', type: 'address',}, {internalType: 'uint256', name: 'nonce', type: 'uint256',}, {internalType: 'uint256', name: 'expiry', type: 'uint256',}, {internalType: 'uint8', name: 'v', type: 'uint8',}, {internalType: 'bytes32', name: 'r', type: 'bytes32',}, {internalType: 'bytes32', name: 's', type: 'bytes32',}, ], name: 'selfPermitAllowedIfNecessary', outputs: [], stateMutability: 'payable', type: 'function',},
    {inputs: [ {internalType: 'address', name: 'token', type: 'address',}, {internalType: 'uint256', name: 'value', type: 'uint256',}, {internalType: 'uint256', name: 'deadline', type: 'uint256',}, {internalType: 'uint8', name: 'v', type: 'uint8',}, {internalType: 'bytes32', name: 'r', type: 'bytes32',}, {internalType: 'bytes32', name: 's', type: 'bytes32',}, ], name: 'selfPermitIfNecessary', outputs: [], stateMutability: 'payable', type: 'function',},
    {inputs: [ {internalType: 'address', name: 'token', type: 'address',}, {internalType: 'uint256', name: 'amountMinimum', type: 'uint256',}, {internalType: 'address', name: 'recipient', type: 'address',}, ], name: 'sweepToken', outputs: [], stateMutability: 'payable', type: 'function',},
    {inputs: [ {internalType: 'address', name: 'token', type: 'address',}, {internalType: 'uint256', name: 'amountMinimum', type: 'uint256',}, {internalType: 'address', name: 'recipient', type: 'address',}, {internalType: 'uint256', name: 'feeBips', type: 'uint256',}, {internalType: 'address', name: 'feeRecipient', type: 'address',}, ], name: 'sweepTokenWithFee', outputs: [], stateMutability: 'payable', type: 'function',},
    {inputs: [ {internalType: 'int256', name: 'amount0Delta', type: 'int256',}, {internalType: 'int256', name: 'amount1Delta', type: 'int256',}, {internalType: 'bytes', name: '_data', type: 'bytes',}, ], name: 'uniswapV3SwapCallback', outputs: [], stateMutability: 'nonpayable', type: 'function',}, {inputs: [ {internalType: 'uint256', name: 'amountMinimum', type: 'uint256',}, {internalType: 'address', name: 'recipient', type: 'address',}, ], name: 'unwrapWETH9', outputs: [], stateMutability: 'payable', type: 'function',}, {inputs: [ {internalType: 'uint256', name: 'amountMinimum', type: 'uint256',}, {internalType: 'address', name: 'recipient', type: 'address',}, {internalType: 'uint256', name: 'feeBips', type: 'uint256',}, {internalType: 'address', name: 'feeRecipient', type: 'address',}, ], name: 'unwrapWETH9WithFee', outputs: [], stateMutability: 'payable', type: 'function',}, {stateMutability: 'payable', type: 'receive',}
  ];

  return new Interface(swapRouterAbi);
  // @formatter:on
}
```

Further down in the tutorial, you'll find detailed explanations of what the code is doing.

### Step 3: Run the script

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
npx ts-node src/swap.ts
```

### Understanding the code

First, we're creating a new instance of the Tenderly SDK:

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const tenderly = new Tenderly({
  accessKey: 'access key',
  accountName: 'your account name',
  projectName: 'project-name-hyphenated',
  network: Network.MAINNET,
});
```

To call the Simulation API and perform a bundled simulation, we're using `Tenderly.simulator.simulateBundle()` and passing an object with the following fields:

* `blockNumber` - the block number on which you wish to execute the simulation.
* `transactions` - an array holding three transactions: minting of 2 DAI, approving the Uniswap Router, and swapping DAI for WETH.
* `overrides` - an object making `fakeWardAddress` a ward of DAI within the simulation.

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const simulatedBundle = await tenderly.simulator.simulateBundle({
  blockNumber: 0x103a957,
  transactions: [
    // TX1: Mint 2 DAI for daiOwnerEOA.
    // For minting to happen, we must do a state override so fakeWardAddressEOA is considered a ward for this simulation (see overrides below)
    mint2DaiTx(),
    // TX2: daiOwnerEOA approves 1 DAI to uniswapV3SwapRouterAddressMainnet
    approveUniswapV3RouterTx(),
    // TX3: Perform a uniswap swap of 1/3 ETH
    swapSomeDaiForWethTx(),
  ],
  overrides: {
    [daiAddressMainnet]: {
      state: {
        // make DAI think that fakeWardAddress is a ward for minting
        [`wards[${fakeWardAddressEOA}]`]:
          '0x0000000000000000000000000000000000000000000000000000000000000001',
      },
    },
  },
});
```

### Understanding State Overrides

We're calling the DAI stablecoin `mint` function. During the simulation, the DAI contract has to believe you (the sender) are one of the wards. Otherwise, it will reject to mint.

We need the following condition to hold for DAI contract's state for a successful minting initiated by `fakeWardAddressEOA`:

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
daiAddressMainnet.state.wards[fakeWardAddressEOA] == 0x0000...0001
```

To enable this, we're passing `overrides` to the SDK, where we're overriding the DAI `wards` storage variable, so `fakeDaiWardAddress` becomes a ward during the simulation.

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
overrides: {
  [daiAddressMainnet]: {
    state: {
        // make DAI think that fakeWardAddress is a ward for minting
        [`wards[${fakeWardAddressEOA}]`]:
        '0x0000000000000000000000000000000000000000000000000000000000000001',
    },
  },
},
```

<Note>
  Note that the overrides apply to the **entire bundle** and are visible to all simulations within
  the bundle.
</Note>

Now, you have a better understanding of how to use the Tenderly SDK to perform complex simulation scenarios and display essential results.


# Tenderly TX Preview Snap
Source: https://docs.tenderly.co/platform/tx-preview-snap

Preview transactions before sending them on-chain to get valuable insights, avoid failed transactions, and save funds.

<iframe title="Tenderly TX Preview Snap Demo" />

Tenderly TX Preview is a MetaMask Snap that enables you to preview transaction outcomes without actually executing a transaction on a production network. This Snap gives you a human-readable overview of transaction outcomes across [95 supported EVM networks](/platform/supported-networks) so you can understand their financial implications before sending them on-chain.

More specifically, Tenderly TX Preview snap shows you which assets will be transferred within your transaction should you decide to send it. It also shows you the corresponding dollar values of asset transfers for ERC-20 and ERC-721 tokens.

With Tenderly TX Preview Snap, you can:

* **Get accurate information** on asset transfers with dollar values.
* **Avoid paying gas fees** for reverted transactions and save funds.
* **Send transactions confidently** knowing what’s going to happen.
* **Inspect simulated transactions** in greater detail on Tenderly.
* **Share simulated transactions** publicly with team members or associates.

<figure>
  <img alt="" />

  <figcaption>
    <p>Tenderly TX Preview Snap</p>
  </figcaption>
</figure>

## What does Tenderly TX Preview Snap do?

Tenderly TX Preview Snap simulates your transactions without sending them on-chain. It sends a request to the [Tenderly Simulation API](/api-reference) and simulates transaction execution against the most recent state of a selected network. It then returns a detailed response on the simulated transaction execution and provides you with a detailed overview of transferred assets.

The Snap also enables you to examine a simulated transaction in greater detail on Tenderly. Simply click the link to the Tenderly Dashboard, where you can find more information on emitted events, state changes, gas consumption, and more.

Finally, transactions simulated using Tenderly TX Preview Snap are publicly sharable. You can share them with your team or associates even if they don’t have a Tenderly account.

## How to install the Tenderly TX Preview Snap?

To install the Tenderly TX Preview Snap, follow these steps:

1. Create a [free Tenderly account](https://dashboard.tenderly.co/register/) or log in if you already have one.
2. [Go to the Authorization page](https://dashboard.tenderly.co/account/authorization) to connect to the Snap.
3. Click the **Connect to Tenderly Snap** button, which will open a pop-up.

<figure>
  <img alt="" />

  <figcaption>
    <p>Authorization page on Tenderly Dashboard</p>
  </figcaption>
</figure>

4. Select a different project from the drop-down menu and change the access token label. This is an optional step - you can also use the default project and token label.
5. Click the **Connect** button.

<figure>
  <img alt="" />

  <figcaption>
    <p>Connect to Tenderly Snap instructions</p>
  </figcaption>
</figure>

This automatically installs Tenderly TX Preview Snap and sets up your credentials within your MetaMask wallet so you don’t have to do this manually.

## What does the Tenderly TX Preview Snap NOT do?

Tenderly TX Preview Snap **does not execute** your transactions on-chain. All transactions are simulated against the most recent state of a selected network using the Tenderly Simulation API.

## What networks does Tenderly TX Preview Snap support?

Tenderly TX Preview Snap supports 95 EVM-compatible networks. The list includes major chains such as Ethereum Mainnet and its testnets, Optimism, Arbitrum, Base, and Polygon. Check out the [complete list of supported networks on Tenderly](/platform/supported-networks).

This means that you can simulate transaction execution against any of the networks from the list provided that it’s supported by the dapp or wallet you’re using.

## How to use the Tenderly TX Preview Snap?

After installing the Tenderly TX Preview Snap, you can start using it right away. Just connect to the dapp you typically use and continue using MetaMask as usual. Once you initiate a transaction, you’ll notice an additional tab where you find transaction simulation insights.

## Where can I find simulated transactions?

All simulated transactions are saved within the project created for the account you used to install the Snap. You can find them in the list of simulated transactions on the Simulator page.

For example, if you use an account named “Bob” and create a project “mm-snap”, you can find your simulated transactions on this URL: [https://dashboard.tenderly.co/bob/mm-snap/simulator](https://dashboard.tenderly.co/bob/mm-snap/simulator).

## How do I reach out for snap support?

If you have any questions or come across any issues while installing or using the Tenderly TX Preview Snap, feel free to reach out to us at [metamask.snap@tenderly.co](mailto:metamask.snap@tenderly.co).


# Asset and Balance Changes
Source: https://docs.tenderly.co/simulations/asset-balance-changes

Access token data and dollar value changes from the asset_changes object returned by Simulation API and Transaction Trace.

Both the RPC and API simulation responses provide information about the asset and balance changes that have occurred converted into dollar values. The displayed dollar value represents the **current dollar value** and reflects the most recent market data sourced from [CoinGecko](https://www.coingecko.com/).

Supported token standards: **ERC20** and **ERC721**.

### RPC response

Asset and balance changes are always returned as part of the response when you call both the `tenderly_simulateTransaction` (single simulation) and the `tenderly_simulateBundle` (bundled simulations) RPC methods. See the [RPC Reference](/node-rpc/rpc-reference).

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://mainnet.gateway.tenderly.co/${TENDERLY_NODE_ACCESS_KEY}
```

Follow these paths to access this information:

* **Asset Changes**: Look under `result.assetChanges`. This will provide a breakdown of how assets have been altered or moved during the transaction.
* **Balance Changes**: Find these under `result.balanceChanges`. This offers insights into the balance fluctuations in token and dollar values.

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "assetChanges": [
    {
      "assetInfo": {
        "standard": "ERC20",
        "type": "Fungible",
        "contractAddress": "0xc02...c2",
        "symbol": "weth",
        "name": "WETH",
        "logo": "https://assets.coingecko.com/coins/images/2518/large/weth.webp?1696503332",
        "decimals": 18,
        "dollarValue": "2195.8701171875"
      },
      "type": "Transfer",
      "from": "0xd8...45",
      "to": "0x20...d6",
      "rawAmount": "0x1",
      "amount": "0.000000000000000001",
      "dollarValue": "10.0071875"
    }
  ],
  "balanceChanges": [
    {
      "address": "0x20...1d6",
      "dollarValue": "0.0000021958701171875",
      "transfers": [
        0
      ]
    },
    {
      "address": "0xd8...045",
      "dollarValue": "0.00021958701171875",
      "transfers": [
        0
      ]
    }
  ]
}
```

### API response

Asset and balance changes are also returned as part of the API response when you call the `simulate` (single simulations) endpoint:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate
```

and `simulate-bundle` (bundled simulations) endpoint:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate-bundle
```

In the API response, the structure is similarly intuitive:

* **Asset Changes**: Find `transaction.transaction_info.asset_changes`. Here, you'll find details like the type of change (transfer, mint, burn), involved addresses, and the amount in both the token and its dollar value.
* **Balance Changes**: Find `transaction.transaction_info.balance_changes`. This section will show you how balances have shifted as a result of the transaction in token and dollar terms.

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "asset_changes": [
    {
      "token_info": {
        "standard": "ERC20",
        "type": "Fungible",
        "contract_address": "0xc02...c2",
        "symbol": "weth",
        "name": "WETH",
        "logo": "https://assets.coingecko.com/coins/images/2518/large/weth.webp?1696503332",
        "decimals": 18,
        "dollar_value": "2195.8701171875"
      },
      "type": "Transfer",
      "from": "0xd8...045",
      "to": "0x20...d6",
      "amount": "0.000000000000000001",
      "raw_amount": "1",
      "dollar_value": "0.0000000000000021958701171875"
    }
  ],
  "balance_changes": [
    {
      "address": "0x20...d6",
      "dollar_value": "0.0000000000000021958701171875",
      "transfers": [
        0
      ]
    },
    {
      "address": "0xd...045",
      "dollar_value": "-0.0000000000000021958701171875",
      "transfers": [
        0
      ]
    }
  ]
}
```

For more information, consult the [API reference](/api-reference) and [RPC references](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction).


# Bundled Simulations
Source: https://docs.tenderly.co/simulations/bundled-simulations

Learn how to simulate multiple transactions in a single API or RPC request.

Simulation Bundles enable you to simulate several transactions consecutively. For example, to set a particular
conditions before simulating a desired transaction, you first need to execute several other transactions.

Both [Simulation API](/simulations/bundled-simulations#rpc-bundled-simulations) and [Simulation RPC](/simulations/bundled-simulations#api-bundled-simulations) support bundled simulations. The endpoints receive an array of transactions that get simulated one after another within the same block.

## RPC bundled simulations

[Node RPC](/node-rpc/overview) allows you to read blockchain data and send transactions. But you can also simulate bundled transactions on the Node through a single RPC URL. Simulations via RPC are only available on supported networks. If your network is not supported on Node, run bundled simulations via [Simulation API](/simulations/bundled-simulations#api-bundled-simulations) instead.

Retrieve the RPC URL from the [Dashboard](https://dashboard.tenderly.co/register?redirectTo=gateways).

Go to **Node** > **Copy HTTPS URL** of the desired network.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://mainnet.gateway.tenderly.co/$TENDERLY_NODE_ACCESS_KEY
```

To simulate bundled transactions via RPC, call the `tenderly_simulateBundle` method. This custom method allows you to simulate several transactions by passing them as an array. [See RPC reference](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateBundle).

<Note>
  Transactions are simulated one after the other in the same block.
</Note>

**Example**

<Tabs>
  <Tab title="example">
    ```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
              "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
              "data": "0x40c10f19000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce10000000000000000000000000000000000000000000000001bc16d674ec80000"
            },
            {
              "from": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
              "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
              "gas": "0x7a1200",
              "data": "0x095ea7b3000000000000000000000000f7ddedc66b1d482e5c38e4730b3357d32411e5dd0000000000000000000000000000000000000000000000000de0b6b3a7640000"
            },
            {
              "from": "0xf7ddedc66b1d482e5c38e4730b3357d32411e5dd",
              "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
              "gas": "0x7a1200",
              "data": "0x23b872dd000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1000000000000000000000000bd8daa414fda8a8a129f7035e7496759c5af8570000000000000000000000000000000000000000000000000006a94d74f430000"
            }
          ],
          "latest",
          {
            "0x6b175474e89094c44da98b954eedeac495271d0f": {
              "stateDiff": {
                "0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03": "0x0000000000000000000000000000000000000000000000000000000000000001"
              }
            }
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="response.json">
    ```json title="response.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "id": 0,
      "jsonrpc": "2.0",
      "result": [
        {
          "status": true,
          "gasUsed": "0xd0d9",
          "cumulativeGasUsed": "0x0",
          "blockNumber": "0x121c950",
          "type": "0x0",
          "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000010000000020000000000000000000800000000000000000000000010000000000000000000004000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000000000000000000020000000002000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000",
          "logs": [
            {
              "name": "Transfer",
              "anonymous": false,
              "inputs": [
                {
                  "value": "0x0000000000000000000000000000000000000000",
                  "type": "address",
                  "name": "src"
                },
                {
                  "value": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
                  "type": "address",
                  "name": "dst"
                },
                {
                  "value": "2000000000000000000",
                  "type": "uint256",
                  "name": "wad"
                }
              ],
              "raw": {
                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "topics": [
                  "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                  "0x0000000000000000000000000000000000000000000000000000000000000000",
                  "0x000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1"
                ],
                "data": "0x0000000000000000000000000000000000000000000000001bc16d674ec80000"
              }
            }
          ],
          "trace": [
            {
              "type": "CALL",
              "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
              "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
              "gas": "0xbeb6d8c",
              "gasUsed": "0x7c65",
              "value": "0x0",
              "input": "0x40c10f19000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce10000000000000000000000000000000000000000000000001bc16d674ec80000",
              "decodedInput": [
                {
                  "value": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
                  "type": "address",
                  "name": "usr"
                },
                {
                  "value": "2000000000000000000",
                  "type": "uint256",
                  "name": "wad"
                }
              ],
              "method": "mint",
              "output": "0x",
              "subtraces": 0,
              "traceAddress": []
            }
          ],
          "assetChanges": [
            {
              "assetInfo": {
                "standard": "ERC20",
                "type": "Fungible",
                "contractAddress": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "symbol": "dai",
                "name": "Dai",
                "logo": "https://assets.coingecko.com/coins/images/9956/large/Badge_Dai.webp?1696509996",
                "decimals": 18,
                "dollarValue": "0.9996880292892456"
              },
              "type": "Mint",
              "to": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
              "rawAmount": "0x1bc16d674ec80000",
              "amount": "2",
              "dollarValue": "1.9993760585784912109"
            }
          ],
          "balanceChanges": [
            {
              "address": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
              "dollarValue": "1.9993760585784912109",
              "transfers": [
                0
              ]
            }
          ]
        },
        {
          "status": true,
          "gasUsed": "0xb442",
          "cumulativeGasUsed": "0x0",
          "blockNumber": "0x121c950",
          "type": "0x0",
          "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000200000000000000000000000000008000000000000000000000000000000000000000010000000000000000000020000000000000000000000000000000000000000000000000000004000800000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020000000002000000000000000000000000100010000000000000000000000000000000000000000000000000000000000000",
          "logs": [
            {
              "name": "Approval",
              "anonymous": false,
              "inputs": [
                {
                  "value": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
                  "type": "address",
                  "name": "src"
                },
                {
                  "value": "0xf7ddedc66b1d482e5c38e4730b3357d32411e5dd",
                  "type": "address",
                  "name": "guy"
                },
                {
                  "value": "1000000000000000000",
                  "type": "uint256",
                  "name": "wad"
                }
              ],
              "raw": {
                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "topics": [
                  "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
                  "0x000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1",
                  "0x000000000000000000000000f7ddedc66b1d482e5c38e4730b3357d32411e5dd"
                ],
                "data": "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000"
              }
            }
          ],
          "trace": [
            {
              "type": "CALL",
              "from": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
              "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
              "gas": "0x79bd80",
              "gasUsed": "0x5fc2",
              "value": "0x0",
              "input": "0x095ea7b3000000000000000000000000f7ddedc66b1d482e5c38e4730b3357d32411e5dd0000000000000000000000000000000000000000000000000de0b6b3a7640000",
              "decodedInput": [
                {
                  "value": "0xf7ddedc66b1d482e5c38e4730b3357d32411e5dd",
                  "type": "address",
                  "name": "usr"
                },
                {
                  "value": "1000000000000000000",
                  "type": "uint256",
                  "name": "wad"
                }
              ],
              "method": "approve",
              "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
              "decodedOutput": [
                {
                  "value": true,
                  "type": "bool",
                  "name": ""
                }
              ],
              "subtraces": 0,
              "traceAddress": []
            }
          ]
        },
        {
          "status": true,
          "gasUsed": "0xe38b",
          "cumulativeGasUsed": "0x0",
          "blockNumber": "0x121c950",
          "type": "0x0",
          "logsBloom": "0x00000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000010000000000000000000004000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000040000000000000000000000000002000000000000000000020000000002000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000",
          "logs": [
            {
              "name": "Transfer",
              "anonymous": false,
              "inputs": [
                {
                  "value": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
                  "type": "address",
                  "name": "src"
                },
                {
                  "value": "0xbd8daa414fda8a8a129f7035e7496759c5af8570",
                  "type": "address",
                  "name": "dst"
                },
                {
                  "value": "30000000000000000",
                  "type": "uint256",
                  "name": "wad"
                }
              ],
              "raw": {
                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "topics": [
                  "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                  "0x000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1",
                  "0x000000000000000000000000bd8daa414fda8a8a129f7035e7496759c5af8570"
                ],
                "data": "0x000000000000000000000000000000000000000000000000006a94d74f430000"
              }
            }
          ],
          "trace": [
            {
              "type": "CALL",
              "from": "0xf7ddedc66b1d482e5c38e4730b3357d32411e5dd",
              "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
              "gas": "0x79bc28",
              "gasUsed": "0x8db3",
              "value": "0x0",
              "input": "0x23b872dd000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1000000000000000000000000bd8daa414fda8a8a129f7035e7496759c5af8570000000000000000000000000000000000000000000000000006a94d74f430000",
              "decodedInput": [
                {
                  "value": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
                  "type": "address",
                  "name": "src"
                },
                {
                  "value": "0xbd8daa414fda8a8a129f7035e7496759c5af8570",
                  "type": "address",
                  "name": "dst"
                },
                {
                  "value": "30000000000000000",
                  "type": "uint256",
                  "name": "wad"
                }
              ],
              "method": "transferFrom",
              "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
              "decodedOutput": [
                {
                  "value": true,
                  "type": "bool",
                  "name": ""
                }
              ],
              "subtraces": 0,
              "traceAddress": []
            }
          ],
          "assetChanges": [
            {
              "assetInfo": {
                "standard": "ERC20",
                "type": "Fungible",
                "contractAddress": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "symbol": "dai",
                "name": "Dai",
                "logo": "https://assets.coingecko.com/coins/images/9956/large/Badge_Dai.webp?1696509996",
                "decimals": 18,
                "dollarValue": "0.9996880292892456"
              },
              "type": "Transfer",
              "from": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
              "to": "0xbd8daa414fda8a8a129f7035e7496759c5af8570",
              "rawAmount": "0x6a94d74f430000",
              "amount": "0.03",
              "dollarValue": "0.029990640878677368163"
            }
          ],
          "balanceChanges": [
            {
              "address": "0xbd8daa414fda8a8a129f7035e7496759c5af8570",
              "dollarValue": "0.029990640878677368163",
              "transfers": [
                0
              ]
            },
            {
              "address": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
              "dollarValue": "-0.029990640878677368163",
              "transfers": [
                0
              ]
            }
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## API bundled simulations

Use the `simulate-bundle` API endpoint to simulate multiple consecutive transactions at once. [See API reference](/api-reference).

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate-bundle
```

The simulation output shows the emitted events and state changes the transaction might cause if you send it to the blockchain.

In case a transaction fails, there will be an early return with all simulations up until the failure point.

**Example**

<Tabs>
  <Tab title="Shell">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl --request POST \
      --url https://api.tenderly.co/api/v1/account/me/project/project/simulate-bundle \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --header "X-Access-Key: $TENDERLY_ACCESS_KEY" \
      --data '{
      "simulations": [
        {
          "network_id": "1",
          "save": true,
          "save_if_fails": true,
          "simulation_type": "full",
          "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
          "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
          "input": "0x40c10f19000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce10000000000000000000000000000000000000000000000001bc16d674ec80000",
          "state_objects": {
            "0x6b175474e89094c44da98b954eedeac495271d0f": {
              "storage": {
                "0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03": "0x0000000000000000000000000000000000000000000000000000000000000001"
              }
            }
          }
        },
        {
          "network_id": "1",
          "save": true,
          "save_if_fails": true,
          "simulation_type": "full",
          "from": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
          "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
          "input": "0x095ea7b3000000000000000000000000f7ddedc66b1d482e5c38e4730b3357d32411e5dd0000000000000000000000000000000000000000000000000de0b6b3a7640000"
        },
        {
          "network_id": "1",
          "save": true,
          "save_if_fails": true,
          "simulation_type": "full",
          "from": "0xf7ddedc66b1d482e5c38e4730b3357d32411e5dd",
          "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
          "input": "0x23b872dd000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1000000000000000000000000bd8daa414fda8a8a129f7035e7496759c5af8570000000000000000000000000000000000000000000000000006a94d74f430000"
        }
      ]
    }'
    ```
  </Tab>

  <Tab title="request.ts">
    ```ts title="request.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

    dotenv.config();

    // assuming environment variables TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG and TENDERLY_ACCESS_KEY are set
    const { TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG, TENDERLY_ACCESS_KEY } = process.env;

    const batchedSimulations = async () => {
      console.time('Batch Simulation');

      const daiSequence = (
        await axios.post(
          `https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate-bundle`,
          // the transaction
          {
            simulations: getTxSequence().map((transaction) => ({
              network_id: '1', // network to simulate on
              save: true,
              save_if_fails: true,
              simulation_type: 'full',
              ...transaction,
            })),
          },
          {
            headers: {
              'X-Access-Key': TENDERLY_ACCESS_KEY as string,
            },
          },
        )
      ).data;
      console.timeEnd('Batch Simulation');
      console.log(JSON.stringify(daiSequence, null, 2));
    };

    function getTxSequence() {
      const fakeWardAddress = '0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2';
      const daiOwner = 'e58b9ee93700a616b50509c8292977fa7a0f8ce1';
      const daiSpend = 'f7ddedc66b1d482e5c38e4730b3357d32411e5dd';
      const daiRecip = 'e58b9ee93700a616b50509c8292977fa7a0f8ce1';
      const daiContract = '0x6b175474e89094c44da98b954eedeac495271d0f';
      return [
        // TX1: Mint 2 DAI for e58b9ee93700a616b50509c8292977fa7a0f8ce1.
        // Must do state override so sender (from) is considered a ward for this simulation
        {
          from: fakeWardAddress,
          to: '0x6b175474e89094c44da98b954eedeac495271d0f',
          input:
            '0x40c10f19000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce10000000000000000000000000000000000000000000000001bc16d674ec80000',
          // make 0xcace477c66b1f2e151974eeada9ac8b95a31c50593ae1db2f048f0a2b54c1424 a ward
          state_objects: {
            '0x6b175474e89094c44da98b954eedeac495271d0f': {
              storage: {
                '0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03':
                  '0x0000000000000000000000000000000000000000000000000000000000000001',
              },
            },
          },
        },
        // TX2: e58b9ee93700a616b50509c8292977fa7a0f8ce1 approves 1 DAI to f7ddedc66b1d482e5c38e4730b3357d32411e5dd
        {
          from: '0xe58b9ee93700a616b50509c8292977fa7a0f8ce1',
          to: '0x6b175474e89094c44da98b954eedeac495271d0f',
          input:
            '0x095ea7b3000000000000000000000000f7ddedc66b1d482e5c38e4730b3357d32411e5dd0000000000000000000000000000000000000000000000000de0b6b3a7640000',
        },
        {
          // TX3: 0xf7ddedc66b1d482e5c38e4730b3357d32411e5dd calls transferFrom to transfer 0.5 DAI belonging to e58b9ee93700a616b50509c8292977fa7a0f8ce1, sending them to e58b9ee93700a616b50509c8292977fa7a0f8ce1
          from: '0xf7ddedc66b1d482e5c38e4730b3357d32411e5dd',
          to: '0x6b175474e89094c44da98b954eedeac495271d0f',
          input:
            '0x23b872dd000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1000000000000000000000000bd8daa414fda8a8a129f7035e7496759c5af8570000000000000000000000000000000000000000000000000006a94d74f430000',
        },
      ];
    }

    function getWardStorageLocation(wardAddress: string) {
      // calculate the storage location of `wards[wardAddress]`
      // yields 0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03
      return ethers.utils.keccak256(
        ethers.utils.concat([
          ethers.utils.hexZeroPad(wardAddress, 32), // the ward address (address 0x000..0) - mapping key
          ethers.utils.hexZeroPad('0x0', 32), // the wards slot is 0th in the DAI contract - the mapping variable
        ]),
      );
    }

    batchedSimulations();
    ```
  </Tab>
</Tabs>

## Explore use cases

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

## Where to go next

<Card title="Single simulations" href="" />

<Card title="Simulate via SDK" href="" />


# Gas Estimation
Source: https://docs.tenderly.co/simulations/gas-estimation

Estimate gas with the Simulation API using estimate_gas, or get 100% accurate limits via the tenderly_estimateGas RPC methods before sending.

The Simulation API allows you to simulate transactions and obtain the estimated gas usage needed to successfully execute the transactions.

Set `estimate_gas: true` in the request to get gas estimates.

<Note>
  Note: you can get 100% accurate gas estimates using the [**`tenderly_estimateGas`**](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_estimateGas) and [**`tenderly_estimateGasBundle`**](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_estimateGasBundle) RPC methods.
</Note>

**Example**

Make sure to store the access key securely in a `.env` file.

```ts title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

dotenv.config();

const { TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG, TENDERLY_ACCESS_KEY } = process.env;

const simulateTransaction = async () => {
  const { data } = await axios.post(
    `https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate`,
    {
      // Simulation Configuration
      save: true,
      save_if_fails: false,
      estimate_gas: true,
      simulation_type: 'quick',
      network_id: '1',
      // Standard EVM Transaction object (sample values)
      from: '0xdc6bdc37b2714ee601734cf55a05625c9e512461',
      to: '0x6b175474e89094c44da98b954eedeac495271d0f',
      input: '0x095ea7b3000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1000000000000000000000000000000000000000000000000000000000000012b',
      gas: 8000000,
      gas_price: 0,
      value: 0,
    },
    {
      headers: {
        'X-Access-Key': TENDERLY_ACCESS_KEY as string,
      },
    },
  );

  console.log({ data });
};

simulateTransaction();
```

This calculates the maximum gas needed for the transaction. After a successful simulation, check the `gas_used` field in the `transaction` structure.

**Result**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
"transaction": {
    ...
    "gas": 8000000,
    "gas_price": 0,
    "gas_fee_cap": 0,
    "gas_tip_cap": 0,
    "cumulative_gas_used": 0,
    "gas_used": 51534, // Gas estimates
    "effective_gas_price": 0,
    ...
 }
```


# Dry-Run User Transactions
Source: https://docs.tenderly.co/simulations/guides/dry-run-user-transactions

Learn how to integrate Simulation API to dry-run users' transactions and help them avoid financial losses, frustration, and anxiety when using your dapp.

## Overview

Learn how to use [Simulation API](/simulations/overview) in your dapp to allow users to preview transaction outcomes before sending them on-chain. This way, you can help them avoid financial losses due to failed or incorrect transactions and increase their confidence when using your dapp.

To integrate Tenderly Simulations API into your dapp to detect if a transaction would fail before you even send it on-chain, you need to:

1. Populate raw transactions from ethers.js library.
2. Simulate transactions before sending them.
3. (optional) Wrap every blockchain interaction into a Tenderly simulation.

For the request and response details of an individual call, see [single simulations](/simulations/single-simulations).

### Populate raw transactions from ethers.js

The first step is to create a transaction object that's going to be sent to our simulation endpoint. We're going to generate it directly from the `ethers.js` library. In the example below, we're going to see how we can achieve that for the `transfer()` function on top of a DAI contract:

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const dai = new ethers.Contract(DAI_ADDRESS, DAI_ABI, tenderlyForkProvider);

const unsignedTx = await dai.populateTransaction.transfer(
  ZERO_ADDRESS,
  YOUR_ADDRESS,
  util.ether(1),
);
```

### Simulate transactions before sending

Now that we have extracted an unsigned raw transaction, let's simulate it before sending it on-chain (to the Ethereum Mainnet):

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
...

const body = {
    "network_id": "1",
    "from": senderAddr,
    "to": contract.address,
    "input": unsignedTx.data,
    "gas": 21204,
    "gas_price": "0",
    "value": 0,
    "save_if_fails": true
}

const headers = {
    headers: {
        'content-type': 'application/JSON',
        'X-Access-Key': TENDERLY_ACCESS_KEY,
  }
}
const resp = await axios.post(apiURL, body, headers);

if (resp.data.simulation.status === false) {
	// it failed, do as you please
}
```

### Wrap every blockchain interaction into a Tenderly simulation (optional)

To ensure that every blockchain interaction is simulated first, write a simple wrapper around the `ethers.js` signer object that would always simulate transactions.

Additionally, going forward, you can introduce typed errors with which your logic can interact:

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export class TenderlySimulationSigner {
  public _provider: ethers.Provider;

  constructor(provider: ethers.Provider) {
    this._provider = provider;
  }

  public async sendTransaction(
    transaction: Deferrable<TransactionRequest>,
  ): Promise<TransactionResponse> {
    await this._simulateTx(transaction);

    return this._signer.sendTransaction(transaction);
  }

  public async getAddress(): Promise<string> {
    return this._signer.getAddress();
  }

  public async signTransaction(transaction: Deferrable<TransactionRequest>): Promise<string> {
    return this._signer.signTransaction(transaction);
  }

  _simulateTx(transaction: Deferrable<TransactionRequest>): Promise<void> {
    const unsignedTx = await contract.populateTransaction[funcName](...args);

    const apiURL = `https://api.tenderly.co/api/v1/account/me/project/project/simulate`;
    const body = {
      network_id: '1',
      from: senderAddr,
      to: contract.address,
      input: unsignedTx.data,
      gas: 21204,
      gas_price: '0',
      value: 0,
      save_if_fails: true,
    };

    const headers = {
      headers: {
        'content-type': 'application/JSON',
        'X-Access-Key': REACT_APP_TENDERLY_ACCESS_KEY as string,
      },
    };
    const resp = await axios.post(apiURL, body, headers);
    if (resp.data.simulation.status == false) {
      throw new Error('Transaction is going to fail');
    }

    return;
  }
}
```

<Info>
  Here's a [GitHub
  repo](https://github.com/Tenderly/integration-samples/tree/main/dry-run-transactions) where you
  can find an example of this implementation.
</Info>


# MetaMask Snap Transaction Preview
Source: https://docs.tenderly.co/simulations/guides/metamask-snap

Add transaction preview to MetaMask via a Snap using the Tenderly Simulation API so users can preview outcomes before signing.

This tutorial demonstrates how to add a "transaction preview" option to a wallet using [Tenderly Simulation API](/api-reference). We’ll show you how to add this option to the MetaMask wallet.

The "[transaction preview](/simulations/transaction-preview)" feature allows users to see the exact outcome of their transactions before submitting them to the production network. Wallets equipped with this feature make it easier for users to understand the financial implications of their transactions before making a commitment.

Simulations are executed on a fork of the latest state of the blockchain in a safe, risk-free environment. This helps wallet users prevent sending malicious or error-prone transactions.

You can find the complete demo repository on GitHub:

<Card title="Tenderly Simulate Asset Changes Snap" href="" />

<iframe />

Tenderly MetaMask Snap Demo

<Warning>
  This tutorial is for demonstration purposes only, specifically to illustrate how to add a
  transaction preview option to a MetaMask Snap. It is not intended nor recommended for any other
  usage.
</Warning>

## Project overview

This project shows you how to integrate transaction simulations into the MetaMask wallet. We’ll be working with [MetaMask Snaps](https://metamask.io/snaps/).

You’ll learn how to connect to the [Tenderly Simulation API](/api-reference), send the transaction data, retrieve the simulation results, and display them to the user via the MetaMask UI. This includes asset changes in dollars, native-asset balance changes, output value, storage changes, event logs, and call traces.

Simulated transactions can then also be opened in Tenderly for further debugging and testing.

Below is a list of features that we’ll be adding to the MetaMask Snap. Similar features can also be added to any wallet to help users build confidence when sending transactions.

<br />

| Feature                                     | Description                                                                                  |
| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Simulation debugging**                    | Auto-generated link to inspect and debug the simulation in Tenderly.                         |
| **Publicly sharable simulations**           | Ability to enable/disable public sharing of simulations.                                     |
| **Asset changes displayed in dollar value** | Human-readable data, including asset changes automatically converted into dollars.           |
| **Native-asset balance changes**            | Ability to track changes in their native-asset balance during the execution of the contract. |
| **Output value**                            | See the result of the contract call, displaying what the contract is set to return.          |
| **Storage changes**                         | See any changes made to the contract's storage during the execution.                         |
| **Event logs**                              | See events that were emitted during the contract's execution.                                |
| **Call traces**                             | Breakdown of all the function calls that happened during the execution.                      |

### Prerequisites

* [MetaMask Flask](https://chromewebstore.google.com/detail/metamask-flask-developmen/ljfoeinjpaedjfecbmggjgodbgkmjkjk) browser extension installed
* [Node.js](https://nodejs.org) (version 16 or later)
* [Yarn](https://classic.yarnpkg.com/lang/en/docs/install) (version 3)

<Note>
  Before you start building the MetaMask Snap, make sure to disable the "real" version of MetaMask
  and [install the MetaMask Flask Development
  Plugin](https://chromewebstore.google.com/detail/metamask-flask-developmen/ljfoeinjpaedjfecbmggjgodbgkmjkjk).
</Note>

Let’s start building! 👷‍♂️

## Step 1: Setting up a MetaMask Snap project

Install MetaMask’s official [Create Snap CLI](https://docs.metamask.io/snaps/get-started/quickstart) and create a new project.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
yarn create @metamask/snap project-name

OR

npm create @metamask/snap project-name
```

Next, we need to start the Snap project and serve the front end on [https://localhost:8000](https://localhost:8000/).

From the root of the newly created project, install the project dependencies using Yarn.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
yarn
```

Start the development server.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
yarn start
```

### Setting the correct permissions

Once you’ve installed the Snap, find the `/packages/snap/snap.manifest.json` file and set the permissions as shown below. Learn about MetaMask permissions [here](https://docs.metamask.io/snaps/reference/permissions/).

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  // ...
  "initialPermissions": {
    "snap_dialog": {},
    "endowment:rpc": {
      "dapps": true,
      "snaps": false
    },
    "endowment:transaction-insight": {
      "allowTransactionOrigin": true
    },
    "endowment:network-access": {},
    "snap_manageState": {},
    "endowment:ethereum-provider": {
      "dapps": true,
      "snaps": true
    }
  }
}
```

When you run the app and try to connect the wallet, a permission request will pop up.

Click **Connect** and **Approve & install** buttons to continue.

<Frame>
  <img alt="Install MetaMask Snap Permissions" />
</Frame>

## Step 2: Generating Tenderly API access tokens

The transaction preview option in the MetaMask Snap is powered by the Tenderly Simulation API.

Before you can start using the API, you need to generate access tokens. Follow these steps:

1. [Log into Tenderly or create a free account here](https://dashboard.tenderly.co/register).
2. Go to the [Authorization page](https://dashboard.tenderly.co/account/authorization) and click on the **Generate Access Token** button.

If you need help with API authentication, please follow this guide:

<Card title="How to Generate API Access Tokens" href="" />

<Frame>
  <img alt="Generate Access Token from Authorization page" />
</Frame>

## Step 3: Writing the logic for the Snap

The core logic that makes the Snap work is stored in three files:

* **Credentials Access** (`credentials-access.ts`)**:** Manages the Tenderly API authentication and access.
* **Simulation** (`simulation.ts`)**:** The core logic for interacting with the Tenderly API to simulate transactions and fetch simulation results.
* **Formatter** (`formatter.ts`)**:** Logic for parsing simulation results and formatting them in a user-friendly way in the MetaMask UI.

### Credentials Access

We can store all methods responsible for requesting, updating, and fetching Tenderly API credentials in a file called **credentials-access.ts**. [View the source code here](https://github.com/Tenderly/tenderly-metamask-snap-simulate-asset-changes/blob/main/packages/snap/src/tenderly/credentials-access.ts).

The most important methods include:

* **`fetchCredentials()`**: This function retrieves the credentials of a Tenderly project. If no credentials are stored, it triggers `handleUpdateTenderlyCredentials` to request new ones.
* **`handleUpdateTenderlyCredentials()`**: This function handles the process of updating Tenderly project credentials. It gets new credentials by calling `requestNewTenderlyCredentials` and then saves them using the `snap_manageState` method with an `'update'` operation.
* **`requestNewTenderlyCredentials()`**: This function requests new Tenderly credentials. It calls `requestCredentials` to receive the raw credentials data and verifies its correctness before returning an object with `accountId`, `projectId`, and `accessToken`.

<Note>
  **snap\_manageState** is a built-in method that allows the Snap to persist up to 100 MB of data to
  the disk. Learn more [here](https://docs.metamask.io/snaps/reference/snaps-api/#snap_managestate).
</Note>

### Simulation

Next, we need to create the logic that sends transaction data to the [Tenderly Simulation API](/api-reference), simulates it, and retrieves the results.

We’ll use the **`simulate`** API endpoint for that.

Endpoint: `https://api.tenderly.co/api/v1/account/{accountId}/project/{projectId}/simulate`

To keep things organized, let’s store the simulation logic in a file called **simulation.ts**. [View the source code here.](https://github.com/Tenderly/tenderly-metamask-snap-simulate-asset-changes/blob/main/packages/snap/src/tenderly/simulation.ts)

To send transaction data to the Tenderly Simulation API, we need to create two key methods:

* **simulate()**: This is the main function that handles the simulation of a transaction. It fetches the API access credentials, submits the transaction data to the Tenderly Simulation API, and handles any errors returned by the API.

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export async function simulate(
  transaction: { [key: string]: Json },
  transactionOrigin: string,
): Promise<Panel> {
  const credentials = await fetchCredentials(transactionOrigin);

  if (!credentials) {
    return panel([text('🚨 Tenderly access token updated. Please try again.')]);
  }

  const simulationResponse = await submitSimulation(transaction, credentials);
  const err = catchError(simulationResponse, credentials);

  return err || formatResponse(simulationResponse, credentials);
}
```

* **submitSimulation()**: This function sends a request to the API along with the transaction data to be simulated.

When the transaction is simulated, we can make it publicly accessible by calling the share API endpoint. Making the simulation shareable allows you to copy the link to the transaction and send it to anyone. Shared transactions can be viewed without a Tenderly account.

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
async function submitSimulation(
  transaction: { [key: string]: Json },
  credentials: TenderlyCredentials,
) {
  const chainId = await ethereum.request({ method: 'eth_chainId' });
  const response = await fetch(
    `https://api.tenderly.co/api/v1/account/${credentials.accountId}/project/${credentials.projectId}/simulate`,
    {
      method: 'POST',
      body: JSON.stringify({
        from: transaction.from,
        to: transaction.to,
        input: transaction.data,
        gas: hex2int(transaction.gas),
        value: hex2int(transaction.value),
        network_id: hex2int(chainId as string),
        save: true,
        save_if_fails: true,
        simulation_type: 'full',
        generate_access_list: false,
        source: 'tenderly-metamask-snap',
      }),
      headers: {
        'Content-Type': 'application/json',
        'X-Access-Key': credentials.accessToken,
      },
    },
  );

  const parsedResponse = await response.json();

  // Make the simulation publicly accessible
  if (parsedResponse?.simulation?.id) {
    await fetch(
      `https://api.tenderly.co/api/v1/account/${credentials.accountId}/project/${credentials.projectId}/simulations/${parsedResponse.simulation.id}/share`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Access-Key': credentials.accessToken,
        },
      },
    );
  }

  return parsedResponse;
}
```

### Formatter

Once the API returns the simulation results, we need to parse this data and format it in a user-friendly way to be displayed in the MetaMask UI.

We can store this logic in a file called **formatter.ts**. [View the source code here.](https://github.com/Tenderly/tenderly-metamask-snap-simulate-asset-changes/blob/main/packages/snap/src/tenderly/formatter.ts)

The core formatting methods include:

* **`formatResponse()`**: This function receives the raw data and credentials of a Tenderly project simulation, calls the individual formatter functions for each relevant section (like balance changes, output value, asset changes, etc.), and returns a panel with all the formatted outputs.
* **`formatBalanceDiff()`**: This function generates a panel showing balance changes for each account involved in the transaction.
* **`formatOutputValue()`**: This function creates a panel that presents the output values of the transaction if any exist. It also decodes the output, if possible.
* **`formatAssetChanges()`**: This function formats a panel to show any asset changes, differentiating between ERC20, ERC721, and other changes.
* **`formatStorageChanges()`**: This function creates a panel that lists any changes to storage that occurred during the transaction. It uniquely formats addresses and nested data structures for clarity.
* **`formatEventLogs()`**: This function presents the event logs, if they exist, for each transaction. The logs are formatted for readability and include input values.
* **`formatCallTrace()`**: This function produces a formatted visual hierarchy of call traces, showing nested calls recursively.
* **`formatSimulationUrl()`**: This function returns a link to the full details of the simulation on the Tenderly Dashboard and a separate shareable link.

## Step 4: Displaying simulation data in the MetaMask UI

The [MetaMask Snap mono repo](https://github.com/MetaMask/template-snap-monorepo) provides a set of predefined UI elements and layout configurations. We'll use these elements to extend the existing MetaMask UI to display the simulation results.

When you install our MetaMask example, we show you how to run different types of simulations:

* **Successful transaction simulation** with a predefined payload (successful ERC-20 transfer and NFT transfer)
* **Failed transaction simulation** with a predefined payload
* **Custom transaction simulation** with any payload

<Frame>
  <img alt="Tenderly Snap UI" />
</Frame>

For the purpose of this tutorial, we’ll show you how to run simulations with a predefined payload and how to add your custom payload and execute the simulation.

### Successful simulation with a predefined payload

To initiate a simulation, we’ll write a function that will send the predefined transaction data from our wallet address and call the `eth_sendTransaction` RPC method.

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// packages/site/src/utils/snap.ts

export const sendTransaction = async (data: any): Promise<any> => {
  try {
    const [from] = (await window.ethereum.request({
      method: 'eth_requestAccounts',
    })) as string[];

    if (!from) {
      return Promise.reject(Error('Failed to get an account'));
    }

    // https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendtransaction
    return window.ethereum.request({
      method: 'eth_sendTransaction',
      params: [
        {
          ...data,
          from,
        },
      ],
    });
  } catch (e) {
    console.error(e);
    return e;
  }
};
```

The `eth_sendTransaction` method call will trigger the `onTransaction` handler, which will call our custom `simulate` function, which was defined in `simulation.ts`.

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// packages/snap/src/index.ts

export const onTransaction: OnTransactionHandler = async ({ transaction, transactionOrigin }) => {
  if (!isObject(transaction) || !hasProperty(transaction, 'to')) {
    return {
      content: {
        value: 'Unknown transaction type',
        type: NodeType.Text,
      },
    };
  }

  const simulationResponse = await simulate(transaction, transactionOrigin || '');

  return {
    content: {
      children: simulationResponse.children,
      type: NodeType.Panel,
    },
  };
};
```

In the `onTransaction` handler, the `simulate` function is called with the transaction and its origin as arguments.

The `simulate` function is responsible for fetching access credentials, submitting the transaction data to the Tenderly API, handling any errors, and formatting the API response for output.

The results of the simulation are displayed within the MetaMask UI. The images below show a successful ERC20 token transfer of 1 USDC to `demo.eth`. The output is generated by the functions defined in the `formatter.ts` file.

<Frame>
  <img alt="ERC20 Transfer - send 1 USDC to demo.eth" />
</Frame>

For example, the **Asset Changes** block, which shows us the dollar value changes resulting from the simulation, is generated by the `formatAssetChanges()` function.

You also get a link to the simulated transaction which you can open in Tenderly and inspect it further with [Debugger](/debugger/overview) or resimulate it with different values.

This link is generated by the `formatSimulationUrl()` function defined in the `formatter.ts` file.

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export function formatSimulationUrl(data: any, credentials: TenderlyCredentials): Component[] {
  const simulationUrl = `https://dashboard.tenderly.co/${credentials.accountId}/${credentials.projectId}/simulator/${data.simulation?.id}`;
  const sharedSimulationUrl = `https://tdly.co/shared/simulation/${data.simulation?.id}`;

  return [
    heading('Tenderly Dashboard:'),
    text('See full simulation details in Tenderly.'),
    text(`**Status:** ${data.transaction?.status ? 'Success ✅' : 'Failed ❌'}`),
    copyable(`${simulationUrl}`),
    text('Share simulation details with others! 🤗'),
    copyable(`${sharedSimulationUrl}`),
  ];
}
```

### Failed transaction with a predefined payload

For the second example, we’ll simulate a failed transaction with a predefined payload.

The image below shows a failed ERC20 token transfer of 1,000,000 USDC to `demo.eth`.

<Frame>
  <img alt="Preview of the failed transaction" />
</Frame>

We also get a link to the Tenderly Dashboard, where the user can inspect the stack trace, events, state changes, gas consumption, etc. This is particularly useful for understanding why the transaction failed.

The user can smoothly continue debugging the failed transaction and resimulating it to test different solutions.

### Simulation with a custom payload

To run a simulation with a custom payload, you need to add an object that aligns with the [Ethereum transaction specification](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendtransaction).

<Frame>
  <img alt="Custom payload UI" />
</Frame>

It can contain the following fields:

* `from`: `DATA`, 20 Bytes - The address the transaction is sent from.
* `to`: `DATA`, 20 Bytes - (optional when creating a new contract) The address the transaction is directed to.
* `gas`: `QUANTITY` - (optional, default: 90000) Integer of the gas provided for the transaction execution. It will return unused gas.
* `gasPrice`: `QUANTITY` - (optional, default: To-Be-Determined) Integer of the `gasPrice` used for each paid gas.
* `value`: `QUANTITY` - (optional) Integer of the value sent with this transaction.
* `data`: `DATA` - The compiled code of a contract OR the hash of the invoked method signature and encoded parameters.
* `nonce`: `QUANTITY` - (optional) Integer of a nonce. This allows you to overwrite your own pending transactions that use the same nonce.

All numerical values should be hexadecimal strings, and addresses should be Ethereum addresses (20 bytes).

<Frame>
  <img alt="Send a custom payload" />
</Frame>

After entering the custom payload, users can initiate the simulation using the same `sendTransaction` function as before. This passes the custom payload to the `onTransaction` handler, which then triggers the `simulate` function to run the simulation.

## Next steps

In this tutorial, you learned how to add a transaction preview option to a MetaMask Snap powered by the Tenderly Simulation API. You can find the [source code for this project on GitHub](https://github.com/Tenderly/tenderly-metamask-snap-simulate-asset-changes).

Transaction simulation on Tenderly can be initiated in three ways, depending on your project and needs. Learn how to integrate simulations into your dapps with these help resources:

<Card title="Simulation UI" href="" />

<Card title="Simulation API" href="" />

<Card title="Simulation RPC" href="" />


# Simulate a Token Mint, Approve, and TransferFrom Bundle
Source: https://docs.tenderly.co/simulations/guides/mint-approve-transfer-bundle

Simulate a 3-step bundle that mints DAI, approves a spender, and transfers tokens, with shared state across steps for testing multi-transaction flows.

This guide builds a 3-step simulation bundle that exercises the classic ERC-20 approval flow: mint tokens to a holder, approve a spender, then let the spender call `transferFrom`. Each step depends on state that the previous step creates, which is why a bundle is the right tool here.

## Why a bundle?

Simulating each transaction in isolation breaks down:

* **Mint alone**: you can verify the mint logic, but the holder address has no tokens on mainnet.
* **Approve alone**: the simulation needs the holder to actually have a balance to approve from.
* **TransferFrom alone**: requires both the balance and the approval to be in place.

A Sim Bundle runs all three in sequence, sharing the resulting state. Step 2 sees the minted balance from step 1. Step 3 sees the approval from step 2.

## The three transactions

All three transactions target the DAI contract on Ethereum mainnet (`0x6b175474e89094c44da98b954eedeac495271d0f`).

### Step 1: Mint 2 DAI

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
From:  0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2  (fake ward)
To:    0x6b175474e89094c44da98b954eedeac495271d0f  (DAI)
Input: 0x40c10f19
       000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1  (recipient)
       0000000000000000000000000000000000000000000000001bc16d674ec80000  (2 DAI)
```

DAI's `mint` function is guarded by a `wards` mapping: only addresses registered as wards can call it. The fake ward (`0xe2e2...e2`) is not a ward on mainnet. To make this step succeed, add a **state override** that sets the ward storage slot for that address to `1`:

| Field       | Value                                                                |
| ----------- | -------------------------------------------------------------------- |
| Contract    | `0x6b175474e89094c44da98b954eedeac495271d0f`                         |
| Storage key | `0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03` |
| Value       | `0x0000000000000000000000000000000000000000000000000000000000000001` |

The storage key is `keccak256(abi.encode(wardAddress, 0))`, the standard Solidity mapping slot for `wards[fakeWardAddress]` at storage position `0`.

### Step 2: Approve 1 DAI

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
From:  0xe58b9ee93700a616b50509c8292977fa7a0f8ce1  (token holder from step 1)
To:    0x6b175474e89094c44da98b954eedeac495271d0f  (DAI)
Input: 0x095ea7b3
       000000000000000000000000f7ddedc66b1d482e5c38e4730b3357d32411e5dd  (spender)
       0000000000000000000000000000000000000000000000000de0b6b3a7640000  (1 DAI)
```

The holder approves a spender to pull up to 1 DAI. This step works because step 1 already credited 2 DAI to the holder's balance in the shared state stream.

### Step 3: TransferFrom 0.03 DAI

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
From:  0xf7ddedc66b1d482e5c38e4730b3357d32411e5dd  (approved spender)
To:    0x6b175474e89094c44da98b954eedeac495271d0f  (DAI)
Input: 0x23b872dd
       000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1  (sender / token holder)
       000000000000000000000000bd8daa414fda8a8a129f7035e7496759c5af8570  (recipient)
       000000000000000000000000000000000000000000000000006a94d74f430000  (0.03 DAI)
```

The spender moves 0.03 DAI from the holder to a recipient. This works because step 2 granted the allowance, which is only visible inside the bundle's state stream, not on-chain.

## Run via the Simulator UI

<Steps>
  <Step title="Open the Sim Bundle Builder">
    Go to **Simulator** in the left navigation, then click **New Simulation**. The bundle builder opens with one empty step.
  </Step>

  <Step title="Configure the session strip">
    The session strip runs across the top. Set **Network** to **Mainnet** and leave **Block** as **Pending**.
  </Step>

  <Step title="Fill Step 1: Mint">
    Switch the step to **Raw** mode. Set:

    * **From**: `0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2`
    * **To**: `0x6b175474e89094c44da98b954eedeac495271d0f`
    * **Calldata**: `0x40c10f19000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce10000000000000000000000000000000000000000000000001bc16d674ec80000`

    Then expand **State overrides**, add the DAI contract, and enter the ward storage slot and value from the table above. Click **Add storage override** to commit the slot.

    <Frame>
      <img alt="Step 1 mint transaction configured with state override" />
    </Frame>
  </Step>

  <Step title="Add Step 2: Approve">
    Click **+ Add function call** in the bundle rail. Switch the new step to **Raw** mode. Set:

    * **From**: `0xe58b9ee93700a616b50509c8292977fa7a0f8ce1`
    * **To**: `0x6b175474e89094c44da98b954eedeac495271d0f`
    * **Calldata**: `0x095ea7b3000000000000000000000000f7ddedc66b1d482e5c38e4730b3357d32411e5dd0000000000000000000000000000000000000000000000000de0b6b3a7640000`
  </Step>

  <Step title="Add Step 3: TransferFrom">
    Add another step. Switch to **Raw** mode. Set:

    * **From**: `0xf7ddedc66b1d482e5c38e4730b3357d32411e5dd`
    * **To**: `0x6b175474e89094c44da98b954eedeac495271d0f`
    * **Calldata**: `0x23b872dd000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1000000000000000000000000bd8daa414fda8a8a129f7035e7496759c5af8570000000000000000000000000000000000000000000000000006a94d74f430000`
  </Step>

  <Step title="Run the bundle">
    Click **Simulate** (or press `⌘↵`). All three steps execute in sequence. Click each step in the rail to inspect its decoded output, gas used, events, and token transfers.

    <Frame>
      <img alt="Step 2 approve result showing the Approval event" />
    </Frame>

    <Frame>
      <img alt="Step 3 transferFrom result showing the DAI transfer" />
    </Frame>
  </Step>
</Steps>

## Run via the Simulation API

Use the `simulate-bundle` endpoint to run the same sequence programmatically. Replace `{accountSlug}` and `{projectSlug}` with your values.

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl --request POST \
  --url https://api.tenderly.co/api/v1/account/{accountSlug}/project/{projectSlug}/simulate-bundle \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: <api-key>' \
  --data '{
  "simulations": [
    {
      "network_id": "1",
      "save": true,
      "save_if_fails": true,
      "simulation_type": "full",
      "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
      "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "input": "0x40c10f19000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce10000000000000000000000000000000000000000000000001bc16d674ec80000",
      "state_objects": {
        "0x6b175474e89094c44da98b954eedeac495271d0f": {
          "storage": {
            "0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03": "0x0000000000000000000000000000000000000000000000000000000000000001"
          }
        }
      }
    },
    {
      "network_id": "1",
      "save": true,
      "save_if_fails": true,
      "simulation_type": "full",
      "from": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1",
      "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "input": "0x095ea7b3000000000000000000000000f7ddedc66b1d482e5c38e4730b3357d32411e5dd0000000000000000000000000000000000000000000000000de0b6b3a7640000"
    },
    {
      "network_id": "1",
      "save": true,
      "save_if_fails": true,
      "simulation_type": "full",
      "from": "0xf7ddedc66b1d482e5c38e4730b3357d32411e5dd",
      "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "input": "0x23b872dd000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1000000000000000000000000bd8daa414fda8a8a129f7035e7496759c5af8570000000000000000000000000000000000000000000000000006a94d74f430000"
    }
  ]
}'
```

The response is an array of three simulation results, one per step. Each entry contains `status`, `gasUsed`, decoded `logs`, a `trace`, `assetChanges`, and `balanceChanges`.

A successful run shows `"status": true` for all three steps. If a step reverts (for example, because the state override is missing from step 1), the API returns all results up to and including the failing step, and subsequent steps are not run.

## What to look for in the results

| Step         | Key signals                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mint         | `assetChanges` entry with `"type": "Mint"` and 2 DAI credited to the holder. `Transfer` event from the zero address.                                                                                            |
| Approve      | `Approval` event in `logs`. No asset changes (approvals don't move tokens).                                                                                                                                     |
| TransferFrom | `assetChanges` entry with `"type": "Transfer"` and 0.03 DAI moving from holder to recipient. `Transfer` event in `logs`. `balanceChanges` showing negative delta for the holder and positive for the recipient. |

## Next steps

* [Bundled Simulations (API reference)](/simulations/bundled-simulations): full endpoint documentation and response schema.
* [State overrides](/simulations/state-overrides): how to override storage, balance, and bytecode in simulations.
* [Simulator UI](/simulator-ui/overview): layout reference and keyboard shortcuts for the bundle builder.


# Rabby Wallet Transaction Preview
Source: https://docs.tenderly.co/simulations/guides/rabby-wallet

Add transaction preview to Rabby Wallet using the Tenderly Simulation API so users can preview outcomes before sending on-chain.

This tutorial shows how to integrate a "transaction preview" feature into a Rabby Wallet example using the [Tenderly Simulation API](/api-reference).

[Transaction Preview](/simulations/transaction-preview) enables wallet users to simulate transaction execution and preview the exact outcomes without sending transactions on-chain. This way, users can better understand the financial implications of their transactions and send them with confidence. Additionally, you help protect users’ funds, eliminate unnecessary gas costs, and improve the overall user experience and security of your product.

Here’s the GitHub repository of this open-source example:

<Card title="Integrate Tenderly Transaction Simulations Into Rabby Wallet" href="" />

<iframe />

Tenderly Rabby Transaction Preview Demo

<Warning>
  This tutorial is solely for illustrative purposes, showcasing how to integrate Transaction Preview
  into Rabby Wallet. It’s not intended or recommended for any other usage.
</Warning>

## Project overview

In this tutorial, you’ll learn how to integrate the Tenderly Simulation API into the [Rabby Wallet Chrome extension](https://github.com/RabbyHub/Rabby/blob/develop/README.md). First, you’ll learn how to interact with the API and implement the transaction simulation logic. Then, you’ll group the simulation data and expose it to the user. This way, you’ll improve the user experience in this Rabby Wallet example by adding new functionalities.

### Prerequisites

For this tutorial, you need:

* [Node.js](https://nodejs.org) (version 14 or later)
* [Yarn](https://classic.yarnpkg.com/lang/en/docs/install)
* Knowledge of React.js, TypeScript, and [Tailwind CSS](https://tailwindcss.com)

Let’s start building! 👷‍♂️

## Step 1: Clone the Rabby Wallet project

First, fork or clone the official Rabby Wallet GitHub repository. To do this, run:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
git clone https://github.com/RabbyHub/Rabby.git
```

Next, navigate to the project root and install the dependencies using the Yarn package manager:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
yarn install
```

Then, use the following command to run the repo locally:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
yarn build:dev
```

The `dist` folder will be generated. You can use it to load your Chrome extension.

Go to `chrome://extensions` and enable **Developer mode**. Then, click the "**Load unpacked**" button, navigate to your Rabby directory, and select the `dist` folder. The unpacked extension will be visible on the screen, and you can start using Rabby Wallet.

Now, you can import your existing wallet or create a new one.

<Note>
  Before you start, make sure to disable the production version of the Rabby Wallet Chrome Extension if you have it installed.

  Please follow the [official guidelines](https://github.com/RabbyHub/Rabby) from the Rabby team in case you encounter any connection issues.
</Note>

<Frame>
  <img alt="Enabled unpacked version of the Rabby Wallet" />
</Frame>

<Frame>
  <img alt="Disabled production version of the Rabby Wallet" />
</Frame>

## Step 2: Generate a Tenderly access token

To use the Tenderly Simulation API, you need to generate an access token. Follow these steps:

1. [Create a free Tenderly account](https://dashboard.tenderly.co/register) or log into your existing one.
2. Go to the [Authorization page](https://dashboard.tenderly.co/account/authorization) and click the **Generate Access Token** button.
3. The token secret is displayed only once. Be sure to copy and store it somewhere safe as you won’t be able to retrieve it later.

<figure>
  !\[Tenderly Docs]\(/images/image (113).webp)

  <figcaption />
</figure>

Follow the guide below if you need any help with the API authentication process:

<Card title="How to Generate API Access Tokens" href="" />

## Step 3: Build the simulation logic

Next, we’ll cover the following steps:

* Set up a secure storage system for the Tenderly credentials.
* Create the necessary code to connect with the Tenderly Simulation API.
* Use both private and public endpoints to interact with the API.
* Construct a proper payload for these endpoints.

### Handling Tenderly Credentials

First, you need to retrieve the Tenderly credentials. Create a file `/_raw/tenderly.json` and update the Tenderly credentials:

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "tenderlyAccount": "YOUR_ACCOUNT_NAME",
  "tenderlyProject": "YOUR_PROJECT_NAME",
  "tenderlyAccessToken": "YOUR_ACCESS_TOKEN"
}
```

To access the Tenderly credentials in your project, you need to update `build/webpack.common.config.js` with the following:

```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const { tenderlyAccount, tenderlyProject, tenderlyAccessToken } = require('../_raw/tenderly.json');

// other code...

const config = {
  plugins: [
    // abbreviated
    new webpack.DefinePlugin({
      'process.env.version': JSON.stringify(`version: ${version}`),
      'process.env.release': JSON.stringify(version),
      // Tenderly Credentials
      'process.env.TENDERLY_ACCOUNT_SLUG': JSON.stringify(tenderlyAccount),
      'process.env.TENDERLY_PROJECT_SLUG': JSON.stringify(tenderlyProject),
      'process.env.TENDERLY_ACCESS_TOKEN': JSON.stringify(tenderlyAccessToken),
    }),
  ],
  resolve: {
    // abbreviated
  },
};
```

You can [find the implementation here](https://github.com/Tenderly/tenderly-rabby-transaction-preview/blob/develop/build/webpack.common.config.js#L221).

### Implementing the transaction simulation logic

Next, create a `src/ui/utils/tenderly.ts` file and implement the logic using the Tenderly Simulation API. [Get the complete source code here](https://github.com/Tenderly/tenderly-rabby-transaction-preview/blob/develop/src/ui/utils/tenderly.ts).

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

export const simulateTransaction = async (tx: Tx): Promise<Record<string, any> | null> => {
  const TENDERLY_ACCOUNT_SLUG = process.env.TENDERLY_ACCOUNT_SLUG;
  const TENDERLY_PROJECT_SLUG = process.env.TENDERLY_PROJECT_SLUG;
  const TENDERLY_ACCESS_TOKEN = process.env.TENDERLY_ACCESS_TOKEN;

  if (!TENDERLY_ACCOUNT_SLUG || !TENDERLY_PROJECT_SLUG || !TENDERLY_ACCESS_TOKEN) {
    throw new Error('Tenderly credentials are not set up correctly.');
  }

  const txPayload: any = {
    ...tx,
    save: true,
    save_if_fails: true,
    simulation_type: 'full',
    source: 'rabby-wallet',
    network_id: tx.chainId.toString(),
    gas: parseInt(tx.gas as string, 16) || null,
    gas_price: parseInt(tx.gasPrice as string, 16) || null,
    value: parseInt(tx.value, 16) || null,
    input: tx.data,
  };

  try {
    const simulationResponse = await axios.post(
      `https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate`,
      txPayload,
      {
        headers: {
          'Content-Type': 'application/json',
          'X-Access-Key': TENDERLY_ACCESS_TOKEN as string,
        },
      },
    );

    // Make the simulation publicly accessible
    if (simulationResponse?.data?.simulation?.id) {
      await axios.post(
        `https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulations/${simulationResponse.data.simulation.id}/share`,
        {},
        {
          headers: {
            'Content-Type': 'application/json',
            'X-Access-Key': TENDERLY_ACCESS_TOKEN as string,
          },
        },
      );
    }

    return simulationResponse?.data;
  } catch (e) {
    console.error({ e });
    return null;
  }
};
```

Here, we used two endpoints.

The first endpoint allows you to simulate a transaction with different parameters on any of the [95 networks](/platform/supported-networks) supported by Tenderly. Go to our [Simulation API reference](/api-reference) to see all required and optional fields for this endpoint.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://api.tenderly.co/api/v1/account/{accountId}/project/{projectId}/simulate
```

The second endpoint enables you to make a simulated transaction publicly accessible. This way, you can share it with your team members or associates for additional insights or quick issue resolution.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://api.tenderly.co/api/v1/account/{accountId}/project/{projectId}/simulations/{simulationID}/share
```

The last step is to call the `simulateTransaction` function within the `SignTx.tx` component by placing it inside the `explainTx` function, which is invoked before a transaction is signed. For code details, refer to this [link](https://github.com/Tenderly/tenderly-rabby-transaction-preview/blob/develop/src/ui/views/Approval/components/SignTx.tsx#L911).

## Step 4: Display a simulated transaction preview

To help users understand what will happen when sending transactions, you can show human-readable simulation data in the UI. For instance, once wallet users simulate transactions, you can display which assets have been transferred.

In the Rabby Wallet example, we created three easy-to-understand sections:

1. **`Tenderly Simulation Summary`**: Think of this as a transaction report card. It gives you the basic information about your transaction, with a direct link to a detailed simulation overview in the Tenderly Dashboard.
2. **`Assets In & Assets Out`**: Get a clear list of all assets (either ERC20 or NFT tokens) your wallet is about to interact with.
3. **`Tokens Transferred`**: View every token transfer that happens within a transaction. For added clarity, group all transfers by address and highlight native coin transfers.

<Frame>
  <img alt="Transaction preview for ERC20 token swap on Uniswap" />
</Frame>

<Frame>
  <img alt="Transaction preview for NFT token purchase on Joepegs" />
</Frame>

### Tenderly Simulation Summary

First, let’s create the Tenderly Simulation Summary section. Here, we show the simulation status, a network where the transaction is executed, and the gas value.

<figure>
  !\[Tenderly Docs]\(/images/image (116).webp)

  <figcaption />
</figure>

To build this section, you need to interact with the [Tenderly Simulation API response](/api-reference). Start by creating a `TenderlySimulationSummary.tsx` file. You can find the whole code implementation below or in [the GitHub repo here](https://github.com/Tenderly/tenderly-rabby-transaction-preview/blob/develop/src/ui/views/Approval/components/TxComponents/Tenderly/TenderlySimulationSummary/TenderlySimulationSummary.tsx).

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}


const TenderlySimulationSummary = ({ simulation }: { simulation: Record<string, any> | null }) => {
  const isSuccess = !!simulation?.status;
  const simulationUrl = `https://dashboard.tenderly.co/${process.env.TENDERLY_ACCOUNT_SLUG}/${process.env.TENDERLY_PROJECT_SLUG}/simulator/${simulation?.id}`;
  const sharedSimulationUrl = `https://tdly.co/shared/simulation/${simulation?.id}`;

  return (
    <div className="tenderly-simulation-summary container">
      <p className="text-16 text-gray-title font-medium mb-12">Tenderly Simulation Summary</p>
      {!simulation && <div>Something went wrong.</div>}
      {simulation && (
        <div className="flex flex-col gap-8">
          <div className="flex items-center justify-between gap-2">
            <div>Status</div>
            <div className={isSuccess ? 'text-green' : 'text-red'}>
              {isSuccess ? 'Success' : 'Failed'}
            </div>
          </div>
          <div className="flex items-center justify-between gap-2">
            <div>Network</div>
            <div className="flex items-center gap-4">
              <div className="flex items-center rounded-full">
                <img
                  src={TenderlyNetwork[simulation.network_id]?.image}
                  className="h-16 rounded-full"
                  alt="Tenderly"
                />
              </div>
              <div>{TenderlyNetwork[simulation.network_id]?.name}</div>
            </div>
          </div>
          <div className="flex items-center justify-between gap-2">
            <div>Gas</div>
            <div>{simulation.gas}</div>
          </div>
          <Button
            className="tenderly-simulation-summary-button flex items-center justify-between gap-2 pb-0"
            href={simulationUrl}
            target="_blank"
            rel="noreferrer"
            size="large"
            block
          >
            <div>View details</div>
            <div className="flex items-center gap-2">
              <img src={TenderlySvg} className="h-32" alt="Tenderly" />
              <IconRightArrow />
            </div>
          </Button>
          <Button
            className="text-[#6E56CF] bg-white flex items-center justify-center gap-2 pb-0"
            href={sharedSimulationUrl}
            target="_blank"
            rel="noreferrer"
            type="link"
            size="middle"
            block
          >
            <div>Share simulation ✨</div>
          </Button>
        </div>
      )}
    </div>
  );
};

export default TenderlySimulationSummary;
```

Notice how we generated the links that lead users to the Tenderly Dashboard. The first link is for the authenticated users and the second one is a shareable transaction simulation link:

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const simulationUrl = `https://dashboard.tenderly.co/${process.env.TENDERLY_ACCOUNT_SLUG}/${process.env.TENDERLY_PROJECT_SLUG}/simulator/${simulation?.id}`;
const sharedSimulationUrl = `https://tdly.co/shared/simulation/${simulation?.id}`;
```

To retrieve the data from a simulated transaction, refer to the Tenderly Simulation API reference:

<Card title="Tenderly Simulation API" href="" />

### Assets In & Assets Out

The second section provides insights into managing and monitoring the flow of assets within the Rabby Wallet example. It shows both the incoming and outgoing assets to give you a better view of the wallet activity.

<figure>
  !\[Tenderly Docs]\(/images/image (117).webp)

  <figcaption />
</figure>

To achieve this, start by creating a `TenderlyWalletChanges.tsx` file:

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}


const TenderlyWalletChanges = ({
  account,
  assetChanges,
}: {
  account?: Account;
  assetChanges: any;
}) => {
  const { assetsInList, assetsOutList } = React.useMemo(() => {
    const assetsInList = assetChanges.filter(asset => asset.to === account?.address) || [];
    const assetsOutList = assetChanges.filter(asset => asset.from === account?.address) || [];

    return {
      assetsInList,
      assetsOutList,
    };
  }, [account, assetChanges]);

  return (
    <div className="TenderlyWalletChanges">
      <div className="TenderlyWalletChanges__Content">
        {/* Assets Out */}
        {assetsOutList?.length > 0 && (
          <>
            <p className="text-16 text-gray-title font-medium mb-4">Assets Out</p>
            <div className="flex flex-col gap-4 border border-gray-divider rounded-sm">
              {assetsOutList.map((token, index) => (
                <div
                  key={index}
                  className={clsx('flex gap-4 p-4', {
                    'border-t-[1px] border-gray-divider': index !== 0,
                  })}
                >
                  <div className="flex items-center justify-center p-4">
                    <img src={token.token_info.logo} className="w-60 rounded" alt="Tenderly" />
                  </div>
                  <div className="flex flex-col gap-4">
                    <div className="flex flex-col gap-1">
                      <div className="font-semibold">
                        {token.token_info.symbol.toUpperCase()}
                        {token.token_id && <span className="ml-2">#{Number(token.token_id)}</span>}
                      </div>
                      <div className="text-12 text-gray-content">{token.token_info.name}</div>
                    </div>
                    <div className="flex flex-wrap items-center gap-4">
                      <div className="font-semibold">{token.type}:</div>
                      <div className="text-red-forbidden">- {formatAmount(token.amount)}</div>
                      <div className="text-12 text-gray-content">
                        (≈ {formatUsdValue(new BigNumber(token.dollar_value).toFixed())})
                      </div>
                    </div>
                  </div>
                </div>
              ))}
            </div>
          </>
        )}

        {/* Assets In */}
        {assetsInList?.length > 0 && (
          <>
            <p className="text-16 text-gray-title font-medium mt-4 mb-4">Assets In</p>
            <div className="flex flex-col gap-4 border border-gray-divider rounded-sm">
              {assetsInList.map((token, index) => (
                <div
                  key={index}
                  className={clsx('flex gap-4 p-4', {
                    'border-t-[1px] border-gray-divider': index !== 0,
                  })}
                >
                  <div className="flex items-center justify-center p-4">
                    <img src={token.token_info.logo} className="w-60 rounded" alt="Tenderly" />
                  </div>
                  <div className="flex flex-col gap-4">
                    <div className="flex flex-col gap-1">
                      <div className="font-semibold">
                        {token.token_info.symbol.toUpperCase()}
                        {token.token_id && <span className="ml-2">#{Number(token.token_id)}</span>}
                      </div>
                      <div className="text-12 text-gray-content">{token.token_info.name}</div>
                    </div>
                    <div className="flex flex-wrap items-center gap-4">
                      <div className="font-semibold">{token.type}:</div>
                      <div className="text-green">+ {formatAmount(token.amount)}</div>
                      <div className="text-12 text-gray-content">
                        (≈ {formatUsdValue(new BigNumber(token.dollar_value).toFixed())})
                      </div>
                    </div>
                  </div>
                </div>
              ))}
            </div>
          </>
        )}
      </div>
      <TenderlyCredits classname="mt-12" />
    </div>
  );
};

export default TenderlyWalletChanges;
```

Here, we filtered out the asset changes array and created two lists:

1. Assets getting into the wallet
2. Assets going out of the wallet

Then, we used helper functions to preview and format the data.

However, you can also create your own UI layout to show the important asset information.

Learn more about simulation asset changes here:

<Card title="Asset and Balance Changes" href="" />

### Tokens Transferred

The Token Transfers section is a more complex component. This file primarily manages the layout, so let’s first discuss the sorting logic. You can find the [implementation of this section here](https://github.com/Tenderly/tenderly-rabby-transaction-preview/blob/a6b8059eeae4c856f32b328632a8cd8aa274f757/src/ui/views/Approval/components/TxComponents/Tenderly/AssetChanges/TenderlyAssetChanges.tsx).

Start by creating a `TenderlyAssetChanges.tsx` file. It contains the logic for presenting two tabs: **Tokens Transferred** and **Native Coins Transferred**. To do this, you need to add the logic for sorting, switching between tabs, and grouping the data by address.

<Frame>
  <img alt="Tokens Transferred UI" />
</Frame>

First, let’s group the data and create two arrays: tokens transferred and native coins transferred:

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const assetChangesMappedByType = React.useMemo<
  Record<AssetChangesTabs, TransactionAssetChangeData[]>
>(
  () =>
    transactionAssetChanges.reduce(
      (
        acc: {
          nativeCoinsTransferred: TransactionAssetChangeData[];
          tokensTransferred: TransactionAssetChangeData[];
        },
        assetChange: TransactionAssetChangeData,
      ) => {
        const { type } = assetChange.tokenInfo;
        if (type === TokenType.NATIVE) {
          return {
            ...acc,
            [AssetChangesTabs.nativeCoins]: [...(acc?.nativeCoinsTransferred ?? []), assetChange],
          };
        }
        return {
          ...acc,
          [AssetChangesTabs.tokens]: [...(acc?.tokensTransferred ?? []), assetChange],
        };
      },
      { [AssetChangesTabs.nativeCoins]: [], [AssetChangesTabs.tokens]: [] },
    ),
  [assetChanges],
);
```

Next, let’s write the logic for handling sorting types in two ways: chronologically and per address. Here, we need two components: **ChronologicalContent.tsx** and **PerAddressContent.tsx**.

You can find the implementation in the GitHub repository:

* [ChronologicalContent.tsx](https://github.com/Tenderly/tenderly-rabby-transaction-preview/blob/develop/src/ui/views/Approval/components/TxComponents/Tenderly/AssetChanges/ChronologicalContent.tsx)
* [PerAddressContent.tsx](https://github.com/Tenderly/tenderly-rabby-transaction-preview/blob/develop/src/ui/views/Approval/components/TxComponents/Tenderly/AssetChanges/PerAddressContent.tsx)

### Grouping and previewing all components

Finally, let’s put all of the components together. To do this, you need to create a `TenderlySimulationResult.tsx` file. You also need to use the `useWallet()` hook provided by the Rabby team to interact with the connected wallet address.

Here’s the code overview:

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

const TenderlySimulationResult = ({ data }: { data: Record<string, any> | null }) => {
  const [account, setAccount] = React.useState<Account>();
  const wallet = useWallet();

  const init = async () => {
    const currentAccount = await wallet.syncGetCurrentAccount();

    if (currentAccount) {
      setAccount(currentAccount);
    }
  };

  React.useEffect(() => {
    init();
  }, []);

  return (
    <div className="tenderly-simulation-result mt-16">
      <ActionWrapper>
        {!data && <div className="bg-[#f5f6fa] sticky top-[64px] z-10">Something went wrong.</div>}
        {data && <TenderlySimulationSummary simulation={data.simulation} />}
      </ActionWrapper>
      {data?.transaction?.transaction_info.asset_changes && (
        <>
          <ActionWrapper>
            <TenderlyWalletChanges
              account={account}
              assetChanges={data.transaction.transaction_info.asset_changes}
            />
          </ActionWrapper>
          <ActionWrapper>
            <TenderlyAssetChanges
              assetChanges={data.transaction.transaction_info.asset_changes}
              contracts={data.contracts}
            />
          </ActionWrapper>
        </>
      )}
    </div>
  );
};

export default TenderlySimulationResult;
```

## What's next?

Congrats! You added the Transaction Preview feature to a Rabby Wallet example using the Tenderly Simulation API. 🎉

To dive into the logic, check out the [complete source code on GitHub](https://github.com/Tenderly/tenderly-rabby-transaction-preview).

Additionally, you can initiate Tenderly transaction simulations using three different methods depending on your project requirements. To learn about other ways to integrate transaction simulations into your wallet or dapp, take a look at the following resources:

<Card title="Simulation API" href="" />

<Card title="Simulating Transactions" href="" />

<Card title="Simulation RPC" href="" />


# Using Simulation RPC in Dapp UI
Source: https://docs.tenderly.co/simulations/guides/simulation-rpc-dapp-ui

Integrate transaction simulations into your dapp via Tenderly Simulation RPC. Follow a step-by-step Uniswap UI integration example.

<Note>
  Simulation RPC is compatible with Mainnet, Boba and Polygon, while other networks will be
  integrated gradually.\ Simulation API is compatible with [all Tenderly-supported
  networks](/node-rpc/overview).
</Note>

You can introduce simulations into your dapp by integrating Simulation RPC or Simulation API.

### Benefits of integrating Simulation API

By integrating Simulation API/Simulation RPC

1. Dry-run users' transactions before they sign and submit them on-chain.
2. Provide better visibility into potential rollbacks and avoid losing money on gas fees.
3. Provide better visibility into the outcomes of successful apps, including moving assets and state changes relevant to the user.
4. Build logic around simulation results to show users whether their transactions bring optimal value and suggest improvements.

Here are a few examples:

* If you're building a wallet-like app, you can show how a transaction moves ERC-20 tokens and enable users to see the shifting of their funds.
* If you're building a DeFi product, you can use events to analyze whether a transaction meets the optimal conditions set by the user in the UI.
* If you're preparing a governance proposal, consisting of several transactions, you can do a simulation bundle to see how the proposal is applied.
* You can even bundle the proposal transactions with several test transactions to verify that your proposal executes as intended and identify possible blind spots.

### Example: Adding Simulations to Uniswap UI

In this example, we'll show how to integrate Simulation RPC into the Uniswap UI and show the exact token hops along the exchange path. This way, we'll give the user higher visibility into the effects of the transaction and allow them to make a well-informed decision on whether or not to proceed.

## The `Simulation` component requirements

Here are the requirements for the simulation component:

* The component should display the number of tokens the user has before and after signing and sending the transaction.
* The simulation should be done every time the trade data changes, so it needs to receive the `trade` and `allowedSlippage` parameters.
* The component must keep track of:
  * Current balances (before the swap).
  * The `Swap` event we'll use to calculate the new balances.
  * An array of `Transfer` events we'll use to calculate the new balances.

## Render the `Simulation` into `ConfirmSwapModal`

The best place to inform the user about the outcomes of a transaction is `ConfirmSwapModal`, just before they can sign and send the transaction.

The code is redacted for brevity:

```diff title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export default function ConfirmSwapModal({
  /* ... */
}: {
  /* ... */
}) {
  // ...
  const modalHeader = useCallback(() => {
    return trade ? (
      <>
        <SwapModalHeader.../>
+        <Simulation trade={trade} recipient={null} allowedSlippage={allowedSlippage} />
      </>
    ) : null
  }, [/* ... */])
  //...

```

## The `Simulation` component implementation

The logic of the component lies in the **simulate** function:

* It runs in event of changing `trade` or `provider` arguments, so it updates and re-simulates whenever the swap potentially changes.
* It calls `setOldBalances`, which gets the balances of In and Out ERC-20 tokens and stores them in the `oldBalances` state variable.
* It calls `simulateRPC`, which performs the Simulation RPC call to `tenderly_simulateTranscation` and then:
  * It parses through decoded logs to find the `Transfer` events and stores them in the component's `transfers` state variable.
  * It parses through the decoded logs to find the `Swap` event and stores it in the component's `swap` state variable.

Finally, to render the simulation results, we display the `SimulationDetails` component, which is a purely functional component. It calculates the old and new states and renders the data based on `trade`, `swap`, `transfers`, and `oldBalances`.

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const Simulation = ({
  trade,
  allowedSlippage,
  recipient,
}: {
  trade: InterfaceTrade<Currency, Currency, TradeType> | undefined;
  recipient: string | null;
  allowedSlippage: Percent;
}) => {
  const { account, provider } = useWeb3React();
  const nativeCurrency = useNativeCurrency();

  const deadline = useTransactionDeadline();
  const signatureData = useERC20PermitFromTrade(trade, allowedSlippage, deadline);
  const args = useSwapCallArguments(
    trade,
    allowedSlippage,
    recipient,
    signatureData.signatureData,
    deadline,
    undefined,
  );

  const [oldBalances, setOldBalances] = useState<any[]>([]);
  const [transfers, setTransfers] = useState<any[]>([]);
  const [swap, setSwap] = useState<any>({});

  useEffect(() => {
    onSimulate();
  }, [trade, provider]);

  async function onSimulate() {
    setOldBalances([]);
    setSwap({});
    const { address, calldata, value } = args[0];
    const provider = RPC_PROVIDERS[SupportedChainId.MAINNET];

    await getCurrentBalances();
    await simulateRPC(account, address, calldata, value);
  }

  async function getCurrentBalances() {
    return Promise.all([
      provider.send('eth_getBalance', [account, 'latest']),
      provider.send('eth_call', [
        {
          to: '0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984',
          data: `0x70a0823100000000000000000000000000${stripX(account)}`,
        },
        'latest',
      ]),
    ]).then(oldBalances => {
      setOldBalances(oldBalances);
    });
  }

  async function simulateRPC(account: string, address: string, calldata: string, value: string) {
    RPC_PROVIDERS[SupportedChainId.MAINNET]
      .send('tenderly_simulateTransaction', [
        {
          from: account,
          to: address,
          data: calldata,
          value: stripHexZero(value),
        },
        'latest', // block number to simulate on
        null, // optional state overrides for involved contracts
      ])
      .then(simulationResponse => {
        console.log('Simulation Response', simulationResponse);
        setTransfers(simulationResponse.logs.filter((log: any) => log.name === 'Transfer'));
        setSwap(simulationResponse.logs.filter((log: any) => log.name === 'Swap')[0]);
      });
  }

  return (
    <>
      ...
      <SimulationDetails
        trade={trade}
        syncing={oldBalances.length == 0 && transfers.length == 0 && !!swap.inputs}
        transfers={transfers}
        oldBalances={oldBalances}
        swap={swap}
      />
    </>
  );
};
```


# Simulations Overview
Source: https://docs.tenderly.co/simulations/overview

Simulate single or bundled transactions via API or RPC with decoded traces, accurate gas estimates, balance changes, and more.

Transaction Simulations let you predict a transaction's exact outcome before it is executed on the network. Tenderly enables you to run simulations on any of the [95 supported networks](/platform/supported-networks) in one place.

Tenderly simulates transactions in a virtual environment that is a replica of the real blockchain. This ensures you're always getting the most accurate simulation results: **100% accurate gas usage breakdown**, **assets exchanged**, **balance changes**, **storage updates**, and entire **decoded transaction trace**.

<CardGroup>
  <Card title="Simulate via RPC" href="/simulations/quickstart#rpc-simulations-quickstart">
    Opt to simulate via RPC when you need combined capabilities of blockchain access and simulations.
  </Card>

  <Card title="Simulate via API" href="/simulations/single-simulations#simulate-via-api">
    Incorporate simulations seamlessly into your dapp or wallet using standard REST endpoints.
  </Card>

  <Card title="Tenderly SDK" href="/platform/sdk/introduction">
    The Tenderly SDK provides useful utilities for quickly adding simulations into your dapp or wallet.
  </Card>
</CardGroup>

See the [supported networks](/platform/supported-networks) for the full list.

## Features

Learn how to simulate single and bundled transactions via API or RPC.

<CardGroup>
  <Card title="Single Transaction Simulations" href="/simulations/single-simulations">
    Integrate simulations into your dapp to give users the ability to preview the results of their transactions without risking real assets and or spending money on gas.
  </Card>

  <Card title="Bundled Transaction Simulations" href="/simulations/bundled-simulations">
    Simulate bundled transactions in one go and test the results of all interdependent transactions. Bundled simulations are ideal for governance proposals or strategy testing.
  </Card>
</CardGroup>

## Use cases

* [**Asset and balance changes**](/simulations/asset-balance-changes): Get exact dollar values for all balance and asset changes that will happen.
* [**Gas estimation**](/simulations/gas-estimation): Accurately predict the gas costs before sending the transaction.
* [**State overrides**](/simulations/state-overrides): Modify blockchain conditions like timestamps and contract data to test different scenarios.
* [**Preview transaction outcomes**](/simulations/transaction-preview): Identify and fix issues that could cause transactions to fail.
* **Access lists**: Create lists of addresses and storage slots the transaction will access.
* **Human-readable errors**: Get complex errors decoded into explanations that you can easily understand.

## Resources

<CardGroup>
  <Card title="Quickstart" icon="play" href="/simulations/quickstart">
    Learn the quickest way to integrate simulations into your dapp or wallet.
  </Card>

  <Card title="Authentication" icon="key" href="/platform/account/projects/api-tokens">
    Learn how to configure and authenticate access to the API and RPC.
  </Card>

  <Card title="Guides" icon="file-code" href="/simulations/overview">
    Browse our growing library of transaction simulation integration guides.
  </Card>

  <Card title="API Reference" icon="brackets-curly" href="/api-reference">
    Get familiar with all the API simulation endpoints, requests, and parameters.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/troubleshooting/simulations">
    Get answers to the most commonly asked questions about simulations.
  </Card>
</CardGroup>


# Simulations Quickstart
Source: https://docs.tenderly.co/simulations/quickstart

Simulate your first transaction with tenderly_simulateTransaction over Node RPC, verifying behavior before sending it onchain in minutes.

This quickstart guide demonstrates how to simulate a single transaction on the Node RPC using a custom RPC method `tenderly_simulateTransaction`. See [RPC simulation reference](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction). Simulations allow you to precisely verify the transaction's behavior before sending it to the blockchain.

<Note>
  Simulation RPC is available both on [Node RPC](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction) and [Virtual Environment RPCs](/virtual-environments/interact/simulate-transactions)
</Note>

## Get the RPC URL

Log into your [Tenderly account](https://dashboard.tenderly.co/register?redirectTo=gateways) and from the left-hand menu click on **Node**.

Copy the RPC URL of your preferred network. If your network is not supported on the Node, [simulate via API](/simulations/single-simulations#simulate-via-api) instead.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://mainnet.gateway.tenderly.co/${TENDERLY_NODE_ACCESS_KEY}
```

The access key is automatically appended to the end of the RPC URL.

## Send the request

Make a `POST` request to the RPC URL.

Your request must include:

* The RPC URL with your access key.
* Call to the RPC method `tenderly_simulateTransaction`.
* Transaction parameters such as `from`, `to`, `gas`, `gas price`, `value`, and `data`.

**Example cURL request**

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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",
        "gas": "0x0",
        "value": "0x0",
        "data": "0xa9059cbb00000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001"
      },
      "latest"
    ]
  }'
```

## Explore use cases

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

## Where to go next

<Card title="Bundled simulations" href="" />

<Card title="Simulate via SDK" href="" />


# Simulation Modes
Source: https://docs.tenderly.co/simulations/simulation-modes

Choose full mode for complete decoding, abi mode for partial decoding, or quick mode for faster raw transaction outputs.

The `simulation_type` API parameter allows you to control the level of detail returned in the [Simulation API](/simulations/overview) result. It applies to both [single simulations](/simulations/single-simulations) and bundled requests.

## Types of simulations

* `full` (default): Detailed raw and decoded information with call trace, function inputs and outputs, state diffs, etc.
* `quick`: Minimal, raw values
* `abi`: Minimal information with decoded inputs, outputs, and logs

<Note>
  Full simulations take more time, depending on the depth of the call trace. Use quick simulations when decoded
  information isn't necessary.
</Note>

## Full simulation mode

* The **call trace** containing the function name, position in the source file, caller's address, and balance
* Decoded **function inputs and outputs**, with **soltype** for all arguments. This applies to all function calls, including the direct call to the smart contract from EOA, internal calls between smart contracts, and function calls within each smart contract.
* Decoded **state diff** (changes to the state) enriched with **soltype** for the modified fields
* Decoded **logs (events)** consisting of the Solidity **event** that produced them and the event arguments' **value**, enriched with **type** for each.

```ts title="request.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

dotenv.config();

const approveDai = async () => {
  // assuming environment variables TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG and TENDERLY_ACCESS_KEY are set
  // https://docs.tenderly.co/platform/account/projects/slug
  // https://docs.tenderly.co/platform/account/projects/api-tokens
  const { TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG, TENDERLY_ACCESS_KEY } = process.env;

  console.time('Simulation');

  const resp = await axios.post(
    `https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate`,
    // the transaction
    {
      /* Simulation Configuration */
      save: false, // if true simulation is saved and shows up in the dashboard
      save_if_fails: false, // if true, reverting simulations show up in the dashboard
      simulation_type: 'full', // full, abi or quick (full is default)
      network_id: '1', // network to simulate on
      /* Standard EVM Transaction object */
      from: '0xdc6bdc37b2714ee601734cf55a05625c9e512461',
      to: '0x6b175474e89094c44da98b954eedeac495271d0f',
      input: '0x095ea7b3000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1000000000000000000000000000000000000000000000000000000000000012b',
      gas: 8000000,
      value: 0,
    },
    {
      headers: {
        'X-Access-Key': TENDERLY_ACCESS_KEY as string,
      },
    },
  );
  console.timeEnd('Simulation');

  const transaction = resp.data.transaction;
  console.log(JSON.stringify(transaction, null, 2));
};

approveDai();
```

## Quick simulation mode

Offers raw data without additional decoding. This mode is best when you only need the fundamental details of a transaction.

```ts title="request.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

dotenv.config();

const approveDai = async () => {
  // assuming environment variables TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG and TENDERLY_ACCESS_KEY are set
  // https://docs.tenderly.co/platform/account/projects/slug
  // https://docs.tenderly.co/platform/account/projects/api-tokens
  const { TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG, TENDERLY_ACCESS_KEY } = process.env;

  console.time('Simulation');

  const resp = await axios.post(
    `https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate`,
    // the transaction
    {
      /* Simulation Configuration */
      save: false, // if true simulation is saved and shows up in the dashboard
      save_if_fails: false, // if true, reverting simulations show up in the dashboard
      simulation_type: 'quick', // full, abi or quick (full is default)
      network_id: '1', // network to simulate on
      /* Standard EVM Transaction object */
      from: '0xdc6bdc37b2714ee601734cf55a05625c9e512461',
      to: '0x6b175474e89094c44da98b954eedeac495271d0f',
      input: '0x095ea7b3000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1000000000000000000000000000000000000000000000000000000000000012b',
      gas: 8000000,
      value: 0,
    },
    {
      headers: {
        'X-Access-Key': TENDERLY_ACCESS_KEY as string,
      },
    },
  );
  console.timeEnd('Simulation');

  const transaction = resp.data.transaction;
  console.log(JSON.stringify(transaction, null, 2));
};

approveDai();
```

## ABI simulation mode

The **call trace** containing the function name, decoded input and output variables

Decoded **logs (events)** consisting of the Solidity **event** that produced them and the event arguments' **value**, enriched with **type** description for each.

```ts title="request.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

dotenv.config();

const approveDai = async () => {
  // assuming environment variables TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG and TENDERLY_ACCESS_KEY are set
  // https://docs.tenderly.co/platform/account/projects/slug
  // https://docs.tenderly.co/platform/account/projects/api-tokens
  const { TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG, TENDERLY_ACCESS_KEY } = process.env;

  console.time('Simulation');

  const resp = await axios.post(
    `https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate`,
    // the transaction
    {
      /* Simulation Configuration */
      save: false, // if true simulation is saved and shows up in the dashboard
      save_if_fails: false, // if true, reverting simulations show up in the dashboard
      simulation_type: 'abi', // full, abi or quick (full is default)
      network_id: '1', // network to simulate on
      /* Standard EVM Transaction object */
      from: '0xdc6bdc37b2714ee601734cf55a05625c9e512461',
      to: '0x6b175474e89094c44da98b954eedeac495271d0f',
      input: '0x095ea7b3000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1000000000000000000000000000000000000000000000000000000000000012b',
      gas: 8000000,
      value: 0,
    },
    {
      headers: {
        'X-Access-Key': TENDERLY_ACCESS_KEY as string,
      },
    },
  );
  console.timeEnd('Simulation');

  const transaction = resp.data.transaction;
  console.log(JSON.stringify(transaction, null, 2));
};

approveDai();
```


# Single Simulations
Source: https://docs.tenderly.co/simulations/single-simulations

Simulate a single transaction over JSON-RPC or the Simulation API to preview execution, balance and asset changes, logs, and the call trace.

Tenderly supports single transaction simulations via [RPC](/simulations/single-simulations#simulate-via-rpc) and [API](/simulations/single-simulations#simulate-via-api). Simulations are executed on the latest state of the chosen network.

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](/node-rpc/overview) 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.

<Note>
  Simulations via RPC or API are only available on supported networks. Check out the list of [supported networks](/platform/supported-networks).
</Note>

Retrieve your RPC URL and the access key from the [Dashboard](https://dashboard.tenderly.co/register?redirectTo=gateways).

Go to **Node** > **Copy HTTPS URL** of the desired network.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://mainnet.gateway.tenderly.co/$TENDERLY_NODE_ACCESS_KEY
```

To simulate a single transaction via RPC, call the `tenderly_simulateTransaction` method. [See RPC reference](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction).

**Example**

<Tabs>
  <Tab title="request">
    ```bash title="request" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"
        ]
      }'
    ```
  </Tab>

  <Tab title="response.json">
    ```json title="response.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "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"
            }
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

## Simulate via API

Use the [simulate API endpoint](/api-reference) to simulate a single transaction with different parameters.

<Note>
  To use Simulations on Virtual Environments, we recommend the [Simulate RPC](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction) and [Bundle Simulate RPC](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateBundle).
  Otherwise, you may use [Virtual Environments Simulation API](/api-reference).
</Note>

The URL must contain your **account slug** and the **project slug**. Follow this [quick guide](/platform/account/projects/slug) to find the slugs.

```bash title="Simulation API endpoint on public network" showLineNumbers wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate
```

```bash title="Simulation API endpoint on a Virtual Environment" showLineNumbers wordWrap=true theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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](/platform/account/projects/api-tokens).

### Request payload

Send a `POST` request to the API endpoint. For full details on the request payload, see the [See API reference](/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.
* `block_number` (number): “latest” or the block number to be used for 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.

<Note>
  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.
</Note>

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](/simulations/simulation-modes).

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.

<Tabs>
  <Tab title="request.ts">
    ```ts title="request.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

    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();
    ```
  </Tab>

  <Tab title="response.json">
    ```json title="response.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "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": []
    }
    ```
  </Tab>
</Tabs>

## Explore use cases

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

## Where to go next

<Card title="Bundled simulations" href="" />

<Card title="Simulate via SDK" href="" />


# Simulation API With State Overrides
Source: https://docs.tenderly.co/simulations/state-overrides

Override contract storage slots and balances in the Simulation API to test scenarios not present on the live network, like minting as a ward.

State overrides allow you to customize the network state for the purpose of your [simulation](/simulations/overview). This feature is useful when you need to test scenarios under conditions that aren't currently present on the live network. To apply the same overrides through the dashboard instead of the API, see [state overrides in the Simulator UI](/simulator-ui/state-overrides).

To illustrate how state overrides work, let's use the DAI stablecoin contract. In the DAI system, certain actions, like minting new DAI tokens, can only be performed by addresses designated as `wards`. If your address isn't a ward, you can't test minting operations.

## Setting up as a ward through state overrides

To simulate a transaction where we mint DAI, we need to override the state to make our address appear as a ward. We need to adjust the `wards` map in the DAI contract to include our address with the necessary permissions.

To be able to mint, the sender of the transaction must be a ward. In other words, the following condition must hold: `wards['0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2'] == 1`.

In the API request, assign a map of overrides to the `state_objects` object. This map points to specific storage locations in the smart contract and assigns new values for the simulation.

* DAI contract address: `0x6b175474e89094c44da98b954eedeac495271d0f`
* Storage slot location: `0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03`
* Override value: `0x0000000000000000000000000000000000000000000000000000000000000001`

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "state_objects": {
    "0x6b175474e89094c44da98b954eedeac495271d0f": {
      "storage": {
        "0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03": "0x0000000000000000000000000000000000000000000000000000000000000001"
      }
    }
  }
}
```

The script below shows how to set the overrides and send a request to Simulation API.

Make sure to have `TENDERLY_ACCOUNT_SLUG` and `TENDERLY_ACCESS_KEY` set as environment variables. Learn how to obtain the slug and access key.

<Tabs>
  <Tab title="Request">
    ```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

    dotenv.config();

    // assuming environment variables TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG and TENDERLY_ACCESS_KEY are set
    // https://docs.tenderly.co/platform/account/projects/slug
    // https://docs.tenderly.co/platform/account/projects/api-tokens
    const { TENDERLY_ACCOUNT_SLUG, TENDERLY_PROJECT_SLUG, TENDERLY_ACCESS_KEY } = process.env;

    const mintDai = async () => {
      console.time('Simulation');
      const fakeWardAddress = '0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2';
      // calculate the storage location of `wards[fakeWardAddress]`
      // yields 0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03
      const overrideStorageLocation = ethers.utils.keccak256(
        ethers.utils.concat([
          ethers.utils.hexZeroPad(fakeWardAddress, 32), // the ward address (address 0x000..0) - mapping key
          ethers.utils.hexZeroPad('0x0', 32), // the wards slot is 0th in the DAI contract - the mapping variable
        ]),
      );
      console.log('Storage Override Location', overrideStorageLocation);
      const mint = (
        await axios.post(
          `https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT_SLUG}/project/${TENDERLY_PROJECT_SLUG}/simulate`,
          // the transaction
          {
            save: true,
            save_if_fails: true,
            simulation_type: 'full',
            network_id: '1',
            from: '0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2',
            to: '0x6b175474e89094c44da98b954eedeac495271d0f',
            input:
              '0x40c10f19000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce10000000000000000000000000000000000000000000000001bc16d674ec80000',
            gas: 8000000,
            state_objects: {
              '0x6b175474e89094c44da98b954eedeac495271d0f': {
                storage: {
                  '0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03':
                    '0x0000000000000000000000000000000000000000000000000000000000000001',
                },
              },
            },
          },
          {
            headers: {
              'X-Access-Key': TENDERLY_ACCESS_KEY as string,
            },
          },
        )
      ).data;

      console.timeEnd('Simulation');
      console.log(JSON.stringify(mint, null, 2));
      // TODO: extract token transferred
    };

    mintDai();
    ```
  </Tab>

  <Tab title="Response">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    Storage Override Location 0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03
    Simulation: 185.029ms
    {
      "transaction": {
        "hash": "0xd9d52b2cb6b6d8d8640bc2dee86050a623401fe39d7fbc4ab46ffd7ff3ea6ab6",
        "block_hash": "",
        "block_number": 16598541,
        "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
        "gas": 8000000,
        "gas_price": 0,
        "gas_fee_cap": 0,
        "gas_tip_cap": 0,
        "cumulative_gas_used": 0,
        "gas_used": 53465,
        "effective_gas_price": 0,
        "input": "0x40c10f19000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce10000000000000000000000000000000000000000000000001bc16d674ec80000",
        "nonce": 0,
        "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
        "index": 0,
        "value": "0x",
        "access_list": null,
        "status": true,
        "addresses": [
          "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
          "0x6b175474e89094c44da98b954eedeac495271d0f"
        ],
        "contract_ids": [
          "eth:1:0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
          "eth:1:0x6b175474e89094c44da98b954eedeac495271d0f"
        ],
        "network_id": "1",
        "timestamp": "2023-02-10T13:04:56Z",
        "function_selector": "",
        "l1_block_number": 0,
        "l1_timestamp": 0,
        "deposit_tx": false,
        "system_tx": false,
        "mint": null,
        "sig": {
          "v": "0x0",
          "r": "0x0",
          "s": "0x0"
        },
        "transaction_info": {
          "contract_id": "eth:1:0x6b175474e89094c44da98b954eedeac495271d0f",
          "block_number": 16598541,
          "transaction_id": "0xd9d52b2cb6b6d8d8640bc2dee86050a623401fe39d7fbc4ab46ffd7ff3ea6ab6",
          "contract_address": "0x6b175474e89094c44da98b954eedeac495271d0f",
          "method": "mint",
          "parameters": null,
          "intrinsic_gas": 21620,
          "refund_gas": 0,
          "call_trace": {
            "hash": "0xd9d52b2cb6b6d8d8640bc2dee86050a623401fe39d7fbc4ab46ffd7ff3ea6ab6",
            "contract_name": "Dai",
            "function_name": "mint",
            "function_pc": 3948,
            "function_op": "JUMPDEST",
            "function_file_index": 0,
            "function_code_start": 5501,
            "function_line_number": 134,
            "function_code_length": 202,
            "absolute_position": 88,
            "caller_pc": 0,
            "caller_op": "CALL",
            "call_type": "CALL",
            "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
            "from_balance": "0",
            "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "to_balance": "0",
            "value": "0",
            "caller": {
              "address": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
              "balance": "0"
            },
            "block_timestamp": "0001-01-01T00:00:00Z",
            "gas": 7978380,
            "gas_used": 31845,
            "intrinsic_gas": 21620,
            "input": "0x40c10f19000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce10000000000000000000000000000000000000000000000001bc16d674ec80000",
            "decoded_input": [
              {
                "soltype": {
                  "name": "usr",
                  "type": "address",
                  "storage_location": "default",
                  "components": null,
                  "offset": 0,
                  "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                  "indexed": false,
                  "simple_type": {
                    "type": "address"
                  }
                },
                "value": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1"
              },
              {
                "soltype": {
                  "name": "wad",
                  "type": "uint256",
                  "storage_location": "default",
                  "components": null,
                  "offset": 0,
                  "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                  "indexed": false,
                  "simple_type": {
                    "type": "uint"
                  }
                },
                "value": "2000000000000000000"
              }
            ],
            "nonce_diff": [
              {
                "address": "0xe2E2E2e2e2e2E2E2E2E2e2E2e2E2E2e2e2e2E2e2",
                "original": "0",
                "dirty": "1"
              }
            ],
            "state_diff": [
              {
                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "soltype": {
                  "name": "totalSupply",
                  "type": "uint256",
                  "storage_location": "storage",
                  "components": null,
                  "offset": 0,
                  "index": "0x0000000000000000000000000000000000000000000000000000000000000001",
                  "indexed": false,
                  "simple_type": {
                    "type": "uint"
                  }
                },
                "original": "5090814826520179690761462859",
                "dirty": "5090814828520179690761462859",
                "raw": [
                  {
                    "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                    "key": "0x0000000000000000000000000000000000000000000000000000000000000001",
                    "original": "0x0000000000000000000000000000000000000000107305f8bb52a43b529da44b",
                    "dirty": "0x0000000000000000000000000000000000000000107305f8d71411a2a165a44b"
                  }
                ]
              },
              {
                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "soltype": {
                  "name": "balanceOf",
                  "type": "mapping (address => uint256)",
                  "storage_location": "storage",
                  "components": null,
                  "offset": 0,
                  "index": "0x0000000000000000000000000000000000000000000000000000000000000002",
                  "indexed": false
                },
                "original": {
                  "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1": "0"
                },
                "dirty": {
                  "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1": "2000000000000000000"
                },
                "raw": [
                  {
                    "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                    "key": "0x9b5472766fd311751f6a33c8e30061e20a26259ca626cf5a2feaadf96903cd9e",
                    "original": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "dirty": "0x0000000000000000000000000000000000000000000000001bc16d674ec80000"
                  }
                ]
              }
            ],
            "logs": [
              {
                "name": "Transfer",
                "anonymous": false,
                "inputs": [
                  {
                    "soltype": {
                      "name": "src",
                      "type": "address",
                      "storage_location": "default",
                      "components": null,
                      "offset": 0,
                      "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                      "indexed": true,
                      "simple_type": {
                        "type": "address"
                      }
                    },
                    "value": "0x0000000000000000000000000000000000000000"
                  },
                  {
                    "soltype": {
                      "name": "dst",
                      "type": "address",
                      "storage_location": "default",
                      "components": null,
                      "offset": 0,
                      "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                      "indexed": true,
                      "simple_type": {
                        "type": "address"
                      }
                    },
                    "value": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1"
                  },
                  {
                    "soltype": {
                      "name": "wad",
                      "type": "uint256",
                      "storage_location": "default",
                      "components": null,
                      "offset": 0,
                      "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                      "indexed": false,
                      "simple_type": {
                        "type": "uint"
                      }
                    },
                    "value": "2000000000000000000"
                  }
                ],
                "raw": {
                  "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                  "topics": [
                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                    "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "0x000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1"
                  ],
                  "data": "0x0000000000000000000000000000000000000000000000001bc16d674ec80000"
                }
              }
            ],
            "output": "0x",
            "decoded_output": null,
            "network_id": "1",
            "calls": [
              {
                "hash": "",
                "contract_name": "Dai",
                "function_name": "add",
                "function_pc": 7825,
                "function_op": "JUMPDEST",
                "function_file_index": 0,
                "function_code_start": 3853,
                "function_line_number": 94,
                "function_code_length": 102,
                "absolute_position": 136,
                "caller_pc": 4200,
                "caller_op": "JUMP",
                "caller_file_index": 0,
                "caller_line_number": 135,
                "caller_code_start": 5579,
                "caller_code_length": 24,
                "call_type": "JUMPDEST",
                "from": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "from_balance": null,
                "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "to_balance": null,
                "value": null,
                "caller": {
                  "address": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
                  "balance": "0"
                },
                "block_timestamp": "0001-01-01T00:00:00Z",
                "gas": 7973640,
                "gas_used": 62,
                "input": "0x",
                "decoded_input": [
                  {
                    "soltype": {
                      "name": "x",
                      "type": "uint256",
                      "storage_location": "default",
                      "components": null,
                      "offset": 0,
                      "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                      "indexed": false,
                      "simple_type": {
                        "type": "uint"
                      }
                    },
                    "value": "0"
                  },
                  {
                    "soltype": {
                      "name": "y",
                      "type": "uint256",
                      "storage_location": "default",
                      "components": null,
                      "offset": 0,
                      "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                      "indexed": false,
                      "simple_type": {
                        "type": "uint"
                      }
                    },
                    "value": "2000000000000000000"
                  }
                ],
                "output": "0x",
                "decoded_output": [
                  {
                    "soltype": {
                      "name": "z",
                      "type": "uint256",
                      "storage_location": "default",
                      "components": null,
                      "offset": 0,
                      "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                      "indexed": false,
                      "simple_type": {
                        "type": "uint"
                      }
                    },
                    "value": "2000000000000000000"
                  }
                ],
                "network_id": "",
                "calls": null
              },
              {
                "hash": "",
                "contract_name": "Dai",
                "function_name": "add",
                "function_pc": 7825,
                "function_op": "JUMPDEST",
                "function_file_index": 0,
                "function_code_start": 3853,
                "function_line_number": 94,
                "function_code_length": 102,
                "absolute_position": 184,
                "caller_pc": 4279,
                "caller_op": "JUMP",
                "caller_file_index": 0,
                "caller_line_number": 136,
                "caller_code_start": 5630,
                "caller_code_length": 21,
                "call_type": "JUMPDEST",
                "from": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "from_balance": null,
                "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "to_balance": null,
                "value": null,
                "caller": {
                  "address": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
                  "balance": "0"
                },
                "block_timestamp": "0001-01-01T00:00:00Z",
                "gas": 7951356,
                "gas_used": 62,
                "input": "0x",
                "decoded_input": [
                  {
                    "soltype": {
                      "name": "x",
                      "type": "uint256",
                      "storage_location": "default",
                      "components": null,
                      "offset": 0,
                      "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                      "indexed": false,
                      "simple_type": {
                        "type": "uint"
                      }
                    },
                    "value": "5090814826520179690761462859"
                  },
                  {
                    "soltype": {
                      "name": "y",
                      "type": "uint256",
                      "storage_location": "default",
                      "components": null,
                      "offset": 0,
                      "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                      "indexed": false,
                      "simple_type": {
                        "type": "uint"
                      }
                    },
                    "value": "2000000000000000000"
                  }
                ],
                "output": "0x",
                "decoded_output": [
                  {
                    "soltype": {
                      "name": "z",
                      "type": "uint256",
                      "storage_location": "default",
                      "components": null,
                      "offset": 0,
                      "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                      "indexed": false,
                      "simple_type": {
                        "type": "uint"
                      }
                    },
                    "value": "5090814828520179690761462859"
                  }
                ],
                "network_id": "",
                "calls": null
              }
            ]
          },
          "stack_trace": null,
          "logs": [
            {
              "name": "Transfer",
              "anonymous": false,
              "inputs": [
                {
                  "soltype": {
                    "name": "src",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": true,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  "value": "0x0000000000000000000000000000000000000000"
                },
                {
                  "soltype": {
                    "name": "dst",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": true,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  "value": "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1"
                },
                {
                  "soltype": {
                    "name": "wad",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  },
                  "value": "2000000000000000000"
                }
              ],
              "raw": {
                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "topics": [
                  "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                  "0x0000000000000000000000000000000000000000000000000000000000000000",
                  "0x000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce1"
                ],
                "data": "0x0000000000000000000000000000000000000000000000001bc16d674ec80000"
              }
            }
          ],
          "balance_diff": null,
          "nonce_diff": [
            {
              "address": "0xe2E2E2e2e2e2E2E2E2E2e2E2e2E2E2e2e2e2E2e2",
              "original": "0",
              "dirty": "1"
            }
          ],
          "state_diff": [
            {
              "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
              "soltype": {
                "name": "totalSupply",
                "type": "uint256",
                "storage_location": "storage",
                "components": null,
                "offset": 0,
                "index": "0x0000000000000000000000000000000000000000000000000000000000000001",
                "indexed": false,
                "simple_type": {
                  "type": "uint"
                }
              },
              "original": "5090814826520179690761462859",
              "dirty": "5090814828520179690761462859",
              "raw": [
                {
                  "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                  "key": "0x0000000000000000000000000000000000000000000000000000000000000001",
                  "original": "0x0000000000000000000000000000000000000000107305f8bb52a43b529da44b",
                  "dirty": "0x0000000000000000000000000000000000000000107305f8d71411a2a165a44b"
                }
              ]
            },
            {
              "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
              "soltype": {
                "name": "balanceOf",
                "type": "mapping (address => uint256)",
                "storage_location": "storage",
                "components": null,
                "offset": 0,
                "index": "0x0000000000000000000000000000000000000000000000000000000000000002",
                "indexed": false
              },
              "original": {
                "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1": "0"
              },
              "dirty": {
                "0xe58b9ee93700a616b50509c8292977fa7a0f8ce1": "2000000000000000000"
              },
              "raw": [
                {
                  "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                  "key": "0x9b5472766fd311751f6a33c8e30061e20a26259ca626cf5a2feaadf96903cd9e",
                  "original": "0x0000000000000000000000000000000000000000000000000000000000000000",
                  "dirty": "0x0000000000000000000000000000000000000000000000001bc16d674ec80000"
                }
              ]
            }
          ],
          "raw_state_diff": null,
          "console_logs": null,
          "created_at": "2023-02-10T13:04:56Z"
        },
        "method": "",
        "decoded_input": null,
        "call_trace": [
          {
            "call_type": "CALL",
            "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
            "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "gas": 7978380,
            "gas_used": 31845,
            "type": "CALL",
            "input": "0x40c10f19000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce10000000000000000000000000000000000000000000000001bc16d674ec80000"
          }
        ]
      },
      "simulation": {
        "id": "46cb1f92-c9ee-4ef2-8736-6dc6ae84f8d8",
        "project_id": "11686306-12f4-4c48-9396-c07dbe6b3c51",
        "owner_id": "796e7d91-d8a2-4137-af6c-361f34e79557",
        "network_id": "1",
        "block_number": 16598541,
        "transaction_index": 0,
        "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
        "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
        "input": "0x40c10f19000000000000000000000000e58b9ee93700a616b50509c8292977fa7a0f8ce10000000000000000000000000000000000000000000000001bc16d674ec80000",
        "gas": 8000000,
        "gas_price": "0",
        "gas_used": 53465,
        "value": "0",
        "method": "mint",
        "status": true,
        "access_list": null,
        "queue_origin": "",
        "block_header": {
          "number": "0xfd460d",
          "hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "parentHash": "0x033362dcc958b7c9628256b1a59d7a82c2a7205fc7cb7c3270d08aef8e760e52",
          "sha3Uncles": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "receiptsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
          "timestamp": "0x63e640f8",
          "difficulty": "0x0",
          "gasLimit": "0x1c9c380",
          "gasUsed": "0xed3d6a",
          "miner": "0x0000000000000000000000000000000000000000",
          "extraData": "0x",
          "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "nonce": "0x0000000000000000",
          "baseFeePerGas": "0x1",
          "size": "0x0",
          "totalDifficulty": "0x0",
          "uncles": null,
          "transactions": null
        },
        "state_overrides": {
          "0x6b175474e89094c44da98b954eedeac495271d0f": {
            "storage": {
              "0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03": "0x0000000000000000000000000000000000000000000000000000000000000001"
            }
          }
        },
        "mint": null,
        "deposit_tx": false,
        "system_tx": false,
        "nonce": 0,
        "addresses": [
          "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
          "0x6b175474e89094c44da98b954eedeac495271d0f"
        ],
        "contract_ids": [
          "eth:1:0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
          "eth:1:0x6b175474e89094c44da98b954eedeac495271d0f"
        ],
        "created_at": "2023-02-10T13:04:57.004109816Z"
      },
      "contracts": [
        {
          "id": "eth:1:0x6b175474e89094c44da98b954eedeac495271d0f",
          "contract_id": "eth:1:0x6b175474e89094c44da98b954eedeac495271d0f",
          "balance": "",
          "network_id": "1",
          "public": true,
          "export": false,
          "verified_by": "etherscan",
          "verification_date": null,
          "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
          "contract_name": "Dai",
          "ens_domain": null,
          "type": "contract",
          "standard": "erc20",
          "standards": [
            "erc20"
          ],
          "token_data": {
            "symbol": "DAI",
            "name": "Dai Stablecoin",
            "decimals": 18,
            "main": true
          },
          "evm_version": "default",
          "compiler_version": "v0.5.12+commit.7709ece9",
          "optimizations_used": false,
          "optimization_runs": 200,
          "libraries": null,
          "data": {
            "main_contract": 0,
            "contract_info": [
              {
                "id": 0,
                "path": "Dai.sol",
                "name": "Dai.sol",
                "source": "// hevm: flattened sources of /nix/store/8xb41r4qd0cjb63wcrxf1qmfg88p0961-dss-6fd7de0/src/dai.sol\npragma solidity =0.5.12;\n\n////// /nix/store/8xb41r4qd0cjb63wcrxf1qmfg88p0961-dss-6fd7de0/src/lib.sol\n// This program is free software: you can redistribute it and/or modify\n// it under the terms of the GNU General Public License as published by\n// the Free Software Foundation, either version 3 of the License, or\n// (at your option) any later version.\n\n// This program is distributed in the hope that it will be useful,\n// but WITHOUT ANY WARRANTY; without even the implied warranty of\n// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n// GNU General Public License for more details.\n\n// You should have received a copy of the GNU General Public License\n// along with this program.  If not, see <http://www.gnu.org/licenses/>.\n\n/* pragma solidity 0.5.12; */\n\ncontract LibNote {\n    event LogNote(\n        bytes4   indexed  sig,\n        address  indexed  usr,\n        bytes32  indexed  arg1,\n        bytes32  indexed  arg2,\n        bytes             data\n    ) anonymous;\n\n    modifier note {\n        _;\n        assembly {\n            // log an 'anonymous' event with a constant 6 words of calldata\n            // and four indexed topics: selector, caller, arg1 and arg2\n            let mark := msize                         // end of memory ensures zero\n            mstore(0x40, add(mark, 288))              // update free memory pointer\n            mstore(mark, 0x20)                        // bytes type data offset\n            mstore(add(mark, 0x20), 224)              // bytes size (padded)\n            calldatacopy(add(mark, 0x40), 0, 224)     // bytes payload\n            log4(mark, 288,                           // calldata\n                 shl(224, shr(224, calldataload(0))), // msg.sig\n                 caller,                              // msg.sender\n                 calldataload(4),                     // arg1\n                 calldataload(36)                     // arg2\n                )\n        }\n    }\n}\n\n////// /nix/store/8xb41r4qd0cjb63wcrxf1qmfg88p0961-dss-6fd7de0/src/dai.sol\n// Copyright (C) 2017, 2018, 2019 dbrock, rain, mrchico\n\n// This program is free software: you can redistribute it and/or modify\n// it under the terms of the GNU Affero General Public License as published by\n// the Free Software Foundation, either version 3 of the License, or\n// (at your option) any later version.\n//\n// This program is distributed in the hope that it will be useful,\n// but WITHOUT ANY WARRANTY; without even the implied warranty of\n// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n// GNU Affero General Public License for more details.\n//\n// You should have received a copy of the GNU Affero General Public License\n// along with this program.  If not, see <https://www.gnu.org/licenses/>.\n\n/* pragma solidity 0.5.12; */\n\n/* import \"./lib.sol\"; */\n\ncontract Dai is LibNote {\n    // --- Auth ---\n    mapping (address => uint) public wards;\n    function rely(address guy) external note auth { wards[guy] = 1; }\n    function deny(address guy) external note auth { wards[guy] = 0; }\n    modifier auth {\n        require(wards[msg.sender] == 1, \"Dai/not-authorized\");\n        _;\n    }\n\n    // --- ERC20 Data ---\n    string  public constant name     = \"Dai Stablecoin\";\n    string  public constant symbol   = \"DAI\";\n    string  public constant version  = \"1\";\n    uint8   public constant decimals = 18;\n    uint256 public totalSupply;\n\n    mapping (address => uint)                      public balanceOf;\n    mapping (address => mapping (address => uint)) public allowance;\n    mapping (address => uint)                      public nonces;\n\n    event Approval(address indexed src, address indexed guy, uint wad);\n    event Transfer(address indexed src, address indexed dst, uint wad);\n\n    // --- Math ---\n    function add(uint x, uint y) internal pure returns (uint z) {\n        require((z = x + y) >= x);\n    }\n    function sub(uint x, uint y) internal pure returns (uint z) {\n        require((z = x - y) <= x);\n    }\n\n    // --- EIP712 niceties ---\n    bytes32 public DOMAIN_SEPARATOR;\n    // bytes32 public constant PERMIT_TYPEHASH = keccak256(\"Permit(address holder,address spender,uint256 nonce,uint256 expiry,bool allowed)\");\n    bytes32 public constant PERMIT_TYPEHASH = 0xea2aa0a1be11a07ed86d755c93467f4f82362b452371d1ba94d1715123511acb;\n\n    constructor(uint256 chainId_) public {\n        wards[msg.sender] = 1;\n        DOMAIN_SEPARATOR = keccak256(abi.encode(\n            keccak256(\"EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)\"),\n            keccak256(bytes(name)),\n            keccak256(bytes(version)),\n            chainId_,\n            address(this)\n        ));\n    }\n\n    // --- Token ---\n    function transfer(address dst, uint wad) external returns (bool) {\n        return transferFrom(msg.sender, dst, wad);\n    }\n    function transferFrom(address src, address dst, uint wad)\n        public returns (bool)\n    {\n        require(balanceOf[src] >= wad, \"Dai/insufficient-balance\");\n        if (src != msg.sender && allowance[src][msg.sender] != uint(-1)) {\n            require(allowance[src][msg.sender] >= wad, \"Dai/insufficient-allowance\");\n            allowance[src][msg.sender] = sub(allowance[src][msg.sender], wad);\n        }\n        balanceOf[src] = sub(balanceOf[src], wad);\n        balanceOf[dst] = add(balanceOf[dst], wad);\n        emit Transfer(src, dst, wad);\n        return true;\n    }\n    function mint(address usr, uint wad) external auth {\n        balanceOf[usr] = add(balanceOf[usr], wad);\n        totalSupply    = add(totalSupply, wad);\n        emit Transfer(address(0), usr, wad);\n    }\n    function burn(address usr, uint wad) external {\n        require(balanceOf[usr] >= wad, \"Dai/insufficient-balance\");\n        if (usr != msg.sender && allowance[usr][msg.sender] != uint(-1)) {\n            require(allowance[usr][msg.sender] >= wad, \"Dai/insufficient-allowance\");\n            allowance[usr][msg.sender] = sub(allowance[usr][msg.sender], wad);\n        }\n        balanceOf[usr] = sub(balanceOf[usr], wad);\n        totalSupply    = sub(totalSupply, wad);\n        emit Transfer(usr, address(0), wad);\n    }\n    function approve(address usr, uint wad) external returns (bool) {\n        allowance[msg.sender][usr] = wad;\n        emit Approval(msg.sender, usr, wad);\n        return true;\n    }\n\n    // --- Alias ---\n    function push(address usr, uint wad) external {\n        transferFrom(msg.sender, usr, wad);\n    }\n    function pull(address usr, uint wad) external {\n        transferFrom(usr, msg.sender, wad);\n    }\n    function move(address src, address dst, uint wad) external {\n        transferFrom(src, dst, wad);\n    }\n\n    // --- Approve by signature ---\n    function permit(address holder, address spender, uint256 nonce, uint256 expiry,\n                    bool allowed, uint8 v, bytes32 r, bytes32 s) external\n    {\n        bytes32 digest =\n            keccak256(abi.encodePacked(\n                \"\\x19\\x01\",\n                DOMAIN_SEPARATOR,\n                keccak256(abi.encode(PERMIT_TYPEHASH,\n                                     holder,\n                                     spender,\n                                     nonce,\n                                     expiry,\n                                     allowed))\n        ));\n\n        require(holder != address(0), \"Dai/invalid-address-0\");\n        require(holder == ecrecover(digest, v, r, s), \"Dai/invalid-permit\");\n        require(expiry == 0 || now <= expiry, \"Dai/permit-expired\");\n        require(nonce == nonces[holder]++, \"Dai/invalid-nonce\");\n        uint wad = allowed ? uint(-1) : 0;\n        allowance[holder][spender] = wad;\n        emit Approval(holder, spender, wad);\n    }\n}"
              }
            ],
            "abi": [
              {
                "type": "constructor",
                "name": "",
                "constant": false,
                "anonymous": false,
                "stateMutability": "",
                "inputs": [
                  {
                    "name": "chainId_",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ],
                "outputs": null
              },
              {
                "type": "function",
                "name": "totalSupply",
                "constant": true,
                "anonymous": false,
                "stateMutability": "view",
                "inputs": [],
                "outputs": [
                  {
                    "name": "",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "move",
                "constant": false,
                "anonymous": false,
                "stateMutability": "nonpayable",
                "inputs": [
                  {
                    "name": "src",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "dst",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "wad",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ],
                "outputs": []
              },
              {
                "type": "function",
                "name": "name",
                "constant": true,
                "anonymous": false,
                "stateMutability": "view",
                "inputs": [],
                "outputs": [
                  {
                    "name": "",
                    "type": "string",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "string"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "wards",
                "constant": true,
                "anonymous": false,
                "stateMutability": "view",
                "inputs": [
                  {
                    "name": "",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  }
                ],
                "outputs": [
                  {
                    "name": "",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "approve",
                "constant": false,
                "anonymous": false,
                "stateMutability": "nonpayable",
                "inputs": [
                  {
                    "name": "usr",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "wad",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ],
                "outputs": [
                  {
                    "name": "",
                    "type": "bool",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "bool"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "mint",
                "constant": false,
                "anonymous": false,
                "stateMutability": "nonpayable",
                "inputs": [
                  {
                    "name": "usr",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "wad",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ],
                "outputs": []
              },
              {
                "type": "function",
                "name": "transferFrom",
                "constant": false,
                "anonymous": false,
                "stateMutability": "nonpayable",
                "inputs": [
                  {
                    "name": "src",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "dst",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "wad",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ],
                "outputs": [
                  {
                    "name": "",
                    "type": "bool",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "bool"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "burn",
                "constant": false,
                "anonymous": false,
                "stateMutability": "nonpayable",
                "inputs": [
                  {
                    "name": "usr",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "wad",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ],
                "outputs": []
              },
              {
                "type": "function",
                "name": "deny",
                "constant": false,
                "anonymous": false,
                "stateMutability": "nonpayable",
                "inputs": [
                  {
                    "name": "guy",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  }
                ],
                "outputs": []
              },
              {
                "type": "function",
                "name": "push",
                "constant": false,
                "anonymous": false,
                "stateMutability": "nonpayable",
                "inputs": [
                  {
                    "name": "usr",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "wad",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ],
                "outputs": []
              },
              {
                "type": "function",
                "name": "nonces",
                "constant": true,
                "anonymous": false,
                "stateMutability": "view",
                "inputs": [
                  {
                    "name": "",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  }
                ],
                "outputs": [
                  {
                    "name": "",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "symbol",
                "constant": true,
                "anonymous": false,
                "stateMutability": "view",
                "inputs": [],
                "outputs": [
                  {
                    "name": "",
                    "type": "string",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "string"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "allowance",
                "constant": true,
                "anonymous": false,
                "stateMutability": "view",
                "inputs": [
                  {
                    "name": "",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  }
                ],
                "outputs": [
                  {
                    "name": "",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "balanceOf",
                "constant": true,
                "anonymous": false,
                "stateMutability": "view",
                "inputs": [
                  {
                    "name": "",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  }
                ],
                "outputs": [
                  {
                    "name": "",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "version",
                "constant": true,
                "anonymous": false,
                "stateMutability": "view",
                "inputs": [],
                "outputs": [
                  {
                    "name": "",
                    "type": "string",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "string"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "PERMIT_TYPEHASH",
                "constant": true,
                "anonymous": false,
                "stateMutability": "view",
                "inputs": [],
                "outputs": [
                  {
                    "name": "",
                    "type": "bytes32",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "bytes"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "transfer",
                "constant": false,
                "anonymous": false,
                "stateMutability": "nonpayable",
                "inputs": [
                  {
                    "name": "dst",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "wad",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ],
                "outputs": [
                  {
                    "name": "",
                    "type": "bool",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "bool"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "decimals",
                "constant": true,
                "anonymous": false,
                "stateMutability": "view",
                "inputs": [],
                "outputs": [
                  {
                    "name": "",
                    "type": "uint8",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "DOMAIN_SEPARATOR",
                "constant": true,
                "anonymous": false,
                "stateMutability": "view",
                "inputs": [],
                "outputs": [
                  {
                    "name": "",
                    "type": "bytes32",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "bytes"
                    }
                  }
                ]
              },
              {
                "type": "function",
                "name": "permit",
                "constant": false,
                "anonymous": false,
                "stateMutability": "nonpayable",
                "inputs": [
                  {
                    "name": "holder",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "spender",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "nonce",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  },
                  {
                    "name": "expiry",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  },
                  {
                    "name": "allowed",
                    "type": "bool",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "bool"
                    }
                  },
                  {
                    "name": "v",
                    "type": "uint8",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  },
                  {
                    "name": "r",
                    "type": "bytes32",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "bytes"
                    }
                  },
                  {
                    "name": "s",
                    "type": "bytes32",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "bytes"
                    }
                  }
                ],
                "outputs": []
              },
              {
                "type": "function",
                "name": "pull",
                "constant": false,
                "anonymous": false,
                "stateMutability": "nonpayable",
                "inputs": [
                  {
                    "name": "usr",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "wad",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ],
                "outputs": []
              },
              {
                "type": "function",
                "name": "rely",
                "constant": false,
                "anonymous": false,
                "stateMutability": "nonpayable",
                "inputs": [
                  {
                    "name": "guy",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "address"
                    }
                  }
                ],
                "outputs": []
              },
              {
                "type": "event",
                "name": "Approval",
                "constant": false,
                "anonymous": false,
                "stateMutability": "",
                "inputs": [
                  {
                    "name": "src",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": true,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "guy",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": true,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "wad",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ],
                "outputs": null
              },
              {
                "type": "event",
                "name": "LogNote",
                "constant": false,
                "anonymous": true,
                "stateMutability": "",
                "inputs": [
                  {
                    "name": "sig",
                    "type": "bytes4",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": true,
                    "simple_type": {
                      "type": "bytes"
                    }
                  },
                  {
                    "name": "usr",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": true,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "arg1",
                    "type": "bytes32",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": true,
                    "simple_type": {
                      "type": "bytes"
                    }
                  },
                  {
                    "name": "arg2",
                    "type": "bytes32",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": true,
                    "simple_type": {
                      "type": "bytes"
                    }
                  },
                  {
                    "name": "data",
                    "type": "bytes",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "bytes"
                    }
                  }
                ],
                "outputs": null
              },
              {
                "type": "event",
                "name": "Transfer",
                "constant": false,
                "anonymous": false,
                "stateMutability": "",
                "inputs": [
                  {
                    "name": "src",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": true,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "dst",
                    "type": "address",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": true,
                    "simple_type": {
                      "type": "address"
                    }
                  },
                  {
                    "name": "wad",
                    "type": "uint256",
                    "storage_location": "default",
                    "components": null,
                    "offset": 0,
                    "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "indexed": false,
                    "simple_type": {
                      "type": "uint"
                    }
                  }
                ],
                "outputs": null
              }
            ],
            "raw_abi": null,
            "states": [
              {
                "name": "DOMAIN_SEPARATOR",
                "type": "bytes32",
                "storage_location": "storage",
                "components": null,
                "offset": 0,
                "index": "0x0000000000000000000000000000000000000000000000000000000000000005",
                "indexed": false,
                "simple_type": {
                  "type": "bytes"
                }
              },
              {
                "name": "wards",
                "type": "mapping (address => uint256)",
                "storage_location": "storage",
                "components": null,
                "offset": 0,
                "index": "0x0000000000000000000000000000000000000000000000000000000000000000",
                "indexed": false
              },
              {
                "name": "totalSupply",
                "type": "uint256",
                "storage_location": "storage",
                "components": null,
                "offset": 0,
                "index": "0x0000000000000000000000000000000000000000000000000000000000000001",
                "indexed": false,
                "simple_type": {
                  "type": "uint"
                }
              },
              {
                "name": "balanceOf",
                "type": "mapping (address => uint256)",
                "storage_location": "storage",
                "components": null,
                "offset": 0,
                "index": "0x0000000000000000000000000000000000000000000000000000000000000002",
                "indexed": false
              },
              {
                "name": "allowance",
                "type": "mapping (address => mapping (address => uint256))",
                "storage_location": "storage",
                "components": null,
                "offset": 0,
                "index": "0x0000000000000000000000000000000000000000000000000000000000000003",
                "indexed": false
              },
              {
                "name": "nonces",
                "type": "mapping (address => uint256)",
                "storage_location": "storage",
                "components": null,
                "offset": 0,
                "index": "0x0000000000000000000000000000000000000000000000000000000000000004",
                "indexed": false
              }
            ]
          },
          "creation_block": 0,
          "creation_tx": "",
          "creator_address": "",
          "created_at": "2022-12-16T09:10:37Z",
          "number_of_watches": null,
          "language": "solidity",
          "in_project": false,
          "number_of_files": 1
        }
      ],
      "generated_access_list": []
    }
    ```
  </Tab>
</Tabs>

## Storage Slot Calculation

The key part of setting an override is calculating the correct storage location. This depends on the structure of the contract's storage and the specific variable you want to override.

For the DAI contract, the storage location for the `wards` mapping for our address is calculated based on the [Solidity storage layout rules](https://docs.soliditylang.org/en/latest/internals/layout_in_storage.html#mappings-and-dynamic-arrays), and is given by this expression:

```js title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const fakeWardAddress = '0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2';
const overrideStorageLocation = keccak256(
  concatenate(
    hexZeroPad(fakeWardAddress), hexZeroPad(0x0)
  )
)
```

In our example, the storage location is:  `0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03`.

## Explore

<Card title="How to override Gnosis Safe contracts" href="" />


# Transaction Preview
Source: https://docs.tenderly.co/simulations/transaction-preview

Learn how the add a Transaction Preview option to your dapp or wallet powered by Tenderly's Simulation API.

Learn how the add a Transaction Preview option to your dapp or wallet powered by [Tenderly's Transaction Simulations](/simulations/single-simulations). We give you two practical examples that demonstrate how to integrate simulations into real wallets:

* [MetaMask Snap with Transaction Preview](/simulations/transaction-preview#metamask-snap-with-transaction-preview)
* [Rabby Wallet with Transaction Preview](/simulations/transaction-preview#rabby-wallet-with-transaction-preview)

## What is Transaction Preview?

Transaction Preview offers a secure testing solution for dapps and wallets, enabling users to preview transaction outcomes before they're executed on the live network. This solution uses Tenderly's [Simulation API](/simulations/single-simulations#simulate-via-api) to dry-run transactions in a virtual environment that mimics the latest state of the blockchain. This is to ensure that simulation results are realistic and highly reliable.

Here's an example project that demonstrates how the Transaction Preview option works in the Rabby Wallet.

<iframe />

## Why wallet users need simulations

Giving users a way to preview transactions before committing real assets is beneficial for several reasons.
First, it helps users, especially those new to trading, avoid mistakes by letting them practice before making real transactions. This makes it easier for them to start using your wallet and build trust. Second, it helps users understand how much they will be charged in fees, which can save them money. But most importantly, it can alert users about potential security red flags before signing transactions.

Tenderly's Simulation API helps you to achieve these goals by allowing you to:

* [Display asset and balance changes](/simulations/asset-balance-changes), including fungible, non-fungible, and native tokens, converted into dollars based on prices coming from CoinGecko.
* [Give accurate gas usage estimates](/simulations/gas-estimation) to execute their transactions and help them save money.
* Tell users if their transaction will fail and help them save on gas.
* Help users understand why their transactions are failing with human-readable errors.
* Provide users with an [access list](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=eth_createAccessList) of addresses and storage slots the transaction will access.
* Get emitted events, log names, and related parameters in decoded form.
* Validate transaction workflows on DeFi platforms with [bundled simulations](/simulations/bundled-simulations) when executing and approving swaps that entail multiple intermediate steps.

## Integrating simulations into a wallet

We created two open-source projects to show you the process of integrating Tenderly's Simulation API into your dapp or wallet. These examples showcase how to add a Transaction Preview feature to a MetaMask Snap and Rabby Wallet.

You can download the source code for both projects from GitHub. Also, be sure to check out the [Simulation API reference](/api-reference) for guidance on how to make requests to the API and query the results.

<Card title="MetaMask Snap With Transaction Preview" href="" />

<Card title="Rabby Wallet With Transaction Preview" href="" />

### MetaMask Snap with Transaction Preview

The [MetaMask Snap](https://metamask.io/snaps/) project demonstrates how to connect to the Simulation API, send transaction data, retrieve the simulation results, and display them to the user in the MetaMask UI. This includes asset changes in dollars, native-asset balance changes, output value, storage changes, event logs, and call traces.

<iframe />

#### ERC20 transfer example

Here's a successful ERC20 token transfer example, where 1 USDC is sent to demo.eth. The first image illustrates the asset changes that have occurred, followed by the breakdown of the transaction details.

<img alt="" />

#### NFT transfer example

Below is an example ERC721 (NFT) token transfer example. This example involves transferring 1 Crypto Bull to another address. The first screenshot shows the asset changes and the image on the right image shows the transaction details.

<img alt="" />

Want to try this integration yourself? Follow this detailed guide where we show you step-by-step how to integrate the Tenderly Simulation API, process transaction data, obtain simulation results via API, and display them through the MetaMask Snap UI.

<Card title="Guide: How to Add Transaction Preview to a MetaMask Snap" href="" />

### Rabby Wallet with Transaction Preview

The second project shows you how to integrate our Simulation API into the [Rabby Wallet](https://github.com/RabbyHub/Rabby) and give users a way to preview transaction outcomes in the UI. When the user is confident that the transaction will behave as expected, they can sign it in the UI.

<iframe />

#### ERC20 token swap on Uniswap example

The image below shows a successful swap of ETH for 1INCH on Uniswap, displaying both the asset changes and a detailed transaction breakdown to the user in the Rabby Wallet UI.

<img alt="" />

#### NFT purchase on Joepegs example

Here's an example of a successful NFT purchase with asset changes and a summary of the simulation results.

<img alt="" />

Want to try to integrate simulations into the Rabby Wallet? Follow this step-by-step guide.

<Card title="Guide: How to Add Transaction Preview to a Rabby Wallet" href="" />


# Prefill the Simulator with a draft link
Source: https://docs.tenderly.co/simulator-ui/draft-links

Build a base64url-encoded URL that opens the Tenderly Simulator with a pre-filled transaction form, for sharing simulations from CI or tooling.

A draft link opens the [Tenderly Simulator](/simulator-ui/overview) with a pre-filled form. Nothing runs until the recipient clicks **Simulate**, so the link is safe to share in test reports, pull requests, or alerts.

A draft prefills a **single simulation**, not a [bundle](/simulator-ui/simulation-bundles). It populates one transaction form (one `row`); it does not reconstruct a multi-step bundle.

## URL format

The link is the Simulator's new-simulation route with a `draft` query parameter:

`https://dashboard.tenderly.co/<org>/<project>/simulator/new?draft=<value>`

`<value>` is the draft JSON payload, UTF-8 encoded, then **base64url**: standard base64 with `+` replaced by `-`, `/` replaced by `_`, and `=` padding stripped.

<Tip>
  For a one-off share you do not need a script. Fill the form in the Simulator and click **Copy draft link** in the page header (shown while the bundle has a single simulation). The rest of this page is for generating links programmatically, from CI, test reports, or other tooling.
</Tip>

## Quick start

A minimal raw-calldata draft is all most CI scripts need. The `to` address goes in `contractAddress`, and the calldata goes in `rawFunctionInput`:

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "v": 1,
  "network": { "id": "1" },
  "row": {
    "contractAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "from": "0xab5801a7d398351b8be11c439e05c5b3259aec9b",
    "inputDataType": "raw",
    "rawFunctionInput": "0xa9059cbb…"
  }
}
```

Encode that payload and append it to the URL:

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import base64, json

payload = {
    "v": 1,
    "network": {"id": "1"},
    "row": {
        "contractAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
        "from": "0xab5801a7d398351b8be11c439e05c5b3259aec9b",
        "inputDataType": "raw",
        "rawFunctionInput": "0xa9059cbb…",
    },
}

draft = base64.urlsafe_b64encode(json.dumps(payload).encode()).decode().rstrip("=")
url = f"https://dashboard.tenderly.co/<org>/<project>/simulator/new?draft={draft}"
```

```javascript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// Node.js
const payload = {
  v: 1,
  network: { id: "1" },
  row: {
    contractAddress: "0xdac17f958d2ee523a2206206994597c13d831ec7",
    from: "0xab5801a7d398351b8be11c439e05c5b3259aec9b",
    inputDataType: "raw",
    rawFunctionInput: "0xa9059cbb…",
  },
};

const draft = Buffer.from(JSON.stringify(payload)).toString("base64url");
const url = `https://dashboard.tenderly.co/<org>/<project>/simulator/new?draft=${draft}`;
```

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Shell, reading the payload from payload.json (GNU coreutils)
DRAFT=$(jq -c . payload.json | basenc --base64url -w0 | tr -d '=')
# macOS fallback:
DRAFT=$(jq -c . payload.json | base64 | tr '+/' '-_' | tr -d '=\n')
```

## Top-level payload

| Field     | Type                         | Required | Description                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `v`       | number                       | yes      | Schema version. Must be `1`.                                                                                                                                                                                                                                                                                                                                                        |
| `network` | `{ "id": string }` or `null` | yes      | Chain id as a **string** (`"1"` is Mainnet, `"56"` is BNB Chain, and so on). Must be a network enabled on the recipient's project, otherwise they get a "network not available" error and an empty form. Always set it. `null` is accepted but skips the contract lookup and leaves the form mostly unusable. See [Supported Networks](/platform/supported-networks) for chain ids. |
| `row`     | object                       | yes      | The form fields. See [`row` fields](#row-fields) below.                                                                                                                                                                                                                                                                                                                             |

## `row` fields

Only `contractAddress` is required. Omit anything you do not need. Omitted fields keep the form's defaults, and unknown extra fields are ignored.

### Contract and function

| Field               | Type                   | Description                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contractAddress`   | string                 | **Required.** The "to" address. The contract and its ABI are fetched on the recipient's side when the link opens.                                                                                                                                                                                                                                                                         |
| `inputDataType`     | `"decoded"` or `"raw"` | Selects the function-input mode. Use `"raw"` with `rawFunctionInput`, or `"decoded"` with `contractFunction` and `functionInputs`.                                                                                                                                                                                                                                                        |
| `rawFunctionInput`  | string                 | Hex calldata (`0x…`) for raw mode. No ABI needed, which makes it the most robust option for scripts.                                                                                                                                                                                                                                                                                      |
| `contractFunction`  | object or `null`       | Decoded-mode function reference: `{ "name": string, "selector"?: string, "signature"?: string }`. `name` is required inside the object. `selector` (4-byte hex, e.g. `"0xa9059cbb"`) is optional but preferred: it is matched first and is exact for overloaded functions. Without it, matching falls back to `name` and may pick the wrong overload. `signature` is informational only.  |
| `functionInputs`    | array or object        | Decoded-mode argument values. Preferred: a **positional array** in ABI order, for example `["0xabc…", "1000000", ["0xa…", "0xb…"]]`. Values are strings, numbers, or booleans. Array and tuple arguments may be passed natively as nested arrays or objects, with no pre-stringifying needed. The keyed form `{ "input_0": … }` is also accepted (it is what the UI's Copy button emits). |
| `contractAbiImport` | string                 | Pre-fills the in-app "Edit ABI" field. Function matching on open uses the **fetched** ABI only, so this field does not make decoded mode work for unverified contracts. Use raw calldata for those.                                                                                                                                                                                       |

### Transaction parameters

| Field      | Type             | Description                  |
| ---------- | ---------------- | ---------------------------- |
| `from`     | string           | Sender address.              |
| `gas`      | string or number | Gas limit, e.g. `"8000000"`. |
| `gasPrice` | string or number | Gas price in wei.            |
| `value`    | string or number | Native-token value in wei.   |

### Block selection

| Field             | Type                      | Description                                                                                          |
| ----------------- | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `block`           | string or number          | Block number to simulate at. Omit for the chain head.                                                |
| `blockIndex`      | string, number, or `null` | Transaction position inside the block. `null` or omitted means the start of the block.               |
| `endOfBlock`      | boolean                   | `true` runs the simulated transaction after every transaction in the block (overrides `blockIndex`). |
| `usePendingBlock` | boolean                   | `true` simulates on the pending block instead of a fixed number.                                     |

See [Simulation Parameters](/simulator-ui/parameters#pending-vs-historical-block) for how block selection and transaction index behave in the UI.

### L2 parameters

These fields apply to OP-stack and Boba networks only.

| Field             | Type    | Description                        |
| ----------------- | ------- | ---------------------------------- |
| `depositTx`       | boolean | Mark as an L2 deposit transaction. |
| `systemTx`        | boolean | Mark as an L2 system transaction.  |
| `mint`            | string  | Deposit mint amount.               |
| `l1BlockNumber`   | string  | Originating L1 block number.       |
| `l1Timestamp`     | string  | Originating L1 timestamp.          |
| `l1MessageSender` | string  | L1 message sender address.         |
| `l1Turing`        | string  | Boba Turing data.                  |

### Overrides

| Field                  | Type   | Description                                                                                                                                                                                                                                                                                                                                       |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blockHeaderOverrides` | object | `{ "number"?: …, "timestamp"?: … }`, each a string, number, or `null`. Overrides the simulated block header.                                                                                                                                                                                                                                      |
| `stateOverrides`       | array  | Per-contract [state overrides](/simulator-ui/state-overrides): `{ "id"?: string, "contractAddress": string, "balance": string, "storage"?: [{ "key": string, "value": string }], "code"?: string }`. `id` is optional and generated when absent. `balance` is in wei (`""` means no balance override). `storage` keys and values are 32-byte hex. |
| `accessList`           | array  | [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) access list: `{ "address": string, "storageKeys": string[] }`.                                                                                                                                                                                                                                |

Two override types are UI-only and cannot be set in a draft. Configure them in the app after opening the link: **fund-address ERC-20 overrides** and **custom Solidity sources** (the in-app "Edit source" feature).

## Validation

Draft hydration is all-or-nothing. A missing required field, a wrong `v`, or any wrong-typed field rejects the **whole** payload: the recipient sees "This draft link is invalid or corrupted" and an empty form. There is no partial hydration, so a broken script fails visibly instead of half-working.

## Limits and tips

* Keep the final URL under **2000 characters**. The app refuses to copy longer links, and browsers and proxies may truncate them. Decoded calls with many inputs land around \~1900.
* **Discovering payload shapes:** fill the form in the Simulator UI, click **Copy draft link**, and base64url-decode the `draft` value. The result is a known-good payload for your exact use case, and it is the best way to get the advanced shapes (`stateOverrides`, `accessList`) right.
* The contract ABI is fetched when the link opens. If it cannot be resolved (an unverified contract), decoded-mode drafts open with the address filled but no function selected. Raw mode is immune to this.

For the form fields a draft populates, see [Simulation Parameters](/simulator-ui/parameters). To keep a modified state as a persistent environment instead of a one-shot simulation, use [Virtual Environments](/virtual-environments/overview).


# Editing Contract Source
Source: https://docs.tenderly.co/simulator-ui/editing-contract-source

Edit contract source code, compiler settings, or the ABI inline while building a simulation, and run the modified code against live network state.

Once you select a contract in a simulation step in the [Simulator UI](/simulator-ui/overview), two buttons appear next to the **Contract** field: **Edit source** and **Edit ABI**. They let you change what code the simulation executes without touching the deployed contract, so you can test a bug fix, tweak a parameter, or try new logic against live production state before deploying anything.

The same controls are available when you re-simulate: clicking **Re-Simulate** on a transaction detail page loads its inputs into the builder, where you can edit the source and run again.

## Edit source

Click **Edit source** to open the source editor.

<Frame>
  <img alt="Editing Source view showing the Dai contract address, a File dropdown with Dai.sol, the Solidity source in an editor, and a Select Contract Name dropdown, with Compiler Info, the Dai contract entry, Add contract source, and Apply Changes in the left panel" />
</Frame>

The editing pane shows:

| Element                  | Notes                                                             |
| ------------------------ | ----------------------------------------------------------------- |
| **Address**              | The address whose code you are editing.                           |
| **File**                 | Dropdown to switch between source files for multi-file contracts. |
| **Editor**               | The full source, editable line by line.                           |
| **Select Contract Name** | Which contract in the file is deployed at the address.            |

Edits apply only to your simulation. The deployed contract and other project members' simulations are unaffected.

Click **Apply Changes** in the bottom-left corner to save the edits, then run the simulation. The step executes the modified code with the rest of the network state untouched.

### Compiler settings

Select **Compiler Info** in the left panel to adjust how the edited source is compiled:

<Frame>
  <img alt="Compiler Info pane showing Compiler Version solc v0.5.12, Optimization Used false, Optimization Count 200, EVM Version petersburg, and a ViaIR toggle" />
</Frame>

* **Compiler Version**
* **Optimization Used** and **Optimization Count**
* **EVM Version**
* **ViaIR**

The settings load from the contract's verification metadata, so a plain edit-and-run needs no compiler changes.

### Add contract source

Click **Add contract source** in the left panel to edit additional contracts in the same simulation. Enter the address of any deployed contract and its source loads as another entry in the list. This lets one simulation run modified code for several contracts at once, for example a router and the pool it calls into.

## Edit ABI

Click **Edit ABI** to open a JSON editor over the ABI the builder uses to decode functions and encode your inputs.

<Frame>
  <img alt="Edit ABI dialog showing the contract ABI as JSON with constructor and function entries, and Cancel and Save buttons" />
</Frame>

Editing the ABI is useful when a contract is unverified or its interface differs from the published ABI: paste or adjust the JSON, click **Save**, and the **Function** dropdown and argument fields follow the updated definition. For how those inputs map to a simulation, see [simulation parameters](/simulator-ui/parameters).


# Simulator UI
Source: https://docs.tenderly.co/simulator-ui/overview

Build single-transaction simulations or stateful bundles in the Tenderly dashboard with decoded traces, gas estimates, balance changes, and cheatcodes.

<Frame>
  <img alt="Tenderly Simulator landing page showing the Simulate transaction button and three feature cards: Unlock the blockchain, Inspect and debug errors, Integrate in your dapp" />
</Frame>

The Tenderly Simulator lets you run transactions against live mainnet or testnet state without broadcasting anything. You can simulate as any sender, override contract storage, fund addresses, and manipulate block context, all from the dashboard.

The builder is the same whether you run one transaction or five. A **single simulation** is a one-step bundle. A **[simulation bundle](/simulator-ui/simulation-bundles)** is up to five steps that share state: each step sees the state changes made by the step before it.

## Layout

The builder has three regions:

**Session strip** runs across the top. It holds defaults that apply to every step: Network, Block (defaults to `Pending`), and a default From address. Click **Configure** to set default gas, gas price, and value.

**Bundle rail** is the left column. Each step card shows a step number, a label (`New call` until a contract is chosen, then `ContractName · functionName`), and a status badge after a run. Click a step to focus it. Drag to reorder. Use `C` to add a step, `J`/`K` to move between steps, and `F` to toggle focus mode.

**Focused step view** is the right column. Before running, it shows the step editor. After running, it shows that step's result: decoded output, gas used, events, state changes, and token transfers.

## Single simulations

To run a single simulation, work with the one step that opens by default.

**Decoded mode** lets you pick a contract and function by name:

| Field          | Notes                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| **From**       | Defaults to the session From. Override per step.                                                           |
| **Contract**   | Project contracts surface first. Also matches public contracts and top tokens by name, symbol, or address. |
| **Function**   | Filtered to non-event, non-constructor methods.                                                            |
| **Parameters** | One typed input per ABI argument.                                                                          |

**Raw mode** takes a target address and a `0x`-prefixed hex payload directly. This is useful when you have calldata from an existing transaction or a manual encode.

Click **Simulate** (or press `⌘↵`) to run. The right panel fills with the result: function call summary, gas used, decoded output, and tabs for Events, State Changes, Fund Flow, and Gas Profiler.

You can also start from an existing transaction: click **Re-Simulate** on any transaction detail page to load its inputs into the builder. The simulation runs on the block and timestamp of the original by default.

To share a pre-filled form (for example from CI or a test report), click **Copy draft link** in the page header, or build the link yourself. See [Prefill the Simulator with a draft link](/simulator-ui/draft-links).

## Simulation bundles

A bundle runs up to **five steps** in sequence, sharing state. Use a bundle when the outcome of one transaction depends on a previous one, for example, an approval that enables a later transfer. Steps are added and reordered in the rail, each with its own From override and cheatcodes, and the whole bundle executes with one click of **Simulate**.

See [Simulation Bundles](/simulator-ui/simulation-bundles) for building, reordering, result badges, and how bundles appear in the simulation history.

<Frame>
  <img alt="New Simulation builder showing session strip with network and block selectors, transaction parameters (From, Contract, Function), and collapsed cheatcode sections for Override gas, Fund address, Increase block, Override timestamp, State overrides, and Optional Access Lists" />
</Frame>

## Cheatcodes

Each step has a set of cheatcodes (add-ons that run immediately before the step executes). They apply to both single simulations (as step-level controls) and each step in a bundle.

| Cheatcode                 | What it does                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Override gas & value**  | Set a custom gas limit and ETH value for this step.                                                           |
| **Fund address**          | Credit any address with token balances before this step runs. Add multiple entries per step.                  |
| **Increase block**        | Advance the block number by a fixed amount before this step.                                                  |
| **Override timestamp**    | Set a custom block timestamp for this step.                                                                   |
| **State overrides**       | Override contract storage slots, balance, or bytecode before this step. Add overrides for multiple contracts. |
| **Optional Access Lists** | Attach an EIP-2930 access list for gas efficiency on multi-contract calls.                                    |

<Frame>
  <img alt="Step editor showing Fund address, Override timestamp, and State overrides cheatcodes expanded" />
</Frame>

For a detailed walkthrough of state overrides, including storage slot calculation, see [Simulation with State Overrides](/simulator-ui/state-overrides).

## See also

* [Simulation Bundles](/simulator-ui/simulation-bundles): multi-step simulations with shared state, including the 3-step DAI mint, approve, and transferFrom guide.
* [Simulation Mode](/simulator-ui/simulation-mode): persistent wallet impersonation that follows you across the dashboard and accumulates state across runs.
* [Simulation with State Overrides](/simulator-ui/state-overrides): how to override storage, balance, and bytecode.
* [Simulation Parameters](/simulator-ui/parameters): full reference for session defaults, block and transaction index selection, From addresses, and cheatcode fields.
* [Prefill the Simulator with a draft link](/simulator-ui/draft-links): build a base64url URL that opens the Simulator with a pre-filled form, for sharing from CI or tooling.
* [Editing Contract Source](/simulator-ui/editing-contract-source): test a bug fix by running a simulation against modified source code.
* [Bundled Simulations (API)](/simulations/bundled-simulations): run bundles programmatically via the `simulate-bundle` endpoint.
* [Virtual Environments](/virtual-environments/overview): when you need a full persistent RPC environment instead of a stateless bundle.


# Simulation Parameters
Source: https://docs.tenderly.co/simulator-ui/parameters

Reference for every input in the simulation builder: session defaults, block and transaction index, sender addresses, step fields, and per-step cheatcodes.

The simulation builder splits its inputs across three surfaces:

* **Session defaults** in the strip at the top apply to every step: Network, Block, and the default From address. Click **Configure** to edit them.
* **Step fields** define the call itself: sender, target contract, function, and arguments.
* **Cheatcodes** below the step fields modify the execution environment immediately before the step runs.

For the overall builder layout (session strip, bundle rail, focused step view), see the [Simulator UI overview](/simulator-ui/overview#layout).

## Session defaults

Click **Configure** in the session strip to open the defaults panel. Values set here apply to every new step in the bundle.

<Frame>
  <img alt="Configure panel showing Network details with Mainnet, a pinned block number, Tx Index set to At start of block, Gas, Gas Price, Value, and the Send transaction from address" />
</Frame>

| Field                     | Notes                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| **Network**               | The network whose state the simulation runs against.                                       |
| **Block number**          | Defaults to `Pending`. Type a block number to pin the simulation to a historical block.    |
| **Tx Index**              | The transaction's position within the pinned block. Only available once a block is pinned. |
| **Gas**                   | Default gas limit for each step. Defaults to `8000000`.                                    |
| **Gas Price**             | Default gas price in Wei.                                                                  |
| **Value**                 | Default ETH value sent with each step.                                                     |
| **Send transaction from** | Default From address for new steps.                                                        |

### Pending vs historical block

Leave **Block number** empty to simulate on the **pending block**. Tenderly executes the bundle against the latest available network state, as if it were included in the next block.

Type a block number to simulate on a **historical block**. The bundle then executes against the chain state as it was at that block, on any block going back to the start of the network. With a block pinned, **Tx Index** controls where in the block the simulation executes:

| Option                | Meaning                                                                                            |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| **At start of block** | Execute before any of the block's transactions.                                                    |
| **At tx**             | Execute at a specific transaction index. The input shows how many transactions the block contains. |
| **At end of block**   | Execute after all of the block's transactions.                                                     |

<Frame>
  <img alt="Configure panel with block number 25250000 pinned and the Tx Index menu open showing At start of block, At tx, and At end of block options" />
</Frame>

## From addresses

Simulations need no private keys or signatures, so any address can act as the sender. The From dropdown offers:

* The **zero address** (`0x0000…0000`), the default sender.
* Your **project wallets** on the selected network, grouped under "Selected network". Changing the network changes which wallets appear.
* Any address you **paste or search** in the input at the top of the dropdown.

<Frame>
  <img alt="Send transaction from dropdown open, showing a search input, the zero address, and two project wallets grouped under Selected network" />
</Frame>

The address set in the Configure panel is the default for new steps. Each step also has its own **From** field in the step editor, so different steps in a bundle can use different senders.

## Step fields

Each step is built in **Decoded** or **Raw** mode, toggled at the top of the step editor.

<Frame>
  <img alt="Step editor showing the Dai contract selected, the transfer function with dst address and wad uint256 inputs, and the Override gas & value, Fund address, and Increase block cheatcodes" />
</Frame>

**Decoded mode** builds the call from the contract's ABI:

| Field         | Notes                                                                                                                                                                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **From**      | The step's sender. Defaults to the session From.                                                                                                                                                                                                    |
| **Contract**  | Project contracts surface first; also matches public contracts and top tokens by name, symbol, or address. Once selected, **Edit source** and **Edit ABI** become available (see [Editing Contract Source](/simulator-ui/editing-contract-source)). |
| **Function**  | Filtered to non-event, non-constructor methods.                                                                                                                                                                                                     |
| **Arguments** | One typed input per ABI argument. Address arguments get an address picker; value arguments get plain inputs.                                                                                                                                        |

**Raw mode** takes a target address and a `0x`-prefixed hex payload directly. Use it when you already have calldata from an existing transaction or a manual encode.

## Cheatcodes

Each step carries six cheatcode sections. They run immediately before the step executes and are scoped to that step only.

### Override gas & value

Set a custom **Gas** limit, **Gas price**, and **Value** for this step, overriding the session defaults.

### Fund address

Credit any address with token balances before the step runs. Each entry takes a **Target address**, a **token** (searchable by symbol, name, or address), and an amount. Click **Add more tokens** to fund multiple tokens, and add further entries for other addresses.

To set an address's native balance instead, use the custom balance switch in [State overrides](#state-overrides).

### Increase block

Advance the block number by an offset before the step executes. The section shows the current block and the resulting block. Contracts that read `block.number` see the increased value.

### Override timestamp

Set the block timestamp the step executes with, in one of two modes:

* **Increase time**: advance the clock by an amount and unit (seconds, minutes, and so on).
* **Set UNIX timestamp**: jump to an absolute timestamp.

The section previews the resulting date and time. Contracts that read `block.timestamp` see the overridden value.

### State overrides

Override contract state before the step runs. Each override targets one contract (defaulting to the step's target) and supports:

* **Use custom balance**: set the contract's native balance.
* **Storage variables**: key and value pairs for individual storage slots, with **Add storage override** for more slots.

Click **Add State Override** to override additional contracts in the same step. For a walkthrough including storage slot calculation, see [Simulation with State Overrides](/simulator-ui/state-overrides).

### Optional Access Lists

Attach an [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) access list to the step. Announcing the contracts and storage keys the transaction touches can lower its gas cost on calls spanning many contracts. Add addresses one by one or import the list as JSON.

## Saving a starting point

Simulations are stateless: each run starts from the configured block. To keep a modified state (overrides, funded accounts, advanced timestamps) as a persistent environment you can keep transacting against, use [Virtual Environments](/virtual-environments/overview).


# Simulation Bundles
Source: https://docs.tenderly.co/simulator-ui/simulation-bundles

Run up to five simulated transactions that share state, where each step sees prior changes. Build and inspect multi-step flows in the simulation builder.

A simulation bundle runs up to **five transactions in sequence against shared state**: each step sees the state changes made by the step before it. Use a bundle whenever one transaction depends on another, for example an approval that enables a later `transferFrom`, or a deposit that a subsequent withdrawal spends.

Bundles use the same builder as single simulations. A single simulation is simply a one-step bundle, so nothing changes about the editor when you add more steps.

<Frame>
  <img alt="Simulator UI showing three steps in the bundle rail and step results on the right" />
</Frame>

## Building a bundle

Start from **Simulator → New Simulation** and configure the first step as usual. Then grow the bundle from the rail on the left:

* **Add a step** with the **+** button under the step cards.
* **Import a transaction** with the import button: paste an existing transaction hash or raw payload and its inputs load as a new step.
* **Reorder** steps by dragging their cards. Steps execute in rail order.

Each step is independent in everything except state: it has its own Decoded/Raw toggle, its own **From** override, and its own set of [cheatcodes](/simulator-ui/parameters#cheatcodes) (gas and value overrides, funded addresses, block and timestamp manipulation, state overrides, access lists). Cheatcodes run immediately before their step.

The bundle is the unit of execution: clicking **Simulate** runs all steps at once, in order, on the network and block configured in the session strip.

## Reading the results

After a run, each step card in the rail shows a result badge:

| Badge           | Meaning                                                                 |
| --------------- | ----------------------------------------------------------------------- |
| Green checkmark | Step succeeded.                                                         |
| Red ✗           | Step reverted or failed pre-EVM (malformed calldata, unknown contract). |

Click any step card to focus its individual result in the right panel: decoded output, gas used, and the Events, State, Fund Flow, and Gas Profiler tabs for that step.

State flows forward only. A balance minted in step 1 is visible to steps 2 through 5, but a revert in a later step does not undo earlier steps' results in the displayed output; each step's view reflects the state at its position in the sequence.

## Bundles in the simulation history

Executed bundles appear in the **Simulator** list as a single `Bundle (N txs)` row showing the shared network, block, and call count. Expand the row to see each step as its own entry with its individual status and function.

<Frame>
  <img alt="Simulator list with an expanded bundle row showing individual mint, approve, and transferFrom steps, and collapsed Bundle rows with call counts" />
</Frame>

## Limits

* Five steps per bundle.
* Cheatcodes are step-scoped. There is no bundle-level cheatcode surface.
* Bundles are stateless between runs: re-running starts again from the configured block. For a persistent environment that accumulates state across many transactions, use [Virtual Environments](/virtual-environments/overview).

## Worked example

[Simulate a Token Mint, Approve, and TransferFrom Bundle](/simulations/guides/mint-approve-transfer-bundle) builds a complete 3-step DAI bundle, including the state override that lets the mint succeed and the step-by-step results.

To run bundles programmatically instead, see [Bundled Simulations](/simulations/bundled-simulations) in the Simulation API.


# Simulation Mode
Source: https://docs.tenderly.co/simulator-ui/simulation-mode

Activate a persistent wallet impersonation context in the dashboard. Pages render as the target wallet with balance overrides and a cumulative session log.

Simulation Mode is a persistent impersonation context. Activate it with a wallet address and a network, and every wired page in the dashboard reads and simulates as that wallet. Nothing is signed and nothing goes onchain. Simulations accumulate in a session: each run sees the state changes produced by the previous ones.

<Frame>
  <img alt="Simulation Mode side panel open from the Enter Simulation Mode button, showing wallet search input and three capability descriptions" />
</Frame>

## When to use it

* **Walk through a wallet's onchain behavior** without holding its keys. Useful for support, risk reviews, or post-incident analysis.
* **Stage a sequence of actions** as a specific wallet (e.g. supply, borrow, repay) and inspect the cumulative state effects.
* **Test from the wallet's perspective** on contract Read/Write pages, the Simulator, and re-simulation flows, all without re-entering the address every time.
* **Override token balances** on the fly to test what an action would look like with more (or less) of an asset.

If you only need a one-off simulation or a multi-step bundle, use the [Simulator](/simulator-ui/overview). If you need a full RPC environment, use a [Virtual Environment](/virtual-environments/overview).

## How a session is built

| Property          | Behavior                                                                                              |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| **Keyed by**      | `(wallet, network)`. One active session at a time.                                                    |
| **Persistence**   | The session survives exiting and re-entering Simulation Mode for the same `(wallet, network)` pair.   |
| **Cumulative**    | Every successful simulation appends to the session log and its state carries forward to the next one. |
| **Reset**         | The **Reset session** action clears state for the active session.                                     |
| **Cross-network** | Switching networks resets the active session.                                                         |

## Entering Simulation Mode

Click **Enter Simulation Mode** in the top bar, or use the **Impersonate** action on any wallet detail page to pre-fill Sim Mode with that wallet.

Once active, the top-bar button is replaced with a `SIMULATING` pill showing the impersonated wallet's identity icon, abbreviated address, and total USD balance.

<Frame>
  <img alt="Top bar showing Enter Simulation Mode button and the Simulation Mode panel with wallet search input expanded" />
</Frame>

## The Sim Mode panel

The active Sim Mode panel anchors to the top-right of the dashboard. It has four parts:

* **Network row**: current network with a dropdown to switch.
* **State row**: block number, block position, and timestamp settings (default: latest block, end of block, auto timestamp).
* **Wallet card**: identity icon, abbreviated address, USD balance, and refresh.
* **Tabs**: **Tokens** and **Simulated transactions**.

### Tokens tab

Lists tokens held by the impersonated wallet on the active network.

* Click the **+** on any row to open an inline editor pre-filled with the live balance.
* An overridden row shows the simulated amount, a green diff badge (e.g. `+123.3K`), an undo control, and an edit control.
* Top of the list shows the count of simulated balances and a **Reset to live** action.
* Bottom: **+ Add tokens** opens the funding flow for tokens the wallet doesn't currently hold.

<Frame>
  <img alt="Simulation Mode Tokens tab showing 1 simulated balance badge, Reset to live link, and the ETH row with an amount-to-add input field open alongside other token rows" />
</Frame>

### Simulated transactions tab

A session log of successful simulations in this session.

* Each row: status dot, function name, relative time.
* Bottom action bar: **▷ Simulate** (primary), **↺ Reset session**, **⚡ Convert to Virtual Environment**, **◆ Send onchain**.

<Frame>
  <img alt="Simulation Mode panel showing the Simulated transactions tab with empty session log and the Simulate / Reset / Open in Virtual Environment action bar pinned to the bottom" />
</Frame>

### State settings

Click the **State** row to expose the underlying simulation parameters:

| Field             | Default     |
| ----------------- | ----------- |
| Block number      | Latest      |
| Position in block | At end      |
| Block timestamp   | Auto        |
| Gas               | `8,000,000` |
| Gas price         | `0`         |
| Value             | `0`         |

## Switching network

The network picker is **sorted by the impersonated wallet's total value, descending**, with a per-network balance preview.

Switching network **resets the active session**. The new network starts fresh with no balance overrides and an empty simulation log.

## Wired surfaces

When Simulation Mode is active, these surfaces pick up the session context automatically:

| Surface                             | Behavior                                                                                                                                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Simulator**                       | Sender pre-fills as the impersonated wallet. Successful sims append to the session log.                                                                                  |
| **Contract Read/Write pages**       | A purple banner indicates Sim Mode is active. The Write button is hidden. Simulate becomes the primary action. The `From` field auto-fills with the impersonated wallet. |
| **Re-Simulate (tx and sim detail)** | The Re-Simulate dropdown gains a **Re-simulate as \[wallet]** option. Re-simulations from here do not append to the session log.                                         |
| **Wallet detail pages**             | An **Impersonate** button sits between Create Alert and Simulate. Pre-fills Sim Mode with that wallet.                                                                   |

### Cross-network mismatch

If you open a page on a network different from your active Sim Mode session, a banner offers a one-click **Switch Sim Mode to \[network]**. Read and Write actions are disabled until you switch.

### Replacing the active session

If you start a Simulation Mode flow on a different `(wallet, network)` pair than the active one, a modal confirms the switch. Switching ends the active session.

## Limits

Simulation Mode usage counts against your account's simulation quota. There is no separate per-session limit. The number of sessions you can run is bounded by how many simulations your plan allows.

## See also

* [Simulator UI](/simulator-ui/overview): single simulations and multi-step bundles.
* [Virtual Environments](/virtual-environments/overview): when you need a full RPC environment.


# Simulation with State Overrides
Source: https://docs.tenderly.co/simulator-ui/state-overrides

Use state overrides in the simulation builder to set custom contract state before a simulation runs, demonstrated by minting DAI from a non-ward address.

State overrides set custom values for a contract's storage before a simulation executes. Use them to satisfy access-control checks, plant balances, or set any storage slot to the value your scenario needs, without owning the keys or state on the real network.

This page walks through a complete example. For the field-level reference of the State overrides cheatcode, see [Simulation Parameters](/simulator-ui/parameters#state-overrides).

## Example: minting 2 DAI

We'll simulate minting 2 DAI (`2000000000000000000` wei) to the holder `0xe58b9ee93700a616b50509c8292977fa7a0f8ce1`, sent from `0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2`.

DAI's `mint` function is guarded by a `wards` mapping: only registered ward addresses can mint. The sender is not a ward on Mainnet, so a plain simulation reverts. The override `wards[0xe2e2…e2e2] = 1` makes it a ward for the duration of the simulation.

### Build the mint step

1. Go to **Simulator** and click **New Simulation**.
2. In the **Contract** field, paste `0x6b175474e89094c44da98b954eedeac495271d0f` and select **Dai**.
3. Select **mint** in the **Function** field.
4. Set **usr** to `0xe58b9ee93700a616b50509c8292977fa7a0f8ce1` and **wad** to `2000000000000000000`.
5. Set the step's **From** to `0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2`.

### Add the state override

6. Expand the **State overrides** section below the step fields and click **Add State Override**. The override's contract defaults to the step's target (Dai).
7. Under **Storage variables**, enter the key `wards[0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2]` and the value `1`. The key field suggests the contract's decoded storage variables (`wards[]`, `balanceOf[]`, `totalSupply`, and so on); fill the mapping key inside the brackets.
8. Click the **+** button next to the value to add the pair. The committed pair appears as a row under Storage variables. Tenderly stores it as the computed storage slot hash.

<Frame>
  <img alt="Step editor with Dai mint function, usr and wad arguments filled, and the State overrides section showing the committed wards mapping override" />
</Frame>

<Note>
  The override pair must be committed with the **+** button. An uncommitted key/value entry is treated as invalid and the simulation will not start.
</Note>

To override the contract's native balance instead of (or in addition to) storage, flip the **Use custom balance** switch in the same section.

### Run and inspect

9. Click **Simulate**. The mint executes successfully because the simulation sees the sender as a ward.

<Frame>
  <img alt="Simulation result showing Status Success for mint(), an ERC-20 transfer row crediting 2 DAI, and the decoded execution trace" />
</Frame>

The result tabs confirm what the override changed:

* The **Events** tab shows the `Transfer` event from the zero address to the holder for `2000000000000000000` wei.

<Frame>
  <img alt="Events tab showing the decoded Transfer event with src, dst, and wad fields" />
</Frame>

* The **State** tab lists the applied **State Overrides** (the ward slot set to `1`) and the resulting **State Changes**: the holder's `balanceOf` going from `0` to `2000000000000000000`, the increased `totalSupply`, and the sender's nonce.

<Frame>
  <img alt="State tab showing the wards storage slot override under State Overrides and the balanceOf and totalSupply changes under State Changes" />
</Frame>

## Raw storage keys

Instead of the decoded `mapping[key]` form, you can enter the raw 32-byte storage slot directly. For a Solidity mapping at storage position `p`, the slot for `mapping[k]` is `keccak256(abi.encode(k, p))`. The wards override above resolves to:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03
```

Raw keys are the only option for contracts without verified source, and they match the format used by the [Simulation API's state overrides](/simulations/state-overrides) and the [bundle guide](/simulations/guides/mint-approve-transfer-bundle).

## Persisting overridden state

Simulations are stateless: the override applies to one run. To keep modified state as a persistent environment you can transact against repeatedly, use [Virtual Environments](/virtual-environments/overview).


# Custom RPC Methods
Source: https://docs.tenderly.co/virtual-environments/admin-rpc

Network customization RPC methods (cheatcodes) for Virtual Environments to manipulate state, balances, nonces, and block history.

You can fully control your Virtual Environment by using special RPC methods. These methods are made available through the **Admin RPC**, which you can copy from the Dashboard.

They allow you to manipulate the network state such as account balances, block numbers, and storage to accommodate your development needs.

Calls to these RPC methods are represented by a call to virtual `TenderlyCheatcodes` contract.

<img alt="" />

The list of special RPC methods listed here will only work if they are called through the Admin RPC.

**Network customization**

* [evm\_increaseTime](#evm_increasetime)
* [evm\_setNextBlockTimestamp](#evm_setnextblocktimestamp)
* [tenderly\_setNextBlockTimestamp](#tenderly_setNextBlockTimestamp)
* [evm\_increaseBlocks](#evm_increaseblocks)
* [evm\_mine](#evm-mine)

**Send transaction**

* [eth\_sendTransaction](#eth_sendtransaction)
* [eth\_createAccessList](#eth_createaccesslist)
* [evm\_getLatest](#evm_getlatest)

**Unlimited faucet**

* [tenderly\_setBalance](#tenderly_setbalance)
* [tenderly\_addBalance](#tenderly_addbalance)
* [tenderly\_setErc20Balance](#tenderly_seterc20balance)
* [tenderly\_addErc20Balance](#tenderly_adderc20balance)
* [tenderly\_setMaxErc20Balance](#tenderly_setmaxerc20balance)

**Storage manipulation**

* [tenderly\_setStorageAt](#tenderly_setstorageat)

**State revert**

* [evm\_snapshot](#evm_snapshot)
* [evm\_revert](#evm_revert)

**Network Mirror Mode sync control**

* [tenderly\_startSync](#tenderly_startsync)
* [tenderly\_stopSync](#tenderly_stopsync)
* [tenderly\_syncNext](#tenderly_syncnext)
* [tenderly\_revertSync](#tenderly_revertsync)
* [tenderly\_getSyncStatus](#tenderly_getsyncstatus)

### `evm_increaseTime`

Advances the blockchain time by a specified amount and creates an empty block with the new timestamp.

Subsequent calls to `eth_call` and `eth_sendRawTransaction` will get different `block.timestamp` values based on the `blockNumber` they target:

* For `pending` block: Returns `current_time + time_increase`
  This represents the expected timestamp of the next block to be mined.
* For `latest` block: Returns `time_of_evm_increaseTimestamp_call + time_increase`. This is the timestamp of the empty block created when `evm_increaseTimestamp` was called.

**Parameters**

* `QUANTITY` - hex-encoded `time_increase` of seconds to jump forward by

**Returns**

* `DATA` - 32-byte block hash of the newly generated block

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "evm_increaseTime",
  "params": ["0x15180"],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": "0x51e0a03f19e0c154b16363086aa6bbf22ad4582b0515b0a3a00519015f06246f",
  "id": "1234"
}
```

### `evm_setNextBlockTimestamp`

Offsets current time to the specified timestamp, and creates an empty block with given timestamp.

Subsequent calls to `eth_call` and `eth_sendRawTransaction` will return different `block.timestamp` values based on the `blockNumber` they target:

* For `pending` block: Returns `specified_timestamp + time_since_evmSetNextBlockTimestamp_call`.  This represents the set timestamp plus any time elapsed since the method was called.
* For `latest` block: Returns `specified_timestamp`. This is the timestamp of the empty block created when `evm_setNextBlockTimestamp` was called.

**Parameters**

* `QUANTITY` - hex-encoded `specified_timestamp` that represents epoch timestamp (in seconds)

**Returns**

* `QUANTITY` - integer (epoch timestamp) that is set for the next block

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "evm_setNextBlockTimestamp",
  "params": ["1750074671"],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": 1750074671,
  "id": "1234"
}
```

### `tenderly_setNextBlockTimestamp`

Offsets current time to given timestamp without creating an empty block.

Subsequent calls to `eth_call` and `eth_sendRawTransaction` will return different `block.timestamp` values based on the `blockNumber` they target:

* For `pending` block: Returns `specified_timestamp + time_since_tenderly_setNextBlockTimestamp`.  This represents the set timestamp plus any time elapsed since the method was called.
* For `latest` block: Returns the timestamp of the latest created block.

**Parameters**

* `QUANTITY` - hex-encoded `specified_timestamp` that represents epoch timestamp (in seconds)

**Returns**

* `QUANTITY` - integer (epoch timestamp) that is set for the next block

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "evm_setNextBlockTimestamp",
  "params": ["1750074671"],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": 1750074671,
  "id": "1234"
}
```

### `evm_increaseBlocks`

Skips a number of blocks and generates a new block with the new block number.

**Parameters**

* `QUANTITY` - hex-encoded number of blocks to skip

**Returns**

* `DATA` - 32-byte block hash of the newly generated block

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "evm_increaseBlocks",
  "params": ["0x20"],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": "0x51e0a03f19e0c154b16363086aa6bbf22ad4582b0515b0a3a00519015f06246f",
  "id": "1234"
}
```

### `eth_sendTransaction`

Submits an unsigned transaction.

**Parameters**

1. **Transaction** - The transaction object

* `from`: `DATA`, 20 Bytes - The address the transaction is sent from.
* `to`: `DATA`, 20 Bytes - (optional, omitted when creating new contract) The address the transaction is directed to.
* `gas`: `QUANTITY` - (optional) Integer of the gas provided for the transaction execution. It will return unused gas.
* `gasPrice`: `QUANTITY` - (optional) Integer of the `gasPrice` used for each paid gas.
* `value`: `QUANTITY` - (optional) Integer of the value sent with this transaction.
* `data`: `DATA` - (optional) The compiled code of a contract OR the hash of the invoked method signature and encoded parameters.

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "id": 0,
  "jsonrpc": "2.0",
  "method": "eth_sendTransaction",
  "params": [
    {
      "from": "0xDC6bDc37B2714eE601734cf55A05625C9e512461",
      "to": "0xff39a3e734fe363e631441f6d24c7539240c2628",
      "value": "0x0",
      "data": "0x2e7700f0"
    }
  ]
}
```

**RESULT**: Transaction hash `STRING` 32 byte hex value

### `eth_createAccessList`

Returns the access tuples that would be touched by the transaction.

**Parameters**

* `SendTransactionObject` - transaction object (same as the one provided to eth\_sendTransaction)
* `BlockNumber` - block number parameter

**Returns**

* `AccessList` - an array of access tuples touched by the transaction

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "eth_getAccessList",
  "params": [
    {
      "from": "0x7ed8dff35e6fef1a6c1f95423cd8a64e22687aac",
      "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "gas": "0x76c00",
      "gasPrice": "0x0",
      "value": "0x0",
      "data": "0xa9059cbb0000000000000000000000005eddecc908575e1adcf857d8be380b9b7e5f658300000000000000000000000000000000000000000000000228813d891ab86000"
    },
    "latest"
  ],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": [
    {
      "address": "0x7ed8dff35e6fef1a6c1f95423cd8a64e22687aac"
    },
    {
      "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "storage_keys": [
        "0x5051a693fd89be4fee1466db5a0684c1868dc09405da86e3d13004a803e302ec"
      ]
    },
    {
      "address": "0xc8f595e2084db484f8a80109101d58625223b7c9"
    }
  ],
  "id": 1234
}
```

### `evm_getLatest`

Fetches the latest transaction ID on a network Virtual Environment.

**Parameters**

**Returns**

* `DATA` - UUID of the latest Virtual Environment transaction

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "evm_getLatest",
  "params": [],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": "4a05d7ed-f66c-471a-899d-d6d843b8e790",
  "id": "1234"
}
```

### `tenderly_setBalance`

Modifies the balance of an account or accounts.

**Parameters**

* `ADDRESS/ADDRESSES` - a string or an array of account addresses
* `AMOUNT` - hex-encoded number of an amount in wei

**Returns**

* `DATA` - 32-byte block hash of the newly created transaction

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_setBalance",
  "params": [["0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B", "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"], "0xDE0B6B3A7640000"],
  "id": "1234"
}
```

OR

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_setBalance",
  "params": ["0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B", "0xDE0B6B3A7640000"],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": "0xc5b2c658f5fa236c598a6e7fbf7f21413dc42e2a41dd982eb772b30707cba2eb",
  "id": "1234"
}
```

### `tenderly_addBalance`

Adds the balance to the provided account or accounts.

**Parameters**

* `ADDRESS/ADDRESSES` - a string or an array of account addresses
* `AMOUNT` - hex-encoded number of an amount in wei

**Returns**

* `DATA` - 32-byte block hash of the newly created transaction

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_addBalance",
  "params": [["0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B"], "0xDE0B6B3A7640000"],
  "id": "1234"
}
```

OR

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_addBalance",
  "params": ["0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B", "0xDE0B6B3A7640000"],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": "0xc5b2c658f5fa236c598a6e7fbf7f21413dc42e2a41dd982eb772b30707cba2eb",
  "id": "1234"
}
```

### `tenderly_setErc20Balance`

Sets the token balance for the wallet on the provided erc20 contract.

<Note>
  `tenderly_setErc20Balance` writes the new balance directly to the token contract's storage and **does not emit an ERC-20 `Transfer` event**. If your downstream tooling (indexers, subgraphs, accounting) relies on `Transfer` events to track balances, use [`tenderly_addErc20Balance`](#tenderly_adderc20balance) instead, it emits a synthetic `Transfer` log for each funded account.
</Note>

**Parameters**

* `TOKEN_ADDRESS` - address of the ERC20 contract
* `WALLET` - address of the wallet that will get topped up
* `VALUE` - 32-byte hash representing the **wei** value of the tokens

**Returns**

`DATA` - 32-byte hash of the newly created transaction (storage override is committed via transaction)

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_setErc20Balance",
  "params": [
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "0x40BdB4497614bAe1A67061EE20AAdE3c2067AC9e",
    "0xDE0B6B3A7640000"
  ],
  "id": 3640
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "id": 3640,
  "jsonrpc": "2.0",
  "result": "0x8a84686634729c57532b9ffa4e632e241b2de5c880c771c5c214d5e7ec465b1c"
}
```

### `tenderly_addErc20Balance`

Adds the specified amount of tokens to one or more wallets on the provided ERC-20 contract. Unlike [`tenderly_setErc20Balance`](#tenderly_seterc20balance), this method **emits a synthetic `Transfer` event** for every funded account, so indexers, subgraphs, and any tooling that reconciles balances from logs stay in sync with the resulting state.

The emitted log has the standard ERC-20 `Transfer(address,address,uint256)` topic, uses the transaction sender as the `from` address and the funded wallet as the `to` address, and carries the added `amount` in the data field.

**Parameters**

* `TOKEN_ADDRESS` - address of the ERC-20 contract
* `WALLETS` - array of wallet addresses that will receive the tokens
* `VALUE` - 32-byte hash representing the **wei** amount of tokens to add to each wallet

**Returns**

`DATA` - 32-byte hash of the newly created transaction (storage override is committed via transaction)

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_addErc20Balance",
  "params": [
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    [
      "0x40BdB4497614bAe1A67061EE20AAdE3c2067AC9e",
      "0xBd8DaA414Fda8a8A129F7035e7496759C5aF8570"
    ],
    "0xDE0B6B3A7640000"
  ],
  "id": 3641
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "id": 3641,
  "jsonrpc": "2.0",
  "result": "0x8a84686634729c57532b9ffa4e632e241b2de5c880c771c5c214d5e7ec465b1d"
}
```

### `tenderly_setMaxErc20Balance`

Tops up the wallet address with maximum possible token balance (primarily intended for tokens that don't have a simple balance mapping) on the provided erc20 contract.

<Note>
  Like `tenderly_setErc20Balance`, this method writes directly to storage and **does not emit an ERC-20 `Transfer` event**. Use [`tenderly_addErc20Balance`](#tenderly_adderc20balance) when you need indexers or log-based tooling to pick up the balance change.
</Note>

**Parameters**

* `YIELD_TOKEN_ADDRESS` - address of the ERC20 contract
* `WALLET` - address of the wallet that would get topped up

**Returns**

`DATA` - 32-byte hash of the newly created transaction (storage override is committed via transaction)

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "id": 0,
  "jsonrpc": "2.0",
  "method": "tenderly_setMaxErc20Balance",
  "params": [
    "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
    "0xb5f45E52649123117C175B2016Ed3fCd26f9bE06"
  ]
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "id": 0,
  "jsonrpc": "2.0",
  "result": "0x8fb202d4612be9f6e96b955b4e5bd002cde4d79bec8a6d1b7d35976f124636a4"
}
```

### `tenderly_setStorageAt`

Sets the storage of the provided address at the provided slot.

**Parameters**

* `ADDRESS` - the address where the storage will be overridden
* `SLOT` - 32-byte hash representing the storage slot key
* `VALUE` - 32-byte hash representing the value at the key `slot`

**Returns**

* `DATA` - 32-byte hash of the newly created transaction (storage override is committed via transaction)

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_setStorageAt",
  "params": [
    "0x3Df2f692132f55b97cc9DA04A1fFFEA82F5d710b",
    "0x8111de210bcfef10861a4ab6df0f4838296bd61d5a8f02dca283ed3b72a47bba",
    "0x0000000000000000000000000000000000000000000000000000000000000000"
  ],
  "id": "1"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": "0xc5b2c658f5fa236c598a6e7fbf7f21413dc42e2a41dd982eb772b30707cba2eb",
  "id": "1234"
}
```

### `evm_snapshot`

Returns a snapshot ID that allows you to revert a Virtual Environment to a previous point (same as block `hash` from `evm_getLatest`).

**Parameters**

**Returns**

1. `DATA` - hash of the latest block produced by the Virtual Environment (Snapshot ID)

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "evm_snapshot",
  "params": [],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": "0xfdb5a15fe652e0f47e4312df749f8cc1769d5e70f0bf3f26a4e231bb6a550f8d",
  "id": "1234"
}
```

### `evm_revert`

Reverts the state of the Virtual Environment to a previous snapshot.

A single `evm_revert` can roll back at most 2000 blocks. If the snapshot is further back than that, the call fails with a `revert operation is limited to maximum 2000 blocks` error. To return to a point more than 2000 blocks in the past, [clone the Virtual Environment at the target historical block](/virtual-environments/develop/revert-state#clone-at-a-historical-block) instead.

**Parameters**

* `DATA` - ID of the snapshot

**Returns**

* `BOOLEAN` - operation success flag

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "evm_revert",
  "params": ["0xfdb5a15fe652e0f47e4312df749f8cc1769d5e70f0bf3f26a4e231bb6a550f8d"],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": true,
  "id": "1234"
}
```

## Network Mirror Mode sync control

The following methods control [Network Mirror Mode](/virtual-environments/network-mirror-mode), they start, stop, step, rewind, and inspect the continuous sync between a Virtual Environment and its parent network.

<Note>
  While Network Mirror Mode sync is **active**, other Admin RPC cheatcodes (for example `tenderly_setBalance`, `tenderly_setStorageAt`, `tenderly_sendBlock`) are disabled. Pause sync with [`tenderly_stopSync`](#tenderly_stopsync) first if you need them to take effect immediately.
</Note>

### `tenderly_startSync`

Starts continuous sync between the Virtual Environment and its parent network. New parent-network blocks are absorbed as they're produced, and any transactions in the Virtual Environment's mempool are prepended (in FIFO order) to the next synced block.

**Parameters**

None.

**Returns**

* `BOOLEAN` - `true` if sync was started

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_startSync",
  "params": [],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": true,
  "id": "1234"
}
```

### `tenderly_stopSync`

Stops any in-progress sync. The Virtual Environment stays at its current block; you can resume with `tenderly_startSync` or advance manually with `tenderly_syncNext`. Use this before calling other Admin RPC cheatcodes when Mirror Mode is active.

**Parameters**

None.

**Returns**

* `BOOLEAN` - `true` if sync was stopped (or already stopped)

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_stopSync",
  "params": [],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": true,
  "id": "1234"
}
```

### `tenderly_syncNext`

Syncs the next single parent-network block onto the Virtual Environment. Any pending Virtual Environment transactions are prepended to that block in FIFO order. Useful for stepping through sync one block at a time.

**Parameters**

None.

**Returns**

* `DATA` - 32-byte block hash of the newly synced block

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_syncNext",
  "params": [],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": "0x51e0a03f19e0c154b16363086aa6bbf22ad4582b0515b0a3a00519015f06246f",
  "id": "1234"
}
```

### `tenderly_revertSync`

Rewinds the Virtual Environment by N synced blocks, undoing their effect on Virtual Environment state. The default is 10 blocks. Use this to step the Mirror-Mode Virtual Environment back to an earlier point in the parent network's history.

**Parameters**

* `QUANTITY` *(optional)* - hex-encoded number of blocks to rewind. Defaults to `0xa` (10).

**Returns**

* `DATA` - 32-byte block hash of the block the Virtual Environment is now positioned at

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_revertSync",
  "params": ["0xa"],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": "0xfdb5a15fe652e0f47e4312df749f8cc1769d5e70f0bf3f26a4e231bb6a550f8d",
  "id": "1234"
}
```

### `tenderly_getSyncStatus`

Returns the current sync state of the Virtual Environment, including whether sync is active, how far behind the parent network it is, and the latest synced block.

**Parameters**

None.

**Returns**

* `OBJECT` - sync status with the following fields:
  * `active` - `BOOLEAN`, `true` if sync is currently running
  * `lag` - `QUANTITY`, number of blocks the Virtual Environment is behind the parent network
  * `latestSyncedBlock` - `QUANTITY`, block number of the latest block synced onto the Virtual Environment
  * `parentLatestBlock` - `QUANTITY`, block number of the latest block on the parent network

**Example request**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "method": "tenderly_getSyncStatus",
  "params": [],
  "id": "1234"
}
```

**Example response**

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "jsonrpc": "2.0",
  "result": {
    "active": true,
    "lag": 0,
    "latestSyncedBlock": 22845130,
    "parentLatestBlock": 22845130
  },
  "id": "1234"
}
```


# Foundry and Github Actions
Source: https://docs.tenderly.co/virtual-environments/ci-cd/github-actions-foundry

Set up a CI/CD pipeline on Virtual Environments with the Tenderly GitHub Action to test and stage Solidity smart contracts using Foundry.

Learn how to configure a GitHub Action to set up a continuous integration and continuous deployment pipeline (CI/CD) with Foundry on Tenderly [Virtual Environments](/virtual-environments/overview).

Use the [Tenderly Virtual Environment Setup](https://github.com/marketplace/actions/tenderly-virtual-testnet-setup) action to enable automated builds to test and stage your contracts. This approach enables:

* **CI/CD Integration**: Run tests against forked networks and set up staging environments
* **Multi-Network Testing**: Provision multiple networks in a single step
* **Automated Deployments**: Deploy and verify contracts with complete deployment logs
* **Artifact Collection**: Track deployments across networks with structured logs

In this guide, you need to complete two stages:

1. Local setup: Set up Foundry to create and test out the workflow file
2. GitHub setup: Set up a GitHub Action, configure GitHub secrets and variables, and test the build

For reference, use this example project:

<Card title="Foundry CI/CD setup" href="" />

<Frame>
  <img alt="Continuous integration (CI) and continous deployment (CD) with Virtual Environments" />
</Frame>

## Stage 1: Local Setup

First, create a workflow file with the necessary settings.

<Steps>
  ### Create the Workflow File

  In your foundry project, create a new `workflows` directory and `ci-cd.yaml`:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  mkdir -p .github/workflows
  touch .github/workflows/ci-cd.yaml
  ```

  Next, paste the following configuration to `ci-cd.yaml` that sets up two jobs:

  * **`test`** job to run Foundry tests
  * **`deploy`** job to deploy contracts to a staging Virtual Environment

  This sample workflow file:

  * Uses `tenderly/vnet-github-action` to provision Virtual Environments based on a given `network_id` (Mainnet and Base), with custom `chain_id`
  * Uses `update_foundry_config_and_build` to modify `foundry.toml` with the correct chain ID (especially important if you're using a custom `chain_id`), and passes verification information.
  * Funds the `DEPLOYER_WALLET_ADDRESS` EOA with 100 ETH, using `set_wallet_balance`
  * Deploys the contracts on the Virtual Environment
  * Collects deployment information to `$BUILD_OUTPUT_FILE_1` and `$BUILD_OUTPUT_FILE_8453`, respectively, using foundry's `--json` option
  * Pushes captured deployment information to the repository

  <Note>
    The `mode` argument for `Tenderly/vnet-github-action` takes values `CI` and `CD`.

    * The `CD` mode keeps the Virtual Environment active and you can work with deployed contracts.
    * The `CI` mode pauses the Virtual Environment after the step completes. You'll be able to inspect transactions but won't be able to send further RPC requests.
  </Note>

  ```yaml title='ci-cd.yaml' showLineNumbers lines={24-25, 32-34, 38, 43, 49, 69} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  name: Foundry CI/CD

  on:
    push:
    pull_request:

  env:
    TENDERLY_ACCESS_KEY: ${{ secrets.TENDERLY_ACCESS_KEY }}
    DEPLOYER_WALLET_ADDRESS: ${{ vars.DEPLOYER_WALLET_ADDRESS }}
    DEBUG: tenderly/vnet-github-action@v1.0.14
  jobs:
    deploy:
      runs-on: ubuntu-latest
      defaults:
        run:
          working-directory: ./examples/foundry
      permissions:
        contents: write
      steps:
        - uses: actions/checkout@v4
          with:
            submodules: recursive

        - name: Setup Virtual Environment
          uses: tenderly/vnet-github-action@v1.0.14
          with:
            mode: CD
            access_key: ${{ secrets.TENDERLY_ACCESS_KEY }}
            project_name: ${{ vars.TENDERLY_PROJECT_NAME }}
            account_name: ${{ vars.TENDERLY_ACCOUNT_NAME }}
            testnet_name: "Staging"
            network_id: |
              1
              8453
            chain_id_prefix: 7357
            public_explorer: true
            verification_visibility: 'src'
            push_on_complete: true

        - name: Install Foundry
          uses: foundry-rs/foundry-toolchain@v1

        - name: Fund Deployer Account on Mainnet
          run: |
            source ../../fixtures/load-fixtures.sh
            update_foundry_config_and_build $TENDERLY_ACCESS_KEY $TENDERLY_FOUNDRY_VERIFICATION_URL_1  $TENDERLY_CHAIN_ID_1
            set_wallet_balance $TENDERLY_ADMIN_RPC_URL_1 ${{ vars.DEPLOYER_WALLET_ADDRESS }} $HUNDRED_ETH

        - name: Deploy Contracts Mainnet
          run: |
            forge build --sizes
            forge script script/Counter.s.sol \
              --private-key ${{ secrets.DEPLOYER_PRIVATE_KEY }} \
              --rpc-url ${{ env.TENDERLY_PUBLIC_RPC_URL_1 }} \
              --verifier-url ${{ env.TENDERLY_FOUNDRY_VERIFICATION_URL_1 }} \
              --etherscan-api-key $TENDERLY_ACCESS_KEY \
              --slow \
              --broadcast \
              --verify \
              --json > $BUILD_OUTPUT_FILE_1

        - name: Fund Deployer Account on Base
          run: |
            source ../../fixtures/load-fixtures.sh
            update_foundry_config_and_build $TENDERLY_ACCESS_KEY $TENDERLY_FOUNDRY_VERIFICATION_URL_8453  $TENDERLY_CHAIN_ID_8453
            set_wallet_balance $TENDERLY_ADMIN_RPC_URL_8453 ${{ vars.DEPLOYER_WALLET_ADDRESS }} $HUNDRED_ETH

        - name: Deploy Contracts Base
          working-directory: ./examples/foundry
          run: |
            forge script script/Counter.s.sol \
              --private-key ${{ secrets.DEPLOYER_PRIVATE_KEY }} \
              --rpc-url ${{ env.TENDERLY_PUBLIC_RPC_URL_8453 }} \
              --verifier-url ${{ env.TENDERLY_FOUNDRY_VERIFICATION_URL_8453 }} \
              --etherscan-api-key $TENDERLY_ACCESS_KEY \
              --slow \
              --broadcast \
              --verify \
              --json > $BUILD_OUTPUT_FILE_8453
  ```

  ### Configure Foundry

  Create or update your `foundry.toml` configuration file. To use automatic contract verification, you must have the `unknown_chain` entry with `key`, `chain`, and `url`.

  <Note>
    When using Virtual Environments from your local machine, replace the \`chain = 0\` with the chain ID of the Virtual Environment you connected to.
  </Note>

  ```toml showLineNumbers title="foundry.toml" lines={8-11} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  [profile.default]
  src = "src"
  out = "out"
  libs = ["lib"]
  cbor_metadata = true
  # See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options

  [etherscan]

  ## placeholders must be replaced with key ("string"), chain_id (number, non-quoted), and tenderly_foundry_verification_url ("string")
  unknown_chain = { key = "$TENDERLY_ACCESS_KEY", chain = 0, url = "$TENDERLY_FOUNDRY_VERIFICATION_URL" }
  ```

  ### Prepare Environment Variables

  For local testing, set up an `.env` file with the following variables:

  ```dotenv showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # Access parameters
  TENDERLY_ACCESS_KEY=...
  TENDERLY_PROJECT_NAME=...
  TENDERLY_ACCOUNT_NAME=...

  # Deployment parameters
  DEPLOYER_PRIVATE_KEY=...
  DEPLOYER_WALLET_ADDRESS=...
  ```

  Required variables:

  * `TENDERLY_ACCESS_KEY`: Your [Tenderly access key](/platform/account/projects/api-tokens)
  * `TENDERLY_ACCOUNT_NAME` and `TENDERLY_PROJECT_NAME`: Your [account and project names](/platform/account/projects/api-tokens)
  * `DEPLOYER_PRIVATE_KEY`: Private key for the deployment wallet
  * `DEPLOYER_WALLET_ADDRESS`: Address corresponding to the private key

  ### Add fixtures script

  Add the following `fixtures.sh` to your repository to be able to fund accounts and adapt `foundry.toml` easily.

  This file exposes:

  * `set_wallet_balance` function to top up the balance (RPC\_URL WALLET\_ADDRESS BALANCE\_HEX)
  * `update_foundry_config_and_build` function to replace the placeholders in `foundry.toml`
  * `HUNDRED_ETH` the wei value corresponding to 100 ETH

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  #!/bin/bash

  set_wallet_balance() {
      if [ "$#" -ne 3 ]; then
          echo "Usage: set_wallet_balance RPC_URL WALLET_ADDRESS BALANCE_HEX"
          return 1
      fi

      local rpc_url="$1"
      local wallet_address="$2"
      local balance_hex="$3"

      curl --location "$rpc_url" \
          --header 'Content-Type: application/json' \
          --data "{
              \"jsonrpc\": \"2.0\",
              \"method\": \"tenderly_setBalance\",
              \"params\": [\"$wallet_address\", \"$balance_hex\"],
              \"id\": \"1\"
          }"
  }

  update_foundry_config_and_build() {
      if [ "$#" -ne 3 ]; then
          echo "Usage: update_foundry_config_and_build ACCESS_KEY VERIFICATION_URL CHAIN_ID"
          return 1
      fi

      local access_key="$1"
      local verification_url="$2"
      local chain_id="$3"

      # Create temporary file and update foundry.toml
      sed -e "s|\${TENDERLY_ACCESS_KEY}|$access_key|g" \
          -e "s|\${TENDERLY_FOUNDRY_VERIFICATION_URL}|$verification_url|g" \
          -e "s/\(unknown_chain[[:space:]]*=[[:space:]]*{[^}]*chain[[:space:]]*=[[:space:]]*\)[0-9][0-9]*/\1$chain_id/g" \
          foundry.toml > foundry.toml.tmp && mv foundry.toml.tmp foundry.toml
  }

  # Export constant
  HUNDRED_ETH="0xDE0B6B3A7640000"
  export HUNDRED_ETH
  ```

  The github action exposes RPC links and verification URLs via different environment variables:

  | Variable                                         | Description                                                                  |
  | ------------------------------------------------ | ---------------------------------------------------------------------------- |
  | `TENDERLY_TESTNET_ID_{network_id}`               | Virtual Environment UUID, uniquely identifying it within Tenderly            |
  | `TENDERLY_ADMIN_RPC_URL_{network_id}`            | [Admin RPC](/virtual-environments/admin-rpc) endpoint with cheatcode methods |
  | `TENDERLY_PUBLIC_RPC_URL_{network_id}`           | Public RPC endpoint                                                          |
  | `TENDERLY_CHAIN_ID_{network_id}`                 | Chain ID                                                                     |
  | `TENDERLY_TESTNET_SLUG_{network_id}`             | Unique Virtual Environment slug                                              |
  | `TENDERLY_FOUNDRY_VERIFICATION_URL_{network_id}` | [Foundry verification](/contract-verification/foundry#verifier-url) URL      |
  | `BUILD_OUTPUT_FILE_{network_id}`                 | Build output file path                                                       |

  ### Test the Github Action Locally

  You can test your GitHub Action locally using [Act](https://github.com/nektos/act) without pushing to GitHub.

  Use the **`.env`** file to populate GitHub secrets and environment variables as follows:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  act --secret-file .env --var-file .env
  ```
</Steps>

## Stage 2: Github Setup

After confirming your local setup works, configure your GitHub repository using the following steps.

<Steps>
  ### Configure Secrets and Variables

  Set up the following GitHub secrets and variables:

  **Secrets:**

  * `TENDERLY_ACCESS_KEY`: the Tenderly Access Key
  * `DEPLOYER_PRIVATE_KEY`: the private key for the deployer EOA

  **Variables:**

  * `TENDERLY_PROJECT_NAME`: the Tenderly project name
  * `TENDERLY_ACCOUNT_NAME`: the project's owner's name
  * `DEPLOYER_WALLET_ADDRESS`: the deployer EOA

  You can achieve this via the [GitHub UI](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables#creating-configuration-variables-for-a-repository) or using the `gh` command line:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # Load environment variables
  source .env

  # Set variables
  gh variable set TENDERLY_PROJECT_NAME --body ${TENDERLY_PROJECT_NAME}
  gh variable set TENDERLY_ACCOUNT_NAME --body ${TENDERLY_ACCOUNT_NAME}
  gh variable set DEPLOYER_WALLET_ADDRESS --body ${DEPLOYER_WALLET_ADDRESS}

  # Set secrets
  gh secret set TENDERLY_ACCESS_KEY --body ${TENDERLY_ACCESS_KEY}
  gh secret set DEPLOYER_PRIVATE_KEY --body ${DEPLOYER_PRIVATE_KEY}
  ```

  ### Push the Updates

  Finally, commit and push your changes:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  git add .
  git commit -m "Add CI/CD workflow for Foundry"
  git push
  ```

  ### Check your action

  Go go your Github repository and check Actions tab. Congrats, you ran your CI/CD workflow with Virtual Environments and Foundry. After

  ### Get the RPC link

  To get the RPC link, go to **Tenderly dashboard > Virtual Environments** and find your CD Virtual Environment.
</Steps>

## Next steps

* Explore the [Foundry example](https://github.com/Tenderly/vnet-github-action/tree/main/examples/foundry) on Github.
* Explore the [Hardhat example](https://github.com/Tenderly/vnet-github-action/tree/main/examples/hardhat-ignition) on Github.
* Use the [balance fixtures](https://github.com/Tenderly/vnet-github-action/blob/main/fixtures/load-fixtures.sh).


# Hardhat and Github Actions
Source: https://docs.tenderly.co/virtual-environments/ci-cd/github-actions-hardhat

Use Tenderly Github action to set up Continuous Integration and Continuous Deployment (CI/CD) to test and stage Solidity smart contracts with Hardhat

Learn how to configure a GitHub Action to set up a Continuous Integration and Continuous Deployment pipeline (CI/CD) with Hardhat on Tenderly Virtual Environments.

Use the [Tenderly Virtual Environment Setup](https://github.com/marketplace/actions/tenderly-virtual-testnet-setup) to enable automated builds that test and deploy your contracts across multiple networks. After successful testing, you can stage them for the rest of your team by deploying them to provisioned Virtual Environments.

In this guide, you need to complete two stages:

1. Local setup: Set up Hardhat and create and test the workflow file.
2. Github setup: Set up a GitHub Action, configure GitHub secrets and variables, and test the build.

For reference, use this example project:

<Card title="CI/CD setup with hardhat-ignition" href="" />

<Note>
  This guide demonstrates a CI setup that relies on Hardhat-ignition. For `hardhat-verify` setup, the process and configuration are similar.
</Note>

<Frame>
  <img alt="Continuous integration (CI) and continous deployment (CD) with Virtual Environments" />
</Frame>

## Stage 1: Local setup

First, we'll install necessary dependencies and create a workflow file.

<Steps>
  ### Install dependencies

  Make sure you have the following packages installed:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  npm install --save-dev @tenderly/hardhat-tenderly @nomicfoundation/hardhat-ignition
  ```

  ### Create the workflow file

  To set up the GitHub Action, create a new workflow:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  mkdir -p .github/workflows
  touch ci-cd.yaml
  ```

  Next, paste the following yaml file that configures two jobs:

  * **`test`** job to run hardhat tests using a single network for testing
  * **`deploy`** job to deploy contracts to multiple networks (Mainnet and Base) after successful testing

  <Note>
    The `mode` argument takes values `CI` and `CD`.

    * The `CD` mode keeps the Virtual Environment active and you can work with deployed contracts.
    * The `CI` mode pauses the Virtual Environment after the step completes. You'll be able to inspect transactions but won't be able to send further RPC requests.
  </Note>

  ```yaml showLineNumbers title="ci-cd.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  name: Hardhat CI/CD Multichain

  on: [push, pull_request]
  env:
    ## Needed available as env variables for hardhat.config.js
    TENDERLY_PROJECT_NAME: ${{ vars.TENDERLY_PROJECT_NAME }}
    TENDERLY_ACCOUNT_NAME: ${{ vars.TENDERLY_ACCOUNT_NAME }}
  jobs:
    test:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4

        - name: Setup Node.js
          uses: actions/setup-node@v4
          with:
            node-version: '20'
            cache: 'npm'

        - name: Setup Virtual Environment
          uses: tenderly/vnet-github-action@v1.0.14
          with:
            mode: CI    # pauses the Virtual Environment after deployment
            access_key: ${{ secrets.TENDERLY_ACCESS_KEY }}
            project_name: ${{ vars.TENDERLY_PROJECT_NAME }}
            account_name: ${{ vars.TENDERLY_ACCOUNT_NAME }}
            testnet_name: "Testing"
            network_id: 1
            chain_id_prefix: 7357
            public_explorer: true
            verification_visibility: 'src'
            push_on_complete: true

        - name: Install dependencies
          run: npm install
          working-directory: examples/hardhat-ignition

        - name: Run Tests
          run: npm run test:1
          working-directory: examples/hardhat-ignition

    deploy:
      needs: test
      runs-on: ubuntu-latest
      permissions:
        contents: write
      steps:
        - uses: actions/checkout@v4

        - name: Setup Node.js
          uses: actions/setup-node@v4
          with:
            node-version: '20'
            cache: 'npm'

        - name: Setup Virtual Environment
          uses: tenderly/vnet-github-action@v1.0.14
          with:
            mode: CD
            access_key: ${{ secrets.TENDERLY_ACCESS_KEY }}
            project_name: ${{ vars.TENDERLY_PROJECT_NAME }}
            account_name: ${{ vars.TENDERLY_ACCOUNT_NAME }}
            testnet_name: "Staging"
            network_id: |
              1
              8453
            chain_id_prefix: ""
            public_explorer: true
            verification_visibility: 'src'
            push_on_complete: true

        - name: Install dependencies
          run: npm install
          working-directory: examples/hardhat-ignition

        - name: Deploy Contracts Mainnet
          run: npm run deploy:1 -- --deployment-id deploy-1-${BUILD_SLUG}
          working-directory: examples/hardhat-ignition

        - name: Deploy Contracts Base
          run: npm run deploy:8453 -- --deployment-id deploy-8453-${BUILD_SLUG}
          working-directory: examples/hardhat-ignition
  ```

  ### Prepare environment variables

  For local testing, set up an `.env` file using this template:

  ```dotenv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  ## Access parameters
  TENDERLY_ACCESS_KEY=...
  TENDERLY_PROJECT_NAME=...
  TENDERLY_ACCOUNT_NAME=...

  ## Network-specific parameters (populated by the action in CI/CD)
  TENDERLY_ADMIN_RPC_URL_1=...    # Mainnet RPC
  TENDERLY_ADMIN_RPC_URL_8453=... # Base RPC
  TENDERLY_CHAIN_ID_1=...         # Mainnet chain ID
  TENDERLY_CHAIN_ID_8453=...      # Base chain ID
  ```

  Required variables:

  * `TENDERLY_ACCESS_KEY`: Learn how to [get your access key](/platform/account/projects/api-tokens)
  * `TENDERLY_ACCOUNT_NAME` and `TENDERLY_PROJECT_NAME`: Follow steps to [get your account and project name](/platform/account/projects/api-tokens)

  ### Configure Hardhat

  Add the Virtual Environment configuration to `hardhat.config.ts`:

  ```typescript title='hardhat.config.ts' showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

  dotenv.config();

  const config: HardhatUserConfig = {
    solidity: "0.8.27",
    networks: {
      mainnet: {
        url: process.env.TENDERLY_ADMIN_RPC_URL_1,
        chainId: parseInt(process.env.TENDERLY_CHAIN_ID_1 || "1")
      },
      base: {
        url: process.env.TENDERLY_ADMIN_RPC_URL_8453,
        chainId: parseInt(process.env.TENDERLY_CHAIN_ID_8453 || "8453")
      }
    },
    etherscan: {
      apiKey: {
        mainnet: process.env.TENDERLY_ACCESS_KEY!,
        base: process.env.TENDERLY_ACCESS_KEY!
      },
      customChains: [
        {
          network: "mainnet",
          chainId: parseInt(process.env.TENDERLY_CHAIN_ID_1!),
          urls: {
            apiURL: `${process.env.TENDERLY_ADMIN_RPC_URL_1}/verify`,
            browserURL: process.env.TENDERLY_ADMIN_RPC_URL_1!
          }
        },
        {
          network: "base",
          chainId: parseInt(process.env.TENDERLY_CHAIN_ID_8453!),
          urls: {
            apiURL: `${process.env.TENDERLY_ADMIN_RPC_URL_8453}/verify`,
            browserURL: process.env.TENDERLY_ADMIN_RPC_URL_8453!
          }
        }
      ]
    },
    tenderly: {
      project: process.env.TENDERLY_PROJECT_NAME!,
      username: process.env.TENDERLY_ACCOUNT_NAME!,
      accessKey: process.env.TENDERLY_ACCESS_KEY!
    },
    sourcify: {
      enabled: false
    }
  };

  export default config;
  ```

  ### Add test and deploy scripts

  Add the following scripts to your `package.json` for multi-network testing and deployment:

  ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  {
    "scripts": {
      "deploy:1": "npx hardhat ignition deploy ./ignition/modules/Counter.js --network mainnet",
      "deploy:8453": "npx hardhat ignition deploy ./ignition/modules/Counter.js --network base",
      "test:1": "npx hardhat test --network mainnet"
    }
  }
  ```

  The deploy commands use the BUILD\_SLUG environment variable (provided by the action) to create unique deployment identifiers.

  ### Test the build locally

  To test the build locally, run the following commands:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # Test on mainnet fork
  npx hardhat test:1

  # Deploy to mainnet fork
  npx hardhat deploy:1

  # Deploy to Base fork
  npx hardhat deploy:8453
  ```

  ### Test the Github Action locally

  To test your action locally, you can use [Act](https://github.com/nektos/act):

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  act --secret-file .env --var-file .env
  ```
</Steps>

## Stage 2: Github Setup

After successful local setup, proceed by configuring Github with environment variables and necessary secrets.

<Steps>
  ### Configure secrets and environment variables in GitHub

  You must configure the following Github variables and secret:

  **Variables:**

  * `TENDERLY_PROJECT_NAME`
  * `TENDERLY_ACCOUNT_NAME`

  **Secrets:**

  * `TENDERLY_ACCESS_KEY`

  You can configure these via the [GitHub UI](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables#creating-configuration-variables-for-a-repository) or using the `gh` command line:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  source .env

  gh variable set TENDERLY_PROJECT_NAME --body ${TENDERLY_PROJECT_NAME}
  gh variable set TENDERLY_ACCOUNT_NAME --body ${TENDERLY_ACCOUNT_NAME}
  gh secret set TENDERLY_ACCESS_KEY --body ${TENDERLY_ACCESS_KEY}
  ```

  ### Push the updates

  To trigger the GitHub Action, push your changes:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  git add .
  git commit -m "Add CI/CD workflow for multichain deployment"
  git push
  ```

  ### Check your action

  Go to your Github repository and check the Actions tab. You should see:

  1. Test job running against the mainnet fork
  2. Deploy job creating two Virtual Environments (mainnet and Base)
  3. Deployment artifacts being pushed to the repository

  ### Get the RPC links

  To get the RPC links for your deployed contracts:

  1. Go to **Tenderly dashboard > Virtual Environments**
  2. Find your CD Virtual Environments (one for mainnet fork, one for Base fork)
  3. Click on each to get their respective RPC URLs
</Steps>

## Environment Variables Reference

The GitHub Action exposes the following network-specific variables:

| Variable                               | Description                               |
| -------------------------------------- | ----------------------------------------- |
| `TENDERLY_TESTNET_ID_{network_id}`     | Virtual Environment UUID                  |
| `TENDERLY_ADMIN_RPC_URL_{network_id}`  | Admin RPC endpoint with cheatcode methods |
| `TENDERLY_PUBLIC_RPC_URL_{network_id}` | Public RPC endpoint                       |
| `TENDERLY_CHAIN_ID_{network_id}`       | Chain ID                                  |
| `TENDERLY_TESTNET_SLUG_{network_id}`   | Unique Virtual Environment slug           |
| `BUILD_SLUG`                           | Unique identifier for the current build   |

## Next steps

Explore other examples:

* [Hardhat with ethers-v6](https://github.com/Tenderly/vnet-github-action/tree/main/examples/hardhat)
* [Foundry setup](https://github.com/Tenderly/vnet-github-action/tree/main/examples/foundry)
* [Advanced deployment patterns](https://github.com/Tenderly/vnet-github-action/tree/main/examples/advanced)


# Staging Contracts
Source: https://docs.tenderly.co/virtual-environments/ci-cd/stage-contracts

Stage contracts in CI/CD by deploying to a Virtual Environment with Foundry, then share the RPC URL and contract addresses with your team.

Deploy the latest code and to Virtual Environments make it available for your team by sharing the RPC link and contract addresses.

<Frame>
  <img alt="Continuous integration (CI) and continous deployment (CD) with Virtual Environments" />
</Frame>

<Card title="Code Sample: Staging Contracts to Virtual Environment" href="" />

<Card title="REST API: Create and manage Virtual Environments" href="" />

<Steps>
  ### Create a Virtual Environment

  Create a new Virtual Environment to stage your contracts, either by:

  * Using the [Virtual Environments dashboard](/virtual-environments/quickstart#configure-your-virtual-environment)
  * Using the [REST API](/virtual-environments/develop/create-virtual-environment-via-api)

  ### Set up environment variables

  To create a Virtual Environment and then deploy and verify contracts, set up the following environment variables:

  * **`TENDERLY_ACCOUNT_ID`** with your [account ID](/platform/account/projects/slug)
  * **`TENDERLY_PROJECT`** with your [project (slug)](/platform/account/projects/slug)
  * **`TENDERLY_ACCESS_KEY`** with
    the [access key you've generated](/platform/account/projects/api-tokens)
  * **`ORIGINAL_NETWORK_ID`** with the [ID of the network](/platform/supported-networks) you
    want to base the Virtual Environment on
  * **`FOUNDRY_REPO`** with the path to Foundry repo
  * **`DEPLOYER_ADDRESS`** with the account you're deploying from
  * Add other environment variables needed for the deployment scripts

  ```bash showLineNumbers title='.env' theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  export TENDERLY_ACCOUNT_ID=<USERNAME>
  export TENDERLY_PROJECT=<PROJECT>
  export TENDERLY_ACCESS_KEY=<ACCESS_KEY>

  ## TestNet Configuration
  export TENDERLY_TESTNET_NAME=staging
  export PURPOSE=development
  export ORIGINAL_NETWORK_ID=1
  export BLOCK_NUMBER=latest

  ## Custom Chain ID (Prefixed with 7357 - test)
  export CHAIN_ID=7357$ORIGINAL_NETWORK_ID

  ## Public explorer verification visibility
  ## abi | full | none
  export VERIFICATION_VISIBILITY=abi

  # Foundry Repo (Absolute path only!)
  export FOUNDRY_REPO=<ABSOLUTE PATH TO FOUNDRY PROJECT>

  ## Deployer address
  export DEPLOYER_ADDRESS=...

  ## Custom stuff needed for deployment scripts
  ## Add your custom stuff here
  export ADMIN_ADDRESS=...
  ```

  ### Write your deployment commands

  Edit `deploy-command.sh` and add commands to deploy your contracts. Note you'll have to add verification to your Foundry or Hardhat project; see [Deploy and verify contracts](/virtual-environments/develop/deploy-contracts).

  For example:

  ```bash showLineNumbers title='deploy-command.sh' theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  #!/bin/bash

  cd $FOUNDRY_REPO

  ## TODO: Your deployment command here:
  MAX_SEGMENT_COUNT=3

  FOUNDRY_PROFILE=optimized \
  forge script script/DeployCore.s.sol \
    --broadcast \
    --rpc-url $TENDERLY_VIRTUAL_TESTNET_RPC \
    --sig "run(address)" \
    --verify \
    --verifier-url $VERIFICATION_URL \
    $ADMIN_ADDRESS
  ```

  ### Stage contracts

  Run the following commands that will:

  * create a new Virtual Environment
  * fund the **`$DEPLOYER_ADDRESS`** with test ETH using the Infinite faucet
  * configure Foundry's **`foundry.toml`** for verification on your custom chain
  * deploy your contracts
  * and finally clean up `foundry.toml`

  ```bash showLineNumbers title='stage.sh' theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # create a testnet - or paste the Unlocked TestNet RPC URL
  source src/contracts-staging/.env
  cd src/contracts-staging

  ## Create a fresh testnet
  export VIRTUAL_NETWORK_RPC_URL=$(./create-testnet.sh)
  echo "Created a Virtual Environment at ${VIRTUAL_NETWORK_RPC_URL}"

  ### run the deployment
  ./deploy-to-testnet.sh
  ```

  The RPC Link is shown in the output, and your contracts are deployed and verified on the Virtual Environment.

  ### Share the addresses

  Collect the ABIs and addresses of deployed contracts and distribute them to your team, together with the Virtual Environment RPC.
</Steps>


# Connect Dapp UI to Virtual Environment
Source: https://docs.tenderly.co/virtual-environments/ci-cd/stage-dapps

Connect a wallet to a staged dapp on a Virtual Environment with RainbowKit, and send transactions for manual and end-to-end testing.

Virtual Environments work seamlessly with some of the most popular UI libraries for dapps. Follow the guides below to learn how to integrate Virtual Environments into your dapp's UI. If you use a different UI library and need assistance, contact us to include a guide for that library in our resources.

<Steps>
  ### Stage contracts

  Stage your smart contracts by following this guide:

  <Card title="Staging smart contracts" href="" />

  ### Fork the staging Virtual Environment

  Optionally, you may choose to fork the staging Virtual Environment and work on an independent copy.

  <Card title="Fork Virtual Environment" href="" />

  ### Collect deployment data

  Collect all deployment data:

  * Fork RPC
  * Contracts' addresses
  * Contracts' ABI

  ### Integrate

  Depending on the framework you're using, follow the appropriate guide to connect your dapp's UI to the Virtual Environment.

  <CardGroup>
    <Card title="Wagmi Integration Guide" href="/virtual-environments/dapp-ui/wagmi" />

    <Card title="Dynamic Integration Guide" href="/virtual-environments/dapp-ui/dynamic" />

    <Card title="ConnectKit Integration Guide" href="/virtual-environments/dapp-ui/connectkit" />

    <Card title="RainbowKit Integration Guide" href="/virtual-environments/dapp-ui/rainbowkit" />

    <Card title="Web3 Modal Integration Guide" href="/virtual-environments/dapp-ui/reown" />
  </CardGroup>
</Steps>


# ConnectKit
Source: https://docs.tenderly.co/virtual-environments/dapp-ui/connectkit

Configure ConnectKit to connect your dapp's wallet UI to a Tenderly Virtual Environment for building, staging, and demoing dapps.

In this guide you'll learn how to connect a Next.js app to Virtual Environments using ConnectKit.

[ConnectKit](https://family.co/docs/connectkit) is a React.js component library for connecting a wallet to your dapp, and you can use Node RPC for blockchain connection.

You can connect ConnectKit to [Virtual Environments](/virtual-environments/overview) to interact with staged smart contracts while building your dapp UI.

<Card title="Code samples: Using Viem with Virtual Environments" href="" />

<Steps>
  ### Create a Virtual Environment

  In Tenderly Dashboard, create a new Virtual Environment:

  * Select Mainnet as the base network
  * Name it `ConnectKit Virtual Environment`
  * Choose a unique chain ID **`73571`**
  * Turn on the **Public Explorer**
  * Copy the **Virtual Environment RPC**

  ### Create a Chain Config

  Create a file `src/tenderly.config.ts` and replace the following:

  1. Paste the chain ID to the `id` property
  2. Change the name and currency
  3. Paste the **Virtual Environment RPC** to **`rpcUrls.default.http`**
  4. Paste the **Block Explorer URL** to **`blockExplorers.default.url`**

  ```typescript showLineNumbers title="src/tenderly.config.ts" lines={4-5,8, 12-13} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

  export const vMainnet = defineChain({
    id: 73571,
    name: 'Virtual Ethereum Mainnet',
    nativeCurrency: { name: 'vEther', symbol: 'vETH', decimals: 18 },
    rpcUrls: {
      default: { http: [process.env.TENDERLY_VIRTUAL_MAINNET_RPC!] }
    },
    blockExplorers: {
      default: {
        name: 'Tenderly Explorer',
        url: 'https://dashboard.tenderly.co/explorer/vnet/47cdac98-cda3-431a-8fce-9f31037a3d0c'
      }
    },
    contracts: {
      ensRegistry: {
        address: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e'
      },
      ensUniversalResolver: {
        address: '0xE4Acdd618deED4e6d2f03b9bf62dc6118FC9A4da',
        blockCreated: 16773775
      },
      multicall3: {
        address: '0xca11bde05977b3631167028862be2a173976ca11',
        blockCreated: 14353601
      }
    }
  })
  ```

  ### Extend the Wagmi config

  Extend Wagmi's `chains` config with configured Virtual Environments (`vMainnet`).
  To use this chain only while building UI, testing, and demoing the dapp, we added a `NEXT_PUBLIC_TENDERLY_VNETS_ENABLED` environment variable.

  To ease the development, add the **`initialChain`** and set it to `vMainnet`, so your dapp connects instantly to Virtual Environment.

  ```tsx showLineNumbers title="pages/_app.ts" lines={16,27,40} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}


  const config = getDefaultConfig({
    appName: 'vRainbowKit App',
    projectId: 'YOUR_PROJECT_ID',
    chains: [
      mainnet,
      polygon,
      optimism,
      arbitrum,
      base,
      ...(process.env.NEXT_PUBLIC_TENDERLY_VNETS_ENABLED === 'true' ? [vMainnet] : []),
      ...(process.env.NEXT_PUBLIC_ENABLE_TESTNETS === 'true' ? [sepolia] : []),
    ],
    ssr: true,
  });

  const client = new QueryClient();

  function MyApp({ Component, pageProps }: AppProps) {
    return (
      <WagmiProvider config={config}>
        <QueryClientProvider client={client}>
          <RainbowKitProvider
            initialChain={process.env.NEXT_PUBLIC_TENDERLY_VNETS_ENABLED === 'true' ? vMainnet : config.chains[0]}>
            <Component {...pageProps} />
          </RainbowKitProvider>
        </QueryClientProvider>
      </WagmiProvider>
    );
  }

  export default MyApp;
  ```

  ### Run the dapp

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  NEXT_PUBLIC_TENDERLY_VNETS_ENABLED=true pnpm run dev
  ```
</Steps>


# Dynamic
Source: https://docs.tenderly.co/virtual-environments/dapp-ui/dynamic

Learn how to configure Virtual Environments with Dynamic UI kit when building, staging, and demoing dapps.

In this guide you'll learn how to connect a Next.js app to [Virtual Environments](/virtual-environments/overview) using Dynamic.

[Dynamic](https://docs.dynamic.xyz) is a UI kit for building login flows and onboarding experiences.

You can connect Dynamic to Virtual Environments to interact with staged smart contracts while demoing your dap and building the UI. Dynamic wraps Wagmi internally, so you can also pair this setup with the [Wagmi integration](/virtual-environments/dapp-ui/wagmi).

<Steps>
  ### Create a Virtual Environment

  In Tenderly Dashboard, create a new Virtual Environment:

  * Select Mainnet as the base network
  * Name it `Dynamic Virtual Environment`
  * Choose a unique chain ID **`73571`**
  * Turn on the **Public Explorer**
  * Copy the **Virtual Environment RPC**

  ### Create a Chain Config

  Create a file `src/tenderly.config.ts` and replace the following:

  1. Paste the chain ID to the `id` property
  2. Change the chainNname and currency
  3. Paste the **Virtual Environment RPC** to **`rpcUrls`**
  4. Paste the **Block Explorer URL** to **`blockExplorerUrls`**

  ```typescript showLineNumbers title="src/tenderly.config.ts" lines={3-6} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  export const tenderlyChains = [
    {
      blockExplorerUrls: ['https://dashboard.tenderly.co/explorer/vnet/47cdac98-cda3-431a-8fce-9f31037a3d0c'],
      chainId: 73571,
      chainName: 'Virtual Ethereum Mainnet',
      iconUrls: ['https://app.dynamic.xyz/images/networks/eth.svg'],
      name: 'Ethereum',
      nativeCurrency: {
        decimals: 18,
        name: 'Ether',
        symbol: 'ETH',
      },
      networkId: 1,

      rpcUrls: [process.env.TENDERLY_VIRTUAL_MAINNET_RPC!],
      vanityName: 'Virtual ETH Mainnet',
    },
  ];
  ```

  ### Wrap your dapp in DynamicContextProvider

  Wrap your app (or a component) in a `DynamicContextProvider`, configure **`evmNetworks`** with `tenderlyChains` defined previously.

  ```tsx showLineNumbers title="app/layout.tsx" lines={17} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  'use client';


  export default function RootLayout({ children }: Readonly<{ children: React.ReactNode; }>) {
    return (
      <html lang="en">
      <DynamicContextProvider
        settings={{
          // Find your environment id at https://app.dynamic.xyz/dashboard/developer
          environmentId: 'ENVIRONMENT_ID',
          walletConnectors: [EthereumWalletConnectors],
          evmNetworks: process.env.NEXT_PUBLIC_TENDERLY_VNETS_ENABLED ? tenderlyChains : [],
        }}
      >
        <DynamicWagmiConnector>
          <body>
          <DynamicWidget />
          {children}
          </body>
        </DynamicWagmiConnector>
      </DynamicContextProvider>
      </html>

    );
  }
  ```

  ### Run the dapp

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  NEXT_PUBLIC_TENDERLY_VNETS_ENABLED=true pnpm run dev
  ```
</Steps>


# RainbowKit
Source: https://docs.tenderly.co/virtual-environments/dapp-ui/rainbowkit

Learn how to configure RainbowKit with Virtual Environments when building, staging, and demoing dapps.

[RainbowKit](https://rainbowkit.com/docs/introduction) is a React library that simplifies wallet connection for decentralized applications, offering wallet management, chain connections, ENS resolution, balance display, and customizable UI features to enhance the user experience.

You can connect RainbowKit to [Virtual Environments](/virtual-environments/overview) to interact with staged smart contracts while building your dapp UI.

<Steps>
  ### Create a Virtual Environment

  In Tenderly Dashboard, create a new Virtual Environment:

  * Select Mainnet as the base network
  * Name it `RainbowKit Virtual Environment`
  * Choose a unique chain ID **`73571`**
  * Turn on the **Public Explorer**
  * Copy the **Virtual Environment RPC**

  ### Create a Chain Config

  Create a file `src/tenderly.config.ts` and replace the following:

  1. Paste the chain ID to the `id` property
  2. Change the name and currency
  3. Paste the **Virtual Environment RPC** to **`rpcUrls.default.http`**
  4. Paste the **Block Explorer URL** to **`blockExplorers.default.url`**

  ```typescript showLineNumbers title="src/tenderly.config.ts" lines={4-5,8, 12-13} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

  export const vMainnet = defineChain({
    id: 73571,
    name: 'Virtual Ethereum Mainnet',
    nativeCurrency: { name: 'vEther', symbol: 'vETH', decimals: 18 },
    rpcUrls: {
      default: { http: [process.env.TENDERLY_VIRTUAL_MAINNET_RPC!] }
    },
    blockExplorers: {
      default: {
        name: 'Tenderly Explorer',
        url: 'https://dashboard.tenderly.co/explorer/vnet/47cdac98-cda3-431a-8fce-9f31037a3d0c'
      }
    },
    contracts: {
      ensRegistry: {
        address: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e'
      },
      ensUniversalResolver: {
        address: '0xE4Acdd618deED4e6d2f03b9bf62dc6118FC9A4da',
        blockCreated: 16773775
      },
      multicall3: {
        address: '0xca11bde05977b3631167028862be2a173976ca11',
        blockCreated: 14353601
      }
    }
  })
  ```

  ### Extend the Wagmi config

  Extend Wagmi's `chains` config with configured Virtual Environments (`vMainnet`). For a standalone setup, see the [Wagmi integration](/virtual-environments/dapp-ui/wagmi).
  To use this chain only while building UI, testing, and demoing the dapp, we added a `NEXT_PUBLIC_TENDERLY_VNETS_ENABLED` environment variable.

  To ease the development, add the **`initialChain`** and set it to `vMainnet`, so your dapp connects instantly to Virtual Environment.

  ```tsx showLineNumbers title="pages/_app.ts" lines={16,27,40} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}


  const config = getDefaultConfig({
    appName: 'vRainbowKit App',
    projectId: 'YOUR_PROJECT_ID',
    chains: [
      mainnet,
      polygon,
      optimism,
      arbitrum,
      base,
      ...(process.env.NEXT_PUBLIC_TENDERLY_VNETS_ENABLED === 'true' ? [vMainnet] : []),
      ...(process.env.NEXT_PUBLIC_ENABLE_TESTNETS === 'true' ? [sepolia] : []),
    ],
    ssr: true,
  });

  const client = new QueryClient();

  function MyApp({ Component, pageProps }: AppProps) {
    return (
      <WagmiProvider config={config}>
        <QueryClientProvider client={client}>
          <RainbowKitProvider
            initialChain={process.env.NEXT_PUBLIC_TENDERLY_VNETS_ENABLED === 'true' ? vMainnet : config.chains[0]}>
            <Component {...pageProps} />
          </RainbowKitProvider>
        </QueryClientProvider>
      </WagmiProvider>
    );
  }

  export default MyApp;
  ```

  ### Run the dapp

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  NEXT_PUBLIC_TENDERLY_VNETS_ENABLED=true pnpm run dev
  ```
</Steps>


# Reown AppKit
Source: https://docs.tenderly.co/virtual-environments/dapp-ui/reown

Learn how to connect ConnectKit to Virtual Environments when building, staging, and demoing dapps.

With [Reown AppKit](https://reown.com/reown-sdk), you can provide seamless wallet connections, including email and social logins, on-ramp functionality, smart accounts, one-click authentication, and wallet notifications, all designed to deliver an exceptional user experience.

You can use a Virtual Environment as a chain for UI development, testing, and dapp demo mode.

<Steps>
  ### Create a Virtual Environment

  In Tenderly Dashboard, create a new Virtual Environment:

  * Select Mainnet as the base network
  * Name it `Reown AppKit Virtual Environment`
  * Choose a unique chain ID **`73571`**
  * Turn on the **Public Explorer**
  * Copy the **Virtual Environment RPC**

  ### Create a Chain Config

  Create a file `app/tenderly.config.ts` and replace the following:

  1. Paste the chain ID to the `id` property
  2. Change the name and currency
  3. Paste the [**Public RPC**](/virtual-environments/overview#public-rpc) to **`rpcUrls.default.http`**
  4. Paste the **Block Explorer URL** to **`blockExplorers.default.url`**

  ```typescript showLineNumbers title="app/tenderly.config.ts" lines={4-5,8, 12-13} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

  export const vSepolia = defineChain({
    id: 73571,  // Add this to match the chain Id you set for your Virtual Environment
    caipNetworkId: 'eip155:73571',
    chainNamespace: 'eip155',
    name: 'Virtual Sepolia',
    nativeCurrency: { name: 'vSepolia', symbol: 'vETH', decimals: 18 },
    rpcUrls: {
      default:{
        http: [process.env.TENDERLY_VIRTUAL_TESTNET_RPC!],
      }
    },
    blockExplorers: {
      default:{
        name:'Tenderly Explorer',
        url: 'https://dashboard.tenderly.co/explorer/vnet/6a6910ba-5831-4758-9d89-1f8e3169433f', // replace this with your Virtual Environment's explorer URL
      }
    },
    contracts: {
      ensRegistry: {
        address: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e'
      },
      ensUniversalResolver: {
        address: '0xE4Acdd618deED4e6d2f03b9bf62dc6118FC9A4da',
        blockCreated: 16773775
      },
      multicall3: {
        address: '0xca11bde05977b3631167028862be2a173976ca11',
        blockCreated: 14353601
      }
    }
  })

  ```

  ### Create a Wagmi Config

  Create a Wagmi config at `config/index.tsx` that will:

  * include the `vMainnet` chain we defined in the previous step
  * Specify the [Public RPC](/virtual-environments/overview#public-rpc) in **`transport`** under `vMainnet.id`

  ```typescript showLineNumbers title="config/wagmi.config.ts" lines={13, 19-20} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

  // Get projectId from https://cloud.reown.com
  export const projectId = process.env.NEXT_PUBLIC_PROJECT_ID

  if (!projectId) {
    throw new Error('Project ID is not defined')
  }

  export const networks = [mainnet, arbitrum, vSepolia]

  //Set up the Wagmi Adapter (Config)
  export const wagmiAdapter = new WagmiAdapter({
    storage: createStorage({
      storage: cookieStorage
    }),
    ssr: true,
    transports: {
      [vSepolia.id]: http(process.env.TENDERLY_VIRTUAL_TESTNET_RPC!)
    },
    networks,
    projectId
  })

  export const config = wagmiAdapter.wagmiConfig
  ```

  ### Create a ContextProvider

  Now, inside your `context/index.tsx` file, you also need to import `vSepolia` and pass it as one of the supported networks within the `createAppKit` function, as shown below.

  To use the Virtual Environment only while building UI, testing, and demoing the dapp, we added a `NEXT_PUBLIC_TENDERLY_VNETS_ENABLED` environment variable.
  The call to `createWeb3Modal` uses `vMainnet` as the default chain, when app runs with `NEXT_PUBLIC_TENDERLY_VNETS_ENABLED`.

  ```tsx showLineNumbers title='context/index.tsx' lines={21, 31} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  'use client'



  // Set up queryClient
  const queryClient = new QueryClient()

  if (!projectId) {
    throw new Error('Project ID is not defined')
  }

  // Set up metadata
  const metadata = { //this is optional
    name: "appkit-example",
    description: "AppKit Example - EVM",
    url: "https://exampleapp.com", // origin must match your domain & subdomain
    icons: ["https://avatars.githubusercontent.com/u/37784886"]
  }

  // Create the modal
  const modal = createAppKit({
    adapters: [wagmiAdapter],
    projectId,
    networks: [mainnet, arbitrum, vSepolia],
    metadata: metadata,
    features: {
      analytics: true, // Optional - defaults to your Cloud configuration
    }
  })

  function ContextProvider({ children, cookies }: { children: ReactNode; cookies: string | null }) {
    const initialState = cookieToInitialState(wagmiAdapter.wagmiConfig as Config, cookies)

    return (
      <WagmiProvider config={wagmiAdapter.wagmiConfig as Config} initialState={initialState}>
        <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
      </WagmiProvider>
    )
  }

  export default ContextProvider
  ```

  ### Use the ContextProvider

  Wrap your dapp `body` (`app/layout.tsx`) in a `ContextProvider` we created in the last step.

  ```tsx showLineNumbers title="src/app/layout.ts" lines={15, 28} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

  const inter = Inter({ subsets: ['latin'] });

  export const metadata: Metadata = {
    title: 'Create Next App',
    description: 'Generated by create next app',
  };

  export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) {
    return (
      <html lang="en">

      <body className={inter.className}>
        <ContextProvider>
          {children}
        </ContextProvider>
      </body>
      </html>
    );
  }
  ```

  ### Run the dapp

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  ## Get projectId at https://cloud.reown.com
  NEXT_PUBLIC_PROJECT_ID=???? \
  NEXT_PUBLIC_TENDERLY_VNETS_ENABLED=true \
  pnpm run dev
  ```
</Steps>


# Wagmi
Source: https://docs.tenderly.co/virtual-environments/dapp-ui/wagmi

Learn how to connect Wagmi with Virtual Environments when building, staging, and demoing dapps.

[Wagmi](https://wagmi.sh/) is a React Hooks library that streamlines Ethereum integration in React applications, offering easy installation, chain configuration, and various hooks for wallet, contract, and transaction interactions.

In this guide you'll learn how to connect your Wagmi dapp with a Tenderly [Virtual Environment](/virtual-environments/overview). If you use a wallet connection UI on top of Wagmi, see the [RainbowKit integration](/virtual-environments/dapp-ui/rainbowkit).

<Steps>
  ### Create a Virtual Environment

  In Tenderly Dashboard, create a new Virtual Environment:

  * Select Mainnet as the base network
  * Name it `Wagmi Virtual Environment`
  * Choose a unique chain ID **`73571`**
  * Turn on the **Public Explorer**
  * Copy the **Virtual Environment RPC**

  ### Create a Chain Config

  Create a file `src/tenderly.config.ts` and replace the following:

  1. Paste the chain ID to the `id` property
  2. Change the name and currency
  3. Paste the **Virtual Environment RPC** to **`rpcUrls.default.http`**
  4. Paste the **Block Explorer URL** to **`blockExplorers.default.url`**

  ```typescript showLineNumbers title="src/tenderly.config.ts" lines={4-5,8, 12-13} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

  export const vMainnet = defineChain({
    id: 73571,
    name: 'Virtual Ethereum Mainnet',
    nativeCurrency: { name: 'vEther', symbol: 'vETH', decimals: 18 },
    rpcUrls: {
      default: { http: [process.env.TENDERLY_VIRTUAL_MAINNET_RPC!] }
    },
    blockExplorers: {
      default: {
        name: 'Tenderly Explorer',
        url: 'https://dashboard.tenderly.co/explorer/vnet/47cdac98-cda3-431a-8fce-9f31037a3d0c'
      }
    },
    contracts: {
      ensRegistry: {
        address: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e'
      },
      ensUniversalResolver: {
        address: '0xE4Acdd618deED4e6d2f03b9bf62dc6118FC9A4da',
        blockCreated: 16773775
      },
      multicall3: {
        address: '0xca11bde05977b3631167028862be2a173976ca11',
        blockCreated: 14353601
      }
    }
  }
  ```

  ### Extend the Wagmi configuration

  Add the **`vMainnet`** to `wagmi.ts` as one of **`chains`**, and a **`transports`** entry under `[vMainnet.id]`, referencing the Virtual Environment RPC.

  ```ts showLineNumbers title="src/wagmi.ts" lines={4, 7, 16} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

  export const config = createConfig({
    chains: [mainnet, vMainnet],
    connectors: [
      injected(),
      coinbaseWallet({ appName: 'Create Wagmi' })
      walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID || "" }),
    ],
    ssr: true,
    transports: {
      [mainnet.id]: http(`https://mainnet.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_MAINNET}`),
      [vMainnet.id]: http(process.env.TENDERLY_VIRTUAL_MAINNET_RPC!)
    }
  })

  declare module 'wagmi' {
    interface Register {
      config: typeof config
    }
  }

  ```
</Steps>


# Bytecode deployment cheatcode
Source: https://docs.tenderly.co/virtual-environments/develop/bytecode-deployment

Learn how you can deploy custom bytecode to any address using tenderly_setCode Admin RPC method.

The Admin RPC method [**`tenderly_setCode`**](/virtual-environments/admin-rpc#tenderly_setcode) lets you deploy arbitrary bytecode to an arbitrary address. This is useful for testing purposes, for instrumenting contracts that take part in the test.

<Warning>
  When deploying modified bytecode, the verification information will no longer match and it will not be possible to access traces and debugger for target addresses.
</Warning>

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
#!/bin/bash

# Define the Tenderly RPC URL

VIRTUAL_TESTNET_RPC="https://YOUR_VIRTUAL_TESTNET_RPC_URL" # Replace with the actual RPC
CONTRACT_ADDRESS="0x81a831281cb844cf383d5b7446048c33f8f61597" # Replace with the an arbitrary contract address

# Define the contract address and bytecode
BYTECODE="0x6080604052348015600f57600080fd5b506004361060325760003560e01c8063188ec356146037578063f2c9ecd814604b575b600080fd5b425b60405190815260200160405180910390f35b43603956fea2646970667358221220cf2559005e1cfe369d80627215e827ac118ec62d8642fc9962efa55315dd451b64736f6c63430008110033"

# Function to deploy the contract by setting the bytecode
set_code_response=$(curl -s -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "tenderly_setCode",
    "params": ["'"$CONTRACT_ADDRESS"'", "'"$BYTECODE"'"],
    "id": 1
  }' "$VIRTUAL_TESTNET_RPC")

# Call the function from contract

eth_call_response=$(curl -s -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_call",
    "params": [{
      "to": "'"$CONTRACT_ADDRESS"'",
      "data": "0x188ec356"
    }, "latest"],
    "id": 2
  }' "$VIRTUAL_TESTNET_RPC")

echo $eth_call_response
```


# Create Virtual Environments via API
Source: https://docs.tenderly.co/virtual-environments/develop/create-virtual-environment-via-api

Script the creation of single-network and Multichain Virtual Environments using the Tenderly REST API. Useful for CI/CD and per-PR environments.

Use the REST API to create Virtual Environments from scripts, CI/CD jobs, or any backend. The same endpoints back the dashboard.

For the full request and response schemas, see the [REST API reference](/virtual-environments/rest-api).

## Before you begin

* A [Tenderly access key](/platform/account/projects/api-tokens). Export it as `TENDERLY_ACCESS_KEY` in your shell.
* Your account and project slugs, available in the URL of your Tenderly Dashboard.

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export TENDERLY_ACCESS_KEY=# the key you copied
```

## Create a single-network Virtual Environment

<Steps>
  ### Call the API

  `POST` to the `vnets` endpoint with your fork and chain configuration:

  ```bash title="testnet-create.sh" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  RESPONSE=$(curl --request POST \
    --url https://api.tenderly.co/api/v1/account/me/project/project/vnets \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header "X-Access-Key: ${TENDERLY_ACCESS_KEY}" \
    --data '{
      "slug": "my-staging-testnet-25",
      "display_name": "My Staging TestNet",
      "fork_config":            { "network_id": 1, "block_number": "latest" },
      "virtual_network_config": { "chain_config": { "chain_id": 73571 } },
      "sync_state_config":      { "enabled": false, "commitment_level": "latest" },
      "explorer_page_config":   { "enabled": false, "verification_visibility": "bytecode" }
    }')
  ```

  ### Extract the Admin RPC URL

  The `rpcs` array on the response contains the Admin and Public RPC URLs. Pull the Admin RPC out for the rest of your script:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  ADMIN_RPC=$(echo $RESPONSE | jq -r '.rpcs[] | select(.name == "Admin RPC") | .url')
  ```
</Steps>

## Create a Multichain Virtual Environment

A [Multichain Virtual Environment](/virtual-environments/multichain/overview) is created in a single call via the `multivnets` endpoint. All networks in the call are grouped under one `stack_id`, which is what makes cross-chain bridging possible between them.

```bash title="multivnet-create.sh" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl --location 'https://api.tenderly.co/api/v1/account/me/project/project/multivnets' \
  --header 'accept: application/json, text/plain, */*' \
  --header "X-Access-Key: ${TENDERLY_ACCESS_KEY}" \
  --header 'content-type: application/json' \
  --data '{
    "vnets": [
      {
        "slug": "mainnet-staging",
        "fork_config":            { "network_id": 1,     "block_number": "latest" },
        "virtual_network_config": { "chain_config": { "chain_id": 1 } }
      },
      {
        "slug": "arbitrum-staging",
        "fork_config":            { "network_id": 42161, "block_number": "latest" },
        "virtual_network_config": { "chain_config": { "chain_id": 42161 } }
      },
      {
        "slug": "base-staging",
        "fork_config":            { "network_id": 8453,  "block_number": "latest" },
        "virtual_network_config": { "chain_config": { "chain_id": 8453 } }
      }
    ]
  }'
```

Each entry in the `vnets` array creates one network inside the Multichain Virtual Environment. The response returns a `stack_id` and an array of Virtual Environment objects, each with its own RPC endpoints.

See the [REST API reference](/virtual-environments/rest-api#create-a-multichain-virtual-environment) for the field-by-field schema.

## Next steps

* [Set up GitHub Actions with Foundry](/virtual-environments/ci-cd/github-actions-foundry) or [Hardhat](/virtual-environments/ci-cd/github-actions-hardhat) to provision Virtual Environments per pull request.
* [Stage contracts](/virtual-environments/ci-cd/stage-contracts) on the Virtual Environment you just created.
* Browse the full [REST API reference](/virtual-environments/rest-api).


# Debugging Transactions
Source: https://docs.tenderly.co/virtual-environments/develop/debug-transactions

Replay and debug a transaction on a Virtual Environment, step through its execution, and inspect state changes and revert reasons.

[Tenderly Debugger](/debugger/overview) is supported on transactions executed on the Virtual Environment. You can use it to inspect and debug transactions executed on your Virtual Environment with the same functionalities as if you were debugging real transactions.

For Debugger to work, it needs to come from a contract that has been verified on the parent network, Tenderly, or on the Virtual Environment.

Access Debugger by clicking on any transaction in the **Virtual Environment Explorer** and then on **Debugger**.

[Watch on Loom →](https://www.loom.com/share/09413e8a867f4ddeaa41a5080d771895?sid=b8f60cda-fcb8-401b-ba9a-8bb69630fe9a)

How can Debugger help you find and fix transaction errors?

* Navigate through the function calls of any transaction.
* Analyze emitted events and state changes.
* Get accurate gas usage details with [Gas Profiler](/debugger/gas-profiler).

If debugging reveals a logical error in the smart contract you're inspecting, you can use [Simulator UI](/simulator-ui/overview) with **Edit Source Code** to run the failing transaction against bug-fixed code. This is a quick way to validate the bug fix before applying it to the code-base and re-deploying.


# Deploy and verify contracts
Source: https://docs.tenderly.co/virtual-environments/develop/deploy-contracts

Deploy Solidity contracts to a Virtual Environment with Foundry or Hardhat, with verification for the Debugger, Gas Profiler, and Simulator.

Deploy Solidity contracts to a Virtual Environment using Foundry or Hardhat. Contracts deployed on a Virtual Environment are called **virtual contracts** and appear in the **Contracts** section under the **Virtual Contracts** tab.

Verify contracts as you deploy them. Verified contracts unlock the Debugger, Gas Profiler, Simulator, and richer transaction views in the explorer.

## Before you begin

* A [Virtual Environment](/virtual-environments/quickstart). Copy its RPC URL from the dashboard.
* A [funded deployer address](/virtual-environments/unlimited-faucet) on that Virtual Environment.

Verification on a Virtual Environment needs no separate access key: the RPC URL itself authenticates, and the verifier endpoint is that URL with `/verify` appended.

<Warning>
  By default, contracts verified on a Virtual Environment are private. Depending on the visibility setting of the [public explorer](/virtual-environments/explorer#public-explorer), the code may be visible externally. Check the public explorer toggle and [verification visibility](/virtual-environments/explorer#public-explorer) before verifying anything you want to keep private.
</Warning>

## Deploy and verify

<Tabs>
  <Tab title="Foundry">
    ### Configure `foundry.toml`

    Tenderly's verifier matches the metadata hash the Solidity compiler appends to deployed bytecode against the source you submit. Keep the metadata in the compiled output by setting `cbor_metadata` and `bytecode_hash` explicitly:

    ```toml title="foundry.toml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    [profile.default]
    src = "src"
    out = "out"
    libs = ["lib"]
    solc_version = "0.8.24"
    optimizer = true
    optimizer_runs = 200

    # Required for Tenderly contract verification:
    # keep the CBOR metadata so the verifier can match the on-chain bytecode hash.
    cbor_metadata = true
    bytecode_hash = "ipfs"
    ```

    `cbor_metadata = true` and `bytecode_hash = "ipfs"` are Foundry's defaults, but some templates strip them; `bytecode_hash = "none"` breaks verification. Pin `solc_version` and the optimizer settings so re-verification compiles the same bytecode.

    If your project uses libraries such as OpenZeppelin, declare the remappings explicitly in `remappings.txt`:

    ```bash title="remappings.txt" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    @openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/
    forge-std/=lib/forge-std/src/
    ```

    With auto-detected remappings, the verification payload can contain different remapping strings than the build used, which causes bytecode-mismatch failures.

    ### Set environment variables

    ```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    export TENDERLY_VIRTUAL_TESTNET_RPC=...   # paste your RPC URL
    export TENDERLY_VERIFIER_URL=$TENDERLY_VIRTUAL_TESTNET_RPC/verify
    export PRIVATE_KEY=...                    # deployer private key
    ```

    Sanity-check the connection before deploying. `cast chain-id` should print the Virtual Environment's chain ID, and the deployer balance should be non-zero:

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    cast chain-id --rpc-url $TENDERLY_VIRTUAL_TESTNET_RPC
    cast balance <DEPLOYER_ADDRESS> --rpc-url $TENDERLY_VIRTUAL_TESTNET_RPC
    ```

    ### Deploy with `forge create`

    Run `forge create` with the verify flags. Constructor arguments are passed as raw values; Foundry ABI-encodes them and submits the encoded form to the verifier:

    ```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    forge create src/Counter.sol:Counter \
      --rpc-url $TENDERLY_VIRTUAL_TESTNET_RPC \
      --private-key $PRIVATE_KEY \
      --broadcast \
      --verify \
      --verifier custom \
      --verifier-url $TENDERLY_VERIFIER_URL \
      --constructor-args 42
    ```

    <Warning>
      Put `--constructor-args` last. It greedily consumes the rest of the command line, so any flag placed after it is treated as another constructor argument.
    </Warning>

    ### Deploy with a Foundry script

    Use `forge script` to deploy multiple contracts in one run. Every `new Foo(...)` in the script is submitted for verification automatically, with the correct constructor arguments taken from the broadcast log. Imports are handled transparently: the verifier receives a standard-JSON payload containing every source file the compiler touched, so local imports and library imports (such as OpenZeppelin) verify without extra steps.

    Use `--slow` so transactions are sent one at a time. Without it, broadcast batching can submit a transaction before the previous one is confirmed, which is flaky against a hosted RPC and can race the verification step.

    ```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    forge script script/Counter.s.sol:CounterScript \
      --rpc-url $TENDERLY_VIRTUAL_TESTNET_RPC \
      --private-key $PRIVATE_KEY \
      --broadcast \
      --slow \
      --verify \
      --verifier custom \
      --verifier-url $TENDERLY_VERIFIER_URL
    ```

    ### Verify an existing contract

    Already-deployed contracts can be verified with `forge verify-contract`. Unlike `forge create`, this command expects constructor arguments **already ABI-encoded**; use `cast abi-encode` to produce them:

    ```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    forge verify-contract $COUNTER_ADDRESS src/Counter.sol:Counter \
      --verifier custom \
      --verifier-url $TENDERLY_VERIFIER_URL \
      --constructor-args $(cast abi-encode "constructor(uint256)" 42) \
      --watch
    ```

    `--watch` polls the verifier until verification finishes and prints the result. For multi-contract deployments, run `forge verify-contract` once per deployed address.
  </Tab>

  <Tab title="Hardhat">
    <Info>
      The `@tenderly/hardhat-tenderly` plugin is compatible with Hardhat up to version `2.22.0`. See [Hardhat verification](/contract-verification/hardhat#versions-and-compatibility) for the supported version matrix.

      ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      npm install hardhat@2.22.0
      ```
    </Info>

    ### Install the plugin and the CLI

    Install the Tenderly Hardhat plugin:

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    npm install --save-dev @tenderly/hardhat-tenderly
    ```

    Install the [Tenderly CLI](https://github.com/Tenderly/tenderly-cli) and log in so the plugin can authenticate:

    <Tabs>
      <Tab title="macOS (Homebrew)">
        ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        brew tap tenderly/tenderly
        brew install tenderly
        tenderly login
        ```
      </Tab>

      <Tab title="Linux">
        ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        curl https://raw.githubusercontent.com/Tenderly/tenderly-cli/master/scripts/install-linux.sh | sudo sh
        tenderly login
        ```
      </Tab>

      <Tab title="Manual">
        Download the latest binary from the [release page](https://github.com/Tenderly/tenderly-cli/releases), add it to your `$PATH`, then run:

        ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        tenderly login
        ```
      </Tab>
    </Tabs>

    ### Configure Hardhat

    Add `virtualMainnet` (or any name prefixed with `virtual` for clarity) to your `networks` block, then add a `tenderly` block with your [project and username slugs](/platform/account/projects/slug). Call `tenderly.setup()` with `automaticVerifications: true` so contracts are verified during every deploy.

    ```typescript title="hardhat.config.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import * as tenderly from "@tenderly/hardhat-tenderly";

    tenderly.setup({ automaticVerifications: true });

    const config: HardhatUserConfig = {
      solidity: "0.8.19",
      networks: {
        virtualMainnet: {
          url: process.env.TENDERLY_VIRTUAL_MAINNET_RPC!,
          chainId: 73571, // the Chain ID you selected at Virtual Environment creation
        },
      },
      tenderly: {
        project: "YOUR_PROJECT_SLUG",
        username: "YOUR_USERNAME_SLUG",
      },
    };

    export default config;
    ```

    ### Deploy

    Run your deploy script against the network you defined. With `automaticVerifications: true`, the plugin verifies as it deploys.

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    npx hardhat run scripts/deploy.ts --network virtualMainnet
    ```
  </Tab>
</Tabs>

## Check the dashboard

In the Tenderly Dashboard, open **Contracts** and select the **Virtual Contracts** tab. Your newly deployed contracts appear there, with verification status visible per contract.

## Troubleshooting

| Symptom                                                           | Likely cause                                                                                                                                           | Fix                                                                                                                                             |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `unauthorized` / `-32004` response from the verifier              | Wrong verifier URL. A common mistake is appending `/verify/etherscan` instead of `/verify`.                                                            | Make sure the verifier URL ends in exactly `/verify`.                                                                                           |
| `Bytecode does not match deployed contract`                       | The submitted source compiled differently than what's deployed: an `optimizer_runs` mismatch, a different `solc_version`, or a stripped metadata hash. | Pin `solc_version`, `optimizer`, `optimizer_runs`, and `bytecode_hash` in `foundry.toml`. Run `forge clean && forge build` before re-verifying. |
| `Failed to deserialize content`                                   | The verifier returned an error string Foundry can't parse, usually wrapping an upstream auth or path error.                                            | Re-check the URL and re-run with `-vvvv` to see the raw response.                                                                               |
| `Dry run enabled, not broadcasting transaction` on `forge create` | `--broadcast` not passed, or swallowed by `--constructor-args`.                                                                                        | Move `--constructor-args` to be the last flag.                                                                                                  |
| Only the first contract verifies on `forge script`                | RPC race: the second transaction was submitted before the first receipt.                                                                               | Add `--slow`.                                                                                                                                   |
| Verifier reports `OK` but the explorer still shows unverified     | UI caching.                                                                                                                                            | Hard-refresh the explorer page. The status in the API response is authoritative.                                                                |

## Next steps

* [Verify proxy contracts with Foundry](/virtual-environments/develop/verify-proxy-contracts): verify a UUPS implementation and its ERC1967 proxy, including upgrades.
* [Stage contracts](/virtual-environments/ci-cd/stage-contracts): share the RPC link and contract addresses with your team.
* [Stage your dApp](/virtual-environments/ci-cd/stage-dapps): point your frontend at the Virtual Environment.
* [Fork a Virtual Environment](/virtual-environments/develop/fork-testnet): branch from a Virtual Environment state.


# Fork a Virtual Environment
Source: https://docs.tenderly.co/virtual-environments/develop/fork-testnet

Fork a Virtual Environment to create a disposable working copy that inherits all contracts, balances, and state from the source at a point in time.

Forking a Virtual Environment creates an exact snapshot of its state at a specific moment. The new Virtual Environment inherits all contracts, balances, and transactions from the source network. This allows your team to develop in iterations with minimal interference while working on an accurate, disposable working copy.

<Note>
  A fork always starts from the latest block. To create a copy at a specific past block, [clone the Virtual Environment at a historical block](/virtual-environments/develop/revert-state#clone-at-a-historical-block) instead.
</Note>

After [staging smart contracts](/virtual-environments/ci-cd/stage-contracts), and setting up the state by [sending transactions](/virtual-environments/interact/send-transactions) or [funding accounts](/virtual-environments/unlimited-faucet), your team members can create **personal working copies** of the staging Virtual Environment. This way, tests don't impact the original Virtual Environment's state, and each team can perform their own tests with no test-data noise and interference.

<img alt="" />

To Fork a Virtual Environment:

* Click the **Fork** button located in the top right corner.
* Choose the project where the new Virtual Environment will reside and give it a name.

You can verify the origin of a forked Virtual Environment by checking the details section, which displays the source network from which the Virtual Environment was forked.

<img alt="" />

## Next Steps

* [Stage dapps](/virtual-environments/ci-cd/stage-dapps): Learn how to connect the Virtual Environment to your dapp's UI.
* [Revert state](/virtual-environments/develop/revert-state): Revert Virtual Environment state if testing steps aren't repeatable otherwise.


# Revert State
Source: https://docs.tenderly.co/virtual-environments/develop/revert-state

Revert a Virtual Environment to a previous state to re-run transactions and tests from a known checkpoint.

Reverting state can be helpful when testing contracts and protocols and you want to discard all state changes up to the snapshot position.

<Note>
  Instead of reverting state, consider [forking an existing Virtual Environment](/virtual-environments/develop/fork-testnet) instead, and do your testing on a disposable working copy.
</Note>

<img alt="" />

## Reverting to a snapshot

<Steps>
  ### Create snapshot

  Use [`evm_snapshot`](/virtual-environments/admin-rpc#evm_snapshot) to create a snapshot on the current block.
  The method returns the snapshot ID you can use to revert.

  ```bash title="snapshot.sh" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  TENDERLY_VIRTUAL_TESTNET_RPC= #...

  SNAPSHOT_ID=$(curl $TENDERLY_VIRTUAL_TESTNET_RPC \
      -X POST \
      -H "Content-Type: application/json" \
      -d '{
        "jsonrpc": "2.0",
        "method": "evm_snapshot",
        "id": "1234"
      }' \
      | jq -r  '.result')
  ```

  ### Revert

  Use [`evm_revert`](/virtual-environments/admin-rpc#evm_revert) to back revert to previously created snapshot (`SNAPSHOT_ID`).
  From this point onwards, all prior changes up to the snapshot will be discarded.

  ```bash title="revert.sh" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  read -r -d '' REVERT_REQUEST <<EOF
  {
    "jsonrpc": "2.0",
    "method": "evm_revert",
    "params": ["$SNAPSHOT_ID"],
    "id": "1234"
  }
  EOF

  curl $TENDERLY_VIRTUAL_TESTNET_RPC \
      -H "Content-Type: application/json" \
      -d $REVERT_REQUEST
  ```
</Steps>

## Revert distance limit

A single [`evm_revert`](/virtual-environments/admin-rpc#evm_revert) can roll back at most 2000 blocks. If the snapshot is more than 2000 blocks behind the current block, the call fails with:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
revert operation is limited to maximum 2000 blocks
```

This affects Virtual Environments that produce blocks continuously (for example, a scheduled job minting blocks), where the target snapshot can quickly fall outside the 2000-block window. To return to a point further back, clone the Virtual Environment at the target historical block instead of reverting.

## Clone at a historical block

To get a Virtual Environment whose state matches a specific past block, clone it at that block. The clone is a new, independent Virtual Environment forked at the chosen point, while the source is left untouched. There is no distance limit, so this is the way to reach a block more than 2000 blocks in the past.

In the dashboard, open the **Activity** tab and use the clone action on the transaction at the block you want to return to. The new Virtual Environment is created with state as of that transaction's block.

<Note>**Screenshot placeholder:** per-transaction clone action on the Activity tab.</Note>

Cloning at a historical block is also the right approach when you want to "fork at a specific block number." A [fork](/virtual-environments/develop/fork-testnet) always starts from the latest block, whereas a clone can target any historical block.


# Foundry Cheatcode Tutorial
Source: https://docs.tenderly.co/virtual-environments/develop/solidity-cheatcodes

Deploy a cheatcode playground on a Virtual Environment and use cast send to manipulate balances, nonces, storage, and event logs from transactions.

This tutorial builds a modular cheatcode playground in Foundry. You deploy a single contract to a Virtual Environment, then call its functions with `cast send` to exercise every [Solidity precompile cheatcode](/virtual-environments/precompiles) from inside transactions.

## What you build

Three files:

* `src/IVnetPrecompile.sol`: the precompile interface.
* `src/MyTestSetup.sol`: a playground contract. Each function wraps one precompile call, so you deploy once and call individual functions to manipulate one piece of state at a time.
* `script/Deploy.s.sol`: a `forge script` deploy.

### Function map

| Category | Function                                | Wraps                                             |
| -------- | --------------------------------------- | ------------------------------------------------- |
| Balance  | `forceBalance(account, newBalance)`     | `setBalance`                                      |
|          | `topUp(account, amount)`                | `addBalance`                                      |
| ERC-20   | `fundToken(token, holders[], amount)`   | `setErc20Balance`                                 |
|          | `maxToken(token, account)`              | `setMaxErc20Balance`                              |
| Nonce    | `forceNonce(account, newNonce)`         | `setNonce`                                        |
| Storage  | `writeStorage(target, slot, value)`     | `setStorageAt`                                    |
|          | `readStorage(target, slot) → bytes32`   | `getStorageAt`                                    |
| Events   | `fireTransfer(token, from, to, amount)` | `emitEvent` (ERC-20 `Transfer`)                   |
|          | `fireEvent(target, topics[], data)`     | `emitEvent` (generic, 0–4 topics)                 |
| Demo     | `demoScenario(account)`                 | Combines balance, nonce, storage, USDC `Transfer` |

## Prerequisites

* A Tenderly account with a project.
* Foundry installed (`curl -L https://foundry.paradigm.xyz | bash && foundryup`).

<Steps>
  ### Create a Virtual Environment

  In the Tenderly Dashboard, go to **Virtual Environments** and create a Virtual Environment. Copy the **Admin RPC** URL, the public RPC returns 401 on funding and verification calls, so use the Admin RPC throughout this tutorial.

  ### Initialize the Foundry project

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  forge init tenderly-cheatcodes
  cd tenderly-cheatcodes
  ```

  ### Add the precompile interface

  Save as `src/IVnetPrecompile.sol`:

  ```solidity title="src/IVnetPrecompile.sol" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  // SPDX-License-Identifier: MIT
  pragma solidity ^0.8.0;

  interface IVnetPrecompile {
      function setStorageAt(address target, bytes32 slot, bytes32 value) external returns (bool);
      function setBalance(address[] calldata addresses, uint256 balance) external returns (bool);
      function getStorageAt(address target, bytes32 slot) external view returns (bytes32);
      function addBalance(address[] calldata addresses, uint256 amount) external returns (bool);
      function setNonce(address target, uint256 value) external returns (bool);
      function setErc20Balance(address target, address[] calldata addresses, uint256 amount) external returns (bool);
      function addErc20Balance(address target, address[] calldata addresses, uint256 amount) external returns (bool);
      function setMaxErc20Balance(address target, address account) external returns (bool);

      function emitEvent(address target, bytes calldata data) external returns (bool);
      function emitEvent(address target, bytes32 topic1) external returns (bool);
      function emitEvent(address target, bytes32 topic1, bytes calldata data) external returns (bool);
      function emitEvent(address target, bytes32 topic1, bytes32 topic2) external returns (bool);
      function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes calldata data) external returns (bool);
      function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3) external returns (bool);
      function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3, bytes calldata data) external returns (bool);
      function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3, bytes32 topic4) external returns (bool);
      function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3, bytes32 topic4, bytes calldata data) external returns (bool);

      event SetStorageAtEvent(address target, bytes32 slot, bytes32 value);
      event SetBalanceEvent(address[] addresses, uint256 balance);
      event AddBalanceEvent(address[] addresses, uint256 amount);
      event SetNonceEvent(address target, uint256 value);
      event SetErc20BalanceEvent(address target, address[] addresses, uint256 amount);
      event AddErc20BalanceEvent(address target, address[] addresses, uint256 amount);
      event SetMaxErc20BalanceEvent(address target, address account);
  }
  ```

  ### Add the playground contract

  Save as `src/MyTestSetup.sol`:

  ```solidity title="src/MyTestSetup.sol" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  // SPDX-License-Identifier: MIT
  pragma solidity ^0.8.0;

  import {IVnetPrecompile} from "./IVnetPrecompile.sol";

  contract MyTestSetup {
      IVnetPrecompile constant VNET = IVnetPrecompile(0xc100000000000000000000000000000000000000);

      bytes32 constant TRANSFER_TOPIC = keccak256("Transfer(address,address,uint256)");

      function forceBalance(address account, uint256 amount) external {
          VNET.setBalance(_single(account), amount);
      }

      function topUp(address account, uint256 amount) external {
          VNET.addBalance(_single(account), amount);
      }

      function fundToken(address token, address[] calldata holders, uint256 amount) external {
          VNET.setErc20Balance(token, holders, amount);
      }

      function maxToken(address token, address account) external {
          VNET.setMaxErc20Balance(token, account);
      }

      function forceNonce(address account, uint256 n) external {
          VNET.setNonce(account, n);
      }

      function writeStorage(address target, bytes32 slot, bytes32 value) external {
          VNET.setStorageAt(target, slot, value);
      }

      function readStorage(address target, bytes32 slot) external view returns (bytes32) {
          return VNET.getStorageAt(target, slot);
      }

      function fireTransfer(address token, address from, address to, uint256 amount) external {
          VNET.emitEvent(
              token,
              TRANSFER_TOPIC,
              bytes32(uint256(uint160(from))),
              bytes32(uint256(uint160(to))),
              abi.encode(amount)
          );
      }

      function fireEvent(address target, bytes32[] calldata topics, bytes calldata data) external {
          if (topics.length == 0)      VNET.emitEvent(target, data);
          else if (topics.length == 1) VNET.emitEvent(target, topics[0], data);
          else if (topics.length == 2) VNET.emitEvent(target, topics[0], topics[1], data);
          else if (topics.length == 3) VNET.emitEvent(target, topics[0], topics[1], topics[2], data);
          else                         VNET.emitEvent(target, topics[0], topics[1], topics[2], topics[3], data);
      }

      function demoScenario(address account) external {
          VNET.setBalance(_single(account), 10 ether);
          VNET.setNonce(account, 5);
          VNET.setStorageAt(account, bytes32(uint256(0)), bytes32(uint256(0x1234)));
          VNET.addBalance(_single(account), 2 ether);
          VNET.emitEvent(
              0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48,
              TRANSFER_TOPIC,
              bytes32(uint256(0)),
              bytes32(uint256(uint160(account))),
              abi.encode(uint256(1000e6))
          );
      }

      function _single(address account) private pure returns (address[] memory arr) {
          arr = new address[](1);
          arr[0] = account;
      }
  }
  ```

  ### Add the deploy script

  Save as `script/Deploy.s.sol`:

  ```solidity title="script/Deploy.s.sol" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  // SPDX-License-Identifier: MIT
  pragma solidity ^0.8.0;

  import {Script} from "forge-std/Script.sol";
  import {MyTestSetup} from "../src/MyTestSetup.sol";

  contract Deploy is Script {
      function run() external {
          vm.startBroadcast();
          new MyTestSetup();
          vm.stopBroadcast();
      }
  }
  ```

  ### Configure environment variables

  Save as `.env`:

  ```bash title=".env" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  VNET_RPC=https://virtual.mainnet.eu.rpc.tenderly.co/<your-virtual-env-uuid>
  PRIVATE_KEY=0x...
  DEPLOYER=0x...
  ```

  Source it: `source .env`.

  ### Fund the deployer

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  cast rpc tenderly_setBalance "[\"$DEPLOYER\"]" "0x56BC75E2D63100000" --rpc-url "$VNET_RPC"
  ```

  ### Deploy and verify

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  forge script script/Deploy.s.sol:Deploy \
      --rpc-url "$VNET_RPC" \
      --private-key "$PRIVATE_KEY" \
      --broadcast --slow \
      --verify \
      --verifier custom \
      --verifier-url "$VNET_RPC/verify"
  ```

  Export the deployed address from the script output:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  export TEST_CONTRACT=0x...
  ```

  ### Exercise the cheatcodes

  Each call is a separate transaction. Re-run with different arguments at any time, no redeployment needed.

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # Set 999 ETH on an arbitrary account
  cast send "$TEST_CONTRACT" "forceBalance(address,uint256)" \
      0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 999000000000000000000 \
      --rpc-url "$VNET_RPC" --private-key "$PRIVATE_KEY"

  # Give two accounts 1,000,000 USDC each (6 decimals)
  cast send "$TEST_CONTRACT" "fundToken(address,address[],uint256)" \
      0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
      '[0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB]' \
      1000000000000 \
      --rpc-url "$VNET_RPC" --private-key "$PRIVATE_KEY"

  # Max out an account's DAI balance
  cast send "$TEST_CONTRACT" "maxToken(address,address)" \
      0x6B175474E89094C44Da98b954EedeAC495271d0F \
      0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA \
      --rpc-url "$VNET_RPC" --private-key "$PRIVATE_KEY"

  # Set vitalik.eth's nonce to 4242
  cast send "$TEST_CONTRACT" "forceNonce(address,uint256)" \
      0xd8da6bf26964af9d7eed9e03e53415d37aa96045 4242 \
      --rpc-url "$VNET_RPC" --private-key "$PRIVATE_KEY"

  # Write storage slot 0 of a contract
  cast send "$TEST_CONTRACT" "writeStorage(address,bytes32,bytes32)" \
      "$TARGET" \
      0x0000000000000000000000000000000000000000000000000000000000000000 \
      0x0000000000000000000000000000000000000000000000000000000000001234 \
      --rpc-url "$VNET_RPC" --private-key "$PRIVATE_KEY"

  # Spoof a 1 DAI Transfer from the real DAI contract
  cast send "$TEST_CONTRACT" "fireTransfer(address,address,address,uint256)" \
      0x6B175474E89094C44Da98b954EedeAC495271d0F \
      0xCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC \
      0xDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD \
      1000000000000000000 \
      --rpc-url "$VNET_RPC" --private-key "$PRIVATE_KEY"

  # Spoof a BAYC ERC-721 Transfer of token #1234 (all args indexed, data is empty)
  cast send "$TEST_CONTRACT" "fireEvent(address,bytes32[],bytes)" \
      0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D \
      '[0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef,0x000000000000000000000000CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC,0x000000000000000000000000DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD,0x00000000000000000000000000000000000000000000000000000000000004d2]' \
      0x \
      --rpc-url "$VNET_RPC" --private-key "$PRIVATE_KEY"
  ```

  ### Verify the state changes

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  cast balance 0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA --rpc-url "$VNET_RPC"
  cast nonce   0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --rpc-url "$VNET_RPC"
  cast storage "$TARGET" 0                                --rpc-url "$VNET_RPC"
  cast call 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 "balanceOf(address)(uint256)" \
      0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA --rpc-url "$VNET_RPC"
  ```

  ### Confirm the spoofed log

  Pull the receipt and check `logs[]` for an entry whose `address` matches the contract you spoofed:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  cast receipt <TX_HASH> --rpc-url "$VNET_RPC" --json | jq '.logs'
  ```

  For the BAYC example, the receipt should contain:

  ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  {
    "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
    "topics": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "0x000000000000000000000000cccccccccccccccccccccccccccccccccccccccc",
      "0x000000000000000000000000dddddddddddddddddddddddddddddddddddddddd",
      "0x00000000000000000000000000000000000000000000000000000000000004d2"
    ],
    "data": "0x"
  }
  ```

  `address` matches the BAYC contract, `topics[0]` is the `Transfer` event signature hash, and `topics[1–3]` carry the indexed `from`, `to`, and `tokenId`. An indexer listening for BAYC transfers will process this log identically to a real emission.

  <Note>
    The precompile also emits diagnostic logs with `address` = `0xc100000000000000000000000000000000000000`, recording each state mutation. Filter `logs[]` by the target address to isolate the spoofed log from the precompile's own entries.
  </Note>
</Steps>

## See also

* [Solidity Cheatcodes reference](/virtual-environments/precompiles), full interface definition and function table.
* [Admin RPC](/virtual-environments/admin-rpc), state manipulation from outside a transaction via JSON-RPC.


# The Graph and Virtual Environments
Source: https://docs.tenderly.co/virtual-environments/develop/thegraph

Guide to setting up and using Tenderly Virtual Environments alongside The Graph.

This guide provides detailed steps to set up and use Tenderly Virtual Environments alongside The Graph.

To use The Graph with Virtual Environments, you need to run your own Graph node. In case you're staging your dapp, you'll have to have The Graph instance hosted on your cloud provider of choice.

## Prerequisites

Ensure you have the following prerequisites installed on your system:

* Node.js and npm
* Docker
* A [Tenderly account](https://dashboard.tenderly.co/login?redirectTo=testnets)
* A Virtual Environment RPC
* A smart contract deployed to Virtual Environment using [Hardhat](/virtual-environments/develop/deploy-contracts#hardhat) or [Foundry](/virtual-environments/develop/deploy-contracts#foundry)

## Set up The Graph

<Steps>
  ### Install Graph CLI Globally

  Install the Graph CLI globally on your system using npm:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  npm install -g @graphprotocol/graph-cli
  ```

  Refer to the official [Graph CLI documentation](https://thegraph.com/docs/en/developer/cli/) for more details.

  ### Set up The Graph project

  Inside your project directory, initialize The Graph project.

  Notes:

  * Adapt `--abi` to point to contrac ABI on your local system
  * Modify the `--contract-name` and `--from-contract` with contract name and address, respectively
  * Set he `--start-block`
  * Change the `--network` so it references the network you based your Virtual Environment off of (e.g. `mainnet`, `base`, etc.).

  <Note>
    We recommend having `network` match the original network's name, without labeling it as `virtual_`. This enables effortless switching of RPCs when deploying to different staging and demoing environments.
  </Note>

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  graph init your-subgraph-name subgraph-dir \
  --protocol ethereum \
  --studio \
  --abi path/to/abi/ERC20Token.json \
  --contract-name ERC20TokenFactory \
  --from-contract 0x7F2Fa32C991fD2F8dF3EB23C394f550376e9b30d \
  --start-block 0 \
  --network mainnet
  ```

  <Card title="Graph Initialization documentation" href="" />

  ### Update `docker-compose.yml`

  Edit the `docker-compose.yml` file (below) and update `environment.ethereum` so it refers to the Virtual Environment RPC.

  ```yaml showLineNumbers lines={15} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  version: '3'
  services:
    graph-node:
      image: graphprotocol/graph-node
      ports:
        - '8020:8020'
        - '8000:8000'
        - '5001:5001'
      environment:
        postgres_host: postgres
        postgres_user: graph-node
        postgres_pass: let-me-in
        postgres_db: graph-node
        ipfs: 'ipfs:5001'
        ethereum: 'mainnet:https://virtual.mainnet.rpc.tenderly.co/d0a6...-40..2c-81..0f-a5..90'
  ```

  <Card title="Graph Docker documentation" href="" />

  ### Run Docker Compose locally

  After setting up docker-compose config, run the following:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  docker-compose up
  ```

  ### Create and deploy your subgraph

  Run the following commands, replacing `your-subgraph-name` with the desired name for your subgraph.

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  graph codegen
  graph create --node http://localhost:8020 your-subgraph-name
  graph deploy --node http://localhost:8020 --ipfs http://localhost:5001 your-subgraph-name
  ```

  <Card title="Graph Deployment documentation" href="" />

  ### Access the subgraph

  After deployment, access your subgraph through the URL below. Open this URL in your browser to access the subgraph and run queries:

  `Deployed to http://localhost:8000/subgraphs/name/your-subgraph-name`

  <Card title="Graph Query documentation" href="" />

  ### Deploy to Cloud

  For dapp staging, deploy The Graph node your cloud provider of choice, and connect your dapp UI/backend to that node for querying.
</Steps>


# Working with timestamps on Virtual Environments
Source: https://docs.tenderly.co/virtual-environments/develop/timestamps

Learn how you can access the correct timestamp and advance time on Virtual Environments

For certain types of tests it's useful to skip through time. This is possible by relying on 2 Admin RPC methods available on Virtual Environments: **[`evm_setNextBlockTimestamp`](/virtual-environments/admin-rpc/#evm_setnextblocktimestamp)** and **[`evm_setNextBlockTimestamp`](/virtual-environments/admin-rpc/#evm_setnextblocktimestamp)**.

## Getting the correct time

During execution of a transaction or `eth_call` accesses `block.timestamp` within a contract, the value will depend on whether the target block (`latest` or `pending`) block:

* For **`pending` block**: `block.timestamp == time.now() + adjustment_offset`. This represents the current time adjusted by the time-adjustment methods.
* For **`latest` block**: `block.timestamp == latest_block.timestamp`. This is the timestamp of the most recently mined block.

The `adjustment_offset` comes from time-adjustment methods:

1. [`evm_setNextBlockTimestamp`](/virtual-environments/admin-rpc/#evm_setnextblocktimestamp):
   Skips time to the timestamp for the next block: `adjustment_offset = timestamp - time.now()`.

2. [`evm_increaseTime`](/virtual-environments/admin-rpc/#evm_increasetime):
   Advances time by a relative amount.
   `adjustment_offset += increase_value`

## Examples

### Increase time by an offset

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
VIRTUAL_TESTNET_RPC=https://YOUR-RPC-URL-HERE
curl -s -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "evm_increaseTime",
    "params": ["0xe10"],
    "id": 2
  }' "$VIRTUAL_TESTNET_RPC"
```

### Set timestamp for pending block

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
VIRTUAL_TESTNET_RPC=https://YOUR-RPC-URL-HERE

# Get the current date in Unix timestamp format
current_date=$(date +%s)

# Use evm_setTime to set the block time to today (current timestamp)
curl -s -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "evm_setNextBlockTimestamp",
    "params": ["'"$current_date"'"],
    "id": 3
  }' "$VIRTUAL_TESTNET_RPC"
```


# Verify proxy contracts with Foundry
Source: https://docs.tenderly.co/virtual-environments/develop/verify-proxy-contracts

Deploy and verify a UUPS implementation and its ERC1967 proxy on a Virtual Environment with forge script, then re-verify after an upgrade.

A proxy deployment consists of two contracts: the proxy, which delegates every call, and the implementation, which holds the logic. Both must be verified separately. For any proxy that follows [ERC-1967](https://eips.ethereum.org/EIPS/eip-1967), the Tenderly explorer reads the standard implementation storage slot, so once both contracts are verified, calls to the proxy address are decoded with the implementation's ABI.

This guide deploys a UUPS implementation (`CounterV1`) behind an `ERC1967Proxy` on a [Virtual Environment](/virtual-environments/overview), verifies both in one `forge script` run, upgrades the implementation to `CounterV2`, and covers re-verifying a proxy that was deployed without verification. For the Hardhat equivalent, see [Verifying Proxy Contracts](/contract-verification/hardhat-proxy).

## Before you begin

* Complete the setup from [Deploy and verify contracts](/virtual-environments/develop/deploy-contracts): a Virtual Environment, a [funded deployer address](/virtual-environments/unlimited-faucet), and a `foundry.toml` with `cbor_metadata = true` and `bytecode_hash = "ipfs"`.
* Set the environment variables:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export TENDERLY_VIRTUAL_TESTNET_RPC=...   # your Virtual Environment RPC URL
export TENDERLY_VERIFIER_URL=$TENDERLY_VIRTUAL_TESTNET_RPC/verify
export PRIVATE_KEY=...                    # deployer private key
```

* Install OpenZeppelin's upgradeable contracts alongside the base library:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge install OpenZeppelin/openzeppelin-contracts --no-git --shallow
forge install OpenZeppelin/openzeppelin-contracts-upgradeable --no-git --shallow
```

* Add both remappings to `remappings.txt`:

```bash title="remappings.txt" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/
@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/
forge-std/=lib/forge-std/src/
```

The two libraries serve different roles: `openzeppelin-contracts` provides the proxy (`ERC1967Proxy`), and `openzeppelin-contracts-upgradeable` provides the implementation building blocks (`Initializable`, `UUPSUpgradeable`, `OwnableUpgradeable`). The upgradeable versions replace constructors with initializer functions, because constructors don't run when state lives behind a proxy.

## The implementation contract

```solidity title="src/CounterV1.sol" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";

contract CounterV1 is Initializable, OwnableUpgradeable, UUPSUpgradeable {
    uint256 public number;

    /// @custom:oz-upgrades-unsafe-allow constructor
    constructor() {
        _disableInitializers();
    }

    function initialize(address owner_, uint256 initialNumber) external initializer {
        __Ownable_init(owner_);
        number = initialNumber;
    }

    function increment() external {
        number += 1;
    }

    function setNumber(uint256 newNumber) external {
        number = newNumber;
    }

    function version() external pure virtual returns (string memory) {
        return "v1";
    }

    function _authorizeUpgrade(address newImplementation) internal override onlyOwner {}
}
```

Three parts of this contract matter for the proxy pattern:

1. `constructor() { _disableInitializers(); }` locks the implementation. Only the proxy is supposed to hold state; this constructor makes a direct `initialize` call on the implementation address revert.
2. `initialize(...)` replaces the constructor. The proxy delegatecalls it once, in the same transaction that deploys the proxy.
3. `_authorizeUpgrade(...)` is the required UUPS permissioning hook. It runs on every `upgradeToAndCall`; if it reverts, the upgrade is blocked.

## The deploy script

```solidity title="script/DeployProxy.s.sol" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {Script, console} from "forge-std/Script.sol";
import {ERC1967Proxy} from "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
import {CounterV1} from "../src/CounterV1.sol";

contract DeployProxyScript is Script {
    function run() public {
        address owner = vm.addr(vm.envUint("PRIVATE_KEY"));
        uint256 initialNumber = 42;

        vm.startBroadcast();

        // 1. Deploy the implementation.
        CounterV1 implementation = new CounterV1();

        // 2. Deploy the proxy, calling initialize(owner, 42) in the same tx.
        bytes memory initData = abi.encodeCall(CounterV1.initialize, (owner, initialNumber));
        ERC1967Proxy proxy = new ERC1967Proxy(address(implementation), initData);

        vm.stopBroadcast();

        console.log("Implementation:", address(implementation));
        console.log("Proxy         :", address(proxy));
        console.log("Owner         :", owner);
    }
}
```

The script deploys the logic contract, builds the `initialize` calldata with `abi.encodeCall` (which type-checks the arguments at compile time, unlike `abi.encodeWithSignature`), and deploys the proxy. The proxy's constructor stores the implementation address in the ERC-1967 implementation slot and delegatecalls `initData` against it, atomically initializing the proxy's storage.

## Deploy and verify both contracts

The proxy and the implementation are two contracts in one script, so the command is the same `forge script` shape as any multi-contract deployment:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge script script/DeployProxy.s.sol:DeployProxyScript \
  --rpc-url        $TENDERLY_VIRTUAL_TESTNET_RPC \
  --private-key    $PRIVATE_KEY \
  --broadcast --slow \
  --verify \
  --verifier       custom \
  --verifier-url   $TENDERLY_VERIFIER_URL
```

Expected tail of the output:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
ONCHAIN EXECUTION COMPLETE & SUCCESSFUL.
##
Start verification for (2) contracts
Submitting verification for [src/CounterV1.sol:CounterV1] 0xeDa7...
	Response: `OK`
	Details: `Pass - Verified`
Submitting verification for [lib/openzeppelin-contracts/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy] 0xb22e...
	Response: `OK`
	Details: `Pass - Verified`
All (2) contracts were verified!
```

Note the second submission path: the proxy is verified as `lib/openzeppelin-contracts/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy`, the OpenZeppelin contract from your `lib/` tree, not a contract in `src/`. Foundry resolves this automatically because the script's broadcast log records every `new` and its bytecode.

## Confirm the proxy linkage

The explorer decodes calls through the proxy when both the proxy and the implementation are verified. To confirm the proxy is delegating, read the ERC-1967 implementation slot directly:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
PROXY=<your-proxy-address>
IMPL_SLOT=0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc

cast storage $PROXY $IMPL_SLOT --rpc-url $TENDERLY_VIRTUAL_TESTNET_RPC
# 0x000000000000000000000000<implementation address, 20 bytes>
```

Then call an implementation function through the proxy:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
cast call $PROXY "number()(uint256)" --rpc-url $TENDERLY_VIRTUAL_TESTNET_RPC
# 42
```

In the Tenderly Dashboard, the proxy's address page shows the verified `ERC1967Proxy` source, a proxy tag with the linked implementation address, and an ABI view that includes the implementation's functions. Transactions calling `proxy.increment()` or `proxy.setNumber(...)` are decoded with the implementation's function names and parameter labels in the call trace.

<Note>
  If the explorer shows the proxy but doesn't decode calls with the implementation's ABI, the most common cause is that only one of the two contracts is verified. Re-run `forge verify-contract` on whichever is missing.
</Note>

## Upgrade the implementation

UUPS upgrades are issued through `upgradeToAndCall(newImpl, callData)`, inherited from `UUPSUpgradeable`. Add a V2:

```solidity title="src/CounterV2.sol" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {CounterV1} from "./CounterV1.sol";

contract CounterV2 is CounterV1 {
    function decrement() external {
        number -= 1;
    }

    function version() external pure override returns (string memory) {
        return "v2";
    }
}
```

Storage layout constraints when writing a V2:

* Inherit from V1, or copy V1's storage layout verbatim. Storage slots are positional; adding a new state variable before an existing one corrupts the proxy's state.
* New state variables go after V1's existing variables, never between them.
* Don't change existing variable types or reorder declarations.

```solidity title="script/UpgradeProxy.s.sol" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {Script, console} from "forge-std/Script.sol";
import {CounterV1} from "../src/CounterV1.sol";
import {CounterV2} from "../src/CounterV2.sol";

contract UpgradeProxyScript is Script {
    function run() public {
        address proxy = vm.envAddress("PROXY");

        vm.startBroadcast();

        CounterV2 newImplementation = new CounterV2();
        CounterV1(proxy).upgradeToAndCall(address(newImplementation), bytes(""));

        vm.stopBroadcast();

        console.log("New implementation:", address(newImplementation));
        console.log("Proxy upgraded:    ", proxy);
    }
}
```

Run it with the same verify flags:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
PROXY=<your-proxy-address> \
forge script script/UpgradeProxy.s.sol:UpgradeProxyScript \
  --rpc-url        $TENDERLY_VIRTUAL_TESTNET_RPC \
  --private-key    $PRIVATE_KEY \
  --broadcast --slow \
  --verify \
  --verifier       custom \
  --verifier-url   $TENDERLY_VERIFIER_URL
```

Only `CounterV2` is deployed and verified (the output reports `(1) contracts`). The proxy address doesn't change; only its ERC-1967 slot does. After the script returns:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
cast storage $PROXY $IMPL_SLOT --rpc-url $TENDERLY_VIRTUAL_TESTNET_RPC
# 0x000000000000000000000000<CounterV2 address>

cast call $PROXY "version()(string)" --rpc-url $TENDERLY_VIRTUAL_TESTNET_RPC
# "v2"

cast call $PROXY "number()(uint256)" --rpc-url $TENDERLY_VIRTUAL_TESTNET_RPC
# 42   <-- state preserved; only the logic changed
```

The proxy address in the explorer now decodes against `CounterV2`'s ABI. The old `CounterV1` implementation remains verified at its original address but is no longer the active implementation.

## Verify a proxy that's already deployed

If you deployed without `--verify`, run `forge verify-contract` for each contract separately.

The implementation was deployed via `new CounterV1()` with no constructor arguments, so no `--constructor-args` flag is needed:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge verify-contract <IMPL_ADDRESS> src/CounterV1.sol:CounterV1 \
  --verifier       custom \
  --verifier-url   $TENDERLY_VERIFIER_URL \
  --watch
```

The proxy requires the exact constructor arguments used at deploy time, ABI-encoded:

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# ABI-encode: constructor(address implementation, bytes initData)
INIT_DATA=$(cast calldata "initialize(address,uint256)" <OWNER_ADDRESS> 42)

forge verify-contract <PROXY_ADDRESS> \
  lib/openzeppelin-contracts/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy \
  --verifier       custom \
  --verifier-url   $TENDERLY_VERIFIER_URL \
  --constructor-args $(cast abi-encode "constructor(address,bytes)" <IMPL_ADDRESS> $INIT_DATA) \
  --watch
```

Three details to get right:

1. **The contract path uses the `lib/` location**, not `src/`. The proxy is OpenZeppelin's code, so the source the verifier matches against lives in `lib/openzeppelin-contracts/...`. `forge script --verify` resolves this automatically; `forge verify-contract` doesn't.
2. **`initData` must match the deploy-time `initData` exactly.** Even if state changed after deployment, the constructor argument is the original `initialize(owner, 42)` calldata the proxy bytecode was constructed with.
3. **The proxy's constructor signature is `(address, bytes)`**, and `forge verify-contract` expects the already-ABI-encoded form, which is what `cast abi-encode` produces.

## Next steps

* [Deploy and verify contracts](/virtual-environments/develop/deploy-contracts): the base Foundry and Hardhat verification flow on a Virtual Environment.
* [Smart Contract Verification Using Foundry](/contract-verification/foundry): verifying contracts on public networks through Tenderly's verification API.
* [Verifying Proxy Contracts](/contract-verification/hardhat-proxy): the Hardhat plugin flow for UUPS, Transparent, and Beacon proxies.


# Virtual Environment Explorer
Source: https://docs.tenderly.co/virtual-environments/explorer

Browse Virtual Environment transactions privately, or enable the public explorer to share read-only contract and transaction access with external users.

[Virtual Environments](/virtual-environments/overview) offer two types of explorers: **private** and **public**. Each serves distinct visibility purposes for managing activity on your Virtual Environment and whether or not external users have access to your smart contracts through the explorer.

### Private explorer

<Frame>
  <img alt="Virtual Environment Activity view listing executed transactions with network, status, function, block, hash, from, and to columns, with Contracts, Wallets, and JSON-RPC Calls sections in the sidebar" />
</Frame>

Accessible only to your team, the private explorer provides an overview of everything happening on your Virtual Environment:

* **Activity**: Overview of all the transactions executed on your Virtual Environment, with a **Transactions** and a **Mempool** view
* **Contracts**: Explorer for contracts you're monitoring (watched contracts) and contracts deployed on the Virtual Environment (virtual contracts)
* **Wallets**: Explorer for wallets you're monitoring (watched wallets) on your Virtual Environment
* **JSON-RPC Calls**: Explorer for all the RPC methods executed on your Virtual Environment

### Public explorer

Enabling the public explorer generates a public URL that you can share with anyone and allow them to view transactional activity on your Virtual Environment. A Tenderly account is not required to view a public explorer.

You can enable the public explorer with the **Public Explorer** option in the **Advanced** section of the Virtual Environment creation form, or at any point afterwards under **Settings** > **Advanced**.

To open the public explorer and get the public URL, click the **Public explorer** button with a 🌐 globe icon in the **Integrate Virtual RPC** section at the top of your Virtual Environment's **Home** view.

The public explorer can be disabled at any point. Go to **Settings** > **Advanced**, uncheck **Public Explorer**, and apply the change.

#### Contract visibility in public explorer

<Frame>
  <img alt="Create Virtual Environment form with the Contract visibility dropdown open, showing ABI only, Full source code, and None options" />
</Frame>

When you enable the public explorer, select the level of visibility for smart contracts on your Virtual Environment with the **Contract visibility** dropdown:

* **None**: No access is provided to contracts verified on the Virtual Environment; only publicly verified contracts from the parent network remain visible.
* **ABI only**: Only the ABI of your contracts is accessible but not the source code.
* **Full source code**: Allows complete visibility of all contracts verified on your Virtual Environment through the public explorer. See [deploy and verify contracts](/virtual-environments/develop/deploy-contracts) for how source code gets verified on a Virtual Environment.

You can change the contract visibility level at any time under **Settings** > **Advanced**.


# Virtual Environment Integration Guides
Source: https://docs.tenderly.co/virtual-environments/integrations

Learn how to integrate Virtual Environments with different client libraries, smart contract development frameworks, and UI libraries.

Virtual Environments support the most popular client libraries, smart contract frameworks, and UI libraries. On this page, you can find links to guides with simple code snippets that enable you to quickly integrate your Virtual Environment with third-party libraries.

## Client libraries

Client libraries enable your dapp to connect to your Virtual Environment via RPC and interact with it.

<CardGroup>
  <Card title="Ethers.js" href="/virtual-environments/libraries/ethers">
    Typescript and Javascript library for interacting with the Ethereum blockchain and ecosystem.
  </Card>

  <Card title="Viem" href="/virtual-environments/libraries/viem">
    TypeScript Interface that provides low-level stateless primitives for interacting with Ethereum.
  </Card>
</CardGroup>

## Smart contract frameworks

Deploying contracts with Foundry or Hardhat is covered in [Deploy and verify contracts](/virtual-environments/develop/deploy-contracts), which walks through configuration, deployment, and automatic verification for both frameworks.

## Dapp UI libraries

Dapp UI libraries provide pre-built components designed for building dapp interfaces that communicate with the blockchain. Below you'll find code snippets for popular UI libraries to connect to your Virtual Environment via RPC.

<CardGroup>
  <Card title="Wagmi" href="/virtual-environments/dapp-ui/wagmi">
    React hooks library for building Ethereum apps with wallet connection modules.
  </Card>

  <Card title="WalletConnect" href="/virtual-environments/dapp-ui/reown">
    Tools, modules, and SDKs for building secure and interactive dapps.
  </Card>

  <Card title="ConnectKit" href="/virtual-environments/dapp-ui/connectkit">
    React.js component library for connecting wallets to dapps.
  </Card>

  <Card title="Dynamic" href="/virtual-environments/dapp-ui/dynamic">
    Login flows for crypto users, onboarding, and developer tools.
  </Card>

  <Card title="RainbowKit" href="/virtual-environments/dapp-ui/rainbowkit">
    React library for adding wallet connections to dapps.
  </Card>
</CardGroup>


# Adding Virtual Environments to Wallets
Source: https://docs.tenderly.co/virtual-environments/interact/add-to-wallet

Add a Virtual Environment as a custom network in MetaMask to send transactions and interact with deployed contracts through the wallet UI.

Virtual Environments can be added as providers in wallets like Metamask. This allows you to interact with the Virtual Environment through a wallet to send and receive funds between accounts.

<Note>
  When creating a Virtual Environment, it's recommended to set a **different chain ID from the parent chain ID**.
  For example, if you're creating a Virtual Environment that uses Mainnet as the base network (chainID `1`), specify a different chainID: `73571`.
</Note>

## Adding a Virtual Environment as a provider in MetaMask

From the Virtual Environments dashboard,

1. Click **Add to MetaMask**. This will work if you configure your Virtual Environment with a [unique chain ID](/troubleshooting/virtual-environments#unique-chain-id).
2. Follow the instructions in Metamask and approve the network.

To manually add Virtual Environments to MetaMask's list of available networks, follow these steps:

1. [Create a Virtual Environment](/virtual-environments/quickstart) with a custom chain ID.
2. Copy the [Public RPC](/virtual-environments/overview#public-rpc) link.
3. Open MetaMask and click the network selector.
4. Click **Add network**, and in the next window click **Add a network manually**.
5. Select an arbitrary name (e.g. **Virtual Mainnet**).
6. Paste the RPC URL.
7. Paste the chain ID you chose.
8. Paste the block explorer URL.
9. Click **Save**.

[Watch on Loom →](https://www.loom.com/embed/4275dd13f6c8443ea851708ced61fd7e?sid=7007b253-7dfb-4ed8-9641-f54615b1354e)


# Sending Transactions to Virtual Environments
Source: https://docs.tenderly.co/virtual-environments/interact/send-transactions

Send signed and unsigned transactions to a Virtual Environment over JSON-RPC, and fund accounts with Admin RPC cheatcodes.

Virtual Environments allow you to send transactions to the virtual network. The process of sending transactions is identical to sending transactions on the real network.

Transactions can be sent through the Dashboard UI or via RPC. This page shows you how to do it using both methods.

## Sending via RPC

Use the `eth_sendRawTransaction` RPC method to send transactions to your Virtual Environment.

The example below shows you how to send a transaction using Viem, Ethers.js and the cURL command. The code snippets are runnable without changes.

<Tabs>
  <Tab title="Shell">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl $TENDERLY_VIRTUAL_TESTNET_RPC \
        -X POST \
        -H "Content-Type: application/json" \
        -d '{
              "jsonrpc": "2.0",
              "id": 0,
              "method": "eth_sendRawTransaction",
              "params": [
                "0x095ea7b300000000000000000000000040bdb4497614bae1a67061ee20aade3c2067ac9e00000000000000000000000000000000000000000000000000000000000186a0"
              ]
        }'
    ```
  </Tab>

  <Tab title="virtual-environments/src/viem-send-tx.ts">
    Find more details on Viem integration by reading [this guide](/virtual-environments/libraries/viem).

    ```typescript showLineNumbers title="virtual-environments/src/viem-send-tx.ts" lines={2,4, 17, 23} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

    const EXPLORER_BASE_URL = vMainnet.blockExplorers.default;

    const account = privateKeyToAccount(generatePrivateKey());

    (async () => {
      const client = createWalletClient({
        account,
        chain: vMainnet,
        transport: http(vMainnet.rpcUrls.default.http[0]),
      });

      await tenderlySetBalance(client, [
        [account.address],
        "0xDE0B6B3A7640000",
      ]);


      const tx = await client.sendTransaction({
        to: "0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC",
        value: parseEther("0.01"),
      });

      console.log(`${EXPLORER_BASE_URL}/tx/${tx}`);
    })();
    ```
  </Tab>

  <Tab title="send-tx.ts">
    Find more details on Ethers integration by reading [this guide](/virtual-environments/libraries/ethers).

    ```ts title="send-tx.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

    await (async () => {
      const provider = new ethers.JsonRpcProvider(process.env.TENDERLY_VIRTUAL_TESTNET_RPC!);

      const signer = Wallet.fromPhrase(Mnemonic.fromEntropy(ethers.randomBytes(24)).phrase, provider);

      await provider.send("tenderly_setBalance", [
        signer.address,
        "0xDE0B6B3A7640000",
      ]);

      const tx = await signer.sendTransaction({
        to: "0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC",
        value: ethers.parseEther("0.01"),
      });

      console.log(`${process.env.VIRTUAL_MAINNET_EXPLORER!}/tx/${tx.hash}`);
    })();
    ```
  </Tab>
</Tabs>

## Sending from the Dashboard

Transactions sent from the Dashboard will be recorded in the Virtual Environment's state. These transactions **do not need to be signed** and can be sent to and from any address on the Virtual Environment.

From the Explorer view, click on the **Send icon** from the top right to access the **Send Transaction** input form.

[Watch on Loom →](https://www.loom.com/embed/e376ad4184ab4294b9e0ca57033af568?sid=0cdaf910-aad4-41fc-86a6-6bc678032341)

<Steps>
  ### Select a contract

  In the **address** field, paste the address of the DAI stablecoin contract:`0x6B175474E89094C44Da98b954EedeAC495271d0F`.

  The receiving contract can be any of the following:

  * Virtual Contract [deployed on the Virtual Environment](/virtual-environments/develop/deploy-contracts)
  * Contract added to your [Tenderly project](/platform/account/projects/overview)
  * Any pre-existing contract on the network

  ### Specify the call data

  For contracts that are [verified on Tenderly](/contract-verification/overview) (privately or publicly) or publicly on Etherscan or Blockscout,
  you can use the **Choose function and parameters**.

  1. Select the **`approve`** function
  2. Paste an address you wish to approve DAI to (`0x40BdB4497614bAe1A67061EE20AAdE3c2067AC9e`)
  3. Set the wei amount of DAI you want to approve. For example, `10000000000000000000`.

  <Note>For unverified contracts, you need to **enter raw input data/calldata** in hex form.</Note>

  ### Fill in transaction parameters

  You can fill in the following options:

  * **From**: Any account address since transactions on Virtual Environments don't need to be signed. Use `0xbd8daa414fda8a8a129f7035e7496759c5af8570` or any address you funded with DAI.
  * **Gas**: Defaults to `800000` or set the desired gas (limit)
  * **Gas Price**: Defaults to `0` or an arbitrary gas price
  * **Value**: Defaults to `0` or specify an arbitrary transaction value, that will be deducted from the sender's (**from**) balance.

  <Note>
    Sender accounts need to have sufficient funds to send transactions. Use the [Unlimited Faucet](/virtual-environments/unlimited-faucet) to top up any account with any balance before sending transactions on Virtual Environments.
  </Note>

  ### Send transaction

  Click **Send Transaction**.

  Sent transactions will appear in the [Virtual Environment Explorer](/virtual-environments/explorer). Click on the transaction to inspect the call trace, debug using Debugger, or re-simulate with different parameters.

  <img alt="" />
</Steps>

## Next steps

* [Simulate a transaction](/virtual-environments/interact/simulate-transactions): Run transaction simulations from the Dashboard or via RPC
* [Deploy a smart contract](/virtual-environments/develop/deploy-contracts): Start deploying and monitoring smart contracts
* [Stage dapps](/virtual-environments/ci-cd/stage-dapps): Learn how to connect the Virtual Environment to you dapp's UI
* [Debug transactions](/virtual-environments/develop/debug-transactions) by using Tenderly Debugger.


# Simulate Transactions
Source: https://docs.tenderly.co/virtual-environments/interact/simulate-transactions

Simulate a transaction on a Virtual Environment to preview its outcome, gas usage, state changes, and emitted events before sending.

Transaction simulations are supported on Virtual Environments. You can simulate transactions form the Dashboard UI or programmatically using RPC.

<CardGroup>
  <Card title="Simulator UI" href="/simulator-ui/overview" />

  <Card title="Simulation RPC" href="/node-rpc/rpc-reference?network=ethereum-mainnet&method=tenderly_simulateTransaction" />

  <Card title="Bundle Simulation RPC" href="/node-rpc/rpc-reference?network=ethereum-mainnet&method=tenderly_simulateBundle" />

  <Card title="Simulation API on Virtual Environments" href="/api-reference" />
</CardGroup>

## Simulate from the Dashboard

To simulate a transaction from the Dashboard, go to **Virtual Environments** and click **Simulate** from the left-hand menu. Simulated transactions are visible only within the Virtual Environment dashboard and won't be visible in the [Public Explorer](/virtual-environments/explorer#public-explorer).
You can use the Simulator in the following ways:

* Debug smart contracts errors, using **Edit Source** to check your bugfix.
* Call contracts to get a sense of states without persisting transactions to the network.
* Set up desired contract states using **State Overrides**, to evaluate the execution under conditions that aren't and shouldn't be present on the chain.
* Build proof of concept transactions to validate testing scenarios.

## Simulate via RPC

Transactions on Virtual Environments can also be simulated using our the RPC methods [`tenderly_simulate`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction) and [`tenderly_simulateBundle`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateBundle).

<Note>
  We recommend integrating the Simulation RPC, but it's possible to use [Simulation REST API](/api-reference).
</Note>

The example code below runs a simulation that uses state overrides to mint DAI.

* Sender address: `0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2`.
* DAI contract address: `0x6b175474e89094c44da98b954eedeac495271d0f`
* State override arguments: `DAI(0x6b175474e89094c44da98b954eedeac495271d0f).wards[0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2] = 1`

Explore this guide to learn more about [simulating with state overrides](/simulations/state-overrides).

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# simulate DAI minting by 0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2
# 0xf1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1 gets the minted DAI
# Simulated on the latest block

VIRTUAL_TESTNET_RPC=RPC_LINK_HERE

curl $VIRTUAL_TESTNET_RPC \
-X POST \
-H "Content-Type: application/json" \
-d \
'{
  "id":0,
  "jsonrpc":"2.0",
  "method":"tenderly_simulateTransaction",
  "params":[
    {
      "from":"0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
      "to":"0x6b175474e89094c44da98b954eedeac495271d0f",
      "gas":"0x7a1200",
      "data":"0x40c10f19000000000000000000000000f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f10000000000000000000000000000000000000000000000001bc16d674ec80000"
    },
    "latest",
    {
      "0x6b175474e89094c44da98b954eedeac495271d0f":{
        "stateDiff":{
          "0xedd7d04419e9c48ceb6055956cbb4e2091ae310313a4d1fa7cbcfe7561616e03":"0x0000000000000000000000000000000000000000000000000000000000000001"
        },
        "balance": "0xFFFFFF"
      }
    }
  ]
}'
```

## Simulate transactions via client libraries

To simulate transactions via Ethers and Viem, check out the following example:

<Card title="Simulating with Viem" href="" />


# Connect to a WebSocket on Virtual Environments
Source: https://docs.tenderly.co/virtual-environments/interact/websockets

Connect over WebSockets to a Virtual Environment for real-time block and event updates using eth_subscribe and eth_unsubscribe.

WebSockets provide an efficient, real-time connection to Virtual Environments, allowing immediate updates on new blocks and events. By eliminating the need for constant polling, WebSockets reduce latency and server load. They’re crucial for dapps requiring instant data, such as DEXs and trading platforms.

Tenderly supports websockets for both [Node RPCs](/node-rpc/overview) and [Virtual Environments](/virtual-environments/overview), enabling you to build and test responsive, high-performance blockchain applications with ease.

WebSocket access is necessary for using the `eth_subscribe` and `eth_unsubscribe` methods.

* `eth_subscribe`
* `eth_unsubscribe`

## Connecting to Tenderly WebSockets

1. Go to the [Virtual Environments page](https://dashboard.tenderly.co/?redirectTo=testnets)
2. Create a new Virtual Environments or select an existing one and copy the RPC URL
3. Test with `wscat`:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
wscat -c wss://virtual.mainnet.rpc.tenderly.co/$VIRTUAL_TESTNET_ID
```

Once connected, you can send JSON-RPC requests to the Tenderly WebSocket. You'll receive responses in real time. For example, you can try sending an **eth\_subscribe** request:

```json title="request.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}
```

You should receive a response that looks something like this:

```json title="response.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{"id":1,"jsonrpc":"2.0","result":"0x5ab4555c1620e384bfb27d9f3a01c71e"}
```


# Ethers.js
Source: https://docs.tenderly.co/virtual-environments/libraries/ethers

Learn how to use Ethers.js to connect to a blockchain network through Node RPC.

[Ethers.js](https://docs.ethers.org/v5/) is a standalone Typescript/Javascript for interacting with the Virtual Environments.

You can use the standard RPC methods when you connecti via the **Public RPC**, or the [Admin RPC](/virtual-environments/admin-rpc) when you connect using the **Admin RPC**.

<Card title="Code samples: Using Ethers with Virtual Environments" href="" />

```typescript title="virtual-environments/src/ethers-6-https.ts" showLineNumbers lines={4-5, 9, 15, 21, 28, 35, 41} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

const RPC_URL = process.env.VIRTUAL_MAINNET_RPC_URL || '';
const EXPLORER_BASE_URL = `https://dashboard.tenderly.co/explorer/vnet/${path.basename(RPC_URL)}`;

const provider = new JsonRpcProvider(RPC_URL);
(async () => {
    const ret = await Promise.all([
      provider.send('tenderly_setBalance', [
        ['0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B', '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'],
        '0xDE0B6B3A7640000',
      ]),

      // USDT
      provider.send('tenderly_setErc20Balance', [
        '0xdAC17F958D2ee523a2206206994597C13D831ec7',
        '0x40BdB4497614bAe1A67061EE20AAdE3c2067AC9e',
        '0xDE0B6B3A7640000',
      ]),

      // DAI
      provider.send('tenderly_setErc20Balance', [
        '0x6B175474E89094C44Da98b954EedeAC495271d0F',
        '0x40BdB4497614bAe1A67061EE20AAdE3c2067AC9e',
        '0xDE0B6B3A7640000',
      ]),
      // Shiba Inu
      provider.send('tenderly_setErc20Balance', [
        '0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE',
        '0x40BdB4497614bAe1A67061EE20AAdE3c2067AC9e',
        '0xDE0B6B3A7640000',
      ]),
    ]);
    console.log('ETH balance, DAI and ShibaInu topups', ret.map(txHash => `${EXPLORER_BASE_URL}/tx/${txHash}`));
  }
)().catch(e => {
  console.error(e);
  process.exitCode = 1;
});
```


# Viem
Source: https://docs.tenderly.co/virtual-environments/libraries/viem

Connect viem to a Virtual Environment to define a custom chain, call standard and custom RPC methods, and simulate or trace transactions.

[Viem](https://viem.sh/) is a TypeScript Interface for Ethereum that provides low-level stateless primitives for interacting with Ethereum.

You can interact with Virtual Environments using the standard RPC methods when you copy the **Public RPC**,
as well as [custom methods available on Node RPC](/virtual-environments/admin-rpc) when you copy the **Admin RPC**.

<Card title="Code samples: Using Viem with Virtual Environments" href="" />

## Define a custom chain

Create a file `tenderly.config.ts` and use **`defineChain`** to create a chain object.

<Info>
  If you specified a unique Chain ID during Virtual Environment creation, you need to create a new chain object and set the **`id`** to your chosen value.
</Info>

```typescript title="virtual-environments/src/tenderly.config.ts" showLineNumbers lines={4, 8, 13} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

export const vMainnet = defineChain({
  id: 73571,
  name: 'Virtual Ethereum Mainnet',
  nativeCurrency: { name: 'vEther', symbol: 'vETH', decimals: 18 },
  rpcUrls: {
    default: { http: [process.env.TENDERLY_VIRTUAL_MAINNET_RPC!] },
  },
  blockExplorers: {
    default: {
      name: 'Tenderly Explorer',
      url: process.env.TENDERLY_VIRTUAL_MAINNET_EXPLORER!
    },
  },
  contracts: {
    ensRegistry: {
      address: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e',
    },
    ensUniversalResolver: {
      address: '0xE4Acdd618deED4e6d2f03b9bf62dc6118FC9A4da',
      blockCreated: 16773775,
    },
    multicall3: {
      address: '0xca11bde05977b3631167028862be2a173976ca11',
      blockCreated: 14353601,
    },
  },
});
```

## Define Viem actions for custom RPC methods

Define Viem actions for custom RPC methods, such as `tenderly_setBalance` `tenderly_setErc20Balance`, and `simulate`.

For example, the following file defines a `tenderlySetBalance` action that will invoke `tenderly_setBalance`.

You can find more actions here:

<Card title="Viem actions for custom RPC methods" href="" />

```typescript title="virtual-environments/src/viem-tenderly-actions.ts" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

type TSetBalanceParams = [addresses: Hex[], value: Hex];

export async function tenderlySetBalance(client: Client, params: TSetBalanceParams) {
  return client.request<{
    method: 'tenderly_setBalance',
    Parameters: TSetBalanceParams,
    ReturnType: Hex
  }>({
    method: 'tenderly_setBalance',
    params: params,
  });
}
```

## Call standard and custom RPC methods

In this example, you can see how to:

* Call Viem's `createPublicClient` and pass the following arguments:
* **`chain`**: set to `vMainnet` we defined in the previous step
* **`transport`**: either a call to `http`, and set to `https` RPC URL.

```typescript title="virtual-environments/src/viem-call-balance-top-up.ts" showLineNumbers {8, 12-13, 24-28, 31-34, 39-41, 46} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

(async () => {
  const client = createPublicClient({
    chain: vMainnet,
    transport: http(vMainnet.rpcUrls.default.http[0]),
  });

  console.log("Block Number", await client.getBlockNumber());
  console.log("Chain", await client.getChainId());

  const balanceTxs = await Promise.all([
    tenderlySetBalance(client, [
      ["0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B", "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"],
      "0xDE0B6B3A7640000"
    ]),
    tenderlySetErc20Balance(client, [
      "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "0x40BdB4497614bAe1A67061EE20AAdE3c2067AC9e",
      "0xDE0B6B3A7640000"
    ]),
    // USDT
    tenderlySetErc20Balance(client, [
      "0x6B175474E89094C44Da98b954EedeAC495271d0F",
      "0x40BdB4497614bAe1A67061EE20AAdE3c2067AC9e",
      "0xDE0B6B3A7640000"
    ]),
    tenderlySetErc20Balance(client, [
      "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
      "0x40BdB4497614bAe1A67061EE20AAdE3c2067AC9e",
      "0xDE0B6B3A7640000"
    ]),
  ]);

  console.log(
    "ETH balance, DAI and ShibaInu topups",
    balanceTxs.map(txHash => `${(vMainnet.blockExplorers.default.url)}/tx/${txHash}`));
})().catch(e => {
  console.error(e);
  process.exitCode = 1;
});
```

## Simulate transactions using viem

To use Virtual Environment's [Simulation RPC methods](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction), simply `request` to make the call to **`tenderly_simulateTransaction`**:

```typescript title="virtual-environments/src/viem-call-simulate.ts" showLineNumbers {6, 9-24} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

const client = createPublicClient({
  chain: vMainnet,
  transport: http(vMainnet.rpcUrls.default[0])
});

const simulation = await client.request({
  method: "tenderly_simulateTransaction",
  params: [
    // transaction object
    {
      from: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      to: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      gas: "0x0",
      gasPrice: "0x0",
      value: "0x0",
      data: "0xa9059cbb00000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001",
    },
    // the block
    "latest",
  ],
});

console.log("Trace");
console.log(JSON.stringify(simulation.trace, null, 2));
console.log("Logs");
console.log(JSON.stringify(simulation.logs, null, 2));
console.log("Asset Changes");
console.log(JSON.stringify(simulation.assetChanges, null, 2));
console.log("Balance Changes");
console.log(JSON.stringify(simulation.balanceChanges, null, 2));
```

## Trace transactions using Viem

Use [`tenderly_traceTransaction`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_traceTransaction) to get fully decoded transaction trace.

```ts showLineNumbers title="node/samples/viem/2-transaction-trace.ts" {2-6} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const txTrace = await client.request({
  method: "tenderly_traceTransaction",
  params: [
    // transaction hash
    "0x6b2264fa8e28a641d834482d250080b39cbbf39251344573c7504d6137c4b793"
  ],
});


console.log("Logs");
console.log(JSON.stringify(txTrace.logs, null, 2));
console.log("=======================================================");
console.log("Asset Changes");
console.log(JSON.stringify(txTrace.assetChanges, null, 2));
console.log("=======================================================");
console.log("Balance Changes");
console.log(JSON.stringify(txTrace.balanceChanges, null, 2));
console.log("=======================================================");
```


# Bridges
Source: https://docs.tenderly.co/virtual-environments/multichain/bridges

Relay LayerZero, Chainlink CCIP, Across, and CCTP messages between networks in a Multichain Virtual Environment, with configurable relay modes.

The Bridge Module connects the networks in a [Multichain Virtual Environment](/virtual-environments/multichain/overview). With it enabled, a source-chain transaction that emits a bridge event triggers the corresponding delivery on the destination chain within the same Virtual Environment. Relay runs in the mode you configure (immediate or delayed) and uses no real funds.

<Note>
  The Bridge Module is available on plans that include multichain capabilities. [Contact us](https://tenderly.co/contact-us) to enable it on your account.
</Note>

## Enabling the Bridge Module

Open the **Settings** page for your Virtual Environment and expand the **Advanced** panel. Check **Bridge** ("Enable cross-network bridge"), then **Save Changes**. Once enabled, relay covers every supported protocol on the networks attached to the Virtual Environment.

Two settings control how messages are relayed:

* **Relay mode**: `Auto relay` delivers the destination transaction as soon as the source event is detected. `Delayed relay` holds delivery for a fixed interval so you can test in-flight timing and destination-chain latency.
* **Delayed relay seconds**: the delay applied in `Delayed relay` mode (for example `3600`).

<Frame>
  <img alt="Bridge settings Advanced panel showing the Bridge enable checkbox, a Relay mode dropdown set to Delayed relay, a Delayed relay seconds field set to 3600, and the supported protocols Layer Zero, Chainlink, Across, and CCTP with descriptions" />
</Frame>

The module only relays where the protocol contracts are already deployed. If a protocol is not present on a network in your Virtual Environment, that route is not available. The [Bridge contracts panel](#bridge-dashboard) shows which protocol router contracts are deployed per network.

## Supported protocols

| Protocol           | Version support                     | What it relays                                                                                                                                   |
| ------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **LayerZero**      | Standard messaging (see note below) | Omnichain messaging protocol with configurable security. A source `PacketSent` triggers the destination delivery (`lzReceive`).                  |
| **Chainlink CCIP** | v1.5 and v1.6                       | Chainlink's cross-chain interoperability protocol. A source `CCIPMessageSent` triggers the destination delivery (for example `manuallyExecute`). |
| **Across**         | V3                                  | Intent-based bridge with optimistic verification. A source `V3FundsDeposited` triggers the destination fill.                                     |
| **CCTP**           | v2.0                                | Circle's Cross-Chain Transfer Protocol for native USDC transfers across chains.                                                                  |

LayerZero relay covers standard omnichain messages. LayerZero Read requests are relayed on Ethereum Mainnet only, and composed messages (`lzCompose`) are not relayed.

## Supported networks

Bridge protocol availability is narrower than overall network support because the Bridge Module relies on the real protocol contracts being present on a given network. Initial coverage:

| Protocol       | Initially supported networks                |
| -------------- | ------------------------------------------- |
| LayerZero      | Ethereum, Arbitrum, Optimism, Base, Polygon |
| Chainlink CCIP | Ethereum, Arbitrum, Optimism, Base, Polygon |
| Across         | Ethereum, Arbitrum, Optimism, Base, Polygon |
| CCTP           | Ethereum, Arbitrum, Optimism, Base, Polygon |

Per-network protocol support follows the protocol's own deployments. For Chainlink CCIP, check the [CCIP Directory](https://docs.chain.link/ccip/directory/mainnet) to confirm which networks CCIP supports.

Coverage expands based on customer demand. If you need a specific network enabled for a bridge protocol, reach out to us at [support@tenderly.co](mailto:support@tenderly.co).

## Bridge dashboard

The **Overview** tab gives you operational visibility into all bridge activity in the Virtual Environment:

* **Top routes**: each source-to-destination network pair, its protocol, and the number of relayed operations.
* **Bridge contracts**: the protocol router contracts deployed on each network, with network, contract name, address, and protocol.
* **Bridge transactions**: a list of every relayed operation with its status, source network and transaction, destination network and transaction, protocol, and relative time. An auto-refresh interval control keeps the list current.

<Frame>
  <img alt="Bridge Overview tab showing a Top routes panel (route, protocol, relayed count), a Bridge contracts panel (network, name, address, protocol), and a transaction list with status, source and destination networks and transactions, protocol, and relative time" />
</Frame>

To confirm a round-trip, find the source transaction (for example a LayerZero `PacketSent`) and follow its row across to the matching destination transaction (`lzReceive`).

### Bridge operation detail

Selecting a row opens the bridge operation, which shows the protocol, the overall status, and the chain of transactions that make up the cross-chain message: each step's network, status, function (for example `verify`, `lzReceive`), block, transaction hash, sender, recipient, and gas used. An **Input** viewer renders the decoded message payload (`srcEid`, `dstEid`, `guid`, `options`, `sendLibrary`) with a Decoded/Raw toggle.

<Frame>
  <img alt="Bridge operation detail page showing protocol layerzero with completed status, a table of constituent transactions with functions verify and lzReceive and their gas used, and a decoded input payload with srcEid, dstEid, guid, options, and sendLibrary fields" />
</Frame>

## When to use bridging

| Scenario                                                               | Use                                                                                          |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Cross-chain dApps, bridges, governance, and multi-chain protocol logic | [Multichain Virtual Environment](/virtual-environments/multichain/overview) with bridging on |
| Single-network development with no bridge concerns                     | A standard [Virtual Environment](/virtual-environments/quickstart) per network               |

## See also

* [Multichain Virtual Environments overview](/virtual-environments/multichain/overview)
* [Multichain quickstart](/virtual-environments/multichain/quickstart)
* [Unlimited Faucet](/virtual-environments/unlimited-faucet)
* [Admin RPC](/virtual-environments/admin-rpc)


# Multichain Virtual Environments
Source: https://docs.tenderly.co/virtual-environments/multichain/overview

One Virtual Environment that spans multiple networks, with shared identity, predictable RPC URLs, Virtual Chain IDs, and a unified cross-chain timeline.

A Multichain Virtual Environment is a single testing environment that contains more than one blockchain network. You might attach Ethereum mainnet, Arbitrum, Optimism, Base, or any of the other 100+ supported EVM networks to one Virtual Environment, then work with them all under a shared identity. Each network keeps its own RPC endpoints, explorer view, and faucet, but they live together in one resource that you create, fund, and tear down as a unit.

What a Multichain Virtual Environment adds on top of running separate per-network Virtual Environments is awareness across chains. The [Bridge Module](/virtual-environments/multichain/bridges) can detect cross-chain messages on one network and relay them to another in the same Virtual Environment, and the dashboard shows you one timeline of transactions across the whole environment.

<Note>
  Multichain Virtual Environments and the Bridge Module are available on plans that include multichain capabilities. [Contact us](https://tenderly.co/contact-us) to enable them on your account.
</Note>

<Frame>
  <img alt="Virtual Environments list showing one Virtual Environment with Mainnet network, Network Mirror sync mode, and created timestamp" />
</Frame>

## Common uses

* Deploy and test contracts across multiple chains simultaneously from one environment.
* Cross-chain protocol testing across Mainnet, Arbitrum, and Optimism, with bridge transactions running end-to-end.
* Bridge integration validation against LayerZero, CCIP, CCTP and Across, with instant relay for happy paths and manual controls for failure modes.
* Security testing for replay attacks, oracle configurations, and light-client implementations.
* CI/CD pipelines that deploy and regression-test across multiple chains on every push.
* Staging environments where a dApp runs against a multichain backend without real funds.

See the [quickstart](/virtual-environments/multichain/quickstart) to create one, or [Bridges](/virtual-environments/multichain/bridges) for the bridge relay model.

## How a Multichain Virtual Environment is organized

A Multichain Virtual Environment is one environment with one or more networks attached. The Virtual Environment has a consistent identity (name and slug). Adding or removing a network does not change the others.

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Organization
  > Project
    > Virtual Environment
        > Network: Ethereum
        > Network: Arbitrum
        > Network: Optimism
      > Enabled Features
          > Block Explorer (ON)
          > Bridges (ON)
          > State Sync (OFF)
```

You can mix production chains and testnets in the same Virtual Environment, drawing from any of the 100+ EVM networks Tenderly supports. Production chains appear first in the creation flow. See [supported networks](/platform/supported-networks) for the full list.

<Frame>
  <img alt="Create Virtual Environment form with the network dropdown open showing multiple EVM networks to choose from, and Bridge / Public Explorer toggles in the Advanced section" />
</Frame>

## RPC URLs

Every network in your Virtual Environment gets a predictable RPC URL. The URL includes the organization slug, project slug, and a Virtual Environment slug (a random 6-character string assigned at creation that cannot be changed):

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://virtual.<network>.<region>.rpc.tenderly.co/<org-slug>/<project-slug>/<env-slug>
```

If your org is `acme-protocol`, your project is `my-project`, and your Virtual Environment slug is `a1b2c3`:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Ethereum:  https://virtual.mainnet.eu.rpc.tenderly.co/acme-protocol/my-project/a1b2c3
Arbitrum:  https://virtual.arbitrum.eu.rpc.tenderly.co/acme-protocol/my-project/a1b2c3
Optimism:  https://virtual.optimism.eu.rpc.tenderly.co/acme-protocol/my-project/a1b2c3
Base:      https://virtual.base.eu.rpc.tenderly.co/acme-protocol/my-project/a1b2c3
```

Each network endpoint follows the same pattern, so all URLs for a given Virtual Environment share the same org, project, and environment slug.

<Frame>
  <img alt="Virtual Environment detail page showing the Integrate Virtual RPC tab with Admin RPC URL, Public RPC toggle, Chain ID, and RPC endpoint setup steps" />
</Frame>

## Virtual Chain IDs

By default, each network in a Multichain Virtual Environment uses a Virtual Chain ID. It combines a `999xx` prefix with the real chain ID. This prevents accidental replay between your Virtual Environment and the real network: a transaction signed for your virtual mainnet will not validate on real Ethereum, and vice versa.

You can override this at creation time if your setup requires it, for example when a contract verifies a specific `chainid` value. Choose to use the real chain ID, or a custom one, on a per-network basis.

## Supported networks

Multichain Virtual Environments work on the same 100+ EVM networks the rest of Tenderly supports. See the [supported networks](/platform/supported-networks) page for the full list, including which products are available on which network.

Bridge protocol coverage is narrower than overall network coverage. See [Bridges](/virtual-environments/multichain/bridges#supported-networks) for which protocols are live on which chains.

## How it works with other Virtual Environment features

[State Sync](/virtual-environments/state-sync) is per-environment. Enabling State Sync applies to the entire Virtual Environment: it tracks live mainnet state for all attached networks until a Virtual Environment transaction modifies a storage slot.

[Network Mirror Mode](/virtual-environments/network-mirror-mode) is single-network. Combining Mirror Mode with a Multichain Virtual Environment isn't currently supported.

Each network has its own Admin RPC. Cheatcodes apply per network. `tenderly_setBalance` on the Ethereum leg will not affect balances on the Base leg.

Each network has its own block time. The Virtual Environment does not synchronize clocks across networks. You control time per network using the [Admin RPC](/virtual-environments/admin-rpc) time methods.

## Programmatic access

Everything you can do in the dashboard is also available through the [Tenderly REST API](/virtual-environments/rest-api) and the CLI. The `tenderly-virtual-testnet-setup` GitHub Action automates provisioning of parallel Virtual Environments for CI/CD pipelines, which is useful when you want a fresh multichain environment per pull request.

## Next steps

<CardGroup>
  <Card title="Quickstart" href="/virtual-environments/multichain/quickstart">
    Create a Multichain Virtual Environment, wire it into Foundry or Hardhat, fund accounts, and run your first cross-chain transaction.
  </Card>

  <Card title="Bridges" href="/virtual-environments/multichain/bridges">
    How the Bridge Module relays LayerZero, CCIP, CCTP and Across messages between networks, with dashboards and manual controls for failure testing.
  </Card>
</CardGroup>


# Multichain quickstart
Source: https://docs.tenderly.co/virtual-environments/multichain/quickstart

Create a Multichain Virtual Environment, wire it into Foundry or Hardhat, fund accounts, and run a cross-chain transaction end-to-end.

This tutorial takes you from zero to a cross-chain transaction on a Multichain Virtual Environment. By the end you will have a Virtual Environment that spans more than one network, with the Bridge Module relaying messages between them, your contracts deployed on each network, funded accounts on every chain, and a working cross-chain transaction visible in the unified dashboard timeline.

If you have not read the [overview](/virtual-environments/multichain/overview) yet, do that first. It explains what a Multichain Virtual Environment is, how the RPC URLs are structured, and what Virtual Chain IDs mean.

## Before you begin

You need:

* A Tenderly account with multichain capabilities enabled. If you do not see the option to add multiple networks during Virtual Environment creation, [contact us](https://tenderly.co/contact-us).
* A wallet private key you are willing to use in a test environment. Set it as `PRIVATE_KEY` in your shell.
* [Foundry](https://www.getfoundry.sh/) or [Hardhat](https://hardhat.org/) installed locally.

The rest of the tutorial assumes Ethereum mainnet, Arbitrum, Optimism, and Base, but the same flow works for any combination of supported networks.

## Run the tutorial

<Steps>
  ### Create the Multichain Virtual Environment

  In the Tenderly Dashboard, open **Virtual Environments** and start a new one. Ethereum mainnet is preselected by default. Add Arbitrum, Optimism, and Base from the network picker. Production chains appear first in the list, testnets at the bottom.

  For each network you can choose:

  * **Fork point.** Fork from the latest block (the default) or pick a specific block number, timestamp, or date.
  * **Chain ID.** Leave the default Virtual Chain ID unless you have a reason to override it. The [Virtual Chain IDs](/virtual-environments/multichain/overview#virtual-chain-ids) section explains the tradeoffs.

  Save the Virtual Environment. Take note of the slug Tenderly assigns it. The slug is part of every RPC URL you will use from here on.

  ### Enable the Bridge Module

  Open the Virtual Environment's settings and toggle **Bridging** to On. Once enabled, the Bridge Module watches for cross-chain events on every network in the Virtual Environment and relays them to the destination chain automatically. See [Bridges](/virtual-environments/multichain/bridges) for the protocols and networks it covers.

  ### Wire the RPCs into your project

  Each network in your Virtual Environment has a unique RPC URL with a predictable shape:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  https://virtual.<network>.<region>.rpc.tenderly.co/<org-slug>/<virtual-env-slug>
  ```

  Copy the RPC URLs from the Virtual Environment detail page and add them to your project configuration.

  <Tabs>
    <Tab title="Foundry">
      ```toml title="foundry.toml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      [rpc_endpoints]
      mainnet  = "https://virtual.mainnet.eu.rpc.tenderly.co/<org-slug>/<virtual-env-slug>"
      arbitrum = "https://virtual.arbitrum.eu.rpc.tenderly.co/<org-slug>/<virtual-env-slug>"
      optimism = "https://virtual.optimism.eu.rpc.tenderly.co/<org-slug>/<virtual-env-slug>"
      base     = "https://virtual.base.eu.rpc.tenderly.co/<org-slug>/<virtual-env-slug>"
      ```

      To verify a deployment against the Virtual Environment explorer, set `--verifier-url` to the same RPC. You will get a verified contract in the dashboard the moment the deploy completes.
    </Tab>

    <Tab title="Hardhat">
      ```typescript title="hardhat.config.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      const config: HardhatUserConfig = {
        networks: {
          tenderly_mainnet: {
            url: "https://virtual.mainnet.eu.rpc.tenderly.co/<org-slug>/<virtual-env-slug>",
            accounts: [process.env.PRIVATE_KEY],
          },
          tenderly_arbitrum: {
            url: "https://virtual.arbitrum.eu.rpc.tenderly.co/<org-slug>/<virtual-env-slug>",
            accounts: [process.env.PRIVATE_KEY],
          },
          tenderly_optimism: {
            url: "https://virtual.optimism.eu.rpc.tenderly.co/<org-slug>/<virtual-env-slug>",
            accounts: [process.env.PRIVATE_KEY],
          },
        },
      };
      ```
    </Tab>
  </Tabs>

  ### Fund accounts on every network

  Open the [Unlimited Faucet](/virtual-environments/unlimited-faucet) for your Virtual Environment and top up the address you will deploy from. Do this on each network, since balances are kept per network. Native currency is enough for the deploy itself. If your contracts move tokens, top those up too.

  ### Deploy and trigger a cross-chain transaction

  Deploy your contracts to each network you attached to the Virtual Environment.

  <Tabs>
    <Tab title="Foundry">
      ```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      forge create Counter \
        --private-key $PRIVATE_KEY \
        --rpc-url https://virtual.optimism.eu.rpc.tenderly.co/<org-slug>/<virtual-env-slug> \
        --broadcast \
        --verify \
        --verifier-url https://virtual.optimism.eu.rpc.tenderly.co/<org-slug>/<virtual-env-slug>
      ```
    </Tab>

    <Tab title="Hardhat">
      ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      npx hardhat run scripts/deploy.ts --network tenderly_mainnet
      ```
    </Tab>
  </Tabs>

  Once the contracts are deployed on each network, send a cross-chain transaction the way you normally would (for example a LayerZero `send` call). With the Bridge Module on, the destination-side delivery is posted immediately. Open the Virtual Environment dashboard and you should see both the source and destination transactions on the unified timeline.

  Use the [Bridges](/virtual-environments/multichain/bridges#transaction-views) Source/Destination filter to confirm the round-trip explicitly.
</Steps>

You now have a working Multichain Virtual Environment with cross-chain bridging.

## What to try next

Now that the tutorial works, here is how to apply the same setup to real workflows:

<CardGroup>
  <Card title="Automate deployments in CI" href="/virtual-environments/ci-cd/github-actions-foundry">
    Deploy to every network on every push, in parallel, using GitHub Actions. The CI/CD guides show the matrix workflow and the secrets you need.
  </Card>

  <Card title="Stage your frontend" href="/virtual-environments/dapp-ui/wagmi">
    Point your dApp at the Virtual Environment RPCs and give your team and reviewers an environment that exercises the full multichain flow.
  </Card>

  <Card title="Create Virtual Environments via API" href="/virtual-environments/develop/create-virtual-environment-via-api">
    The `multivnets` endpoint creates a Multichain Virtual Environment in one call. Useful for per-PR provisioning.
  </Card>

  <Card title="Test bridge failures" href="/virtual-environments/multichain/bridges#manual-bridge-controls">
    Manual bridge controls let you stage gas starvation, duplicate deliveries, modified payloads, and other failure modes deterministically.
  </Card>
</CardGroup>

## See also

* [Multichain Virtual Environments overview](/virtual-environments/multichain/overview)
* [Bridges](/virtual-environments/multichain/bridges)
* [Unlimited Faucet](/virtual-environments/unlimited-faucet)
* [Admin RPC](/virtual-environments/admin-rpc)


# Named RPC URLs
Source: https://docs.tenderly.co/virtual-environments/named-rpc-urls

Attach a fixed, human-readable name to a Virtual Environment's RPC URL so CI/CD and local configs never change across re-forks.

By default, a Virtual Environment's RPC URL contains a randomly generated identifier that changes every time you create or re-fork the environment. A Named RPC URL replaces that identifier with a name you choose, so the URL stays constant across re-forks. This removes the need to update CI secrets, `.env` files, or hardcoded RPC URLs every time you spin up a fresh environment for a pull request, a local dev loop, or a staging deployment.

## RPC URL format

<Frame>
  <img alt="Advanced section of the Create Virtual Environment dialog with the Named RPC URL toggle enabled and the Add named endpoint combobox open showing a Create option for a new name" />
</Frame>

Without a name, the identifier segment of the RPC URL is auto-generated, for example `https://virtual.mainnet.eu.rpc.tenderly.co/tenderly/demo/89e9b3-4bcd00`, and a new one is generated every time you re-fork.

With a name attached, the Public and Admin RPC URLs take this form instead:

| Endpoint   | URL format                                                                                   | Notes                                                                                                                                                                 |
| ---------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public RPC | `https://virtual.[NETWORK].[REGION].rpc.tenderly.co/[ACCOUNT]/[PROJECT]/[RPC_NAME]`          | Standard JSON-RPC only, safe to share with external testers or embed in a dapp UI.                                                                                    |
| Admin RPC  | `https://virtual.[NETWORK].[REGION].rpc.tenderly.co/[ACCOUNT]/[PROJECT]/[RPC_NAME]-[SUFFIX]` | `[SUFFIX]` is a random string Tenderly appends so the [cheatcode-enabled](/virtual-environments/admin-rpc) endpoint stays unguessable even though the name is public. |

`[REGION]` is `eu` or `us-east`, whichever you pick when assigning the name. `[RPC_NAME]` must be unique within your project. Once a name is attached, it, not the auto-generated identifier, is what stays fixed across re-forks.

## Assign a name when creating a Virtual Environment

1. Start [creating a Virtual Environment](/virtual-environments/quickstart) and expand the **Advanced** section.
2. Enable **Named RPC URL**.
3. In **Add named endpoint**, type a new name and select **Create `<name>`**, or pick an existing name from the list.
4. Click **Create Virtual Environment**.

The Admin and Public RPC URLs for the new environment are available on its **Home** page, under **Integrate Virtual RPC**.

<Frame>
  <img alt="Integrate Virtual RPC panel showing the resolved Admin RPC URL ending in the name plus a random suffix, the Public RPC URL ending in just the name, and the chain id" />
</Frame>

## Change or remove a name after creation

Open the Virtual Environment's **Settings** page. The **Named RPC URL** section there mirrors the one in the creation dialog:

* To reassign the environment to a different name, open the name picker and select another entry, or type a new name and select **Create `<name>`**.
* To detach the name from this environment, disable **Named RPC URL** and save. The name itself is not deleted, it just becomes free to attach elsewhere.

## A name maps to one environment at a time

Attaching a name to a Virtual Environment is a one-to-one relationship. In the name picker, existing names that are already assigned elsewhere in the project are labeled **In use on another environment**. Selecting one of them attaches it to the current environment and detaches it from the environment that previously held it, so that environment's named RPC URL stops resolving there and instead routes to the current environment.

This makes swapping the target of a fixed RPC URL a single action: create the replacement environment, assign it the same name as the one you're retiring, and every script, CI pipeline, or dapp config pointed at that URL now resolves to the new environment without any changes on their end.

## Set a name via the REST API

Pass `rpcName` when creating an environment through the environment creation endpoint:

```bash title="environment-create-named.sh" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl --request POST \
  --url https://api.tenderly.co/api/v1/account/me/project/project/environments \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Access-Key: ${TENDERLY_ACCESS_KEY}" \
  --data '{
    "displayName": "My Staging Environment",
    "rpcName": "my-staging-rpc",
    "networkConfigs": [
      {
        "networkId": "1",
        "chainConfigOverrides": { "chainId": "1" },
        "blockNumber": "latest",
        "region": "eu",
        "explorerConfig": { "enabled": false, "contractVerificationVisibility": "bytecode" }
      }
    ]
  }'
```

Read the environment back through the [REST API reference](/virtual-environments/rest-api#get-an-environment) to get the resolved RPC URLs:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl --request GET \
  --url https://api.tenderly.co/api/public/v1/account/me/project/project/environments/{environmentId} \
  --header "X-Access-Key: ${TENDERLY_ACCESS_KEY}"
```

The `active_instance.vnets[].rpcs` array contains the named Admin and Public RPC URLs:

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "rpcs": [
    { "name": "Admin RPC", "url": "https://virtual.mainnet.eu.rpc.tenderly.co/tenderly/project/my-staging-rpc-800896" },
    { "name": "Public RPC", "url": "https://virtual.mainnet.eu.rpc.tenderly.co/tenderly/project/my-staging-rpc" }
  ]
}
```

## See also

* [Quickstart](/virtual-environments/quickstart) for the full Virtual Environment creation flow.
* [Admin RPC](/virtual-environments/admin-rpc) for the cheatcodes available on the Admin RPC.
* [CI/CD with GitHub Actions](/virtual-environments/ci-cd/github-actions-foundry) for pipelines that create and tear down environments per pull request.


# Backtest a token position by replaying historical blocks
Source: https://docs.tenderly.co/virtual-environments/network-mirror-backtest

Fork at a past block, take a position in a yield-bearing token, and replay real mainnet history with Network Mirror Mode to measure realized yield.

[Network Mirror Mode](/virtual-environments/network-mirror-mode) replays the parent network's real blocks onto a Virtual Environment. When the Virtual Environment is forked at a **past block**, that replay covers real history: every mainnet transaction from the fork point onward re-executes on your private copy, in order. This how-to uses that replay to backtest a position: fork at a past date, acquire a yield-bearing token, replay history forward, and read the yield the position actually earned over the period.

The worked example is the Franklin OnChain U.S. Government Money Fund token (`BENJI`) on Ethereum Mainnet. The same workflow applies to any yield-bearing token.

<Note>
  Network Mirror Mode is available on the paid plan. To enable it for your account, [contact our sales team](https://tenderly.co/contact-us).
</Note>

<Steps>
  ### Create the Virtual Environment at a past block

  Create a new Virtual Environment in your project. In the creation form, set:

  * **Networks**: Ethereum Mainnet
  * **Network mode**: **Network mirror** (full block-by-block mainnet replay)
  * Uncheck **Start from latest block**, set the reference point type to **Block Number**, and enter the block number for the date the position starts. The **Fork from block** column shows the block each selected network forks at.

  <Frame>
    <img alt="Create Virtual Environment form with Ethereum Mainnet, Network mirror mode, and a past fork block number entered" />
  </Frame>

  Create the Virtual Environment, open it, and go to the **Network sync** tab. The **Network sync status** panel shows the mainnet head, the Virtual Environment head (sitting at your fork block), and how many blocks behind mainnet the Virtual Environment is. That gap is the stretch of history the replay will cover.

  <Frame>
    <img alt="Network sync status panel showing Mainnet head 25,638,816, Virtual Environment head 25,634,161, and 4,655 blocks behind mainnet" />
  </Frame>

  ### Fund the wallet and take the position

  Real network state as of the fork block is live on the Virtual Environment, so the fund's token contract and any pools it trades in are already there.

  [Admin RPC cheatcodes are disabled while sync is active](/virtual-environments/network-mirror-mode#cheatcode-behavior), so do all setup before starting the replay. Confirm sync is paused: the status panel shows **Start auto-sync** rather than a running timer.

  1. Use **RPC Cheatcodes** in the top right to fund the investor wallet: [`tenderly_setBalance`](/virtual-environments/admin-rpc#tenderly_setbalance) for gas ETH and [`tenderly_setErc20Balance`](/virtual-environments/admin-rpc#tenderly_seterc20balance) for the stablecoin to invest.
  2. Acquire the fund token the way an investor would: swap for it, or subscribe through the fund's onchain flow. The wallet now holds the position as of the fork date.

  ### Track the position balance

  Still on the **Network sync** tab, switch the lower panel from **Sync operations** to **State drift**, then open the **Balance** sub-tab.

  Click **Track balance** and fill in the **Track wallet balance** dialog:

  * **Wallet**: the investor wallet
  * **Token**: the fund token (`BENJI`: `0x3DDc84940Ab509C11B20B76B466933f40b750dc9`)

  A card appears showing the wallet, the token, and a **Diff** counter. It reads "No balance drift data yet" until blocks replay.

  <Frame>
    <img alt="Track wallet balance dialog with a wallet address and the BENJI token on Mainnet selected" />
  </Frame>

  ### Replay history forward

  In the **Network sync status** panel:

  1. Open the speed dropdown next to the sync button and select **4×** (one block every 3 seconds; see the [speed settings](/virtual-environments/network-mirror-mode#time-controls)).
  2. Press **Start auto-sync**.

  The Virtual Environment replays real mainnet blocks onto the fork. The Virtual Environment head climbs, the blocks-behind counter shrinks, and every real transaction from the period re-executes in order, including the fund's onchain yield distributions.

  On the **Balance** card, each yield payout that replays steps the tracked balance up on the chart. Let the replay run until it covers the period you want to measure, then press **Stop auto-sync**.

  <Frame>
    <img alt="State drift Balance card showing a flat BENJI balance line stepping up sharply at block 25,634,222" />
  </Frame>

  ### Read the realized yield

  The **Balance** card now holds the result:

  * The chart plots the tracked balance at each replayed block. Every distribution appears as a step up; the difference between the balance at the start and at the end of the replayed window is the realized yield for the period. For a fund with a \$1.00 NAV, that is the yield in dollars.
  * Hover the chart to read the balance at any block along the way.
  * The **Diff** counter shows how far the tracked balance has diverged from mainnet at the same block height. It stays `0.000` while the replay re-executes mainnet history unchanged, and moves when transactions you sent on the Virtual Environment change the position relative to mainnet.

  To annualize, with gain *G* on principal *P* over *D* days of replayed history: `APY ≈ (1 + G/P)^(365/D) − 1`.

  ### Compare scenarios (optional)

  * **Rewind** unwinds the last synced blocks so you can re-run a stretch of history.
  * **Sync block** advances exactly one block, which is useful for landing on a single yield distribution and reading it in isolation.
  * Create a second Virtual Environment at a different fork block or with a different position size to compare outcomes side by side.
</Steps>

## Practical notes

* **Yield appears when the fund's real yield transactions replay.** A rebasing token's held balance grows automatically. For a fund that distributes to registered holders, track a holder position so the distributions land on it.
* **Cheatcodes pause with sync.** Do all setup (funding, entering the position) while sync is paused, then start the replay.
* **One network per environment.** Network Mirror Mode runs against a single parent network; it isn't combined with [multichain Virtual Environments](/virtual-environments/multichain/overview).
* **Replay is bounded by real blocks.** Covering a long period means replaying many blocks. To capture yield quickly, fork shortly before a known distribution, or replay a representative window and annualize.

## Next steps

* Track a storage slot instead of a balance (**State drift → State → Track variable**) to follow any contract variable over the replayed period.
* Point a dapp's RPC at the Virtual Environment to drive the same replay from your own UI. See [Stage dapps](/virtual-environments/ci-cd/stage-dapps).
* Read the [Network Mirror Mode](/virtual-environments/network-mirror-mode) concept page for sync mechanics, time controls, and cheatcode behavior.


# Network Mirror Mode
Source: https://docs.tenderly.co/virtual-environments/network-mirror-mode

Run a Virtual Environment that stays block-for-block in sync with a live network, with a visible mempool, time controls, and a state-drift lens.

Network Mirror Mode keeps a Virtual Environment continuously aligned with its parent network. New mainnet blocks are absorbed into the Virtual Environment as they're produced, and a UI-visible mempool collects any transactions you submit. Your transactions are prepended to the next synced block in the order they arrive.

<Note>
  Network Mirror Mode is available on the paid plan. To enable it for your account, [contact our sales team](https://tenderly.co/contact-us).
</Note>

<Frame>
  <img alt="Network Sync page showing sync status counters, block-lag chart, time controls, and a sync-operations table with tenderly_startSync and tenderly_stopSync entries" />
</Frame>

## When to use it

Use Network Mirror Mode when you need to evaluate behavior against **live network conditions** rather than a frozen fork:

* Test how your contracts behave against today's oracle prices, pool reserves, or governance state.
* Stage a transaction and control when it executes relative to the next synced block.
* Pause the live network at a specific block to inspect state, then continue replaying.
* Compare your Virtual Environment's storage and balances against mainnet baselines over time.
* Fork at a past block and replay real history forward, for example to [backtest a token position's realized yield](/virtual-environments/network-mirror-backtest).

If you need a frozen point-in-time fork, use a standard Virtual Environment. If you need real-time state without mempool semantics or block-for-block ticking, use [State Sync](/virtual-environments/state-sync).

## How sync works

A mainnet tick produces a Virtual Environment tick within roughly 12 seconds. Each tick brings in the next block's transactions and applies them on top of your Virtual Environment's current state.

Transactions you submit sit in the Virtual Environment's mempool until the next sync tick, at which point they're **prepended to the synced block in FIFO order**. Your transactions execute first; the synced mainnet transactions execute after them, against the resulting state.

A "live" indicator shows whether the Virtual Environment is keeping up:

| State       | Meaning                                 |
| ----------- | --------------------------------------- |
| Live        | Tick active, lag of one block or less   |
| Catching up | Tick active, lag greater than one block |
| Paused      | Tick loop stopped                       |

<Frame>
  <img alt="Network sync status counters showing Mainnet head 25,644,372, Virtual Environment head 25,634,318, and 10,054 blocks behind mainnet in orange" />
</Frame>

## Time controls

The time-control strip lets you move the Virtual Environment's clock relative to mainnet. Each control maps directly to an RPC call you can also invoke from your own code:

| Control | RPC call                                                                     | Behavior                                   |
| ------- | ---------------------------------------------------------------------------- | ------------------------------------------ |
| Rewind  | [`tenderly_revertSync`](/virtual-environments/admin-rpc#tenderly_revertsync) | Unwinds N blocks (default 10)              |
| Play    | [`tenderly_startSync`](/virtual-environments/admin-rpc#tenderly_startsync)   | Resumes continuous sync from current block |
| Pause   | [`tenderly_stopSync`](/virtual-environments/admin-rpc#tenderly_stopsync)     | Stops the tick loop                        |
| Step    | [`tenderly_syncNext`](/virtual-environments/admin-rpc#tenderly_syncnext)     | Syncs the next block only                  |

The speed picker (`0.5×`, `1×`, `2×`, `4×`) sets the tick delay between sync calls (`24s`, `12s`, `6s`, `3s` per block respectively); `1×` matches mainnet pace.

<Frame>
  <img alt="Rewind, Sync block, and Start auto-sync buttons with the speed menu open showing 0.5x, 1x mainnet pace, 2x, and 4x options" />
</Frame>

To check sync progress programmatically, use [`tenderly_getSyncStatus`](/virtual-environments/admin-rpc#tenderly_getsyncstatus).

## State drift lens

The State Drift lens shows where your Virtual Environment has diverged from mainnet. Useful for finding the contract or wallet your test actually moved.

Two sub-views share one surface:

| Sub-view | What it shows                                 |
| -------- | --------------------------------------------- |
| State    | Storage-slot drift per contract               |
| Balance  | Wallet and token-balance delta versus mainnet |

The lens is scoped to the contracts and wallets you're watching plus any contracts the current session has touched.

<Frame>
  <img alt="State drift view inside Network Sync, showing the State and Balance tabs and the Track variable / Track balance buttons" />
</Frame>

## Block-context fidelity

Network Mirror Mode commits to one-to-one parity with the parent network on the dimensions that most often affect contract behavior:

* **Block-context alignment**: `block.timestamp`, `baseFee`, `coinbase`, and `prevrandao` reflect mainnet values.
* **Gas-market parity**: current mainnet gas pricing applies to transactions you submit.
* **Sub-tick latency**: a mainnet tick produces a Virtual Environment tick within roughly 12 seconds.

## Cheatcode behavior

Because Network Mirror Mode is continuously importing real blocks, some Admin RPC cheatcodes behave differently than on a standard Virtual Environment.

| Behavior                                                                                                | When the Virtual Environment is in Network Mirror Mode                    |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Admin RPC cheatcodes (`tenderly_setBalance`, `tenderly_setErc20Balance`, `tenderly_setStorageAt`, etc.) | **Disabled while live sync is active.** Pause sync to use them.           |
| Solidity precompile cheatcodes                                                                          | Work, but execute on the **next synced block boundary**, not immediately. |
| `tenderly_sendBlock`                                                                                    | Disabled while sync is active.                                            |
| Initial empty block at Virtual Environment creation                                                     | Skipped.                                                                  |
| Default 10 funded accounts at Virtual Environment creation                                              | Not created.                                                              |

See the [Admin RPC reference](/virtual-environments/admin-rpc) for the full cheatcode list.

## Mode comparison

|                                      | Standard Virtual Environment   | [State Sync](/virtual-environments/state-sync) | Network Mirror Mode                    |
| ------------------------------------ | ------------------------------ | ---------------------------------------------- | -------------------------------------- |
| Initial state from parent network    | Yes (snapshot)                 | Yes                                            | Yes                                    |
| Tracks new parent-network blocks     | No                             | Per-slot, on read                              | Yes, block-for-block                   |
| User-visible mempool                 | No                             | No                                             | Yes                                    |
| Block-context matches parent network | No (independent clock)         | No                                             | Yes                                    |
| Cheatcodes work over Admin RPC       | Yes                            | Yes                                            | Only when sync is paused               |
| Time controls (rewind / play / step) | No                             | No                                             | Yes                                    |
| State drift lens                     | No                             | No                                             | Yes                                    |
| Good for                             | Frozen-point integration tests | Latest oracle values, pool state               | Live network rehearsals, mempool tests |

## Known limitations

* **Single-network only.** Network Mirror Mode applies per Virtual Environment; combining it with multichain Virtual Environments isn't currently supported.

## See also

* [Backtest a token position by replaying historical blocks](/virtual-environments/network-mirror-backtest)
* [Admin RPC: sync methods](/virtual-environments/admin-rpc#tenderly_startsync)
* [State Sync](/virtual-environments/state-sync)
* [Multichain Virtual Environments](/virtual-environments/multichain/overview)


# Virtual Environments
Source: https://docs.tenderly.co/virtual-environments/overview

Fork a live network into a private, production-like testnet alternative for dapp development, CI/CD, and staging, over JSON-RPC and a visual dashboard.

Virtual Environments are private blockchain environments that fork a live network and behave like a mainnet you control. They give you the realism of a production chain (oracle prices, live pools, governance state) with none of the cost or risk. You interact with them through the same JSON-RPC your tools already speak, plus an enriched Admin RPC for cheatcodes, and a visual dashboard with a block explorer.

<Note>
  Virtual Environments are available on the paid plan. To enable them for your account, [contact our sales team](https://tenderly.co/contact-us) to schedule a call and discuss upgrading your plan.
</Note>

<Frame>
  <img alt="Virtual Environment Home view showing the Integrate Virtual RPC section with Admin RPC and Public RPC endpoints, setup steps, Network Mirror, Bridge, and Contracts cards, and the attached network with chain IDs and block numbers" />
</Frame>

## What you can build with them

* **A local node replacement.** Code, test, and debug every part of your dapp (smart contracts, dapp UI, backend, indexing layer) against a network that mirrors mainnet state.
* **CI/CD infrastructure.** Provision a fresh Virtual Environment per pull request, deploy your contracts, run your tests, and tear it down. The [GitHub Actions guides](/virtual-environments/ci-cd/github-actions-foundry) cover the pattern.
* **Staging and demo environments.** Run the full dapp against a forked mainnet for manual QA, community testing, contract audits, or sales demos. Reviewers see a real block explorer; you don't move real funds.
* **Cross-chain testing.** Attach multiple networks to one Virtual Environment and exercise bridge flows end-to-end. The [Multichain Quickstart](/virtual-environments/multichain/quickstart) walks through the setup.

## How do Virtual Environments compare to public testnets?

Public testnets like Sepolia and Holesky run their own isolated chain state, so they lack mainnet liquidity, live oracle prices, and the deployed protocols your dapp depends on. A Virtual Environment forks mainnet (or any of 100+ networks) instead, so you test against real production state, with faucet funds that never run out and full control over account balances, block number, and time. Unlike a public testnet, it stays private to your team and can be created and torn down per pull request.

## Start here

<CardGroup>
  <Card title="Quickstart" href="/virtual-environments/quickstart">
    Launch your first Virtual Environment, fund an account, and send a transaction.
  </Card>

  <Card title="Multichain Quickstart" href="/virtual-environments/multichain/quickstart">
    Set up a Virtual Environment that spans multiple networks and run a cross-chain transaction with automatic bridge relay.
  </Card>
</CardGroup>

## Network sync modes

Every Virtual Environment has a network sync mode that controls how it relates to its parent network after creation:

* **Static** (default): The Virtual Environment stays at the forked block head with no live updates from the parent network. State changes only through your own transactions and cheatcodes.
* **State Only Sync**: Storage slots keep tracking live parent-network values until your Virtual Environment writes to them. See [State Sync](/virtual-environments/state-sync).
* **Network Mirror**: A full block-by-block replay of the parent network onto your Virtual Environment, with a visible mempool and time controls. See [Network Mirror Mode](/virtual-environments/network-mirror-mode).

The sync mode is fixed at creation and cannot be changed afterwards, from the dashboard or the API. To use a different mode, create a new Virtual Environment.

## The building blocks

These pages explain what each piece of a Virtual Environment does and how it relates to the others. Read them before you need to debug something.

<CardGroup>
  <Card title="Explorer" href="/virtual-environments/explorer">
    Inspect transactions, contracts, wallets, and RPC calls on your Virtual Environment through a familiar block-explorer UI.
  </Card>

  <Card title="Unlimited Faucet" href="/virtual-environments/unlimited-faucet">
    Top up native currency or ERC-20 balances on any account, with no real funds required.
  </Card>

  <Card title="State Sync" href="/virtual-environments/state-sync">
    Keep storage slots tracking live mainnet values until your Virtual Environment writes to them.
  </Card>

  <Card title="Network Mirror Mode" href="/virtual-environments/network-mirror-mode">
    Stay block-for-block aligned with the parent network, with a visible mempool and time controls.
  </Card>

  <Card title="Named RPC URLs" href="/virtual-environments/named-rpc-urls">
    Attach a fixed, human-readable name to an environment's RPC URL so it survives re-forks.
  </Card>

  <Card title="Multichain Virtual Environments" href="/virtual-environments/multichain/overview">
    One Virtual Environment, multiple networks, shared identity, unified timeline.
  </Card>

  <Card title="Bridges" href="/virtual-environments/multichain/bridges">
    Automatic relay for LayerZero, Chainlink CCIP, and Across between networks in a Multichain Virtual Environment.
  </Card>
</CardGroup>

## How you interact with a Virtual Environment

You drive a Virtual Environment through four surfaces:

* The **Tenderly Dashboard**, where you create the Virtual Environment, browse transactions, fund accounts, simulate transactions against the environment's current state, and configure settings.
* The **Public RPC**, a standard JSON-RPC endpoint that supports the methods any dapp or library already calls. Use this for your dapp UI, backend, and anything you would expose to external testers.
* The **Admin RPC**, an enriched JSON-RPC endpoint that adds cheatcodes for setting balances, overriding storage, fast-forwarding time, deploying arbitrary bytecode, and synchronising with the live network. Use this from your dev tooling and tests, not from anything externally accessible. The full set of cheatcodes is documented in the [Admin RPC reference](/virtual-environments/admin-rpc).
* The **REST API**, for creating, forking, and deleting Virtual Environments from scripts and CI pipelines. See the [REST API reference](/virtual-environments/rest-api); the [GitHub Actions guides](/virtual-environments/ci-cd/github-actions-foundry) wrap it for pull-request workflows.

<Warning>
  When you share a Virtual Environment with external testers or expose it through a dapp UI, hand out the Public RPC, not the Admin RPC. The Admin RPC lets the caller mutate balances, storage, time, and other network state in ways that can break your tests.
</Warning>

## Common tasks

<CardGroup>
  <Card title="Add to a wallet" href="/virtual-environments/interact/add-to-wallet">
    Connect MetaMask or another wallet to your Virtual Environment.
  </Card>

  <Card title="Connect your tooling" href="/virtual-environments/integrations">
    Point Foundry, Hardhat, ethers, viem, or your dapp UI at your Virtual Environment RPC.
  </Card>

  <Card title="Deploy and verify contracts" href="/virtual-environments/develop/deploy-contracts">
    Deploy with Foundry or Hardhat, with automatic contract verification.
  </Card>

  <Card title="Simulate transactions" href="/virtual-environments/interact/simulate-transactions">
    Dry-run transactions against the Virtual Environment's current state before sending them.
  </Card>

  <Card title="Fork a Virtual Environment" href="/virtual-environments/develop/fork-testnet">
    Branch an existing Virtual Environment into a new one at its current state.
  </Card>

  <Card title="Revert state" href="/virtual-environments/develop/revert-state">
    Take snapshots and roll the Virtual Environment back to them.
  </Card>
</CardGroup>

## Supported networks

Virtual Environments work on 100+ EVM networks. See [supported networks](/platform/supported-networks) for the full list.

## See also

* [Quickstart](/virtual-environments/quickstart) for your first Virtual Environment, end-to-end.
* [Stage contracts](/virtual-environments/ci-cd/stage-contracts) to share a Virtual Environment with your team.
* [Admin RPC](/virtual-environments/admin-rpc) and [REST API](/virtual-environments/rest-api) for reference material.
* [Solidity Cheatcodes](/virtual-environments/precompiles) for manipulating state from inside a transaction via the Virtual Environment precompile.


# Solidity Cheatcodes
Source: https://docs.tenderly.co/virtual-environments/precompiles

IVnetPrecompile interface reference for the Solidity-level cheatcodes available on every Virtual Environment at 0xc100000000000000000000000000000000000000.

Every Virtual Environment exposes a precompile contract at `0xc100000000000000000000000000000000000000`. Calling functions on this precompile from inside a transaction lets your contracts manipulate on-chain state directly, storage slots, ETH balances, ERC-20 token balances, nonces, and event logs, without impersonating accounts or deploying helper proxies.

These cheatcodes complement the [Admin RPC methods](/virtual-environments/admin-rpc). The Admin RPC methods manipulate state from outside a transaction (via JSON-RPC). The precompile manipulates state from inside a transaction (via Solidity call). Use the precompile when your setup needs to stay atomic, be replayable from a tx hash, or run in a loop over many slots.

## Interface

Add this file to your project as `IVnetPrecompile.sol`:

```solidity title="IVnetPrecompile.sol" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IVnetPrecompile {
    function setStorageAt(address target, bytes32 slot, bytes32 value) external returns (bool);
    function setBalance(address[] calldata addresses, uint256 balance) external returns (bool);
    function getStorageAt(address target, bytes32 slot) external view returns (bytes32);
    function addBalance(address[] calldata addresses, uint256 amount) external returns (bool);
    function setNonce(address target, uint256 value) external returns (bool);
    function setErc20Balance(address target, address[] calldata addresses, uint256 amount) external returns (bool);
    function addErc20Balance(address target, address[] calldata addresses, uint256 amount) external returns (bool);
    function setMaxErc20Balance(address target, address account) external returns (bool);

    function emitEvent(address target, bytes calldata data) external returns (bool);
    function emitEvent(address target, bytes32 topic1) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes calldata data) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes calldata data) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3, bytes calldata data) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3, bytes32 topic4) external returns (bool);
    function emitEvent(address target, bytes32 topic1, bytes32 topic2, bytes32 topic3, bytes32 topic4, bytes calldata data) external returns (bool);

    event SetStorageAtEvent(address target, bytes32 slot, bytes32 value);
    event SetBalanceEvent(address[] addresses, uint256 balance);
    event AddBalanceEvent(address[] addresses, uint256 amount);
    event SetNonceEvent(address target, uint256 value);
    event SetErc20BalanceEvent(address target, address[] addresses, uint256 amount);
    event AddErc20BalanceEvent(address target, address[] addresses, uint256 amount);
    event SetMaxErc20BalanceEvent(address target, address account);
}
```

Reference it in your contract at the fixed address:

```solidity theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
IVnetPrecompile constant VNET = IVnetPrecompile(0xc100000000000000000000000000000000000000);
```

## Functions

### Storage

| Function       | Parameters                                        | Returns   | Description                                    |
| -------------- | ------------------------------------------------- | --------- | ---------------------------------------------- |
| `setStorageAt` | `address target`, `bytes32 slot`, `bytes32 value` | `bool`    | Writes `value` to `slot` on `target`.          |
| `getStorageAt` | `address target`, `bytes32 slot`                  | `bytes32` | Reads the current value of `slot` on `target`. |

```solidity theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
VNET.setStorageAt(tokenContract, balanceSlot, bytes32(uint256(1000e18)));
bytes32 val = VNET.getStorageAt(tokenContract, balanceSlot);
```

### Balance

| Function     | Parameters                               | Returns | Description                                                               |
| ------------ | ---------------------------------------- | ------- | ------------------------------------------------------------------------- |
| `setBalance` | `address[] addresses`, `uint256 balance` | `bool`  | Sets the ETH balance of every address in `addresses` to an exact value.   |
| `addBalance` | `address[] addresses`, `uint256 amount`  | `bool`  | Adds `amount` to the current ETH balance of every address in `addresses`. |

```solidity theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
address[] memory accounts = new address[](2);
accounts[0] = alice;
accounts[1] = bob;
VNET.setBalance(accounts, 10 ether);
VNET.addBalance(accounts, 2 ether);
```

### ERC-20 balances

| Function             | Parameters                                                | Returns | Description                                                                                   |
| -------------------- | --------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `setErc20Balance`    | `address target`, `address[] addresses`, `uint256 amount` | `bool`  | Sets the balance of every address in `addresses` to `amount` on the ERC-20 token at `target`. |
| `addErc20Balance`    | `address target`, `address[] addresses`, `uint256 amount` | `bool`  | Adds `amount` to the current token balance of every address in `addresses`.                   |
| `setMaxErc20Balance` | `address target`, `address account`                       | `bool`  | Sets the token balance of `account` to the maximum value (`2^256 - 1`).                       |

The precompile locates the token's balance storage slot automatically, so no slot input is required. Standard mapping layouts resolve directly and are cached after the first holder; non-standard layouts are discovered by probing the token's `balanceOf` execution.

```solidity theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
address[] memory holders = new address[](2);
holders[0] = alice;
holders[1] = bob;
VNET.setErc20Balance(USDC, holders, 1_000_000e6);
VNET.addErc20Balance(USDC, holders, 500e6);
VNET.setMaxErc20Balance(USDC, alice);
```

<Note>
  Tokens that pack extra flags into the balance storage slot report `balanceOf` accordingly. For example, USDC reserves the top bit of the slot, so after `setMaxErc20Balance` its `balanceOf` returns `2^255 - 1`.
</Note>

### Nonce

| Function   | Parameters                        | Returns | Description                             |
| ---------- | --------------------------------- | ------- | --------------------------------------- |
| `setNonce` | `address target`, `uint256 value` | `bool`  | Sets the transaction count of `target`. |

```solidity theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
VNET.setNonce(account, 42);
```

### Events

`emitEvent` fires a log whose `address` field is `target`, not the calling contract. Downstream consumers (indexers, subgraphs, webhooks) treat the log as a real emission from `target`.

Nine overloads cover zero to four indexed topics with an optional unindexed data payload:

| Overload                                  | Topics | Data |
| ----------------------------------------- | ------ | ---- |
| `emitEvent(target, data)`                 | 0      | ✓    |
| `emitEvent(target, t1)`                   | 1      | ,    |
| `emitEvent(target, t1, data)`             | 1      | ✓    |
| `emitEvent(target, t1, t2)`               | 2      | ,    |
| `emitEvent(target, t1, t2, data)`         | 2      | ✓    |
| `emitEvent(target, t1, t2, t3)`           | 3      | ,    |
| `emitEvent(target, t1, t2, t3, data)`     | 3      | ✓    |
| `emitEvent(target, t1, t2, t3, t4)`       | 4      | ,    |
| `emitEvent(target, t1, t2, t3, t4, data)` | 4      | ✓    |

`topic1` is typically `keccak256("EventName(type,type,...)")`. Example, spoof a USDC `Transfer`:

```solidity theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
VNET.emitEvent(
    USDC,
    keccak256("Transfer(address,address,uint256)"),
    bytes32(uint256(uint160(from))),
    bytes32(uint256(uint160(to))),
    abi.encode(amount)
);
```

### Cheatcode events

Every state-changing cheatcode emits a corresponding event from the precompile address (`0xc100000000000000000000000000000000000000`):

| Cheatcode            | Event                                                                       |
| -------------------- | --------------------------------------------------------------------------- |
| `setStorageAt`       | `SetStorageAtEvent(address target, bytes32 slot, bytes32 value)`            |
| `setBalance`         | `SetBalanceEvent(address[] addresses, uint256 balance)`                     |
| `addBalance`         | `AddBalanceEvent(address[] addresses, uint256 amount)`                      |
| `setNonce`           | `SetNonceEvent(address target, uint256 value)`                              |
| `setErc20Balance`    | `SetErc20BalanceEvent(address target, address[] addresses, uint256 amount)` |
| `addErc20Balance`    | `AddErc20BalanceEvent(address target, address[] addresses, uint256 amount)` |
| `setMaxErc20Balance` | `SetMaxErc20BalanceEvent(address target, address account)`                  |

When inspecting a receipt for a log spoofed via `emitEvent`, filter `logs[]` by the target address to ignore the precompile's own entries.

## Known limitations

* **Base-based Virtual Environments.** Solidity cheatcodes are not available on Base.
* **Arbitrum-based Virtual Environments.** Cheatcode calls made through `eth_call` do not work due to Arbitrum internals. Transactions, gas estimates, and simulations work as expected.

## See also

* [Admin RPC](/virtual-environments/admin-rpc), the equivalent JSON-RPC methods for state manipulation from outside a transaction.
* [Foundry cheatcode tutorial](/virtual-environments/develop/solidity-cheatcodes), end-to-end walkthrough deploying a reusable cheatcode playground.


# Virtual Environment quickstart
Source: https://docs.tenderly.co/virtual-environments/quickstart

Learn how to quickly spin up a Virtual Environment and start interacting with it.

Follow this guide to learn how to spin up a Virtual Environment and start interacting with it.

[Watch on Loom →](https://www.loom.com/embed/4275dd13f6c8443ea851708ced61fd7e?sid=7007b253-7dfb-4ed8-9641-f54615b1354e)

<Steps>
  ### Configure your Virtual Environment

  From the Dashboard, go to **Virtual Environments** and click **Create Virtual Environment**. Fill in the settings below:

  **Parent network and name**: Choose which network you want to fork from the [supported networks](/platform/supported-networks) and give it a unique name (e.g., **Virtual Mainnet**).

  **Chain ID**: Specify a custom value such as **`73571`** or use the parent network's original chain ID. It's recommended to set a [unique chain ID](/troubleshooting/virtual-environments#unique-chain-id) to prevent transaction replay attacks, and avoid issues when adding the Virtual Environment to wallets.

  **Public Explorer**: Leave disabled or enable to allow public transaction viewing. If enabled, set the [contract verification visibility](/virtual-environments/explorer#contract-visibility-in-public-explorer) option to control whether or not smart contracts' code is visible publicly.

  **State sync**: Activate to keep your Virtual Environment updated in real-time with the parent network. Learn more about [how state sync works](/virtual-environments/state-sync).

  **Named RPC URL**: Optionally attach a fixed name to the RPC URL, so it stays the same across re-forks instead of changing every time. See [Named RPC URLs](/virtual-environments/named-rpc-urls).

  Click **Create**.

  ### Add your Virtual Environment to Metamask

  Access your Virtual Environment and click **Add to Wallet** to add the Virtual Environment as a chain in Metamask. Follow Metamask's instructions to change the network. Once confirmed, you can send and receive transactions on your Virtual Environment through Metamask.

  [Follow this tutorial](/virtual-environments/interact/add-to-wallet) for more guidance.

  ### Fund accounts

  Every Virtual Environment has an [unlimited faucet](/virtual-environments/unlimited-faucet) that allows you to top up or set a new balance for any account on the Virtual Environment instantly.

  **From the Dashboard**

  * Navigate to **Faucet**
  * Input your address (`0xBd8DaA414Fda8a8A129F7035e7496759C5aF8570`) and the amount you wish to add (e.g., 1000) in ETH (not wei).
  * Click **Fund**

    <img alt="" />

  **Using RPC**

  Copy the Virtual Environment RPC link and call the `tenderly_setBalance` method to set a new balance specified in **wei** in hexadecimal form.

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  curl $TENDERLY_VIRTUAL_TESTNET_RPC \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
      "jsonrpc": "2.0",
      "method": "tenderly_setBalance",
      "params": [["0xE58b9ee93700A616b50509C8292977FA7a0f8ce1"], "0xDE0B6B3A7640000"],
      "id": "1234"
  }'
  ```
</Steps>

## Next steps

* [Send transactions](/virtual-environments/interact/send-transactions): Start sending transactions on your Virtual Environments
* [Simulate transactions](/virtual-environments/interact/simulate-transactions): Run transaction simulations from the Dashboard or via RPC
* [Deploy smart contracts](/virtual-environments/develop/deploy-contracts): Start deploying and monitoring smart contracts on your Virtual Environment
* [Virtual Environments API](/api-reference): Create and manage Virtual Environments via REST API
* [Use cases](/virtual-environments/overview#use-cases): Explore further use-cases of Virtual Environments
* [FAQ](/troubleshooting/virtual-environments): Get answers to frequently asked questions about Virtual Environments


# REST API
Source: https://docs.tenderly.co/virtual-environments/rest-api

Reference for the Tenderly REST API endpoints that create and manage Virtual Environments, including single-network and multi-network environments.

The Tenderly REST API exposes endpoints for creating, listing, and managing Virtual Environments. For a walkthrough of how to call them from a script, see [Create Virtual Environments via API](/virtual-environments/develop/create-virtual-environment-via-api). For the complete API surface, see the [API Reference](/api-reference).

All environment endpoints use the base URL:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://api.tenderly.co/api/public/v1/account/{accountSlug}/project/{projectSlug}
```

## Authentication

All requests require an `X-Access-Key` header. Generate a key from **Account Settings → Authorization** in the Tenderly Dashboard. See [API tokens](/platform/account/projects/api-tokens).

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
X-Access-Key: <your-access-key>
```

## Create an environment

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
POST /environments
```

Creates a new environment with one or more networks. Both single-network and multi-network environments use this endpoint, pass one entry in `network_configs` for a single-network environment, or multiple entries for a multi-network one.

### Request body

| Field                                                       | Type    | Required | Description                                                                      |
| ----------------------------------------------------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| `display_name`                                              | string  | yes      | Human-readable name shown in the dashboard.                                      |
| `slug`                                                      | string  | no       | URL-safe identifier. Auto-generated from `display_name` if omitted.              |
| `network_configs`                                           | array   | yes      | One entry per network in the environment.                                        |
| `network_configs[].network_id`                              | string  | yes      | Chain ID of the network to fork (e.g. `"1"` for Ethereum).                       |
| `network_configs[].block_number`                            | string  | no       | Fork point in hex. Defaults to the latest block.                                 |
| `network_configs[].chain_config_overrides.chain_id`         | string  | no       | Override the chain ID assigned to this Virtual Environment.                      |
| `network_configs[].explorer_config.enabled`                 | boolean | no       | Expose a [public explorer page](/virtual-environments/explorer#public-explorer). |
| `network_configs[].explorer_config.verification_visibility` | string  | no       | `"bytecode"`, `"abi"`, or `"source"`.                                            |
| `network_configs[].accounts`                                | array   | no       | Pre-funded accounts. Each entry has `address` and `balance` (Wei, hex-encoded).  |
| `bridge_config.enabled`                                     | boolean | no       | Enable cross-chain bridging between networks in this environment.                |
| `bridge_config.relay_mode`                                  | string  | no       | `"autoRelay"` (default) or `"delayedRelay"`.                                     |
| `bridge_config.delay_seconds`                               | integer | no       | Relay delay in seconds when using `"delayedRelay"`.                              |

### Single-network example

```json title="request.json" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "display_name": "Staging Mainnet",
  "slug": "staging-mainnet",
  "network_configs": [
    {
      "network_id": "1",
      "block_number": "latest",
      "chain_config_overrides": { "chain_id": "73571" },
      "explorer_config": { "enabled": false, "verification_visibility": "bytecode" }
    }
  ]
}
```

### Multi-network example

```json title="request.json" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "display_name": "Cross-chain Staging",
  "network_configs": [
    {
      "network_id": "1",
      "block_number": "latest",
      "chain_config_overrides": { "chain_id": "1" }
    },
    {
      "network_id": "42161",
      "block_number": "latest",
      "chain_config_overrides": { "chain_id": "42161" }
    },
    {
      "network_id": "8453",
      "block_number": "latest",
      "chain_config_overrides": { "chain_id": "8453" }
    }
  ],
  "bridge_config": { "enabled": true, "relay_mode": "autoRelay" }
}
```

### Response

Returns the created environment object. The `active_instance.vnets` array contains one entry per network, each with its RPC endpoints.

```json title="response.json" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "id": "d998eea3-139d-4477-9de2-42f7739362f0",
  "display_name": "Staging Mainnet",
  "slug": "staging-mainnet",
  "created_at": "2026-06-08T10:00:00.000Z",
  "networks": [
    {
      "id": "a1b2c3d4-...",
      "network_id": "1",
      "network_name": "Ethereum Mainnet",
      "block_number": "0x168a5c6"
    }
  ],
  "active_instance": {
    "id": "e5f6a7b8-...",
    "vnets": [
      {
        "id": "f9e8d7c6-...",
        "display_name": "Staging Mainnet",
        "slug": "staging-mainnet",
        "status": "running",
        "rpcs": [
          { "name": "Admin RPC", "url": "https://virtual.mainnet.rpc.tenderly.co/..." },
          { "name": "Public RPC", "url": "https://virtual.mainnet.rpc.tenderly.co/..." }
        ],
        "fork_config": { "network_id": 1, "block_number": "0x168a5c6" }
      }
    ]
  }
}
```

The `rpcs` array on each entry contains the Admin RPC (full [cheatcode](/virtual-environments/admin-rpc) access) and the Public RPC (standard JSON-RPC).

## List environments

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
GET /environments
```

Returns all environments for the project.

## Get an environment

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
GET /environments/{environmentId}
```

Returns a single environment by ID, including its `active_instance` and RPC endpoints.

## Delete an environment

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
DELETE /environments/{environmentId}
```

Permanently deletes a single environment. Returns `204 No Content`.

## Batch delete environments

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
DELETE /environments
```

Permanently deletes multiple environments in one call. Pass the IDs in the request body.

## List transactions

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
GET /environments/{environmentId}/instance/{instanceId}/transactions
```

Returns transactions across all Virtual Environments in an environment instance. Supports pagination and optional filters by status, category, kind, and from/to address.

## Get a transaction

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
GET /environments/{environmentId}/instance/{instanceId}/transactions/{txHash}
```

Returns a single transaction from an environment instance by transaction hash.

## Send a transaction

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
POST /environments/{environmentId}/instance/{instanceId}/vnet/{vnetId}/transactions
```

Executes a transaction on a specific Virtual Environment within an environment instance. State is preserved.

## Simulate a transaction

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
POST /environments/{environmentId}/instance/{instanceId}/vnet/{vnetId}/transactions/simulate
```

Simulates a transaction without preserving state. Supports block overrides, state overrides, and a custom block number. Returns a detailed simulation result including call trace, state changes, and emitted events.

## See also

* [Create Virtual Environments via API](/virtual-environments/develop/create-virtual-environment-via-api), full scripted walkthrough
* [Admin RPC reference](/virtual-environments/admin-rpc), cheatcodes available on the Admin RPC
* [API Reference](/api-reference), complete Tenderly API surface


# State Sync
Source: https://docs.tenderly.co/virtual-environments/state-sync

Keep a Virtual Environment in real-time sync with its parent network using State Sync to read live oracle prices, pool data, and balances.

State Sync keeps your environment in real-time sync with the state of the parent network. This helps ensure you can access all blocks produced after the Virtual Environment has been created.

<Note>
  State Sync is available on the paid plan. To enable it for your account, [contact our sales team](https://tenderly.co/contact-us).
</Note>

You enable State Sync when creating the Virtual Environment, by selecting the **State only sync** network sync mode.

<Note>
  The network sync mode is fixed at creation and stays the same for the entire life of the Virtual Environment. It cannot be turned on, off, or switched afterwards, from the dashboard or the API. To run with a different mode, create a new Virtual Environment.
</Note>

<Tip>
  Need block-for-block alignment with the parent network and a visible mempool? See [Network Mirror Mode](/virtual-environments/network-mirror-mode), it's a stronger guarantee than State Sync, with time controls and a state-drift lens for comparing your Virtual Environment against mainnet.
</Tip>

<Warning>
  Behavior of mainnet contracts that cache `block.number` is unpredictable when running Virtual Environment transactions, since the [block number grows at different rates](#which-parent-network-state-does-latest-reflect) on mainnet and Virtual Environment.
</Warning>

## When to activate State Sync

This option is useful in several scenarios:

* Virtual Environment contracts and transactions can **access current Oracle values** that are present on the original chain.
* Access Uniswap pools from the Virtual Environments when testing contracts and building proof-of-concept transactions.
* Build a subgraph without stale data.
* Test the behavior and performance of your dapps and protocols in one-to-one correspondence with real network conditions

## How State Sync resolves write collisions

State sync enables you to access the latest values of storage slots and account balances on mainnet as they update. Upon writing to a particular storage slot on the Virtual Environment, synchronization stops for that slot, but remains active for all unmodified ones.

Here's state sync in more detail:

* The initial block number matches the latest block of the original chain at the time of creation.
* Each time you send a transaction to a Virtual Environment via `eth_sendTransaction` or `eth_sendRawTransaction`, a block is mined and block number increases by 1, independently of the original network.
* *Until writing to a variable* on Virtual Environment, the Virtual Environment tracks the current value from the original network.
* *After writing to a variable* on Virtual Environment of a contract (e.g., `C.X=100`), any subsequent read will yield that value (`100`).
* All *unmodified state variables* of a contract (`C.Y`) will reflect the value from the original network.
* Before a new block is mined on a Virtual Environment, the latest virtual block is synchronized with the latest block on the parent chain.
* Virtual Environment *mines a block after every state modification* (`sendTransaction`, `setBalance`, etc.).
* Block numbers on Virtual Environment and the original network will *change with different rates*.

<img alt="" />

## Which parent-network state does `latest` reflect?

On a State Sync Virtual Environment, `latest` account state (storage, balances, nonces, and contract code) reflects the most recently synced block of the parent network, plus any changes made by your own Virtual Environment transactions. Blocks are synced contiguously, so there are no gaps in the synced state.

The Virtual Environment's block height is not an indicator of state freshness. Blocks are mined only when the Virtual Environment processes a state modification, so its block number advances independently of the parent chain. A Virtual Environment whose head block is far behind the parent network's still serves the parent network's latest synced state at `latest`. To reason about staleness, compare against the synced parent state, not block numbers.

Synced state includes contract code. A contract deployed on the parent network after the Virtual Environment was created returns bytecode from `eth_getCode(address, "latest")` on the Virtual Environment, even though no deployment transaction, event logs, or blocks for it exist there. Reads pinned to an earlier block, such as `eth_getCode(address, "<creation block>")`, still return the state as of that block.

Only state is synced. Parent-network transactions, event logs, and blocks never appear on the Virtual Environment; see [Why can't I see mainnet transactions with State Sync?](/troubleshooting/virtual-environments#why-can-t-i-see-mainnet-transactions-with-state-sy)

For better understanding, let's explore an example:

## Example

The example demonstrates the following:

* Virtual Environment (Virtual Sepolia) accesses the latest state from original network (Sepolia).
* After a Virtual Environment **`write`**, the modified variable detaches from its Sepolia counterpart.

You can find the example on Github:

<Card title="State Sync Example" href="" />

Th example uses a modified [Counter contract](https://github.com/Tenderly/tenderly-examples/tree/master/virtual-environments-state-sync/contracts/src/Counter.sol), that contains a map of counters. It's deployed on Sepolia at `0xd01dF6d2354c5A869265dC9a9561E3544ac53262`. The [test script](https://github.com/Tenderly/tenderly-examples/tree/master/virtual-environments-state-sync/src/index.ts) will interact with both Sepolia and a Virtual Environment based on
Sepolia - `Virtual Sepolia`.

The script takes a random entry in the counter map, and then:

* Sets the value on Sepolia, then reads values on both Sepolia and Virtual Sepolia, showing that the same value is read back.
* Sets the value on Virtual Sepolia, then reads values on both Sepolia and Virtual Sepolia, showing that different values are read.
* Again sets the value on Sepolia, then reads values on both Sepolia and Virtual Sepolia, showing that the modification on Sepolia is invisible on its virtual counterpart.

<Steps>
  ### Create a Virtual Environment

  Create a [new Virtual Environment](/virtual-environments/quickstart) based on Sepolia, using `735711155111` as
  the custom Chain ID.

  ### Environment setup

  Copy `.example.env` template and replace the following:

  * **`TENDERLY_VIRTUAL_TESTNET_CHAIN_ID`** the chain ID of the Virtual Environment. Use `735711155111`
  * **`TENDERLY_VIRTUAL_TESTNET_RPC_URL_SEPOLIA`** the RPC URL of the Virtual Environment
  * **`PRIVATE_KEY`** for signing test transactions

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  cp .example.env .env
  vi .env # modify environment variables
  ```

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  cd virtual-environments-state-sync
  source .env
  yarn install
  npx ts-node src/index.ts
  ```

  ### Results

  Key points to notice about **`write`** operations:

  1. After writing to sepolia (`1`), both sepolia and virtualSepolia read value `1` - the latest state of the original
     network.
  2. After writing to Virtual Sepolia (`10`), reading from Sepolia gives the previously set value (`1`), and reading from
     virtualSepolia gives the recently set value (`10`).
  3. After writing to Sepolia again (`100`), reading from Sepolia gives the latest set value (`100`), and reading from
     virtualSepolia gives the previously set value (`10`).

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  Playing with Counter(0xd01dF6d2354c5A869265dC9a9561E3544ac53262).numbers[3788720642447205]
  State:
    sepolia: 0
    virtualSepolia: 0

  ================================================================================================
  Write: Counter(0xd01dF6d2354c5A869265dC9a9561E3544ac53262)@Sepolia.numbers[3788720642447205] = 1
  Tx hash: 0xe57c5da70c68d55f86957f7a2fc2644670b032fe5f972b9e9ccc2774cd2ba352
  State:
    sepolia: 1
    virtualSepolia: 1

  ================================================================================================
  Write: Counter(0xd01dF6d2354c5A869265dC9a9561E3544ac53262)@Virtual Sepolia.numbers[3788720642447205] = 10
  Tx hash: 0x56099d89c1d6fd001a1e9a0cecca13e13c04013b473acb6a48cd61a4b988696c
  State:
    sepolia: 1
    virtualSepolia: 10

  ================================================================================================
  Write: Counter(0xd01dF6d2354c5A869265dC9a9561E3544ac53262)@Sepolia.numbers[3788720642447205] = 100
  Tx hash: 0xc3c37e912bfa4fca9b980339fa2c95dbef75d6c605f0df831ca985b0ef3b61ec
  State:
    sepolia: 100
    virtualSepolia: 10
  ```
</Steps>


# Unlimited Faucet
Source: https://docs.tenderly.co/virtual-environments/unlimited-faucet

Fund any account with arbitrary native and ERC-20 token balances on a Virtual Environment, from the dashboard or via Admin RPC methods.

Virtual Environments come with an unlimited faucet which you can use to fund or set an arbitrary amount of native and ERC-20 tokens to any account. Since there is no mining of tokens, funds will be instantly added to the account and available for you to use.

Accounts can be funded from the Dashboard or using custom JSON-RPC methods.

## Dashboard unlimited faucet

[Watch on Loom →](https://www.loom.com/embed/2b899ce09b694a6a8c8d2ea30ee273eb?sid=1965eae5-ff0c-49fd-9b84-75601dac1611)

From the Virtual Environment dashboard, go to **Faucet**.

1. Paste an address or addresses (1 address per line)
2. Enter the desired amount **in the nominal currency** (not WEI)
3. Pick the currency. It can be one of:
   * Network's native token
   * An existing ERC-20 token
   * Select **use custom token address** and paste the token's address
4. Click **Fund**.

## RPC unlimited faucet

You must use the **Admin RPC** URL to get access to the following RPC methods for manipulating account balances:

* [`tenderly_addBalance`](/virtual-environments/admin-rpc#tenderly_setbalance): Adds the balance to the provided account or accounts.
* [`tenderly_setBalance`](/virtual-environments/admin-rpc#tenderly_setbalance): Modifies the balance of an account or accounts.
* [`tenderly_setErc20Balance`](/virtual-environments/admin-rpc#tenderly_seterc20balance): Sets the token balance for the wallet on the provided erc20 contract. Does not emit a `Transfer` event.
* [`tenderly_addErc20Balance`](/virtual-environments/admin-rpc#tenderly_adderc20balance): Adds tokens to one or more wallets and emits a synthetic ERC-20 `Transfer` event for each funded account, use this when indexers or log-based tooling need to pick up the balance change.
* [`tenderly_setMaxErc20Balance`](/virtual-environments/admin-rpc#tenderly_setmaxerc20balance): Sets the maximum token balance for the wallet on the provided erc20 contract. Does not emit a `Transfer` event.

## Fund ERC-20 balance

To fund DAI tokens (`0x6B175474E89094C44Da98b954EedeAC495271d0F`) to accounts `["0x40BdB4497614bAe1A67061EE20AAdE3c2067AC9e", "0xBd8DaA414Fda8a8A129F7035e7496759C5aF8570"]`
with the value of `0xDE0B6B3A7640000`, run the following script that uses [`tenderly_setErc20Balance`](/virtual-environments/admin-rpc#tenderly_seterc20balance).

```bash showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl $TENDERLY_VIRTUAL_TESTNET_RPC \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
        "jsonrpc": "2.0",
        "method": "tenderly_setErc20Balance",
        "params": [
        "0x6B175474E89094C44Da98b954EedeAC495271d0F",
        [
          "0x40BdB4497614bAe1A67061EE20AAdE3c2067AC9e",
          "0xBd8DaA414Fda8a8A129F7035e7496759C5aF8570"
        ],
        "0xDE0B6B3A7640000"
        ],
        "id": "1234"
    }'
```

## Fund native balance

You can fund the account `0xE58b9ee93700A616b50509C8292977FA7a0f8ce1` to value of `0xDE0B6B3A7640000` by running the following script that uses [`tenderly_setBalance`](/virtual-environments/admin-rpc#tenderly_setbalance).

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl $TENDERLY_VIRTUAL_TESTNET_RPC \
-X POST \
-H "Content-Type: application/json" \
-d '{
    "jsonrpc": "2.0",
    "method": "tenderly_setBalance",
    "params": [
      [
        "0xE58b9ee93700A616b50509C8292977FA7a0f8ce1",
        "0xBd8DaA414Fda8a8A129F7035e7496759C5aF8570"
        ],
      "0xDE0B6B3A7640000"
      ],
    "id": "1234"
}'
```

## Fund yield tokens

You can also fund staking tokens like stETH `0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84` on wallet address `0xb5f45E52649123117C175B2016Ed3fCd26f9bE06` by running the following script that uses [`tenderly_setMaxErc20Balance`](/virtual-environments/admin-rpc#tenderly_setmaxerc20balance).
The value will be set to the maximum possible uint256 value that the method algorithm calculates. At the moment it is not possible to predetermine the exact value.

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl $TENDERLY_VIRTUAL_TESTNET_RPC \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "id": 0,
  "jsonrpc": "2.0",
  "method": "tenderly_setMaxErc20Balance",
  "params": [
    "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
    "0xb5f45E52649123117C175B2016Ed3fCd26f9bE06"
  ]
}'
```


# What you get
Source: https://docs.tenderly.co/what-you-get

What you get with Tenderly, the simulation platform for onchain operations: Simulator, Console, Monitor, and Node RPC for engineering and finance teams.

Tenderly is the blockchain operations platform teams use to run onchain systems in production. Model every transaction, deployment, and strategy against live network state before it's final, investigate anything that happens onchain with fully decoded context, and respond to issues the moment they appear.

The full platform is built for teams operating production systems, with a free account available so anyone can explore and debug any supported chain. This page covers what you get at each level, starting with the full platform.

## The full Tenderly platform

Engineering, finance, and risk teams get a single operational layer across 100+ EVM networks, organized around four products.

### Simulator: the simulation engine for every onchain decision

Simulator is Tenderly's core capability, enabling you to preview the exact result of any onchain action against the live state of every chain you operate on, before any capital or users are exposed.

* **[Virtual Environments](/virtual-environments/overview):** production-mirroring environments with real oracle prices, current liquidity, and live protocol state. Spin them up in seconds, sync state continuously, and share one environment across your whole team instead of isolated local forks.
* **[Multichain environments with bridging](/virtual-environments/multichain/quickstart):** validate complete cross-chain workflows in a single environment, with built-in support for LayerZero, Chainlink CCIP, Across, and CCTP.
* **Full control over network state:** impersonate any account, fund any address with any token through the [unlimited faucet](/virtual-environments/unlimited-faucet), override storage, advance time, and mine blocks with [Admin RPC cheatcodes](/virtual-environments/admin-rpc).
* **[Simulation API](/simulations/overview):** dry-run any transaction programmatically and read back state diffs, asset changes, emitted events, gas usage, and a full execution trace.
* **[Simulation Bundles](/simulations/bundled-simulations):** sequence approvals, transfers, and protocol calls as a single multi-step unit, each step building on the state of the previous one, to validate entire user intents end-to-end.
* **[Simulator UI](/simulator-ui/overview) and [Simulation Mode](/developer-explorer/simulation-mode):** build, edit, and re-run simulations in the dashboard, with state overrides, source edits, and historical or pending block context.
* **CI/CD and staging:** provision fresh environments per commit, pull request, or pipeline stage with [GitHub Actions](/virtual-environments/integrations), [Foundry, and Hardhat integrations](/virtual-environments/overview).

### Console: complete context for onchain activity

Console decodes the most granular execution data on the blockchain into human-readable context, for verified and unverified contracts alike, serving as the operational center for your team.

The full platform adds multi-network coverage, shared team context, and the following products:

* **[Explorer](/developer-explorer/overview):** unified multi-network search, transaction listings, and decoded transaction views across every chain in your project.
* **[Debugger](/debugger/overview):** step through any transaction to the exact line of code where it failed, evaluate expressions, edit contract source, and re-simulate to validate a fix.
* **[Gas Profiler](/debugger/gas-profiler):** visual gas breakdown per function call, with access list recommendations.
* **[Fund Flow](/developer-explorer/inspect-transaction/fund-flow):** follow capital movement through any transaction across addresses and protocols, with decoded context at every step.
* **[DeFi Modules](/defi-modules/overview):** observe the health and activity of the lending protocols your product depends on, with positions, liquidity movement, and protocol risk in one view.
* **[Address management](/developer-explorer/wallets):** import and label the wallets and contracts that matter to your organization so every team works with the same named entities.
* **[Private contract verification](/contract-verification/overview):** verify contracts within your project only, keeping pre-release code and strategies off public networks.
* **Team workspace:** [organizations and projects](/platform/account/organizations/overview) with role-based permissions, so engineering, support, and risk teams share one source of truth.

### Monitor: the full detection-to-response pipeline

Catch early signals of unexpected behavior and move from detection to a verified response before issues cascade.

* **[Alerts](/monitoring/alerts/introduction):** real-time rules for failed transactions, function calls, emitted events, balance and state changes, and threshold violations.
* **[Alert destinations](/monitoring/alerts/destinations/overview):** route notifications to Slack, Discord, Telegram, PagerDuty, email, or custom webhooks.
* **[Web3 Actions](/monitoring/web3-actions/introduction):** execute custom code when conditions are met, from notifying the right team to pausing execution or triggering downstream workflows.

### Node RPC: production-grade RPC infrastructure access

Scale with growing onchain usage on a highly scalable Node RPC with multi-regional traffic routing, low latency, and near-zero error rates.

* **[Node RPC](/node-rpc/overview):** low-latency JSON-RPC across 75+ networks with full archive data.
* **[Simulations and gas estimation over RPC](/node-rpc/guides/simulate-json-rpc):** embed transaction previews and accurate gas estimates directly into your product through the same connection that submits transactions.

### Built for organizations

For teams with specific operational, security, or compliance requirements, Tenderly supports SSO sign-in, role-specific access control, private and custom chain support, and dedicated deployments within your own infrastructure.

<Card title="Get the full platform" href="https://tenderly.co/contact-us">
  Talk to our team about setting up Tenderly for your organization, sized to your operations.
</Card>

## What you get with a free account

A free account gives you access to:

* **[Explorer](/developer-explorer/overview):** search and inspect transactions, addresses, and assets with decoded context.
* **Single-transaction simulation:** run a transaction in the browser and see exactly what would happen before you sign anything.
* **Impersonate any account:** send simulated transactions as *any* public address. No private keys needed.
* **Override balances and storage:** pretend your wallet has 1,000 ETH, or that a contract slot holds a different value, and watch the outcome.
* **Public contract verification:** verify your contract source through the Dashboard or the Hardhat and Foundry plugins so the decoded view shows up for everyone.

<Card title="Sign up for free" href="https://dashboard.tenderly.co/register">
  Create a free account and get the in-browser simulator at no cost.
</Card>

## What you get without an account

The core explorer and debugger surface is public. Drop any transaction hash, contract, or wallet address into Tenderly and inspect it on the network of your choice:

* **Transaction details at a glance:** token transfers, emitted events, balance and state changes, every contract involved.
* **Full error and stack trace** with human-readable revert messages, jump-to-revert, opcode search, and event logs, storage, and gas per call.
* **Debugger:** step through execution one opcode at a time, evaluate expressions, and inspect contract variables.
* **Gas Profiler:** visual breakdown of gas usage per function call.
* **Account abstraction (ERC-4337) decoding:** full UserOp visibility with bundler and paymaster context.
* **Fund Flow:** visual token-transfer graph across every call in a transaction.
* **Read/write interfaces:** interact with any verified contract directly from the UI.

<Note>
  Without an account you explore one network at a time. Pick the chain, then search.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="What does the full platform include?">
    The full platform includes all the products listed above: Virtual Environments, the Simulation API and Bundles, complete Console with multi-network search and team workspaces, Monitor with Alerts and Web3 Actions, and Node RPC access. [Contact our team](https://tenderly.co/contact-us) to set it up for your organization.
  </Accordion>

  <Accordion title="Can I use Tenderly without paying?">
    Yes. Explorer and Debugger are free for any supported EVM chain, with no account required for the core functionalities. A free account adds the in-browser Simulator.
  </Accordion>

  <Accordion title="Do I need an account to debug a transaction?">
    No. Paste any transaction hash and you'll land directly in Debugger.
  </Accordion>

  <Accordion title="Which networks are supported?">
    Tenderly supports 100+ EVM chains. See the full list on the [Supported Networks](/platform/supported-networks) page.
  </Accordion>
</AccordionGroup>


# Tenderly MCP Server examples with Claude
Source: https://docs.tenderly.co/ai-tools/examples

Step-by-step walkthroughs for simulating transactions, tracing execution, and inspecting contracts with the Tenderly MCP Server and Claude.

These walkthroughs show how Claude uses [Tenderly MCP Server](/ai-tools/overview) tools to complete real development tasks. If you haven't connected it yet, follow the [MCP Server quickstart](/ai-tools/quickstart) first. You don't need to call tools by name, just describe what you want and Claude handles the rest.

The examples are grouped roughly by activity:

* **Setup & pre-flight**: spinning up environments, funding wallets, checking transactions before you sign.
* **Debugging & post-mortem**: figuring out why a transaction failed, who took funds, or why a swap returned less than expected. The advanced trace navigation tools shine here.
* **Virtual Environment workflows**: impersonation, multi-step testing, snapshots, time-travel, token balance overrides.
* **Optimization & inspection**: gas breakdowns, contract metadata.

## Create a Virtual Environment and fund a wallet

**What to ask:**

> "Create a Virtual Environment forked from Ethereum mainnet and fund my wallet 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 with 100 ETH."

**What Claude does:**

1. Calls `list_projects` to find your projects, then `set_active_project` to select one.
2. Calls `get_networks` to find the Ethereum mainnet network ID.
3. Calls `create_vnet` with the network ID, creating a forked environment. The new Virtual Environment is automatically set as active.
4. Calls `fund_account` with your wallet address, setting the balance to 100 ETH in hex wei. Operates on the active Virtual Environment automatically.
5. Returns the Virtual Environment details including **Admin RPC** and **Public RPC** URLs, ready for use in Hardhat, Foundry, or any Web3 library.

**What you get back:**

A running Virtual Environment forked from latest mainnet state, your wallet funded, and RPC URLs you can drop into your development framework config.

***

## Simulate a Uniswap swap

**What to ask:**

> "Simulate a swap of 1 ETH for USDC on Uniswap V3 from 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 on Ethereum mainnet. Show me the expected output and any token transfers."

**What Claude does:**

1. Calls `simulate_transaction` with the Uniswap V3 router address, your sender address, the swap calldata, and 1 ETH as value.
2. The simulation runs against current mainnet state and returns: success/revert status, gas used, and decoded method name.
3. Calls `get_simulation_asset_transfers` to show all token movements, the ETH going in and USDC coming out.
4. Calls `get_simulation_balance_changes` to show the net impact on your balances with USD values.

**What you get back:**

The exact USDC output, gas cost, and a breakdown of every asset transfer. If the swap would revert (e.g., slippage too high), you get the decoded revert reason.

***

## Pre-flight check a transaction before sending

**What to ask:**

> "I'm about to call `approve` on 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 to give 0xE592427A0AEce92De3Edee1F18E0157C05861564 unlimited USDC allowance. Simulate it first and show me exactly what approvals and state changes it will create."

**What Claude does:**

1. Calls `simulate_transaction` with your wallet as sender, the token contract as recipient, and the `approve` calldata.
2. Calls `get_simulation_exposure_changes` to show every approval and allowance change, which spender gets access to what, and how much.
3. Calls `get_simulation_state_changes` to show the exact storage slots modified.

**What you get back:**

The exact approval being granted (spender address, token, amount), the storage diff confirming the allowance slot changed, and whether the transaction would succeed. Useful any time you're interacting with an unfamiliar contract or want to verify calldata before signing.

***

## Debug a failed on-chain transaction

**What to ask:**

> "Why did transaction 0x6c5df5a1e6b34e2432ae19706e38a84239495cdbf40c2a9d4d79806443c4aa0d revert on Ethereum?"

**What Claude does:**

1. Calls `trace_transaction` with the tx hash. Returns the status (`false` = reverted), gas used, decoded method name, and error message.
2. Calls `get_simulation_call_trace` to get the full internal call tree, every function call, with decoded names, inputs, outputs, and which specific call failed.
3. Calls `get_simulation_events` to see what events were emitted before the revert point.
4. Optionally calls `get_simulation_state_changes` to see what state was modified up to the failure.

**What you get back:**

A clear explanation of exactly which internal call failed, the decoded revert reason (e.g., `"ERC20: transfer amount exceeds balance"`), and the full call trace so you can see the execution path leading up to the failure.

***

## Find the root cause of a revert in a deeply nested transaction

**What to ask:**

> "Transaction 0x... reverted on Ethereum. It's a complex DeFi call with lots of internal calls, find the actual error and show me the path that led to it."

**What Claude does:**

1. Calls `trace_transaction` for the top-level summary and confirms the revert.
2. Calls `find_failures` to list every failing call in the transaction, not just the outermost one. This surfaces both the originating revert and any wrapping `require`/try-catch failures.
3. Calls `get_error_path` to return the blame chain from the root call down to the deepest failing call, with decoded inputs and outputs at each level.
4. If any node still has omitted children, calls `get_call_trace_node` on the specific position to expand it.

**What you get back:**

The exact contract, function, and decoded revert reason at the deepest failure, plus the full chain of callers that led there. Much faster than paging through a 200-call `get_simulation_call_trace` output.

***

## Navigate a very large trace

**What to ask:**

> "This transaction has hundreds of internal calls and `get_simulation_call_trace` is truncated. Help me understand its structure and drill into the part that matters."

**What Claude does:**

1. Calls `get_trace_stats` to report total calls, max depth, error count, and unique contracts, a quick size check that decides the strategy.
2. Calls `get_trace_skeleton` to get a compressed call tree: function name, contract, depth, and error flag per node, without decoded args.
3. Identifies the interesting subtree (a failing branch, a specific protocol, or a suspicious contract) using `absolute_position` values from the skeleton.
4. Calls `get_call_trace_node` to expand that subtree with full decoded inputs and outputs.
5. Optionally calls `get_subtree_events` and `get_subtree_state_changes` to see only the events and storage diffs from that subtree.

**What you get back:**

A map of the transaction's structure, then full detail on just the part you care about, without loading thousands of calls into context.

***

## Search a trace for a specific contract or function

**What to ask:**

> "Did this transaction ever call `transferFrom` on USDC? If so, show me every call with the decoded args."

**What Claude does:**

1. Calls `search_call_trace` with the USDC address and `transferFrom` as filters, returning only matching calls with their decoded inputs, outputs, and absolute positions.
2. For any match that's interesting, calls `get_call_trace_node` to fetch the full nested context around it.

**What you get back:**

A targeted list of matching calls instead of the full trace. Useful for answering "did X happen" questions on large transactions, and for auditing whether a known-risky selector was invoked.

***

## Follow the money through a transaction

**What to ask:**

> "For transaction 0x... on Ethereum, show me who sent what to whom, in order, with USD values."

**What Claude does:**

1. Calls `get_transaction_fund_flow` with the tx hash. Returns ordered token and native transfers, each with from/to addresses and USD values, plus a net flow per address.
2. Optionally calls `get_contract_info` on any unfamiliar address to identify it (protocol router, pool, treasury, etc.).

**What you get back:**

A chronological money map of the transaction and a per-address net flow, ideal for understanding MEV bundles, unfamiliar DeFi interactions, or verifying that a multi-hop swap moved funds as expected. On-chain transactions only.

***

## Debug a failed Safe multisig batch execution

**What to ask:**

> "Our Safe batch execution at 0x... reverted on Ethereum. The batch has 12 calls. Which one actually failed and why?"

**What Claude does:**

1. Calls `trace_transaction` to confirm the revert and get the top-level method (`execTransaction` or `multiSend`).
2. Calls `get_trace_stats`, Safe batches explode into large traces quickly, so the stats decide the next step.
3. Calls `find_failures`, because `multiSend` often reverts the whole batch on any sub-call failure, this is the fastest way to see which of the 12 operations blew up, not just the outer Safe revert.
4. Calls `get_error_path` on the failing sub-call for the full decoded input/output chain at each level.
5. Optionally calls `get_call_trace_node` if any relevant node was truncated.

**What you get back:**

The exact sub-call inside the batch that failed, with the decoded target, function, arguments, and revert reason, rather than a generic "GS013" Safe error with no context.

***

## Post-mortem an exploit or suspicious transaction

**What to ask:**

> "0x... on Ethereum drained funds from our protocol. Walk me through what happened: who ended up with the money, what the attacker called, and where the exploit entered our contracts."

**What Claude does:**

1. Calls `get_transaction_fund_flow` first, the ordered token and native flows plus per-address net flow surface the attacker's wallet and the drained protocol addresses immediately.
2. Calls `get_trace_skeleton` to map the attacker's call structure without loading every argument.
3. Calls `search_call_trace` for calls into the protocol's contracts (by address) to isolate the entry point.
4. Calls `get_call_trace_node` on the entry point for decoded args, then `get_subtree_state_changes` to see exactly what state the exploit mutated.
5. Calls `get_contract_info` on any unknown contracts the attacker interacted with (helpers, proxies, known exploit contracts).

**What you get back:**

A money-first narrative of the exploit: who received what, the exact function and arguments that triggered the drain, and the state changes that made it possible. Enough detail to write an incident report or start a patch.

***

## Investigate an unexpected liquidation

**What to ask:**

> "My Aave position got liquidated in 0x..., figure out why. I want to know the oracle price at liquidation time and the exact health-factor path."

**What Claude does:**

1. Calls `trace_transaction` and `get_trace_skeleton` to map the liquidation call tree.
2. Calls `search_call_trace` for oracle calls (e.g., `latestAnswer`, `getAssetPrice`) to find the price reads the liquidation used.
3. Calls `get_call_trace_node` on each match for the decoded return values, the exact price feeding the health-factor math.
4. Calls `get_transaction_fund_flow` to show how much collateral was seized, the debt repaid, and the liquidator's bonus.
5. Optionally calls `get_subtree_events` on the liquidation subtree for `LiquidationCall` and `Transfer` events in order.

**What you get back:**

The oracle prices used, the liquidator's profit, the exact collateral and debt amounts, and, if applicable, the block or transaction that moved your health factor below 1. A complete "why did I get liquidated" answer.

***

## Audit a 1inch / aggregator swap that returned less than expected

**What to ask:**

> "0x... was a 1inch swap where I got significantly less USDC than the quote. Which pool or hop gave the bad price?"

**What Claude does:**

1. Calls `get_trace_stats`, aggregator routes can be deep with many pool hops.
2. Calls `get_trace_skeleton` to see the sequence of pool calls in order.
3. Calls `search_call_trace` for `swap`, `exactInput`, or the router's pool-interaction selectors, pulling out each hop.
4. Calls `get_call_trace_node` on each hop for decoded `amountIn` / `amountOut` values.
5. Calls `get_transaction_fund_flow` to confirm the final net received and any unexpected transfers (fees, rebates).

**What you get back:**

A per-hop breakdown of input and output amounts across the route, with the pool that had worse-than-expected execution called out. Useful for measuring slippage, comparing routes, or catching stale-quote issues.

***

## Re-simulate a failed transaction with a fix

**What to ask:**

> "Transaction 0x... failed with 'ERC20: transfer amount exceeds balance'. Re-simulate it but override my USDC balance to 10,000 USDC to confirm that's the only issue."

**What Claude does:**

1. Calls `resimulate_transaction` with the original tx hash and a state override setting your token balance to 10,000 USDC.
2. If the simulation succeeds, confirms the root cause was insufficient balance.
3. Calls `get_simulation_call_trace` to verify the execution path now completes without error.
4. Optionally calls `get_simulation_asset_transfers` to show what the transaction would have done if it had succeeded.

**What you get back:**

Confirmation of whether the fix resolves the issue, without deploying anything or spending gas. State overrides let you test assumptions, insufficient balance, wrong allowance, incorrect ownership, instantly, against real mainnet state.

***

## Understand what a transaction did

**What to ask:**

> "Walk me through everything that happened in transaction 0x... on Ethereum, every internal call, who called who, and what changed."

**What Claude does:**

1. Calls `trace_transaction` for a top-level summary: method name, sender, recipient, gas used, and status.
2. Calls `get_simulation_call_trace` to get the full internal call tree, every nested call with decoded function names, inputs, outputs, and per-call gas.
3. Calls `get_simulation_events` to list all events emitted in order.
4. Calls `get_simulation_state_changes` to show every storage slot and balance that changed.

**What you get back:**

A complete, human-readable reconstruction of the transaction. Useful for auditing unfamiliar protocol interactions, understanding MEV activity, or verifying that a complex multi-contract call did exactly what you expected.

***

## Inspect a smart contract

**What to ask:**

> "What contract is deployed at 0xdAC17F958D2ee523a2206206994597C13D831ec7 on Ethereum?"

**What Claude does:**

1. Calls `get_contract_info` with the address and Ethereum's network ID.

**What you get back:**

The contract name (Tether USD), token standards (ERC-20), compiler version, EVM version, source language, creation block, deployer address, creation transaction hash, and the full ABI. Claude can then use the ABI to help you encode calldata for simulations or build transactions.

***

## Send an impersonated transaction on a Virtual Environment and trace it

**What to ask:**

> "On my Virtual Environment, send a transaction from the Uniswap V2 deployer 0x1a9C8182C09F50C8318d769245beA52c32BE35BC to the USDC contract 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 calling the `transfer` function to send 1000 USDC to my wallet. Then trace the execution."

**What Claude does:**

1. Calls `send_vnet_transaction` on the active Virtual Environment with the deployer as `from`, USDC as `to`, and the ABI-encoded `transfer` calldata. The sender is impersonated, no private key needed.
2. Calls `get_vnet_transactions` to get the `operation_id` of the executed transaction.
3. Calls `trace_vnet_transaction` to get the decoded execution summary, contract name, function name, decoded input parameters, and output.
4. Optionally calls `get_vnet_simulation_events` and `get_vnet_simulation_state_changes` for deeper details.

**What you get back:**

Confirmation that the transaction executed, the decoded trace showing the `transfer` call succeeded, and the events emitted (Transfer event with your wallet as recipient).

***

## Test a multi-step contract interaction on a Virtual Environment

**What to ask:**

> "On my Virtual Environment, run the full approval and swap flow: first approve the Uniswap router to spend 1000 USDC from my wallet, then execute the swap. Show me my balances before and after."

**What Claude does:**

1. Calls `send_vnet_transaction` on the active Virtual Environment to submit the `approve` transaction, impersonating your wallet, no private key needed.
2. Calls `send_vnet_transaction` again with the swap calldata.
3. Calls `get_vnet_simulation_asset_changes` on each transaction to show token movements per step.
4. Calls `get_vnet_simulation_balance_changes` after the final step to show the net balance impact.

**What you get back:**

Step-by-step confirmation that each transaction succeeded, token transfers per step, and your final net balance change. This is the full pre-deployment testing loop, run any sequence of transactions against a forked mainnet state before touching real funds.

***

## Analyze gas usage for optimization

**What to ask:**

> "Simulate this transaction and show me a gas breakdown so I can find the most expensive function calls: \[paste calldata or describe the transaction]"

**What Claude does:**

1. Calls `simulate_transaction` with your transaction parameters.
2. Calls `get_simulation_gas_breakdown` to get per-call gas consumption including intrinsic gas and refunds.
3. Calls `get_simulation_call_trace` to map gas costs to specific function calls in the execution tree.

**What you get back:**

A ranked list of the most gas-expensive operations, mapped to specific function calls. Use this to identify which parts of your contract logic to optimize.

<Note>
  Use `get_simulation_generated_access_list` to generate an EIP-2930 access list, which can reduce gas costs by pre-declaring which storage slots and addresses the transaction will access.
</Note>

***

## Fork a Virtual Environment for parallel testing

**What to ask:**

> "Fork my current Virtual Environment so I can test a different approach without losing the current state."

**What Claude does:**

1. Calls `list_vnets` to find your current Virtual Environment, then `set_active_vnet` if needed.
2. Calls `fork_vnet`, creating a new Virtual Environment with all state preserved, deployed contracts, balances, and transaction history. The fork is automatically set as active.
3. Returns the new Virtual Environment details with fresh RPC URLs.

**What you get back:**

Two independent Virtual Environments sharing the same starting state. You can test different contract changes or transaction sequences in each without interference, like branching in git, but for blockchain state.

***

## Snapshot, test, and revert for stress-testing

**What to ask:**

> "On my Virtual Environment, snapshot the current state, then simulate a liquidation on Aave with different oracle prices. Revert to the snapshot between each attempt so I can compare outcomes."

**What Claude does:**

1. Calls `snapshot_vnet` to save the current Virtual Environment state, receiving a snapshot ID.
2. Calls `set_storage_at` to override the oracle price to a specific value.
3. Calls `send_vnet_transaction` to trigger the liquidation.
4. Calls `get_vnet_simulation_balance_changes` and `get_vnet_simulation_asset_changes` to capture the outcome.
5. Calls `revert_vnet` to restore the Virtual Environment to the snapshot state (the snapshot is consumed).
6. Calls `snapshot_vnet` again for the next iteration, sets a different oracle price, and repeats.

**What you get back:**

A side-by-side comparison of liquidation outcomes under different price scenarios, all tested against real forked state, without deploying anything or affecting other tests.

***

## Set ERC-20 balances for testing

**What to ask:**

> "On my Virtual Environment, give my wallet 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 a balance of 10,000 USDC and 5 WETH so I can test a swap."

**What Claude does:**

1. Calls `set_erc20_balance` with the USDC token address, your wallet, and the desired amount.
2. Calls `set_erc20_balance` again with the WETH token address and amount.
3. Optionally calls `vnet_call` with a `balanceOf` call to verify the balances were set correctly.

**What you get back:**

Your wallet funded with exact token amounts, ready for testing. This is simpler than calculating storage slots manually, `set_erc20_balance` handles the token's storage layout automatically.

***

## Time-travel to test timelocks and vesting

**What to ask:**

> "On my Virtual Environment, advance the clock by 7 days to test whether my timelock contract unlocks correctly."

**What Claude does:**

1. Calls `increase_time` with 604800 seconds (7 days) to advance the Virtual Environment clock.
2. Calls `mine_block` to commit the time change to a new block.
3. Calls `vnet_call` to read the timelock contract's state (e.g., `isUnlocked()` or `releaseTime()`).
4. Optionally calls `send_vnet_transaction` to execute the unlock and verify it succeeds.

**What you get back:**

Confirmation of whether the timelock is unlockable after the time skip, without waiting 7 real days. Use this for any time-dependent logic: vesting schedules, governance voting periods, interest accrual, or cooldown windows.


# Tenderly MCP Server for Claude and AI assistants
Source: https://docs.tenderly.co/ai-tools/overview

Connect Claude and other AI assistants to Tenderly through the Model Context Protocol for simulations, tracing, contract inspection, and RPC access.

The Tenderly MCP Server gives AI assistants direct access to Tenderly, creating Virtual Environments, simulating transactions, tracing execution, inspecting contracts, and more. Use natural language in Claude to drive your entire smart contract development workflow.

<Note>
  The MCP Server is available on the paid plan. To enable it for your account, [contact our sales team](https://tenderly.co/contact-us). You also need a [Tenderly account](https://dashboard.tenderly.co/register) with at least one project.
</Note>

## Get started

<CardGroup>
  <Card title="Quickstart" href="/ai-tools/quickstart" />

  <Card title="Tools Reference" href="/ai-tools/tools" />

  <Card title="Examples" href="/ai-tools/examples" />
</CardGroup>

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard by Anthropic that lets AI models connect to external tools and data sources. Instead of copy-pasting RPC responses or writing curl commands, Claude can call Tenderly tools directly, live blockchain data, transaction simulation, debugging, and Virtual Environment management all happen within the conversation.

## Capabilities

The MCP Server exposes **59 tools** across seven areas:

* **Virtual Environments**: Create, fork, delete, and manage private blockchain environments. Set a Virtual Environment as active and all subsequent tools operate on it automatically. Fund accounts, set ERC-20 balances, write to storage slots, send impersonated transactions, make read-only contract calls, mine blocks, time-travel, and save/restore snapshots for branching test scenarios.
* **Transaction Simulation**: Simulate any transaction on any supported EVM network without spending gas. Get decoded call traces, events, state changes, asset transfers, and balance diffs.
* **Transaction Tracing**: Trace on-chain and Virtual Environment transactions with full execution details. Inspect call trees, gas breakdown, state diffs, and EIP-2930 access lists.
* **Advanced Trace Navigation**: 16 tools for navigating complex transactions with hundreds or thousands of internal calls. Includes trace size inspection, skeleton views, subtree drilling, failure detection, error path tracing, and fund flow analysis.
* **Contract Inspection**: Retrieve contract metadata for any address: name, ABI, compiler version, token standards, and creation info.
* **Network Discovery**: List all 100+ EVM networks Tenderly supports.
* **Project Management**: List projects and set the active project context.

See the full [Tools Reference](/ai-tools/tools) for details on every tool.

## Supported clients

The Tenderly MCP Server works with any MCP-compatible client:

* **Claude Code**: Add via CLI with one command
* **Claude.ai**: Connect through Settings → Connectors
* **Claude Desktop**: Connect through Settings → Connectors
* **Cursor/VS Code**: Add the server URL to your MCP config

See the [Quickstart](/ai-tools/quickstart) for setup instructions for each client.

## Authentication

The MCP Server uses OAuth 2.0 via [WorkOS](https://workos.com/). When you connect from Claude, you'll be redirected to Tenderly to log in and authorize access. Claude can only perform actions within the scope of your permissions.

Revoke access at any time by disconnecting the connector in Claude.


# Tenderly MCP Server quickstart for Claude clients
Source: https://docs.tenderly.co/ai-tools/quickstart

Connect the Tenderly MCP Server to Claude Code, Claude.ai, Claude Desktop, and other MCP clients to run simulations and inspect contracts from chat.

Get the Tenderly MCP Server running in your AI assistant in under a minute.

<Note>
  The MCP Server is available on the paid plan. To enable it for your account, [contact our sales team](https://tenderly.co/contact-us).
</Note>

## Prerequisites

* A [Tenderly account](https://dashboard.tenderly.co/register) with MCP Server access enabled
* At least one Tenderly project

## Connect to the MCP Server

<Tabs>
  <Tab title="Shell">
    Run the following command in your terminal:

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    claude mcp add tenderly --transport http https://mcp.tenderly.co/mcp
    ```

    Verify the server is connected:

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    claude mcp list
    ```

    Run `/mcp` inside Claude Code, select **tenderly**, and follow the browser login to authenticate.
  </Tab>

  <Tab title="1. Open [claude.ai](https://claude.ai) a">
    1. Open [claude.ai](https://claude.ai) and go to **Settings → Connectors**.
    2. Click **Add custom connector** at the bottom.
    3. Enter the URL: `https://mcp.tenderly.co/mcp`
    4. Click **Add** and complete the OAuth login.

    Once connected, Tenderly tools are available in any conversation.

    > **Note:** Custom connectors require a Pro or higher Claude plan. On Enterprise plans, only workspace admins can add connectors.
  </Tab>

  <Tab title="1. Open Claude Desktop and go to Setting">
    1. Open Claude Desktop and go to **Settings → Connectors**.
    2. Click **Add custom connector**.
    3. Enter the URL: `https://mcp.tenderly.co/mcp`
    4. Click **Add** and complete the OAuth login.

    > **Note:** Custom connectors require a Pro or higher Claude plan. On Enterprise plans, only workspace admins can add connectors.
  </Tab>

  <Tab title="JSON">
    Add the following to your MCP configuration file (`.cursor/mcp.json`, `.vscode/mcp.json`, or equivalent):

    ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "mcpServers": {
        "tenderly": {
          "type": "streamable-http",
          "url": "https://mcp.tenderly.co/mcp"
        }
      }
    }
    ```

    Your editor will prompt you to authenticate when you first use a Tenderly tool.
  </Tab>
</Tabs>

## First tool call

Once connected, try a simple prompt to verify everything works:

> "What is my account name and currently active project?"

Claude will call `get_user_info` and returns your account information and the currently active project (if set). If this works, you're all set.

## Set your active project

Most tools require a project context. Set it once per session:

> "Set my active project to my-project under my-account"

Claude will call `set_active_project`. All subsequent tool calls (simulations, Virtual Environments, traces) will use this project.

<Note>
  You can also let Claude figure out the project automatically, just ask it to do something and it will call `list_projects` first if needed.
</Note>

## Troubleshooting

### Authentication fails or the connector won't log in

If the OAuth login loops or errors out, disconnect the Tenderly connector in your Claude client (Settings → Connectors) and re-add it. In Claude Code, run `/mcp`, select **tenderly**, and redo the browser login. Custom connectors on Claude.ai and Claude Desktop require a Pro or higher plan, on Enterprise plans, only workspace admins can add them.

If reconnecting doesn't help and requests return HTTP 403, see the [plan restriction below](#http-403-your-current-plan-does-not-include-mcp-access).

### HTTP 403: Your current plan does not include MCP access

This is a plan restriction, not an authentication problem. The MCP Server is available on the paid plan; on accounts without MCP access, every request returns HTTP 403 with the `quota_limit_reached` error even after a successful OAuth login. Some MCP clients react to the `insufficient_scope` response by restarting the OAuth flow, so the restriction can surface as a login loop. Re-authenticating does not resolve it. To enable MCP Server access for your account, [contact our sales team](https://tenderly.co/contact-us).

### "No active project" errors

Most tools require a project context. Ask Claude to set one:

> "Set my active project to my-project under my-account"

Or let Claude pick automatically by asking it to list projects first.

### "No active Virtual Environment" errors

Virtual Environment tools operate on the active Virtual Environment. Either create/fork a Virtual Environment (which auto-activates it) or ask Claude to call `set_active_vnet` with an existing Virtual Environment ID.

### Call trace or events are truncated

`get_simulation_call_trace` is capped at 256 entries and `get_simulation_events` at 100. For large transactions, use the [Advanced Trace Navigation](/ai-tools/tools#advanced-trace-navigation) tools: start with `get_trace_stats` for size, then `get_trace_skeleton` to see the tree structure, and `get_call_trace_node`, `get_subtree_events`, or `search_call_trace` to drill into specific parts. For reverts, `find_failures` and `get_error_path` are usually the fastest path to the root cause.

### Claude picks the wrong network, project, or Virtual Environment

Be explicit in the prompt, name the network, project slug, or Virtual Environment. You can also ask Claude to confirm the active context with `get_user_info` before running a task.

### A tool call returns stale or wrong data

Active project and Virtual Environment state is per-session. If you switch projects or Virtual Environments mid-conversation, confirm the active context with `get_user_info` before running follow-up tools.

## Next steps

* [Tools Reference](/ai-tools/tools): See all 59 tools and what they do
* [Examples](/ai-tools/examples): Walkthroughs for common workflows
* [Virtual Environments](/virtual-environments/overview): Learn more about the environments you can create
* [Simulations](/simulations/overview): Understand how transaction simulation works


# Tenderly MCP Server tools reference
Source: https://docs.tenderly.co/ai-tools/tools

Complete reference for all 59 Tenderly MCP Server tools covering simulations, transaction tracing, contract inspection, and JSON-RPC access.

The [Tenderly MCP Server](/ai-tools/overview) exposes 59 tools organized into seven groups. To connect it to your client first, follow the [MCP Server quickstart](/ai-tools/quickstart). All tools that operate on project resources require an active project, call `set_active_project` first. Virtual Environment tools require an active Virtual Environment, call `set_active_vnet` or create/fork a Virtual Environment (which auto-activates it).

<Note>
  You don't need to call tools by name. Just describe what you want in natural language and Claude will pick the right tools automatically.
</Note>

## Project & account

These tools manage your session context. Most other tools depend on having an active project set.

| Tool                 | Description                                                                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_user_info`      | Returns your account info (ID, username, email), the currently active project, and the active Virtual Environment (ID, RPC URL, network ID) if set. |
| `list_projects`      | Lists all Tenderly projects accessible to you. Supports optional search filtering by name or slug.                                                  |
| `set_active_project` | Sets the active project for subsequent tool calls. Accepts `account_slug` and `project_slug`. Must be called before using project-scoped tools.     |

## Networks

| Tool           | Description                                                                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_networks` | Lists all public EVM networks supported by Tenderly (100+). Supports optional search filtering by name. Returns network ID, name, slug, and chain ID. |

## Contracts

| Tool                | Description                                                                                                                                                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_contract_info` | Retrieves metadata for a contract address on a given network: contract name, ABI (if verified), compiler version, EVM version, language, token standards (ERC-20, ERC-721, etc.), creation block, creation transaction, and deployer address. |

## Transaction simulations

Simulate and trace transactions on any Tenderly-supported EVM network without spending gas or modifying on-chain state.

### Core simulation tools

| Tool                     | Description                                                                                                                                                                                                                                                    |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `simulate_transaction`   | Simulates a transaction and returns the outcome: success/revert status, gas used, decoded method name, error message, and revert reason. Supports state overrides, EIP-1559 fields, and custom block numbers. Results are persisted to your project dashboard. |
| `resimulate_transaction` | Replays an existing on-chain transaction in Tenderly's simulation environment. Useful for debugging transactions that reverted or behaved unexpectedly.                                                                                                        |
| `trace_transaction`      | Traces an on-chain transaction and returns a summary: status, gas used, decoded method, sender, recipient, and error details.                                                                                                                                  |

### Simulation detail tools

After running `simulate_transaction`, `resimulate_transaction`, or `trace_transaction`, use these follow-up tools with the returned `simulation_id` or `tx_hash` to inspect specific aspects of the execution.

| Tool                                   | Description                                                                                                                                                         |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_simulation_call_trace`            | Flattened call tree, every internal EVM call with decoded function names, inputs, outputs, and per-call gas. Supports `max_depth` parameter. Capped at 256 entries. |
| `get_simulation_events`                | Decoded events (logs) emitted during execution, including event names, emitting addresses, and ABI-decoded parameters. Capped at 100 entries.                       |
| `get_simulation_state_changes`         | Storage slot diffs (address, key, before/after values) and native balance diffs for all affected accounts. Capped at 100 entries.                                   |
| `get_simulation_asset_transfers`       | All token and native asset transfers: sender, recipient, token info (name, type, symbol, decimals), and amount. Capped at 100 entries.                              |
| `get_simulation_exposure_changes`      | Token approval and allowance changes, approvals, revocations, and permits. Capped at 100 entries.                                                                   |
| `get_simulation_balance_changes`       | Net per-address balance impact with USD dollar values. Capped at 100 entries.                                                                                       |
| `get_simulation_gas_breakdown`         | Per-call gas breakdown including intrinsic gas and refunds. Gas values are inclusive of subcalls.                                                                   |
| `get_simulation_generated_access_list` | Generates an EIP-2930 access list by re-simulating the transaction. Useful for gas optimization.                                                                    |

## Virtual Environments

Create and manage private, persistent forks of public EVM networks. Virtual Environments have their own RPC endpoints and support impersonated transactions without private keys.

Virtual Environment tools use a **stateful session model**: set a Virtual Environment as active (or create/fork one, which auto-activates it), and all subsequent Virtual Environment tools operate on it. No need to pass Virtual Environment IDs to every call.

| Tool                    | Description                                                                                                                                                                                                                                                                                                                                   |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `set_active_vnet`       | Sets the active Virtual Environment for subsequent tool calls. Accepts a `vnet_id`. Once set, all Virtual Environment tools operate on this Virtual Environment automatically.                                                                                                                                                                |
| `create_vnet`           | Creates a new Virtual Environment by forking a public network at a specific block. Accepts `network_id`, optional `display_name`, `description`, `block_number` (hex), custom `chain_id`, and `sync_state_enabled`. Returns the Virtual Environment details including RPC URLs. **Automatically sets the new Virtual Environment as active.** |
| `list_vnets`            | Lists Virtual Environments in the active project. Supports pagination (`page`, `per_page`), status filtering (`running`, `stopped`, `cloning`), and search by name.                                                                                                                                                                           |
| `get_vnet`              | Returns full details of the active Virtual Environment: ID, slug, display name, status, description, fork config, chain config, and RPC endpoint URLs.                                                                                                                                                                                        |
| `fork_vnet`             | Forks the active Virtual Environment into a new one, preserving all state including deployed contracts and balances. **Automatically sets the new fork as active.**                                                                                                                                                                           |
| `delete_vnet`           | Deletes a Virtual Environment. This is a destructive action. Clears the active Virtual Environment from session state.                                                                                                                                                                                                                        |
| `send_vnet_transaction` | Sends and executes a transaction on the active Virtual Environment. The sender address is impersonated, no private key needed. Accepts `from`, `to`, `input` (calldata), `value` (hex wei), and `gas`.                                                                                                                                        |
| `get_vnet_transactions` | Lists transactions on the active Virtual Environment with pagination. Returns transaction hash, status, gas used, block number, and method.                                                                                                                                                                                                   |
| `fund_account`          | Sets the native token balance of any address on the active Virtual Environment by calling `tenderly_setBalance` via RPC. Accepts `address` and `amount` in hex wei.                                                                                                                                                                           |
| `set_erc20_balance`     | Sets the ERC-20 token balance of any address on the active Virtual Environment via `tenderly_setErc20Balance`. Accepts `token_address`, `address`, and `value`. Prefer this over `set_storage_at` for token balance changes.                                                                                                                  |
| `set_storage_at`        | Writes a raw value to a specific storage slot on a contract via `tenderly_setStorageAt`. Accepts `contract_address`, `slot`, and `value`. Use for oracle price overrides, protocol parameters, or any state not covered by higher-level tools.                                                                                                |
| `vnet_call`             | Executes a read-only `eth_call` on the active Virtual Environment. Accepts `to`, `input` (calldata), and optional `from`. Results are truncated at 10 KB.                                                                                                                                                                                     |
| `vnet_multicall`        | Executes a batch of up to 10 read-only `eth_call` requests in a single RPC round-trip. Each call accepts `to`, `input`, and optional `from`. Results are truncated individually at 10 KB.                                                                                                                                                     |
| `mine_block`            | Mines a single block on the active Virtual Environment via `evm_mine`. Use after `increase_time` to apply the time change.                                                                                                                                                                                                                    |
| `increase_time`         | Advances the Virtual Environment clock by a specified number of seconds via `evm_increaseTime`. Always follow with `mine_block` to commit the time change to a new block.                                                                                                                                                                     |
| `snapshot_vnet`         | Saves the current Virtual Environment state and returns a snapshot ID via `evm_snapshot`. Use for branching test scenarios, snapshot before a test, then revert to try a different path.                                                                                                                                                      |
| `revert_vnet`           | Restores the Virtual Environment to a previously saved snapshot via `evm_revert`. The snapshot is consumed on use, take a new snapshot if you need to revert again.                                                                                                                                                                           |

## Virtual Environment simulations & traces

Simulate and trace transactions on the active Virtual Environment. These tools work with operation IDs rather than network-level tx hashes.

### Core Virtual Environment simulation tools

| Tool                          | Description                                                                                                                                                                                  |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `simulate_vnet_transaction`   | Simulates a transaction on a Virtual Environment without modifying its state. Returns status, gas used, decoded method, and an `operation_id` for follow-up tools. Supports state overrides. |
| `resimulate_vnet_transaction` | Re-traces a previously executed Virtual Environment transaction by its `operation_id` (from `get_vnet_transactions`).                                                                        |
| `trace_vnet_transaction`      | Returns a decoded execution trace summary: contract name, function name, decoded input parameters, decoded output, gas used, and error details.                                              |

### Virtual Environment simulation detail tools

Use these with the `operation_id` from the tools above. They operate on the active Virtual Environment.

| Tool                                        | Description                                                                                                    |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `get_vnet_simulation_call_trace`            | Flattened call trace for a Virtual Environment transaction with call type, addresses, gas, and value per call. |
| `get_vnet_simulation_events`                | Decoded events emitted during a Virtual Environment transaction: event name and emitting address.              |
| `get_vnet_simulation_gas_breakdown`         | Per-call gas breakdown sorted by gas usage. Shows total gas and top consumers.                                 |
| `get_vnet_simulation_state_changes`         | Storage slot diffs: address, key, before/after values for each modified slot.                                  |
| `get_vnet_simulation_generated_access_list` | EIP-2930 access list generated from the Virtual Environment transaction execution.                             |
| `get_vnet_simulation_balance_changes`       | Net per-address balance changes with dollar values.                                                            |
| `get_vnet_simulation_asset_changes`         | Token and native asset transfers: type, from, to, amount, and token info.                                      |

## Advanced trace navigation

16 tools for navigating complex transactions with hundreds or thousands of internal calls. Use these when `get_simulation_call_trace` or `get_vnet_simulation_call_trace` returns truncated results, or when you need to search, drill into, or summarize a large trace without loading the full tree.

### On-chain & simulation

| Tool                        | Description                                                                                                                                                                       |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_trace_stats`           | Quick size check before loading a trace, returns total calls, max depth, error count, and unique contracts. Use to decide which navigation strategy to apply.                     |
| `get_trace_skeleton`        | Returns a compressed call tree (function name, contract, depth, error flag, no decoded args) for large truncated traces. Use the returned `absolute_position` values to drill in. |
| `get_call_trace_node`       | Expands a specific truncated node in the trace. Use when a node reports `omitted_children > 0`.                                                                                   |
| `search_call_trace`         | Searches a large trace for specific calls without loading the full tree. Filter by address, function name, or error status.                                                       |
| `get_subtree_events`        | Returns events from one specific subtree instead of the full transaction. Use when `get_simulation_events` returns too many events.                                               |
| `get_subtree_state_changes` | Returns storage diffs from one specific subtree.                                                                                                                                  |
| `find_failures`             | Finds all error locations in a transaction at once, returns every failing node with contract name, function, and decoded error.                                                   |
| `get_error_path`            | Shows the blame chain from root to the deepest error with decoded inputs/outputs at each level. The go-to tool for debugging reverts in complex transactions.                     |
| `get_transaction_fund_flow` | Shows ordered money movement in a transaction, who sent what to whom with USD values and net flow per address. On-chain transactions only.                                        |

### Virtual Environment equivalents

Mirror of the tools above for transactions on the active Virtual Environment.

| Tool                       | Description                                              |
| -------------------------- | -------------------------------------------------------- |
| `get_vnet_trace_stats`     | Virtual Environment equivalent of `get_trace_stats`.     |
| `get_vnet_trace_skeleton`  | Virtual Environment equivalent of `get_trace_skeleton`.  |
| `get_vnet_call_trace_node` | Virtual Environment equivalent of `get_call_trace_node`. |
| `search_vnet_call_trace`   | Virtual Environment equivalent of `search_call_trace`.   |
| `get_vnet_subtree_events`  | Virtual Environment equivalent of `get_subtree_events`.  |
| `find_vnet_failures`       | Virtual Environment equivalent of `find_failures`.       |
| `get_vnet_error_path`      | Virtual Environment equivalent of `get_error_path`.      |


# Create Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/create-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/publishFile
Create a new Web3 Action. You can also set the Web3 Action to be deployed once it's been created.

## Validation

When the payload fails validation, the endpoint responds with `400` and the error slug
`found_validation_errors` without per-field detail. Common causes:

- `action.name` doesn't match `^[a-zA-Z][a-zA-Z0-9_-]*$` (it must start with a letter and may contain only letters, digits, dashes, and underscores; spaces are not allowed). Put human-readable text in `action.description` instead.
- `trigger.periodic.cron` is not a standard five-field cron expression (minute, hour, day of month, month, day of week). Seconds fields and `@hourly`-style shortcuts are not supported.
- The function referenced in `action.function` is not present in `action.source`.
- `action.trigger` is missing for a non-`ALERT` trigger type, or the trigger object doesn't match `triggerType`.
- `action.invocationType` is not one of `SYNC` or `ASYNC`.



# Delete Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/delete-web3-action

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}
This endpoint allows you to delete a Web3 Action. You need to provide the Web3 Action ID.



# Get details for all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/get-details-for-all-web3-actions

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions
Retrieve the configuration details for all Web3 Actions created in a specific project.



# Get details for single Web3 Action execution
Source: https://docs.tenderly.co/api-reference/actions/get-details-for-single-web3-action-execution

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/calls/call/{executionId}
Retrieve the details of a specific Web3 Action execution. You need to provide the Web3 Action ID and execution ID.



# Get execution history for single Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/get-execution-history-for-single-web3-action

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/calls
Retrieve the entire execution history for a specific Web3 Action. You need to provide the Web3 Action ID.



# Get Web3 Action details
Source: https://docs.tenderly.co/api-reference/actions/get-web3-action-details

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}
Retrieve the configuration details of a specific Web3 Action. You need to provide the Web3 Action ID.



# Resume all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/resume-all-web3-actions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/resume
Resume all stopped Web3 Actions created in a project.



# Resume specific Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/resume-specific-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/resume
Resume a stopped Web3 Action. You need to provide the Web3 Action ID.



# Stop all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/stop-all-web3-actions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/stop
Stop all Web3 Actions created in a specific project.



# Stop specific Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/stop-specific-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/stop
Stop a Web3 Action. You need to provide the Web3 Action ID.



# Create Alert
Source: https://docs.tenderly.co/api-reference/alerts/create-alert

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/alert
Create an Alert in a Tenderly project. 

Learn more about the different [types of Alert triggers](https://docs.tenderly.co/alerts/alert-types-targets-and-parameters).



# Delete Alert
Source: https://docs.tenderly.co/api-reference/alerts/delete-alert

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/alert/{alertId}
Delete an existing Alert. You need to provide the Alert ID.



# Get Alert History
Source: https://docs.tenderly.co/api-reference/alerts/get-alert-history

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/alert-history
Retrieve the execution history for all Alerts in a Tenderly project. 



# List Alerts
Source: https://docs.tenderly.co/api-reference/alerts/list-alerts

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/alerts
This endpoint allows you retrieve alerts for given project.



# Send test Alert
Source: https://docs.tenderly.co/api-reference/alerts/send-test-alert

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/test-alerts
This endpoint allows you test the execution of Alerts.



# Update Alert
Source: https://docs.tenderly.co/api-reference/alerts/update-alert

/api-reference/openapi.json patch /v1/account/{accountSlug}/project/{projectSlug}/alert/{alertId}
Update an existing Alert. You need to provide the Alert ID.



# Add contract to project
Source: https://docs.tenderly.co/api-reference/contracts/add-contract-to-project

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/address
Add a smart contract to a Tenderly project.

**Note**: If a contract is unverified on both Tenderly and external providers like Etherscan, Blockscout, or Routescan, it will be added to the project as **unverified**. However, if the contract is verified on an external provider, Tenderly will retrieve and apply the verification, subsequently adding the verified contract to the project.



# Add tag to mutiple contracts
Source: https://docs.tenderly.co/api-reference/contracts/add-tag-to-mutiple-contracts

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/tag
This endpoint allows you to tag multiple smart contracts.



# Delete contract from project
Source: https://docs.tenderly.co/api-reference/contracts/delete-contract-from-project

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}
Delete a smart contract from a Tenderly project. 



# Delete contract tag
Source: https://docs.tenderly.co/api-reference/contracts/delete-contract-tag

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}/tag
Delete a tag that has been added to a smart contract.



# Encode state overrides
Source: https://docs.tenderly.co/api-reference/contracts/encode-state-overrides

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/contracts/encode-states
Encode state overrides of the smart contract.



# Get all contracts in project
Source: https://docs.tenderly.co/api-reference/contracts/get-all-contracts-in-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/contracts
Get details for all smart contracts in a Tenderly project.



# Rename contract
Source: https://docs.tenderly.co/api-reference/contracts/rename-contract

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}/rename
This endpoint allows you to rename a smart contract.

**Note**: If a contract is unverified on both Tenderly and external providers like Etherscan, Blockscout, or Routescan, it will be added to the project as **unverified**. However, if the contract is verified on an external provider, Tenderly will retrieve and apply the verification, subsequently adding the verified contract to the project.



# List Delivery Channels
Source: https://docs.tenderly.co/api-reference/delivery-channels/list-delivery-channels

/api-reference/openapi.json get /v1/account/{accountSlug}/delivery-channels
Retrieves all configured delivery channels for an account.



# List Delivery Channels for project
Source: https://docs.tenderly.co/api-reference/delivery-channels/list-delivery-channels-for-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/delivery-channels
Retrieve all configured delivery channels associated with a specific project.



# Disable simulation sharing
Source: https://docs.tenderly.co/api-reference/simulator/disable-simulation-sharing

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/unshare
Call the `unshare` endpoint to disable public sharing for a simulated transaction from a specific account or project. You need to provide the ID of the simulated transaction.

Learn more about [sharing transactions](https://blog.tenderly.co/changelog/public-sharing-of-transactions-devnets-forks-and-simulations).



# Enable simulation sharing
Source: https://docs.tenderly.co/api-reference/simulator/enable-simulation-sharing

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/share
Call the `share` endpoint to enable the public sharing feature for a simulation ID from a specific account or project. Once enabled, simulation details become accessible to anyone with the link to the transaction simulation.

Example sharable link: `https://www.tdly.co/shared/simulation/{simulationId}`.

Learn more about [sharing transactions](https://blog.tenderly.co/changelog/public-sharing-of-transactions-devnets-forks-and-simulations).



# Fetch all simulated transactions
Source: https://docs.tenderly.co/api-reference/simulator/fetch-all-simulated-transactions

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/simulations
Call the `simulations` endpoint to get a list of all simulated transactions within an account and project.



# Get full simulated transaction details
Source: https://docs.tenderly.co/api-reference/simulator/get-full-simulated-transaction-details

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}
Get all the simulation details for a transaction from a specific account or project. This data includes details about the transaction, simulation details, list of contracts involved, and generated access list. You need to provide the ID of the simulated transaction. 



# Get quick simulated transaction details
Source: https://docs.tenderly.co/api-reference/simulator/get-quick-simulated-transaction-details

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/info
Call the `info` endpoint to fetch only the `transaction_info` object for a simulated transaction from a specific account or project. The response also return the block header information and block override data as separate objects. You need to provide the ID of the simulated transaction. 

This endpoint returns the same data as the [Fetch full simulation details by transaction ID](https://docs.tenderly.co/reference/api#/operations/getSimulatedTransactionById) just formatted in a different way.



# Simulate bundled transactions
Source: https://docs.tenderly.co/api-reference/simulator/simulate-bundled-transactions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulate-bundle
Call the `simulate-bundle` endpoint to simulate multiple consecutive transactions at once. You can simulate bundled transactions on real-time data from over [105+ supported networks](https://docs.tenderly.co/supported-networks-and-languages). This endpoint receive an array of transactions that get simulated one after another on the same block.

**Note:** If the initial transaction in the array changes the state, all subsequent transactions will be simulated against this modified state. Furthermore, should a simulation fail for any reason, all following simulations in the sequence will not be executed.

Learn more about [bundled simulations](https://docs.tenderly.co/simulations/bundled-simulations).

The response returns a `simulation_results` array, where each element corresponds to a simulation in the input array (in the same order). Each result contains the following objects:

`transaction`: Contains data related to the simulated transaction, including its hash, block number, origin and destination addresses, gas details, input data, nonce, and other transaction details, like the status, timestamp, and involved contract addresses. The nested `transaction_info` object holds detailed execution data such as the call trace, emitted logs, state diffs, and asset changes.

`simulation`: Contains metadata about this simulation within the bundle, including its unique ID, project and owner IDs, block number, gas used, the method invoked, simulation status, state overrides applied, and other metadata.

`contracts`: Contains data about the contract(s) involved in the transaction, including the contract's ID, network ID, balance, verification status, associated standards (like ERC20), token-specific data if the contract is a token, compiler version, and even the source code of the contract in some cases.

`generated_access_list`: Contains a list of addresses and storage keys that the transaction will access, enabling certain gas cost optimizations. The access list is a feature introduced in [Ethereum's EIP-2930](https://eips.ethereum.org/EIPS/eip-2930).



# Simulate transaction
Source: https://docs.tenderly.co/api-reference/simulator/simulate-transaction

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulate
Call the `simulate` endpoint to preview the outcomes a single transaction before sending it to the live network. You can simulate transactions with custom parameters on [105+ supported networks](https://docs.tenderly.co/supported-networks-and-languages). The output provides detailed insights into emitted events, state changes, asset and balance changes, among other things. 

Learn about [single transaction simulations](https://docs.tenderly.co/simulations/single-simulations).

The response returns the following objects:

`transaction`: Contains data related to the transaction, including its hash, block number, origin and destination addresses, gas details, input data, nonce, and other transaction details, like the status, timestamp, and involved contract addresses.

`simulation`: Contains data about the simulated transaction. It provides details related to the ID of the simulation, project and owner IDs, block number where the transaction was included, gas used, method invoked, simulation status, and other metadata.

`contracts`: Contains data about the contract(s) involved in the transaction, including the contract's ID, network ID, balance, verification status, associated standards (like ERC20), token-specific data if the contract is a token, compiler version, and even the source code of the contract in some cases.

`generated_access_list`: Contains a list of addresses and storage keys that the transaction will access, enabling certain gas cost optimizations. The access list is a feature introduced in [Ethereum's EIP-2930](https://eips.ethereum.org/EIPS/eip-2930).



# Batch Delete Environments
Source: https://docs.tenderly.co/api-reference/virtual-environments/batch-delete-environments

/api-reference/openapi.json delete /public/v1/account/{accountSlug}/project/{projectSlug}/environments
Permanently delete multiple environments by ID



# Create Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/create-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments
Create a new multi-chain environment with Virtual Environments across specified networks



# Delete Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/delete-environment

/api-reference/openapi.json delete /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}
Permanently delete a single environment by ID



# Get Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}
Get a single environment by ID



# Get Environment Instance Transaction
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment-instance-transaction

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/transactions/{txHash}
Get a single transaction from an environment instance by transaction hash



# Get Environment Instance Transactions
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment-instance-transactions

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/transactions
Get transactions across all Virtual Environments in an environment instance, with pagination and optional filters by status, category, kind, from/to address.



# List Environments
Source: https://docs.tenderly.co/api-reference/virtual-environments/list-environments

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments
List all multi-chain environments for the given account and project



# Send Transaction on Environment Virtual Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/send-transaction-on-environment-virtual-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/vnet/{vnetId}/transactions
Send a transaction to be executed on a specific Virtual Environment within an environment instance



# Simulate Transaction on Environment Virtual Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/simulate-transaction-on-environment-virtual-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/vnet/{vnetId}/transactions/simulate
Simulate a transaction on a specific Virtual Environment within an environment instance. State is not preserved. Supports block overrides, state overrides, and a custom block number. The richer response includes asset changes, balance changes, exposure changes, state changes, and cross-chain interop information.



# Get wallet in project
Source: https://docs.tenderly.co/api-reference/wallets/get-wallet-in-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/wallet/{address}/network/{networkId}
This endpoint allows you to get a single wallet for your Tenderly project.



# Account-Scoped
Source: https://docs.tenderly.co/monitoring/alerts/destinations/account-scoped

This page walks you through how to create each account-scoped Alert Destination.

[Connect Slack to Tenderly →](https://dashboard.tenderly.co/account/alerts/destinations)

Account-scoped [Alert destinations](/monitoring/alerts/destinations/overview) are accessible across all your projects within your Tenderly account. See the [Alerts](/monitoring/alerts/introduction) documentation for how to route notifications to them.

### Email Destination

<Frame>
  <img alt="Email destination configurations" />
</Frame>

Get an Alert notification in your email inbox.

Go to **Alerts →** **Destinations → Email.**

**Click Add Email.**

A verification email will be sent to the email address you provided. Click the link in the email to confirm that you’re the owner of the email address.

### Slack Destination

<Frame>
  <img alt="Slack destination configurations" />
</Frame>

Get Alert notifications in a private message or a channel on Slack.

Go to **Alerts →** **Destinations → Slack → Connect Slack.**

This will take you to the Slack permissions screen, where you need to set the Slack channel or private message to receive notifications.

### Telegram Destination

<Frame>
  <img alt="Telegram destination configurations" />
</Frame>

Get Alert notifications in a Telegram channel.

Go to **Alerts →** **Destinations → Telegram.**

Add a required label for the Telegram Destination and click **Save label**.

**Follow the instruction** on the screen to connect to TenderlyRobot for Telegram and **click Finish**.

### Discord Destination

<Frame>
  <img alt="Discord destination configurations" />
</Frame>

Get Alert notifications in a Discord channel.

Go to **Alerts →** **Destinations → Discord.**

Add a required label and paste your Discord webhook. Follow this [official guide from Discord](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) to get the webhook URL.

**Click Add Webhook**.

### Sentry Destination

<Frame>
  <img alt="Sentry destination configurations" />
</Frame>

Send Alert data to Sentry, a third-party application alert monitoring and error tracking platform.

Go to **Alerts →** **Destinations → Sentry.**

Add a required label and paste the Sentry DSN key. Check the [official Sentry documentation](https://docs.sentry.io/concepts/key-terms/dsn-explainer/) to learn how to find your project DSN.

**Click Connect Sentry**.

### PagerDuty Destination

<Frame>
  <img alt="PagerDuty destination configurations" />
</Frame>

Send Alert data to PagerDuty, a third-party incident response platform.

Go to **Alerts →** **Destinations → Pager Duty → Connect PagerDuty.**

You'll get redirected to a PagerDuty page and asked to add the Tenderly PagerDuty App to your workspace and authorize a specific channel to receive Alert notifications.


# Alert Destinations
Source: https://docs.tenderly.co/monitoring/alerts/destinations/overview

Configure alert destinations like email, Slack, and webhooks to receive notifications when your Tenderly alerts trigger.

When the desired event triggers your Alert, Tenderly will send the data about the event to a designated Alert Destination. The Destination will use this data to send you an email notification, Discord, or Slack message or send it to another Tenderly system like Web3 Actions or a Webhook.

<Note>
  You can set a single Destination for multiple Alerts, and a single Alert can send data to multiple
  Destinations.
</Note>

### Alert Destination scope

Accessibility to certain Destinations is limited by scope:

* **Account-scoped:** The same Destination can be used across all projects created within your Tenderly account. This includes email, Slack, Telegram, Discord, Sentry, and PagerDuty.
  * Learn [**how to create account-scoped Destinations**](/monitoring/alerts/destinations/account-scoped).
* **Project-scoped:** Can be used only for Alert Types created within a specific project. This includes Web3 Actions and Webhooks.
  * Learn [**how to create project-scoped Destinations**](/monitoring/alerts/destinations/project-scoped).

<Warning>
  If you edit or delete a Destination, this change will be reflected across all projects and active
  Alert Types.
</Warning>

### How to create an Alert Destination

<Frame>
  <img alt="Alerts set-up wizard" />
</Frame>

1. **Go to Alerts** from the left-hand menu.
2. **Click on Destinations** from the top page menu.
3. **Select the Destination** that fits your needs.
4. **Configure the Destination** based on the type and enable it.
5. **Check the Active Destinations** section to view and manage the Destinations you created.

When you make a Destination for the first time, it will show up on this page, and it will be available for usage in all existing, and future Alerts.

<Note>
  You can also create new Destinations in the process of configuring individual Alerts.
</Note>


# Project-Scoped
Source: https://docs.tenderly.co/monitoring/alerts/destinations/project-scoped

This page walks you through how to create each project-scoped Alert Destination.

Project-scoped Destinations are only accessible within the project they were created.

### Web3 Actions

This type of alert destination means your action will be used as a [**destination for the alert**](/monitoring/web3-actions/references/notifications).

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
trigger:
  type: alert
  alert: {}
```

A single action can be used as a destination for multiple alerts.

For more information, [read more about this and Web3 Actions in general](/monitoring/web3-actions/introduction).

### Webhooks

This alert destination allows for execution of your webhook when an alert is triggered. Your webhook will receive a signed payload, containing the transaction object that triggered the alert.

<Note>
  After adding a Webhook as an alert destination, you can use it as destination for other alerts.
</Note>

<Card title="How to use Webhooks for Alerting" href="/monitoring/alerts/tutorials/webhooks" />

#### The webhook requirements:

* It **must** be reachable at the webhook URL: when you add the webhook, Tenderly sends a **GET** request to verify reachability. Any HTTP response passes verification; verification fails only on transport errors (DNS, TCP, TLS, or no response within 2 seconds).
* It **must** expose a **POST** method with the same webhook URI. The webhook will receive a payload described below.
* Deliveries are considered failed unless the webhook responds with a `2xx` status within **10 seconds**.
* Using HTTPS for the webhook URL is strongly recommended.

<Warning>
  The Webhook must respond with a `2xx` status within **10 seconds**. If there's no response in that
  time-frame, the delivery is considered failed.
</Warning>

Tenderly keeps track of all executions. Webhook execution can have several statuses:

* **Success** - indicates that the webhook was successfully executed and the event was delivered to the specified URL
* **Failed** - indicates that the webhook was unable to be executed due to an error, such as a connectivity issue, a problem with the URL, or something else (check the response content to see what caused the error or contact our support)
* **Pending** - indicates that the webhook is in the process of being executed and has not yet been completed
* **Retry** - indicates that the webhook execution failed and will be retried; an event is delivered in at most **5 total attempts** before the status settles at Success or Failed
* **Skipped** - indicates that the webhook was not executed because it was disabled

#### Webhook payload

The webhook will receive the payload representing the alerting event. The payload consists of four fields:

* **id**: `String` - ID unique across all delivered alert events (UUID).
* **event\_type**: `TEST` | `ALERT` - the type of webhook event type.
* **alert\_id**: `String` - the ID of the alert whose rule triggered this event. Empty for `TEST` events.
* **transaction**: `Object` - an object representing an un-decoded transaction that triggered the alert and the webhook execution.

Upon adding the webhook as an alert destination, it will be invoked with a `TEST` alert event type.

<Note>
  Use the `id` field to ensure your webhook processes each alert event exactly once, by keeping
  track of processed IDs.
</Note>

#### Securing the Webhook

You can enhance security of your webhooks using the signature validation method. This way, you can verify that the request to webhook originates from Tenderly, before proceeding with the execution.

The `x-tenderly-signature` header contains a cryptographic signature: an HMAC-SHA256 digest computed with the signing secret as the **key**, over the request payload followed by the timestamp. The timestamp is delivered in the `Date` HTTP header of the request.

<Warning>
  The Signing Secret is unique for each webhook destination. Tenderly generates this secret and uses
  it to generate a signature for the payload. Keep it at a safe place.
</Warning>

**Step 1.** Obtain the Secret Signing Secret.

<Frame>
  <img alt="Copying secret signing key" />
</Frame>

**Step 2.** Validate the received signature

To validate the received signature, compute an HMAC-SHA256 digest using the signing secret as the key, feeding it, in this order:

1. the entire webhook request payload,
2. the timestamp (from the `Date` header of the request).

Lastly, compare the hex-encoded digest with the value of the `x-tenderly-signature` header.

<Tabs>
  <Tab title="example.go">
    ```go title="example.go" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    func isValidSignature(
      signature string,
      payload []byte,
      timestamp string,
    ) bool {
      h := hmac.New(sha256.New, []byte(signingKey))
      h.Write(payload)
      h.Write([]byte(timestamp))
      digest := hex.EncodeToString(h.Sum(nil))
      return digest == signature
    }
    ```
  </Tab>

  <Tab title="example.js">
    ```javascript title="example.js" showLineNumbers showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    function isValidSignature(signature, payload, timestamp) {
      // Create a HMAC SHA256 hash using the signing key
      const hmac = crypto.createHmac("sha256", signingKey);

      // Update the hash with the request body using utf8
      hmac.update(payload.toString(), 'utf8');

      // Update the hash with the request timestamp
      hmac.update(timestamp);
      const digest = hmac.digest("hex");
      return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest))
    }
    ```
  </Tab>

  <Tab title="example.py">
    ```python title="example.py" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    def isValidSignature(signature: string, payload: bytes, timestamp: string):
        h = hmac.new(str.encode(signingKey), payload, hashlib.sha256)
        h.update(str.encode(timestamp))
        digest = h.hexdigest()
        return hmac.compare_digest(signature, digest)
    ```
  </Tab>
</Tabs>

#### Debugging Webhook executions

To support debugging of webhook malfunctions, you can manually send `TEST` events, based on existing transactions from any network

**Step 1.** Click "**Test Webhook**" in the header of the webhook page.

<Frame>
  <img alt="Webhook overview" />
</Frame>

**Step 2.** Paste a hash of a transaction that matches your alert's trigger

<Frame>
  <img alt="Testing webhook: paste the transaction hash" />
</Frame>

**Step 3.** Click "**Test Webhook**" to confirm and send the test event.

Your webhook will be invoked with the transaction corresponding to the hash you pasted, and **event\_type** of `TEST`. You'll be presented with overview of that execution.

<Frame>
  <img alt="Result of a manual (test) execution of a webhook" />
</Frame>


# Setting Up Alerts as Triggers for Web3Actions
Source: https://docs.tenderly.co/monitoring/alerts/destinations/web3-action

Learn how to set up and configure Alerts as triggers for Web3Actions in Tenderly, enabling automated responses to blockchain events.

[Web3 Actions](/monitoring/web3-actions/introduction) in Tenderly provide a powerful way to automate responses to blockchain events. This guide will walk you through the process of setting up [Alerts](/monitoring/alerts/introduction) as triggers for Web3Actions, allowing you to create automated workflows based on specific blockchain conditions.

<Note>
  This guide assumes you have a Tenderly account and basic familiarity with Web3Actions.
</Note>

## Prerequisites

Before you begin, make sure you have:

* [Tenderly CLI](https://github.com/Tenderly/tenderly-cli) installed
* A Tenderly account with appropriate permissions
* Basic understanding of Web3Actions

## Setup Process

You can set up Alert triggers for Web3Actions through either the UI or CLI approach.

<Steps>
  ### UI Approach

  1. Log in to your Tenderly dashboard
  2. Navigate to the Web3Action section
  3. Click on `Create New Action`
  4. In the trigger type selection, choose `Alert`
  5. Configure your action:

  * Set a name for your action
  * Define the function that will be executed
  * Specify any necessary environment variables

  6. Click `Deploy` to create and deploy your Web3Action
  7. Open your Alert (**Alerts** in the left-hand menu) and add the deployed Web3 Action as its destination

  ### CLI Approach

  1. Create an Alert in your Tenderly dashboard (or pick an existing one)
  2. Initialize your Web3Action:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  tenderly actions init
  ```

  3. Configure your `tenderly.yaml`:

  ```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  account_id: "<YOUR_ACCOUNT_ID>"
  actions:
    <YOUR_ACCOUNT_ID>/<YOUR_PROJECT_SLUG>:
      runtime: v2
      sources: actions
      specs:
        <YOUR_ACTION_NAME>:
          description: "Description of what your action does"
          function: example:actionFn
          trigger:
            type: alert
            alert: {}
          execution_type: sequential
  project_slug: "<YOUR_PROJECT_SLUG>"
  ```

  <Warning>
    Make sure to replace all placeholder values (`<YOUR_ACCOUNT_ID>`, `<YOUR_PROJECT_SLUG>`, and `<YOUR_ACTION_NAME>`) with your actual values.
  </Warning>

  The `alert` trigger takes no configuration: the yaml only declares that the action is alert-triggered. The link to a specific Alert is made in the next step, by adding the action as that Alert's destination.

  4. Implement your action code
  5. Deploy using:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  tenderly actions deploy
  ```

  6. Open your Alert (**Alerts** in the left-hand menu) and add the deployed Web3 Action as its destination
</Steps>

## Understanding the Configuration

Here's what each configuration element means:

* `account_id` and `project_slug`: Identify your Tenderly account and project
* `runtime`: Specifies the runtime version for your action
* `sources`: Indicates the directory containing your action code
* `specs`: Defines the specifications for your action
* `trigger`: Configures how your action is triggered
* `execution_type`: Determines how multiple instances are handled

## Best Practices

1. Use descriptive names for your actions and alerts
2. Keep your action code modular and focused
3. Use environment variables for sensitive information
4. Test thoroughly before deployment
5. Monitor your action executions regularly

<Note>
  Following these best practices will help ensure smooth operation of your Web3Actions.
</Note>

## Troubleshooting

If you encounter issues:

* Verify the Web3 Action is added as a destination on the Alert
* Check alert conditions are properly configured
* Review Tenderly dashboard logs for errors
* Ensure CLI is up to date and properly authenticated

<Warning>
  If your action isn't triggering, first check the alert configuration and action logs in the Tenderly dashboard.
</Warning>

## Conclusion

By following this guide, you should now have a Web3Action set up to trigger based on an Alert. This powerful combination allows you to create automated, responsive systems that can react to specific blockchain events or conditions in real-time.


# Alerting Quickstart Guide
Source: https://docs.tenderly.co/monitoring/alerts/tutorials/quickstart

Learn how to set up, configure, and manage an Alert in a few easy steps.

This quick start guide shows you how to configure a Successful Transaction alert to send a notification about successful transactions coming to and from a wallet.

## Step 1: Launch the Alerts setup wizard

<Frame>
  <img alt="Alerts landing page" />
</Frame>

From the left-hand menu, **click on Alerts** to launch the Alerts setup. From here, you can create new Alerts or manage existing ones.

To create a new Alert, **click the** **New Alert** **button**, which will open up the Alert configuration settings.

<Frame>
  <img alt="Alert set up wizard" />
</Frame>

To set up a Successful Transaction alert or any other alert, you need to configure four components:

* **Alert Type:** The event you want the Alert to listen for and send you a notification when it happens. Tenderly supports [12 Alert Types](/monitoring/alerts/types).
* **Alert Target:** Here, you tell Tenderly which addresses you want to monitor. The Target options are the same across all Alert Types.
* **Alert Parameters:** Based on the Target, this is where you select the specific address(es) you want to monitor along with other settings specific to the Alert Type.
* **Alert Destinations:** Location where you want to receive notifications when the event occurs.

## Step 2: Choose the Successful Transaction Alert Type

From the list of available Alert Types, **select Successful Transaction** to monitor when a successful transaction happens.

<Frame>
  <img alt="Available Alert trigger types" />
</Frame>

<Note>
  Some Alert Types are self-explanatory, while others are more nuanced, so please refer to the
  [Alert Trigger Types documentation](/monitoring/alerts/types) page for detailed
  explanations of each.
</Note>

## Step 3: Set the Alert Target to Address

The Alert Target section is where you tell Tenderly which address(es) you’d like to monitor and where they are located.

The available Target options are the same for all Alert Types and include:

* **Address:** Monitor a single smart contract or wallet
* **Network:** Monitor all transactions on a specific network
* **Project:** Monitor all addresses that are part of your Tenderly Project
* **Tag:** Monitor all contracts and wallets labeled with the specific tag

In our case, we’ll **choose Address** because we want to monitor a single address of our wallet.

<Frame>
  <img alt="Available Alert Targets" />
</Frame>

## Step 4: Set the wallet address as the Target Parameter

With the Target set to Address, we need to tell Tenderly which wallet address we want to monitor. Tenderly will pull all the smart contracts and wallets associated with your project and display them in a dropdown.

<Note>
  If you haven’t added any smart contracts or wallets to your Tenderly Project, follow these quick
  guides to learn how to add a [wallet](/developer-explorer/wallets) or a [smart
  contract](/developer-explorer/contracts). Alerts are evaluated only for your project's addresses,
  so the address you want to monitor must be added to the project. If the added address makes the
  project's Transactions view noisy, you can [hide it from the transaction
  listing](/developer-explorer/contracts#hide-a-contract-from-the-transaction-listing) without
  affecting Alerts.
</Note>

From the dropdown, we’ll select the address of the Tenderly Wallet.

<Frame>
  <img alt="List of smart contracts and wallets associated with the project" />
</Frame>

## Step 5: Choose Email as the Alert Destination

To keep things simple, we want to receive an email notification informing us about successful transactions coming to and from our Tenderly Wallet.

**Select Email as the Alert Destination** and fill out the required details, including the email address. If you’re adding a new email address, you’ll have to confirm that you’re the owner to be able to receive notifications there.

<Frame>
  <img alt="Setting Email as the Alert Destination" />
</Frame>

When a Successful Transaction event occurs on our wallet, Tenderly will send us an email notification with important information about the event and links to Tenderly Dashboard to inspect it further.

<Frame>
  <img alt="Email notification from Tenderly" />
</Frame>

In addition to [email](/monitoring/alerts/destinations/account-scoped#email-destination), you can also receive notifications in your favorite messaging app:

\**Click on the link for each destination to learn how to set it up.*

* [**Slack**](/monitoring/alerts/destinations/account-scoped#slack-destination)
* [**Telegram**](/monitoring/alerts/destinations/account-scoped#telegram-destination)
* [**Discord**](/monitoring/alerts/destinations/account-scoped#discord-destination)

Or you can send alert data to other Tenderly systems:

* [**Web3 Actions**](/monitoring/alerts/destinations/project-scoped#web3-actions)
* [**Webhooks**](/monitoring/alerts/destinations/project-scoped#webhooks)

Or third-party incident and error monitoring platforms like:

* [**Sentry**](/monitoring/alerts/destinations/account-scoped#sentry-destination)
* [**PagerDuty**](/monitoring/alerts/destinations/account-scoped#pagerduty-destination)

With the Alert Destination all set, **click Save** to create and enable the Alert.

<Note>
  Notifications from a single Alert can be sent to multiple Destinations. Likewise, you can have
  multiple Alerts send notifications to a single Destination. Once you add a Destination for the
  first time, it can be used by Alerts you create in the future.
</Note>

## Step 6: Managing Alerts and Destinations

All deployed Alerts can be managed from the **Rules** view. Click an Alert to open it and reveal the management options: **Enable/Disable**, **Trigger Test Alert**, **Duplicate Alert**, **Edit**, or **Remove**.

<Frame>
  <img alt="Managing an existing Alert" />
</Frame>

If you **click on History** in the top menu, you can view when and how many times your Alerts were executed.

<Frame>
  <img alt="History of Alert execution" />
</Frame>

And if you navigate to the **Destinations tab**, you can manage all previously created Destinations or create new ones.

Once you create a Destination, it will be accessible from all your projects, so you don’t have to create the same Destination in another project.

The exceptions are Web3 Actions and Webhooks as Alert Destinations. These Destinations are visible only under the project where they were created.

If you **edit or delete** a Destination, the changes will be applied across all your projects and active rules.

<Frame>
  <img alt="List of created Alert Destinations" />
</Frame>

## Wrapping up

In this guide, you learned how to set up and configure a Successful Transaction alert that sends an email notification about all successful transactions coming to and from a wallet.


# How to Use Webhooks for Alerting
Source: https://docs.tenderly.co/monitoring/alerts/tutorials/webhooks

Learn how to create your first webhook and start receiving alerting events.

Welcome to this guide on how to create a webhook as an alert destination to receive events from an alerting service. In this guide, you will learn how to set up a webhook and see its execution.

### Adding a webhook as an alert destination

<Note>
  To continue, [log into your account](https://dashboard.tenderly.co/) or [create a free
  account](https://dashboard.tenderly.co/register) if you don’t have one.
</Note>

Once logged in, create a new [Tenderly project](/platform/account/projects/overview) or select an existing one where you want to create your Webhook.

From the left-hand menu, go to **Alerts → Destinations** tab, where you'll see a list of [all the available destinations](/monitoring/alerts/destinations/overview).

<Frame>
  <img alt="Navigating to the Destination section" />
</Frame>

To create a webhook alert destination, click on the Webhook card, which will open up the configuration modal. You'll be prompted to configure the following options:

* **Webhook name** - Must be unique and cannot be changed later
* **Webhook URL** - URL where you'll receive live events from Tenderly
* **Description** - Optional parameter, but you can use it to provide more information about the webhook configuration

<Frame>
  <img alt="Add Webhook Modal" />
</Frame>

If you click on the **Advanced Configuration** link, a modal will open with JavaScript, Python, or Go code snippets that you can use to set up your custom webhook.

<Frame>
  <img alt="Webhook Modal Advanced Configuration Modal" />
</Frame>

To test if the provided URL is able to receive events from Tenderly, click on the **Send test webhook** button, and the predefined test payload will be sent to your endpoint.

<Frame>
  <img alt="Send Test Webhook" />
</Frame>

If everything works as expected and you've received the event, click on the **Add Webhook** button. This action will add the new webhook destination to the **Active Destinations** list.

<Frame>
  <img alt="New Webhook is added to the active destinations list" />
</Frame>

Clicking on the button to the right will open up the Webhook overview page. This is where you can find information about the webhook status, URL, creation date, signing secrets, etc.

<Frame>
  <img alt="Webhook Page" />
</Frame>

You can also perform other actions on your webhook from the overview page. The **Disable Webhook** button toggles the webhook between active and inactive, and the three-dot menu in the top right holds the **Edit Webhook** and **Delete Webhook** options.

**Enable/Disable Webhook:** Toggle the status of a webhook between active and inactive.

**Delete Webhook**: Remove a webhook from your Tenderly project. Deleting a webhook is a permanent action and cannot be undone.

<Frame>
  <img alt="Webhook Options" />
</Frame>

**Send a Test Request:** Test the functionality of your webhook by sending a test event to the provided URL by providing a transaction hash with its network.

<Frame>
  <img alt="Test Webhook Modal" />
</Frame>

**Edit Webhook**: Modify the configuration of an existing webhook, such as the URL or description.

<Frame>
  <img alt="Edit Webhook Modal" />
</Frame>

### Webhook execution history

From the webhook overview page, click on Execution History to see the transaction payload that has been sent to the provided webhook URL and the response from the webhook endpoint.

<Frame>
  <img alt="Manually Triggered Webhook After Clicking on Test Webhook Button" />
</Frame>

Webhook execution can have several statuses:

* **Success:** Webhook was successfully executed, and the event was delivered to the specified URL.
* **Failed**: Webhook was unable to be executed due to an error, such as a connectivity issue, a problem with the URL, or something else. Check the response content to see what caused the error, or contact our support.
* **Pending**: Webhook is in the process of being executed and has not yet been completed.
* **Retry**: Webhook execution failed and will be retried; an event is delivered in at most 5 total attempts before the status settles at Success or Failed.
* **Skipped**: Webhook was not executed because it was disabled.

<Frame>
  <img alt="Webhook Execution Page" />
</Frame>

You can also see prior webhook executions by applying different filters, such as **Filter by Status** and **Select a Date Range**.

<Frame>
  <img alt="Webhook Execution History Page" />
</Frame>

<Frame>
  <img alt="Select Webhook Status Dropdown" />
</Frame>

<Frame>
  <img alt="Select Date Range Dropdown" />
</Frame>

### Connecting a webhook to an Alert

With your webhook endpoint configured, you can add it as a Destination to any of your Alerts.

<Info>
  [Follow this guide](/monitoring/alerts/tutorials/quickstart) to learn how to set up an Alert.
</Info>

<Frame>
  <img alt="Adding a Webhook as a Destination to the Alert Rule" />
</Frame>

When you create an Alert rule, you'll be redirected to the following page:

<Frame>
  <img alt="Alert Rule with a Webhook as a Destination" />
</Frame>

If your Alert is enabled, you'll start receiving events to your webhook endpoint.

<Frame>
  <img alt="Webhook Execution History Page" />
</Frame>

In this example, we used [https://webhook.site](https://webhook.site/) to create a temporary webhook endpoint to test how Tenderly webhooks work. Below is an image of the payload successfully sent to the webhook.

<Frame>
  <img alt="Successful Webhook Executions" />
</Frame>


# Intro to Web3 Actions
Source: https://docs.tenderly.co/monitoring/web3-actions/introduction

Deploy custom JS/TS functions that hook into on-chain events to build active monitoring, serverless dapp backends, and service integrations.

<Note>
  Web3 Actions are available on the paid plan. To enable them for your account, [contact our sales team](https://tenderly.co/contact-us).
</Note>

### What are Web3 Actions?

Web3 Actions are programmable hooks for smart contract and chain events. They can also be serverless backends for your dapps. A Web3 Action is a regular TypeScript/JavaScript function that runs on Tenderly infrastructure.

A Web3 Action comes with key-value storage for data you need to persist and secrets management for sensitive information such as API keys. You can think of Web3 Actions as infrastructure building a Web3 version of IFTTT/Zapier automation, allowing you to glue together your smart contracts, on-chain events, dapp frontends, APIs, and other services.

Based on the trigger rules you define, external on-chain or off-chain events will trigger your Web3 Action and your JavaScript/TypeScript code will handle the event instantly. Web3 Actions run either in **sequential mode** (default) or **parallel**.

In sequential mode, actions run in the order of triggering. In parallel mode, actions execute with no particular order compared to the time of triggering. The choice applies only to **block** and **transaction** triggers. **Periodic** and **webhook** triggers always run in parallel, and **alert** triggers always run sequentially; `execution_type` has no effect for them.

With Web3 Actions, you can build systems that let you be timely informed about non-trivial events. This way, you can improve your dapp in terms of UX and interactivity and enhance your project through the depth of information you can collect or share through notifications.

To get an idea of what’s possible with Web3 Actions, here are some use cases:

* **Watch out for important transactions**: Build a real-time(ish) data-rich notification system for events emitted from a contract by sending messages to Discord, Slack, or Telegram or posting it to a database.
* **When a block is mined**: Monitor changes in on-chain assets or gas prices to build customized analytics and automation. Then, post the data to an external API.
* **Expose a webhook**: Enhance your dapp by exposing a webhook that handles users' inputs.
* **Periodic automation**: Periodically simulate a transaction execution using [Tenderly simulations](/simulator-ui/overview#simulating-a-transaction) and send the results to Slack and/or even send the transaction to the chain to achieve automation.

For more ideas, check out the [Use cases for Web3 Actions and different events](/monitoring/web3-actions/introduction#use-cases-for-web3-actions-and-different-events) section.

<Note>
  Web3 Actions are rate-limited per action: 400 executions/5 minutes for sequential actions and
  2000 executions/5 minutes for parallel actions. Any extra executions are skipped. See
  [Usage Rate Limits](/monitoring/web3-actions/usage-rate-limits).
</Note>

### Quickstart guides

Follow these guides to quickly get started with building Web3 Actions via the browser or command line tools.

Setting up Web3 Actions requires you to write JavaScript code for your functions. Building your Web3 Actions using Tenderly CLI includes defining triggers in a [yaml configuration file](/monitoring/web3-actions/references/project-structure#the-tenderlyyaml-file-structure). The defined trigger and yaml configuration become an integral part of your project’s codebase.

* [Deploy Web3 Actions via Tenderly Dashboard](/monitoring/web3-actions/tutorials/deploy-via-dashboard): Learn how to set up and deploy Web3 Actions directly in your browser.
* [Deploy Web3 Actions via Tenderly CLI](/monitoring/web3-actions/tutorials/deploy-via-cli): Learn how to install the Tenderly CLI, define triggers using the YAML configuration, and set up and deploy Web3 Actions through the command line.

<Note>
  To set up Web3 Actions triggered by transaction-related events, you must use the CLI-based
  approach.
</Note>

<Card title="CLI Cheatsheet" href="/monitoring/web3-actions/references/cli-cheatsheet" />

### Understanding Web3 Actions

In a nutshell, Web3 Actions instruct Tenderly to listen for a specific external event to occur and run your code as events happen.

You need to provide a **trigger specification** that is related to a pre-defined external event. A Web3 Action can be triggered every few blocks as they’re mined (block trigger), when a relevant transaction is executed (transaction trigger), via a webhook it exposes (webhook trigger), at specific time intervals (periodic trigger), or when one of your Alerts fires (alert trigger).

When the event occurs, Tenderly executes your custom code (function). Here, monitoring becomes active. You can send data to an external API, write to a database, deliver a push notification or a data-rich message through messaging services, or even send a new transaction to the blockchain, to name a few examples.

Let’s get familiar with the three core elements of Web3 Actions: **functions**, **events**, and **trigger specification**.

<Frame>
  <img alt="The elements of Web3 Actions" />
</Frame>

**Functions:** The custom JavaScript or TypeScript code you want to execute when an external event you specified occurs. Functions can be written directly in the browser through the Tenderly Dashboard or using the CLI (within an npm project). In both cases, the function must be a named export from the defining file.

**Events:** Instances of pre-defined external events that you can listen for by configuring a trigger. The function receives the event object as an argument, making the data about the event available to your function code. These are supported events:

* **Block:** Run a function each time a block is mined.
* **Periodic:** Run a function at specific intervals.
* **Webhook:** Call the Web3 Action via HTTP.
* **Transaction:** React to contract transactions that match a specific filter.
* **Alert:** Run a function when one of your [Alerts](/monitoring/alerts/introduction) fires, with the Web3 Action set as the [alert destination](/monitoring/alerts/destinations/web3-action). Alert-triggered actions always run sequentially.

**Trigger specification:** A schema or a pattern describing external events your Web3 Action should listen for.

When building a Web3 Action, you have to link the trigger specification to the function you wish to run. Tenderly executes your custom code (function) when it detects the event specified in the trigger.

Learn how to configure [Web3 Action Functions, Events, and Triggers](/monitoring/web3-actions/references/functions-events-triggers).

#### Web3 Actions Utilities

**Error reporting:** An overview in the Tenderly Dashboard where you can find errors and incidents that have occurred during the execution of your Web3 Action and re-execute failed ones. Learn more about [Error Handling in Web3 Actions](/monitoring/web3-actions/references/error-reporting).

**Secrets:** A place to store sensitive data such as API keys that are called from inside your code. This information is stored in the Tenderly Dashboard and can only be read from your code.

**Storage:** Project-wide key-value storage you can use to persist data between consecutive runs. You can read and write to Storage through the Tenderly Dashboard. Learn how to [manage Secrets and use Web3 Actions Storage](/monitoring/web3-actions/references/context).

<Frame>
  <img alt="Web3 Action Storage and Secrets" />
</Frame>

#### Local development and testing support

To quickly iterate when writing your Web3 Action functions, explore how the `@tenderly/actions-test` npm package provides [support for testing and local development of action function code](/monitoring/web3-actions/references/local-development).

### Use cases for Web3 Actions and different events

Below is a brief overview of each event type and example use cases.

🧾 **Transaction event:** Listens for a transaction event that matches a given set of criteria, successful or failed transaction, value transfers, a particular amount of gas a transaction used, event emitted, and much more. Learn about [Transaction events](/monitoring/web3-actions/references/functions-events-triggers#transaction-event).

Example use cases:

* Collect specific data about transactions as they happen and store them in Tenderly Storage.
* Send the data about a transaction to other (Web2 or Web3) services via HTTP.
* Send data-rich notifications about wanted or unwanted transactions through your communication channels, such as Discord.
* Send a transaction to the chain from a Web3 Action itself.

🔢 **Block event:** Listens for an event when a block is mined on a selected network. Learn about [Block events](/monitoring/web3-actions/references/functions-events-triggers#block-event).

Example use cases:

* Monitor changes in on-chain assets to build customized analytics and automation.
* Monitor smart contract changes once every few blocks get mined and run automation when a condition is met.
* Monitor gas prices and automate your operations.

🪝 **Webhook event:** Listens for an event **when** an HTTP request is posted to the Webhook URL (the action exposes a WebHook). Learn about [Webhook events](/monitoring/web3-actions/references/functions-events-triggers#webhook-event).

Example use cases:

* Build a serverless backend that handles your dapp users' input.
* Retrieve the data your other Web3 Actions collected about transactions or specific smart contract changes.
* Your CI can call the webhook to clean up or prepare other Tenderly resources such as the [Virtual Environments you use for testing](/virtual-environments/overview).

🕖 **Periodic event:** Listens for an event representing a passage of a time interval or CRON expression you specify. Learn about [Periodic events](/monitoring/web3-actions/references/functions-events-triggers#periodic-event).

Example use cases:

* Periodically send notifications with custom data collected from the network and/or aggregated in Web3 Action Storage.
* Simulate a DAO proposal and send a voting reminder to Discord.
* Simulate a transaction execution using Tenderly simulations and send the outcome to Slack and/or send the transaction on-chain to achieve automation.
* Periodic cleanup of Tenderly infrastructure (e.g., point a Fork to the latest block on the Mainnet before continuing simulations).

### Web3 Actions tutorials

If you want a full tutorial, here’s a step-by-step guide for monitoring an on-chain Tic-Tac-Toe game, with all relevant explanations, from deploying the game contract to displaying the board after a move.

<Card title="How to Handle On-Chain Events" href="/monitoring/web3-actions/tutorials/on-chain-events" />

To see how to build a Web3 Action to send a message to Discord when a Uniswap pair is created and fetch some data using Axios, this is the place:

<Card title="How to Send a Discord Message About a New Uniswap Pool" href="/monitoring/web3-actions/tutorials/discord-uniswap-pools" />

To deploy your own simple Oracle in a Tenderly Web3 Action, explore this tutorial:

<Card title="How to Build a Custom Oracle" href="/monitoring/web3-actions/tutorials/custom-oracle" />

To see how a Web3 Action can use Virtual Environments to simulate a transaction submitted to a multisig wallet and send Discord messages with simulation outcomes, try this one:

<Card title="Web3 Actions + Multisig wallet" href="https://github.com/Tenderly/examples-web3-actions/tree/main/multisig-wallet" />

### Resources

Here you can find all the relevant information about the main building blocks and accompanying tools:

Find details about the Web3 Actions project structure and general layout of the **tenderly.yaml** configuration file:

<Card title="Project Structure" href="/monitoring/web3-actions/references/project-structure" />

Find detailed information about the core components of Web3 Actions and writing trigger configuration in **tenderly.yaml**:

<Card title="Action Functions, Events, and Triggers" href="/monitoring/web3-actions/references/functions-events-triggers" />

Learn about using Storage and Secrets:

<Card title="Context: Gateway, Storage, Secrets" href="/monitoring/web3-actions/references/context" />

Learn about tools for local development and testing of Web3 Actions:

<Card title="Local Development and Testing" href="/monitoring/web3-actions/references/local-development" />

Learn about utilities for inspecting and handling failed executions of Web3 Actions in the Tenderly Dashboard:

<Card title="Error Reporting" href="/monitoring/web3-actions/references/error-reporting" />

Learn how to operate Web3 Actions: stopping, upgrading, and running Web3 Actions manually:

<Card title="Stopping, Upgrading, and Manually Running Web3 Actions" href="/monitoring/web3-actions/references/lifecycle" />


# CLI Cheatsheet
Source: https://docs.tenderly.co/monitoring/web3-actions/references/cli-cheatsheet

Follow a step-by-step guide and a cheat sheet of CLI commands for initializing, building, and deploying Web3 Actions.

This guide shows the commands you need to initialize, build, and deploy a Web3 Action project using Tenderly CLI.

**Step 1: Install the Tenderly CLI**

Use the `curl` command to download and install the Tenderly CLI binary on your local machine.

Install on macOS:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl https://raw.githubusercontent.com/Tenderly/tenderly-cli/master/scripts/install-macos.sh | sh
```

Install on Linux:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl https://raw.githubusercontent.com/Tenderly/tenderly-cli/master/scripts/install-linux.sh | sh
```

**Step 2: Log in to Tenderly via the CLI**

Log into the Tenderly CLI with your credentials by running this command:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
tenderly login
```

**Step 3: Initialize a Web3 Actions project**

To initialize a Web3 Action project, run this command:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
tenderly actions init
```

You can change the default initialization settings with three flags: `--sources` sets the name of the root Web3 Actions folder (default: `actions`), `--language` sets the language for writing Action functions (`typescript`, the default, or `javascript`), and `--template` initializes the project from a starter template in the [Tenderly/tenderly-actions](https://github.com/Tenderly/tenderly-actions/tree/main/templates) repository.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
tenderly actions init --sources=actions --language=typescript

# initialize from a starter template
tenderly actions init --template=webhook-event
```

You’ll be prompted to add your Web3 Actions to a Tenderly project. You can either create a new project or pick an existing one.

**Step 3**: **Install any NPM dependency you need**

After running `tenderly actions init`, you have an NPM project at your disposal, so you can install any NPM library you need in a familiar way.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
cd actions
npm i --save-dev axios ethers
cd ..
```

**Step 4: Build and deploy Web3 Actions**

After you have written your function and trigger configuration in **tenderly.yaml**, you can run these commands to build and deploy the Web3 Action.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# run within the folder containing tenderly.yaml

# Build the project (optional)
tenderly actions build

# Upload the project to Tenderly WITHOUT activating it
tenderly actions publish

# Upload AND activate the project (or re-deploy any changes you make)
tenderly actions deploy
```

Shortly after running `deploy`, your Web3 Action is available in the Dashboard and listening to events per your configuration. A `publish`-ed action is visible in the Dashboard but stays inactive: it isn't scheduled and doesn't listen to events until you run `deploy` or start it from the Dashboard.

<Note>
  You can upgrade your Web3 Actions with zero downtime, by running the `deploy` command after
  you’ve edited the function and trigger configuration.
</Note>

**Optional: Validate your tenderly.yaml**

Before deploying, you can validate the structure and trigger configuration of your `tenderly.yaml` locally. No login is required.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Validate all projects in tenderly.yaml
tenderly actions validate

# Validate a single project only
tenderly actions validate --project username/project-slug

# Machine-readable JSON output (useful in CI pipelines)
tenderly actions validate --json
```

The `--json` flag emits a structured result. When everything is valid:

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{ "valid": true }
```

When validation fails, `schema_errors` and/or `trigger_errors` are included (omitted when empty):

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "valid": false,
  "schema_errors": ["..."],
  "trigger_errors": [
    { "project": "my-org/my-project", "action": "myAction", "errors": ["..."] }
  ]
}
```

**Optional: Generate a JSON Schema for your editor**

The `schema` command outputs a JSON Schema describing the `actions` section of `tenderly.yaml`. Use it with the VS Code YAML extension (`redhat.vscode-yaml`) or JetBrains IDEs to get autocomplete and validation while editing the file.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Print the schema to stdout
tenderly actions schema

# Write the schema to a file
tenderly actions schema --output tenderly-schema.json
```

**Optional: Explore supported features**

To see a machine-readable manifest of all supported trigger types, runtimes, execution types, and intervals:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Print the capabilities manifest
tenderly actions capabilities

# Include the full embedded JSON Schema in the output
tenderly actions capabilities --include-schema
```

This is useful for editor integrations and tooling that need to discover what the CLI supports without parsing documentation.

**Optional: Using Tenderly Runtime locally**

Install the [**@tenderly/actions-test**](https://github.com/Tenderly/tenderly-actions/tree/main/packages/actions-test) package to test your Web3 Action Functions locally.

Assuming you're already in an npm project, run the following:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
npm install @tenderly/actions-test
```

<Note>
  It’s recommended to keep tests and run scripts for web3-actions outside of the actions directory,
  to avoid increasing the size of your Web3 Actions project.
</Note>

Check out a [guide on local development and testing of Web3 Actions](/monitoring/web3-actions/references/local-development) for more detail and examples.


# Context: Gateway, Storage, Secrets
Source: https://docs.tenderly.co/monitoring/web3-actions/references/context

Access blockchain via Node RPC, store and fetch data from Storage, and save sensitive information like API keys in Secrets.

This guide provides an overview of the `context` object and how to use it to get access to Gateway, Storage, and Secrets utilities within Web3 Actions.

You’ll also learn how to access [Node RPC](/node-rpc/overview) through `context`, how to manage and access private data such as API keys with Secrets, how to persist data to Storage, and how to access this data from your application.

### Context

`context` is an object that gives you access to Storage and Secrets from within your code. Context is the first parameter that needs to be specified in your functions, enabling access to the execution context when Tenderly runs your code.

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export const actionFun: ActionFn = async (context: Context, event: Event) => {
  // ...
  await context.storage.putJson(key, storedValue);
};
```

<Note>
  Storage and Secrets are shared between all Actions within a project in Tenderly.
</Note>

#### Gateways

The Gateways utility (`context.gateways`) gives you access to [Node RPC](/node-rpc/overview), allowing you to send transactions or read on-chain data with Web3 Actions.

The `gateways` property gives you access to a method called `getGateway()`, which requires one argument - the network you want to access. To access the Mainnet, for example, the argument needs to be formatted like this `Network.MAINNET`.

An example of a completed statement stored in a variable looks like this:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const defaultGatewayURL = context.gateways.getGateway(Network.MAINNET);
```

The `Network` enum has a member for every network supported in Node RPC, for example:

* `Network.MAINNET`
* `Network.SEPOLIA`
* `Network.POLYGON`
* `Network.OPTIMISTIC`
* `Network.BASE`
* `Network.ARBITRUM`

For the full list, see [`networks.ts` in the `@tenderly/actions` package](https://github.com/Tenderly/tenderly-actions/blob/main/packages/actions/src/networks.ts).

For more details about how `context.gateways` works and sample code snippets to help you understand how to use it, read through the [**Node RPC access on the Web3 Actions**](/node-rpc/overview) documentation page.

### Storage

You can use the Storage utility to make your Web3 Actions stateful. Web3 Actions Storage is a key-value-based store. You can save data to Storage both from your custom code (functions) and the Tenderly Dashboard.

Below is a code snippet that shows you how to store JSON objects to Storage.

```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
await context.storage.putJson(key, valueStored);
```

<Note>
  All functions that interact with Storage are asynchronous, so you need to use the `await` operator
  to avoid undesired behavior.
</Note>

#### Saving and retrieving data from Storage

To save data to Storage, use the following functions, which store values of their respective type:

* `putBigInt`
* `putStr`
* `putNumber`
* `putJson`

To retrieve data from Storage, use the following functions to fetch a specific data type:

* `getBigInt`
* `getStr`
* `getNumber`
* `getJson`

Below is an example of how to save and fetch a JSON object from Storage.

```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
await context.storage.putJson('BAR_BAZ', { bar: 'baz' });
//....
const barBaz = await context.storage.getJson('BAR_BAZ');
```

#### Storage Limits

| Limit                    | Value  |
| ------------------------ | ------ |
| Maximum keys per project | 1,000  |
| Maximum key size         | 1 KB   |
| Maximum value size       | 100 KB |

If the limits get exceeded, the client will surface a `400 Bad Request` error with a message indicating the specific limit that was breached.

Storage is project-wide, all actions in a project share the same key pool.

<Warning>
  Storage is not a database, it’s for small stateful data like config parameters or counters. For large datasets or high-frequency operations, use an external database and store credentials in [**Secrets**](/monitoring/web3-actions/references/context#secrets).
</Warning>

#### Accessing Storage via the Tenderly Dashboard

To view data saved to Storage via the **Tenderly Dashboard**, go to **Web3 Actions** from the left-hand menu and click **Storage** from the page menu.

<Frame>
  <img alt="Accessing Web3 Action data saved to Storage" />
</Frame>

### Secrets

Secrets are used to store sensitive information such as private API keys for services that your Web3 Action might call during the execution. Secrets are stored as key-value pairs and are comprised of the name and secret value.

#### Creating and storing Secrets

The only way to create secrets is via the **Tenderly Dashboard**. Go to **Web3 Actions** from the left-hand menu and click **Secrets** from the page menu.

Add Secrets by clicking the **Add Secret** button and provide the key name and value.

<Frame>
  <img alt="Creating Secrets for Web3 Actions" />
</Frame>

#### Fetching Secrets data from inside your code

You can fetch Secrets data from within your code using the `context`object with the `get()` method. As the argument, use the exact key name you specified via the Tenderly Dashboard.

```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const fooApiKey = await context.secrets.get('FOO_API_KEY');
```


# Error Reporting
Source: https://docs.tenderly.co/monitoring/web3-actions/references/error-reporting

Access the Error Reporting section for Web3 Action execution incidents. Filter incidents by parameters and re-run failed ones.

When your [Web3 Action](/monitoring/web3-actions/introduction) fails, the failure is recorded as an **Incident**. Incidents group failures by Action version and error: the first occurrence of an error creates a new incident, and repeated occurrences of the same error are added to it. You can access incidents in the Actions section in the main navigation tree, through the sub-tab **Error Reporting**:

<Frame>
  <img alt="Opening the Error Reporting tab" />
</Frame>

You can filter the incidents by status as well as a date range.

<Frame>
  <img alt="Filtering Web3 Action error reports" />
</Frame>

## Incident statuses

An incident has one of three statuses. Besides note-keeping and team collaboration, the status controls [failure email notifications](/monitoring/web3-actions/references/notifications#when-failure-emails-are-sent):

* **Ongoing** - the status an incident is created with. Repeated occurrences of the same error are grouped under the incident and don't trigger additional emails.
* **Acknowledged** - marks the incident as seen. Emails for the incident's error stay muted, same as Ongoing.
* **Resolved** - closes the incident and re-arms notifications: if the same error occurs again, a new incident is created and you receive a new email.

Incidents are never resolved automatically, even if later executions succeed. When you open a specific incident, you will see each and every instance of your Action executing with all the info about how the execution went.

<Frame>
  <img alt="Changing the incident status" />
</Frame>

You can also explore a detailed view for each of the incidents, and see the [execution status](/monitoring/web3-actions/references/execution), errors, payload, and logs for each individual execution of your Actions:

<Frame>
  <img alt="Examining a Web3 Action incident in detail " />
</Frame>

If you would like to test changes to your Action configuration through Execution History and see how changes to your Action would impact its previous executions, you can rerun single, multiple, or all of the incidents at any point.

<Frame>
  <img alt="Re-running incident executions" />
</Frame>


# Action Execution
Source: https://docs.tenderly.co/monitoring/web3-actions/references/execution

Status reference for Web3 Action executions in Tenderly, with default execution limits and the conditions that create incidents.

## Web3 Action Execution Status Types

Each execution of a [Web3 Action](/monitoring/web3-actions/introduction) carries one of the following statuses. The literals below are the values the API returns and the dashboard execution-history filter matches on; the dashboard may show a friendlier label (for example, "Success" for `SUCCEEDED`).

* **`PENDING`** - The execution has been created but not yet submitted. Manual runs and re-runs hold this status before submission.
* **`SUBMITTED`** - The execution has been submitted and is running. This status is temporary and changes once execution completes.
* **`SUCCEEDED`** - The execution completed without errors.
* **`SKIPPED`** - The execution was intentionally not run, typically because a condition or rule wasn't met.
* **`FAILED`** - The action code threw an error during execution.
* **`TIMED_OUT`** - The execution did not complete within the execution time limit (30 seconds by default).
* **`RATE_LIMITED`** - The trigger fired more often than the allowed rate. Rate-limited trigger events are dropped, not queued; the execution is not retried.
* **`TU_QUOTA_REACHED`** - The account's usage quota was exhausted when the trigger fired. The execution is dropped and not retried.

## Execution limits

Each execution runs with a 30-second time limit and 128 MB of memory by default.

<Note>
  If you need higher limits for your action execution, or if your action timed out, contact
  Tenderly support at [support@tenderly.co](mailto:support@tenderly.co).
</Note>

<Frame>
  <img alt="Web3 Action Execution History" />
</Frame>

## When an execution creates an incident

An incident is logged in [Error Reporting](/monitoring/web3-actions/references/error-reporting), and failure notification emails are sent, only when a trigger-based execution ends in `FAILED`. Manual runs never create incidents, regardless of outcome, and executions ending in `TIMED_OUT`, `RATE_LIMITED`, or `TU_QUOTA_REACHED` do not create incidents or send failure emails. Rate-limited executions are reported separately in a batched notification email, at most one per action per 24 hours (see [Usage Rate Limits](/monitoring/web3-actions/usage-rate-limits)).


# Action Functions, Events, and Triggers
Source: https://docs.tenderly.co/monitoring/web3-actions/references/functions-events-triggers

Explore Web3 Actions core elements, configure triggers for supported events, and link triggers to action functions in tenderly.yaml.

This guide presents the three core concepts of Web3 Actions: **triggers, events, and functions**. You’ll learn how they work and how to use them to build your own Web3 Actions.

The three core components that make up a Web3 Action are:

* **Functions:** Custom JavaScript or TypeScript code you want to execute when an external event occurs. This is the core of your automation.
* **Triggers:** Pre-defined external events that your Web3 Action is configured to listen for. When the event occurs, the trigger instructs Tenderly to execute your custom code (function).
* **Events (Trigger Types):** Pre-defined external events that you can listen for by setting a trigger. When the event occurs, the trigger will call your custom code (functions).

### Execution Types

Web3 Actions in Tenderly can be executed in two modes: **Sequential** and **Parallel**.

<Warning>
  `execution_type` only applies to **block** and **transaction** triggers. **Periodic** and **webhook** triggers always run in parallel, and any `execution_type` set on them is ignored.
</Warning>

<Frame>
  <img alt="Web3 Action Execution Type step in the Web3 Action UI Builder" />
</Frame>

#### Sequential Execution

In sequential execution, actions are executed one by one in the order they were invoked. This is the default mode of execution. In this mode, each action waits for the previous action to complete before it begins execution. Here's an example of an action configuration for a sequential execution:

```diff title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
our-org/our-cool-project:
  runtime: v2
  sources: actions
  specs:
    bestActionEver:
      description: Does the best thing ever
+     execution_type: sequential
      function: very/organized/file:bestActionEver
      trigger:
        ...
```

#### Parallel Execution

In parallel execution, actions are executed in parallel, which leads to higher throughput. In this mode, the order of execution is not guaranteed and there may be possible race conditions with [action storage](/monitoring/web3-actions/references/context#storage). Here's an example of an action configuration for a parallel execution:

```diff title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
our-org/our-cool-project:
  runtime: v2
  sources: actions
  specs:
    bestActionEver:
      description: Does the best thing ever
+     execution_type: parallel
      function: very/organized/file:bestActionEver
      trigger:
        ...
```

### Action functions

Web3 Action functions refer to the custom code written as standard JavaScript or TypeScript functions, but they must adhere to some rules.

* Functions must be asynchronous, returning `Promise<void>`
* Functions accept two parameters: `context` and `event`
* Functions must be a named export from the file
* Functions can be placed in any file under the *actions root* directory

Learn about the [Web3 Actions project and file structure](/monitoring/web3-actions/references/project-structure).

When a Web3 Action function is deployed, the Tenderly runtime will pass the following arguments during invocation:

* The `context` parameter that holds access to [Storage and Secrets](/monitoring/web3-actions/references/context).
* The `event` parameter that is an object with information answering the question *“what just happened?*”. This parameter contains data specific to the trigger type the Web3 Action function is listening for. The section [Specifying triggers for external events](/monitoring/web3-actions/references/functions-events-triggers#specifying-triggers-for-external-events) goes into detail about external events.

<Note>
  The execution of Web3 Action functions is limited to 30 seconds. If your function takes longer
  than 30 seconds to execute, it will be terminated.
</Note>

Here’s an example of a Web3 Action function written in TypeScript. The `event` parameter can be any one of the supported trigger types (events).

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// File: actions/myCoolTsFile.ts

// importing ethers available in Tenderly Runtime

export const awesomeActionFunction: ActionFn = async (context: Context, event: Event) => {
  // cast the event parameter to an appropriate type, based on the Trigger
  // this function subscribed to.
  // Of course, only one of these casts makes sense
  const blockEvent = event as BlockEvent;
  const periodicEvent = event as PeriodicEvent;
  const transactionEvent = event as TransactionEvent;
  const webhookEvent =  event as WebhookEvent;
	...
}
```

#### Available libraries for dashboard-based actions

The Tenderly runtime comes pre-bundled with several javascript libraries that you can import when creating Web3 Actions via the Tenderly Dashboard. Available libraries include:

* [Ethers.js](https://docs.ethers.io/v5/)
* [Bignumber.js](https://mikemcl.github.io/bignumber.js/)
* [Axios](https://axios-http.com/docs/intro)
* [Luxon](https://moment.github.io/luxon/#/?id=luxon)

To import any of these libraries, use the `require()` function as you would with a standard npm-based project (without ES6).

Example import for Axios looks like this:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const axios = require('axios');
```

#### Using npm libraries for CLI-based Web3 Actions

The project created by Tenderly CLI is in fact an npm module. You can install any npm package from your *actions root* folder.

### External events and trigger types

When an external event happens, it *triggers the execution of your custom code* (functions). You can choose between five external events to listen for:

* **Block event**: A block is mined on a selected network.
* **Periodic event:** This trigger happens when certain time intervals pass or based on CRON expressions.
* **Webhook event:** An HTTP request is posted to the webhook URL (the Web3 Action exposes a webhook)
* **Transaction event:** A transaction matching given filter criteria is executed on a selected network.
* **Alert event:** One of your [Alerts](/monitoring/alerts/introduction) fires with the Web3 Action set as its [destination](/monitoring/alerts/destinations/web3-action).

When defining a Web3 Action, you'll be effectively defining triggers that react to external events of interest for your project. In the context of trigger specification, we'll be using the term **trigger type**.

<Info>
  You should write separate functions for each trigger type. Using the same function for different
  trigger types is not recommended.
</Info>

### Subscribing Web3 Action functions to events

In addition to defining your action function in JavaScript, you also need to provide the trigger configuration, which tells Tenderly **what triggers it, the external event your function subscribes to.**

When creating Web3 Actions via the Tenderly Dashboard, the creation flow in the UI will handle this part for you. Read the [Dashboard Quickstart](/monitoring/web3-actions/tutorials/deploy-via-dashboard) guide.

When working with code-based Web3 Actions, functions and their triggers must be defined in the `tenderly.yaml` file, which is generated by Tenderly CLI. Read the [CLI Quickstart](/monitoring/web3-actions/tutorials/deploy-via-cli) guide.

**Example**

In the example below, we’re declaring a Web3 Action called **bestActionEver** and referencing the function **awesomeActionFunction** that is exported from the **actions/myCoolTsFile.ts** file. This is the function that Tenderly will call when the Web3 Action gets triggered. The execution is controlled via **`execution_type`**, in this case it's set to `parallel`.

```yaml title="tenderly.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
account_id: ""
actions:
  our-cool-org/our-cool-project:
    runtime: v2
    sources: actions
    specs:
      bestActionEver:
        execution_type: parallel # or sequential
        description: Does the best thing ever
        function: myCoolTsFile:awesomeActionFunction
        trigger:           # trigger declaration start
          type: ...        # type
          ...              # configuration map (external event specific)
```

### Specifying triggers for external events

In this section, we’ll examine the `trigger` declaration. For more information on writing tenderly.yaml file, reference [this guide](/monitoring/web3-actions/references/project-structure#the-tenderlyyaml-file-structure).

The trigger type and corresponding configurations are defined in the **tenderly.yaml** file. You first must define the `trigger` object, which has two mandatory properties:

* The `type` property, that specifies the trigger type, which can be: `periodic | webhook | block | transaction | alert`
* An object with a configuration specific to the selected trigger type

For `alert` triggers, the action is wired by selecting the Web3 Action as the [alert destination](/monitoring/alerts/destinations/web3-action); alert-triggered actions always run sequentially.

Below is a detailed explanation of the trigger-specific configurations for each trigger type.

### Periodic event

A periodic event is used when you want your Web3 Action to be triggered at specific time intervals. It carries **time**: the time of invocation.

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
type PeriodicEvent = {
  time: Date;
};
```

The trigger declaration has the `periodic` type. It can be interval- or cron-based:

```yaml title="trigger.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
trigger:
  type: periodic
  periodic:
    interval: 5m
```

The `interval` property can take any of the following values: `5m | 10m | 15m | 30m | 1h | 3h | 6h | 12h | 1d`

Use the CRON-based periodic trigger if you need more granular control over when your Web3 Action gets executed:

```yaml title="trigger.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
trigger:
  type: periodic
  periodic:
    cron: '5 */1 * * *'
```

The `cron` property can be any valid [CRON string](https://crontab.guru/).

### Webhook event

Webhook-based Web3 Actions expose a custom webhook URL, making it possible to trigger them from external systems using a simple HTTP POST request.

The corresponding trigger type holds two properties: the **time** of invocation and any **payload** (a JSON object). Tenderly doesn't perform any validation or inspections on your payload.

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
type WebhookEvent = {
  time: Date;
  payload: any;
};
```

A trigger configuration example:

```yaml title="webhook-trigger.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
trigger:
  type: webhook
  webhook:
    authenticated: true
```

If `authenticated` is set to **true**, you must include the Tenderly Access Token with your request to be able to run the Web3 Action as the value of `x-access-key`. You can find the cURL of the exposed webhook in the Web3 Action overview in the Tenderly Dashboard.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl -X POST \
-H "x-access-key: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.tenderly.co/api/v1/actions/7acc7db2-00d6-4872-b2d2-d9430bd8fe7b/webhook \
-d '{"foo": "bar"}'
```

### Block event

The block event is used when you want to listen for the mining of blocks on one or several networks. You can make your Web3 Action "block-periodic" by specifying the number of mined blocks between two consecutive invocations.

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
type BlockEvent = {
  blockHash: string;
  blockNumber: number;
  network: string;
};
```

When declaring the block trigger, you can specify the following properties:

* `network`: a single value or a list of [network IDs](/monitoring/web3-actions/references/functions-events-triggers) you’re interested in
* `blocks`: the number of mined blocks between two consecutive executions of the Web3 Action. For example, execute the Web3 Action on every 100th block mined.

```yaml title="block-trigger.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
trigger:
  type: block
  block:
    network:
      - 1
      - 8453
    blocks: 100
```

### Transaction event

The transaction trigger type allows you to listen for specific transactions as they get executed on-chain.

<Note>
  To listen for transactions from a smart contract, the smart contract must be verified and added to
  your project in the Tenderly Dashboard. The CLI will throw a warning if this is not the case.
</Note>

You can specify different conditions in the form of **filters** to zero in on transactions of interest. Your custom code will be invoked with that exact transaction payload passed through the `event` parameter.

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
type TransactionEvent = {
  blockHash: string;
  blockNumber: number;
  from: string;
  hash: string;
  network: string;
  to?: string;
  logs: Array<{
    address: string;
    data: string;
    topics: string[];
  }>;
  input: string;
  value: string;
  nonce: string;
  gas: string;
  gasUsed: string;
  cumulativeGasUsed: string;
  gasPrice: string;
  gasTipCap: string;
  gasFeeCap: string;
  transactionHash: string;
};
```

When listening for transaction events, you can also specify the following settings:

* **Transaction mining status**: `mined` (the transaction has been mined) or `confirmed10` (10 blocks are confirmed since the block that contains the transaction)
* **Filters:** A list of conditions involving transaction payload using the `filters` list. Only transactions that match filters will trigger the execution of your code.

#### Filtering transactions

The `filters` list allows you to define triggering criteria using transaction properties to match specific transactions.

Each filter in the list is an object where **all fields are AND-ed together**. Every condition in the filter must be true for it to match. The `filters` list itself is **OR-ed**: a transaction matches if it satisfies **any single filter** in the list.

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
match = anyOf(
  (network AND status AND from AND eventEmitted),   # Filter 1
  (network AND to)                                  # Filter 2
)
```

Below is a list of all available filters you can combine to build criteria for transactions that will trigger the execution of your Web3 Action.

<br />

| Filter                                                         | Description                                                                                                                            |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| <p>\*mandatory / \*\*at least one of these must be present</p> |                                                                                                                                        |
| network\*                                                      | The network ID from which the transaction originated                                                                                   |
| status                                                         | The transaction status: fail or success                                                                                                |
| from\*\*                                                       | The address of the transaction originator                                                                                              |
| to\*\*                                                         | The address of the transaction recipient                                                                                               |
| eventEmitted\*\*                                               | An event of a specific type, emitted by a particular contract                                                                          |
| logEmitted\*\*                                                 | Logs emitted by a particular contract, by matching the prefix of the raw log entry                                                     |
| function\*\*                                                   | A call to the given function, direct or internal (configurable via `invocation`, default `any`)                                        |
| ethBalance\*\*                                                 | An account or contract whose ETH balance changed in the transaction and meets a numeric condition                                      |
| stateChanged\*\*                                               | A contract whose on-chain state variable changed during the transaction, with optional value/percentage conditions                     |
| value                                                          | The value that is transferred within the transaction in wei                                                                            |
| gasUsed                                                        | The amount of gas used by the transaction, in gas units                                                                                |
| gasLimit                                                       | The gas limit set for the transaction, in gas units                                                                                    |
| fee                                                            | The effective gas price paid by the transaction, in wei (not the total fee)                                                            |
| contract                                                       | A smart contract involved in the transaction (see <a href="#filtering-transactions-involving-a-specific-contract">contract filter</a>) |

<Warning>
  A trigger must contain `network` and at least one of the following filters: `from`, `to`,
  `function`, `eventEmitted`, `logEmitted`, `ethBalance`, or `stateChanged`
</Warning>

An **example** of a transaction on Ethereum mainnet or Base sent to `0x236..fd62`.

```yaml title="transaction-trigger.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
failedTransactionToMyContract:
  execution_type: parallel
  description: When sent to my contract fails
  function: observingTransactions:failedAttempts
  trigger:
    type: transaction
    transaction:
      status:
        - mined
      filters:
        # Transaction must be from Ethereum mainnet
        - network: 1
          # Transaction must have failed
          status: fail
          # Transaction must have been sent to this address
          to: 0x2364259ACD20Bd2A8dEfDc628f4099302449fd62
        # Or from Base
        - network: 8453
          # Transaction must have failed
          status: fail
          # Transaction must have been sent to this address
          to: 0x2364259ACD20Bd2A8dEfDc628f4099302449fd62
```

In this case, we're interested only in transactions that are mined, matching either of these two filters:

* **Filter 1**: network 1 (Ethereum) AND status fail AND to `0x2364...fd62`
* **Filter 2**: network 8453 (Base) AND status fail AND to `0x2364...fd62`

Since we didn't filter by any particular sender, all transactions coming to the mentioned recipient will result in the Web3 Action being triggered.

#### Filtering transactions by transaction fields

Among the common transaction fields, you can filter by the following properties having specific values.

* `from` - filtering on a specific sender. Can be a single address or a list of addresses (OR-ed). Optional.
* `to` - filtering on a specific receiver. Can be a single address or a list of addresses (OR-ed). Optional.
* `status` - filtering on transaction status: `success` or `fail`. Can be a single value or a list (OR-ed). Optional.
* `network` - filtering by network. Can be a single chain ID or a list of chain IDs (OR-ed). Mandatory.
* `contract.address` - filtering only transactions involving the contract with this specific address. Optional.

All address fields must be 0x-prefixed, 40 hex characters (e.g. `0xf63c48626f874bf5604D3Ba9f4A85d5cE58f8019`).

```yaml title="list-fields.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network:                  # list of networks (OR-ed)
      - 1
      - 8453
    status:                   # list of statuses (OR-ed)
      - success
      - fail
    from:                     # list of sender addresses (OR-ed)
      - 0x7ebB3Dca1C281b23D5B73175f10cA5A0a309B01F
      - 0xD3a02149A236b2547Cc3C897Fb41C1a962f881AE
    to:                       # list of recipient addresses (OR-ed)
      - 0x003b3625cDcb5958E9709F4Ba8E340Cb0783DeaE
      - 0x26997bd8473E0Dd0b37eB1711B7c1eE2354d78e4
```

You can also query numerics related to exchanged value and gas, using relational operators. All of the following are in **wei**:

* `value`
* `gasUsed`
* `gasLimit`
* `fee`

Numeric fields accept either a single comparison object or a list of comparison objects. When a list is provided, comparisons are OR-ed. Within a single comparison object, all operators are AND-ed.

You can use any of the common comparison operators: `eq`, `gte`, `gt`, `lt`, `lte`. You can also use the `not` boolean flag to negate a comparison.

<br />

| Operator | Meaning                                                                                     |
| -------- | ------------------------------------------------------------------------------------------- |
| `eq`     | Equal to                                                                                    |
| `gt`     | Greater than                                                                                |
| `gte`    | Greater than or equal to                                                                    |
| `lt`     | Less than                                                                                   |
| `lte`    | Less than or equal to                                                                       |
| `not`    | Boolean. Set to `true` to negate the comparison (e.g. match when value is **not** in range) |

Below is an example of a filter demonstrating filters using scalar values in the transaction payload.

```yaml title="numeric-filters.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    to: 0x003b3625cDcb5958E9709F4Ba8E340Cb0783DeaE
    # Single comparison object (operators AND-ed within)
    value:
      gte: 100
      lte: 1000
    # List of comparison objects (OR-ed between entries)
    gasLimit:
      - lt: 100
      - gt: 1000
    gasUsed:
      eq: 9999
    fee:
      - lte: 100
      - gte: 1000
```

Using the `not` flag to negate a comparison:

```yaml title="negated-comparison.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    to: 0x003b3625cDcb5958E9709F4Ba8E340Cb0783DeaE
    # Matches when value is NOT between 100 and 1000
    value:
      gte: 100
      lte: 1000
      not: true
```

#### Filtering transactions using emitted EVM Events

Configuring Web3 Actions to listen for EVM events emitted by a transaction execution allows you to respond to significant changes logged by these events. You can achieve this by using the `eventEmitted` operator, which supports the following nested properties:

* `contract` (mandatory): To specify the origin of the event.
  * `contract.address`: The address of the contract that emitted the event.
  * `contract.invocation`: Controls how the contract was called: `direct`, `internal`, or `any` (default). See [contract filter](#filtering-transactions-involving-a-specific-contract) for details.
* `name`: The name of the event (requires a verified contract).
* `id`: The topic hash of the event signature (alternative to `name`). For example, the `Transfer(address,address,uint256)` event has the topic hash `0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef`. Matching by `id` still requires the contract's ABI to decode the log; for contracts without an ABI, use [`logEmitted`](#filtering-transactions-by-emitted-logs) with the raw topic hash.
* `not`: Boolean. Set to `true` to negate the entire event match, including parameters (trigger when the event is **not** emitted with the specified parameters).
* `parameters`: A list of conditions on decoded event argument values. All conditions are AND-ed: every condition must match. Each entry supports:
  * `name` (required): The name of the event argument.
  * `string`: String comparison. Accepts a plain string for exact match, or an object with `exact` and `not` fields. See [StringComparison](#shared-types) for details.
  * `int`: Integer comparison. Supports the same operators as numeric filters (`eq`, `gt`, `gte`, `lt`, `lte`). All operators within a single `int` block are AND-ed. Use the `not` flag to negate the combined condition. See [IntComparison](#shared-types) for details.

<Info>
  There is no OR within a single `eventEmitted` entry's `parameters`. All conditions are AND-ed.
  For OR logic on the same parameter, use multiple `eventEmitted` entries (which are OR-ed in the outer list).
</Info>

<Note>
  The `eventEmitted` filter requires a contract that is verified and added to the project in the
  Tenderly Dashboard; the ABI is needed to decode the log even when matching by `id`. For unverified
  contracts, use [`logEmitted`](#filtering-transactions-by-emitted-logs) instead.
</Note>

For the complete field reference, see [EventFilter](#eventfilter-eventemitted).

Below is an example of a Web3 Action that will be invoked when either `TxSubmission` or `TxConfirmation` event is emitted when the smart contract is executed at the address `0x418d..9d45` on Sepolia.

```yaml title="event-emitted-filter.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
txSubmittedOrConfirmed:
  description: When any of TxSubmission and TxConfirmation is emitted
  execution_type: parallel
  function: myCoolJsFile:myCoolFunction
  trigger:
    type: transaction
    transaction:
      status:
        - mined
      filters:
        - network: 11155111
          eventEmitted:
            contract:
              address: 0x418ebb95eaa40c119408143056cad984c6129d45
            name: TxSubmission
        - network: 11155111
          eventEmitted:
            contract:
              address: 0x418ebb95eaa40c119408143056cad984c6129d45
            name: TxConfirmation
```

Here is an example filtering by decoded event parameters. All parameter conditions are AND-ed:

```yaml title="event-parameters.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 8453
    eventEmitted:
      contract:
        address: 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
      name: Transfer
      parameters:
        - name: from
          string: "0x8F362C3dd5301Ce1b43ea3A278E3f12c1807C271"
        - name: value
          int:
            gte: 1000000           # >= 1 USDC (6 decimals)
```

Numeric range with negation on parameters:

```yaml title="negated-parameter.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    eventEmitted:
      contract:
        address: 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
      name: Transfer
      parameters:
        - name: value
          int:
            gte: 100
            lte: 1000
            not: true              # matches when value < 100 OR value > 1000
```

For OR logic on parameters, use multiple `eventEmitted` entries:

```yaml title="event-parameter-or.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    eventEmitted:
      # Entry 1: value < 100
      - contract:
          address: 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
        name: Transfer
        parameters:
          - name: value
            int:
              lt: 100
      # Entry 2: value > 1000 (OR-ed with entry 1)
      - contract:
          address: 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
        name: Transfer
        parameters:
          - name: value
            int:
              gt: 1000
```

Using `not` on the event itself to negate the entire match:

```yaml title="negated-event.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    eventEmitted:
      contract:
        address: 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
      name: Transfer
      parameters:
        - name: from
          string: "0x0000000000000000000000000000000000000000"
      not: true   # matches when no Transfer event from the zero address is found
```

#### Filtering transactions by emitted logs

Another way to listen for EVM events is to query them by the log topic.

The `logEmitted` filter can be a single object or a list (entries are OR-ed). It supports the following properties:

* `startsWith` (mandatory): A list of topic values to match against the transaction’s log topics. Each entry is compared by exact equality (case-insensitive) to the corresponding topic. In practice these are full 32-byte topic hashes (0x-prefixed, 64 hex chars), but the field accepts any valid hex string.
* `contract.address` (optional): The source of the logs. When specified, only logs from this contract are matched.
* `matchAny`: Boolean. When `true`, matching **any single** topic from `startsWith` is sufficient. When `false` (default), all topics must match.
* `not`: Boolean. Set to `true` to negate the entire log match (trigger when the log is **not** emitted).

<Note>
  Using `logEmitted` enables you to use the event topic prefix in its raw form to filter for events.
  This is useful if you’re setting up a Web3 Action on an unverified contract.
</Note>

For the complete field reference, see [LogFilter](#logfilter-logemitted).

Below is an example of a Web3 Action that will be invoked when a transaction contains log entries starting with the given prefixes.

```yaml title="log-emitted-filter.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
txEmittedSomeLogs:
  description: When particular logs are emitted
  function: observingTransactions:someLogsEmittedAction
  execution_type: parallel
  trigger:
    type: transaction
    transaction:
      status:
        - mined
      filters:
        - network: 11155111
          logEmitted:
            # Transaction must have emitted a log entry
            contract:
              address: 0x418ebb95eaa40c119408143056cad984c6129d45
            startsWith:
              # and the log topics must match these values positionally (all of
              # them, by default; set matchAny: true to match any one of them)
              - 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
              - 0x0000000000000000000000000000000000000000000000000000000000000000
```

#### Filtering transactions involving a specific contract

To filter for transactions that call a specific contract during their execution, you can use the optional `contract` filter.

The `contract` filter supports the following properties:

* `address`: The address of the contract.
* `invocation`: Controls how the contract was called. Possible values:
  * `direct`: the contract was called directly by the transaction sender (EOA). Use this when you only care about top-level calls to the contract.
  * `internal`: the contract was called internally by another contract during execution (e.g. via `CALL`, `DELEGATECALL`, or `STATICCALL` opcodes). Use this to detect when your contract is invoked as part of a multi-contract interaction.
  * `any`: matches both direct and internal calls. This is the default.

The `invocation` field is available wherever a `contract` object is used, including inside [`eventEmitted`](#filtering-transactions-using-emitted-evm-events) filters. For `eventEmitted` contracts, only `direct` is distinguished: `internal` behaves the same as `any`. See [Contract](#shared-types) for the schema.

<Warning>
  `invocation` is not supported on `logEmitted`. Only `contract.address` is used to restrict log matching; the invocation type is ignored.
</Warning>

In the example below, the first filter matches any successful transaction sent to `0x2364...fd62` on Sepolia. The second filter is more restrictive: only transactions that also involve an internal call to contract `0xad88...80d6` will trigger the Web3 Action.

```yaml title="contract-filter.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
contractInvocationAction:
  description: When my contract is called directly or internally
  execution_type: parallel
  function: observingTransactions:contractCalls
  trigger:
    type: transaction
    transaction:
      status:
        - mined
      filters:
        # Any successful transaction sent to this address
        - network: 11155111
          status: success
          to: 0x2364259ACD20Bd2A8dEfDc628f4099302449fd62
        # Only transactions that internally call this contract
        - network: 11155111
          status: success
          to: 0x2364259ACD20Bd2A8dEfDc628f4099302449fd62
          contract:
            address: 0xad881d3d06c7f168715b84b54f9d3e1ff27b80d6
            invocation: internal
```

#### Filtering transactions by function call

To filter for transactions that call a specific function, you can use the optional `function` filter. It requires the address of the contract `contract.address` and the `name` of the function.

The `function` filter supports the following properties:

* `contract` (mandatory): To specify the target contract.
  * `contract.address`: The address of the contract being called.
  * `contract.invocation`: Controls how the function must be called: `any` (default, both direct and internal), `direct` (EOA-initiated only), or `internal` (sub-calls only). See [contract filter](#filtering-transactions-involving-a-specific-contract) for details.
* `name` (mandatory): The name of the function (requires a verified contract).
* `not`: Boolean. Set to `true` to negate the entire function match, including parameters (trigger when the function is **not** called with the specified parameters).
* `parameters`: A list of conditions on decoded function input argument values. All conditions are AND-ed: every condition must match. Each entry supports:
  * `name` (required): The name of the function argument.
  * `string`: String comparison. Accepts a plain string for exact match, or an object with `exact` and `not` fields. See [StringComparison](#shared-types) for details.
  * `int`: Integer comparison. Supports the same operators as numeric filters (`eq`, `gt`, `gte`, `lt`, `lte`). All operators within a single `int` block are AND-ed. Use the `not` flag to negate the combined condition. See [IntComparison](#shared-types) for details.

<Info>
  There is no OR within a single `function` entry’s `parameters`. All conditions are AND-ed.
  For OR logic on the same parameter, use multiple `function` entries (which are OR-ed in the outer list).
</Info>

<Note>
  The `function` filter requires a contract that is verified and added to the project in the
  Tenderly Dashboard. For unverified contracts, filter on the transaction's effects instead, for
  example with [`logEmitted`](#filtering-transactions-by-emitted-logs).
</Note>

You can specify `function` as a single object or as a list. When a list is provided, entries are OR-ed. The filter matches if **any** function in the list is called. For the complete field reference, see [FunctionFilter](#functionfilter).

Below is an example of a Web3 Action trigger responding to any call (direct or internal) to the `verySpecialFunction` of the contract deployed at `0xad88...80d6`.

```yaml title="function-filter.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
failedTransactionToMyContract:
  description: When sent to my contract fails
  execution_type: parallel
  function: observingTransactions:failedAttempts
  trigger:
    type: transaction
    transaction:
      status:
        - mined
      filters:
        # Transaction must be from Ethereum mainnet
        - network: 1
          # Transaction must have failed
          status: fail
          function:
            # the function verySpecialFunction must have been called (direct or internal)
            name: verySpecialFunction
            contract:
              address: 0xad881d3d06c7f168715b84b54f9d3e1ff27b80d6
```

You can also use multiple function entries (OR-ed):

```yaml title="function-multi.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    function:
      - name: transfer
        contract:
          address: 0xad881d3d06c7f168715b84b54f9d3e1ff27b80d6
      - name: approve
        not: true  # negate: trigger when approve is NOT called
        contract:
          address: 0xad881d3d06c7f168715b84b54f9d3e1ff27b80d6
```

Here is an example filtering by decoded function input parameters. All parameter conditions are AND-ed:

```yaml title="function-parameters.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    function:
      name: transfer
      contract:
        address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
      parameters:
        - name: to
          string: "0x8F362C3dd5301Ce1b43ea3A278E3f12c1807C271"
        - name: amount
          int:
            gte: 1000000           # >= 1 USDC (6 decimals)
```

String negation, trigger when the recipient is **not** a specific address:

```yaml title="function-negated-string.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    function:
      name: transfer
      contract:
        address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
      parameters:
        - name: to
          string:
            exact: "0xa59a97Ab934aE02A1E0561ea0f4F6C275Fc148B4"
            not: true              # matches when 'to' is NOT this address
```

Numeric range with negation on parameters:

```yaml title="function-negated-parameter.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    function:
      name: transfer
      contract:
        address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
      parameters:
        - name: amount
          int:
            gte: 100
            lte: 1000
            not: true              # matches when amount < 100 OR amount > 1000
```

For OR logic on parameters, use multiple `function` entries:

```yaml title="function-parameter-or.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    function:
      # Entry 1: amount < 100
      - name: transfer
        contract:
          address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
        parameters:
          - name: amount
            int:
              lt: 100
      # Entry 2: amount > 1000 (OR-ed with entry 1)
      - name: transfer
        contract:
          address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
        parameters:
          - name: amount
            int:
              gt: 1000
```

To match only internal calls, for example, a `transfer` triggered by a router or flash-loan provider rather than directly by a user, set `invocation: internal`. This example triggers only when another contract internally calls `transfer` on USDC for at least 1,000 USDC:

```yaml title="function-internal-with-params.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    function:
      name: transfer
      contract:
        address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
        invocation: internal       # sub-calls only — excludes direct EOA calls
      parameters:
        - name: amount
          int:
            gte: 1000000000        # >= 1,000 USDC (6 decimals)
```

#### Filtering transactions by ETH balance

The `ethBalance` filter triggers your Web3 Action when a transaction changes an account or contract's ETH balance and the resulting balance meets a numeric condition. This is useful for monitoring large whale movements, protocol treasury thresholds, or wallet funding events.

The filter is evaluated only when the address's native balance changes in the transaction; a transaction that leaves the balance untouched never matches, even if the balance already satisfies the condition.

The filter supports the following properties:

* `address` (mandatory): The account or contract address to monitor.
* `balanceCmp` (mandatory): A numeric comparison against the balance after the transaction. Uses [`BigIntComparison`](#shared-types) operators (`eq`, `gt`, `gte`, `lt`, `lte`). Values are in **wei** and can be provided as decimal strings (e.g. `"1000000000000000000"`) or `0x`-prefixed hex (e.g. `"0xde0b6b3a7640000"`).
* `not` (optional): Set to `true` to negate the entire match.

You can provide a single `ethBalance` object or a list, entries are OR-ed.

For the complete field reference, see [`EthBalanceFilter`](#ethbalancefilter-ethbalance).

**Example**: trigger when a wallet's balance reaches at least 1 ETH:

```yaml title="eth-balance-filter.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
balanceWatcher:
  description: Alert when wallet reaches 1 ETH
  function: watchers:onBalanceReached
  trigger:
    type: transaction
    transaction:
      status:
        - mined
      filters:
        - network: 1
          ethBalance:
            address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"   # vitalik.eth
            balanceCmp:
              gte: "1000000000000000000"   # 1 ETH in wei
```

**Example**: multiple accounts monitored in one filter (OR-ed):

```yaml title="eth-balance-multi.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    ethBalance:
      - address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"   # vitalik.eth
        balanceCmp:
          gte: "1000000000000000000"
      - address: "0xBE0eB53F46cd790Cd13851d5EFf43D12404d33E8"   # Binance cold wallet
        balanceCmp:
          lte: "500000000000000000"   # below 0.5 ETH
```

**Example**: balance within a range:

```yaml title="eth-balance-range.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    ethBalance:
      address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"   # vitalik.eth
      balanceCmp:
        gte: "1000000000000000000"   # >= 1 ETH
        lte: "2000000000000000000"   # <= 2 ETH
```

**Example**: trigger when a wallet's balance is **not** below 1 ETH (i.e. negating the condition):

```yaml title="eth-balance-not.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    ethBalance:
      address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"   # vitalik.eth
      balanceCmp:
        lt: "1000000000000000000"   # < 1 ETH
      not: true                     # negate: trigger when balance is NOT below 1 ETH
```

#### Filtering transactions by contract state changes

The `stateChanged` filter triggers your Web3 Action when a contract's state variable changes during a transaction. You can match on any combination of: whether the variable changed at all, a specific new value, a percentage change, or a raw storage slot key.

The filter supports the following properties:

* `address` (mandatory unless `matchAny: true`): The contract address to watch.
* `matchAny` (optional): When `true`, matches state changes on **any** contract in the transaction, `address` can be omitted. Useful for protocol-wide monitoring.
* `params` (optional): A list of state variable conditions, one entry per variable name. Entries are **OR-ed**: the filter matches when any listed variable's condition is met. Repeating the same `name` overwrites the earlier entry, so combine all conditions for one variable in a single entry. When `params` is omitted, the filter matches any state change on the specified address.
* `not` (optional): Set to `true` to negate the entire match.

Each entry in `params` requires:

* `name` (mandatory): The name of the state variable.
* At least one condition:
  * `change: true`: matches when the variable's value changed at all.
  * `valueCmp` ([`BigIntComparison`](#shared-types)), matches when the new value meets a numeric condition.
  * `percentageCmp` ([`BigIntComparison`](#shared-types)), matches on the **signed** percentage change computed as `(newValue - oldValue) * 100 / oldValue`. Positive values mean an increase, negative values mean a decrease. For example, `gte: "10"` fires on increases of 10%+; `lte: "-10"` fires on decreases of 10%+. Note: when `oldValue` is 0, the percentage is always 0, use `change: true` or `valueCmp` instead.
  * `storageSlotKey`: matches by raw storage slot key (useful for unverified contracts).

For the complete field reference, see [`StateChangedFilter`](#statechangedfilter-statechanged).

<Note>
  To use `name`-based state variable matching, the contract must be verified and added to your project
  in the Tenderly Dashboard.
</Note>

**Example**: trigger when `totalSupply` changes at all:

```yaml title="state-changed-basic.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
stateWatcher:
  description: Alert on any totalSupply change
  function: watchers:onStateChange
  trigger:
    type: transaction
    transaction:
      status:
        - mined
      filters:
        - network: 1
          stateChanged:
            address: "0x6B175474E89094C44Da98b954EedeAC495271d0F"   # DAI on mainnet
            params:
              - name: totalSupply
                change: true
```

**Example**: trigger when `totalSupply` reaches a threshold:

```yaml title="state-changed-value.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    stateChanged:
      address: "0x6B175474E89094C44Da98b954EedeAC495271d0F"   # DAI on mainnet
      params:
        - name: totalSupply
          valueCmp:
            gte: "1000000000000000000000"   # >= 1000 DAI (18 decimals)
```

**Example**: trigger when `totalSupply` increases by 50% or more:

```yaml title="state-changed-percentage-increase.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    stateChanged:
      address: "0x6B175474E89094C44Da98b954EedeAC495271d0F"   # DAI on mainnet
      params:
        - name: totalSupply
          percentageCmp:
            gte: "50"   # positive = increase; fires when totalSupply grew by >= 50%
```

**Example**: trigger when `totalSupply` decreases by 10% or more:

```yaml title="state-changed-percentage-decrease.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    stateChanged:
      address: "0x6B175474E89094C44Da98b954EedeAC495271d0F"   # DAI on mainnet
      params:
        - name: totalSupply
          percentageCmp:
            lte: "-10"   # negative = decrease; fires when totalSupply dropped by >= 10%
```

**Example**: entries in `params` are OR-ed, so this fires when **either** variable changes:

```yaml title="state-changed-multi-params.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    stateChanged:
      address: "0x6B175474E89094C44Da98b954EedeAC495271d0F"   # DAI on mainnet
      params:
        - name: totalSupply
          change: true
        - name: wards
          change: true
```

To apply several conditions to the same variable, put them in one entry; repeating a `name` in separate entries overwrites the earlier one.

**Example**: watch a specific mapping slot (e.g. `balances[bob]`) using a raw storage slot key:

For mappings, there is no named variable per entry, use `storageSlotKey` with the keccak256-derived slot for the key you care about. The slot for `mapping(address => uint256) balances` at storage slot `N` and key `addr` is `keccak256(abi.encode(addr, N))`.

```yaml title="state-changed-slot.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    stateChanged:
      address: "0x6B175474E89094C44Da98b954EedeAC495271d0F"   # DAI on mainnet
      params:
        # slot = keccak256(abi.encode(bob_address, mapping_slot_index))
        # compute this off-chain with ethers.js: ethers.solidityPackedKeccak256(["address", "uint256"], [bobAddress, slotIndex])
        - storageSlotKey: "0x<precomputed-slot-hash>"
          change: true
```

The `storageSlotKey` approach works for unverified contracts and any storage layout, it does not require the contract to be verified or added to your Tenderly project.

**Example**: `matchAny` to monitor any contract in the transaction:

```yaml title="state-changed-match-any.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 1
    function:
      name: liquidate
      contract:
        address: 0xad881d3d06c7f168715b84b54f9d3e1ff27b80d6
    stateChanged:
      matchAny: true
      params:
        - name: collateralBalance
          change: true
```

`stateChanged` and `ethBalance` can be combined with any other filter in the same filter object, all fields are AND-ed. The examples below show common real-world combinations.

**Example**: `mint()` was called AND `totalSupply` changed (confirm the call had on-chain effect):

```yaml title="state-changed-with-function.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 8453
    function:
      name: mint
      contract:
        address: "0x0232b6c44752020C645b65CAA68c139ab456Ec37"
    stateChanged:
      address: "0x0232b6c44752020C645b65CAA68c139ab456Ec37"
      params:
        - name: totalSupply
          change: true
```

**Example**: `Transfer` event emitted AND `paused` state changed (ownership or pause flag toggled during a transfer):

```yaml title="state-changed-with-event.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 8453
    eventEmitted:
      contract:
        address: "0x0232b6c44752020C645b65CAA68c139ab456Ec37"
      name: Transfer
    stateChanged:
      address: "0x0232b6c44752020C645b65CAA68c139ab456Ec37"
      params:
        - name: paused
          change: true
```

**Example**: any call to a contract AND the caller's ETH balance is above a threshold:

```yaml title="eth-balance-with-to.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 8453
    to: "0x0232b6c44752020C645b65CAA68c139ab456Ec37"
    ethBalance:
      address: "0x4786f86f7d9d1467928b3518f123ea4fb65f1500"
      balanceCmp:
        gte: "500000000000000"   # caller has >= 0.0005 ETH
```

**Example**: trigger when `togglePause()` was called but `balances` did **not** change (i.e. the tx affected only the paused flag):

```yaml title="state-changed-not.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
filters:
  - network: 8453
    to: "0x0232b6c44752020C645b65CAA68c139ab456Ec37"
    stateChanged:
      address: "0x0232b6c44752020C645b65CAA68c139ab456Ec37"
      params:
        - name: balances
          change: true
      not: true   # negate: trigger when balances did NOT change
```

#### Complete transaction trigger reference

The following annotated YAML block shows every available field for transaction triggers in one place. Use it as a quick reference when building your trigger configuration. For type definitions, see the [Trigger YAML schema reference](#trigger-yaml-schema-reference) below.

```yaml title="complete-reference.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
trigger:
  type: transaction
  transaction:
    status:
      - mined              # or confirmed10

    # At least one filter must match (OR logic).
    # Within a filter, all fields are AND-ed.
    filters:
      - network: 1                                          # mandatory (single or list)
        status: success                                     # fail | success (single or list)
        from: "0xDB6Fd484cFA46eeB73c71165C6C004B50309BbE1" # single or list of addresses
        to: "0x2364259ACD20Bd2A8dEfDc628f4099302449fd62"   # single or list of addresses

        # --- Contract filter ---
        contract:
          address: 0xad881d3d06c7f168715b84b54f9d3e1ff27b80d6
          invocation: any    # any | direct | internal

        # --- Numeric comparisons (all in wei) ---
        # Each can be a single object or a list (OR-ed between entries).
        # Within a single object, all operators are AND-ed.
        value:
          gte: 1000000000000000000   # >= 1 ETH
          not: false                 # set true to negate
        gasUsed:
          eq: 21000
        gasLimit:                    # list form (OR-ed)
          - lt: 100
          - gt: 1000
        fee:
          - lte: 100
          - gte: 1000

        # --- Event filter (single object or list, OR-ed) ---
        eventEmitted:
          - contract:
              address: 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
            name: Transfer           # match by event name (verified contract)
            # id: "0xddf252..."      # alternative: match by topic hash
            not: false               # negate entire event match
            parameters:              # filter by decoded event arguments (AND-ed)
              - name: from
                string: "0x8F362C3dd5301Ce1b43ea3A278E3f12c1807C271"
              - name: value
                int:
                  gte: 1000000       # >= 1 USDC (6 decimals)

        # --- Log filter (single object or list, OR-ed) ---
        logEmitted:
          - startsWith:
              - "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
            contract:
              address: 0x418ebb95eaa40c119408143056cad984c6129d45
            matchAny: false          # true = match any single topic
            not: false               # negate entire log match

        # --- Function filter (single object or list, OR-ed) ---
        function:
          - name: transfer           # match by name (verified contract)
            contract:
              address: 0xad881d3d06c7f168715b84b54f9d3e1ff27b80d6
              invocation: any        # any (default) | direct | internal
            not: false               # negate entire function + parameters match
            parameters:              # filter by decoded function arguments (AND-ed)
              - name: to
                string: "0x8F362C3dd5301Ce1b43ea3A278E3f12c1807C271"  # short form
              - name: from
                string:              # long form (with negation)
                  exact: "0xa59a97Ab934aE02A1E0561ea0f4F6C275Fc148B4"
                  not: true          # negate this string match
              - name: amount
                int:
                  gte: 1000000       # >= 1 USDC (6 decimals)
          - name: approve            # multiple entries are OR-ed
            not: true                # negate this function match
            contract:
              address: 0xad881d3d06c7f168715b84b54f9d3e1ff27b80d6

        # --- ETH balance filter (single object or list, OR-ed) ---
        ethBalance:
          address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"  # vitalik.eth
          balanceCmp:
            gte: "1000000000000000000"  # >= 1 ETH in wei (decimal or 0x-prefixed hex)
          not: false                    # negate the balance match

        # --- State changed filter (single object or list, OR-ed) ---
        stateChanged:
          address: "0x6B175474E89094C44Da98b954EedeAC495271d0F"  # DAI on mainnet
          matchAny: false               # true = match any contract in the transaction
          not: false                    # negate the entire state change match
          params:                       # entries are OR-ed, one per variable name
                                        # (a repeated name overwrites the earlier entry)
            - name: totalSupply         # state variable name (verified contract)
              # at least one condition per entry:
              change: true              # matches when the value changed at all
              valueCmp:                 # BigIntComparison on the new value
                gte: "1000"
              percentageCmp:            # signed: (newVal-oldVal)*100/oldVal
                gte: "50"               # >= 50 means increased by >= 50%
                                        # use lte: "-50" to match a decrease of >= 50%
```

### Trigger YAML schema reference

The schema below describes the structure and types of every field accepted by the trigger configuration. Use it alongside the [annotated example](#complete-transaction-trigger-reference) above when building your `tenderly.yaml`.

Notation: `?` = optional, `|` = one of, `[]` = list. Fields marked "single or list" accept either a scalar value or a YAML list.

#### All trigger types

```yaml title="schema.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
trigger:
  type: periodic | webhook | block | transaction | alert

  periodic:               # when type = periodic
    interval: string?     # "5m" | "10m" | "15m" | "30m" | "1h" | "3h" | "6h" | "12h" | "1d"
    cron: string?         # standard cron expression (mutually exclusive with interval)

  webhook:                # when type = webhook
    authenticated: bool?  # default: true

  block:                  # when type = block
    network: Network      # single chain ID or list of chain IDs
    blocks: int           # run every N blocks (must be > 0)

  transaction:            # when type = transaction
    status: TransactionStatus[]    # "mined" | "confirmed10"
    filters: TransactionFilter[]   # at least one filter required
```

#### TransactionFilter

```yaml title="schema.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# All fields within a filter are AND-ed.
# Multiple filters in the list are OR-ed.

TransactionFilter:
  network: Network                # required. single chain ID or list (OR-ed)
  status: Status                  # optional. single or list: "success" | "fail" (OR-ed)
  from: Address                   # optional. single or list of addresses (OR-ed)
  to: Address                     # optional. single or list of addresses (OR-ed)
  value: IntComparison            # optional. single object or list (OR-ed)
  gasUsed: IntComparison          # optional. single object or list (OR-ed)
  gasLimit: IntComparison         # optional. single object or list (OR-ed)
  fee: IntComparison              # optional. single object or list (OR-ed)
  contract: Contract              # optional. shared default — applied to function/eventEmitted that omit their own contract
  function: FunctionFilter        # optional. single object or list (OR-ed)
  eventEmitted: EventFilter       # optional. single object or list (OR-ed)
  logEmitted: LogFilter           # optional. single object or list (OR-ed)
  ethBalance: EthBalanceFilter    # optional. single object or list (OR-ed)
  stateChanged: StateChangedFilter  # optional. single object or list (OR-ed)
  # constraint: at least one of from, to, function, eventEmitted, logEmitted, ethBalance, or stateChanged is required
```

<Warning>
  At least one of `from`, `to`, `function`, `eventEmitted`, `logEmitted`, `ethBalance`, or `stateChanged` must be present in each filter.
</Warning>

<Note>
  The top-level `contract` field acts as a shared default for the filter. It is automatically applied to any `function` or `eventEmitted` entry that does not specify its own contract, letting you avoid repeating the same address. It does **not** apply to `logEmitted`.
</Note>

#### Shared types

```yaml title="schema.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Address: string                   # 0x-prefixed, 40 hex characters (case-insensitive)

Network: int | int[]              # chain ID(s)

Status: string | string[]        # "success" | "fail"

Contract:
  address: Address                # required
  invocation: string?             # "any" (default) | "direct" | "internal"

IntComparison:                    # single object or list of objects (OR-ed)
  eq: int?                        # equal to
  gt: int?                        # greater than
  gte: int?                       # greater than or equal
  lt: int?                        # less than
  lte: int?                       # less than or equal
  not: bool?                      # negate the combined condition

BigIntComparison:                 # used by ethBalance and stateChanged filters
  # values are decimal strings ("1000000000000000000") or 0x-prefixed hex ("0xde0b6b3a7640000")
  # for percentageCmp: signed value, (newVal-oldVal)*100/oldVal — positive=increase, negative=decrease
  eq: string?                     # equal to
  gt: string?                     # greater than
  gte: string?                    # greater than or equal
  lt: string?                     # less than
  lte: string?                    # less than or equal
  not: bool?                      # negate the combined condition
  # at least one of eq, gt, gte, lt, lte must be set

StringComparison:                 # accepts a plain string OR an object
  # Short form:  string: "0xdead..."        → exact match, not = false
  # Long form:   string: { exact: "0xdead...", not: true }
  exact: string?                  # exact match (case-insensitive)
  not: bool?                      # negate the match
```

#### FunctionFilter

```yaml title="schema.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
FunctionFilter:                   # single object or list (OR-ed)
  contract: Contract              # required
  name: string                    # required. function name (requires verified contract)
  not: bool?                      # negate entire function + parameters match
  parameters: ParameterCondition[]?

ParameterCondition:               # all conditions in the list are AND-ed
  name: string                    # required. function argument name
  string: StringComparison?       # string comparison (plain string or { exact, not })
  int: IntComparison?             # numeric comparison
```

#### EventFilter (eventEmitted)

```yaml title="schema.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
EventFilter:                      # single object or list (OR-ed)
  contract: Contract              # required
  name: string?                   # event name (requires verified contract)
  id: string?                     # topic hash, 0x-prefixed, 64 hex chars
  not: bool?                      # negate entire event + parameters match
  parameters: ParameterCondition[]?
  # note: name and id are mutually exclusive (use one or the other)
  # note: a verified contract is required even when matching by id (the ABI decodes the log)
  # note: contract.invocation "internal" behaves like "any" here; only "direct" is distinguished
  # note: see ParameterCondition definition under FunctionFilter above
```

#### LogFilter (logEmitted)

```yaml title="schema.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
LogFilter:                        # single object or list (OR-ed)
  startsWith: string[]            # required. hex strings (typically 0x + 64 hex chars for full topic hashes)
  contract: Contract?             # optional. restrict to logs from this contract address
  # note: invocation is not supported for logEmitted; only contract.address is used
  matchAny: bool?                 # true = match any topic; false (default) = match all
  not: bool?                      # negate entire log match
```

#### EthBalanceFilter (ethBalance)

```yaml title="schema.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
EthBalanceFilter:                 # single object or list (OR-ed)
  address: Address                # required. account or contract address to monitor
  balanceCmp: BigIntComparison    # required. condition on the ETH balance in wei
  not: bool?                      # negate the balance match
  # note: evaluated only when the address's balance changes in the transaction
```

#### StateChangedFilter (stateChanged)

```yaml title="schema.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
StateChangedFilter:               # single object or list (OR-ed)
  address: Address?               # required unless matchAny = true
  matchAny: bool?                 # true = match state changes on any contract in the transaction
  params: StateChangedParamCondition[]?  # optional. when omitted, matches any state change on address
  not: bool?                      # negate the entire state change match

StateChangedParamCondition:       # entries in the params list are OR-ed, keyed by variable
                                  # name (a repeated name overwrites the earlier entry)
  name: string                    # required. state variable name (verified contract)
  # at least one of the following must be set:
  change: bool?                   # true = matches when the variable changed at all
  valueCmp: BigIntComparison?     # condition on the new value
  percentageCmp: BigIntComparison?  # signed: (newVal-oldVal)*100/oldVal
                                  #   gte: "10"  → increased by >= 10%
                                  #   lte: "-10" → decreased by >= 10%
                                  #   returns 0 when oldVal is 0; use valueCmp or change: true instead
  storageSlotKey: string?         # raw storage slot key (useful for unverified contracts)
```


# Manage Web3 Actions Lifecycle
Source: https://docs.tenderly.co/monitoring/web3-actions/references/lifecycle

Operate your Web3 Actions using the Tenderly Dashboard. Learn how to stop, upgrade, or manually run a Web3 Action.

In this guide, you’ll learn how to:

* Manually stop the execution of Web3 Actions.
* Upgrade and edit deployed Web3 Actions without downtime.
* Manually execute Web3 Actions.

### Stop a Web3 Action

Web3 Actions run indefinitely until you stop their execution manually. To stop a Web3 Action, go to the Web3 Actions overview page where you'll see a list of all your Web3 Actions. Click the one you want to stop.

<figure>
  <img alt="Opening a Web3 Action you want to stop" />

  <figcaption>
    <p>Opening a Web3 Action you want to stop</p>
  </figcaption>
</figure>

From the top right page menu, click on the **Stop Action** button.

<figure>
  <img alt="Clicking the Stop Action button" />

  <figcaption>
    <p>Clicking the Stop Action button</p>
  </figcaption>
</figure>

You’ll be prompted to confirm your decision.Click the **Stop Action** button to confirm.

<figure>
  <img alt="Confirming that you want to stop a Web3 Action" />

  <figcaption>
    <p>Confirming that you want to stop a Web3 Action </p>
  </figcaption>
</figure>

### Restart a stopped Web3 Action

While you’re still on the page of the stopped Web3 Action, click on the **Start Action** button from the top right page menu.

<figure>
  <img alt="Restarting a stopped Web3 Action" />

  <figcaption>
    <p>Restarting a stopped Web3 Action</p>
  </figcaption>
</figure>

You’ll be prompted to confirm your decision.Click the **Start Action** button to confirm.

### Upgrade and edit a Web3 Action

Deployed Web3 Actions are editable and upgradeable.You can safely make changes to any active and deployed Web3 Action without any downtime.The new version of your Web3 Action will be queued and deployed as soon as the previous version is done executing, ensuring zero downtime.

To edit a Web3 Action, open it and click the **Edit** button in the **Source Code** section.

<figure>
  <img alt="Editing a Web3 Action" />

  <figcaption>
    <p>Editing a Web3 Action</p>
  </figcaption>
</figure>

You’ll be forwarded to the editing interface, where you can modify any of the parameters of your Web3 Action.Once you’re happy with the changes, click **Save** at the bottom of the page.

<figure>
  <img alt="Modifying Web3 Action parameters" />

  <figcaption>
    <p>Modifying Web3 Action parameters </p>
  </figcaption>
</figure>

At any moment, you can revert to the previous version of your Web3 Action.Click on the **Version History** menu item to view all previous Web3 Action versions.Click the **Deploy** button next to the version of the Web3 Action you want to deploy.

### Trigger a Web3 Action manually

For your Web3 Action to work, the trigger type must be specified.You don’t need to configure the trigger setting.Web3 Actions without a specified trigger will never run automatically, and you would need to run them manually.

To trigger a Web3 Action manually, click on the **Manual Trigger** button from the top right page menu.You can specify any payload you want as long as it matches the required schema.

If you specify block or transaction as the trigger type, you can fetch a transaction(by entering a transaction hash) or block(by entering the block number) from the actual network instead of manually creating a payload.

For example, if you deploy a Web3 Action that gets triggered once a block is mined on the Mainnet, this is the payload you can use to manually trigger that action.

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "network": "1",
  "blockNumber": 1000,
  "blockHash": "0x5b4590a9905fa1c9cc273f32e6dc63b4c512f0ee14edc6fa41c26b416a7b5d58"
}
```

<Note>
  Manual runs appear in the execution history, but they never create [Error Reporting](/monitoring/web3-actions/references/error-reporting) incidents or send [failure emails](/monitoring/web3-actions/references/notifications#when-failure-emails-are-sent), regardless of outcome. Running a failing Action manually won't exercise the notification path; use a trigger-based run to verify notifications.
</Note>


# Local Development and Testing
Source: https://docs.tenderly.co/monitoring/web3-actions/references/local-development

Achieve faster iteration on Web3 Action code and write automated tests for your action functions using @tenderly/actions-test.

To facilitate local development of your [Web3 Action](/monitoring/web3-actions/introduction) code, you can use the **@tenderly/actions-test** package (contained in tenderly-actions). It exposes a Tenderly runtime, so you can execute and perhaps test your Web3 Action in your local environment.

Install the [**@tenderly/actions-test**](https://github.com/Tenderly/tenderly-actions/tree/main/packages/actions-test) package to test your Web3 Action functions locally.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
yarn add --dev @tenderly/actions-test
```

<Note>
  It’s recommended to keep tests and run scripts for web3-actions outside of the *actions root*
  directory to avoid increasing the size of your Web3 Action project.
</Note>

You can use **@tenderly/actions-test** in two ways to support your development process:

* Use it within your automated tests (**recommended**).
* Create a run script in JavaScript/TypeScript.

### Using @tenderly/actions-test in your tests

To use **@tenderly/actions-test** in your tests, no additional steps are needed. Import `TestRuntime` and events you need to test your Web3 Action and assert the results.

The following examples show how to use the package to invoke the Web3 Action and pass the event object the Action functions expect. For details on the event types you can pass, see [functions, events, and triggers](/monitoring/web3-actions/references/functions-events-triggers).

### A working example

Check out the multisig wallet example and the way it uses **@tenderly/actions-test** to run the action function locally.

<Card title="Running the action function locally" href="https://github.com/Tenderly/examples-web3-actions/tree/main/multisig-wallet#2-run-it-locally" />

### Example: running an Action function within a script

The following example shows a file at **src/web3-actions-local/run.ts** that runs three actions, passing adequate events. Note the Web3 Actions source file (`src/actions/awesomeActions.ts`) is in a sibling to directory containing the script:

#### Step 1: write the run script

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// File: src/web3-actions-local/run.ts
// web3-actions sources location: src/actions/awesomeActions.ts

import {
  TestRuntime,
  TestPeriodicEvent,
  TestWebhookEvent,
  TestTransactionEvent,
} from '@tenderly/actions-test';

import { everyDay, whenDappPosts, onTxEvent } from '../actions/awesomeActions';

/*
 * Running Web3 Actions code locally.
 * TestRuntime is a helper class that allows you to run the functions,
 * and set storage and secrets before running the function
 **/
const main = async () => {
  const testRuntime = new TestRuntime();

  testRuntime.context.secrets.put('multisig.DISCORD_URL', process.env.DISCORD_URL || '');

  await testRuntime.execute(everyDay, new TestPeriodicEvent());

  await testRuntime.execute(whenDappPosts, new TestWebhookEvent({ foo: 'bar' }));

  const te = new TestTransactionEvent();
  te.to = '0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2';
  te.from = '0xc0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0';

  await testRuntime.execute(onTxEvent, te);
};

(async () => await main())();
```

#### Step 2: Extend scripts in package.json of the enclosing project.

You can add this script to your **package.json** file.

```diff title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
    ...
  "scripts": {
    ...
+   "local-w3a-run": "ts-node src/web3-actions-local/run.ts"
    ...
  }
  ...
}
```

#### Step 3: Run the script

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
yarn local-w3a-run
```


# Node RPC Access
Source: https://docs.tenderly.co/monitoring/web3-actions/references/node-rpc-access

Learn how to set up a Web3 Action with access to the Mainnet through Node RPC.

You can access [Node RPC](/node-rpc/overview) directly from your Web3 Action functions. This allows you to send transactions on the Mainnet or testnets and read on-chain data automatically through Web3 Actions.

Setting up Web3 Actions to access the blockchain requires minimal setup, a single Javascript variable. No need to worry about copying/pasting RPC URLs, managing secret keys, etc. Tenderly takes care of all this for you in the background.

In this guide, you’ll learn how to configure your Web3 Action function code to use Tenderly’s production node to access the Mainnet.

## Node RPC in Context

In Web3 Actions, access to Tenderly’s node is enabled through the `context` object. Learn more about [Web3 Actions Context](/monitoring/web3-actions/references/context) here.

The `context` object contains a property called `gateways` which gives you access to the `getGateway()` method. This method requires one argument `Network`, which is used to specify the network you want to access.

The `Network` enum has a member for every network supported in Node RPC, for example:

* `Network.MAINNET`
* `Network.SEPOLIA`
* `Network.POLYGON`
* `Network.OPTIMISTIC`
* `Network.BASE`
* `Network.ARBITRUM`

For the full list, see [`networks.ts` in the `@tenderly/actions` npm package](https://github.com/Tenderly/tenderly-actions/blob/main/packages/actions/src/networks.ts).

To demonstrate how all of this comes together, here’s an example Javascript variable that is configured to access the Mainnet:

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const defaultGatewayURL = context.gateways.getGateway(Network.MAINNET);
```

## Example Web3 Action function to access the Mainnet

Let’s create a simple Web3 Action that will get triggered every time a new block is mined on the Mainnet. Each time a block gets mined, the Web3 Action will execute the custom code, also referred to as “function”. Read more about [Web3 Action functions](/monitoring/web3-actions/references/functions-events-triggers#action-functions) here.

For the sake of simplicity, the example function below will get the block number of the latest block mined and log it to the console.

You can read the comments to understand what each line of code does.

```jsx title="example.jsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// Required libraries that must be included for the code to work
const ethers = require('ethers');
const { Network } = require('@tenderly/actions');

// Do not change the default 'actionFn' name.
const actionFn = async (context, blockEvent) => {
  // Setting a variable that will store the Node RPC RPC URL and secret key
  const defaultGatewayURL = context.gateways.getGateway(Network.MAINNET);

  // Using the Ethere.js provider class to call the RPC URL
  const provider = new ethers.providers.JsonRpcProvider(defaultGatewayURL);

  // Logging the block number of the latest mined block
  console.log(await provider.getBlockNumber());
};

// Exporting the default module. Do not change this.
module.exports = { actionFn };
```

Next, go to the **Dashboard** → **Web3 Actions** → **Add Action**.

<Frame>
  <img alt="Web3 Action set up wizard" />
</Frame>

* For the Trigger Type, select **Block.**
* In the **Function** textbox, paste the code from the example above and click **Next**.

<Frame>
  <img alt="Custom code that is executed when the Web3 Action is triggered" />
</Frame>

* Set the **Trigger** by selecting the network. In our case, that is **Mainnet**.
* Also, set the **Block Period** to tell Tenderly how often to execute the Web3 Action function. For example, if you put 1, the Web3 Action will be executed once every block is mined.
* In the **Info** fields, **add a name** for the Web3 Action and an optional description.
* You can also set a **Destination** where you’ll [receive notifications](/monitoring/web3-actions/references/notifications) about failed executions of the Web3 Action.
* Lastly, **click Create** to deploy the Web3 Action.

From the **Execution History** page, we can see that the Web3 Action is being executed successfully.

<Frame>
  <img alt="Web3 Action execution history" />
</Frame>

You can click on the **Execution ID** to see details about the executed Web3 Action and the payload in JSON.

### Helpful resources

For more information on how to manage your Web3 Actions and monitor execution errors, read the following guides:

* [Managing Web3 Actions](/monitoring/web3-actions/references/lifecycle)
* [Error Reporting for Web3 Actions](/monitoring/web3-actions/references/error-reporting)


# Notifications
Source: https://docs.tenderly.co/monitoring/web3-actions/references/notifications

Set up email notifications for failed Web3 Actions and learn how Tenderly groups repeated failures into incidents and when failure emails are sent.

Tenderly can notify you by email when a [Web3 Action](/monitoring/web3-actions/introduction) fails to execute. Since Web3 Actions often run as part of critical workflows, email notifications let you react quickly when an Action stops working, without watching the Tenderly Dashboard.

<Frame>
  <img alt="Overview of the existing Web3 Actions " />
</Frame>

You can now set up an email as a destination where you will receive Tenderly notifications about failed executions of your set Web3 Action(s) by clicking any Action:

<Frame>
  <img alt="Information about a specific Web3 Action " />
</Frame>

Scroll down to the Destinations section:

<Frame>
  <img alt="Choosing an email destination for Web3 Action notifications" />
</Frame>

We already have a couple of email destinations set up. We can turn them on or off so we don't have to delete certain email delivery channels in periods when we don't want to use them.

To add a new email delivery channel, just click the **Add Destination Email** button in the bottom right corner, type in the email you want to use, and that's it.

You will need to verify your email and turn the switch for that email to "on" after the verification. You can also choose multiple emails as delivery channels for a single Action.

If you are adding an email you are already using as your account email, or if you added that email through some other flow to Tenderly (e.g. through [Alerts](/monitoring/alerts/introduction)), your email will be recognized and you won't have to verify it again.

<Frame>
  <img alt="Adding a new email address" />
</Frame>

You are also able to choose the email notification delivery channels when creating a new action. However, if you want to add a new email as a destination, you will have to do that first before choosing it as an option in the Create New Action flow.

<Frame>
  <img alt="Choosing an email destination upon creating a Web3 Action " />
</Frame>

## When failure emails are sent

Tenderly groups failed executions into incidents instead of emailing you about every failure. When an execution fails, the failure is matched to an incident based on the Action version and the error. You receive an email only when a new incident is created, that is, the first time a given error occurs for the current version of your Action.

While an incident is open, repeated occurrences of the same error are grouped under it and don't trigger additional emails. Incidents are never resolved automatically, even if later executions succeed. Manage them in [Error Reporting](/monitoring/web3-actions/references/error-reporting), where the incident status controls notifications:

* **Acknowledging** an incident keeps notifications for that error muted.
* **Resolving** an incident re-arms notifications: if the same error occurs again, a new incident is created and you receive a new email.

Publishing a new version of the Action also resets the grouping: the first failure of the new version creates a new incident and triggers an email.

Failure emails cover trigger-based executions that fail with an error. Manually triggered runs never send failure emails or create incidents, regardless of outcome, so use a trigger-based run to verify the notification path. Executions that [time out or get rate-limited](/monitoring/web3-actions/references/execution#web3-action-execution-status-types) don't trigger failure emails either.


# Project Structure
Source: https://docs.tenderly.co/monitoring/web3-actions/references/project-structure

Learn about the structure of a Web3 Action project generated via CLI and understand the general layout of the tenderly.yaml configuration file.

In this guide, you’ll learn how to navigate the files and project structure in a Web3 Action project generated via the Tenderly CLI.

Learn [how to use the Tenderly CLI](https://github.com/Tenderly/tenderly-cli).

## Project overview and root directory file structure

When you run the `tenderly actions init` command, the Tenderly CLI will create an *actions* *root* directory along with the necessary files. By default, the *actions root* directory is named *actions*.

However, you're able to specify another name during the initialization process. Once initialized, the name of the root directory can still be adjusted by changing the folder name and the `sources` field inside the `tenderly.yaml` file.

An **example** of a TypeScript-based Web3 Actions project structure:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
src
|--- actions 			# actions root directory, can be renamed
|--- |--- example.ts
|--- |--- package.json
|--- |--- tsconfig.json
|--- |--- node_modules
|         |--- @tenderly/actions
|         |--- typescript
|--- tenderly.yaml
|--- tenderly-schema.json
```

The *actions root* directory contains the npm project for your Web3 Actions. All relevant files, including package.json, node\_modules, source files, and other dependencies, libraries, and resources, are contained in this folder.

**Default files include:**

* `actions/example.ts`: By default, this file contains all Web3 Actions.
* `tenderly.yaml`: This is a configuration file that specifies settings for all Web3 Actions in a project
* `tenderly-schema.json`: Auto-generated JSON Schema that enables IDE validation and autocomplete for `tenderly.yaml`, do not edit `tenderly-schema.json` by hand

<Warning>
  The size of the zipped actions root directory, including `node_modules`, must be under 40MB. Make
  sure you stay below this limit when installing additional packages.
</Warning>

## The tenderly.yaml file structure

The `tenderly.yaml` file contains configurations and settings for a Tenderly project and all Web3 Actions.

For the purpose of this guide, the completed example `tenderly.yaml` file will look like this:

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
$schema: ./tenderly-schema.json
account_id: 'tenderly-username'
project_slug: 'our-cool-project'
actions:
  our-org/our-cool-project:
    runtime: v2
    sources: actions
    specs:
      bestActionEver:
        description: Does the best thing ever
        function: very/organized/file:bestActionEver
        trigger:
          type: block
          block:
            network:
              - 3
            blocks: 10
```

<Note>
  The `$schema` field is automatically added by `tenderly actions init` and points to the generated
  `tenderly-schema.json` file. IDEs that support JSON Schema (VS Code, JetBrains) use this to provide
  autocompletion and inline validation while you edit `tenderly.yaml`. The schema file is also
  regenerated any time you run `tenderly actions init`. Add `tenderly-schema.json` to your
  `.gitignore` if you prefer not to commit it.
</Note>

Now, let’s break down what each section of this file does and how to configure it.

For easier understanding, think of the `tenderly.yaml` as containing two primary sections:

* **General configuration**: A section containing the name of the account and project the Web3 Action is associated with.
* **Web3 Actions configuration**: A section containing configurations for the Web3 Action itself, essentially informing Tenderly when it should be run.

### General configuration

The general configuration section includes the following key-value pairs:

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
account_id: 'johnDoe'
project_slug: 'our-cool-project'
```

* `account_id`: Your username
* `project_slug`: Slug of the project associated with the Web3 Action (optional, can be left empty)

Check out this guide to learn how to [find the organization name, username, and project slug](/platform/account/projects/slug).

### Web3 Actions configuration

The `actions` object is where you start defining your Web3 Actions, including the project settings, such as runtime, sources location, and the actual Web3 Action declaration.

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
account_id: 'johnDoe'
project_slug: ''
actions:
  my-username/my-cool-project: # in case it's an individual project
    # our-cool-org/our-cool-project:   # in case it's an org-level project
    runtime: v2
    sources: actions
    specs: ...
```

### Specifying the project

Start by specifying the composite key that uniquely identifies the project within Tenderly.

* `username/project-slug`: Username and project slug for projects belonging to individual developers
* `org-name/project-slug`: Organization name and project slug if your project belongs to an organization

Check out this guide to learn how to [find the organization name, username, and project slug](/platform/account/projects/slug).

<Note>
  It's possible to use the same Web3 Actions project for multiple projects you have access to in the
  Tenderly Dashboard.
</Note>

### Configuring the runtime

Next, you need to specify the runtime version and the directory that contains your Web3 Action code. This data is used by the Tenderly CLI to bundle and deploy your code to the Web3 Actions runtime on Tenderly’s infrastructure.

The following settings are mandatory:

* `runtime`: The runtime version. Currently, we support **v2**, which corresponds to Node 20.
* `sources`: The location of Web3 Action source files. The value must be a path pointing to the *actions root* directory, relative to the folder containing the `tenderly.yaml` file. It should match the path you specified when running the init command.

**Example:** For the folder structure shown below, the proper value for **sources** would be `web3-actions`.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
src
|-- web3-actions 			# actions root directory, can be renamed
|   |--- example.ts
|   |--- package.json
|   |--- tsconfig.json
|   |--- node_modules
|   	 |--- @tenderly
|        |--- /typescript
|-- tenderly.yaml
```

<Note>
  If you change the `sources` value, a directory must exist at the specified path, relative to the
  *actions root*, and it must contain your source files with Web3 Action functions.
</Note>

### Defining Web3 Actions settings

Individual Web3 Actions are declared under the `specs` object. You can declare multiple Web3 Actions in a single `tenderly.yaml` file.

Each Web3 Action must start with a key that represents the action name (`bestActionEver`). The action name must be unique at the project level and must begin with a letter followed by letters, digits, hyphens, or underscores (pattern: `^[a-zA-Z][a-zA-Z0-9_-]*$`). This key denotes how the deployed Web3 Action is named and represented in the Tenderly Dashboard.

The `description` key must also be included. The description is generally a sentence or two that describes what a Web3 Action does.

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
specs:
  bestActionEver:
    description: Does the best thing ever!
```

Next, you need to specify the `function` key to link to the action function you want to run. Source code for Web3 Actions can be split among multiple files or nested in a custom directory structure. The `tenderly.yaml` file allows for seamless referencing.

For example, a function `bestActionEver` located in `actions/very/organized/file.ts` would be referenced in the yaml like so:

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
our-org/our-cool-project:
  runtime: v2
  sources: actions
  specs:
    bestActionEver:
      description: Does the best thing ever
      function: very/organized/file:bestActionEver
      trigger: ...
```

The next step is to choose and define a trigger for the Web3 Action. A trigger is an event that Tenderly listens to and executes the Web3 Action once a criterion is met.

For an in-depth reference of triggers, explore [available Web3 Action Trigger Types](/monitoring/web3-actions/references/functions-events-triggers).

When defining a **trigger** for a Web3 Action, the first thing to specify is its type. In the example below, we’re defining the *block* trigger type. This means that the `bestActionEver` Web3 Action will run once every 10 blocks get mined on Sepolia.

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
bestActionEver:
  description: Does the best thing ever
  function: very/organized/file:bestActionEver
  trigger:
    type: block
    block:
      network:
        - 11155111
      blocks: 10
```


# How to Build a Custom Oracle
Source: https://docs.tenderly.co/monitoring/web3-actions/tutorials/custom-oracle

Learn how to use Web3 Actions to build a custom oracle for gathering data from real-world systems.

In this tutorial, we’ll show you how to **build a custom Web3 oracle using Tenderly Web3 Actions**. An oracle gathers data from real-world systems and sends it to the blockchain. It acts as an entry point for streaming data from Web2 applications toward smart contracts.

Using oracles, we can access data from sources outside the blockchain (e.g., exchanges, traffic and weather data, gas rates, oil prices, etc) from within our smart contracts.

<Note>
  The entire code is available in [**this Github
  repo**](https://github.com/Tenderly/examples-web3-actions/).
</Note>

## Project Overview

The purpose of this project is to teach you how to build a Web3 Action that fetches data from a Web2 API whenever a smart contract makes a data request through an on-chain event. This data will then be sent to the contract that requested it.

Here’s a quick breakdown of the project’s flow.

* Create a Consumer – a smart contract that requests the ETH price from an Oracle Contract.
* The Oracle Contract requests a new coin price from the CoinGecko API with the `RequestCoinPrice` event.
* Once the price request has been observed, the Web3 Action is called to fetch the value.
* The price value is pushed back to the Oracle Contract.

<Frame>
  <img alt="The interactions between different components" />
</Frame>

We use a pre-made smart contract for this project. Feel free to explore the code and adapt it to your own use case.

Note that the `SimpleCoinConsumer` contract accepts the `coinPrice` coming in only from the `CoinOracle` it was assigned when it got deployed. Additionally, `CoinOracle` accepts updates only if it is signed by the same Wallet that deployed it (`owner`).

## The Plan

Here’s a list of steps we’ll need to take to build our oracle:

* Deploy the `CoinOracle` and `SimpleCoinConsumer` smart contracts.
* Get the API key and other information needed to use one of the Ethereum providers. We’ll store this data in the Web3 Actions Secrets (*needed for interaction 5*).
* Get the Private Key of the account that deployed the Oracle Contract (`owner`) and store it in the Web3 Actions Secrets (*needed to sign transactions in interaction 5*).
* Initialize Tenderly’s Web3 Actions directory on your dev environment and add npm dependencies.
* Create a Web3 Action that will send price updates to the oracle.

### 1: Deploy the Smart Contracts

Both `CoinOracle` and `SimpleCoinConsumer` contracts are stored in the same file: `CoinOracle.sol`. Check out the source code [**in our GitHub repo**](https://github.com/Tenderly/examples-web3-actions/blob/main/simple-coin-oracle/CoinOracle.sol).

The `CoinOracle` contact must be deployed first, before the `SimpleCoinConsumer` contract, preferably using a different Wallet. Make sure to pass the `CoinOracle` address as the constructor parameter.

For the purpose of this tutorial, we’ll deploy to the Ropsten test network (ID is 3) but you’re free to use a different one.

### 2: Initialize Web3 Actions

<Warning>
  For this tutorial, you’ll need access to the **Tenderly Dashboard**. If you don’t have an account,
  [**sign up here for free**](https://dashboard.tenderly.co/register?utm_source=homepage) (no cc
  required as well).
</Warning>

**Install the Tenderly CLI (follow** [**this installation guide**](https://github.com/Tenderly/tenderly-cli#installation)**)**. With the Tenderly CLI installed on your machine, create a new directory `tdly-actions` and `cd` into it to initialize your Web3 Actions using the `tenderly actions init` command.

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
$ cd tdly-actions
$ tenderly actions init
```

When prompted, select your Tenderly projects where you want to deploy Web3 Actions. List out the contents of the directory to explore the files created by the CLI:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
ls actions
example.ts
tsconfig.json
package.json
```

The Tenderly CLI will also create an npm project which will allow your Web3 Actions to use any npm package.

**Install NPM dependencies** - we’ll use Axios to make requests to an external API and Ethers to interact with the blockchain. Run the following command from your terminal to add these dependencies to your npm project:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
cd actions && npm install --save-dev axios ethers @types/node && cd ..
```

### 3: Create Your Web3 Action

Before moving forward, copy the `CoinOracleContract.json` file to the `actions` directory. **You can find this JSON file in Remix or** [**this GitHub repo**](https://github.com/Tenderly/examples-web3-actions/blob/main/simple-coin-oracle/actions/CoinOracleContract.json).

<Warning>
  All files your Web3 Action code uses and references must be placed in the
  `actions` directory (e.g.
  `CoinOracleContract.json`).
</Warning>

Set the `CONTRACT_ADDRESS` variable to the address of your deployed `Oracle`:

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}



const CONTRACT_ADDRESS = '...'; // replace with contract address

export const coinPrice: ActionFn = async (context: Context, event: Event) => {
  let transactionEvent = event as TransactionEvent;

  const ifc = new ethers.utils.Interface(CoinOracleContract.abi);

  const { data, topics } = transactionEvent.logs[0];
  const priceRequest = ifc.decodeEventLog('RequestCoinPrice', data, topics);
  const price = await getPrice();

  const oc = await oracleContract(context, ifc);

  await oc.update(priceRequest.reqId, price, {
    gasLimit: 250000,
    gasPrice: ethers.utils.parseUnits('100', 'gwei'),
  });
  console.log(`Processed: ${priceRequest.reqId} with price in cents: ${price}`);
};

const getPrice = async (coin: string) => {
  const coinInfo = await axios.get(`https://api.coingecko.com/api/v3/coins/${coin}`);
  return coinInfo.data.market_data.current_price.usd * 100;
};

const oracleContract = async (context: Context, contractInterface: ethers.utils.Interface) => {
  const etherscanApiKey = await context.secrets.get('oracle.providerApiKey');

  const provider = ethers.getDefaultProvider(ethers.providers.getNetwork(3), {
    etherscan: etherscanApiKey,
  });

  const oracleWallet = new ethers.Wallet(
    await context.secrets.get('oracle.addressPrivateKey'),
    provider,
  );

  const contract = new ethers.Contract(CONTRACT_ADDRESS, contractInterface, oracleWallet);
  return contract;
};
```

Our Web3 Action will make a call to a CoinGecko API using Axios in `getPrice`. The result we get from the API will be the price in cents. We’ll send this data back to our smart contract.

However, before moving forward, we have to take care of some plumbing.

**Off-road: Deal with Typescript.** If Typescript throws an error, add the following two lines to your `tsconfig.json` file, under `compilerOptions`. This will stop Typescript from frowning upon us for importing a JSON file as an ES module.

```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
"esModuleInterop": true,
"resolveJsonModule": true
```

**Plumbing: Instantiate the Ethers Interface.** The `CoinOracleContract.json` file creates an `Interface` instance that Ethers uses to encode and decode data exchanged when interacting with smart contracts. We’re passing the `abi` part of the entire JSON file.

**Get the Event Data.** Use the `Interface` we just created (`ifc`) to `decodeEventLog`. We know that the first log entry (`logs[0]`) corresponds to the `RequestCoinPrice` event, so this is the one we want to decode. In more complex interactions, you may need to do this dynamically[ **like we did here**](/monitoring/web3-actions/tutorials/on-chain-events).

**Necessary Web3 Plumbing aka Boilerplate.** To interact with our Oracle Contract, we need to do some plumbing. The contract has a restriction - updates can be sent only by the `owner`. This means we need to send transactions from the address that deployed it. The plumbing is done in the `oracleContract` function, and here’s the breakdown of steps.

**Plumbing: Configure a Provider Object.** We can obtain the provider using `ethers.getDefaultProvider` to work with network `3` (Ropsten’s ID). We’re also passing a second argument – a configuration object which contains the API key. Consult [**ethers docs**](https://docs.ethers.io/v5/api/providers/#providers-getDefaultProvider) for more information on how to configure other providers and use alternatives like `JsonRpcProvider`.

**Plumbing: Create a Wallet.** You need to create a `Wallet` to ensure that each transaction originating from our oracle is signed and funded by the same address that deployed the contract. Since the Wallet’s private key is sensitive information, we’re reading it from *Secrets*:

`await context.secrets.get("w3_oracle.oracle_address_private_key")`

**Plumbing: Create a Contract.** This is the step where we piece together everything we’ve created so far:

<ul>
  <li>
    `Contract` instance by passing
    `CONTRACT_ADDRESS`.
  </li>

  <li>
    `contractInterface` for encoding data we want to send
    to the network.
  </li>

  <li>
    `oracleWallet` to sign the transaction.
  </li>
</ul>

**🎉 Send Data Back to the Oracle Contract.** With the plumbing completed, the last line invokes the function `receiveWeatherUpdate` and sends the prediction our oracle has come up with. This bit issues a transaction to our smart contract.

### 4: Specify When Your Web3 Action Gets Executed

We want execute the transaction every time the `RequestCoinPrice` event is fired by the `OracleContract` on the Ropsten network. We want to do this only after the transaction has been mined.

Replace `YOUR_USERNAME` and `YOUR_PROJECT_SLUG` with your Tenderly username and the slug of your project. You can copy those from the Dashboard URL:

`https://dashboard.tenderly.co/{YOUR_USERNAME}/{YOUR_PROJECT_SLUG}/transactions`

Also, replace `CONTRACT_ADDRESS` with the address of your deployed Oracle Contract:

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
account_id: ''
actions:
  YOUR_USERNAME/YOUR_PROJECT_SLUG:
    runtime: v1
    sources: actions
    specs:
      coinOracle:
        description: Swapit
        function: coinOracle:coinPrice
        trigger:
          type: transaction
          transaction:
            status:
              - mined
            filters:
              - network: 3
                eventEmitted:
                  contract:
                    address: CONTRACT_ADDRESS
                  name: RequestCoinPrice
project_slug: ''
```

### 5: Create Web3 Action Secrets

For Web3 Actions to perform operations on the deployed `OracleContract`, we need a way to access the contract. You can choose any provider service (Infura, QuickNode, Alchemy, Etherscan, etc). Check [**Ethers’ Default Provider docs**](https://docs.ethers.io/v5/api/providers/#providers-getDefaultProvider) to find out what’s needed to establish the access.

Since we’re using Etherscan as the provider, we only need the API key. The key will be stored in Web3 Actions Secrets.

<Warning>
  Keep all your sensitive data tucked away safely in the Web3 Actions Secrets (e.g., API keys,
  Wallet private keys, etc). Secrets are highly secure, so even if you try to
  `console.log` the values, they will remain hidden.
</Warning>

**Secrets.** Head over to your Tenderly Dashboard to place the private key you copied in Web3 Actions Secrets. From the sidebar, go to “Actions”, click “Secrets”, and then “Add New”. Name the secret `oracle.providerApiKey` and paste the API token as well as any other sensitive information you need.

<Frame>
  <img alt="Saving your private key to Web3 Action Secrets" />
</Frame>

**Store Oracle Wallet Private Key.** To send transactions to the chain, our Web3 Action needs to have a private key to sign transactions and fund them. The `OracleContract` is designed to only accept updates that are signed by the address that deployed them.

If you’re using Metamask, pick the account you used to deploy the smart contract and copy its private key [**following this Metamask guide**](https://metamask.zendesk.com/hc/en-us/articles/360015289632-How-to-Export-an-Account-Private-Key).

In the Tenderly Dashboard, create a new Secret called `w3_oracle.oracle_address_private_key` and paste the private key.

### 6: Deploy Your Web3 Action

Go to the root of your project (folder containing the `tenderly.yaml` file) and run the following command:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
tenderly actions deploy
```

After the CLI shows successful deployment, you can head to Tenderly Dashboard. There you should see that your Web3 Action has been deployed (or is getting ready to be deployed).

### 7: Execute the Project

To check if what we’ve created so far is working, head back to Remix and invoke the `doSomethingSmart` function of the `SimpleCoinConsumer` contract.

After a while, you should see an execution in the Execution tab in your Tenderly Dashboard. You’ll also see a new transaction that was sent from the oracle’s address by your Web3 Action, calling the `update` function of the `OracleContract` contract. 🎉

<Card title="How to Send a Discord Message About a New Uniswap Pool" href="" />


# Deploy Web3 Action via CLI
Source: https://docs.tenderly.co/monitoring/web3-actions/tutorials/deploy-via-cli

Get started with building Web3 Actions using the Tenderly CLI step by step.

In this guide, you’ll learn how to deploy Web3 Actions via the Tenderly CLI that watches for blocks as they're mined and simply outputs the block number.

### Prerequisites

You need to have npm and the Tenderly CLI installed and properly configured on your local machine. Check out the [Web3 Actions CLI Cheatsheet](/monitoring/web3-actions/references/cli-cheatsheet) for installation instructions.

### Initializing a Web3 Actions Project

Navigate to the folder on your system where you want to place your Web3 Action code and run the following command to initialize a new Web3 Actions project:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
tenderly actions init
```

By default, the project will be configured to use TypeScript. If you prefer plain JavaScript, add the language flag and specify javascript:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
tenderly actions init --language javascript
```

When prompted, select an existing Tenderly project from your account or create a new one.

<Frame>
  <img alt="Creating a new Tenderly project" />
</Frame>

Next, input the name of the root directory where your code will be stored. If you want to leave the default actions, press Enter, or input a custom directory name.

<Frame>
  <img alt="Adding a directory name" />
</Frame>

The folder structure of your project should look like this:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
/actions
|--- .gitignore
|--- example.ts
|--- package.json
|--- package-lock.json
|--- tsconfig.json
|--- /node_modules
      |--- @tenderly
      |--- /typescript
tenderly.yaml
tenderly-schema.json
```

The `tenderly-schema.json` file is a JSON Schema for the `actions` section of `tenderly.yaml`, referenced from its `$schema` key; editors with YAML schema support use it for autocomplete and validation.

### Building and deploying the Web3 Action

These are the steps we need to take to build and deploy a Web3 Action:

* Create the action function
* Configure the block trigger to run the function
* Deploy the code to Tenderly using the CLI

#### Creating an action function

Copy the following code into the **example.ts** file:

```tsx title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import {
  ActionFn,
  Context,
  Event,
  BlockEvent,
} from '@tenderly/actions';

export const blockHelloWorldFn: ActionFn = async (context: Context, event: Event) => {
  let blockEvent = event as BlockEvent;
  console.log('Block number is: ', blockEvent.blockNumber);
};
```

This defines and exports an action function. In the next step, we'll configure it to run after 10 blocks are mined.

**Notes:**

Notice that the function is asynchronous and accepts two arguments - a `Context` object and an `Event` object.

* `Context` object enables access to Storage and Secrets. You can read more about it in the [Context reference](/monitoring/web3-actions/references/context).
* The `event` argument is an object containing information about the external (on-chain) event that triggered the action. Because we want to run this action on a block-related event, the `event` argument will be of type `BlockEvent`. The `BlockEvent` object contains information about the block that was mined, such as the block number, the block hash, and the block timestamp.

#### Configuring the trigger in **tenderly.yaml** for a new action

**Step 1**: Replace the content of the `tenderly.yaml` file with the following (keep the `$schema` line the CLI generated):

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
$schema: ./tenderly-schema.json
account_id: ''
project_slug: ''
actions:
  username/project-slug:
    runtime: v2
    sources: actions
    specs:
      block-number-printer:
        description: Example Web3 Action that logs block number once it is mined.
        function: example:blockHelloWorldFn
        trigger:
          type: block
          block:
            network:
              - 1
            blocks: 10
```

**Step 2**: Replace the `username` and `project-slug` with your username and the slug of your project.

Check out this guide to learn how to [find the organization name, username, and project slug](/platform/account/projects/slug).

**Notes:**

The **tenderly.yaml** file contains specifications of triggers for each action in the project and links the trigger to an action function. Here, we're creating an action called `block-number-printer`.

* The `function` property is referencing the `blockHelloWorldFn` function from the **example.ts** file.
* This action will be triggered on each 10th block mined on network 1, as per the `trigger` property.

Learn more about [External Events and Trigger types](/monitoring/web3-actions/references/functions-events-triggers#external-events-and-trigger-types).

#### Building and deploying actions

Go back to terminal and run the following command to deploy all Web3 Actions you defined. After successful deployment, the actions appear in the Tenderly UI.

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
tenderly actions deploy
```

<Note>
  **Zero downtime upgrade of Web3 Actions**\ To **upgrade** a Web3 Action, just edit the source code
  and/or **tenderly.yaml** and run `tenderly actions deploy.`
</Note>

### Before you go

Keep in mind:

* You must run the `deploy` command from the folder containing **tenderly.yaml** file.
* If you initialize actions for multiple Tenderly projects in the same directory, upon running `deploy` you will be asked to select a project. Only actions belonging to the selected project will be deployed.
* All actions belonging to one project are deployed simultaneously.
* Any file referenced from the JavaScript/TypeScript must be in the *actions root*. Do not reference files outside of this folder.

### Resources

* Learn more about [Web3 Actions Functions, Events, and Triggers](/monitoring/web3-actions/references/functions-events-triggers).
* Learn more about [Context, Storage, and Secrets](/monitoring/web3-actions/references/context).
* Learn more about [Project Structure and **tenderly.yaml** configuration](/monitoring/web3-actions/references/project-structure).


# Deploy Web3 Actions via Dashboard
Source: https://docs.tenderly.co/monitoring/web3-actions/tutorials/deploy-via-dashboard

Build and deploy a Web3 Action using the Web3 Action builder in the Tenderly Dashboard.

This guide shows you how to create a Web3 Action via the Web3 Action builder in the Tenderly Dashboard. Though a practical example, you'll learn how to create a Web3 Action that logs a message to the console every time 10 blocks get mined on the Mainnet.

### Creating a Web3 Action

<Note>
  To continue, [log into your account](https://dashboard.tenderly.co/) or [create a free
  account](https://dashboard.tenderly.co/register) if you don't have one.
</Note>

Once logged in, create a new [Tenderly project](/platform/account/projects/overview) or select an existing one where you want to create your Web3 Action.

From the left-hand menu, select **Web3 Actions**, where you'll see a list of Web3 Actions you've already created in your project.

<Frame>
  <img alt="Navigating to the Actions section" />
</Frame>

If you recently created a project, the list will be empty and you'll have to click the **Add Action** button to create your first Web3 Action.

<Frame>
  <img alt="Creating a Web3 Action" />
</Frame>

The builder has three configuration sections, which this guide walks through together with deployment and monitoring:

1. **Trigger Type**: Choose an on-chain or off-chain event that will trigger the execution of your custom code.
2. **Function:** Your application logic written in JavaScript or TypeScript to be executed when the event occurs.
3. **Trigger:** Each pre-defined trigger (event) has its settings. For example, for the Block event, you can choose the network to be monitored and the number of blocks to be mined for the event to get triggered.

<Frame>
  <img alt="Configuring a new Web3 Action" />
</Frame>

#### Step 1: Choose the trigger type

Choose the event you want the Web3 Action to listen for (the event that will trigger your custom code to run). The builder offers **Block**, **Periodic**, **Webhook**, and **Alert** triggers; an Alert-triggered action runs when one of your [Alerts](/monitoring/alerts/introduction) fires with this action set as its [destination](/monitoring/alerts/destinations/web3-action). The **Transaction** trigger is available only through the [CLI](/monitoring/web3-actions/tutorials/deploy-via-cli).

For example, run your custom code (outlined in the next step) every time a block is mined on the Mainnet network.

<Frame>
  <img alt="Choosing a trigger type for your Web3 Action" />
</Frame>

#### Step 2: Add your custom code

Under the Functions section, paste or write your custom JavaScript or TypeScript code directly. This is the custom logic that will be executed once a block is mined. Learn more about [Web3 Actions functions](/monitoring/web3-actions/references/functions-events-triggers#action-functions).

For example, log the message "Action triggered" to the console once a block is mined.

<Frame>
  <img alt="Adding your custom Web3 Action code" />
</Frame>

<Note>
  Tenderly provides [several JavaScript
  libraries](/monitoring/web3-actions/references/functions-events-triggers#available-libraries-for-dashboard-based-actions)
  for the functions created using the Dashboard.
</Note>

#### Step 3: Specify trigger settings

Specify the trigger-specific configurations. Each trigger type has different settings. Learn more about [Web3 Actions Events](/monitoring/web3-actions/references/functions-events-triggers#external-events-and-trigger-types) and how to configure them.

For the Block trigger type, you need to define two additional parameters: the network (Mainnet) and the block period (10). This means that our code will get executed every 10th block mined on the Mainnet network.

<Frame>
  <img alt="Specifying trigger settings" />
</Frame>

#### Step 4: Add the title and description

In the **Info** section, add the Web3 Action and title and description. The title and description don't influence the behavior of your Web3 Actions.

<Frame>
  <img alt="Adding a title and a description for your Web3 Action" />
</Frame>

Optionally, you can select where you'd like Tenderly to send you notifications about failed Web3 Actions. To receive email notifications, activate the toggle. While this step is optional, enabling notifications will help give you visibility into why your Web3 Actions are failing and help you build more reliable systems.

<Frame>
  <img alt="Activating email notifications for possible Web3 Action failure" />
</Frame>

#### Step 5: Deploy your Web3 Action

When finished, click the **Create** button to build and deploy your Web3 Action. Once deployed, you'll be forwarded to the Overview page, where you can [stop, upgrade, and delete your Web3 Action](/monitoring/web3-actions/references/lifecycle).

<Frame>
  <img alt="An overview of your Web3 Action" />
</Frame>

#### Step 6: Monitor your Web3 Action

Monitor the execution of your Web3 Actions by clicking the **Execution History** tag from the top page menu. This is where you'll see a log entry for every execution instance of your Web3 Action.

<Frame>
  <img alt="Monitoring the execution of your Web3 Action" />
</Frame>

### Deploy and manage Web3 Actions programmatically

If you prefer to specify action triggers through YAML configuration and have your action functions in your project's code-base, follow the Quickstart on **building and deploying a Web3 Action using CLI**.

<Note>
  Transaction-triggered Web3 Actions can be built only using the CLI approach.
</Note>

### Resources

* Learn more about [Web3 Actions Functions, Events, and Triggers](/monitoring/web3-actions/references/functions-events-triggers).
* Learn more about [Context, Storage, and Secrets](/monitoring/web3-actions/references/context) available to action functions.
* Learn more about [Project Structure and **tenderly.yaml** configuration](/monitoring/web3-actions/references/project-structure).


# Discord Alerts for New Uniswap Pools
Source: https://docs.tenderly.co/monitoring/web3-actions/tutorials/discord-uniswap-pools

Follow a step-by-step guide to create a Web3 Action that will send you a Discord message whenever a new Uniswap V3 pool is created.

This tutorial shows you **how to use a [Web3 Action](/monitoring/web3-actions/introduction) to send a message to a Discord channel when a new pool is created on Uniswap V3**. You can use this Web3 Action to notify your community when something happens on the chain.

<Note>
  The entire code is available in [**this Github
  repo**](https://github.com/Tenderly/examples-web3-actions/). Note that it’s in a separate branch
  at the moment.
</Note>

## Project Overview

The goal of this project is to teach you how to use Web3 Actions to send a Discord message whenever a Uniswap Pool is made. We’ll show you two approaches - the more convenient one is to use `PoolCreated` event as a trigger for our Web3 Action (see [functions, events, and triggers](/monitoring/web3-actions/references/functions-events-triggers) and the [**Uniswap docs**](https://developers.uniswap.org/protocol/V2/reference/smart-contracts/factory#paircreated)).

## The Plan

* Add contracts to your Tenderly project - [**UniswapV3ContractFactory**](https://dashboard.tenderly.co/nenad/uniswap/contract/mainnet/0x1f98431c8ad98523631ae4a59f267346ea31f984). It’s already verified and present in Tenderly, so you just need to add them to your project.
* Store the Discord Webhook URL in your Web3 Action Secrets.
* Create a Web3 Action that will respond to the `[PoolCreated](<https://developers.uniswap.org/protocol/reference/core/interfaces/IUniswapV3Factory#poolcreated>)`event.

### 1: Add Uniswap Contracts to Your Tenderly Project

Web3 Actions require that smart contracts used to specify triggers are verified in Tenderly.

Web3 Actions require that smart contracts used to specify triggers are verified in Tenderly. Since we’re using existing contracts, you can find them using the search bar by typing in the contract name or address.

Alternatively, go to [**UniswapV2ContractFactory**](https://dashboard.tenderly.co/contract/mainnet/0x5c69bee701ef814a2b6a3edd4b1652cb9cc5aa6f) and click **“Add to Project”**. Do the same for [**UniswapV2Pair**](https://dashboard.tenderly.co/contract/mainnet/0xd849b2af570ffa3033973ea11be6e01b7ba661d9).

### 2: Create a Web3 Action for the PoolCreated Event

Below you’ll find the code for our Web3 Action as well as an explanation of how it works:

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}


export const onPoolCreatedEventEmitted: ActionFn = async (context: Context, event: Event) => {
  try {
    const txEvent = event as TransactionEvent;

    const eventLog = await getPoolCreatedEvent(txEvent);

    const tokensData = await getTokensData(eventLog.token0, eventLog.token1);
    console.log('Received Tokens Data: ', tokensData);

    await notifyDiscord(`${tokensData.token0.name} ↔️ ${tokensData.token1.name}`, context);
  } catch (error) {
    console.error(error);
  }
};

const getPoolCreatedEvent = async (txEvent: TransactionEvent) => {
  const ifc = new ethers.utils.Interface(UniswapV3FactoryAbi);
  const poolCreatedTopic = ifc.getEventTopic('PoolCreated');

  const poolCreatedEventLog = txEvent.logs.find(log => {
    return log.topics.find(topic => topic == poolCreatedTopic) !== undefined;
  });

  if (poolCreatedEventLog == undefined) {
    throw Error('PoolCreatedEvent missing');
  }
  return ifc.decodeEventLog(
    'PoolCreated',
    poolCreatedEventLog.data,
    poolCreatedEventLog.topics,
  ) as unknown as UniswapPool;
};

const getTokensData = async (token0: string, token1: string) => {
  const tokenFields = `id, name, symbol, totalValueLocked, totalSupply, derivedETH`;
  const theGraphQuery = `
{
	token0: token(id:"${token0.toLowerCase()}"){${tokenFields}},
	token1: token(id:"${token1.toLowerCase()}"){${tokenFields}}
}`;

  const UNISWAP_THE_GRAPH = 'https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v3';
  const resp = await axios.post(UNISWAP_THE_GRAPH, {
    query: theGraphQuery,
  });

  return resp.data.data as unknown as {
    token0: UniwswapToken;
    token1: UniwswapToken;
  };
};

const notifyDiscord = async (text: string, context: Context) => {
  console.log('Sending to Discord:', `🐥 ${text}`);
  const webhookLink = await context.secrets.get('discord.uniswapChannelWebhook');
  await axios.post(
    webhookLink,
    {
      content: `🐥 ${text}`,
    },
    {
      headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
      },
    },
  );
};

type UniswapPool = {
  token0: string;
  token1: string;
  fee: number;
  tickSpacing: number;
  pool: number;
};

type UniwswapToken = {
  id: string;
  name: string;
  symbol: string;
  tokenValueLocked: number;
  totalSupply: number;
  derivedEth: number;
};
```

**Obtain Tokens in the Newly Created Pool.** To get information about two tokens in the new pool, we need to search through the transaction logs in the `getEventLog` function. We’re using Ethers and the ABI of the contract: `UniswapV3FactoryAbi`. Go to the `UniswapV3Factory` [**contract in Tenderly**](https://dashboard.tenderly.co/nenad/uniswap/contract/mainnet/0x1f98431c8ad98523631ae4a59f267346ea31f984), click **“View ABI”** and copy/paste it to a local file in the `actions` directory.

Essentially, we’re looking for the log entry in the topic `PoolCreate`. First, we’re taking a reference of that topic (`poolCreatedTopic = ifc.getEventTopic("PoolCreated")`) and then we’re filtering the actual logs (`tx.logs`) until we find the entry referencing that topic. Lastly, we’re decoding the log we found (`poolCreatedEventLog`) using Ethers. This is the event we’re looking for, and it contains the addresses of the tokens: `token0` and `token1`.

**Obtain Token Data Using Uniswap’s Graph API on TheGraph.** Uniswap exposes access to its data through [**TheGraph**](https://thegraph.com/hosted-service/subgraph/uniswap/uniswap-v3). We’re using the `getTokensData` function to query TheGraph and get several fields for the `token0` and `token1` IDs – the ones present in the `PoolCreated` event from the first step.

**Notify the Discord Community.** Having gathered all the relevant information, we are ready to send a message to our Discord channel. With the `notifyDiscord` function, we need to get the Webhook URL from the `secrets`. We’re using Axios to make an HTTP post request to run the Webhook and pass the content.

### 3: Configure Your Web3 Action

In the `tenderly.yaml` file, we’re need to specify that we want to have `uniswapActions:onPoolCreatedEventEmitted` ran when an event is fired from the `UniswapV3Factory` contract (on address `0xd849b2af570ffa3033973ea11be6e01b7ba661d9`) within a transaction that is mined on the Mainnet (network 1).

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
account_id: ''
actions:
  YOUR_USERNAME/YOUR_PROJECT_SLUG:
    runtime: v1
    sources: actions
    specs:
      uniswapNewPool:
        description: Runs when a new swap is made on Uniswap
        function: uniswapActions:onPoolCreatedEventEmitted
        trigger:
          type: transaction
          transaction:
            status:
              - mined
            filters:
              - network: 1
                eventEmitted:
                  contract:
                    address: 0xd849b2af570ffa3033973ea11be6e01b7ba661d9
                  name: PoolCreated
project_slug: ''
```

### 4: Store the Discord Webhook URL in Secrets

Before running our Web3 Action in Tenderly, we have to set the value for the Discord Webhook.

In the Tenderly Dashboard, go to the Actions page of your project and click Secrets. Add a new secret named `discord.uniswapChannelWebhook` and paste your Discord channel’s Webhook.

### 5: Deploy and Try Out Your Web3 Action

Deploy your Web3 Action by running this command:

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
tenderly actions deploy
```

**To try out if your Web3 Action is working, go to the Actions page in your Tenderly Dashboard. Select your Action and click Manual Trigger.**

That’s all! Hopefully, you’ve received a message on your Discord channel 🎉


# Modular Monitoring with Web3Actions
Source: https://docs.tenderly.co/monitoring/web3-actions/tutorials/modular-actions

Build a modular monitoring system with Web3 Actions and Alerts to track onchain events, process traces, and deliver webhook notifications.

This guide demonstrates how to build a flexible monitoring system that can track any on-chain event, process transaction data, and deliver real-time notifications through webhooks. By combining powerful trigger criterias of Tenderly's Alert system with Web3Actions, you'll create a modular monitoring infrastructure that can adapt to any blockchain monitoring need, from simple event tracking to complex multi-contract interactions.

<Note>
  This guide assumes you have a Tenderly account and basic familiarity with Web3Actions and blockchain events.
</Note>

<Card title="Modular Monitoring with Web3Actions" href="" />

## Prerequisites

Before starting, ensure you have:

* [Node.js](https://nodejs.org/) (**v20** currently supported as latest version)
* [Tenderly CLI](https://github.com/Tenderly/tenderly-cli) installed
* A webhook endpoint for receiving data
* Basic understanding of TypeScript

## System Setup

<Steps>
  ### Create Alert

  * **Alert Type:** We'll set it up as **Successful Transaction**. You can find detailed steps [here](/monitoring/alerts/types#successful-transaction)

  <Frame>
    <img alt="Setup Successful Transaction Alert" />
  </Frame>

  * **Alert Target:** As a target we'll use **Tag** which let us monitor all contracts and wallets labeled with the specific tag. You can check here how to add **Tag** for [contract](/developer-explorer/contracts#adding-tags-to-contracts) or [wallet](/developer-explorer/wallets#adding-tags-to-wallets).

  <Frame>
    <img alt="Setup Tag as an Alert Target" />
  </Frame>

  * **Alert Parameter:** Choose **Tag** from the dropdown that holds contracts we want to monitor

  <Frame>
    <img alt="Choose Tag you want to use" />
  </Frame>

  * **Alert Destination:** For now you can setup whatever you want, in the next phase we'll set up Web3Action to be Destination for this Alert

  ### Install Dependencies

  * Clone the repo. You can find link to the template [here](https://github.com/Tenderly/flexible-monitoring-solution)

  * Once you've cloned the repo, run the following command inside CLI:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  cd actions && npm install
  ```

  ### Configure Environment Variables

  Set up these [Secrets](/monitoring/web3-actions/references/context#secrets) in your Tenderly Web3Action:

  ```env showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  WEBHOOK_URL = <Your webhook URL>
  BEARER = <Your Tenderly API bearer token>
  ACCOUNT_SLUG = <Your Tenderly account slug>
  PROJECT_SLUG = <Your project slug>
  EVENT_NAME = <Name of the event to track>
  ```

  ### Configure tenderly.yaml

  Your `tenderly.yaml` should look like this:

  ```yaml showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  account_id: "<YOUR_ACCOUNT_ID>"
  actions:
    <YOUR_ACCOUNT_ID>/<PROJECT_SLUG>:
      runtime: v2
      sources: actions
      specs:
        example:
          description: "Event tracking system"
          function: example:modularFn
          trigger:
            type: alert
            alert: { <YOUR_ALERT_ID> }
          execution_type: parallel
  project_slug: "<PROJECT_SLUG>"
  ```

  Be sure to replace the placeholders with following values:

  * `YOUR_ACCOUNT_ID`: Your account ID you can get following [this guide](/platform/account/projects/slug).
  * `PROJECT_SLUG`: Your project slug you can get following [this guide](/platform/account/projects/slug).
  * `YOUR_ALERT_ID`: The ID of alert you've created in the previous step. You can find the ID in the dashboard.

  <Frame>
    <img alt="Finding the Alert ID" />
  </Frame>

  ### Deploy your Web3 Action

  Run the following command to deploy your Web3 Action:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  tenderly actions deploy
  ```
</Steps>

## Core Components

### Transaction Processing

The system begins by processing transaction information:

```typescript showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export const modularFn = async (context: Context, transactionEvent: TransactionEvent) => {
  const txHash = transactionEvent.hash;
  const txNetwork = transactionEvent.network;

  const blockHash = transactionEvent.blockHash;
  const blockNumber = transactionEvent.blockNumber;

  const WEBHOOK_URL = await context.secrets.get("WEBHOOK_URL");
  const BEARER = await context.secrets.get("BEARER");
  const ACCOUNT_SLUG = await context.secrets.get("ACCOUNT_SLUG");
  const PROJECT_SLUG = await context.secrets.get("PROJECT_SLUG");
  const EVENT_NAME = await context.secrets.get("EVENT_NAME");

  if (!EVENT_NAME) {
    throw new Error("EVENT_NAME not found in environment variables");
  }

  const url = `https://api.tenderly.co/api/v1/public-contract/${txNetwork}/trace/${txHash}`;

  const traceResponse = await axios.get(url, {
    headers: {
      authorization: BEARER,
    },
  });

  const traceData = traceResponse.data;
```

This component:

* Captures transaction hash and network
* Retrieves transaction traces via Tenderly API
* Processes block information

### Contract Information Retrieval

Contract information (names and ABIs) are fetched using the [Contracts API](/api-reference).

```typescript showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const fetchContractName = async (addr: string) => {
  const contractEndpoint = `https://api.tenderly.co/api/v1/account/${ACCOUNT_SLUG}/project/${PROJECT_SLUG}/contract/${txNetwork}/${addr}`;

  try {
    const contractResponse = await axios.get(contractEndpoint, {headers: {'Authorization': BEARER}});
    return contractResponse.data.contract.contract_name;
  } catch (error) {
    console.error(`Error fetching contract name from endpoint for ${addr}:`, error);
  }
};

const fetchContractAbi = async (addr: string) => {
  const contractEndpoint = `https://api.tenderly.co/api/v1/account/${ACCOUNT_SLUG}/project/${PROJECT_SLUG}/contract/${txNetwork}/${addr}`;

  try {
    const contractResponse = await axios.get(contractEndpoint, {headers: {'Authorization': BEARER}});
    return contractResponse.data.contract.data.abi;
  } catch (error) {
    console.error(`Error fetching contract ABI from endpoint for ${addr}:`, error);
  }
};
```

### Event Processing

Event processing is handled through specialized functions:

```typescript showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const extractEventAddresses = (logs: any[]): string[] =>
  Array.from(new Set(
    logs
      .filter(log => log.name === EVENT_NAME)
      .map(log => log.raw.address)
  ));

const extractEventDetails = (logs: any[]) => {
  return logs
    .filter(log => log.name === EVENT_NAME)
    .map(log => {
      const result: { [key: string]: string } = {
        name: log.name
      };

    log.inputs.forEach((input: any) => {
      const name = input.soltype.name;
      const value = input.value.toString();
      result[name] = value;
    });

    return result;
  });
};
```

This section:

* Filters events by name
* Extracts event parameters
* Processes event addresses

## Webhook interaction

The system sends this structured data to your webhook using Axios:

```typescript showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  hash: string,              // Transaction hash
  transaction: object,       // Full transaction event
  blockHash: string,        // Block hash
  blockNumber: number,      // Block number
  matchReasons: Array<{     // Event details
    name: string,
    [parameterName: string]: string
  }>,
  sentinel: {               // Contract information
    contractName: string,
    abi: object
  },
  traceData: object,        // Transaction trace data
  addresses: string[]       // Involved addresses
}
```

## Troubleshooting

Common issues and solutions:

1. **Missing Events**
   * Verify EVENT\_NAME matches contract events exactly
   * Check alert configuration in Tenderly dashboard
   * Review transaction logs for event emission

2. **API Errors**
   * Validate BEARER token permissions
   * Check API endpoint availability
   * Verify network configuration

3. **Webhook Issues**
   * Confirm WEBHOOK\_URL accessibility
   * Check payload format matches expectations
   * Monitor webhook endpoint logs


# Monitor UniswapV3 Pool Creation
Source: https://docs.tenderly.co/monitoring/web3-actions/tutorials/monitor-uniswap-v3-pools

Learn how to use Tenderly Web3 Actions to monitor new pool creations in UniswapV3Factory and perform automated actions.

In this tutorial, we'll show you how to set up a **Tenderly Web3 Action to monitor new pool creations in the UniswapV3Factory contract** and perform automated actions. This project demonstrates how to use Web3 Actions to interact with smart contracts and Tenderly's features to create a custom monitoring system.

<Card title="UniswapV3Factory monitoring Web3 Action template" href="" />

## Project Overview

The purpose of this project is to set up a system that monitors new pool creations in the UniswapV3Factory contract and performs automated actions when specific conditions are met. Here's a quick breakdown of the project's flow:

1. The Web3 Action listens for `PoolCreated` events from the UniswapV3Factory contract on the Ethereum mainnet.
2. When an event is detected, it extracts the new pool's address from the event data.
3. The action adds the new pool contract to your Tenderly project and tags it for easier management.

## Prerequisites

Before you begin, make sure you have the following:

* [Tenderly CLI](https://github.com/Tenderly/tenderly-cli) installed
* [Node.js](https://nodejs.org/) (v20 currently supported)
* [npm](https://www.npmjs.com/)
* A Tenderly account and project

## Setup

Let's go through the steps to set up your `UniswapV3Factory` Monitoring system:

<Steps>
  ### Create a New Tenderly Project

  If you haven't already, create a new project in your Tenderly dashboard or use an existing one.

  ### Create an Alert in Tenderly

  1. Log into your Tenderly Dashboard
  2. Navigate to your project
  3. Go to the **Alerts** tab and click on **New Alert**
  4. Set the Alert Type to **Event Emitted**
  5. Configure the alert:
     * **Contract Address:** `0x1f98431c8ad98523631ae4a59f267346ea31f984` (UniswapV3Factory contract)
     * **Event Signature:** `PoolCreated(address,address,uint24,int24,address)`
     * Name your alert appropriately for easy reference
  6. Save the alert and note down the `id` of an alert for later use

  ### Initialize Web3 Action Project

  Open a terminal and run the following command to initialize a new Web3 Actions project:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  tenderly actions init
  ```

  Select your Tenderly project when prompted and choose a directory name for your actions.

  ### Configure tenderly.yaml

  Update the `tenderly.yaml` file with the following configuration:

  ```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  account_id: "<YOUR_ACCOUNT_ID>"
  actions:
    <YOUR_ACCOUNT_ID>/<YOUR_PROJECT_SLUG>:
      runtime: v2
      sources: actions
      specs:
        uniswapV3:
          description: "Monitoring UniswapV3 Factory Contract and adding Child/Pool to Contracts page with proper tag"
          function: uniswapV3Monitoring:actionFn
          trigger:
            type: alert
            alert: { <ALERT_ID> }
          execution_type: parallel
  project_slug: "<YOUR_PROJECT_SLUG>"
  ```

  Replace `<YOUR_ACCOUNT_ID>`, `<YOUR_PROJECT_SLUG>`, and `<ALERT_ID>` with your actual Tenderly `Account Name`, `Project Slug`, and the `Alert ID` you noted earlier.

  ### Set Up Secrets

  Add the following secret to your Tenderly project settings:

  * `ACCESS-KEY`: Your Tenderly [API access key](/platform/account/projects/api-tokens)

  To add secrets, go to your Tenderly project settings and navigate to the "Secrets" section.

  ### Implement the Web3 Action

  Create a new file in your actions directory named `uniswapV3Monitoring.ts` and implement your Web3 Action logic as follows:

  ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  const ethers = require('ethers');

  const actionFn = async (context: Context, alertEvent: AlertEvent) => {
    const key = await context.secrets.get('ACCESS-KEY');

    const accountSlug = '<YOUR_ACCOUNT_ID>';
    const projectSlug = '<YOUR_PROJECT_SLUG>';
    const tagName = 'pool';

    const tenderly = new Tenderly({
      accountName: accountSlug,
      projectName: projectSlug,
      accessKey: key,
      network: Number(alertEvent.network),
    });

    const poolCreatedSignature = ethers.utils.id("PoolCreated(address,address,uint24,int24,address)");

    let poolAddress = "";
    for (const log of alertEvent.logs) {
      if (log.topics[0] === poolCreatedSignature) {
        const data = log.data;
        const addressHex = data.substring(data.length - 40);
        poolAddress = ethers.utils.getAddress('0x' + addressHex).toLowerCase();
        break;
      }
    }

    try {
      await tenderly.contracts.add(poolAddress, {
        displayName: 'Pool'
      });
      await tenderly.contracts.update(poolAddress, { appendTags: [tagName] });
      console.log(`Pool contract is: ${poolAddress}, and has been added with tag ${tagName}`);
    } catch (error) {
      console.error('Error adding contract:', error);
    }
  };

  module.exports = { actionFn };
  ```

  Make sure to replace `<YOUR_ACCOUNT_ID>` and `<YOUR_PROJECT_SLUG>` with your actual Tenderly `Account Name` and `Project Slug`.

  ### Deployment

  To deploy your Web3 Action, use the Tenderly CLI:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  tenderly actions deploy
  ```

  This command will deploy the action defined in your `tenderly.yaml` file.
</Steps>

## How it Works

The Web3 Action you've set up will automatically trigger whenever the `PoolCreated` event is emitted by the `UniswapV3Factory` contract. Here's a breakdown of the `actionFn` function:

1. Retreive the `ACCESS-KEY` secret from the Tenderly context.
2. Initialize a new Tenderly SDK instance with your account and project details.
3. Define the `PoolCreated` event signature using ethers.js.
4. Loop through the event logs to find the `PoolCreated` event and extracts the new pool's address.
5. Using the Tenderly SDK, add the new pool contract to your Tenderly project with the display name `Pool`.
6. Tag the new pool contract with the `pool` tag for easier management.
7. Log the pool address and confirmation of the tagging process.

<Note>
  This implementation automatically adds new Uniswap V3 pools to your Tenderly project and tags them, making it easier to monitor and manage these contracts.
</Note>

## Customization

To modify the behavior of your Web3 Action:

1. Edit the `actionFn` in the `uniswapV3Monitoring.ts` file.
2. You can change the `tagName` variable to use a different tag for the pools.
3. Add additional logic to process more information from the event or perform other actions with the Tenderly SDK.

For example, to add more detailed logging:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
console.log(`New pool created: ${poolAddress}`);
console.log(`Network: ${alertEvent.network}`);
console.log(`Transaction hash: ${alertEvent.hash}`);
```

## Monitoring and Troubleshooting

To ensure your Web3 Action is working correctly:

* Monitor your Web3 Action executions in the Tenderly dashboard
* Check the Tenderly logs for any error messages or execution details
* Use Tenderly's debugging tools to inspect transaction details and contract interactions
* Check your Tenderly project's Contracts page to see the newly added and tagged pool contracts

<Warning>
  This setup is specifically designed to monitor the `UniswapV3Factory` contract on the Ethereum mainnet.
</Warning>

## Conclusion

You've now set up a custom monitoring system using Tenderly Web3 Actions to track new pool creations in the `UniswapV3Factory` contract. This project demonstrates how to interact with smart contracts, use Tenderly's SDK, and create an automated system for monitoring and responding to specific blockchain events.

For more information on Uniswap V3 and its contracts, refer to the [Uniswap V3 documentation](https://developers.uniswap.org/protocol/reference/core/UniswapV3Factory).


# How to Access Node RPC from Web3 Actions
Source: https://docs.tenderly.co/monitoring/web3-actions/tutorials/node-rpc-access

Learn how to use Web3 Actions and Node RPC to find contracts with the same bytecode that were deployed by another contract.

In this tutorial, we’ll create a Web3 Action that runs each time `UniswapV2Factory` deploys a new `UniswapV2Pair` contract. The Web3 Action will compare the bytecode of the newly deployed contract with the bytecode of another `UniswapV2Pair` contract. In this case, we’ll use the USDC Pair contract.

To obtain the bytecodes, we’ll use [Node RPC](/node-rpc/overview) as our node provider. If the bytecodes match, the Web3 Action will store the pair’s address and contract’s bytecode in the Storage of the Web3 Action.

If you want to skip the tutorial, here’s the complete solution:

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}



type UniswapPair = {
  token0: string;
  token1: string;
  pair: string;
};

const USDC_PAIR_CONTRACT_ADDRESS = '0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc';

export const onPairCreatedEventEmitted: ActionFn = async (context: Context, event: Event) => {
  try {
    const txEvent = event as TransactionEvent;
    const newPair = await getPairCreatedEvent(txEvent);

    const gatewayURL = context.gateways.getGateway(Network.MAINNET);
    const provider = new ethers.providers.JsonRpcProvider(gatewayURL);

    const usdcPairContract = await provider.getCode(USDC_PAIR_CONTRACT_ADDRESS);
    const newPairContract = await provider.getCode(newPair.pair);

    if (usdcPairContract === newPairContract) {
      const pairContracts = await context.storage.getJson('PairContracts');
      pairContracts[newPair.pair] = newPairContract;
      await context.storage.putJson('PairContracts', pairContracts);
    }
  } catch (error) {
    console.error(error);
  }
};

const getPairCreatedEvent = async (txEvent: TransactionEvent): Promise<UniswapPair> => {
  const i = new ethers.utils.Interface(UniswapV2FactoryAbi);
  const pairCreatedTopic = i.getEventTopic('PairCreated');

  const pairCreatedEventLog = txEvent.logs.find(log => {
    return log.topics.find(topic => topic == pairCreatedTopic) !== undefined;
  });

  if (pairCreatedEventLog == undefined) {
    throw Error('PairCreatedEvent missing');
  }

  return i.decodeEventLog(
    'PairCreated',
    pairCreatedEventLog.data,
    pairCreatedEventLog.topics,
  ) as unknown as UniswapPair;
};
```

### Prerequisites

<Note>
  The triggering mechanism for Web3 Actions works only if the contract used in the trigger
  definition is verified on Tenderly. Learn [how to verify contracts on Tenderly
  here](/contract-verification/overview).
</Note>

In this example, we'll be using the `UniswapV2Factory` and `UniswapV2Pair` contracts. Since both contracts are publicly verified on Tenderly, there is no need to verify them manually.

Navigate to the [UniswapV2Factory](https://dashboard.tenderly.co/contract/mainnet/0x5c69bee701ef814a2b6a3edd4b1652cb9cc5aa6f) and click the **Add to Project** button to add the contract to your project. Repeat the same step for [UniswapV2Pair](https://dashboard.tenderly.co/contract/mainnet/0xd849b2af570ffa3033973ea11be6e01b7ba661d9).

## Step 1: Define the trigger

Whenever the [`createPair` function](https://developers.uniswap.org/contracts/v2/reference/smart-contracts/factory#createpair) of the `UniswapV2Factory` contract gets called, the following occurs:

* A new [UniswapV2Pair](https://developers.uniswap.org/contracts/v2/reference/smart-contracts/pair) contract gets created for the token pair (if one doesn’t already exist)
* A [`PairCreated`](https://developers.uniswap.org/contracts/v2/reference/smart-contracts/factory#paircreated) event gets emitted

We can define the trigger to run a Web3 Action each time a transaction hitting a contract calls a function that emits a specific event.

In our case, we’ll write the trigger that fires each time a `UniswapV2Factory` contract emits a `PairCreated` event. In other words, whenever a new `UniswapV2Pair` contract is deployed.

The configuration for the trigger looks like this, and it needs to be saved in the `tenderly.yaml` file:

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
account_id: ''
actions:
  YOUR_USERNAME/YOUR_PROJECT_SLUG:
    runtime: v2
    sources: actions
    specs:
      uniswapNewPair:
        description: Runs when a new pair is created on uniswap
        function: uniswapActions:onPairCreatedEventEmitted
        execution_type: parallel
        trigger:
          type: transaction
          transaction:
            status:
              - mined
            filters:
              - network: 1
                eventEmitted:
                  contract:
                    address: 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f
                  name: PairCreated
project_slug: ''
```

## Step 2: Define the Web3 Action logic

When our Web3 Action runs, it receives two inputs:

* A [`context`](/monitoring/web3-actions/references/context)object that provides access to Node RPC and Storage
* A [`transactionEvent`](/monitoring/web3-actions/references/functions-events-triggers#transaction-event) payload containing data relevant to the transaction that triggered the Web3 Action

We’ll use the `context` object to access `gateways`, which will be our node provider for Ethers and Storage for storing matched bytecode.

<Note>
  Learn [how to use Node RPC in Web3
  Actions](/monitoring/web3-actions/references/node-rpc-access) to access any of
  the supported networks, including Mainnet, without the hassle of managing URLs or secret keys.
</Note>

As for the `transactionEvent` payload, we’ll use its `logs` property to find the event log corresponding to the `PairCreated` topic.

### Step 2.1: Decode the PairCreated event

When triggered, the Web3 Action needs to find the `PairCreated` event in the payload’s logs. We’ll put this code in the `getPairCreatedEvent` function.

To get the hash for the `PairCreated` topic, we need to use the ABI of the `UniswapV2Factory` contract. To do so, go to the `UniswapV2Factory` [contract in Tenderly](https://dashboard.tenderly.co/contract/mainnet/0x5c69bee701ef814a2b6a3edd4b1652cb9cc5aa6f), click **View ABI** and copy/paste it to a local file in the `actions` directory.

<Note>
  Explore the [project structure of a Web3 Action
  here](/monitoring/web3-actions/references/project-structure).
</Note>

Now we can get the reference of that topic with the following code:

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const i = new ethers.utils.Interface(UniswapV2FactoryAbi);
const pairCreatedTopic = i.getEventTopic('PairCreated');
```

Next, we need to go through the transaction logs and find the entry referencing that topic like so.

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const pairCreatedEventLog = txEvent.logs.find(log => {
  return log.topics.find(topic => topic == pairCreatedTopic) !== undefined;
});
```

Finally, we’ll be decoding the log entry into the `UniswapPair` type using Ethers.

The result of the `getPairCreatedEvent` function is then an object that contains the following:

* Addresses of the tokens constituting the pair - `token0` and `token1` properties
* Address of the deployed `UniswapV2Pair` contract - `pair` property

## Step 3: Compare the bytecodes

Now that we have the address of the newly deployed contract (contained in the `pair` property of the `UniswapPair` type), we can use it to get the contract’s bytecode.

We’ll be using the `USDC UniswapV2Pair` contract’s bytecode to determine if the newly created contract’s bytecode is a valid `UniswapV2Pair` contract. Their bytecodes must match exactly.

To get the bytecodes of those contracts, we need to use the Ethers `getCode` function.

To complete these steps, we first need to set up a node provider, Node RPC: `gateways`.

By accessing the `gateways` property of the `context` object, we can easily obtain the JSON-RPC URL for our desired network (`MAINNET`, in our case) by invoking the `getGateway()` function and using it as the provider for Ethers.

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const gatewayURL = context.gateways.getGateway(Network.MAINNET);
const provider = new ethers.providers.JsonRpcProvider(gatewayURL);
```

This will allow us to get the bytecode of both the new pair and the USDC pair.

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const usdcPairContract = await provider.getCode(USDC_PAIR_CONTRACT_ADDRESS);
const newPairContract = await provider.getCode(newPair.pair);
```

If there is a match, we want to store the bytecode of the new pair in the format `pair_address: bytecode` under a JSON property named `PairContracts` in our project’s Storage:

```tsx title="example.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
if (usdcPairContract === newPairContract) {
  const pairContracts = await context.storage.getJson('PairContracts');
  pairContracts[newPair.pair] = newPairContract;
  await context.storage.putJson('PairContracts', pairContracts);
}
```

After letting the Web3 Action run for a while, we can check the project’s Storage and view the created pairs:

<figure>
  <img alt="Tenderly Docs" />

  <figcaption />
</figure>

The keys are the addresses of the newly deployed `UniswapV2Pair` contracts, while the values are all the same and represent the bytecode of the `UniswapV2Pair` contract.


# How to Handle On-Chain Events
Source: https://docs.tenderly.co/monitoring/web3-actions/tutorials/on-chain-events

Use Web3 Actions as a serverless backend to respond to on-chain events. Follow a Tic-Tac-Toe example to monitor game changes.

This tutorial will teach you how to **create a serverless backend for your smart contract using Tenderly Web3 Actions**. Web3 Actions allow you to run custom code in response to on-chain or off-chain events that are initiated by your smart contract.

To illustrate how Web3 Actions work, we build a simple Tic-Tac-Toe game and deploy it to a test network. The smart contract maintains the game state while Web3 Actions monitor changes to the game.

**Whenever a specific event gets fired from the smart contract, Tenderly will execute your custom code in the form of a NodeJS project**. The results of the game and the game board will be printed to the console each time a player makes a move or when the game is over.

<Info>
  Check out this [Github repo](https://github.com/Tenderly/examples-web3-actions/) to find the
  source code for this project. Feel free to clone the repo and play around with it, or code along.
</Info>

## Understanding Web3 Actions

Smart contracts allow you to execute custom code when an event is triggered, a function is invoked, or perhaps periodically.

Tenderly helps you streamline this process with Web3 Actions. You can write your Web3 Actions in a single Javascript file or deploy them as a NodeJS project.

**Web3 Actions also allow you to perform any action you normally would with NodeJS**. This tutorial will show you how to use the Tenderly CLI to deploy your Web3 Actions and ensure they run when specific conditions are met.

<Note>
  Learn more about Web3 Actions and explore how you can use them in your projects with [**Basics of
  Web3 Actions**](/monitoring/web3-actions/tutorials/on-chain-events).
</Note>

### Project Overview

The purpose of this project is to show you how to deploy a smart contract and write several Javascript functions that Tenderly will invoke when an event occurs. You will learn how to use the Tenderly CLI to deploy your Web3 Actions to Tenderly’s infrastructure.

Here’s a step-by-step overview of how to do this:

1. Deploy the smart contract to a test network
2. Use the Tenderly CLI to set up Javascript and config files needed to run the Web3 Actions
3. Develop functions that respond to game events
4. Deploy those functions to Tenderly’s infrastructure using the CLI

<Warning>
  For this tutorial, you’ll need access to the **Tenderly Dashboard**. If you don’t have an account,
  [**sign up here for free**](https://dashboard.tenderly.co/register?utm_source=homepage) (no cc
  required as well).
</Warning>

## 0: Deploy the smart contract

<Note>
  If you’re coding along, you can skip this step and use the contract we [**deployed and verified in
  Tenderly**](https://dashboard.tenderly.co/contract/sepolia/0x1338d7232786b365b0a6bbd06552f885371f5f06).
</Note>

We use a pre-written smart contract. Check out the source code of the[ **smart contract on GitHub**](https://github.com/Tenderly/examples-web3-actions/blob/main/tic-tac-toe/TicTacToe.sol). This smart contract is designed to emit events whenever a change to the state of the game occurs.

Our simple Tic-Tac-Toe game can have four possible states:

* Game start
* Player joins the game
* Player makes a move
* Game over

### Prerequisite

**Create Two Accounts** - deploy the smart contract to any [network that is supported by Tenderly](/platform/supported-networks). The most convenient way to do this is with [Remix](https://remix.ethereum.org/) and the [Metamask](https://metamask.io/) wallet plugin. You need two accounts that have a positive Ether balance. These accounts will represent the two players. For the purpose of this tutorial we use Sepolia. If you plan to follow along with this tutorial, you can use the [Sepolia faucet](https://faucet.chainstack.com/sepolia-testnet-faucet/) to add Ether to the accounts.

**Compile the contract -** use the Remix IDE to compile the smart contract. Create a new contract file and add the code found [**here**](https://github.com/Tenderly/examples-web3-actions/blob/main/tic-tac-toe/TicTacToe.sol).

<Frame>
  <img alt="Compiling the contract in the Remix IDE" />
</Frame>

**Deploy to a test network** - in your Metamask browser plugin, make sure Sepolia is selected as your preferred network. Next, go to the **“Deploy And Run Transactions”** section in Remix and select **`Injected Web3`**. Click **“Deploy”** once you’ve made sure that the account references the account in Metamask.

<Frame>
  <img alt="Deploying the contract to a testnet" />
</Frame>

<Frame>
  <img alt="Copying the contract address" />
</Frame>

To get more information on the deployed contract, check out the **“Deployed Contracts”** section. Click the copy icon to copy the full contract address (`0x133...`) and store it somewhere because we’ll need it for the steps that follow.

Now go to the **Tenderly Dashboard to verify the contract**. This will make it possible for us to interact with the contract later on in the tutorial.

## 1: Set Up Web3 Actions via the Tenderly CLI

To continue with this tutorial, you need to have the **Tenderly CLI** installed on your machine. Follow [**this guide**](https://github.com/Tenderly/tenderly-cli#installation) to learn how to set it up and authenticate access.

With the CLI installed, create a new directory and `cd` into it. Initialize your Web3 Actions by running the `tenderly actions init` command:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
$> cd tdly-actions
$> tenderly actions init
```

You'll be prompted to select one of your existing Tenderly projects. Your Web3 Actions will be deployed to this project and should appear in your directory structure like so:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
$> ls actions
  example.ts     # where we write Web3 actions code
  tsconfig.json
  package.json
```

Typescript is the default language but you can switch to plain Javascript. Before you execute the init command, set Javascript as your preferred language like so: `tenderly actions init --language javascript`.

<Note>
  The `package.json` holds npm dependencies which will be available when you deploy your Web3
  Action. The `tsconfig.json` file holds Typescript
  configuration related only to `.ts` files within the
  `actions` directory.
</Note>

### 1.1. Add Tic-Tac-Toe Contract’s ABI

Before we dive deeper into the code, copy the ABI generated by the compiler to the actions directory. In our example, this is the `tdly-actions` directory.

In Remix, go to `files/artifacts/TicTacToe.json`, copy/paste the file contents and paste them into your project’s `TicTacToe.json` file.

<Warning>
  All files your Web3 Action code uses and references must be placed in the
  `actions` directory (e.g.
  `TicTacToe.json`).
</Warning>

### 1.2. Configure Typescript to Import a JSON File as a Module

By default, Typescript doesn’t allow you to import JSON files as modules. You need to configure Typescript to be able to import the `TicTacToe.json` file as a module and access it as an object.

Go to your `tsconfig.json` file and include the following two configurations under the `compilerOptions` entry:

```diff title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
    ...
    "compilerOptions": {
	...
+        "resolveJsonModule": true,
+        "esModuleInterop": true
    },
   ...
}
```

## 2: Write a Function to Handle New Game Event

Write a function that will execute when a new game is started. Let’s rename the Typescript file to something more descriptive:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
mv example.ts ticTacToeActions.ts
```

To harness the power of Typescript, we'll first need to define a type representing the game state. In essence, we'll store a replica of the game state in the storage of your Web3 Action. Each field contains the ID of the player who played there. We'll map the player's address to their turn (first, second, etc) in the `players` object.

### 2.1. Add an Action

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// ticTacToeActions.ts

export type Game = {
  players: { [address: string]: number };
  board: number[][];
};
```

At this point, we are ready to define the actual Web3 Action like so:

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export const createNewGame = (): Game => {
  return {
    players: {},
    board: [
      [0, 0, 0],
      [0, 0, 0],
      [0, 0, 0],
    ],
  };
};

// ticTacToeActions.ts continued
export const newGameAction: ActionFn = async (context: Context, event: Event) => {
  let txEvent = event as TransactionEvent;

  let iface = new ethers.utils.Interface(TicTacToe.abi);

  const result = iface.decodeEventLog('GameCreated', txEvent.logs[0].data, txEvent.logs[0].topics);

  const { gameId, playerNumber, player } = result;

  console.log('Game Created Event:', {
    gameId: gameId.toString(),
    playerNumber,
    player,
  });

  const game: Game = createNewGame();
  await context.storage.putJson(gameId.toString(), game);
};
```

This Web3 Action will handle the `GameCreated` event that is defined in the smart contract.

Looking at the smart contract, we can see that only one event is getting fired from the `newGame` function, so we’re interested in the first log entry. We can get the `result` with ethers.js by decoding `txEvent.logs[0].data` of the GameCreated event, based on the `TicTacToe.abi`.

Here we can access the ID associated with this particular game once it has been created: `result.gameId`. We want to track the data for this particular game: players and moves they made, using a brand new `Game` instance. We’re saving the object representing the new game in the Storage with this command: `context.storage.putJson(gameId, game)`.

With an empty board, we are setting the foundation to persist future changes which are handled by other actions.

You may also write automated tests to verify the behaviour of the Web3 Action. Some tests are available in the repository, but this is out of the scope of this tutorial.

### 2.2. Specify New Game Action Invocation

Open up tenderly.yaml. In the `specs` section, define the specs for `newGame` (arbitrary name) to invoke the function `newGameAction`. You can do so like this `newGameAction:newGameAction`, first we define the name of the file containing the function and then the function name.

Next, specify the `trigger` that Tenderly is supposed to watch out for to invoke the action. This is a `transaction` trigger that will run when the block is mined. We’re doing this for `network 3` when the event `NewGame` is emitted from the contract on the specified address.

Replace `TTT_CONTRACT_ADDRESS` with the actual address of your smart contract. If you want to deploy the contract to a network other than Sepolia, specify the network’s ID as the value of the network.

<Note>
  Replace `YOUR_USERNAME` and
  `YOUR_PROJECT_SLUG` with your Tenderly username and the
  slug of your project. You can copy those from the Dashboard URL:
  `https://dashboard.tenderly.co/{YOUR_USERNAME}/{YOUR_PROJECT_SLUG}/transactions`
</Note>

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
account_id: ''
actions:
  YOUR_USERNAME/YOUR_PROJECT_SLUG:
    runtime: v1
    sources: actions
    specs:
      newGame:
        description: Respond to newGame event
        function: ticTacToeActions:newGameAction
        trigger:
          type: transaction
          transaction:
            status:
              - mined
            filters:
              - network: 3
                eventEmitted:
                  contract:
                    address: TTT_CONTRACT_ADDRESS
                  name: GameCreated
project_slug: ''
```

### 2.3. Verify Your Tic-Tac-Toe Smart Contract on Tenderly

Before deploying the contract, you need to verify it in your Tenderly Dashboard.

If you wish, you can [upload the contract through your browser](/contract-verification/overview). Once uploaded, select the TicTacToe contract, the network you deployed it to, and the contract address.

Click Add Contract and fill out the compiler options as shown in the picture below:

<Frame>
  <img alt="Verifying and adding the contract to Tenderly " />
</Frame>

<Frame>
  <img alt="Adding the contract compiler information " />
</Frame>

### 2.4. Deploy the Web3 Action to Tenderly

To deploy your Web3 Action, execute the `deploy` command using the Tenderly CLI:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
tenderly actions deploy
```

The output should look like this:

<Frame>
  <img alt="The Web3 Action execution output" />
</Frame>

To see details about the deployment of your Web3 Action, check the Tenderly Dashboard. If the deployment was successful, you should see something like this:

<Frame>
  <img alt="Opening the Web3 Action deployment information " />
</Frame>

### 2.5. Try Joining a New Game 🎉

To verify that everything is working properly, head back to Remix and create a new game or even several games.

Open up the TicTacToe contract and hit `newGame`. Metamask should prompt you to confirm the execution of the Web3 Action.

Once the transaction is submitted to the chain, Remix should produce an output similar to this:

<Frame>
  <img alt="Creating a new game in Remix" />
</Frame>

Next, head back to your Tenderly Dashboard and open the Transactions section to see your transaction. In the Actions section, you’ll notice that the **“Latest Execution”** column has changed.

To view the execution history, open your Web3 Action and click the Execution History tab:

<Frame>
  <img alt="Opening the Execution history tab for your Web3 Action " />
</Frame>

The execution history will provide you with the following data:

<Frame>
  <img alt="The execution history data" />
</Frame>

In the upper pane, you'll find information about the payload coming from the chain. The lower pane contains details about the logged game number. In our case, this is `0xb`, which means it’s the 11th game started for this contract.

### 2.6. Check the Storage of Your Web 3 Actions

Click the **“Go To Storage”** button to see the contents of the Storage. Each game that is initiated will get its own storage slot in this key-value map.

When you open the game we just created with the **ID 11**, you’ll see zeros across all the fields, meaning no players have played the game yet.

<Frame>
  <img alt="Opening the Storage of your Web3 Action " />
</Frame>

## 3: Add a Web3 Action to Handle New Players Joining a Game

The player joining the game should be processed by registering the address of the player and their move (1 or 2).

Besides the boilerplate code that helps us retrieve the event data, the `playerJoinAction.ts` file also contains the code that allows us to:

* Read the current game state from the storage using the game’s ID (`storage.getJson`).
* Retrieve the player’s address and store their turn: `game.players[player] = playerNumber`
* Save the updated game object to the storage of Web3 Action using `storage.putJson`.

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// playerJoinAction.ts

export const playerJoinedAction: ActionFn = async (context: Context, event: Event) => {
  let txEvent = event as TransactionEvent;
  let iface = new ethers.utils.Interface(TicTacToe.abi);
  const result = iface.decodeEventLog(
    'PlayerJoinedGame',
    txEvent.logs[0].data,
    txEvent.logs[0].topics,
  );

  const gameId = result.gameId.toString();
  const playerAddress = result.player.toLowerCase() as string;
  const playerNumber = result.playerNumber;

  console.log('Player joined event:', {
    gameId,
    playerAddress,
    playerNumber,
  });

  const game: Game = (await context.storage.getJson(gameId)) as Game;
  game.players[playerAddress] = playerNumber;

  await context.storage.putJson(result.gameId.toString(), game);
};
```

### 3.1. Specify PlayerJoinedGame Action Invocation

We also need to extend the `specs` from the `tenderly.yaml` file to include the specifications needed to invoke the Web3 Action.

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
playerJoined:
  description: Respond to player joining game
  function: ticTacToeActions:playerJoinedAction
  trigger:
    type: transaction
    transaction:
      status:
        - mined
      filters:
        - network: 3
          eventEmitted:
            contract:
              address: TTT_CONTRACT_ADDRESS
            name: PlayerJoinedGame
```

### 3.2. Deploy the action to Tenderly

Deploy your Web3 Action by running the `deploy` command. This command will also redeploy previously deployed Web3 Actions.

```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
tenderly action deploy
```

### 3.3. Try Joining a New Game

Join a new game by going over to Remix and adding the game number from the logs in the `newGame` input field. To submit the transaction, click the `joinGame` button:

<Frame>
  <img alt="Joining a new game in Remix " />
</Frame>

Once the transaction has been mined, the logs of the execution will display `playerNumber: 1`.

<Frame>
  <img alt="The execution log" />
</Frame>

To play the game, switch to your other account in Metamask and click `joinGame` again. Upon the completion of the transaction, you’ll see a similar log output in the Execution History.

### 3.4. Check the Storage of Your Web 3 Actions

<Frame>
  <img alt="Opening the execution of your Web3 Action" />
</Frame>

Open any of these executions and click the **“Go To Storage”** button.

The game our players have joined has the ID of 11, and this is the state before any move has been made. The Tic-Tac-Toe board contains only zeros and the map from an Ethereum address to the player’s turn is present.

<Frame>
  <img alt="Opening the Storage key value " />
</Frame>

### 3.5. Add an Action to Handle When Player Makes a Move

Using Ethers, we get the game ID and load the game instance from storage. Next, update the field in row `result.boardRow` and column `result.boardCol` with the player’s input `game.players[player]`**.**

The function `processNewGameState`, will log the board to the console, but you can also send a tweet when a move is made, trigger a new transaction on the chain, or use it in any other way.

```typescript title="example.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// ticTacToeActions.ts
//...
export const playerMadeMoveAction: ActionFn = async (context: Context, event: Event) => {
  let txEvent = event as TransactionEvent;
  let iface = new ethers.utils.Interface(TicTacToe.abi);
  const result = iface.decodeEventLog(
    'PlayerMadeMove',
    txEvent.logs[0].data,
    txEvent.logs[0].topics,
  );

  const gameId = result.gameId.toString();
  const game = (await context.storage.getJson(gameId)) as Game;
  const player = result.player.toLowerCase() as string;
  const { boardRow, boardCol } = result;

  console.log("Player's move event log:", {
    gameId,
    player,
    boardRow: boardRow.toString(),
    boardCol: boardCol.toString(),
  });

  console.log(
    `Move: gameId ${gameId}, game ${JSON.stringify(
      game,
    )}, boradRow ${boardRow}, boardCol ${boardCol}, player ${player}`,
  );

  game.board[boardRow][boardCol] = game.players[player];
  console.log('MV', JSON.stringify(game));
  await context.storage.putJson(gameId, game);

  processNewGameState(game);
};

const processNewGameState = (game: Game) => {
  let board = '\n';
  game.board.forEach(row => {
    row.forEach(field => {
      if (field == 1) {
        board += '❎ ';
        return;
      }

      if (field == 2) {
        board += '🅾️ ';
        return;
      }

      board += '💜 ';
    });

    board += '\n';
  });

  console.log(board);
};
```

The corresponding spec for this action is:

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
playerMadeMove:
  description: Respond to player making a move event
  function: ticTacToeActions:playerMadeMoveAction
  trigger:
    type: transaction
    transaction:
      status:
        - mined
      filters:
        - network: 3
          eventEmitted:
            contract:
              address: TTT_CONTRACT_ADDRESS
            name: PlayerMadeMove
```

### 3.6. Make a Move to Play the Game

To make a move, use Metamask to switch to the first player who joined the game. Next, enter the game number you received, as well as the row and column on the board (0, 1).

<Frame>
  <img alt="Making a move in Remix " />
</Frame>

When the action gets executed, the output should look like this:

<Frame>
  <img alt="The Web3 Action execution output" />
</Frame>

## Step 4. Add a Web3 Action to Handle When the Game is Over

Below you’ll find the code for the `GameOver` event. The `GameOver` event is fired when a player makes a move that wins the game or when the board is full. This event is fired after the `PlayerMadeMove` event. In the `txEvent.logs` list, the `GameOver` event is the second element.

An easy way to get `GameOver` event is to access it via the `txEvent.logs[1]`. However, we’ll implement a more robust solution which doesn’t depend on the order and number of events fired.

First, you need to get the `gameOverTopic` using ethers via `iface.getEventTopics`. This will give you the corresponding hexadecimal value. Next, you need to find the log entry in the `txEvent.logs`, whose topics list contains the `gameOverTopic`. This is our `GameOver` event log that we can decode using Ethers.

```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export const gameOverAction: ActionFn = async (context: Context, event: Event) => {
	let txEvent = event as TransactionEvent;
	let iface = new ethers.utils.Interface(TicTacToe.abi);

	const gameOverTopic = iface.getEventTopic("GameOver");
	const gameOverLog = txEvent.logs.find(log => log.topics.find(topic => topic == gameOverTopic) !== undefined);

	if (gameOverLog == undefined) {
		// impossible
		throw Error("GameOver log not found in event's logs");
	}

	const result = iface.decodeEventLog("GameOver", gameOverLog.data, gameOverLog.topics);

	console.log(result);

	const gameId = result.gameId.toString();
	const winner = result.winner as number;

	const winnerMessage = getWinnerMessage(winner);
	if (winnerMessage !== false) {
		console.info(`🎉 Winner of the game ${gameId} is ${winnerMessage}`);
	} else {
		console.error("🤔 weird winner code");
	}
}
```

### 4.1. Specify GameOver Action Invocation

Finally, we need to add the specification to invoke the `GameOver` action by extending the `specs` in `tenderly.yaml`:

```yaml title="example.yaml" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
gameOver:
  description: Respond to game over
  function: ticTacToeActions:gameOverAction
  trigger:
    type: transaction
    transaction:
      status:
        - mined
      filters:
        - network: 3
          eventEmitted:
            contract:
              address: TTT_CONTRACT_ADDRESS
            name: GameOver
```

### 4.2. Play the Game

Keep playing until one player wins the game or the board is entirely filled out. At the end of the game, the Execution History should look like this:

<Frame>
  <img alt="The execution history at the end of the game" />
</Frame>


# Lido Validator Exit Notifications
Source: https://docs.tenderly.co/monitoring/web3-actions/tutorials/validators-exits

Learn how to use Tenderly Web3 Actions to monitor Lido validator exit requests and send notifications via Telegram using open-source monitoring template.

In this tutorial, we'll show you how to set up a **Tenderly Web3 Action to monitor Lido validator exit requests** and send notifications via Telegram. This project demonstrates how to use Web3 Actions to interact with smart contracts and external APIs to create a custom notification system.

Use this Github project template to set up your own monitoring of Lido validator exit requests:

<Card title="Validator monitoring Web3 Action template" href="" />

## Project Overview

The purpose of this project is to set up a system that monitors Lido validator exit requests and sends notifications when specific conditions are met.

Here's a quick breakdown of the project's flow:

1. **Subscribe to relevant on-chain events**: The Web3 Action listens for `ValidatorExitRequest` events from the Lido contract on the Ethereum mainnet.
2. **Decode event using Tenderly API**: When an event is detected, it retrieves the transaction details using the Tenderly API.
3. **Filter for specific events of interest**: The `ValidatorExitRequest` event is evaluated further by checking if the `stakingModuleId` is 1 and the `nodeOperatorId` is 14.
4. **Respond**: If `ValidatorExitRequest` of interest has happened, the Web3 Action sends a notification to the specified Telegram channel with details about the validator exit request.

## Prerequisites

Before you begin, make sure you have the following:

* [Tenderly CLI](https://github.com/Tenderly/tenderly-cli) installed
* [Node.js](https://nodejs.org/) (v20 currently supported)
* [npm](https://www.npmjs.com/)
* A Telegram bot token and channel ID
* A Tenderly account and project

### Setup

Let's go through the steps to set up your Lido Validator Exit Notification system:

<Steps>
  ### Clone the Repository

  First, clone the project repository and navigate to the project directory:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  git clone https://github.com/Tenderly/tenderly-lido-validator-monitoring-solution
  cd tenderly-lido-validator-monitoring-solution
  ```

  ### Install Dependencies

  Install the required npm packages:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  npm install
  ```

  ### Configure Tenderly Project

  Set up your Tenderly project by following these steps:

  1. Log in to your Tenderly account
  2. Create a new project or use an existing one
  3. Note down your [**Account Name and Project Slug**](/platform/account/projects/slug)

  ### Configure tenderly.yaml

  Update the `tenderly.yaml` file with your Tenderly project information:

  ```yaml showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  account_id: "<YOUR_ACCOUNT_ID>"
  actions:
    <YOUR_ACCOUNT_ID>/<YOUR_PROJECT_SLUG>:
      runtime: v2
      sources: actions
      specs:
        action_name:
          description: Get a notification when condition matches on Lido tx
          function: lidoEvents:subscribeToLidoValidatorExitRequestFn
          execution_type: parallel
          trigger:
            type: transaction
            transaction:
              status:
                - mined
              filters:
                - network: 1
                  eventEmitted:
                    contract:
                      address: 0x0de4ea0184c2ad0baca7183356aea5b8d5bf5c6e
                    name: ValidatorExitRequest
  project_slug: "<YOUR_PROJECT_SLUG>"
  ```

  Make sure to replace `<YOUR_ACCOUNT_ID>` and `<YOUR_PROJECT_SLUG>` with your actual Tenderly **Account Name** and **Project Slug**.

  ### Add contract address to the project

  In order to be able to deploy action and monitor desired contract, you need to add that contract to the project.

  In this case we want to add **`0x0de4ea0184c2ad0baca7183356aea5b8d5bf5c6e`**.

  ### Set Up Secrets

  Add the following secrets to your Web3 Actions:

  * `BEARER`: Your Tenderly API bearer token
  * `BOT-TOKEN`: Your Telegram bot token
  * `CHANNEL-ID`: Your Telegram channel ID

  To add secrets, go to Web3 Actions inside your project and navigate to the [Secrets](/monitoring/web3-actions/references/context#secrets) section.

  ### Deployment

  To deploy your Web3 Action, use the Tenderly CLI:

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  tenderly actions deploy
  ```

  This command will deploy the action defined in your `tenderly.yaml` file.
</Steps>

## How it Works

Let's break down the main components of the `lidoEvents.ts` file:

```typescript showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

const subscribeToLidoValidatorExitRequestFn = async (
  context: Context,
  transactionEvent: TransactionEvent,
) => {
  // Event handling logic here
};

// Helper functions for API calls and notifications
```

The `subscribeToLidoValidatorExitRequestFn` function is the main entry point for our Web3 Action. It handles the following tasks:

1. Retrieves transaction details using the Tenderly API
2. Checks if the `stakingModuleId` is 1 and the `nodeOperatorId` is 14
3. If the condition is met, sends a notification to the specified Telegram channel

### Tenderly API for Transaction Trace

A key part of this Web3 Action is retrieving the transaction trace using the Tenderly API. Here's the API endpoint used:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const url = `https://api.tenderly.co/api/v1/public-contract/${network}/trace/${txHash}`;
```

This API endpoint returns the detailed trace of the transaction, which includes all the logs and events emitted during the transaction execution. Here's what each part of the URL represents:

* `https://api.tenderly.co/api/v1/public-contract/`: The base URL for Tenderly's public contract API
* `${network}`: The network identifier (e.g., `1` for Ethereum Mainnet)
* `${txHash}`: The hash of the transaction we're interested in

The response from this API contains a wealth of information about the transaction, including:

* All emitted events and their parameters
* Internal calls made during the transaction
* State changes that occurred

In our Web3 Action, we use this trace to find the `ValidatorExitRequest` event and extract relevant information:

```typescript showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const validatorExitRequestLog = result.logs.find(
  (log: any) => log.name === "ValidatorExitRequest"
);

if (validatorExitRequestLog) {
  const stakingModuleId = validatorExitRequestLog.inputs.find(
    (input: any) => input.soltype.name === "stakingModuleId"
  )?.value;
  const nodeOperatorId = validatorExitRequestLog.inputs.find(
    (input: any) => input.soltype.name === "nodeOperatorId"
  )?.value;
  // ... other parameters
}
```

This allows us to precisely identify the validator exit requests we're interested in and extract the necessary information to send our notification.

<Note>
  Using the Tenderly API for transaction traces provides a powerful way to access detailed information about on-chain events without having to directly interact with the blockchain or set up your own node.
</Note>

## Customization

For Lido validator exits, events of interest are recognized by parameters `stakingModuleId` with value 1, and `nodeOperatorId` with value of 14.

To modify these filtering conditions or add more events to monitor:

1. Edit the `lidoEvents.ts` file
2. Update the condition check in the `if` statement to match your requirements
3. Modify the message format or add additional information as needed

For example, to change the `stakingModuleId` and `nodeOperatorId` conditions:

```typescript showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
if (stakingModuleId == 1 && nodeOperatorId == 14) {
  // Your custom logic here
}
```

## Monitoring and Troubleshooting

To ensure your Web3 Action is working correctly:

* Monitor your Web3 Action executions in the Tenderly dashboard
* Check the Tenderly logs for any error messages or execution details
* Ensure your Telegram bot has permission to send messages to the specified channel

<Warning>
  This setup is specifically designed to monitor Lido validator exit requests on the Ethereum mainnet.
</Warning>

## Conclusion

You've now set up a custom notification system using Tenderly Web3 Actions to monitor Lido validator exit requests.


# Usage Rate Limits
Source: https://docs.tenderly.co/monitoring/web3-actions/usage-rate-limits

Reference table of Web3 Action execution limits: timeout, memory, rate limits, payload and package size, with notes on which limits are customizable.

The following table presents limits of setup and execution of [Web3 Actions](/monitoring/web3-actions/introduction):

| What                                  | Limit                                                               | Customizable?\* |
| ------------------------------------- | ------------------------------------------------------------------- | --------------- |
| Execution duration\*\*                | 30s timeout                                                         | Yes             |
| Total number of Web3 Actions          | [Contact sales](https://tenderly.co/contact-us) to discuss capacity | Yes             |
| Memory allocation (RAM)               | 128 MB                                                              | Yes             |
| Sequential actions rate limit\*\*\*   | 400 executions/5 min                                                | Yes             |
| Parallel actions rate limit\*\*\*     | 2000 executions/5 min                                               | Yes             |
| Package size                          | 40MB zipped (including `node_modules`)                              | No              |
| Webhook trigger payload size          | 5 MB                                                                | No              |
| Action source size (dashboard editor) | 5 MB                                                                | No              |

\*Customizable restriction per quote.
\*\*Executions longer than defined timeout will be terminated.
\*\*\*Rate limits apply per action: each action has its own execution budget. Any additional executions are skipped and appear as `RATE_LIMITED` in the [execution history](/monitoring/web3-actions/references/execution#web3-action-execution-status-types). Email notifications about skipped executions are batched: you receive at most one email per action per 24 hours. See [Notifications](/monitoring/web3-actions/references/notifications) for how to configure these email delivery channels.

<Note>
  When your account's usage quota is exhausted, further executions end with the [`TU_QUOTA_REACHED`](/monitoring/web3-actions/references/execution#web3-action-execution-status-types) status. They are dropped without retry and no email is sent.
</Note>

[Contact our support team](https://tenderly.co/contact-us) for custom limits.


# ConnectKit - Node RPC Integration
Source: https://docs.tenderly.co/node-rpc/dapp-ui/connectkit

Learn how to configure your ConnectKit components to use Node RPC as an RPC provider.

[ConnectKit](https://family.co/docs/connectkit) is a React.js component library for connecting a wallet to your dapp, and you can use [Node RPC](/node-rpc/overview) for blockchain connection. ConnectKit is built on top of [wagmi](/node-rpc/dapp-ui/wagmi).

<Steps>
  ### Configure Web3Provider

  ```tsx title="Web3Provider.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

  const config = createConfig(
    getDefaultConfig({
      // Your dApps chains
      chains: [mainnet],
      transports: {
        // RPC URL for each chain
        [mainnet.id]: http(`https://mainnet.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_MAINNET}`),
        [base.id]: http(`https://base.gateway.tenderly.co/${process.env.NEXT_TENDERLY_NODE_ACCESS_KEY_BASE}`),
        [optimism.id]: http(`https://optimism.gateway.tenderly.co/${process.env.NEXT_TENDERLY_NODE_ACCESS_KEY_OPTIMISM}`)
      },

      // Required API Keys
      walletConnectProjectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID,

      // Required App Info
      appName: "Your App Name",

      // Optional App Info
      appDescription: "Your App Description",
      appUrl: "https://dapp.tenderly.co", // your app's url
      appIcon: "https://tenderly.co/favicons/favicon.ico", // your app's icon, no bigger than 1024x1024px (max. 1MB)
    }),
  );


  export const Web3Provider = ({ children }) => {
    return (
      <WagmiProvider config={config}>
        <ConnectKitProvider>{children}</ConnectKitProvider>
      </WagmiProvider>
    );
  };
  ```

  ### Wrap your App with Web3Provider

  Next, wrap your `App` with `Web3Provider`:

  ```tsx title="App.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

  const App = () => {
    return (
      <Web3Provider>
          <ConnectKitButton />
      </Web3Provider>
    );
  };
  ```
</Steps>


# Dynamic - Node RPC Integration
Source: https://docs.tenderly.co/node-rpc/dapp-ui/dynamic

Set Tenderly Node RPC endpoints as the evmNetworks RPC URLs in Dynamic's DynamicContextProvider for your React dapp.

[Dynamic](https://docs.dynamic.xyz) is a platform that provides seamless authentication solutions for Web3 applications, offering smart login flows, easy onboarding processes, and developer tools for enhanced user experience and functionality. Use [Node RPC](/node-rpc/overview) as the RPC provider for the EVM networks you configure, and see the [JSON-RPC reference](/node-rpc/rpc-reference) for supported methods.

<Steps>
  ### Define EVM Networks

  Create a list of networks configuration with Node RPC RPC.

  ```ts title="tenderlyEvemNetworks.ts" showLineNumbers {17, 32, 48} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  export function tenderlyEvmNetworks(){
    // Setting up list of evmNetworks
    return [
      {
        blockExplorerUrls: ['https://etherscan.io/'],
        chainId: 1,
        chainName: 'Ethereum Mainnet',
        iconUrls: ['https://app.dynamic.xyz/images/networks/eth.svg'],
        name: 'Ethereum',
        nativeCurrency: {
          decimals: 18,
          name: 'Ether',
          symbol: 'ETH',
        },
        networkId: 1,

        rpcUrls: [`https://mainnet.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_MAINNET}`],
        vanityName: 'ETH Mainnet',
      },
    {
        blockExplorerUrls: ['https://basescan.org/'],
        chainId: 8453,
        chainName: 'Base',
        iconUrls: ['https://app.dynamic.xyz/images/networks/base.svg'],
        name: 'Base',
        nativeCurrency: {
          decimals: 18,
          name: 'Ether',
          symbol: 'ETH',
        },
        networkId: 8453,
        rpcUrls: [`https://base.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_BASE}`],

        vanityName: 'Base',
      },
      {
        blockExplorerUrls: ['https://polygonscan.com/'],
        chainId: 137,
        chainName: 'Matic Mainnet',
        iconUrls: ["https://app.dynamic.xyz/images/networks/polygon.svg"],
        name: 'Polygon',
        nativeCurrency: {
          decimals: 18,
          name: 'MATIC',
          symbol: 'MATIC',
        },
        networkId: 137,
        rpcUrls: [`https://mainnet.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_POLYGON}`],
        vanityName: 'Polygon',
      },
    ];
  }
  ```

  ### Configure Dynamic Context Provider

  Configure a `DynamicContextProvider` with `evmNetworks` from step 1.

  ```tsx title="Web3Provider.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core'
  import { EthereumWalletConnectors } from '@dynamic-labs/ethereum'
  import { tenderlyEvmNetworks } from './tenderlyEvmNetworks'

  export const App = () => {
    return (
      <DynamicContextProvider
        settings={{
          // Find your environment id at https://app.dynamic.xyz/dashboard/developer
          environmentId: "REPLACE-WITH-YOUR-ENVIRONMENT-ID",
          walletConnectors: [EthereumWalletConnectors],
          evmNetworks: tenderlyEvmNetworks()
        }}
      >
        <Home />
      </DynamicContextProvider>
    );
  };
  ```
</Steps>


# RainbowKit - Node RPC Integration
Source: https://docs.tenderly.co/node-rpc/dapp-ui/rainbowkit

Configure Tenderly Node RPC as the wagmi transport behind RainbowKit, with createConfig, chains, connectors, and per-chain HTTPS endpoints.

[RainbowKit](https://rainbowkit.com/docs/introduction) is a React library that simplifies wallet connection for decentralized applications, offering wallet management, chain connections, ENS resolution, balance display, and customizable UI features to enhance the user experience. It builds on [wagmi](/node-rpc/dapp-ui/wagmi), so you point its transports at [Node RPC](/node-rpc/overview).

### Set up Wagmi config

```ts title="wagmi-config.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createConfig, http } from 'wagmi'
import { mainnet, base, baseSepolia, optimism } from 'wagmi/chains'
import { injected, walletConnect, metaMask, safe } from 'wagmi/connectors'

const projectId = '<WALLETCONNECT_PROJECT_ID>'

export const config = createConfig({
  chains: [mainnet, base, baseSepolia, optimism],
  connectors: [
    injected(),
    walletConnect({ projectId }),
    metaMask(),
    safe(),
  ],
  transports: {
    [mainnet.id]: http(`https://mainnet.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_MAINNET}`),
    [base.id]: http(`https://base.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_BASE}`),
    [baseSepolia.id]: http(`https://base-sepolia.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_BASE_SEPOLIA}`),
    [optimism.id]: http(`https://optimism.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_OPTIMISM}`),
  },
})
```

### Wrap your app

```tsx title="App.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

const queryClient = new QueryClient();

const App = () => {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider>
          <Home />
        </RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
};

export default App;
```


# Reown AppKit - Node RPC Integration
Source: https://docs.tenderly.co/node-rpc/dapp-ui/reown

Configure Tenderly Node RPC as the transport in Reown AppKit's WagmiAdapter, then wire up the AppKit modal and context provider.

[Reown AppKit](https://reown.com/reown-sdk) streamlines Web3 wallet integration by offering seamless authentication through email and social logins, built-in fiat on-ramps, smart contract accounts, and user notifications, delivering a complete toolkit for creating engaging blockchain applications.

You can use [Node RPC](/node-rpc/overview) as chain provider, by using [wagmi](/node-rpc/dapp-ui/wagmi)'s `createConfig` and setting Node RPCs in `transports` array.

<Steps>
  ### RPC Configuration

  * Add the following configuration to `config/index.ts` to use Tenderly RPC.
  * Set the following environment variables:
    * NEXT\_PUBLIC\_TENDERLY\_NODE\_ACCESS\_KEY\_MAINNET
    * NEXT\_PUBLIC\_PROJECT\_ID

  ```tsx title="config/index.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'
  import { mainnet, arbitrum } from '@reown/appkit/networks'
  import { createStorage, cookieStorage, http } from 'wagmi'

  // Get projectId from https://cloud.reown.com
  export const projectId = process.env.NEXT_PUBLIC_PROJECT_ID

  if (!projectId) {
    throw new Error('Project ID is not defined')
  }

  export const networks = [mainnet, arbitrum]

  // Set up the Wagmi Adapter (Config)
  export const wagmiAdapter = new WagmiAdapter({
    storage: createStorage({
      storage: cookieStorage
    }),
    ssr: true,
    transports: {
      [mainnet.id]: http(`https://mainnet.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_MAINNET}`)
    },
    networks,
    projectId
  })

  export const config = wagmiAdapter.wagmiConfig
  ```

  ### Create the ContextProvider

  Create Reown AppKit `ContextProvider` you can use in the rest of your UI to connect to selected networks.

  ```tsx title="context/index.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  'use client'

  import { createAppKit } from '@reown/appkit/react'
  import { mainnet, arbitrum } from '@reown/appkit/networks'
  import { WagmiProvider, cookieToInitialState, type Config } from 'wagmi'
  import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
  import { type ReactNode } from 'react'
  import { wagmiAdapter, projectId } from './config'

  // Set up queryClient
  const queryClient = new QueryClient()

  if (!projectId) {
    throw new Error('Project ID is not defined')
  }

  // Set up metadata
  const metadata = { //this is optional
    name: "appkit-example",
    description: "AppKit Example - EVM",
    url: "https://exampleapp.com", // origin must match your domain & subdomain
    icons: ["https://avatars.githubusercontent.com/u/37784886"]
  }

  // Create the modal
  const modal = createAppKit({
    adapters: [wagmiAdapter],
    projectId,
    networks: [mainnet, arbitrum],
    metadata: metadata,
    features: {
      analytics: true, // Optional - defaults to your Cloud configuration
    }
  })

  function ContextProvider({ children, cookies }: { children: ReactNode; cookies: string | null }) {
    const initialState = cookieToInitialState(wagmiAdapter.wagmiConfig as Config, cookies)

    return (
      <WagmiProvider config={wagmiAdapter.wagmiConfig as Config} initialState={initialState}>
        <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
      </WagmiProvider>
    )
  }

  export default ContextProvider
  ```
</Steps>


# Wagmi - Node RPC Integration
Source: https://docs.tenderly.co/node-rpc/dapp-ui/wagmi

Configure Tenderly Node RPC as the wagmi transport, wiring createConfig, chains, connectors, and per-chain HTTPS endpoints in your React dapp.

[Wagmi](https://wagmi.sh/) is a React Hooks library that streamlines Ethereum integration in React applications, offering easy installation, chain configuration, and various hooks for wallet, contract, and transaction interactions.

Libraries such as [Reown AppKit](/node-rpc/dapp-ui/reown), [ConnectKit](/node-rpc/dapp-ui/connectkit), [Dynamic](/node-rpc/dapp-ui/dynamic) and [RainbowKit](/node-rpc/dapp-ui/rainbowkit) are built on top of Wagmi.

## Configure Wagmi

Create networks configuration with `transports` containing Node RPC RPC.

```ts title="wagmi-config.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createConfig, http } from 'wagmi'
import { mainnet, base, baseSepolia, optimism } from 'wagmi/chains'
import { injected, walletConnect, metaMask, safe } from 'wagmi/connectors'

const projectId = '<WALLETCONNECT_PROJECT_ID>'

export const config = createConfig({
  chains: [mainnet, base, baseSepolia, optimism],
  connectors: [
    injected(),
    walletConnect({ projectId }),
    metaMask(),
    safe(),
  ],
  transports: {
    [mainnet.id]: http(`https://mainnet.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_MAINNET}`),
    [base.id]: http(`https://base.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_BASE}`),
    [baseSepolia.id]: http(`https://base-sepolia.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_BASE_SEPOLIA}`),
    [optimism.id]: http(`https://optimism.gateway.tenderly.co/${process.env.NEXT_PUBLIC_TENDERLY_NODE_ACCESS_KEY_OPTIMISM}`),
  },
})
```

### Wrap your app in WagmiProvider

```tsx title="App.tsx" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

const queryClient = new QueryClient();

export function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <Home />
      </QueryClientProvider>
    </WagmiProvider>
  )
}
```


# Foundry - Node RPC Integration
Source: https://docs.tenderly.co/node-rpc/frameworks/foundry

Learn how to deploy contracts and run scripts from Foundry using Node RPC.

[Foundry](https://github.com/foundry-rs/foundry) is a toolkit for smart contract development on the Ethereum blockchain. It includes tools for compiling, testing, and deploying smart contracts, emphasizing speed and efficiency.

## Using `forge create`

To deploy contracts using Node RPC, run `forge create` with the option `--rpc-url` set to the RPC link you copied from the Dashboard.

```bash title="deploy-counter.sh" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge create Counter \
--rpc-url $RPC_URL \
--private-key $PRIVATE_KEY  \
```

To include a verification step, [follow this guide on verifying contracts with Foundry](/contract-verification/foundry#deploy-and-verify-in-one-step).

## Using `forge script`

To run a script using Node RPC, run `forge script` with the option `--rpc-url` set to the RPC link you copied from the Dashboard.

```bash title="counter-script.sh" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
forge script script/Counter.s.sol:CounterScript \
--rpc-url $RPC_URL \
```

To include a verification step, [follow this guide on verifying contracts with Foundry](/contract-verification/foundry#deploy-and-verify-in-one-step).


# Hardhat - Node RPC
Source: https://docs.tenderly.co/node-rpc/frameworks/hardhat

Learn how to deploy contracts through Node RPC from your Hardhat projects.

[Hardhat](https://hardhat.org/) is a development framework that facilitates the development, testing, and deployment of smart contracts. You can use Node RPC from Hardhat to compile, build, and deploy smart contracts, and run scripts using Ethers.js and Viem.

To include verification, [follow this guide](/contract-verification/hardhat).

For network-specific Hardhat config snippets, open your Node RPC in the [Tenderly Dashboard](https://dashboard.tenderly.co) open the Integrate view and switch to the **Hardhat** tab. Copy the snippet directly into your `hardhat.config.ts`.


# Simulate Blocks with eth_simulateV1
Source: https://docs.tenderly.co/node-rpc/guides/eth-simulatev1

Simulate a sequence of blocks with batched calls, state overrides, and block overrides using the standard eth_simulateV1 JSON-RPC method.

`eth_simulateV1` is the standard multi-block simulation method from the [Ethereum execution APIs](https://github.com/ethereum/execution-apis) specification. It simulates a sequence of blocks, each containing a batch of calls, on top of a base block, without sending anything on chain. Calls within a block execute sequentially and share state, and each simulated block builds on the previous one.

The method runs on [Node RPC](/node-rpc/overview) and [Virtual Environments](/virtual-environments/overview); see the full [JSON-RPC reference](/node-rpc/rpc-reference) for every method and network. A small set of networks does not support it; see [Network availability](#network-availability).

Use `eth_simulateV1` when you need a portable, spec-standard simulation that returns block-shaped results. For decoded logs, call traces, and asset and balance changes, use [`tenderly_simulateTransaction`](/node-rpc/guides/simulate-json-rpc) for a single transaction or [`tenderly_simulateBundle`](/node-rpc/guides/simulate-bundle-json-rpc) for a sequence of transactions.

### `eth_simulateV1`

Simulates a sequence of blocks on top of the given base block. Each block contains a batch of calls: call N sees the state changes of call N-1, and every block after the first builds on the block before it.

**Params**

1. **Simulation payload** `OBJECT`
   * **blockStateCalls** `ARRAY` of Block state call `OBJECT`: the sequence of blocks to simulate, in order
     * **blockOverrides** (*optional*) `OBJECT`: the set of header fields to override in this block
       * **number** (*optional*) `STRING`: hex, overrides the block number
       * **difficulty** (*optional*) `STRING`: hex, overrides the block difficulty
       * **time** (*optional*) `STRING`: hex, overrides the block timestamp
       * **gasLimit** (*optional*) `STRING`: hex, overrides the gas limit
       * **coinbase** (*optional*) `STRING`: hex, overrides the block miner
       * **random** (*optional*) `STRING`: hex, overrides the value that feeds into the PREVRANDAO opcode
       * **baseFee** (*optional*) `STRING`: hex, overrides the block base fee
       * **excessBlobGas** (*optional*) `STRING`: hex, overrides the excess blob gas
       * **blobGasUsed** (*optional*) `STRING`: hex, overrides the blob gas used
     * **stateOverrides** (*optional*) `MAP`: mapping from an account (address) to override specification. Set state overrides on the **first** block entry; see [Tenderly-specific behavior](#tenderly-specific-behavior)
       * **key** `STRING`: the account this override applies to
       * **value** `OBJECT`: the override specification
         * **balance** (*optional*) `STRING`: hex encoded balance override for the account in wei
         * **nonce** (*optional*) `STRING`: hex encoded nonce override for the account
         * **code** (*optional*) `STRING`: data of the code override for the account
         * **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
     * **calls** `ARRAY` of Transaction call `OBJECT`: executed in order; each call observes the state changes of the calls before it
       * **from** (*optional*) `STRING`: hex encoded address; defaults to the zero address
       * **to** (*optional*) `STRING`: hex encoded address
       * **gas** (*optional*) `STRING`: hex encoded gas limit for the call
       * **gasPrice** (*optional*) `STRING`: hex, the gas price willing to be paid by the sender in wei
       * **maxFeePerGas** (*optional*) `STRING`: hex, 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*) `STRING`: hex, the maximum fee per gas the sender is willing to pay to miners in wei
       * **value** (*optional*) `STRING`: hex encoded value in wei; defaults to `0x0`
       * **input** (*optional*) `STRING`: hex encoded call data; `data` is accepted as a deprecated alias, and `input` takes precedence when both are set
       * **nonce** (*optional*) `STRING`: hex encoded nonce
       * **type** (*optional*) `STRING`: hex encoded transaction type
       * **accessList** (*optional*) `ARRAY` of Access list entry `OBJECT`
         * **address** `STRING`: hex encoded address
         * **storageKeys** `ARRAY` of `STRING`: representation of 32 byte hex encoded storage keys
       * **maxFeePerBlobGas** (*optional*) `STRING`: hex, the maximum fee per blob gas in wei
       * **blobVersionedHashes** (*optional*) `ARRAY` of `STRING`: 32 byte hex encoded blob versioned hashes
       * **authorizationList** (*optional*) `ARRAY`: EIP-7702 authorization tuples
   * **returnFullTransactions** (*optional*) `BOOLEAN`: when `true`, result blocks contain full transaction objects instead of transaction hashes
2. **Base block number** (*optional*) The block on top of which the simulation runs. Defaults to `latest`. Either:
   * `STRING` Block number
   * `ENUM` of Block tag `earliest|finalized|safe|latest|pending`

**Example**

The request simulates two blocks. The first block funds a sender with a state override, then sends ETH and wraps 1 ETH into WETH; the second block sets a custom timestamp and transfers the WETH minted in the first block.

<Tabs>
  <Tab title="Request">
    ```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "id": 0,
      "jsonrpc": "2.0",
      "method": "eth_simulateV1",
      "params": [
        {
          "blockStateCalls": [
            {
              "stateOverrides": {
                "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2": {
                  "balance": "0x3635c9adc5dea00000"
                }
              },
              "calls": [
                {
                  "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
                  "to": "0x1111111111111111111111111111111111111111",
                  "value": "0x1bc16d674ec80000"
                },
                {
                  "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
                  "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                  "value": "0xde0b6b3a7640000",
                  "input": "0xd0e30db0"
                }
              ]
            },
            {
              "blockOverrides": { "time": "0x6ae00000" },
              "calls": [
                {
                  "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
                  "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                  "input": "0xa9059cbb00000000000000000000000011111111111111111111111111111111111111110000000000000000000000000000000000000000000000000de0b6b3a7640000"
                }
              ]
            }
          ]
        },
        "latest"
      ]
    }
    ```
  </Tab>

  <Tab title="Shell">
    ```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl https://mainnet.gateway.tenderly.co/$TENDERLY_NODE_ACCESS_KEY \
    -X POST \
    -H "Content-Type: application/json" \
    -d \
    '{
    "id": 0,
    "jsonrpc": "2.0",
    "method": "eth_simulateV1",
    "params": [
    {
    "blockStateCalls": [
      {
        "stateOverrides": {
          "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2": {
            "balance": "0x3635c9adc5dea00000"
          }
        },
        "calls": [
          {
            "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
            "to": "0x1111111111111111111111111111111111111111",
            "value": "0x1bc16d674ec80000"
          },
          {
            "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
            "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "value": "0xde0b6b3a7640000",
            "input": "0xd0e30db0"
          }
        ]
      },
      {
        "blockOverrides": { "time": "0x6ae00000" },
        "calls": [
          {
            "from": "0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
            "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "input": "0xa9059cbb00000000000000000000000011111111111111111111111111111111111111110000000000000000000000000000000000000000000000000de0b6b3a7640000"
          }
        ]
      }
    ]
    },
    "latest"
    ]
    }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    // Installation Instructions: https://docs.ethers.io/v5/getting-started/#installing
    const { ethers } = require('ethers');

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

    // Execute method
    const result = await provider.send('eth_simulateV1', [
    {
    blockStateCalls: [
      {
        stateOverrides: {
          '0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2': {
            balance: '0x3635c9adc5dea00000',
          },
        },
        calls: [
          {
            from: '0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2',
            to: '0x1111111111111111111111111111111111111111',
            value: '0x1bc16d674ec80000',
          },
          {
            from: '0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2',
            to: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
            value: '0xde0b6b3a7640000',
            input: '0xd0e30db0',
          },
        ],
      },
      {
        blockOverrides: { time: '0x6ae00000' },
        calls: [
          {
            from: '0xe2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2',
            to: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
            input: '0xa9059cbb00000000000000000000000011111111111111111111111111111111111111110000000000000000000000000000000000000000000000000de0b6b3a7640000',
          },
        ],
      },
    ],
    },
    'latest',
    ]);

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

    (async () => {
    runSimulateV1();
    })();
    ```
  </Tab>

  <Tab title="Response">
    ```json title="response.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "id": 0,
      "jsonrpc": "2.0",
      "result": [
        {
          "number": "0x184b35b",
          "hash": "0x2b33857d4b0380d7b92a258c77d9357c9515701f914684789e959ae84d73347a",
          "parentHash": "0x1fe7faf7d5b3a57fe52192bcf634b62bda8cfd39a5509d5541a2fb30d5438463",
          "nonce": "0x88425305eb52b6f7",
          "mixHash": "0x5bf018c82ca9e0e3805b00475afe61be2b1077eff79abb6cb4617af8548aa514",
          "sha3Uncles": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
          "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "miner": "0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97",
          "difficulty": "0x0",
          "extraData": "0x546974616e2028746974616e6275696c6465722e78797a29",
          "size": "0x0",
          "gasLimit": "0x3938700",
          "gasUsed": "0x3938700",
          "timestamp": "0x6a4bb197",
          "transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "receiptsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "baseFeePerGas": "0x18d7ee41",
          "blobGasUsed": "0x60000",
          "excessBlobGas": "0xba42085",
          "uncles": [],
          "transactions": [
            "0xbb42f5dcbfa507c52b64642c9b9e2a95fc4e2542cbd06b180239367d45f35e30",
            "0xcb06f645c2962f5dfff047efb2a000d05d0a58a619c63c97ec3e12cf48d02033"
          ],
          "calls": [
            {
              "returnData": "0x",
              "logs": [],
              "gasUsed": "0x5208",
              "status": "0x1"
            },
            {
              "returnData": "0x",
              "logs": [
                {
                  "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                  "topics": [
                    "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c",
                    "0x000000000000000000000000e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2"
                  ],
                  "data": "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000",
                  "blockNumber": "0x184b35b",
                  "transactionHash": "0xcb06f645c2962f5dfff047efb2a000d05d0a58a619c63c97ec3e12cf48d02033",
                  "transactionIndex": "0x1",
                  "blockHash": "0x2b33857d4b0380d7b92a258c77d9357c9515701f914684789e959ae84d73347a",
                  "logIndex": "0x0",
                  "removed": false
                }
              ],
              "gasUsed": "0xafee",
              "status": "0x1"
            }
          ]
        },
        {
          "number": "0x184b35c",
          "hash": "0xddb8a8a01c753b30acea4c8a12e36f3157dfa854ad0134b1dbb1e6227a9838cd",
          "parentHash": "0x2b33857d4b0380d7b92a258c77d9357c9515701f914684789e959ae84d73347a",
          "nonce": "0x0000000000000000",
          "mixHash": "0x5bf018c82ca9e0e3805b00475afe61be2b1077eff79abb6cb4617af8548aa514",
          "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
          "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
          "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "miner": "0x0000000000000000000000000000000000000000",
          "difficulty": "0x0",
          "extraData": "0x546974616e2028746974616e6275696c6465722e78797a29",
          "size": "0x18e",
          "gasLimit": "0x3938700",
          "gasUsed": "0x0",
          "timestamp": "0x6ae00000",
          "transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
          "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
          "baseFeePerGas": "0x1bf2ec09",
          "excessBlobGas": "0xba62085",
          "uncles": [],
          "transactions": [
            "0x21ac69b18844a9f1345c2b29292852477672178b0d338092f20dcb850d261604"
          ],
          "calls": [
            {
              "returnData": "0x0000000000000000000000000000000000000000000000000000000000000001",
              "logs": [
                {
                  "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                  "topics": [
                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                    "0x000000000000000000000000e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2",
                    "0x0000000000000000000000001111111111111111111111111111111111111111"
                  ],
                  "data": "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000",
                  "blockNumber": "0x184b35b",
                  "transactionHash": "0x21ac69b18844a9f1345c2b29292852477672178b0d338092f20dcb850d261604",
                  "transactionIndex": "0x0",
                  "blockHash": "0x2b33857d4b0380d7b92a258c77d9357c9515701f914684789e959ae84d73347a",
                  "logIndex": "0x1",
                  "removed": false
                }
              ],
              "gasUsed": "0x73fe",
              "status": "0x1"
            }
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

**Result**

`ARRAY` of Block result `OBJECT`, one per `blockStateCalls` entry, in order. Each block result carries the standard block header fields returned by `eth_getBlockByNumber` (`number`, `hash`, `parentHash`, `timestamp`, `gasLimit`, `gasUsed`, `baseFeePerGas`, `logsBloom`, `miner`, and so on) plus:

* **transactions** `ARRAY`: transaction hashes of the simulated calls, or full transaction objects when `returnFullTransactions` is `true`
* **calls** `ARRAY` of Call result `OBJECT`, one per call, in order:
  * **returnData** `STRING`: hex encoded return data of the call
  * **logs** `ARRAY` of Log `OBJECT`: events emitted by the call (`address`, `topics`, `data`, `blockNumber`, `transactionHash`, `transactionIndex`, `blockHash`, `logIndex`, `removed`); empty for reverted calls
  * **gasUsed** `STRING`: hex encoded amount of gas consumed by the call
  * **status** `STRING`: `0x1` for success, `0x0` for failure
  * **error** `OBJECT`: present only when the call fails
    * **code** `NUMBER`: error code
    * **message** `STRING`: error message, including the revert reason when available

### Tenderly-specific behavior

The Tenderly implementation deviates from the reference [execution-apis](https://github.com/ethereum/execution-apis) specification in the following ways:

* **`validation` is not supported.** Setting `validation: true` returns the error `validation flag is not supported`. Simulation always runs in non-validating mode: nonce, balance, and fee requirements are not enforced on the calls.
* **`traceTransfers` is not supported.** Setting `traceTransfers: true` returns the error `traceTransfers flag is not supported`. No synthetic ETH transfer logs are produced.
* **`state` overrides are not supported.** The `state` field (full storage replacement) in a state override returns a `not supported` error. Use `stateDiff` to override individual storage slots.
* **State overrides apply from the first block.** Set `stateOverrides` on the first `blockStateCalls` entry; `stateOverrides` on subsequent entries are not applied.
* **Per-call `gas` is clamped.** A `gas` value above the block gas limit plus 600,000,000 is clamped to that ceiling instead of being rejected.
* **No block or call count limits.** There is no enforced maximum on the number of `blockStateCalls` entries or on the number of calls per block.
* **Transaction hashes are synthetic.** The hashes in result blocks identify the simulated calls but are not hashes of signed transactions.
* **Block progression.** Each simulated block after the first gets `number = previous + 1` and a `parentHash` chained to the previous result, with the base fee and gas limit recomputed. The auto-generated timestamp is the node's wall-clock time, so set `blockOverrides.time` explicitly when timestamps matter. Overridden block numbers and timestamps are applied verbatim; monotonicity is not validated. When the first block entry supplies `blockOverrides` without `number`, the block number defaults to the base block plus 1.

### Network availability

`eth_simulateV1` is available on Node RPC networks and Virtual Environments, except on the following networks, where the underlying network nodes do not support the method:

* ApeChain
* Avalanche C-Chain
* Avalanche C-Chain Fuji
* Blast
* Curtis
* Flare
* Immutable
* Immutable Testnet
* Lens
* Lens Testnet
* Metis Andromeda
* Metis Sepolia
* Monad
* Monad Testnet
* Scroll Mainnet
* Sonic
* Sonic Testnet
* Stable
* Stable Testnet
* ZKsync
* ZKsync Sepolia


# Simulate Bundles
Source: https://docs.tenderly.co/node-rpc/guides/simulate-bundle-json-rpc

Simulate a bundle of transactions and get exact gas estimates with the tenderly_simulateBundle and tenderly_estimateGasBundle JSON-RPC methods.

<Note>The custom RPC methods appear in the **`tenderly_`** namespace.</Note>

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`](#tenderly_simulatebundle) returns the full decoded execution result for every transaction: logs, call trace, asset changes, and balance changes.
* [`tenderly_estimateGasBundle`](#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**

1. **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
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**

<Tabs>
  <Tab title="Request">
    ```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "id": 0,
      "jsonrpc": "2.0",
      "method": "tenderly_simulateBundle",
      "params": [
      [
    {
      "from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "data": "0x095ea7b300000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001"
    },
    {
      "from": "0x20a5814b73ef3537c6e099a0d45c798f4bd6e1d6",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "data": "0x23b872dd000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001"
    }
      ],
      "0xF4D880"
      ]
    }
    ```
  </Tab>

  <Tab title="Shell">
    ```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"
    ]
    }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    // 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();

    })();

    ```
  </Tab>

  <Tab title="Request">
    ```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "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
      ]
    }
      ]
    }
      ]
    }
    ```
  </Tab>
</Tabs>

**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
  * **`dollarValue`**`STRING`: dollar value of the transferred token
  * **`assetInfo`**`OBJECT`: asset information
    * **`standard`** `STRING`: supported token standards: ERC20, ERC721, NativeCurrency
    * **`type`** `STRING`: the token type: Native, Fungible, Non-Fungible
    * **`contractAddress`**`STRING` : 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
    * **`dollarValue`**`STRING`: 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`](/node-rpc/guides/simulate-json-rpc#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**

1. **Transactions** Transactions `ARRAY`: list of transactions in a bundle, same shape as in [`tenderly_simulateBundle`](#tenderly_simulatebundle)
2. **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`
3. **State Overrides** (*optional*) `MAP`: mapping from an account (address) to override specification, same shape as in [`tenderly_simulateBundle`](#tenderly_simulatebundle)
4. **Block Overrides** (*optional*) `OBJECT`: the set of header fields to override in a block, same shape as in [`tenderly_simulateBundle`](#tenderly_simulatebundle)

**Example**

<Tabs>
  <Tab title="Request">
    ```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "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"
      ]
    }
    ```
  </Tab>

  <Tab title="Shell">
    ```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"
    ]
    }'
    ```
  </Tab>

  <Tab title="Response">
    ```json title="response.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "id": 0,
      "jsonrpc": "2.0",
      "result": [
        { "gas": "0x12579", "gasUsed": "0xff06" },
        { "gas": "0x10918", "gasUsed": "0xb551" },
        { "gas": "0xa621", "gasUsed": "0x6625" },
        { "gas": "0x10649", "gasUsed": "0xb249" }
      ]
    }
    ```
  </Tab>
</Tabs>

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


# Simulate Transactions
Source: https://docs.tenderly.co/node-rpc/guides/simulate-json-rpc

Simulate a transaction and get an exact gas estimate with the tenderly_simulateTransaction and tenderly_estimateGas JSON-RPC methods.

<Note>The custom RPC methods appear in the **`tenderly_`** namespace.</Note>

These methods run on [Node RPC](/node-rpc/overview); see the full [JSON-RPC reference](/node-rpc/rpc-reference) for every method and network.

Two methods execute a single transaction against a given block without sending it on chain:

* [`tenderly_simulateTransaction`](#tenderly_simulatetransaction) returns the full decoded execution: logs, call trace, asset changes, and balance changes.
* [`tenderly_estimateGas`](#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**

<Tabs>
  <Tab title="Request">
    ```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "id": 0,
      "jsonrpc": "2.0",
      "method": "tenderly_simulateTransaction",
      "params": [
        {
          "from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
          "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "data": "0xa9059cbb00000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001"
        },
        "0xF4D880"
      ]
    }
    ```
  </Tab>

  <Tab title="Shell">
    ```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"
    ]
    }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    // 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();
    })();
    ```
  </Tab>

  <Tab title="Request">
    ```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "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
      ]
    }
      ]
    }
    }
    ```
  </Tab>
</Tabs>

**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
  * **`dollarValue`**`STRING`: dollar value of the transferred token
  * **`assetInfo`**`OBJECT`: asset information
    * **`standard`** `STRING`: supported token standards: ERC20, ERC721, NativeCurrency
    * **`type`** `STRING`: the token type: Native, Fungible, Non-Fungible
    * **`contractAddress`**`STRING` : 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
    * **`dollarValue`**`STRING`: 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`](#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`](#tenderly_simulatetransaction)
4. **Block Overrides** (*optional*) `OBJECT`: the set of header fields to override in a block, same shape as in [`tenderly_simulateTransaction`](#tenderly_simulatetransaction)

**Example**

<Tabs>
  <Tab title="Request">
    ```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "id": 0,
      "jsonrpc": "2.0",
      "method": "tenderly_estimateGas",
      "params": [
        {
          "from": "0x8516feaea147ea0db64d1c5b97bb651ca5435155",
          "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
          "data": "0xa9059cbb0000000000000000000000003fc3c4c84bdd2db5ab2cc62f93b2a9a347de25fb00000000000000000000000000000000000000000000001869c36187f3430000",
          "value": "0x0"
        },
        "21285787"
      ]
    }
    ```
  </Tab>

  <Tab title="Shell">
    ```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"
    ]
    }'
    ```
  </Tab>

  <Tab title="Response">
    ```json title="response.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "id": 0,
      "jsonrpc": "2.0",
      "result": {
        "gas": "0x12579",
        "gasUsed": "0xff06"
      }
    }
    ```
  </Tab>
</Tabs>

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


# Trace Transactions
Source: https://docs.tenderly.co/node-rpc/guides/trace-json-rpc

Get a decoded execution trace of an existing transaction with the tenderly_traceTransaction JSON-RPC method.

<Note>The custom RPC methods appear in the **`tenderly_`** namespace.</Note>

This method runs on [Node RPC](/node-rpc/overview); see the full [JSON-RPC reference](/node-rpc/rpc-reference) for every method and network.

### `tenderly_traceTransaction`

Replays transaction on the blockchain and provides information about the execution, such as status, logs, internal transactions, etc.

**Params**

1. **Transaction hash** `STRING` 32 byte hex value

**Example**

<Tabs>
  <Tab title="Request">
    ```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "id": 0,
      "jsonrpc": "2.0",
      "method": "tenderly_traceTransaction",
      "params": ["0x6b2264fa8e28a641d834482d250080b39cbbf39251344573c7504d6137c4b793" ]
    }
    ```
  </Tab>

  <Tab title="Shell">
    ```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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_traceTransaction",
    "params": ["0x6b2264fa8e28a641d834482d250080b39cbbf39251344573c7504d6137c4b793"]
    }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript title="example.js" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    // 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_traceTransaction", [
    "0x6b2264fa8e28a641d834482d250080b39cbbf39251344573c7504d6137c4b793"
    ]);

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

    }

    (async () => {
    runSimulateTransaction();

    })();

    ```
  </Tab>

  <Tab title="Request">
    ```json title="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "id": 0,
      "jsonrpc": "2.0",
      "result": {
      "status": true,
      "gasUsed": "0x2da74",
      "cumulativeGasUsed": "0x0",
      "blockNumber": "0xfbc520",
      "type": "0x0",
      "logsBloom": "0x00200080000000000000000080000000000000000000000000010040000000000000000000000000000000000000000002000000080000000000000000000000000000000000000000000008000000200000000000000008000000008000000000000000000000001000000000000000000000000000800040000010000000000000000000000000004000000000000000000001080000080000004000000000000000000000000000080000000000000000000000000000000200000000000000000002000000000000000000000000004000000000001000010000000020000000200000000000000000200000000000000000000000400000000000000000",
      "logs": [
    {
      "name": "Deposit",
      "anonymous": false,
      "inputs": [
    {
      "value": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "type": "address",
      "name": "dst"
    },
    {
      "value": "25000000000000000",
      "type": "uint256",
      "name": "wad"
    }
      ],
      "raw": {
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "topics": [
      "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c",
      "0x0000000000000000000000007a250d5630b4cf539739df2c5dacb4c659f2488d"
      ],
      "data": "0x0000000000000000000000000000000000000000000000000058d15e17628000"
    }
    },
    {
      "name": "Transfer",
      "anonymous": false,
      "inputs": [
    {
      "value": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "type": "address",
      "name": "src"
    },
    {
      "value": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "type": "address",
      "name": "dst"
    },
    {
      "value": "25000000000000000",
      "type": "uint256",
      "name": "wad"
    }
      ],
      "raw": {
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "topics": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "0x0000000000000000000000007a250d5630b4cf539739df2c5dacb4c659f2488d",
      "0x000000000000000000000000a0c9bf9aa601ddfb1cdf3be3ef77e010e4184076"
      ],
      "data": "0x0000000000000000000000000000000000000000000000000058d15e17628000"
    }
    },
    {
      "name": "Transfer",
      "anonymous": false,
      "inputs": [
    {
      "value": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "type": "address",
      "name": "from"
    },
    {
      "value": "0x17b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "type": "address",
      "name": "to"
    },
    {
      "value": "1201840076490568",
      "type": "uint256",
      "name": "value"
    }
      ],
      "raw": {
      "address": "0xd81781e686d0ad128b4c7e7b3c072b89f509ea2a",
      "topics": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "0x000000000000000000000000a0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "0x00000000000000000000000017b11ed010e715bf4336a88489fe4f0ef6a09dc7"
      ],
      "data": "0x0000000000000000000000000000000000000000000000000004451132d60748"
    }
    },
    {
      "name": "Sync",
      "anonymous": false,
      "inputs": [
    {
      "value": "5161635883710151874",
      "type": "uint112",
      "name": "reserve0"
    },
    {
      "value": "263488971740003263",
      "type": "uint112",
      "name": "reserve1"
    }
      ],
      "raw": {
      "address": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "topics": [
      "0x1c411e9a96e071241c2f21f7726b17ae89e3cab4c78be50e062b03a9fffbbad1"
      ],
      "data": "0x00000000000000000000000000000000000000000000000047a1d07d1c73fcc200000000000000000000000000000000000000000000000003a819d2e2cbbbbf"
    }
    },
    {
      "name": "Swap",
      "anonymous": false,
      "inputs": [
    {
      "value": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "type": "address",
      "name": "sender"
    },
    {
      "value": "25000000000000000",
      "type": "uint256",
      "name": "amount0In"
    },
    {
      "value": "0",
      "type": "uint256",
      "name": "amount1In"
    },
    {
      "value": "0",
      "type": "uint256",
      "name": "amount0Out"
    },
    {
      "value": "1278553272862306",
      "type": "uint256",
      "name": "amount1Out"
    },
    {
      "value": "0x17b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "type": "address",
      "name": "to"
    }
      ],
      "raw": {
      "address": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "topics": [
      "0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822",
      "0x0000000000000000000000007a250d5630b4cf539739df2c5dacb4c659f2488d",
      "0x00000000000000000000000017b11ed010e715bf4336a88489fe4f0ef6a09dc7"
      ],
      "data": "0x0000000000000000000000000000000000000000000000000058d15e176280000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000048ad661a7c662"
    }
    }
      ],
      "trace": [
    {
      "type": "CALL",
      "from": "0x17b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "to": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "gas": "0x35004",
      "gasUsed": "0x2da40",
      "value": "0x58d15e17628000",
      "input": "0xb6f9de950000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000017b11ed010e715bf4336a88489fe4f0ef6a09dc70000000000000000000000000000000000000000000000000000000063d41cf70000000000000000000000000000000000000000000000000000000000000002000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000d81781e686d0ad128b4c7e7b3c072b89f509ea2a",
      "decodedInput": [
    {
      "value": "0",
      "type": "uint256",
      "name": "amountOutMin"
    },
    {
      "value": [
      "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "0xd81781e686d0ad128b4c7e7b3c072b89f509ea2a"
      ],
      "type": "address[]",
      "name": "path"
    },
    {
      "value": "0x17b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "type": "address",
      "name": "to"
    },
    {
      "value": "1674845431",
      "type": "uint256",
      "name": "deadline"
    }
      ],
      "method": "swapExactETHForTokensSupportingFeeOnTransferTokens",
      "output": "0x",
      "subtraces": 7,
      "traceAddress": [
      0
      ]
    },
    {
      "type": "CALL",
      "from": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "gas": "0x31c34",
      "gasUsed": "0x5da6",
      "value": "0x58d15e17628000",
      "input": "0xd0e30db0",
      "output": "0x",
      "subtraces": 0,
      "traceAddress": [
      0,
      0
      ]
    },
    {
      "type": "CALL",
      "from": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "gas": "0x2bb7b",
      "gasUsed": "0x1f7e",
      "value": "0x0",
      "input": "0xa9059cbb000000000000000000000000a0c9bf9aa601ddfb1cdf3be3ef77e010e41840760000000000000000000000000000000000000000000000000058d15e17628000",
      "decodedInput": [
    {
      "value": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "type": "address",
      "name": "dst"
    },
    {
      "value": "25000000000000000",
      "type": "uint256",
      "name": "wad"
    }
      ],
      "method": "transfer",
      "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
      "decodedOutput": [
    {
      "value": true,
      "type": "bool",
      "name": ""
    }
      ],
      "subtraces": 0,
      "traceAddress": [
      0,
      1
      ]
    },
    {
      "type": "STATICCALL",
      "from": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "to": "0xd81781e686d0ad128b4c7e7b3c072b89f509ea2a",
      "gas": "0x29100",
      "gasUsed": "0x19fe",
      "input": "0x70a0823100000000000000000000000017b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "decodedInput": [
    {
      "value": "0x17b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "type": "address",
      "name": "account"
    }
      ],
      "method": "balanceOf",
      "output": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "decodedOutput": [
    {
      "value": "0",
      "type": "uint256",
      "name": ""
    }
      ],
      "subtraces": 0,
      "traceAddress": [
      0,
      2
      ]
    },
    {
      "type": "STATICCALL",
      "from": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "to": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "gas": "0x267d6",
      "gasUsed": "0x9c8",
      "input": "0x0902f1ac",
      "output": "0x0000000000000000000000000000000000000000000000004748ff1f05117cc200000000000000000000000000000000000000000000000003aca4a9447382210000000000000000000000000000000000000000000000000000000063d41a7f",
      "decodedOutput": [
    {
      "value": "5136635883710151874",
      "type": "uint112",
      "name": "_reserve0"
    },
    {
      "value": "264767525012865569",
      "type": "uint112",
      "name": "_reserve1"
    },
    {
      "value": 1674844799,
      "type": "uint32",
      "name": "_blockTimestampLast"
    }
      ],
      "subtraces": 0,
      "traceAddress": [
      0,
      3
      ]
    },
    {
      "type": "STATICCALL",
      "from": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "gas": "0x25c36",
      "gasUsed": "0x216",
      "input": "0x70a08231000000000000000000000000a0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "decodedInput": [
    {
      "value": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "type": "address",
      "name": ""
    }
      ],
      "method": "balanceOf",
      "output": "0x00000000000000000000000000000000000000000000000047a1d07d1c73fcc2",
      "decodedOutput": [
    {
      "value": "5161635883710151874",
      "type": "uint256",
      "name": ""
    }
      ],
      "subtraces": 0,
      "traceAddress": [
      0,
      4
      ]
    },
    {
      "type": "CALL",
      "from": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "to": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "gas": "0x2542c",
      "gasUsed": "0x1daa9",
      "value": "0x0",
      "input": "0x022c0d9f000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000048ad661a7c66200000000000000000000000017b11ed010e715bf4336a88489fe4f0ef6a09dc700000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000",
      "decodedInput": [
    {
      "value": "0",
      "type": "uint256",
      "name": "amount0Out"
    },
    {
      "value": "1278553272862306",
      "type": "uint256",
      "name": "amount1Out"
    },
    {
      "value": "0x17b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "type": "address",
      "name": "to"
    },
    {
      "value": "0x",
      "type": "bytes",
      "name": "data"
    }
      ],
      "method": "swap",
      "output": "0x",
      "subtraces": 3,
      "traceAddress": [
      0,
      5
      ]
    },
    {
      "type": "CALL",
      "from": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "to": "0xd81781e686d0ad128b4c7e7b3c072b89f509ea2a",
      "gas": "0x220ec",
      "gasUsed": "0x153da",
      "value": "0x0",
      "input": "0xa9059cbb00000000000000000000000017b11ed010e715bf4336a88489fe4f0ef6a09dc700000000000000000000000000000000000000000000000000048ad661a7c662",
      "decodedInput": [
    {
      "value": "0x17b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "type": "address",
      "name": "recipient"
    },
    {
      "value": "1278553272862306",
      "type": "uint256",
      "name": "amount"
    }
      ],
      "method": "transfer",
      "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
      "decodedOutput": [
    {
      "value": true,
      "type": "bool",
      "name": ""
    }
      ],
      "subtraces": 0,
      "traceAddress": [
      0,
      5,
      0
      ]
    },
    {
      "type": "STATICCALL",
      "from": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "gas": "0xd008",
      "gasUsed": "0x216",
      "input": "0x70a08231000000000000000000000000a0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "decodedInput": [
    {
      "value": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "type": "address",
      "name": ""
    }
      ],
      "method": "balanceOf",
      "output": "0x00000000000000000000000000000000000000000000000047a1d07d1c73fcc2",
      "decodedOutput": [
    {
      "value": "5161635883710151874",
      "type": "uint256",
      "name": ""
    }
      ],
      "subtraces": 0,
      "traceAddress": [
      0,
      5,
      1
      ]
    },
    {
      "type": "STATICCALL",
      "from": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "to": "0xd81781e686d0ad128b4c7e7b3c072b89f509ea2a",
      "gas": "0xcc65",
      "gasUsed": "0xa5e",
      "input": "0x70a08231000000000000000000000000a0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "decodedInput": [
    {
      "value": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "type": "address",
      "name": "account"
    }
      ],
      "method": "balanceOf",
      "output": "0x00000000000000000000000000000000000000000000000003a819d2e2cbbbbf",
      "decodedOutput": [
    {
      "value": "263488971740003263",
      "type": "uint256",
      "name": ""
    }
      ],
      "subtraces": 0,
      "traceAddress": [
      0,
      5,
      2
      ]
    },
    {
      "type": "STATICCALL",
      "from": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "to": "0xd81781e686d0ad128b4c7e7b3c072b89f509ea2a",
      "gas": "0x7edd",
      "gasUsed": "0xa5e",
      "input": "0x70a0823100000000000000000000000017b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "decodedInput": [
    {
      "value": "0x17b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "type": "address",
      "name": "account"
    }
      ],
      "method": "balanceOf",
      "output": "0x0000000000000000000000000000000000000000000000000004451132d60748",
      "decodedOutput": [
    {
      "value": "1201840076490568",
      "type": "uint256",
      "name": ""
    }
      ],
      "subtraces": 0,
      "traceAddress": [
      0,
      6
      ]
    }
      ],
      "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": "Mint",
      "to": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "rawAmount": "0x58d15e17628000",
      "amount": "0.025",
      "dollarValue": "45.8654998779296875"
    },
    {
      "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": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "to": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "rawAmount": "0x58d15e17628000",
      "amount": "0.025",
      "dollarValue": "45.8654998779296875"
    },
    {
      "assetInfo": {
      "standard": "ERC20",
      "contractAddress": "0xd81781e686d0ad128b4c7e7b3c072b89f509ea2a"
    },
      "type": "Transfer",
      "from": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "to": "0x17b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "rawAmount": "0x4451132d60748"
    },
    {
      "assetInfo": {
      "standard": "NativeCurrency",
      "type": "Native",
      "symbol": "eth",
      "name": "Ethereum",
      "logo": "https://assets.coingecko.com/coins/images/279/large/ethereum.webp?1595348880",
      "decimals": 18,
      "dollarValue": "1828.77001953125"
    },
      "type": "Transfer",
      "from": "0x17b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "to": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "rawAmount": "0x58d15e17628000",
      "amount": "0.025",
      "dollarValue": "45.71925048828125"
    },
    {
      "assetInfo": {
      "standard": "NativeCurrency",
      "type": "Native",
      "symbol": "eth",
      "name": "Ethereum",
      "logo": "https://assets.coingecko.com/coins/images/279/large/ethereum.webp?1595348880",
      "decimals": 18,
      "dollarValue": "1828.77001953125"
    },
      "type": "Transfer",
      "from": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "rawAmount": "0x58d15e17628000",
      "amount": "0.025",
      "dollarValue": "45.71925048828125"
    }
      ],
      "balanceChanges": [
    {
      "address": "0x17b11ed010e715bf4336a88489fe4f0ef6a09dc7",
      "dollarValue": "-45.71925048828125",
      "transfers": [
      2,
      3
      ]
    },
    {
      "address": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
      "dollarValue": "0",
      "transfers": [
      0,
      1,
      3,
      4
      ]
    },
    {
      "address": "0xa0c9bf9aa601ddfb1cdf3be3ef77e010e4184076",
      "dollarValue": "45.8654998779296875",
      "transfers": [
      1,
      2
      ]
    },
    {
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "dollarValue": "45.71925048828125",
      "transfers": [
      4
      ]
    }
      ]
    }
    }
    ```
  </Tab>
</Tabs>

### Result

Trace transactions 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
  * **`dollarValue`**`STRING`: dollar value of the transferred token
  * **`assetInfo`**`OBJECT`: asset information
    * **`standard`** `STRING`: supported token standards: ERC20, ERC721, NativeCurrency
    * **`type`** `STRING`: the token type: Native, Fungible, Non-Fungible
    * **`contractAddress`**`STRING` : 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
    * **`dollarValue`**`STRING`: 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


# Integration Guides
Source: https://docs.tenderly.co/node-rpc/integrations

Learn how to integrate Node RPC with different client libraries, smart contract development frameworks, and UI libraries.

Node RPC works with the most popular client libraries, smart contract frameworks, and UI libraries. On this page, you can find links to guides with simple code snippets that enable you to quickly integrate Node RPC with third-party libraries and use it as a blockchain provider.

## Client libraries

Client libraries enable your dapp to connect to a blockchain network through RPC using Node RPC and interact with it.

<CardGroup>
  <Card title="Ethers.js" href="/node-rpc/libraries/ethers">
    Typescript and Javascript library for interacting with the Ethereum blockchain and ecosystem.
  </Card>

  <Card title="Viem" href="/node-rpc/libraries/viem">
    TypeScript Interface that provides low-level stateless primitives for interacting with Ethereum.
  </Card>

  <Card title="Go-ethereum (geth)" href="/node-rpc/libraries/go">
    Popular Ethereum client used for writing to the blockchain and reading data.
  </Card>

  <Card title="Web3.py" href="/node-rpc/libraries/web3-py">
    Python library for interacting with smart contracts and reading data on Ethereum.
  </Card>
</CardGroup>

## Smart contract frameworks

Smart contract frameworks provide the tools for developing, testing, and deploying smart contracts to the blockchain. The guides below show you how to connect popular frameworks to use Node RPC as an entry point to the blockchain and Tenderly's testing infrastructure via RPC.

<CardGroup>
  <Card title="Foundry" href="/node-rpc/frameworks/foundry">
    Toolkit for compiling, testing, and deploying smart contracts on Ethereum.
  </Card>

  <Card title="Hardhat" href="/node-rpc/frameworks/hardhat">
    Framework for developing, testing, and deploying smart contracts on Ethereum.
  </Card>
</CardGroup>

## Dapp UI libraries

Dapp UI libraries provide pre-built UI components designed for building dapp interfaces that communicate with the blockchain. Below you'll find code snippets for popular UI libraries that use Node RPC to connect to the blockchain via RPC.

<CardGroup>
  <Card title="Wagmi" href="/node-rpc/dapp-ui/wagmi">
    React hooks library for building Ethereum apps with wallet connection modules.
  </Card>

  <Card title="Reown AppKit" href="/node-rpc/dapp-ui/reown">
    Tools, modules, and SDKs for building secure and interactive dapps.
  </Card>

  <Card title="ConnectKit" href="/node-rpc/dapp-ui/connectkit">
    React.js component library for connecting wallets to dapps.
  </Card>

  <Card title="Dynamic" href="/node-rpc/dapp-ui/dynamic">
    Login flows for crypto users, onboarding, and developer tools.
  </Card>

  <Card title="RainbowKit" href="/node-rpc/dapp-ui/rainbowkit">
    React library for adding wallet connections to dapps.
  </Card>

  <Card title="ThirdWeb SDK" href="/node-rpc/integrations">
    Collection of React hooks and UI components for EVM-compatible dapps.
  </Card>
</CardGroup>


# Ethers.js v6 and v5 - Node RPC Integration
Source: https://docs.tenderly.co/node-rpc/libraries/ethers

Connect ethers v6 or v5 to Tenderly Node RPC with JsonRpcProvider over HTTPS or WebSockets to query, trace, and simulate transactions on EVM networks.

[Ethers.js](https://docs.ethers.org/v5/) is a standalone TypeScript/JavaScript library for interacting with the Ethereum blockchain and its ecosystem.

To connect to a network through Node RPC using ethers v6 or v5, use the JSON-RPC provider backed by HTTPS or WebSockets.

## Using JsonRpcProvider (ethers v6 and v5)

<Tabs>
  <Tab title="Ethers 6">
    ```js title="ethers-6/json-rpc-provider.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    // Installation Instructions: https://docs.ethers.io/v6/getting-started
    import { ethers } from "ethers";

    const RPC_URL = `https://mainnet.gateway.tenderly.co/${process.env.TENDERLY_NODE_ACCESS_KEY}`

    async function executeMethod() {
      // Initialize an ethers provider instance
      const provider = new ethers.JsonRpcProvider(RPC_URL);

      const blockNumber = await provider.getBlockNumber();

      console.log(blockNumber);
    }

    await executeMethod();
    ```
  </Tab>

  <Tab title="Ethers 5">
    ```js title="ethers-5/json-rpc-provider.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    // Installation Instructions: https://docs.ethers.io/v5/getting-started
    import { ethers } from "ethers";

    const RPC_URL = `https://mainnet.gateway.tenderly.co/${process.env.TENDERLY_NODE_ACCESS_KEY}`

    async function executeMethod() {
      // Initialize an ethers provider instance
      const provider = new ethers.providers.JsonRpcProvider(RPC_URL);

      const blockNumber = await provider.getBlockNumber();

      console.log(blockNumber);
    }

    await executeMethod();
    ```
  </Tab>
</Tabs>

Once connected, call any standard `eth_*` method or a Tenderly extension like `tenderly_simulateTransaction` through the provider. See the full [JSON-RPC reference](/node-rpc/rpc-reference) for every supported method and network.

## Using WebSocket provider

<Tabs>
  <Tab title="Ethers 6">
    ```js title="ethers-6/wss-provider.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    // Installation Instructions: https://docs.ethers.io/v6/getting-started
    import { ethers } from "ethers";

    const RPC_URL_WSS = `wss://mainnet.gateway.tenderly.co/${process.env.TENDERLY_NODE_ACCESS_KEY}`

    async function executeMethod() {
      // Initialize an ethers provider instance
      const provider = new ethers.WebSocketProvider(RPC_URL_WSS);

      const blockNumber = await provider.getBlockNumber();

      console.log(blockNumber);
    }

    await executeMethod();
    ```
  </Tab>

  <Tab title="Ethers 5">
    ```js title="ethers-5/wss-provider.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    // Installation Instructions: https://docs.ethers.io/v5/getting-started
    import { ethers } from "ethers";

    const RPC_URL_WSS = `wss://mainnet.gateway.tenderly.co/${process.env.TENDERLY_NODE_ACCESS_KEY}`

    async function executeMethod() {
      // Initialize an ethers provider instance
      const provider = new ethers.providers.WebSocketProvider(RPC_URL_WSS);

      const blockNumber = await provider.getBlockNumber();

      console.log(blockNumber);
    }

    await executeMethod();
    ```
  </Tab>
</Tabs>


# Go-Ethereum (geth) - Node RPC Integration
Source: https://docs.tenderly.co/node-rpc/libraries/go

Connect a Go application to Tenderly Node RPC with the go-ethereum (geth) ethclient using the gateway endpoint to read and write onchain data.

[Go-Ethereum](https://goethereumbook.org/en/) is the official Ethereum implementation in Go, to interact with the blockchain. Go-Ethereum, also known as *geth* for short, is the most popular Ethereum client. It provides everything we'll ever need for reading and writing to the blockchain when developing applications using Golang. Connect it to [Node RPC](/node-rpc/overview) using the gateway endpoint, and see the [JSON-RPC reference](/node-rpc/rpc-reference) for supported methods.

```go title="client.go" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
package main

import (
    "fmt"
    "log"
    "github.com/ethereum/go-ethereum/ethclient"
)

func main() {
    client, err := ethclient.Dial("https://mainnet.gateway.tenderly.co/<TENDERLY_NODE_ACCESS_KEY_MAINNET>")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("we have a connection")
    _ = client // we'll use this in the upcoming sections
}
```


# Viem - Node RPC Integration
Source: https://docs.tenderly.co/node-rpc/libraries/viem

Connect viem to Tenderly Node RPC to read, send, trace, and simulate transactions across 100+ EVM networks over HTTPS or WebSockets.

[Viem](https://viem.sh/) is a TypeScript Interface for Ethereum that provides low-level stateless primitives for interacting with Ethereum.

You can use Tenderly with Viem to interact with the blockchain using standard RPC methods, as well as [custom methods available on Node RPC](/node-rpc/rpc-reference).

Call Viem's `createPublicClient` and pass the following arguments:

* `chain`: one of the pre-defined chains from `viem/chains`
* `transport`: either a call to `http` or `webSocket`, and initialize with the `https` or `wss` RPC URL.

<Card title="Code samples: Using Viem with Node RPC" href="" />

```js title="node/samples/viem/0-a-call.ts" showLineNumbers {16-18} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

const client = createPublicClient({
  chain: mainnet,
  transport: http(
    `https://mainnet.gateway.tenderly.co/${process.env.TENDERLY_NODE_ACCESS_KEY}`
  ),
});


console.log("Block Number", await client.getBlockNumber());
```

## Batching requests

Viem allows you to send [batch requests](https://viem.sh/docs/clients/transports/http#batch-json-rpc). With batching, several JSON-RPC calls are processed in a single HTTPS request. Several Viem actions will be batched and executed at the end of the current JavaScript message queue. By default, there's no time delay, but is possible to configure via an optional `wait` parameter.

This means that several viem actions will be batched and executed at the end of current JavaScript message queue. By default, there's no time-delay, but is possible to configure via an optional `wait` parameter.

```js title="node/samples/viem/0-batch-calls.ts" showLineNumbers {16-21} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

const client = createPublicClient({
  chain: mainnet,
  transport: http(
    `https://mainnet.gateway.tenderly.co/${process.env.TENDERLY_NODE_ACCESS_KEY}`,
    {
      batch: true,
    }
  ),
});

const [blockNumber, balance, ensName] = await Promise.all([
  client.getBlockNumber(),
  client.getBalance({ address: "0xd2135CfB216b74109775236E36d4b433F1DF507B" }),
  client.getEnsName({ address: "0xd2135CfB216b74109775236E36d4b433F1DF507B" }),
  client.getChainId(),
]);
console.log("Results are in");
console.log({ blockNumber, balance, ensName });

//  So will this
const bnPromise = client.getBlockNumber();

const balancePromise = client.getBalance({
  address: "0xd2135CfB216b74109775236E36d4b433F1DF507B",
});

console.log(await bnPromise);
console.log(await balancePromise);
```

## Simulate transactions using viem

To use [Simulation RPC methods](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction), simply use the `client.request` method:

```js title="node/samples/viem/1-simulate.ts" showLineNumbers {2-15} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const simulation = await client.request({
  method: "tenderly_simulateTransaction",
  params: [
    // transaction object
    {
      from: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      to: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      gas: "0x0",
      gasPrice: "0x0",
      value: "0x0",
      data: "0xa9059cbb00000000000000000000000020a5814b73ef3537c6e099a0d45c798f4bd6e1d60000000000000000000000000000000000000000000000000000000000000001",
    },
    // the block
    "latest",
  ],
});

console.log("Trace");
console.log(JSON.stringify(simulation.trace, null, 2));
console.log("=======================================================");
console.log("Logs");
console.log(JSON.stringify(simulation.logs, null, 2));
console.log("=======================================================");
console.log("Asset Changes");
console.log(JSON.stringify(simulation.assetChanges, null, 2));
console.log("=======================================================");
console.log("Balance Changes");
console.log(JSON.stringify(simulation.balanceChanges, null, 2));
```

## Trace transactions using Viem

Use [`tenderly_traceTransaction`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_traceTransaction) to get fully decoded transaction trace.

```ts showLineNumbers title="node/samples/viem/2-transaction-trace.ts" {2-6} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const txTrace = await client.request({
  method: "tenderly_traceTransaction",
  params: [
    // transaction hash
    "0x6b2264fa8e28a641d834482d250080b39cbbf39251344573c7504d6137c4b793"
  ],
});


console.log("Logs");
console.log(JSON.stringify(txTrace.logs, null, 2));
console.log("=======================================================");
console.log("Asset Changes");
console.log(JSON.stringify(txTrace.assetChanges, null, 2));
console.log("=======================================================");
console.log("Balance Changes");
console.log(JSON.stringify(txTrace.balanceChanges, null, 2));
console.log("=======================================================");
```


# Web3.py - Node RPC Integration
Source: https://docs.tenderly.co/node-rpc/libraries/web3-py

Learn how to use Web3.py to enable your Python application to communicate with Ethereum through Node RPC.

[web3.py](https://web3py.readthedocs.io/en/stable/index.html) is a Python library for interacting with Ethereum.

It’s commonly found in decentralized apps (dapps) to help with sending transactions, interacting with smart contracts, reading block data, and a variety of other use cases. Point web3.py at [Node RPC](/node-rpc/overview) to reach 75+ EVM networks, and see the [JSON-RPC reference](/node-rpc/rpc-reference) for supported methods.

```py showLineNumbers title="connect.py" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}

from web3 import Web3, AsyncWeb3

w3 = Web3(Web3.HTTPProvider('https:// mainnet.gateway.tenderly.co/<TENDERLY_NODE_ACCESS_KEY_MAINNET>'))
w3Async = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('https:// mainnet.gateway.tenderly.co/<TENDERLY_NODE_ACCESS_KEY_MAINNET>'))
w3Wss = Web3(Web3.WebsocketProvider('wss:// mainnet.gateway.tenderly.co/<TENDERLY_NODE_ACCESS_KEY_MAINNET>'))

print(w3.eth.get_block('latest'))
print(w3Async.eth.get_block('latest'))
print(w3Wss.is_connected())
print(w3Wss.eth.get_block('latest'))
```


# Node RPC
Source: https://docs.tenderly.co/node-rpc/overview

Access 75+ EVM networks over JSON-RPC and WebSocket with Tenderly Node RPC. Send, simulate, and trace transactions and read chain data, no node to run.

Node RPC is a fast and reliable production node that enables access to over 75 blockchain networks via RPC. It allows you to send transactions, deploy smart contracts, query blockchain data or other operations without having to run your own node or manage infrastructure.

<Note>
  Node RPC is available on the paid plan. To enable it for your account, [contact our sales team](https://tenderly.co/contact-us).
</Note>

Node RPC supports:

* Multi-regional infrastructure (EU & US) ensuring location-independent low latency
* Access through `http` and [WebSocket](#websockets) protocols
* [Request batching](#batching-json-rpc-requests)
* Building custom RPC methods through [Node Extensions](#node-extensions)
* Access to Tenderly's development tooling

<img alt="" />

## Custom RPC methods

In addition to supporting standard EVM methods, Node RPC exposes Tenderly's custom RPC methods in the `tenderly_` namespace.

Simulation, gas estimation, and tracing methods are documented on dedicated pages:

* [`tenderly_simulateTransaction`](/node-rpc/guides/simulate-json-rpc) to simulate the outcome of a transaction before signing.
* [`tenderly_estimateGas`](/node-rpc/guides/simulate-json-rpc#tenderly_estimategas) to get an exact gas estimate for a transaction.
* [`tenderly_simulateBundle`](/node-rpc/guides/simulate-bundle-json-rpc) to simulate multiple transactions in a single request.
* [`tenderly_estimateGasBundle`](/node-rpc/guides/simulate-bundle-json-rpc#tenderly_estimategasbundle) to get exact gas estimates for a bundle of transactions.
* [`tenderly_traceTransaction`](/node-rpc/guides/trace-json-rpc) to get a decoded trace of an existing transaction.

Decoding and signature lookup methods are available in the [RPC reference](/node-rpc/rpc-reference):

* [`tenderly_decodeInput`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_decodeInput) to heuristically decode external function calls.
* [`tenderly_decodeError`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_decodeError) to heuristically decode custom errors.
* [`tenderly_decodeEvent`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_decodeEvent) to heuristically decode emitted events.
* [`tenderly_functionSignatures`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_functionSignatures) to retrieve function interface based on 4-byte function selector.
* [`tenderly_errorSignatures`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_errorSignatures) to retrieve event interface based on 4-byte selector.
* [`tenderly_eventSignature`](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_eventSignature) to retrieve event interface based on 32-byte event signature.

## Managing Node RPCs

Log into the Dashboard and [go to the Node RPCs page](https://dashboard.tenderly.co/register?redirectTo=gateways) where you can create new Node RPCs and manage existing ones.

### Creating a Node RPC

To create a new Node RPC, follow these steps:

* Click the **Create Node** button
* Choose the network you want to access
* Provide a name for the Node
* Click **Create**

<Note>
  Each Node you create will have a unique URL.
</Note>

<img alt="" />

### Configuring Node RPCs

Once the Node RPC has been created, you can configure it in the **Settings**. From there, you can:

* Reset the Node RPC URL
* Change the Node name
* Delete the Node

<img alt="" />

### Add Node RPC to MetaMask

Add the Node RPC to your MetaMask wallet with a single click. Open the node's **Overview** page, click the **Add to Wallet** button, and confirm the action in MetaMask.

Click **Approve** in MetaMask to add Node RPC.

<img alt="Node RPC" />

## WebSockets

Node RPC is accessible over WebSocket (`wss://`) in addition to HTTPS. A WebSocket connection is persistent and bidirectional, and is required for the subscription methods `eth_subscribe` and `eth_unsubscribe`.

To get the WebSocket endpoint, open the node's **Overview** page in the [Dashboard](https://dashboard.tenderly.co/?redirectTo=gateways) and copy the **WSS** URL.

<img alt="" />

You can test the connection with the `wscat` command-line tool:

```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
wscat -c wss://mainnet.gateway.tenderly.co/$TENDERLY_NODE_ACCESS_KEY
```

Once connected, send JSON-RPC requests over the socket and receive responses in real time:

```json title="request.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}
```

```json title="response.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{"jsonrpc":"2.0","id":1,"result":"0x657330"}
```

## Batching JSON-RPC requests

JSON-RPC request batching allows you to send several JSON-RPC method invocations within a single HTTPS call. A batch request consists of an array of individual JSON-RPC requests, and the response is an array of results in the order corresponding to each request from the batch.

You can use batching:

* **directly**, by sending an HTTPS request that contains an array of individual JSON-RPC calls,
* **[using Ethers](/node-rpc/libraries/ethers)**, by instantiating a **`JsonRpcBatchProvider`**,
* **[using Viem](/node-rpc/libraries/viem)**, by configuring the **`batch`** parameter when creating a client via **`createPublicClient`**.

If a particular request fails, the batch request still returns a `200 OK` HTTP status, and the response object corresponding to the failing JSON-RPC call carries the error.

<Note>
  Request batching is supported over `HTTPS` only. There is no batching support over `WSS`. Each request inside a batch is counted and charged individually; see [Node RPC pricing](/node-rpc/pricing).
</Note>

```bash title="batch-call.sh" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl https://mainnet.gateway.tenderly.co/$TENDERLY_NODE_ACCESS_KEY \
-X POST \
-H "Content-Type: application/json" \
-d '[
  {"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []},
  {"jsonrpc": "2.0", "id": 2, "method": "eth_gasPrice", "params": []},
  {"jsonrpc": "2.0", "id": 3, "method": "eth_getBalance", "params": ["0xd8da6bf26964af9d7eed9e03e53415d37aa96045", "latest"]}
]'
```

With Viem, batching is configured at the client level:

```js title="batch-calls.ts" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const client = createPublicClient({
  chain: mainnet,
  transport: http(
    `https://mainnet.gateway.tenderly.co/${process.env.TENDERLY_NODE_ACCESS_KEY}`,
    {
      batch: true,
    }
  ),
});

const [blockNumber, balance, ensName] = await Promise.all([
  client.getBlockNumber(),
  client.getBalance({ address: "0xd2135CfB216b74109775236E36d4b433F1DF507B" }),
  client.getEnsName({ address: "0xd2135CfB216b74109775236E36d4b433F1DF507B" }),
]);
```

## RPC Request Builder

The RPC Request Builder lets you execute any of the supported RPC methods from your browser. Each request is sent directly to Node RPC. The Builder also allows you to use existing collections or create your own requests.

Check out the list of all supported RPC methods in the [RPC reference](/node-rpc/rpc-reference).

<img alt="" />

## Node Extensions

Node Extensions allow you to extend the functionality of Node RPC with custom RPC methods tailored to your dapp, protocol, or specific needs using JavaScript or TypeScript. RPC methods built as Node Extensions have the **`extension_`** prefix and are executed through Node RPC.

<img alt="Node Extensions" />

You can create a Node Extension in several ways from the **Node Extensions** tab in the [Dashboard](https://dashboard.tenderly.co/register?redirectTo=node-extensions):

* **Build from scratch**: click **Create Custom Extension**, name the RPC method, and write the JavaScript/TypeScript function executed on each call.
* **Repurpose a Web3 Action**: reuse the source code of an existing [Web3 Action](/monitoring/web3-actions/introduction) with a non-authenticated webhook trigger as the extension's function.
* **Deploy from the library**: click **Add From Library** to activate a ready-made extension from the [public Node Extensions library](https://github.com/Tenderly/node-extensions-library). Library extensions cannot be edited.
* **Deploy via the CLI**: define extensions in `tenderly.yaml` with `tenderly node-extensions init` and ship them with `tenderly node-extensions deploy` using the [Tenderly CLI](https://github.com/Tenderly/tenderly-cli).

If your extension uses API keys or other sensitive values, store them as [Web3 Action Secrets](/monitoring/web3-actions/references/context#secrets) and read them in code with `await context.secrets.get('API_KEY')`. Use the **Test** button on an extension to send a JSON-RPC payload to it and preview the request and response.

## Resources

Get started with Node RPC or continue learning about how it works with these resources.

<CardGroup>
  <Card title="Simulations & Gas Estimation" href="/node-rpc/guides/simulate-json-rpc">
    Simulate transactions and get exact gas estimates via JSON-RPC.
  </Card>

  <Card title="RPC Reference" href="/node-rpc/rpc-reference">
    See the detailed list of supported RPC methods on Node RPC.
  </Card>

  <Card title="Supported Networks" href="/platform/supported-networks">
    Check out the full list of networks supported on Node RPC.
  </Card>

  <Card title="Pricing" href="/node-rpc/pricing">
    Understand billing based on compute power used to execute RPC methods.
  </Card>
</CardGroup>


# Node RPC Pricing
Source: https://docs.tenderly.co/node-rpc/pricing

Node RPC usage is measured in Tenderly Units (TUs). See the per-method TU cost table and a worked example to estimate your request volume.

[Node RPC](/node-rpc/overview) usage is measured in **Tenderly Units (TUs)** based on the number of requests your dapp makes. Every [RPC method](/node-rpc/rpc-reference) belongs to a category, and each category has a fixed TU cost per request.

<Note>
  Node RPC is available on paid plans only. The Free plan does not include Node RPC access. [Contact our sales team](https://tenderly.co/contact-us) to enable Node RPC for your account.
</Note>

## TU cost per request

| Category           | Cost per request | Example methods                                                                           |
| ------------------ | ---------------- | ----------------------------------------------------------------------------------------- |
| Read               | 1 TU             | `eth_getBalance`, `eth_getTransactionByHash`                                              |
| Compute            | 4 TU             | `eth_call`, `eth_estimateGas`                                                             |
| Write              | 20 TU            | `eth_sendRawTransaction`                                                                  |
| Debug and Trace    | 40 TU            | `debug_traceBlock`, `trace_transaction`                                                   |
| Advanced Compute 1 | 40 TU            | `tenderly_estimateGas`                                                                    |
| Advanced Compute 2 | 400 TU           | `tenderly_simulateTransaction`, `tenderly_traceTransaction`, `tenderly_estimateGasBundle` |

## Calculating your usage

Multiply the number of requests in each category by its TU cost, then add them up. For example, if your dapp makes 1,000 read requests and 100 write requests:

* 1,000 reads × 1 TU = 1,000 TUs
* 100 writes × 20 TUs = 2,000 TUs
* **Total: 3,000 TUs**

<Note>
  To discuss capacity and limits for your account, [contact our sales team](https://tenderly.co/contact-us).
</Note>


# JSON-RPC Reference
Source: https://docs.tenderly.co/node-rpc/rpc-reference

Tenderly JSON-RPC reference: methods, networks, and chain IDs across 75+ EVM chains. Pick a method and network and send the request from this page.

Tenderly Node RPC speaks the standard EVM JSON-RPC plus a `tenderly_` namespace for tracing, simulation, and state manipulation. Pick a method and a network below to see an example request you can send right from this page.

A Node RPC access key from the [Dashboard](https://dashboard.tenderly.co/) is optional: without one, requests go to the public Tenderly RPC endpoint, which is rate-limited. The key stays in your browser only (localStorage).

<div>Loading RPC explorer…</div>

## Supported networks and chain IDs

Tenderly Node RPC is available on the EVM networks below. Each endpoint follows the form `https://<network>.gateway.tenderly.co/<ACCESS_KEY>` (use the `wss://` scheme for WebSockets). Append your Node RPC access key from the [Dashboard](https://dashboard.tenderly.co/).

| Network                  | Chain ID     | HTTPS RPC endpoint                                   |
| ------------------------ | ------------ | ---------------------------------------------------- |
| ApeChain                 | `33139`      | `https://apechain.gateway.tenderly.co`               |
| ApexFusion Nexus Mainnet | `9069`       | `https://af-nexus-mainnet.gateway.tenderly.co`       |
| Arbitrum One             | `42161`      | `https://arbitrum.gateway.tenderly.co`               |
| Avalanche C-Chain        | `43114`      | `https://avalanche.gateway.tenderly.co`              |
| BOB                      | `60808`      | `https://bob.gateway.tenderly.co`                    |
| Base Mainnet             | `8453`       | `https://base.gateway.tenderly.co`                   |
| Berachain                | `80094`      | `https://berachain.gateway.tenderly.co`              |
| Blast                    | `81457`      | `https://blast.gateway.tenderly.co`                  |
| Boba Ethereum            | `288`        | `https://boba-ethereum.gateway.tenderly.co`          |
| Celo Mainnet             | `42220`      | `https://celo.gateway.tenderly.co`                   |
| Conflux eSpace           | `1030`       | `https://cfx-espace.gateway.tenderly.co`             |
| Ethereum Mainnet         | `1`          | `https://mainnet.gateway.tenderly.co`                |
| Flare                    | `14`         | `https://flare.gateway.tenderly.co`                  |
| Fraxtal                  | `252`        | `https://fraxtal.gateway.tenderly.co`                |
| Gnosis Chain             | `100`        | `https://gnosis-chain.gateway.tenderly.co`           |
| Immutable                | `13371`      | `https://immutable.gateway.tenderly.co`              |
| Ink                      | `57073`      | `https://ink.gateway.tenderly.co`                    |
| Interval                 | `1230263917` | `https://interval.gateway.tenderly.co`               |
| Katana                   | `747474`     | `https://katana.gateway.tenderly.co`                 |
| Lens                     | `232`        | `https://lens.gateway.tenderly.co`                   |
| Linea                    | `59144`      | `https://linea.gateway.tenderly.co`                  |
| Lisk                     | `1135`       | `https://lisk.gateway.tenderly.co`                   |
| Mantle                   | `5000`       | `https://mantle.gateway.tenderly.co`                 |
| Mantle Sepolia           | `5003`       | `https://mantle-sepolia.gateway.tenderly.co`         |
| MegaETH                  | `4326`       | `https://megaeth.gateway.tenderly.co`                |
| Metis Andromeda          | `1088`       | `https://metis-andromeda.gateway.tenderly.co`        |
| Monad                    | `143`        | `https://monad.gateway.tenderly.co`                  |
| Optimistic Ethereum      | `10`         | `https://optimism.gateway.tenderly.co`               |
| Plasma                   | `9745`       | `https://plasma.gateway.tenderly.co`                 |
| Polygon                  | `137`        | `https://polygon.gateway.tenderly.co`                |
| Ronin                    | `2020`       | `https://ronin.gateway.tenderly.co`                  |
| Scroll Mainnet           | `534352`     | `https://scroll-mainnet.gateway.tenderly.co`         |
| Soneium                  | `1868`       | `https://soneium.gateway.tenderly.co`                |
| Sonic                    | `146`        | `https://sonic.gateway.tenderly.co`                  |
| Stable                   | `988`        | `https://stable.gateway.tenderly.co`                 |
| Taiko Mainnet            | `167000`     | `https://taiko-mainnet.gateway.tenderly.co`          |
| Unichain                 | `130`        | `https://unichain.gateway.tenderly.co`               |
| World Chain              | `480`        | `https://worldchain-mainnet.gateway.tenderly.co`     |
| X Layer                  | `196`        | `https://xlayer.gateway.tenderly.co`                 |
| ZKsync                   | `324`        | `https://zksync.gateway.tenderly.co`                 |
| ApexFusion Nexus Testnet | `9070`       | `https://af-nexus-testnet.gateway.tenderly.co`       |
| Arbitrum Sepolia         | `421614`     | `https://arbitrum-sepolia.gateway.tenderly.co`       |
| Avalanche C-Chain Fuji   | `43113`      | `https://avalanche-fuji.gateway.tenderly.co`         |
| BOB Testnet              | `808813`     | `https://bob-testnet.gateway.tenderly.co`            |
| Base Sepolia             | `84532`      | `https://base-sepolia.gateway.tenderly.co`           |
| Bepolia                  | `80069`      | `https://bepolia.gateway.tenderly.co`                |
| Boba Sepolia             | `28882`      | `https://boba-sepolia.gateway.tenderly.co`           |
| Celo Sepolia             | `11142220`   | `https://celo-sepolia.gateway.tenderly.co`           |
| Conflux eSpace Testnet   | `71`         | `https://cfx-espace-testnet.gateway.tenderly.co`     |
| Curtis                   | `33111`      | `https://curtis.gateway.tenderly.co`                 |
| Ethereum Hoodi           | `560048`     | `https://hoodi.gateway.tenderly.co`                  |
| Ethereum Sepolia         | `11155111`   | `https://sepolia.gateway.tenderly.co`                |
| Fraxtal Hoodi            | `2523`       | `https://fraxtal-hoodi.gateway.tenderly.co`          |
| Gnosis Chiado Testnet    | `10200`      | `https://gnosis-chiado-testnet.gateway.tenderly.co`  |
| Immutable Testnet        | `13473`      | `https://immutable-testnet.gateway.tenderly.co`      |
| Ink Sepolia              | `763373`     | `https://ink-sepolia.gateway.tenderly.co`            |
| Katana Bokuto            | `737373`     | `https://katana-bokuto.gateway.tenderly.co`          |
| Lens Testnet             | `37111`      | `https://lens-sepolia.gateway.tenderly.co`           |
| Linea Sepolia            | `59141`      | `https://linea-sepolia.gateway.tenderly.co`          |
| Lisk Sepolia             | `4202`       | `https://lisk-sepolia.gateway.tenderly.co`           |
| Metis Sepolia            | `59902`      | `https://metis-sepolia.gateway.tenderly.co`          |
| Monad Testnet            | `10143`      | `https://monad-testnet.gateway.tenderly.co`          |
| Optimistic Sepolia       | `11155420`   | `https://optimism-sepolia.gateway.tenderly.co`       |
| Plasma Testnet           | `9746`       | `https://plasma-testnet.gateway.tenderly.co`         |
| Polygon Amoy             | `80002`      | `https://polygon-amoy.gateway.tenderly.co`           |
| Ronin Testnet            | `202601`     | `https://ronin-testnet.gateway.tenderly.co`          |
| Soneium Minato           | `1946`       | `https://soneium-minato.gateway.tenderly.co`         |
| Sonic Testnet            | `14601`      | `https://sonic-testnet.gateway.tenderly.co`          |
| Stable Testnet           | `2201`       | `https://stable-testnet.gateway.tenderly.co`         |
| Taiko Hoodi              | `167013`     | `https://taiko-hoodi.gateway.tenderly.co`            |
| Tempo Moderato Testnet   | `42431`      | `https://tempo-moderato-testnet.gateway.tenderly.co` |
| Unichain Sepolia         | `1301`       | `https://unichain-sepolia.gateway.tenderly.co`       |
| World Chain Sepolia      | `4801`       | `https://worldchain-sepolia.gateway.tenderly.co`     |
| X Layer Testnet          | `1952`       | `https://xlayer-testnet.gateway.tenderly.co`         |
| ZKsync Sepolia           | `300`        | `https://zksync-sepolia.gateway.tenderly.co`         |

## Supported JSON-RPC methods

**Tenderly extensions (`tenderly_*`)**

`tenderly_decodeError`, `tenderly_decodeEvent`, `tenderly_decodeInput`, `tenderly_errorSignatures`, `tenderly_estimateGas`, `tenderly_estimateGasBundle`, `tenderly_eventSignature`, `tenderly_functionSignatures`, `tenderly_gasPrice`, `tenderly_getContractAbi`, `tenderly_getStorageChanges`, `tenderly_getTransactionsRange`, `tenderly_simulateBundle`, `tenderly_simulateTransaction`, `tenderly_suggestGasFee`, `tenderly_traceTransaction`

**Standard EVM (`eth_*`)**

`eth_accounts`, `eth_blockNumber`, `eth_call`, `eth_chainId`, `eth_coinbase`, `eth_createAccessList`, `eth_estimateGas`, `eth_feeHistory`, `eth_gasPrice`, `eth_getBalance`, `eth_getBlockByHash`, `eth_getBlockByNumber`, `eth_getBlockReceipts`, `eth_getBlockTransactionCountByHash`, `eth_getBlockTransactionCountByNumber`, `eth_getCode`, `eth_getFilterChanges`, `eth_getFilterLogs`, `eth_getLogs`, `eth_getProof`, `eth_getStorageAt`, `eth_getTransactionByBlockHashAndIndex`, `eth_getTransactionByBlockNumberAndIndex`, `eth_getTransactionByHash`, `eth_getTransactionCount`, `eth_getTransactionReceipt`, `eth_getUncleByBlockHashAndIndex`, `eth_getUncleByBlockNumberAndIndex`, `eth_getUncleCountByBlockHash`, `eth_getUncleCountByBlockNumber`, `eth_hashrate`, `eth_maxPriorityFeePerGas`, `eth_mining`, `eth_newBlockFilter`, `eth_newFilter`, `eth_newPendingTransactionFilter`, `eth_protocolVersion`, `eth_sendRawTransaction`, `eth_sendTransaction`, `eth_sign`, `eth_signTransaction`, `eth_simulateV1`, `eth_subscribe`, `eth_syncing`, `eth_uninstallFilter`, `eth_unsubscribe`

**Parity trace (`trace_*`)**

`trace_block`, `trace_call`, `trace_callMany`, `trace_filter`, `trace_get`, `trace_replayBlockTransactions`, `trace_replayTransaction`, `trace_transaction`

**Geth debug (`debug_*`)**

`debug_traceBlock`, `debug_traceBlockByHash`, `debug_traceBlockByNumber`, `debug_traceCall`, `debug_traceTransaction`

**Network (`net_*`)**

`net_listening`, `net_peerCount`, `net_version`

**Web3 (`web3_*`)**

`web3_clientVersion`, `web3_sha3`

For protocol-level method semantics, see the [Ethereum execution APIs spec](https://github.com/ethereum/execution-apis). For per-method request and response examples, use the explorer above or the [Node RPC overview](/node-rpc/overview).


# Add Member
Source: https://docs.tenderly.co/platform/account/organizations/members

Invite team members to a Tenderly organization by email and set granular permissions for projects, members, access tokens, and billing.

Learn how to add new members to an organization and manage their permission levels.

## Add a new member

To add a new member to an organization:

1. On the [Organizations](/platform/account/organizations/overview) page, navigate to **Members**.
2. Click **Add Member**.

<img alt="Organization members list" />

3. Enter the email of the person you want to invite and set their permission level.

<img alt="Add member dialog" />

4. After clicking **Add Member**, an invitation email will be sent to the provided address.

To discuss member capacity for your organization, [contact our sales team](https://tenderly.co/contact-us).

## Member permissions

Member permissions are flexible and can be modified at any time.

Owners and members with the "Manage members" permission enabled can change permission for other members.

The available permissions include:

* **Create projects:** Allows the member to create new projects within the organization.
* **Update projects:** Allows the member to make changes to the organization's projects.
* **Delete projects:** Allows the member to delete any project within the organization.
* **Manage members:** Allows the member to add/delete other members and change their permissions.
* **Manage access tokens:** Allows the member to create, delete, and manage API access tokens.
* **Manage billing:** Allows the member to change/delete the subscription and payment methods.

To change permission levels for a member, go to **Members** and click on the member or the permission options on the right.

<img alt="Member permissions" />


# Organizations and Team Members
Source: https://docs.tenderly.co/platform/account/organizations/overview

Learn how to set up an organization, add team members, and manage permissions.

Organizations enable you to add multiple team members and control their permissions. Each member of an organization will have access to all its projects, depending on the permissions assigned to them. See [Adding members to organizations](/platform/account/organizations/members).

<Note>
  Organizations are available on the paid plan and are set up for your team during onboarding. To get an organization, [contact our sales team](https://tenderly.co/contact-us).
</Note>

## Manage your organization

From the organization page, you can manage projects, add or remove members, manage [Alert Destinations](/monitoring/alerts/destinations/overview), generate access tokens, and more.

<img alt="Organization overview" />

## Manage billing options

Go to **Billing** from the organization page to see your plan and resource usage. To change plans or discuss capacity, [contact our sales team](https://tenderly.co/contact-us).

<img alt="Organization billing" />

<Warning>
  Any organization member with the "Manage billing" permission enabled can change any of the billing settings. Learn more about [member permissions](/platform/account/organizations/members).
</Warning>


# Account Management
Source: https://docs.tenderly.co/platform/account/overview

Learn how to manage your Tenderly account, projects, and team members.

In this section, you'll learn everything you need to manage your Tenderly account, set up projects, get the account and project slugs, and invite team members to your organization.

## Manage projects and organizations

* [Create a project](/platform/account/projects/overview): Learn how to create a Tenderly project.
* [Project settings](/platform/account/projects/settings): Rename, transfer, and delete Tenderly projects.
* [Account slug and project slug](/platform/account/projects/slug): Get the account and project slug for API authentication.
* [API access tokens](/platform/account/projects/api-tokens): Learn how to generate and manage API access tokens.
* [Organizations and team members](/platform/account/organizations/overview): Manage your organization, team members, and their permissions.


# Generate and Manage API Access Tokens
Source: https://docs.tenderly.co/platform/account/projects/api-tokens

Learn how to generate API access tokens for personal accounts and organizations.

Learn how to generate API access tokens for personal accounts and organizations.

<Note>
  Generating API access tokens and using the Tenderly API are available on the paid plan. To enable them for your account, [contact our sales team](https://tenderly.co/contact-us) to schedule a call and discuss upgrading your plan.
</Note>

<Note>
  For security reasons, the token will be displayed only once during the initial creation. Copy your private key and store it in a safe place.
</Note>

## Organization access tokens

Organization access tokens are tied to the organization instead to any specific member. Use organization access tokens to authenticate off-chain services, such as backends and automation scripts. Learn more about [organizations](/platform/account/organizations/overview).

For generating an organization token:

1. In the left sidebar, navigate to the organization and select **Access Tokens**.
2. Click **Generate Access Token**.
3. Enter an **Access Token label**.
4. Click **Generate**.
5. Copy the access token immediately.

<img alt="Organization access tokens" />

<Note>
  Tokens created within an organization are accessible and manageable by members with the required privileges.
</Note>

## Personal account access tokens

Personal tokens allow authentication of individual accounts they're tied to.

To create a token for your personal account:

1. Click on your **profile photo**.
2. Navigate to **Account Settings**.
3. Go to the [**Access Tokens**](https://dashboard.tenderly.co/account/authorization) tab.
4. Click **Generate Access Token** to create a new token.

<img alt="Personal access tokens" />


# Create a Tenderly Project
Source: https://docs.tenderly.co/platform/account/projects/overview

Create a Tenderly project to organize work into separate spaces, switch between projects, and set a permanent project slug.

Projects help you organize your work into separate spaces.

When you first create a Tenderly account, you'll be prompted to create a project. To see all of your projects later, open the project switcher in the top breadcrumb, next to your organization name.

<img alt="Project switcher" />

To create a new project, click **Create project** at the bottom of the switcher.

Give your project a unique name and click **Create Project**. The project URL preview updates as you type.

<img alt="Create project dialog" />

<Warning>
  Once the project is created, you cannot change the [project slug](/platform/account/projects/slug).
</Warning>

If you're part of an [**Organization**](/platform/account/organizations/overview), you'll be able to access all projects that belong to that organization, and they'll appear in the same switcher.


# Project Settings
Source: https://docs.tenderly.co/platform/account/projects/settings

Change your project name, generate API access tokens, transfer project ownership, or delete a project from the Tenderly project Settings tab.

From the left-hand sidebar, go to **Settings** where you can:

* [Change the project name](/platform/account/projects/settings#change-project-name)
* [Find account & project slugs](/platform/account/projects/slug)
* [Generate API access token](/platform/account/projects/settings#generate-api-access-token)
* [Transfer project ownership](/platform/account/projects/settings#transfer-project-ownership)
* [Delete the project](/platform/account/projects/settings#delete-project)

<img alt="Project Settings" />

## Change project name

The project name can be changed at any time. Changing the project name will not change the project slug.

**The project slug cannot be changed** after the project has been created.

When you update the project name, click **Save** to save the changes.

<img alt="Change project name" />

## Generate API access token

<Note>
  Generating API access tokens and using the Tenderly API are available on the paid plan. To enable them for your account, [contact our sales team](https://tenderly.co/contact-us) to schedule a call and discuss upgrading your plan.
</Note>

Access the Tenderly API conveniently through the Project Settings page, where you can copy the API URL and generate API access tokens.

<img alt="API URL and access token" />

To create a new token, click **Generate Access Token** to authenticate access to the Tenderly API.

After giving a name to the token, click **Generate**. Remember, the token is displayed only once. Ensure to copy it immediately after it appears.

<img alt="Generated access token" />

To manage existing tokens, visit your **Account Settings** and select [**Access Tokens**](https://dashboard.tenderly.co/account/authorization) to view or delete your access tokens.

<img alt="Access tokens list" />

## Transfer project ownership

Under **Project Actions**, click on **Transfer Project** to transfer ownership of a project to another Tenderly user. Type in the username of the new owner. Tenderly will automatically find the username if it exists.

<Note>
  Transfer will succeed unless the recipient already has a project with the same slug. In this case [contact our support team](https://tenderly.co/contact-us) for help transferring your project.
</Note>

<img alt="Transfer project dialog" />

Toggle **Transfer Deliver Channels** ON if you also want to transfer all [Alert Destinations](/monitoring/alerts/destinations/overview) you've created within the project.

Click **Transfer** to complete the process.

## Delete project

Under **Project Actions**, click on **Delete Project** if you want to permanently delete the project from your account along with all the data associated with it.

<Warning>
  This action cannot be undone.
</Warning>

<img alt="Delete project dialog" />


# Project Slug and Account Slug
Source: https://docs.tenderly.co/platform/account/projects/slug

Find your Tenderly project slug and account slug in the dashboard for use in the CLI, API calls, and tenderly.yaml configuration files.

The account and project slugs are essential for doing anything with the Tenderly API. These slugs are an integral part of your unique API URL.

Find your account and project slugs by navigating to **Settings** from the left-hand menu. The slugs are located under the **Integration** section.

Click on the input fields to copy the account (**`TENDERLY_ACCOUNT`**) and project (**`TENDERLY_PROJECT`**) slugs.

<img alt="Account and project slugs" />

From the **Settings** page, copy your unique API URL which includes your account and project slugs.

```bash title="API URL" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
https://api.tenderly.co/api/v1/account/${TENDERLY_ACCOUNT}/project/${TENDERLY_PROJECT}/
```


# Supported Networks
Source: https://docs.tenderly.co/platform/supported-networks

All EVM-compatible networks supported by Tenderly's dev tools, Monitor, Virtual Environments, and Node RPC.

Tenderly offers its tools and infrastructure across <span>95</span>+ networks. Some networks additionally have Node RPC support.

To connect to a network, you can:

* Use the public RPC listed in the table, or
* Go to the [Tenderly Dashboard](https://dashboard.tenderly.co/) and get a dedicated Node RPC.

You can check which products from the Tenderly suite are supported on each network in the table below, or by executing an [API call](/api-reference).

<Note>
  Public RPC endpoints are rate-limited. For production use, get a dedicated Node RPC from the [Dashboard](https://dashboard.tenderly.co?redirectTo=nodes).
</Note>

<div>Loading supported networks…</div>


# Check supported networks
Source: https://docs.tenderly.co/api-reference/other/check-supported-networks

/api-reference/openapi.json get /v1/supported-networks
The endpoint returns the list of networks that are currently supported on the Tenderly platform and also returns information about features these networks are supported on as well as corresponding network slugs users can use for integration with Tenderly.



# Add wallet to project
Source: https://docs.tenderly.co/api-reference/wallets/add-wallet-to-project

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/wallet
This endpoint allows you to add a wallet address to your Tenderly project.



# Changelog
Source: https://docs.tenderly.co/changelog/overview

Product updates, new features, and fixes across Virtual Environments, Simulator, DeFi Modules, Node RPC, and the Tenderly Console.

The latest product updates, features, and fixes. For deeper announcements, see the [Tenderly blog](https://blog.tenderly.co).

<Update label="June 9, 2026">
  ## New

  **Multichain Virtual Environments now span 100+ EVM networks.** A single Virtual Environment can attach Ethereum, Arbitrum, Optimism, Base, and any of 100+ supported EVM networks under one shared identity, with a unified cross-chain timeline. See [Multichain Virtual Environments](/virtual-environments/multichain/overview).

  **Multichain contract deployment.** Deploy and test contracts across multiple chains simultaneously from one Virtual Environment, useful for cross-chain protocol testing, CI/CD pipelines, and staging environments without real funds. See [common uses](/virtual-environments/multichain/overview#common-uses).

  ## Updates

  **Simpler Bridge Module setup.** Enable the Bridge Module from the Virtual Environment **Settings** page under the **Advanced** panel, with no separate Bridge settings tab required. Relay covers LayerZero, Chainlink CCIP, Across, and CCTP on supported networks. See [Bridges](/virtual-environments/multichain/bridges).

  **Network Mirror Mode transaction list: no row cap.** Browse the full transaction history of a Mirror-Mode Virtual Environment without a 100-row limit. See [Network Mirror Mode](/virtual-environments/network-mirror-mode).
</Update>


# FAQ: Account
Source: https://docs.tenderly.co/troubleshooting/account

Delete an account, transfer organization ownership, update your email, add members, or create access tokens for your Tenderly account.

<div>
  <Card>
    <div>
      <h2>Can I delete my account/organization on Tenderly?</h2>

      <hr />

      <div>
        To delete your account or organization, please contact our support team at [support@tenderly.co](mailto:support@tenderly.co). In the email,
        please provide a reason for deactivating your account.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I switch the ownership of my organization?</h2>

      <hr />

      <div>
        To switch the ownership of your organization, please contact our support team at [support@tenderly.co](mailto:support@tenderly.co). Please
        note that the new owner must be a member of your organization on Tenderly.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I change my username/organization slug?</h2>

      <hr />

      <div>
        The username or organization slug cannot be changed since they’re deeply embedded in the system.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I update my account’s email address?</h2>

      <hr />

      <div>
        To change your email address, please contact our support team at [support@tenderly.co](mailto:support@tenderly.co).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>
        How can I add a new member to my organization or remove an existing member? How can I set privileges for a
        specific member?
      </h2>

      <hr />

      <div>
        To add a new team member to your organization or remove an existing one, navigate to the Organizations/Members
        page in the top right corner of the Dashboard.

        Here is an example URL to the page:

        ```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        https://dashboard.tenderly.co/organization/ORG_SLUG/members
        ```
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>A verification email was sent, but I never received it.</h2>

      <hr />

      <div>
        Please check your spam folder. If there’s no email in your spam folder, contact our support team for assistance
        at [support@tenderly.co](mailto:support@tenderly.co).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I get access tokens?</h2>

      <hr />

      <div>
        You can create access tokens at organization level, or at the level of your account. Follow this guide to learn how to [create access tokens](/platform/account/projects/api-tokens).
      </div>
    </div>
  </Card>
</div>


# FAQ: Alerts
Source: https://docs.tenderly.co/troubleshooting/alerts

Troubleshoot Tenderly Alerts: verify destinations, configure alert types and triggers, set up webhooks, and monitor transactions, events, and balances.

<div>
  <Card>
    <div>
      <h2>Do I need a paid plan to use Alerts?</h2>

      <hr />

      <div>
        Yes. Alerts are available on the paid plan. To enable them for your account, [contact our sales team](https://tenderly.co/contact-us) to schedule a call and discuss upgrading your plan.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>I've been trying to verify my email as a destination for Alerts/Web3 Actions but every time I click the link in my email, it shows up as an invalid verification code.</h2>

      <hr />

      <div>
        Try opening the verification link in a new browser tab where you’re already logged into the Dashboard. If this
        doesn’t work, please contact our support team at [support@tenderly.co](mailto:support@tenderly.co).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>If we get back a non 2xx response from a webhook as a destination for one of our alerts, will our alerts try to hit it again?</h2>

      <hr />

      <div>
        Yes. Webhook deliveries have a retry mechanism: an event is delivered in at most five total attempts before it's marked as failed.
        Learn more about using [webhooks as an Alert destination here](/monitoring/alerts/tutorials/webhooks).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How does tag target alert work?</h2>

      <hr />

      <div>
        When you use **tag** as alert target, then all contracts you've tagged with the selected tag will be monitored by the alert. You can tag contracts in **Dashboard > Contracts** or on individual contracts page.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Does the event emitted type of alert work with an unverified contracts?</h2>

      <hr />

      <div>
        Setting up an Even Emitted Alert type is possible only for contracts that are verified through **ABI verification** or **source code verification**.
        Learn more about [contract verification on Tenderly here](/contract-verification/overview).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Why aren’t all events visible when I create an event emitted alert type on a proxy contract?</h2>

      <hr />

      <div>
        If you want to create an event or function [alert type](/monitoring/alerts/types) on a proxy contract, both the proxy
        and its implementation have to be added to your project in order for all events to be visible.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do notifications work for the balance change alert type?</h2>

      <hr />

      <div>
        <h3>
          Will an alert be triggered if an account has 0.51 Ether and it sends a transaction to a smart contract, paying
          a transaction fee of 0.02 to the validators (the new balance is 0.49 ETH)?
        </h3>

        Yes, the alert will be triggered when the balance drops below 0.5 ETH.

        <br />

        <h3>
          Will an alert be triggered if an account already has less than 0.5 Ether? For example, if an account has 0.1
          Ether and receives an additional 0.1 from another account (the new balance is 0.2 ETH)?
        </h3>

        No, the alert won’t get triggered if the balance continues to decrease. However, if the balance goes above 0.5
        Ether and then drops below this threshold, the alert will be triggered.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What are Tenderly Alerts?</h2>

      <hr />

      <div>
        Tenderly Alerts notify you of on-chain events, such as successful or failed transactions, contract function calls, and token transfers, through various destinations like email, Slack, or webhooks.

        [Learn more →](/monitoring/alerts/introduction)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I set up an Alert in Tenderly?</h2>

      <hr />

      <div>
        To set up an Alert, define the alert type (e.g., transaction), the target address or contract, and the notification destination (e.g., email, webhook).

        [Learn more →](/monitoring/alerts/tutorials/quickstart)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What are the trigger types for Alerts?</h2>

      <hr />

      <div>
        Alerts can be triggered by successful or failed transactions, function calls, state changes, ERC20 token transfers, balance changes, and more.

        [Learn more →](/monitoring/alerts/types)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What are the available Alert destinations?</h2>

      <hr />

      <div>
        Alerts can be sent to email, Slack, Telegram, Discord, PagerDuty, Sentry, or webhooks.

        [Learn more →](/monitoring/alerts/destinations/overview)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is a successful transaction Alert?</h2>

      <hr />

      <div>
        This Alert triggers when a specified transaction is successfully executed, notifying you of wallet, dapp, or contract activity.

        [Learn more →](/monitoring/alerts/types#successful-transaction)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I use webhooks for Alerts?</h2>

      <hr />

      <div>
        Webhooks can be set as destinations to send real-time notifications of on-chain events to external services or applications.

        [Learn more →](/monitoring/alerts/tutorials/webhooks)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is an Event Emitted Alert?</h2>

      <hr />

      <div>
        This Alert triggers when a specified contract emits a particular event, such as token approvals or transfers.

        [Learn more →](/monitoring/alerts/types#event-emitted)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is the difference between project-scoped and account-scoped Alerts?</h2>

      <hr />

      <div>
        Project-scoped Alerts notify you of events within a specific project, while account-scoped Alerts monitor events across all projects in an account.

        [Learn more →](/monitoring/alerts/destinations/project-scoped)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is a Failed Transaction Alert?</h2>

      <hr />

      <div>
        This Alert notifies you when a transaction fails, which can help detect issues in a dapp or smart contract.

        [Learn more →](/monitoring/alerts/types#failed-transaction)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is a Blocklisted Callers Alert?</h2>

      <hr />

      <div>
        This Alert triggers when an address from a blocklist interacts with your contract, helping to monitor unauthorized access attempts.

        [Learn more →](/monitoring/alerts/types#blocklisted-callers)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I use Tenderly Alerts for security monitoring?</h2>

      <hr />

      <div>
        Yes, Alerts can help detect suspicious behavior like unauthorized access or unusual token transfers, aiding in early threat detection.

        [Learn more →](/monitoring/alerts/introduction)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is a Balance Change Alert?</h2>

      <hr />

      <div>
        This Alert notifies you when a wallet’s balance changes according to specified conditions, useful for monitoring DAOs or key wallets.

        [Learn more →](/monitoring/alerts/types#balance-change)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I monitor token transfers with Alerts?</h2>

      <hr />

      <div>
        The ERC20 Token Transfer Alert triggers when tokens are transferred, helping track fund movements or suspicious wallet activities.

        [Learn more →](/monitoring/alerts/types#erc20-token-transfer)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is a Function Call Alert?</h2>

      <hr />

      <div>
        This Alert triggers when a specific function in a smart contract is called, helping to monitor contract interactions. The Alert will trigger in case of `public` or `external` function is invoked anywhere in the call trace.

        [Learn more →](/monitoring/alerts/types#function-call)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is a View Function Alert?</h2>

      <hr />

      <div>
        This Alert monitors when a view function’s return value meets specified conditions, such as checking token balances.

        [Learn more →](/monitoring/alerts/types#view-function)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I monitor transaction values with Alerts?</h2>

      <hr />

      <div>
        The Transaction Value Alert notifies you when a transaction’s value exceeds a certain amount, ideal for monitoring high-value transfers.

        [Learn more →](/monitoring/alerts/types#transaction-value)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I detect state changes with Alerts?</h2>

      <hr />

      <div>
        The State Change Alert triggers when a state variable in a contract changes, such as monitoring the number of confirmations in a multisig.

        [Learn more →](/monitoring/alerts/types#state-change)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can Alerts be used for automated processes?</h2>

      <hr />

      <div>
        Alerts can trigger Web3 Actions, enabling automated responses to on-chain events, such as executing custom code when a transaction fails.

        [Learn more →](/monitoring/alerts/introduction)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is an Allowlisted Callers Alert?</h2>

      <hr />

      <div>
        This Alert notifies you when an address not on the allowlist interacts with your contract, useful for monitoring restricted access.

        [Learn more →](/monitoring/alerts/types#allowlisted-callers)
      </div>
    </div>
  </Card>
</div>


# FAQ: API
Source: https://docs.tenderly.co/troubleshooting/api

Generate an organization API access token and fetch the latest block number through the Tenderly API, with a pointer to the Simulation API.

<div>
  <Card>
    <div>
      <h2>Do I need a paid plan to use the Tenderly API?</h2>

      <hr />

      <div>
        Yes. Generating API access tokens and using the Tenderly API are available on the paid plan. To enable them for your account, [contact our sales team](https://tenderly.co/contact-us) to schedule a call and discuss upgrading your plan.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>
        How can I generate an API access token for an organization?
      </h2>

      <hr />

      <div>
        To generate an [access token](/platform/account/projects/api-tokens), head over to the Organizations page in the Tenderly Dashboard.

        Once you open the page, click on your organization and go to the Access Tokens tab. Next, click the **New Access
        Token** button, add a token label, and click **Generate**.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>
        How can I fetch the latest block via API?
      </h2>

      <hr />

      <div>
        You can use the following API endpoint to fetch the latest block number. For programmatic transaction simulation, see the [Simulation API](/simulations/quickstart):

        ```bash title="example" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        GET https://api.tenderly.co/api/v1/network/{network-id}/block-number
        ```
      </div>
    </div>
  </Card>
</div>


# FAQ: Billing
Source: https://docs.tenderly.co/troubleshooting/billing

Find your billing page, change plans, download invoices, and pay in USDT or USDC on Ethereum for your Tenderly account or organization.

<div>
  <Card>
    <div>
      <h2>Where can I see my plan and usage?</h2>

      <hr />

      <div>
        Go to the [Billing page](https://dashboard.tenderly.co/account/billing) in the Dashboard.

        * **Personal accounts**: upper-left corner → **Your Name** → [**Account**](/platform/account/overview) → **Billing**.
        * **Organizations**: upper-left corner → [**Organization name**](/platform/account/organizations/overview) → **Billing**.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I change my plan?</h2>

      <hr />

      <div>
        To upgrade, downgrade, or discuss custom plans, [contact our sales team](https://tenderly.co/contact-us).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Where can I download my invoices?</h2>

      <hr />

      <div>
        Invoices aren't downloadable from the Dashboard directly. Please contact our support team at [support@tenderly.co](mailto:support@tenderly.co).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I pay in cryptocurrency?</h2>

      <hr />

      <div>
        Yes, we accept **USDT** and **USDC** on Ethereum. Local legal requirements for crypto payments mean we need to generate an invoice first. We need:

        * Your first and last name or company name
        * Legal address
        * Registration number / VAT number (for companies)
        * The plan you'd like

        Once you provide this, a team member will email you an invoice with payment instructions. Your subscription activates once payment is confirmed.

        <Warning>
          Crypto payments are only available for yearly payment plans.
        </Warning>
      </div>
    </div>
  </Card>
</div>


# FAQ: Contract Verification
Source: https://docs.tenderly.co/troubleshooting/contract-verification

Privately verify contracts on public networks with Hardhat or Foundry, revert public verification, and verify proxies and hardhat-ignition deployments.

<div>
  <Card>
    <div>
      <h2>I verified my contract publicly but want it to be private. Can I remove the public verification of the contract?</h2>

      <hr />

      <div>
        To revert your contract back to private and visible only within your project, [contact our support team](https://tenderly.co/contact-us) or email [support@tenderly.co](mailto:support@tenderly.co). Make sure to provide your username, project, and contract address. Our team will then delete the public verification for the specified contract.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I privately verify contracts from public networks (Mainnet, Holesky, etc.) in Tenderly?</h2>

      <hr />

      <div>
        Private verification means that contracts will be visible only to Tenderly users who have access to your project.

        * When verifying with hardhat, it's necessary to [set the `config.tenderly.private` flag](/contract-verification/hardhat#configure) in `hardhat.config.ts` . Contracts will be verified publicly unless you specify this flag.
        * When verifying with Foundry, the [Verifier URL](/contract-verification/foundry#verifier-url) should end with **`/public`**:
          ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
          ## private verification URL
          https://api.tenderly.co/api/v1/account/me/project/project/etherscan/verify/network/8253

          ## public verification URL
          https://api.tenderly.co/api/v1/account/me/project/project/etherscan/verify/network/8253/public
          ```
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>If I publicly verify a contract on Tenderly, will it still be visible after I delete it from my contracts?</h2>

      <hr />

      <div>
        Yes, publicly verified contracts remain visible even after you delete them from your list of contracts. To
        ensure your contracts are visible only within your project, you can use private verification instead. Learn more
        about [different verification types and the verification
        process](/contract-verification/overview).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I verify contracts with hardhat-ignition?</h2>

      <hr />

      <div>
        Deploy using `hardhat ignition deploy` and be sure to add **`--deployment-id`** with a specific value when running the command.

        ```bash lines={4} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        TENDERLY_AUTOMATIC_VERIFICATION=true \
        npx hardhat ignition deploy ./ignition/modules/Lock.ts \
            --network virtual_base \
            --deployment-id deploy-to-virtual-base
        ```
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I verify contracts automatically with harhdat-tenderly plugin?</h2>

      <hr />

      <div>
        * **For versions `>= 2.4.0 and >=1.10.0`**, the plugin recognizes the environment variable **`TENDERLY_AUTOMATIC_VERIFICATION`**. Use it to switch automatic verification on or off.
          Example:

          ```bash filename="bash.sh" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
          TENDERLY_AUTOMATIC_VERIFICATION=true npx hardhat deploy
          ```

          * **For versions `< 2.4.0 and < 1.10.0`**, you must call `tenderly.setup` in `hardhat.config.ts` in the following way to control automatic verification.

            ```js filename="hardhat.config.js" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
            tenderly.setup({ automaticVerifications: !!process.env.TENDERLY_AUTOMATIC_VERIFICATION })
            ```
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Do I need to call tenderly.setup() in hardhat.config.ts?</h2>

      <hr />

      <div>
        Starting from 2.4.0 and 1.10.0, you don't need to call `tenderly.setup` method.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How should I name networks in hardhat.config.ts?</h2>

      <hr />

      <div>
        * Public networks can have any name.

          For Virtual Environments, depending on the version of `@tenderly/hardhat-tenderly`:

          * network name **must be `tenderly`** with **versions `< 2.4.0` and `< 1.10.0`**.
          * network name can be arbitrary, with **versions `>= 2.4.0` and `>= 1.10.0`**.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I verify proxy contracts in Hardhat?</h2>

      <hr />

      <div>
        * Automatic verification of proxy contracts works out of the box with **versions `>= 2.1.0` and `>= 1.10.0`**.

          * For versions **versions `< 2.4.0` and `< 1.10.0`**, follow the [automatic proxy verification workaround](/contract-verification/hardhat-proxy).
          * To avoid the workaround:

          ```bash filename="upgrade.sh" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
          npm update @tenderly/hardhat-tenderly
          ```
      </div>
    </div>
  </Card>
</div>


# FAQ: Node
Source: https://docs.tenderly.co/troubleshooting/node

Find or reset your Node RPC access key and learn why tenderly_estimateGas returns 100% gas-accurate estimations across supported networks.

<div>
  <Card>
    <div>
      <h2>Do I need a paid plan to use Node RPC?</h2>

      <hr />

      <div>
        Yes. Node RPC is available on the paid plan. To enable it for your account, [contact our sales team](https://tenderly.co/contact-us) to schedule a call and discuss upgrading your plan.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Where can I find the Node RPC access key?</h2>

      <hr />

      <div>
        To find your [Node RPC](/node-rpc/overview) access key, open the [Tenderly
        Dashboard](https://dashboard.tenderly.co/?redirectTo=gateways) and navigate to the Node tab in the navigation
        menu. Your access key is at the top of the page.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I change the Node RPC access key?</h2>

      <hr />

      <div>
        Yes, you can change your node access key. In the [Tenderly
        Dashboard](https://dashboard.tenderly.co/?redirectTo=gateways), head over to the Node tab in the navigation
        menu. Your access key is at the top of the page. Click “...” and then **Reset Access Key**.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How does tenderly\_estimateGas provide 100% accurate estimations?</h2>

      <hr />

      <div>
        The `tenderly_estimateGas` [RPC method](/node-rpc/rpc-reference) ensures accuracy by providing enough `gas` so no internal calls fail.
        The `eth_estimateGas` might underestimate the gas in case of reverts due to insufficient `gas` provided to the transaction.
      </div>
    </div>
  </Card>
</div>


# Tenderly FAQ
Source: https://docs.tenderly.co/troubleshooting/overview

Get answers to the most frequently asked questions about Tenderly products, billing, simulations, Virtual Environments, Node RPC, Alerts, and Web3 Actions.

Browse the FAQ by topic.

<CardGroup>
  <Card title="Account" icon="user" href="/troubleshooting/account">
    Deleting accounts, organization ownership, slugs, email, members, access tokens.
  </Card>

  <Card title="Projects" icon="folder" href="/troubleshooting/projects">
    Creating, sharing, and managing Tenderly projects.
  </Card>

  <Card title="Billing" icon="credit-card" href="/troubleshooting/billing">
    Invoices, payment methods, subscription changes, and refunds.
  </Card>

  <Card title="API" icon="code" href="/troubleshooting/api">
    Authentication, rate limits, and common API gotchas.
  </Card>

  <Card title="Virtual Environments" icon="flask" href="/troubleshooting/virtual-environments">
    Forks, faucet, state sync, and Virtual Environment limits.
  </Card>

  <Card title="Node RPC" icon="cloud" href="/troubleshooting/node">
    Access keys, network coverage, websockets, and request errors.
  </Card>

  <Card title="Simulations" icon="play" href="/troubleshooting/simulations">
    Simulation API behaviour, gas estimation, state overrides, and bundles.
  </Card>

  <Card title="Alerts" icon="bell" href="/troubleshooting/alerts">
    Alert types, destinations, and why an alert didn't fire.
  </Card>

  <Card title="Web3 Actions" icon="bolt" href="/troubleshooting/web3-actions">
    Triggers, execution limits, secrets, and deploy issues.
  </Card>

  <Card title="Contract Verification" icon="badge-check" href="/troubleshooting/contract-verification">
    Source verification, proxies, and Hardhat/Foundry plugins.
  </Card>
</CardGroup>


# FAQ: Projects
Source: https://docs.tenderly.co/troubleshooting/projects

Make a project public, delete or rename it, transfer it between a personal account and an organization, and understand why the project slug is fixed.

<div>
  <Card>
    <div>
      <h2>
        How can I make my project accessible to non-Tenderly users?
      </h2>

      <hr />

      <div>
        To make your project public, please contact our support team at [support@tenderly.co](mailto:support@tenderly.co).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>
        How can I delete a project?
      </h2>

      <hr />

      <div>
        To delete your project, open it in the Dashboard and navigate to the [Settings tab](/platform/account/projects/settings) in the navigation menu. Click
        the Delete Project button.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>
        I want to transfer my project from my personal account to my organization. Is that possible?
      </h2>

      <hr />

      <div>
        To achieve this, open your project in the Tenderly Dashboard. Next, navigate to the Settings tab in the
        navigation menu. Once you open Settings, click the Transfer Project button.

        If you wish to transfer your project from your organization to a personal account, follow the same steps.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>
        Can I rename my project?
      </h2>

      <hr />

      <div>
        Yes, you can change the name of your project in the Settings tab. However, please note that the [project slug](/platform/account/projects/slug)
        will remain the same.
      </div>
    </div>
  </Card>
</div>


# FAQ: Simulations
Source: https://docs.tenderly.co/troubleshooting/simulations

Answers to common questions about Tenderly simulations: dashboard visibility, API vs. RPC, state overrides, gas estimation, and rate limits.

<div>
  <Card>
    <div>
      <h2>Can I see simulations in Dashboard?</h2>

      <hr />

      <div>
        Dashboard shows simulations you've done via the Simulator UI, Simulation API (with `save` or `save_if_fails` set to `true`). RPC simulations do not get persisted and are not shown in the dashboard.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I delete a simulation?</h2>

      <hr />

      <div>
        No, simulations cannot be deleted. Feel free to contact support at [support@tenderly.co](mailto:support@tenderly.co) should you have
        additional questions.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Does running the same simulation multiple times cost the same as running it once?</h2>

      <hr />

      <div>
        No - each API call to the simulate endpoint is counted as a separate request, even if you're sending identical payloads to simulate the exact same transaction multiple times.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I advance a block number/timestamp in a simulation?</h2>

      <hr />

      <div>
        Yes, you can advance the block number or timestamp in a simulation using the [Increase block](/simulator-ui/parameters#increase-block) and [Override timestamp](/simulator-ui/parameters#override-timestamp) cheatcodes.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I simulate transactions on behalf of a user without their private key? In other words, can I simulate transactions originating from arbitrary addresses?</h2>

      <hr />

      <div>
        In simulations, all addresses are unlocked by default. This means you can simulate transactions from any address
        to any address.

        Learn more about [how to use Transaction Simulator during development and testing
        here](/simulations/quickstart).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is the difference between API and RPC simulations?</h2>

      <hr />

      <div>
        API simulations are made via the [Simulation API](/api-reference#/operations/simulateTransaction) endpoint, while RPC simulations are made via the [**`tenderly_simulateTransaction`**](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction) RPC method.

        API simulations can be saved to the Dashboard by setting `save` or `save_if_fails` to `true`. RPC simulations are not saved to the Dashboard.

        Both API and RPC simulations provide the same simulation results, including transaction details, call traces, logs, and balance changes.
        Yes, you can use state overrides to modify contract storage variables, account balances, and other on-chain data for the simulation.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Which rate limits are applied for API simulations?</h2>

      <hr />

      <div>
        API simulations are subject to rate limits. To discuss rate limits or request higher quotas for your account, [contact our sales team](https://tenderly.co/contact-us).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is the correct format of a tuple when simulating a transaction via the Dashboard?</h2>

      <hr />

      <div>
        The format for tuples is JSON. Here’s an example of a tuple:

        ```json filename="example.json" showLineNumbers theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        {
          "tokenIn": "0x3Df2f692132f55b97cc9DA04A1fFFEA82F511333",
          "tokenOut": "0x31254874432f55b97cc9DA04A1fFFEA82F5d7122",
          "fee": 100,
          "recipient": "0x3D555552132f55b97cc9DA04A1fFFEA82F5d7122",
          "deadline": 1630403200,
          "amountIn": 10000,
          "amountOutMinimum": 9000,
          "sqrtPriceLimitX96": 7894561250
        }
        ```
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I test the effects of a token transfer before deploying my smart contract?</h2>

      <hr />

      <div>
        [//]: # "/simulations/single-simulations"

        You can simulate token transfers by running a single simulation with the Simulation API. This will allow you to verify how tokens move between addresses and ensure the contract logic is correct before deploying.

        [Learn more →](/simulations/single-simulations)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I integrate Tenderly simulations into the UI for previewing transaction outcomes for users?</h2>

      <hr />

      <div>
        [//]: # "/simulations/overview"

        You can integrate Tenderly’s [Simulation API](/simulations/overview) or [Simulation RPC](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction) into your dApp UI by calling the API to simulate transactions and display the resulting state changes, asset movements, and gas estimates to users before they confirm transactions.

        [Learn more →](/simulations/overview)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I simulate contract interactions that involve multiple external smart contracts?</h2>

      <hr />

      <div>
        [//]: # "/simulations/bundled-simulations"

        Yes, bundled simulations allow you to test multiple contract interactions in one simulation. The state is updated after each transaction, allowing you to verify complex contract interactions.

        You can also simulate bundles of transaction using [**`tenderly_simulateBundle` RPC**](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateBundle)

        [Learn more →](/simulations/bundled-simulations)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How does the simulation API handle reverts in smart contract calls?</h2>

      <hr />

      <div>
        [//]: # "/simulations/single-simulations"

        When a transaction reverts during a simulation, the API provides detailed error messages to help debug the cause of the revert. This can be used to correct the logic before broadcasting the transaction.

        [Learn more →](/simulations/single-simulations)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I display detailed balance changes to users after a simulated transaction?</h2>

      <hr />

      <div>
        [//]: # "/simulations/asset-balance-changes"

        The Tenderly Simulation API returns asset balance changes as part of the simulation result. You can use this data to show users how their token balances will change after the transaction.

        [Learn more →](/simulations/asset-balance-changes)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I estimate the gas required for contract functions using the simulation API?</h2>

      <hr />

      <div>
        [//]: # "/simulations/gas-estimation"

        Yes, the gas estimation feature in Tenderly allows you to simulate contract functions and get an accurate gas estimate before the transaction is executed. This helps ensure the transaction will succeed and minimizes gas costs.

        Besides Simulation API, you can use [**`tenderly_estimateGas`**](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_estimateGas) and [**`tenderly_estimateGasBundle`**](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_estimateGasBundle).

        [Learn more →](/simulations/gas-estimation)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is the difference between gas and gasUsed?</h2>

      <hr />

      <div>
        Gas is the maximum gas limit allocated for the transaction (the "budget"), while gasUsed shows the actual gas consumed during execution.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do bundled simulations help in testing complex workflows with multiple contract calls?</h2>

      <hr />

      <div>
        [//]: # "/simulations/bundled-simulations"

        Bundled simulations allow you to simulate multiple transactions in sequence, preserving the state from one transaction to the next. This is useful for testing complex workflows, such as multi-contract interactions or dApp user flows.

        [Learn more →](/simulations/bundled-simulations)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I handle simulation failures and errors in the dApp UI?</h2>

      <hr />

      <div>
        [//]: # "/simulations/quickstart"

        When a simulation fails, the Tenderly API provides detailed error messages. You can use these messages to display meaningful error feedback to users in the dApp UI, helping them correct their transaction before retrying.

        [Learn more →](/simulations/quickstart)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I trigger simulations programmatically from the backend to verify transaction success before execution?</h2>

      <hr />

      <div>
        [//]: # "/simulations/quickstart"

        You can trigger simulations programmatically by making a POST request to the [**`/simulate`** REST API](/api-reference#/operations/simulateTransaction) endpoint or [**`tenderly_simulateTransaction`** RPC](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_simulateTransaction), passing transaction details. This helps verify the success of a transaction in a controlled environment before it’s sent to the network.

        [Learn more →](/simulations/quickstart)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I modify storage variables during a simulation to test different scenarios?</h2>

      <hr />

      <div>
        [//]: # "/simulations/state-overrides"

        Yes, you can use state overrides to modify contract storage variables, account balances, and other on-chain data for the simulation.

        [Learn more →](/simulations/state-overrides)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I create a UI that shows gas estimates for user transactions using the Tenderly API?</h2>

      <hr />

      <div>
        [//]: # "/simulations/gas-estimation"

        Yes, you can integrate the gas estimation feature of Tenderly's API into your UI to show users the estimated gas cost for their transactions before they confirm.

        Alternatively, you can use [**`tenderly_estimateGas`**](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_estimateGas) and [**`tenderly_estimateGasBundle`**](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_estimateGasBundle).

        [Learn more →](/simulations/gas-estimation)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I simulate calls from different wallets to my contract to test multi-user scenarios?</h2>

      <hr />

      <div>
        [//]: # "/simulations/single-simulations"

        You can simulate transactions from multiple wallets by running individual simulations with different `from` addresses. This allows you to test how your contract behaves in multi-user scenarios.

        [Learn more →](/simulations/single-simulations)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I simulate invalid or out-of-bound inputs to verify contract resilience in various edge cases?</h2>

      <hr />

      <div>
        [//]: # "/simulations/single-simulations"

        You can simulate function calls with invalid or out-of-bound inputs by setting custom input values in your simulation requests. This allows you to test how your contract handles edge cases and prevents potential vulnerabilities.

        [Learn more →](/simulations/single-simulations)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I simulate flash loan attacks or multi-contract interaction vulnerabilities?</h2>

      <hr />

      <div>
        [//]: # "/simulations/bundled-simulations"

        Yes, you can simulate complex transactions such as flash loan attacks or interactions across multiple contracts by bundling the transactions in one simulation. This is helpful in testing for vulnerabilities in DeFi protocols.

        [Learn more →](/simulations/bundled-simulations)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I simulate cross-contract interactions and ensure transaction flow correctness?</h2>

      <hr />

      <div>
        [//]: # "/simulations/bundled-simulations"

        By bundling transactions in a single simulation, you can test cross-contract interactions and verify that the transaction flow behaves correctly across multiple contracts. This is critical for dApps that rely on complex contract interactions.

        [Learn more →](/simulations/bundled-simulations)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I bundle multiple user actions into a single simulation to provide feedback on complex flows?</h2>

      <hr />

      <div>
        [//]: # "/simulations/bundled-simulations"

        You can bundle multiple user actions by simulating them as part of a single bundled simulation. This allows you to provide feedback on complex transaction flows that involve multiple interactions in your dApp.

        [Learn more →](/simulations/bundled-simulations)
      </div>
    </div>
  </Card>
</div>


# FAQ: Virtual Environments
Source: https://docs.tenderly.co/troubleshooting/virtual-environments

Answers to common questions about creating, forking, and managing Virtual Environments, including chain IDs, timestamps, State Sync, and team workflows.

<div>
  <Card>
    <div>
      <h2>Do I need a paid plan to use Virtual Environments?</h2>

      <hr />

      <div>
        Yes. Virtual Environments are available on the paid plan. To enable them for your account, [contact our sales team](https://tenderly.co/contact-us) to schedule a call and discuss upgrading your plan.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I create Virtual Environments?</h2>

      <hr />

      <div>
        You can create a Virtual Environment in two ways:

        * From the [Dashboard UI](/virtual-environments/overview#quickstart)
        * Using the [Virtual Environment REST API](/api-reference#/operations/createVnet).
        * By [forking an existing Virtual Environment](/virtual-environments/develop/fork-testnet).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Why should I set a unique chain ID?</h2>

      <hr />

      <div>
        Set a custom chain ID that's different from the parent network's chain ID.

        Recommendation: Add the prefix **`7357`** (*test*) to the original network's Chain ID. For example, if
        you're creating a Virtual Environment by forking the Ethereum Mainnet (chain ID: 1), set your Virtual
        Environment chain ID to something like `73571`.

        This is recommended for several reasons:

        * Since the Virtual Environment chain is independent of the Mainnet chain, it should have an independent and unique chain ID.
        * Using a unique chain ID is a **security measure** that protects your dapp against
          [**transaction replay attacks**](https://quantstamp.com/blog/preventing-replay-attacks-post-ethereum-merge).
        * Wallets, such as MetaMask, will recognize that the **original chain ID is already in use** and will
          potentially mistake your Virtual Environment for the parent network unless it uses a unique chain ID.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How Virtual Environments resolve timestamps?</h2>

      <hr />

      <div>
        When a transaction or `eth_call` accesses **`block.timestamp`** within a contract, the value will depend whether the transaction targets `latest` or `pending` block.

        * For `pending` block the value is current time adjusted by the adjustment offset `block.timestamp == time.now() + adjustment_offset`.
        * For `latest` block the value is the timestamp of the latest block `block.timestamp == latest_block.timestamp`

        The `adjustment_offset` somes from time-adjustment methods [`evm_setNextBlockTimestamp`](/virtual-environments/admin-rpc/#evm_setnextblocktimestamp) and [`evm_increaseTime`](/virtual-environments/admin-rpc/#evm_increasetime).

        [Learn more →](/virtual-environments/develop/timestamps)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How mining works?</h2>

      <hr />

      <div>
        Each time you send a transaction to a Virtual Environment via `eth_sendTransaction` or `eth_sendRawTransaction`, a block is mined and block number increases by 1. The **initial block number** is taken from the latest block of the original chain at the time of creation.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How does State Sync work?</h2>

      <hr />

      <div>
        [State Sync](/virtual-environments/state-sync) enables a Virtual Environment to track the live state of the original
        network .

        * Until a Virtual Environment transaction modifies a storage slot, the Virtual Environment tracks the current value from the
          original network.
        * After a Virtual Environment transaction modifies a slot `X` in a contract `C`, any subsequent read will yield that
          value. The unmodified `C.Y` will reflect the value from the original network.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Why can't I see mainnet transactions with State Sync?</h2>

      <hr />

      <div>
        State sync tracks state, but does not synchronize nor display original network

        * transactions
        * event logs
        * blocks

        A contract deployed on the original network after the Virtual Environment was created appears as code at its address (`eth_getCode` at `latest` returns its bytecode), with no deployment transaction visible on the Virtual Environment. The Virtual Environment's own block height is not an indicator of how fresh the synced state is; see [Which parent-network state does `latest` reflect?](/virtual-environments/state-sync#which-parent-network-state-does-latest-reflect)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Are there issues with State Sync?</h2>

      <hr />

      <div>
        Behavior of mainnet contracts that cache `block.number` is unpredictable when running Virtual Environment
        transactions, since the [block number grows at different
        rates](/virtual-environments/state-sync#which-parent-network-state-does-latest-reflect) on mainnet and the Virtual Environment.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I speed up passage of time?</h2>

      <hr />

      <div>
        To enable faster testing of code that depends on current timestamp (e.g. yield and reward calculation), you can use [`tenderly_increaseTime`](/virtual-environments/admin-rpc#evm_increasetime).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Do Virtual Environments support WebSockets?</h2>

      <hr />

      <div>
        Yes, Virtual Environments do support WebSockets. Just use `wss://` instead of `https://` in an URL.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>When would I fork a Virtual Environment?</h2>

      <hr />

      <div>
        You can [fork an existing Virtual Environment](/virtual-environments/develop/fork-testnet) after deploying contracts and
        setting up your Virtual Environment state by [funding accounts](/virtual-environments/unlimited-faucet),
        [sending transactions](/virtual-environments/interact/send-transactions) or using [Admin RPC](/virtual-environments/admin-rpc).

        * **Intact starting point**: By using a forked Virtual Environment to develop or experiment, your starting point
          remains clean from changes.
        * **Working copy per team member**: After [staging smart contracts](/virtual-environments/ci-cd/stage-contracts),
          your team members can do their work on their own working copy of the network.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How Virtual Environments help team collaboration?</h2>

      <hr />

      <div>
        When using Virtual Environments to deploy smart contracts, members of your [**Tenderly
        Organization**](/platform/account/organizations/overview) will have direct access to the Virtual Environment.

        After deployment to a Virtual Environment, you can distribute chain and contract configuration so builders of other
        components such as UI, APIs, and data indexing can connect to staged contracts.

        Here are some recommendations:

        <ol>
          <li> [Stage contracts](/virtual-environments/ci-cd/stage-contracts) to a Virtual Environment.</li>
          <li> [Fork the staging Virtual Environment](/virtual-environments/develop/fork-testnet) for each team (frontend,
          backend, etc.) to ensure boundaries between teams and reduce test-data noise in
          development.</li>
          <li> Update all relevant git repos with Virtual Environment config and contract information:</li>

          <ul>
            <li> Chain config: share the chain ID and Admin RPC (so other builders can control chain state)</li>
            <li> Contracts' ABIs</li>
            <li> Contracts' deployment addresses</li>
          </ul>

          <li>When developing locally (UI, backend), switch to the Virtual Environment.</li>
          <li>Share failing transactions to smart contract developers</li>
        </ol>
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How to stage a dapp for external demos and community testing?</h2>

      <hr />

      <div>
        When staging your dapp for external and demo testing, make sure that:

        * Stage your contracts to a Virtual Environment.
        * Stage all your offchain components (backend, data indexing solutions, etc.) and have them connect to the Virtual Environment.
        * Connect your staged dapp via [**Public RPC**](/virtual-environments/overview#admin-rpc) (not Admin RPC) and connect it to other offchain components.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I revert Virtual Environment state?</h2>

      <hr />

      <div>
        Instead of reverting state, it's recommended to [fork an existing
        Virtual Environment](/virtual-environments/develop/fork-testnet) instead and do your testing on a disposable working
        copy.

        You can [Revert Virtual Environment state](/virtual-environments/develop/revert-state) if testing steps aren't
        repeatable otherwise.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How should I name my Virtual Environment?</h2>

      <hr />

      <div>
        For easier distinction, prefix your Virtual Environments with **`virtual`** (e.g. `virtualMainnet`). This is
        particularly useful for integrations such as [Viem](/virtual-environments/libraries/viem),
        [HardHat](/virtual-environments/develop/deploy-contracts), and
        [others](/virtual-environments/integrations).

        Alternatively, include the **purpose** in Virtual Environment's name:

        * **`internalTestingMainnet`**
        * **`demoMainnet`**
        * **`dataInsightsMainnet`**
        * **`ciMainnet`**
        * **`bugBountyBase`**
        * **`frontEndDevOptimism`**
        * **`communityTestingAvalanche`**
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What's verification visibility in Virtual Environments?</h2>

      <hr />

      <div>
        Virtual Environment's [Public explorer](/virtual-environments/explorer) adheres to **verification visibility for
        contracts** you deploy and verify on the Virtual Environment:

        * **Full**: the public block explorer will display the entire source code of all functions
        * **ABI-only**: the public block explorer shows only function and events' names and signatures,
          including argument names. This way your source code remains invisible outside of your project.
        * **None**: only show the final outcomes of transactions, without revealing the source code, or method
          names.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I run Foundry scripts on Virtual Environments?</h2>

      <hr />

      <div>
        Use the `--slow` flag when running Foundry scripts to prevent transaction batching. With this, a transaction is sent only after it’s preceding transaction is confirmed.

        ```bash lines={2} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        forge script script/Counter.s.sol:CounterScript \
        --slow
        --verify \
        --verifier-url $TENDERLY_VERIFIER_URL \
        --rpc-url $TENDERLY_VIRTUAL_TESTNET_RPC_URL \
        --private-key $PRIVATE_KEY  \
        --etherscan-api-key $TENDERLY_ACCESS_TOKEN \
        --broadcast \
        ```
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>When I fund accounts, should I input the amount in wei?</h2>

      <hr />

      <div>
        When using the Unlimted Faucet in the Dashboard, `1` means `1 ETH`, both for **native and ERC-20
        balance**.
        In case of ERC-20 tokens, Tenderly automatically calculates the exact amount in wei, using the ERC-20 number of decimals.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What's the difference between the Admin RPC and Public RPC?</h2>

      <hr />

      <div>
        **Public RPC** allows the standard JSON-RPC interaction. This is the RPC you'll use to integrate into
        your dapp's UI or backend when you're ready to demo your dapp externally.

        **Admin RPC** supports [additional RPC methods](/virtual-environments/admin-rpc) allowing higher control
        over the network state and storage, as well as account balances. This is the RPC you'll use in your
        deployment scripts for programmatic network control.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can I impersonate a sender on Virtual Environments?</h2>

      <hr />

      <div>
        You can successfully send transactions using **any sender address** [via
        Dashboard](/virtual-environments/interact/send-transactions#sendnig-from-the-dashboard). Tenderly will run
        those transactions on Virtual Environments without checking signatures.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I get accurate gas estimations?</h2>

      <hr />

      <div>
        Gas usage reflects the accurate gas usage of all OPCODES from the original network. You can get gas usage:

        * in Transaction Overview via Dashboard,
        * via [**tenderly\_estimateGas**](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_estimateGas) for single-transaction estimations with 100% accuracy
        * via [**tenderly\_estimateGasBundle**](/node-rpc/rpc-reference?network=ethereum-mainnet\&method=tenderly_estimateGasBundle) for estimation of multiple transactions with 100% accuracy
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Will verification work if I use `tenderly_setcode`?</h2>

      <hr />

      <div>
        When deploying modified bytecode to an address, the verification information will no longer match and it will not be possible to access traces and debugger for target addresses.
      </div>
    </div>
  </Card>
</div>


# FAQ: Web3 Actions
Source: https://docs.tenderly.co/troubleshooting/web3-actions

Answers on Web3 Actions execution modes, storage types, triggers, rate limits, runtime libraries, secrets, local testing, and project size limits.

<div>
  <Card>
    <div>
      <h2>Do I need a paid plan to use Web3 Actions?</h2>

      <hr />

      <div>
        Yes. Web3 Actions are available on the paid plan. To enable them for your account, [contact our sales team](https://tenderly.co/contact-us) to schedule a call and discuss upgrading your plan.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What's the difference between parallel and sequential execution?</h2>

      <hr />

      <div>
        During configuration of your Web3 Action, you can choose between the two modes of execution.

        When there's several triggered Web3 Actions (e.g. transactions from the same block), these two modes behave in the following way:

        * **sequential**: execution will respect the order in which the triggers have happened; until completion of trigger `N-1`, trigger `N` is awaiting for execution. The order of execution is guaranteed.
        * **parallel**: all triggers will be submitted for execution, and the execution order can not be guaranteed.

        The choice between sequential and parallel applies only to **block** and **transaction** triggers. **Periodic** and **webhook** triggers always run in parallel, regardless of `execution_type`.

        Strict ordering is best-effort under sustained load: if a sequential action keeps lagging behind its triggers, Tenderly may switch it to parallel execution to catch up and notifies you by email when that happens.

        Different [rate limits](#whats-the-rate-limit-for-web3-actions) apply.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What’s the difference between WRITE, COPY ON WRITE, and EMPTY storage types?</h2>

      <hr />

      <div>
        * **Write**: This type is selected by default. It’s always used in automatic triggers and writes data on the
          main storage. Please note that this type can potentially overwrite data on the main storage.
          * **Copy on write**: This type creates a copy of the main storage as temporary storage. It can be selected for
            manual triggers. Once a trigger stops running, everything that was written in the temporary storage won’t be
            saved.
          * **Empty**: This type creates temporary empty storage. It can be selected for manual triggers. The empty
            storage type doesn’t have any reference to the main storage. Once a trigger stops running, everything that was
            written on this type of storage will disappear.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Do contracts need to be verified to be used in Web3 Actions?</h2>

      <hr />

      <div>
        Yes, contracts need to be verified and added to your project on Tenderly to be used in Web3 Action triggers.
        Otherwise, the CLI will throw an error.

        Learn more about [triggers and how they work
        here](/monitoring/web3-actions/references/functions-events-triggers).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is the allowed number of Web3 Actions per project?</h2>

      <hr />

      <div>
        The number of Web3 Actions you can run depends on your plan capacity. [Contact our sales team](https://tenderly.co/contact-us) to discuss the capacity your project needs.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is the storage limit?</h2>

      <hr />

      <div>
        Storage allows up to 1,000 keys per project, with a maximum key size of 1 KB and a maximum value size of 100 KB. Exceeding a limit returns a `400 Bad Request` error stating which limit was violated. See [Storage limits](/monitoring/web3-actions/references/context#storage-limits).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can the Web3 Actions storage limits be increased?</h2>

      <hr />

      <div>
        The 100 KB per-value limit is a hard limit of the underlying storage engine and cannot be raised. If a single item needs more space, split it across multiple keys, or keep it in an external database and store its credentials in [Secrets](/monitoring/web3-actions/references/context#secrets). If you're approaching the 1,000-key project limit, contact [support@tenderly.co](mailto:support@tenderly.co).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What's the size limit to the Web3 Action project?</h2>

      <hr />

      <div>
        When you create a Web3 Action using the CLI, the entire NPM project will be zipped and uploaded to Tenderly.
        The maximum size of the zipped archive, including `node_modules` is **40 MB**.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is the execution timeout for Web3 Actions?</h2>

      <hr />

      <div>
        Execution is limited to 30 seconds by default, at which point it's terminated. If more time is needed, contact our support team at [support@tenderly.co](mailto:support@tenderly.co) to discuss your use case. Extended time limits apply only to parallel actions; sequential executions keep the 30-second limit. Get more [information on the execution status types](/monitoring/web3-actions/references/execution).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>I have a `tenderly.yaml` file with two Web3 Actions with the same trigger (a certain contract event). Will the first action declared in the manifest file always be invoked before the second one?</h2>

      <hr />

      <div>
        Two separate Web3 Actions with the same trigger are executed in parallel since they’re isolated entities unaware
        of one another.
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What's available in Web3 Actions Runtime?</h2>

      <hr />

      <div>
        [//]: # "https://docs.tenderly.co/monitoring/web3-actions/references/functions-events-triggers#available-libraries-for-dashboard-based-actions"

        The following libraries are available:

        * Ethers.js
        * Bignumber.js
        * Axios
        * Luxon

        [Learn more →](/monitoring/web3-actions/references/functions-events-triggers#available-libraries-for-dashboard-based-actions)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do Web3 Actions interact with blockchain data?</h2>

      <hr />

      <div>
        [//]: # "https://docs.tenderly.co/monitoring/web3-actions/introduction"

        Web3 Actions can interact with blockchain data by reading blocks, transactions, and logs, enabling smart contract monitoring.
        Example:

        ```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        const { ethers } = require("ethers");
        const provider = new ethers.providers.JsonRpcProvider(RPC_URL);
        const latestBlock = await provider.getBlockNumber();
        ```

        [Learn more →](/monitoring/web3-actions/introduction)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What are the trigger types available for Web3 Actions?</h2>

      <hr />

      <div>
        [//]: # "https://docs.tenderly.co/monitoring/web3-actions/references/functions-events-triggers#external-events-and-trigger-types"

        Web3 Actions support four trigger types, which define when the action should be executed:

        * **Block**: triggered by new blocks on the blockchain, ideal for block-level monitoring.
        * **Transaction**: triggered by specific blockchain transactions, enabling monitoring and custom reactions.
        * **Webhook**: triggered by incoming HTTP requests, allowing Web3 Actions to act as backends for dapps or other services.
        * **Periodic (CRON)**: runs at specific intervals, automating recurring tasks. Example:

        ```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        cron:
          interval: "*/15 * * * *"
        ```

        [Learn more →](/monitoring/web3-actions/references/functions-events-triggers#external-events-and-trigger-types)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How do I deploy Web3 Actions?</h2>

      <hr />

      <div>
        [//]: # "https://docs.tenderly.co/monitoring/web3-actions/introduction"

        Web3 Actions can be deployed via the Tenderly Dashboard or using the CLI. The CLI provides more advanced configuration options. Actions and their triggers are configured in the `tenderly.yaml` file; the deploy command takes no flags:

        ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        tenderly actions deploy
        ```

        [Learn more →](/monitoring/web3-actions/introduction)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How are errors handled in Web3 Actions?</h2>

      <hr />

      <div>
        [//]: # "https://docs.tenderly.co/monitoring/web3-actions/references/error-reporting"

        Errors in Web3 Actions are logged and can be viewed in the Tenderly Dashboard. Failed actions can be re-executed for further debugging.

        [Learn more →](/monitoring/web3-actions/references/error-reporting)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Why didn't I get an email when my Web3 Action failed?</h2>

      <hr />

      <div>
        Failure emails are sent only when a new incident is created: the first time a given error occurs for the current version of your Action, on a trigger-based run. Check the following:

        * Repeated occurrences of the same error are grouped under the existing incident and don't send additional emails until the incident is resolved in [Error Reporting](/monitoring/web3-actions/references/error-reporting).
        * Manual runs and re-runs never send failure emails or create incidents, regardless of outcome.
        * Executions ending in `TIMED_OUT`, `RATE_LIMITED`, or `TU_QUOTA_REACHED` don't send failure emails.
        * The destination email must be verified and switched on in the Action's Destinations section.

        [Learn more →](/monitoring/web3-actions/references/notifications#when-failure-emails-are-sent)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What’s the rate limit for Web3 Actions?</h2>

      <hr />

      <div>
        [//]: # "https://docs.tenderly.co/monitoring/web3-actions/usage-rate-limits"

        Rate limits apply per action: 400 executions per 5 minutes for sequential actions and 2000 executions per 5 minutes for parallel actions, customizable per quote.

        [Learn more →](/monitoring/web3-actions/usage-rate-limits)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>I received an "action reached a rate limit" email. What does it mean?</h2>

      <hr />

      <div>
        The action was triggered more often than its per-action execution rate limit allows. Executions above the limit were skipped: they appear as `RATE_LIMITED` in the [execution history](/monitoring/web3-actions/references/execution#web3-action-execution-status-types) and are not retried. The notification is batched, so you receive at most one such email per action per 24 hours. If your workload needs a higher rate, contact [support@tenderly.co](mailto:support@tenderly.co).
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is key-value storage in Web3 Actions?</h2>

      <hr />

      <div>
        [//]: # "https://docs.tenderly.co/monitoring/web3-actions/references/context#storage"

        Key-value storage allows Web3 Actions to persist state and data between executions. For sensitive information like API keys, use [secrets](#how-can-i-manage-secrets-in-web3-actions) instead.
        Example:

        ```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        await context.storage.putStr("myKey", "value");
        const value = await context.storage.getStr("myKey");
        ```

        [Learn more →](/monitoring/web3-actions/references/context#storage)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What are common use cases for Web3 Actions?</h2>

      <hr />

      <div>
        [//]: # "https://docs.tenderly.co/monitoring/web3-actions/introduction#use-cases-for-web3-actions-and-different-events"

        Common use cases include monitoring blockchain transactions, automating tasks, and building webhook backends for dapps.

        [Learn more →](/monitoring/web3-actions/introduction#use-cases-for-web3-actions-and-different-events)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can Web3 Actions be tested locally?</h2>

      <hr />

      <div>
        [//]: # "https://docs.tenderly.co/monitoring/web3-actions/references/local-development"

        Yes, using the `@tenderly/actions-test` npm package, Web3 Actions can be tested locally. Install it with `npm install --save-dev @tenderly/actions-test`, then execute your action function through the `TestRuntime`:

        ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        import { TestRuntime, TestBlockEvent } from '@tenderly/actions-test';

        const runtime = new TestRuntime();
        await runtime.execute(actionFn, new TestBlockEvent());
        ```

        [Learn more →](/monitoring/web3-actions/references/local-development)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What are the supported programming languages for Web3 Actions?</h2>

      <hr />

      <div>
        Web3 Actions are written in JavaScript or TypeScript.
        Example:

        ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        async function main() {
          console.log("Running Web3 Action");
        }
        ```
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How can I manage secrets in Web3 Actions?</h2>

      <hr />

      <div>
        [//]: # "https://docs.tenderly.co/monitoring/web3-actions/references/context#secrets"

        You can securely store and retrieve sensitive data, such as API keys, using the secrets management feature.
        Example:

        ```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        const apiKey = await context.secrets.get("API_KEY");
        ```

        [Learn more →](/monitoring/web3-actions/references/context#secrets)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>Can Web3 Actions interact with external APIs?</h2>

      <hr />

      <div>
        [//]: # "https://docs.tenderly.co/monitoring/web3-actions/introduction"

        Yes, you can interact with external APIs using libraries such as Axios for HTTP requests.
        Example:

        ```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        const axios = require("axios");
        const response = await axios.get("https://api.example.com/data");
        ```

        [Learn more →](/monitoring/web3-actions/introduction)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>What is the purpose of simulations in Web3 Actions?</h2>

      <hr />

      <div>
        [//]: # "source: https://docs.tenderly.co/monitoring/web3-actions/introduction#use-cases "

        Web3 Actions can run transaction simulations to test and verify outcomes before broadcasting transactions.
        Example:

        ```js theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        const simulationResult = await simulateTransaction(txData);
        ```

        [Learn more →](/monitoring/web3-actions/introduction#use-cases)
      </div>
    </div>
  </Card>

  <Card>
    <div>
      <h2>How does Tenderly handle logs for Web3 Actions?</h2>

      <hr />

      <div>
        Tenderly logs every execution of Web3 Actions. Logs can be accessed and reviewed on the Tenderly Dashboard for debugging.
      </div>
    </div>
  </Card>
</div>


# Delete Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/delete-web3-action

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}
This endpoint allows you to delete a Web3 Action. You need to provide the Web3 Action ID.



# Get details for all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/get-details-for-all-web3-actions

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions
Retrieve the configuration details for all Web3 Actions created in a specific project.



# Get details for single Web3 Action execution
Source: https://docs.tenderly.co/api-reference/actions/get-details-for-single-web3-action-execution

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/calls/call/{executionId}
Retrieve the details of a specific Web3 Action execution. You need to provide the Web3 Action ID and execution ID.



# Get execution history for single Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/get-execution-history-for-single-web3-action

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/calls
Retrieve the entire execution history for a specific Web3 Action. You need to provide the Web3 Action ID.



# Get Web3 Action details
Source: https://docs.tenderly.co/api-reference/actions/get-web3-action-details

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}
Retrieve the configuration details of a specific Web3 Action. You need to provide the Web3 Action ID.



# Resume specific Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/resume-specific-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/resume
Resume a stopped Web3 Action. You need to provide the Web3 Action ID.



# Create Alert
Source: https://docs.tenderly.co/api-reference/alerts/create-alert

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/alert
Create an Alert in a Tenderly project. 

Learn more about the different [types of Alert triggers](https://docs.tenderly.co/alerts/alert-types-targets-and-parameters).



# Delete Alert
Source: https://docs.tenderly.co/api-reference/alerts/delete-alert

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/alert/{alertId}
Delete an existing Alert. You need to provide the Alert ID.



# Get Alert History
Source: https://docs.tenderly.co/api-reference/alerts/get-alert-history

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/alert-history
Retrieve the execution history for all Alerts in a Tenderly project. 



# List Alerts
Source: https://docs.tenderly.co/api-reference/alerts/list-alerts

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/alerts
This endpoint allows you retrieve alerts for given project.



# Send test Alert
Source: https://docs.tenderly.co/api-reference/alerts/send-test-alert

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/test-alerts
This endpoint allows you test the execution of Alerts.



# Update Alert
Source: https://docs.tenderly.co/api-reference/alerts/update-alert

/api-reference/openapi.json patch /v1/account/{accountSlug}/project/{projectSlug}/alert/{alertId}
Update an existing Alert. You need to provide the Alert ID.



# Disable simulation sharing
Source: https://docs.tenderly.co/api-reference/simulator/disable-simulation-sharing

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/unshare
Call the `unshare` endpoint to disable public sharing for a simulated transaction from a specific account or project. You need to provide the ID of the simulated transaction.

Learn more about [sharing transactions](https://blog.tenderly.co/changelog/public-sharing-of-transactions-devnets-forks-and-simulations).



# Enable simulation sharing
Source: https://docs.tenderly.co/api-reference/simulator/enable-simulation-sharing

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/share
Call the `share` endpoint to enable the public sharing feature for a simulation ID from a specific account or project. Once enabled, simulation details become accessible to anyone with the link to the transaction simulation.

Example sharable link: `https://www.tdly.co/shared/simulation/{simulationId}`.

Learn more about [sharing transactions](https://blog.tenderly.co/changelog/public-sharing-of-transactions-devnets-forks-and-simulations).



# Fetch all simulated transactions
Source: https://docs.tenderly.co/api-reference/simulator/fetch-all-simulated-transactions

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/simulations
Call the `simulations` endpoint to get a list of all simulated transactions within an account and project.



# Get full simulated transaction details
Source: https://docs.tenderly.co/api-reference/simulator/get-full-simulated-transaction-details

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}
Get all the simulation details for a transaction from a specific account or project. This data includes details about the transaction, simulation details, list of contracts involved, and generated access list. You need to provide the ID of the simulated transaction. 



# Get quick simulated transaction details
Source: https://docs.tenderly.co/api-reference/simulator/get-quick-simulated-transaction-details

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/info
Call the `info` endpoint to fetch only the `transaction_info` object for a simulated transaction from a specific account or project. The response also return the block header information and block override data as separate objects. You need to provide the ID of the simulated transaction. 

This endpoint returns the same data as the [Fetch full simulation details by transaction ID](https://docs.tenderly.co/reference/api#/operations/getSimulatedTransactionById) just formatted in a different way.



# Simulate bundled transactions
Source: https://docs.tenderly.co/api-reference/simulator/simulate-bundled-transactions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulate-bundle
Call the `simulate-bundle` endpoint to simulate multiple consecutive transactions at once. You can simulate bundled transactions on real-time data from over [105+ supported networks](https://docs.tenderly.co/supported-networks-and-languages). This endpoint receive an array of transactions that get simulated one after another on the same block.

**Note:** If the initial transaction in the array changes the state, all subsequent transactions will be simulated against this modified state. Furthermore, should a simulation fail for any reason, all following simulations in the sequence will not be executed.

Learn more about [bundled simulations](https://docs.tenderly.co/simulations/bundled-simulations).

The response returns a `simulation_results` array, where each element corresponds to a simulation in the input array (in the same order). Each result contains the following objects:

`transaction`: Contains data related to the simulated transaction, including its hash, block number, origin and destination addresses, gas details, input data, nonce, and other transaction details, like the status, timestamp, and involved contract addresses. The nested `transaction_info` object holds detailed execution data such as the call trace, emitted logs, state diffs, and asset changes.

`simulation`: Contains metadata about this simulation within the bundle, including its unique ID, project and owner IDs, block number, gas used, the method invoked, simulation status, state overrides applied, and other metadata.

`contracts`: Contains data about the contract(s) involved in the transaction, including the contract's ID, network ID, balance, verification status, associated standards (like ERC20), token-specific data if the contract is a token, compiler version, and even the source code of the contract in some cases.

`generated_access_list`: Contains a list of addresses and storage keys that the transaction will access, enabling certain gas cost optimizations. The access list is a feature introduced in [Ethereum's EIP-2930](https://eips.ethereum.org/EIPS/eip-2930).



# Simulate transaction
Source: https://docs.tenderly.co/api-reference/simulator/simulate-transaction

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulate
Call the `simulate` endpoint to preview the outcomes a single transaction before sending it to the live network. You can simulate transactions with custom parameters on [105+ supported networks](https://docs.tenderly.co/supported-networks-and-languages). The output provides detailed insights into emitted events, state changes, asset and balance changes, among other things. 

Learn about [single transaction simulations](https://docs.tenderly.co/simulations/single-simulations).

The response returns the following objects:

`transaction`: Contains data related to the transaction, including its hash, block number, origin and destination addresses, gas details, input data, nonce, and other transaction details, like the status, timestamp, and involved contract addresses.

`simulation`: Contains data about the simulated transaction. It provides details related to the ID of the simulation, project and owner IDs, block number where the transaction was included, gas used, method invoked, simulation status, and other metadata.

`contracts`: Contains data about the contract(s) involved in the transaction, including the contract's ID, network ID, balance, verification status, associated standards (like ERC20), token-specific data if the contract is a token, compiler version, and even the source code of the contract in some cases.

`generated_access_list`: Contains a list of addresses and storage keys that the transaction will access, enabling certain gas cost optimizations. The access list is a feature introduced in [Ethereum's EIP-2930](https://eips.ethereum.org/EIPS/eip-2930).



# Batch Delete Environments
Source: https://docs.tenderly.co/api-reference/virtual-environments/batch-delete-environments

/api-reference/openapi.json delete /public/v1/account/{accountSlug}/project/{projectSlug}/environments
Permanently delete multiple environments by ID



# Create Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/create-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments
Create a new multi-chain environment with Virtual Environments across specified networks



# Delete Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/delete-environment

/api-reference/openapi.json delete /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}
Permanently delete a single environment by ID



# Get Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}
Get a single environment by ID



# Get Environment Instance Transaction
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment-instance-transaction

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/transactions/{txHash}
Get a single transaction from an environment instance by transaction hash



# Get Environment Instance Transactions
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment-instance-transactions

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/transactions
Get transactions across all Virtual Environments in an environment instance, with pagination and optional filters by status, category, kind, from/to address.



# List Environments
Source: https://docs.tenderly.co/api-reference/virtual-environments/list-environments

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments
List all multi-chain environments for the given account and project



# Send Transaction on Environment Virtual Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/send-transaction-on-environment-virtual-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/vnet/{vnetId}/transactions
Send a transaction to be executed on a specific Virtual Environment within an environment instance



# Simulate Transaction on Environment Virtual Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/simulate-transaction-on-environment-virtual-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/vnet/{vnetId}/transactions/simulate
Simulate a transaction on a specific Virtual Environment within an environment instance. State is not preserved. Supports block overrides, state overrides, and a custom block number. The richer response includes asset changes, balance changes, exposure changes, state changes, and cross-chain interop information.



# Create Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/create-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/publishFile
Create a new Web3 Action. You can also set the Web3 Action to be deployed once it's been created.

## Validation

When the payload fails validation, the endpoint responds with `400` and the error slug
`found_validation_errors` without per-field detail. Common causes:

- `action.name` doesn't match `^[a-zA-Z][a-zA-Z0-9_-]*$` (it must start with a letter and may contain only letters, digits, dashes, and underscores; spaces are not allowed). Put human-readable text in `action.description` instead.
- `trigger.periodic.cron` is not a standard five-field cron expression (minute, hour, day of month, month, day of week). Seconds fields and `@hourly`-style shortcuts are not supported.
- The function referenced in `action.function` is not present in `action.source`.
- `action.trigger` is missing for a non-`ALERT` trigger type, or the trigger object doesn't match `triggerType`.
- `action.invocationType` is not one of `SYNC` or `ASYNC`.



# Resume all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/resume-all-web3-actions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/resume
Resume all stopped Web3 Actions created in a project.



# Stop all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/stop-all-web3-actions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/stop
Stop all Web3 Actions created in a specific project.



# Stop specific Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/stop-specific-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/stop
Stop a Web3 Action. You need to provide the Web3 Action ID.



# Add contract to project
Source: https://docs.tenderly.co/api-reference/contracts/add-contract-to-project

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/address
Add a smart contract to a Tenderly project.

**Note**: If a contract is unverified on both Tenderly and external providers like Etherscan, Blockscout, or Routescan, it will be added to the project as **unverified**. However, if the contract is verified on an external provider, Tenderly will retrieve and apply the verification, subsequently adding the verified contract to the project.



# Add tag to mutiple contracts
Source: https://docs.tenderly.co/api-reference/contracts/add-tag-to-mutiple-contracts

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/tag
This endpoint allows you to tag multiple smart contracts.



# Delete contract from project
Source: https://docs.tenderly.co/api-reference/contracts/delete-contract-from-project

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}
Delete a smart contract from a Tenderly project. 



# Delete contract tag
Source: https://docs.tenderly.co/api-reference/contracts/delete-contract-tag

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}/tag
Delete a tag that has been added to a smart contract.



# Encode state overrides
Source: https://docs.tenderly.co/api-reference/contracts/encode-state-overrides

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/contracts/encode-states
Encode state overrides of the smart contract.



# Get all contracts in project
Source: https://docs.tenderly.co/api-reference/contracts/get-all-contracts-in-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/contracts
Get details for all smart contracts in a Tenderly project.



# Rename contract
Source: https://docs.tenderly.co/api-reference/contracts/rename-contract

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}/rename
This endpoint allows you to rename a smart contract.

**Note**: If a contract is unverified on both Tenderly and external providers like Etherscan, Blockscout, or Routescan, it will be added to the project as **unverified**. However, if the contract is verified on an external provider, Tenderly will retrieve and apply the verification, subsequently adding the verified contract to the project.



# List Delivery Channels
Source: https://docs.tenderly.co/api-reference/delivery-channels/list-delivery-channels

/api-reference/openapi.json get /v1/account/{accountSlug}/delivery-channels
Retrieves all configured delivery channels for an account.



# List Delivery Channels for project
Source: https://docs.tenderly.co/api-reference/delivery-channels/list-delivery-channels-for-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/delivery-channels
Retrieve all configured delivery channels associated with a specific project.



# Check supported networks
Source: https://docs.tenderly.co/api-reference/other/check-supported-networks

/api-reference/openapi.json get /v1/supported-networks
The endpoint returns the list of networks that are currently supported on the Tenderly platform and also returns information about features these networks are supported on as well as corresponding network slugs users can use for integration with Tenderly.



# Add wallet to project
Source: https://docs.tenderly.co/api-reference/wallets/add-wallet-to-project

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/wallet
This endpoint allows you to add a wallet address to your Tenderly project.



# Get wallet in project
Source: https://docs.tenderly.co/api-reference/wallets/get-wallet-in-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/wallet/{address}/network/{networkId}
This endpoint allows you to get a single wallet for your Tenderly project.



# Disable simulation sharing
Source: https://docs.tenderly.co/api-reference/simulator/disable-simulation-sharing

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/unshare
Call the `unshare` endpoint to disable public sharing for a simulated transaction from a specific account or project. You need to provide the ID of the simulated transaction.

Learn more about [sharing transactions](https://blog.tenderly.co/changelog/public-sharing-of-transactions-devnets-forks-and-simulations).



# Enable simulation sharing
Source: https://docs.tenderly.co/api-reference/simulator/enable-simulation-sharing

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/share
Call the `share` endpoint to enable the public sharing feature for a simulation ID from a specific account or project. Once enabled, simulation details become accessible to anyone with the link to the transaction simulation.

Example sharable link: `https://www.tdly.co/shared/simulation/{simulationId}`.

Learn more about [sharing transactions](https://blog.tenderly.co/changelog/public-sharing-of-transactions-devnets-forks-and-simulations).



# Fetch all simulated transactions
Source: https://docs.tenderly.co/api-reference/simulator/fetch-all-simulated-transactions

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/simulations
Call the `simulations` endpoint to get a list of all simulated transactions within an account and project.



# Get full simulated transaction details
Source: https://docs.tenderly.co/api-reference/simulator/get-full-simulated-transaction-details

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}
Get all the simulation details for a transaction from a specific account or project. This data includes details about the transaction, simulation details, list of contracts involved, and generated access list. You need to provide the ID of the simulated transaction. 



# Get quick simulated transaction details
Source: https://docs.tenderly.co/api-reference/simulator/get-quick-simulated-transaction-details

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/info
Call the `info` endpoint to fetch only the `transaction_info` object for a simulated transaction from a specific account or project. The response also return the block header information and block override data as separate objects. You need to provide the ID of the simulated transaction. 

This endpoint returns the same data as the [Fetch full simulation details by transaction ID](https://docs.tenderly.co/reference/api#/operations/getSimulatedTransactionById) just formatted in a different way.



# Simulate bundled transactions
Source: https://docs.tenderly.co/api-reference/simulator/simulate-bundled-transactions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulate-bundle
Call the `simulate-bundle` endpoint to simulate multiple consecutive transactions at once. You can simulate bundled transactions on real-time data from over [105+ supported networks](https://docs.tenderly.co/supported-networks-and-languages). This endpoint receive an array of transactions that get simulated one after another on the same block.

**Note:** If the initial transaction in the array changes the state, all subsequent transactions will be simulated against this modified state. Furthermore, should a simulation fail for any reason, all following simulations in the sequence will not be executed.

Learn more about [bundled simulations](https://docs.tenderly.co/simulations/bundled-simulations).

The response returns a `simulation_results` array, where each element corresponds to a simulation in the input array (in the same order). Each result contains the following objects:

`transaction`: Contains data related to the simulated transaction, including its hash, block number, origin and destination addresses, gas details, input data, nonce, and other transaction details, like the status, timestamp, and involved contract addresses. The nested `transaction_info` object holds detailed execution data such as the call trace, emitted logs, state diffs, and asset changes.

`simulation`: Contains metadata about this simulation within the bundle, including its unique ID, project and owner IDs, block number, gas used, the method invoked, simulation status, state overrides applied, and other metadata.

`contracts`: Contains data about the contract(s) involved in the transaction, including the contract's ID, network ID, balance, verification status, associated standards (like ERC20), token-specific data if the contract is a token, compiler version, and even the source code of the contract in some cases.

`generated_access_list`: Contains a list of addresses and storage keys that the transaction will access, enabling certain gas cost optimizations. The access list is a feature introduced in [Ethereum's EIP-2930](https://eips.ethereum.org/EIPS/eip-2930).



# Simulate transaction
Source: https://docs.tenderly.co/api-reference/simulator/simulate-transaction

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulate
Call the `simulate` endpoint to preview the outcomes a single transaction before sending it to the live network. You can simulate transactions with custom parameters on [105+ supported networks](https://docs.tenderly.co/supported-networks-and-languages). The output provides detailed insights into emitted events, state changes, asset and balance changes, among other things. 

Learn about [single transaction simulations](https://docs.tenderly.co/simulations/single-simulations).

The response returns the following objects:

`transaction`: Contains data related to the transaction, including its hash, block number, origin and destination addresses, gas details, input data, nonce, and other transaction details, like the status, timestamp, and involved contract addresses.

`simulation`: Contains data about the simulated transaction. It provides details related to the ID of the simulation, project and owner IDs, block number where the transaction was included, gas used, method invoked, simulation status, and other metadata.

`contracts`: Contains data about the contract(s) involved in the transaction, including the contract's ID, network ID, balance, verification status, associated standards (like ERC20), token-specific data if the contract is a token, compiler version, and even the source code of the contract in some cases.

`generated_access_list`: Contains a list of addresses and storage keys that the transaction will access, enabling certain gas cost optimizations. The access list is a feature introduced in [Ethereum's EIP-2930](https://eips.ethereum.org/EIPS/eip-2930).



# Batch Delete Environments
Source: https://docs.tenderly.co/api-reference/virtual-environments/batch-delete-environments

/api-reference/openapi.json delete /public/v1/account/{accountSlug}/project/{projectSlug}/environments
Permanently delete multiple environments by ID



# Create Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/create-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments
Create a new multi-chain environment with Virtual Environments across specified networks



# Delete Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/delete-environment

/api-reference/openapi.json delete /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}
Permanently delete a single environment by ID



# Get Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}
Get a single environment by ID



# Get Environment Instance Transaction
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment-instance-transaction

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/transactions/{txHash}
Get a single transaction from an environment instance by transaction hash



# Get Environment Instance Transactions
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment-instance-transactions

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/transactions
Get transactions across all Virtual Environments in an environment instance, with pagination and optional filters by status, category, kind, from/to address.



# List Environments
Source: https://docs.tenderly.co/api-reference/virtual-environments/list-environments

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments
List all multi-chain environments for the given account and project



# Create Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/create-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/publishFile
Create a new Web3 Action. You can also set the Web3 Action to be deployed once it's been created.

## Validation

When the payload fails validation, the endpoint responds with `400` and the error slug
`found_validation_errors` without per-field detail. Common causes:

- `action.name` doesn't match `^[a-zA-Z][a-zA-Z0-9_-]*$` (it must start with a letter and may contain only letters, digits, dashes, and underscores; spaces are not allowed). Put human-readable text in `action.description` instead.
- `trigger.periodic.cron` is not a standard five-field cron expression (minute, hour, day of month, month, day of week). Seconds fields and `@hourly`-style shortcuts are not supported.
- The function referenced in `action.function` is not present in `action.source`.
- `action.trigger` is missing for a non-`ALERT` trigger type, or the trigger object doesn't match `triggerType`.
- `action.invocationType` is not one of `SYNC` or `ASYNC`.



# Delete Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/delete-web3-action

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}
This endpoint allows you to delete a Web3 Action. You need to provide the Web3 Action ID.



# Get details for all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/get-details-for-all-web3-actions

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions
Retrieve the configuration details for all Web3 Actions created in a specific project.



# Get details for single Web3 Action execution
Source: https://docs.tenderly.co/api-reference/actions/get-details-for-single-web3-action-execution

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/calls/call/{executionId}
Retrieve the details of a specific Web3 Action execution. You need to provide the Web3 Action ID and execution ID.



# Get execution history for single Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/get-execution-history-for-single-web3-action

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/calls
Retrieve the entire execution history for a specific Web3 Action. You need to provide the Web3 Action ID.



# Get Web3 Action details
Source: https://docs.tenderly.co/api-reference/actions/get-web3-action-details

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}
Retrieve the configuration details of a specific Web3 Action. You need to provide the Web3 Action ID.



# Resume all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/resume-all-web3-actions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/resume
Resume all stopped Web3 Actions created in a project.



# Resume specific Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/resume-specific-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/resume
Resume a stopped Web3 Action. You need to provide the Web3 Action ID.



# Stop all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/stop-all-web3-actions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/stop
Stop all Web3 Actions created in a specific project.



# Stop specific Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/stop-specific-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/stop
Stop a Web3 Action. You need to provide the Web3 Action ID.



# Create Alert
Source: https://docs.tenderly.co/api-reference/alerts/create-alert

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/alert
Create an Alert in a Tenderly project. 

Learn more about the different [types of Alert triggers](https://docs.tenderly.co/alerts/alert-types-targets-and-parameters).



# Delete Alert
Source: https://docs.tenderly.co/api-reference/alerts/delete-alert

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/alert/{alertId}
Delete an existing Alert. You need to provide the Alert ID.



# Get Alert History
Source: https://docs.tenderly.co/api-reference/alerts/get-alert-history

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/alert-history
Retrieve the execution history for all Alerts in a Tenderly project. 



# List Alerts
Source: https://docs.tenderly.co/api-reference/alerts/list-alerts

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/alerts
This endpoint allows you retrieve alerts for given project.



# Send test Alert
Source: https://docs.tenderly.co/api-reference/alerts/send-test-alert

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/test-alerts
This endpoint allows you test the execution of Alerts.



# Update Alert
Source: https://docs.tenderly.co/api-reference/alerts/update-alert

/api-reference/openapi.json patch /v1/account/{accountSlug}/project/{projectSlug}/alert/{alertId}
Update an existing Alert. You need to provide the Alert ID.



# Add contract to project
Source: https://docs.tenderly.co/api-reference/contracts/add-contract-to-project

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/address
Add a smart contract to a Tenderly project.

**Note**: If a contract is unverified on both Tenderly and external providers like Etherscan, Blockscout, or Routescan, it will be added to the project as **unverified**. However, if the contract is verified on an external provider, Tenderly will retrieve and apply the verification, subsequently adding the verified contract to the project.



# Add tag to mutiple contracts
Source: https://docs.tenderly.co/api-reference/contracts/add-tag-to-mutiple-contracts

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/tag
This endpoint allows you to tag multiple smart contracts.



# Delete contract from project
Source: https://docs.tenderly.co/api-reference/contracts/delete-contract-from-project

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}
Delete a smart contract from a Tenderly project. 



# Delete contract tag
Source: https://docs.tenderly.co/api-reference/contracts/delete-contract-tag

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}/tag
Delete a tag that has been added to a smart contract.



# Encode state overrides
Source: https://docs.tenderly.co/api-reference/contracts/encode-state-overrides

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/contracts/encode-states
Encode state overrides of the smart contract.



# Get all contracts in project
Source: https://docs.tenderly.co/api-reference/contracts/get-all-contracts-in-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/contracts
Get details for all smart contracts in a Tenderly project.



# Rename contract
Source: https://docs.tenderly.co/api-reference/contracts/rename-contract

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}/rename
This endpoint allows you to rename a smart contract.

**Note**: If a contract is unverified on both Tenderly and external providers like Etherscan, Blockscout, or Routescan, it will be added to the project as **unverified**. However, if the contract is verified on an external provider, Tenderly will retrieve and apply the verification, subsequently adding the verified contract to the project.



# List Delivery Channels
Source: https://docs.tenderly.co/api-reference/delivery-channels/list-delivery-channels

/api-reference/openapi.json get /v1/account/{accountSlug}/delivery-channels
Retrieves all configured delivery channels for an account.



# List Delivery Channels for project
Source: https://docs.tenderly.co/api-reference/delivery-channels/list-delivery-channels-for-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/delivery-channels
Retrieve all configured delivery channels associated with a specific project.



# Check supported networks
Source: https://docs.tenderly.co/api-reference/other/check-supported-networks

/api-reference/openapi.json get /v1/supported-networks
The endpoint returns the list of networks that are currently supported on the Tenderly platform and also returns information about features these networks are supported on as well as corresponding network slugs users can use for integration with Tenderly.



# Send Transaction on Environment Virtual Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/send-transaction-on-environment-virtual-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/vnet/{vnetId}/transactions
Send a transaction to be executed on a specific Virtual Environment within an environment instance



# Simulate Transaction on Environment Virtual Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/simulate-transaction-on-environment-virtual-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/vnet/{vnetId}/transactions/simulate
Simulate a transaction on a specific Virtual Environment within an environment instance. State is not preserved. Supports block overrides, state overrides, and a custom block number. The richer response includes asset changes, balance changes, exposure changes, state changes, and cross-chain interop information.



# Add wallet to project
Source: https://docs.tenderly.co/api-reference/wallets/add-wallet-to-project

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/wallet
This endpoint allows you to add a wallet address to your Tenderly project.



# Get wallet in project
Source: https://docs.tenderly.co/api-reference/wallets/get-wallet-in-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/wallet/{address}/network/{networkId}
This endpoint allows you to get a single wallet for your Tenderly project.



# Create Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/create-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/publishFile
Create a new Web3 Action. You can also set the Web3 Action to be deployed once it's been created.

## Validation

When the payload fails validation, the endpoint responds with `400` and the error slug
`found_validation_errors` without per-field detail. Common causes:

- `action.name` doesn't match `^[a-zA-Z][a-zA-Z0-9_-]*$` (it must start with a letter and may contain only letters, digits, dashes, and underscores; spaces are not allowed). Put human-readable text in `action.description` instead.
- `trigger.periodic.cron` is not a standard five-field cron expression (minute, hour, day of month, month, day of week). Seconds fields and `@hourly`-style shortcuts are not supported.
- The function referenced in `action.function` is not present in `action.source`.
- `action.trigger` is missing for a non-`ALERT` trigger type, or the trigger object doesn't match `triggerType`.
- `action.invocationType` is not one of `SYNC` or `ASYNC`.



# Delete Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/delete-web3-action

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}
This endpoint allows you to delete a Web3 Action. You need to provide the Web3 Action ID.



# Get details for all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/get-details-for-all-web3-actions

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions
Retrieve the configuration details for all Web3 Actions created in a specific project.



# Get details for single Web3 Action execution
Source: https://docs.tenderly.co/api-reference/actions/get-details-for-single-web3-action-execution

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/calls/call/{executionId}
Retrieve the details of a specific Web3 Action execution. You need to provide the Web3 Action ID and execution ID.



# Get execution history for single Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/get-execution-history-for-single-web3-action

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/calls
Retrieve the entire execution history for a specific Web3 Action. You need to provide the Web3 Action ID.



# Get Web3 Action details
Source: https://docs.tenderly.co/api-reference/actions/get-web3-action-details

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}
Retrieve the configuration details of a specific Web3 Action. You need to provide the Web3 Action ID.



# Resume all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/resume-all-web3-actions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/resume
Resume all stopped Web3 Actions created in a project.



# Resume specific Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/resume-specific-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/resume
Resume a stopped Web3 Action. You need to provide the Web3 Action ID.



# Stop all Web3 Actions
Source: https://docs.tenderly.co/api-reference/actions/stop-all-web3-actions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/stop
Stop all Web3 Actions created in a specific project.



# Stop specific Web3 Action
Source: https://docs.tenderly.co/api-reference/actions/stop-specific-web3-action

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/actions/action/{actionId}/stop
Stop a Web3 Action. You need to provide the Web3 Action ID.



# Create Alert
Source: https://docs.tenderly.co/api-reference/alerts/create-alert

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/alert
Create an Alert in a Tenderly project. 

Learn more about the different [types of Alert triggers](https://docs.tenderly.co/alerts/alert-types-targets-and-parameters).



# Delete Alert
Source: https://docs.tenderly.co/api-reference/alerts/delete-alert

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/alert/{alertId}
Delete an existing Alert. You need to provide the Alert ID.



# Get Alert History
Source: https://docs.tenderly.co/api-reference/alerts/get-alert-history

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/alert-history
Retrieve the execution history for all Alerts in a Tenderly project. 



# List Alerts
Source: https://docs.tenderly.co/api-reference/alerts/list-alerts

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/alerts
This endpoint allows you retrieve alerts for given project.



# Send test Alert
Source: https://docs.tenderly.co/api-reference/alerts/send-test-alert

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/test-alerts
This endpoint allows you test the execution of Alerts.



# Update Alert
Source: https://docs.tenderly.co/api-reference/alerts/update-alert

/api-reference/openapi.json patch /v1/account/{accountSlug}/project/{projectSlug}/alert/{alertId}
Update an existing Alert. You need to provide the Alert ID.



# Add contract to project
Source: https://docs.tenderly.co/api-reference/contracts/add-contract-to-project

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/address
Add a smart contract to a Tenderly project.

**Note**: If a contract is unverified on both Tenderly and external providers like Etherscan, Blockscout, or Routescan, it will be added to the project as **unverified**. However, if the contract is verified on an external provider, Tenderly will retrieve and apply the verification, subsequently adding the verified contract to the project.



# Add tag to mutiple contracts
Source: https://docs.tenderly.co/api-reference/contracts/add-tag-to-mutiple-contracts

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/tag
This endpoint allows you to tag multiple smart contracts.



# Delete contract from project
Source: https://docs.tenderly.co/api-reference/contracts/delete-contract-from-project

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}
Delete a smart contract from a Tenderly project. 



# Delete contract tag
Source: https://docs.tenderly.co/api-reference/contracts/delete-contract-tag

/api-reference/openapi.json delete /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}/tag
Delete a tag that has been added to a smart contract.



# Encode state overrides
Source: https://docs.tenderly.co/api-reference/contracts/encode-state-overrides

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/contracts/encode-states
Encode state overrides of the smart contract.



# Get all contracts in project
Source: https://docs.tenderly.co/api-reference/contracts/get-all-contracts-in-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/contracts
Get details for all smart contracts in a Tenderly project.



# Rename contract
Source: https://docs.tenderly.co/api-reference/contracts/rename-contract

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/contract/{networkId}/{address}/rename
This endpoint allows you to rename a smart contract.

**Note**: If a contract is unverified on both Tenderly and external providers like Etherscan, Blockscout, or Routescan, it will be added to the project as **unverified**. However, if the contract is verified on an external provider, Tenderly will retrieve and apply the verification, subsequently adding the verified contract to the project.



# List Delivery Channels
Source: https://docs.tenderly.co/api-reference/delivery-channels/list-delivery-channels

/api-reference/openapi.json get /v1/account/{accountSlug}/delivery-channels
Retrieves all configured delivery channels for an account.



# List Delivery Channels for project
Source: https://docs.tenderly.co/api-reference/delivery-channels/list-delivery-channels-for-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/delivery-channels
Retrieve all configured delivery channels associated with a specific project.



# Check supported networks
Source: https://docs.tenderly.co/api-reference/other/check-supported-networks

/api-reference/openapi.json get /v1/supported-networks
The endpoint returns the list of networks that are currently supported on the Tenderly platform and also returns information about features these networks are supported on as well as corresponding network slugs users can use for integration with Tenderly.



# Disable simulation sharing
Source: https://docs.tenderly.co/api-reference/simulator/disable-simulation-sharing

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/unshare
Call the `unshare` endpoint to disable public sharing for a simulated transaction from a specific account or project. You need to provide the ID of the simulated transaction.

Learn more about [sharing transactions](https://blog.tenderly.co/changelog/public-sharing-of-transactions-devnets-forks-and-simulations).



# Enable simulation sharing
Source: https://docs.tenderly.co/api-reference/simulator/enable-simulation-sharing

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/share
Call the `share` endpoint to enable the public sharing feature for a simulation ID from a specific account or project. Once enabled, simulation details become accessible to anyone with the link to the transaction simulation.

Example sharable link: `https://www.tdly.co/shared/simulation/{simulationId}`.

Learn more about [sharing transactions](https://blog.tenderly.co/changelog/public-sharing-of-transactions-devnets-forks-and-simulations).



# Fetch all simulated transactions
Source: https://docs.tenderly.co/api-reference/simulator/fetch-all-simulated-transactions

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/simulations
Call the `simulations` endpoint to get a list of all simulated transactions within an account and project.



# Get full simulated transaction details
Source: https://docs.tenderly.co/api-reference/simulator/get-full-simulated-transaction-details

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}
Get all the simulation details for a transaction from a specific account or project. This data includes details about the transaction, simulation details, list of contracts involved, and generated access list. You need to provide the ID of the simulated transaction. 



# Get quick simulated transaction details
Source: https://docs.tenderly.co/api-reference/simulator/get-quick-simulated-transaction-details

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/simulations/{simulationId}/info
Call the `info` endpoint to fetch only the `transaction_info` object for a simulated transaction from a specific account or project. The response also return the block header information and block override data as separate objects. You need to provide the ID of the simulated transaction. 

This endpoint returns the same data as the [Fetch full simulation details by transaction ID](https://docs.tenderly.co/reference/api#/operations/getSimulatedTransactionById) just formatted in a different way.



# Simulate bundled transactions
Source: https://docs.tenderly.co/api-reference/simulator/simulate-bundled-transactions

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulate-bundle
Call the `simulate-bundle` endpoint to simulate multiple consecutive transactions at once. You can simulate bundled transactions on real-time data from over [105+ supported networks](https://docs.tenderly.co/supported-networks-and-languages). This endpoint receive an array of transactions that get simulated one after another on the same block.

**Note:** If the initial transaction in the array changes the state, all subsequent transactions will be simulated against this modified state. Furthermore, should a simulation fail for any reason, all following simulations in the sequence will not be executed.

Learn more about [bundled simulations](https://docs.tenderly.co/simulations/bundled-simulations).

The response returns a `simulation_results` array, where each element corresponds to a simulation in the input array (in the same order). Each result contains the following objects:

`transaction`: Contains data related to the simulated transaction, including its hash, block number, origin and destination addresses, gas details, input data, nonce, and other transaction details, like the status, timestamp, and involved contract addresses. The nested `transaction_info` object holds detailed execution data such as the call trace, emitted logs, state diffs, and asset changes.

`simulation`: Contains metadata about this simulation within the bundle, including its unique ID, project and owner IDs, block number, gas used, the method invoked, simulation status, state overrides applied, and other metadata.

`contracts`: Contains data about the contract(s) involved in the transaction, including the contract's ID, network ID, balance, verification status, associated standards (like ERC20), token-specific data if the contract is a token, compiler version, and even the source code of the contract in some cases.

`generated_access_list`: Contains a list of addresses and storage keys that the transaction will access, enabling certain gas cost optimizations. The access list is a feature introduced in [Ethereum's EIP-2930](https://eips.ethereum.org/EIPS/eip-2930).



# Simulate transaction
Source: https://docs.tenderly.co/api-reference/simulator/simulate-transaction

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/simulate
Call the `simulate` endpoint to preview the outcomes a single transaction before sending it to the live network. You can simulate transactions with custom parameters on [105+ supported networks](https://docs.tenderly.co/supported-networks-and-languages). The output provides detailed insights into emitted events, state changes, asset and balance changes, among other things. 

Learn about [single transaction simulations](https://docs.tenderly.co/simulations/single-simulations).

The response returns the following objects:

`transaction`: Contains data related to the transaction, including its hash, block number, origin and destination addresses, gas details, input data, nonce, and other transaction details, like the status, timestamp, and involved contract addresses.

`simulation`: Contains data about the simulated transaction. It provides details related to the ID of the simulation, project and owner IDs, block number where the transaction was included, gas used, method invoked, simulation status, and other metadata.

`contracts`: Contains data about the contract(s) involved in the transaction, including the contract's ID, network ID, balance, verification status, associated standards (like ERC20), token-specific data if the contract is a token, compiler version, and even the source code of the contract in some cases.

`generated_access_list`: Contains a list of addresses and storage keys that the transaction will access, enabling certain gas cost optimizations. The access list is a feature introduced in [Ethereum's EIP-2930](https://eips.ethereum.org/EIPS/eip-2930).



# Batch Delete Environments
Source: https://docs.tenderly.co/api-reference/virtual-environments/batch-delete-environments

/api-reference/openapi.json delete /public/v1/account/{accountSlug}/project/{projectSlug}/environments
Permanently delete multiple environments by ID



# Create Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/create-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments
Create a new multi-chain environment with Virtual Environments across specified networks



# Delete Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/delete-environment

/api-reference/openapi.json delete /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}
Permanently delete a single environment by ID



# Get Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}
Get a single environment by ID



# Get Environment Instance Transaction
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment-instance-transaction

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/transactions/{txHash}
Get a single transaction from an environment instance by transaction hash



# Get Environment Instance Transactions
Source: https://docs.tenderly.co/api-reference/virtual-environments/get-environment-instance-transactions

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/transactions
Get transactions across all Virtual Environments in an environment instance, with pagination and optional filters by status, category, kind, from/to address.



# List Environments
Source: https://docs.tenderly.co/api-reference/virtual-environments/list-environments

/api-reference/openapi.json get /public/v1/account/{accountSlug}/project/{projectSlug}/environments
List all multi-chain environments for the given account and project



# Send Transaction on Environment Virtual Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/send-transaction-on-environment-virtual-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/vnet/{vnetId}/transactions
Send a transaction to be executed on a specific Virtual Environment within an environment instance



# Simulate Transaction on Environment Virtual Environment
Source: https://docs.tenderly.co/api-reference/virtual-environments/simulate-transaction-on-environment-virtual-environment

/api-reference/openapi.json post /public/v1/account/{accountSlug}/project/{projectSlug}/environments/{environmentId}/instance/{instanceId}/vnet/{vnetId}/transactions/simulate
Simulate a transaction on a specific Virtual Environment within an environment instance. State is not preserved. Supports block overrides, state overrides, and a custom block number. The richer response includes asset changes, balance changes, exposure changes, state changes, and cross-chain interop information.



# Add wallet to project
Source: https://docs.tenderly.co/api-reference/wallets/add-wallet-to-project

/api-reference/openapi.json post /v1/account/{accountSlug}/project/{projectSlug}/wallet
This endpoint allows you to add a wallet address to your Tenderly project.



# Get wallet in project
Source: https://docs.tenderly.co/api-reference/wallets/get-wallet-in-project

/api-reference/openapi.json get /v1/account/{accountSlug}/project/{projectSlug}/wallet/{address}/network/{networkId}
This endpoint allows you to get a single wallet for your Tenderly project.