> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cow.bleu.builders/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulation Endpoints

> Endpoints for simulating transaction bundles before on-chain execution using Tenderly integration

# 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 /{chainId}/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

```bash theme={null}
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
    }
  ]'
```

```javascript theme={null}
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);
```

```python theme={null}
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

```json theme={null}
{
  "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:

```bash theme={null}
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

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.)