Skip to main content

​
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:
FieldTypeRequiredDescription
fromstringYesSender’s address
tostringYesRecipient address
inputstringYesEncoded transaction data
valuestringNoETH value to send (in wei)
gasnumberNoGas limit
gas_pricestringNoGas price (in wei)

​
Response

FieldTypeDescription
statusbooleanWhether simulation succeeded
cumulativeBalancesDiffobjectNet token balance changes per address
stateDiffarrayLow-level storage modifications with original/updated values
gasUsedstringGas consumption for the transaction
linkstringTenderly 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

StatusReasonSolution
400Invalid inputVerify transaction parameters
500Simulation failedCheck Tenderly configuration
502Tenderly unavailableRetry after a short delay

​
Best Practices

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