> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enso.build/llms.txt
> Use this file to discover all available pages before exploring further.
# Simulating Transactions
> Simulate any EVM transaction to predict output amounts and gas consumption.
export const date_0 = "2026-04-07"
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
| 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 | Spender address for token approvals |
| `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
Simulate a swap from ETH to USDC on Ethereum mainnet.
```bash cURL theme={null}
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"]
}'
```
```typescript TypeScript theme={null}
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({
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.
```bash cURL theme={null}
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": "0x6e553f65...",
"value": "0",
"to": "0xa354F35829Ae975e850e23e9615b11Da1B3dC4DE",
"from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
},
"tokenIn": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
"tokenOut": ["0xa354F35829Ae975e850e23e9615b11Da1B3dC4DE"],
"amountIn": ["1000000000"]
}'
```
```typescript TypeScript theme={null}
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({
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.
```bash cURL theme={null}
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": "0",
"to": "0x80EbA3855878739F4710233A8a19d89Bdd2ffB8E",
"from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"operationType": 1
},
"tokenIn": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
"tokenOut": ["0xdAC17F958D2ee523a2206206994597C13D831ec7"],
"amountIn": ["1000000000"]
}'
```
```typescript TypeScript theme={null}
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({
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
```typescript theme={null}
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](/pages/shield/reference/error-handling) for a full list of error types and how to handle them.