Skip to main content
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://shield.api.enso.build/api/v1/simulate

​
Request Parameters

​
Top-level fields

FieldTypeRequiredDescription
chainIdnumberYesChain ID (e.g., 1 for Ethereum, 42161 for Arbitrum)
transactionTransactionDtoYesThe transaction to simulate (see below)
tokenInstring[]YesInput token addresses
tokenOutstring[]YesOutput token addresses to track
amountInstring[]YesInput amounts in wei (one per tokenIn)
preSimulationTransactionsTransactionDto[]NoSetup transactions to run before the main simulation

​
Transaction fields

FieldTypeRequiredDescription
datastringYesHex-encoded calldata
valuestringYesNative token value in wei
tostringYesTarget contract address
fromstringYesSender address
operationTypenumberNo0 = Call (default), 1 = DelegateCall
receiverstringNoToken receiver address (if different from sender)
spenderstringNoSpender address for token approvals
executorstringNoContract executor address
originstringNoOriginal caller address
authorityDelegatestringNoDelegation authority address
initCodestringNoInit code for contract creation

​
Response

FieldTypeDescription
simulationIdstringUUID for this simulation. Use with /validate.
chainIdnumberChain ID the simulation ran on
result.status"Success" | "Error"Whether the simulated transaction would succeed
result.amountOutstring[]Predicted output amounts in wei (one per tokenOut)
result.gasstringGas consumed during simulation
result.errorobjectError details when status is "Error"

​
Examples

Simulate a swap from ETH to USDC on Ethereum mainnet.
curl -X POST https://shield.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"]
  }'

​
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://shield.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