Simulation Endpoints

The CoW Protocol provides simulation endpoints that leverage Tenderly to test transaction bundles before on-chain execution. These endpoints deliver comprehensive insights into state modifications, balance adjustments, and gas consumption.

POST //simulation/simulateBundle

Simulates a bundle of transactions in sequence and returns detailed execution information.

Path Parameters

chainId (string, required): The blockchain network ID (e.g., 1, 100, 11155111)

Request Body

An array of transaction objects:

Field	Type	Required	Description
from	string	Yes	Sender’s address
to	string	Yes	Recipient address
input	string	Yes	Encoded transaction data
value	string	No	ETH value to send (in wei)
gas	number	No	Gas limit
gas_price	string	No	Gas price (in wei)

Response

Field	Type	Description
status	boolean	Whether simulation succeeded
cumulativeBalancesDiff	object	Net token balance changes per address
stateDiff	array	Low-level storage modifications with original/updated values
gasUsed	string	Gas consumption for the transaction
link	string	Tenderly dashboard URL for detailed analysis

Code Examples

curl -X POST "https://api.cow.fi/1/simulation/simulateBundle" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "from": "0x1234567890abcdef1234567890abcdef12345678",
      "to": "0xabcdef1234567890abcdef1234567890abcdef12",
      "input": "0x095ea7b3...",
      "value": "0",
      "gas": 100000
    }
  ]'

const transactions = [
  {
    from: '0x1234567890abcdef1234567890abcdef12345678',
    to: '0xabcdef1234567890abcdef1234567890abcdef12',
    input: '0x095ea7b3...',
    value: '0',
    gas: 100000
  }
];

const response = await fetch(
  'https://api.cow.fi/1/simulation/simulateBundle',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(transactions)
  }
);
const result = await response.json();
console.log('Simulation status:', result.status);
console.log('Gas used:', result.gasUsed);

import requests
import json

transactions = [
    {
        "from": "0x1234567890abcdef1234567890abcdef12345678",
        "to": "0xabcdef1234567890abcdef1234567890abcdef12",
        "input": "0x095ea7b3...",
        "value": "0",
        "gas": 100000
    }
]

response = requests.post(
    'https://api.cow.fi/1/simulation/simulateBundle',
    headers={'Content-Type': 'application/json'},
    data=json.dumps(transactions)
)
result = response.json()
print(f"Status: {result['status']}")

Response Example

{
  "status": true,
  "gasUsed": "85000",
  "link": "https://dashboard.tenderly.co/...",
  "cumulativeBalancesDiff": {
    "0x1234...": {
      "0xA0b8...": "-1000000"
    },
    "0xabcd...": {
      "0xA0b8...": "1000000"
    }
  },
  "stateDiff": [
    {
      "address": "0xA0b8...",
      "key": "0x...",
      "original": "0x...",
      "updated": "0x..."
    }
  ]
}

Notes

Use Cases

Simulations enable verification of:

Sufficient balance and allowance for order execution
Expected token transfers and balance changes
Price impact and slippage before committing
Multi-step operations like approve + swap sequences and flash loans
Accurate gas estimates for complex transactions

Supported Networks

Tenderly-compatible EVM chains:

Ethereum Mainnet (1)
Gnosis Chain (100)
Sepolia (11155111)

Important Limitations

Simulations use current blockchain state; pending transactions are not included
Network fluctuations, MEV, and sandwich attacks are not accounted for
Gas estimates should include a safety buffer (+20%) when executing actual transactions

Tenderly Configuration

The simulation endpoint requires Tenderly credentials:

TENDERLY_API_KEY=your_api_key
TENDERLY_PROJECT_NAME=your_project
TENDERLY_ORG_NAME=your_organization

Error Handling

Status	Reason	Solution
400	Invalid input	Verify transaction parameters
500	Simulation failed	Check Tenderly configuration
502	Tenderly unavailable	Retry after a short delay

Best Practices

Validate inputs: Ensure all transaction parameters are correctly encoded
Add gas buffer: Use simulation gas + 20% for actual transactions
Check balance diffs: Verify expected token movements before executing
Use the Tenderly link: For detailed debugging of failed simulations
Handle failures gracefully: Simulations may fail for valid reasons (insufficient balance, etc.)

BFF

Services

Watch Tower

Simulation Endpoints

Simulation Endpoints

POST //simulation/simulateBundle

Path Parameters

Request Body

Response

Code Examples

Response Example

Notes

Use Cases

Supported Networks

Important Limitations

Tenderly Configuration

Error Handling

Best Practices

​Simulation Endpoints

​POST //simulation/simulateBundle

​Path Parameters

​Request Body

​Response

​Code Examples

​Response Example

​Notes

​Use Cases

​Supported Networks

​Important Limitations

​Tenderly Configuration

​Error Handling

​Best Practices

Simulation Endpoints

POST //simulation/simulateBundle

Path Parameters

Request Body

Response

Code Examples

Response Example

Notes

Use Cases

Supported Networks

Important Limitations

Tenderly Configuration

Error Handling

Best Practices