Simulating Transactions

The simulate endpoint executes your transaction on a forked EVM state and returns predicted output amounts, gas consumed, and a simulationId for subsequent validation.

POST https://quoter.api.enso.build/api/v1/simulate

To simulate multiple transactions in one request (same tokenIn, tokenOut, and amountIn), use the batch endpoint:

POST https://quoter.api.enso.build/api/v1/simulate/batch

Pass transactions (an array of TransactionDto) instead of transaction. The response contains a results array in the same order — each item has the same shape as a single /simulate response, with its own simulationId for /validate. Up to 5 transactions per request.

curl -X POST https://quoter.api.enso.build/api/v1/simulate/batch \
  -H "Authorization: Bearer $ENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 1,
    "transactions": [
      {
        "data": "0x3593564c...",
        "value": "1000000000000000000",
        "to": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
        "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
      },
      {
        "data": "0x472b43f3...",
        "value": "1000000000000000000",
        "to": "0xDef1C0ded9bec7F1a1670819833240f027b25FDF",
        "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
      }
    ],
    "tokenIn": ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"],
    "tokenOut": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
    "amountIn": ["1000000000000000000"]
  }'

Request Parameters

Top-level fields

Field	Type	Required	Description
`chainId`	`number`	Yes	Chain ID (e.g., `1` for Ethereum, `42161` for Arbitrum)
`transaction`	`TransactionDto`	Yes	The transaction to simulate (see below)
`tokenIn`	`string[]`	Yes	Input token addresses
`tokenOut`	`string[]`	Yes	Output token addresses to track
`amountIn`	`string[]`	Yes	Input amounts in wei (one per `tokenIn`)
`preSimulationTransactions`	`TransactionDto[]`	No	Setup transactions to run before the main simulation

Transaction fields

Field	Type	Required	Description
`data`	`string`	Yes	Hex-encoded calldata
`value`	`string`	Yes	Native token value in wei
`to`	`string`	Yes	Target contract address
`from`	`string`	Yes	Sender address
`operationType`	`number`	No	`0` = Call (default), `1` = DelegateCall
`receiver`	`string`	No	Token receiver address (if different from sender)
`spender`	`string`	No	Address that needs to be approved on each `tokenIn` to perform simulation
`executor`	`string`	No	Contract executor address
`origin`	`string`	No	Original caller address
`authorityDelegate`	`string`	No	Delegation authority address
`initCode`	`string`	No	Init code for contract creation

Response

Field	Type	Description
`simulationId`	`string`	UUID for this simulation. Use with `/validate`.
`chainId`	`number`	Chain ID the simulation ran on
`result.status`	`"Success" \| "Error"`	Whether the simulated transaction would succeed
`result.amountOut`	`string[]`	Predicted output amounts in wei (one per `tokenOut`)
`result.gas`	`string`	Gas consumed during simulation
`result.error`	`object`	Error details when `status` is `"Error"`

Examples

Token Swap
Vault Deposit
DelegateCall

Simulate a swap from ETH to USDC on Ethereum mainnet.

curl -X POST https://quoter.api.enso.build/api/v1/simulate \
  -H "Authorization: Bearer $ENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 1,
    "transaction": {
      "data": "0x3593564c...",
      "value": "1000000000000000000",
      "to": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
      "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
    },
    "tokenIn": ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"],
    "tokenOut": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
    "amountIn": ["1000000000000000000"]
  }'

const simulation = await fetch("https://quoter.api.enso.build/api/v1/simulate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${ENSO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    chainId: 1,
    transaction: {
      data: "0x3593564c...",
      value: "1000000000000000000",
      to: "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
      from: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    },
    tokenIn: ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"],
    tokenOut: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
    amountIn: ["1000000000000000000"],
  }),
}).then((res) => res.json());

Simulate depositing USDC into a Yearn vault.

curl -X POST https://quoter.api.enso.build/api/v1/simulate \
  -H "Authorization: Bearer $ENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 1,
    "transaction": {
      "data": "0x6e553f65...",
      "value": "0",
      "to": "0xa354F35829Ae975e850e23e9615b11Da1B3dC4DE",
      "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
    },
    "tokenIn": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
    "tokenOut": ["0xa354F35829Ae975e850e23e9615b11Da1B3dC4DE"],
    "amountIn": ["1000000000"]
  }'

const simulation = await fetch("https://quoter.api.enso.build/api/v1/simulate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${ENSO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    chainId: 1,
    transaction: {
      data: "0x6e553f65...",
      value: "0",
      to: "0xa354F35829Ae975e850e23e9615b11Da1B3dC4DE",
      from: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    },
    tokenIn: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
    tokenOut: ["0xa354F35829Ae975e850e23e9615b11Da1B3dC4DE"],
    amountIn: ["1000000000"],
  }),
}).then((res) => res.json());

Simulate with operationType: 1 for smart account (DelegateCall) execution.

curl -X POST https://quoter.api.enso.build/api/v1/simulate \
  -H "Authorization: Bearer $ENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 1,
    "transaction": {
      "data": "0x3593564c...",
      "value": "0",
      "to": "0x80EbA3855878739F4710233A8a19d89Bdd2ffB8E",
      "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "operationType": 1
    },
    "tokenIn": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
    "tokenOut": ["0xdAC17F958D2ee523a2206206994597C13D831ec7"],
    "amountIn": ["1000000000"]
  }'

const simulation = await fetch("https://quoter.api.enso.build/api/v1/simulate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${ENSO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    chainId: 1,
    transaction: {
      data: "0x3593564c...",
      value: "0",
      to: "0x80EbA3855878739F4710233A8a19d89Bdd2ffB8E",
      from: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      operationType: 1,
    },
    tokenIn: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
    tokenOut: ["0xdAC17F958D2ee523a2206206994597C13D831ec7"],
    amountIn: ["1000000000"],
  }),
}).then((res) => res.json());

Handling Simulation Errors

When result.status is "Error", the result.error field contains details about why the transaction would fail. Common causes:

Contract revert — The transaction would revert on-chain (e.g., insufficient balance, failed require check)
Invalid calldata — The data field doesn’t match any function signature on the target contract
Out of gas — The transaction requires more gas than available

const simulation = await fetch("https://quoter.api.enso.build/api/v1/simulate", {
  method: "POST",
  headers: { "Authorization": `Bearer ${ENSO_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify(request),
}).then((res) => res.json());

if (simulation.result.status === "Error") {
  console.error("Simulation failed:", simulation.result.error);
} else {
  console.log("Predicted output:", simulation.result.amountOut);
  console.log("Gas estimate:", simulation.result.gas);
}

See the Error Handling reference for a full list of error types and how to handle them.

Updated

Quoter

Guides

Reference

API Reference

Request Parameters

Top-level fields

Transaction fields

Response

Examples

Handling Simulation Errors

​Request Parameters

​Top-level fields

​Transaction fields

​Response

​Examples

​Handling Simulation Errors

Request Parameters

Top-level fields

Transaction fields

Response

Examples

Handling Simulation Errors