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

# Market Endpoints

> Endpoints for retrieving market data and slippage tolerance recommendations for trading pairs

# Market Endpoints

Endpoints for retrieving market data and slippage tolerance recommendations for trading pairs.

## Get Slippage Tolerance

Retrieves the recommended slippage tolerance for a trading pair based on market volatility.

**Endpoint:** `GET /{chainId}/markets/{baseTokenAddress}-{quoteTokenAddress}/slippageTolerance`

### Path Parameters

* **chainId** (string, required): The blockchain network ID (e.g., `1`, `100`, `11155111`)
* **baseTokenAddress** (string, required): Currency that is being bought or sold (the token you're trading)
* **quoteTokenAddress** (string, required): Currency in which the price of the base token is quoted (the token you're trading for)

### Query Parameters (Optional)

| Parameter               | Type    | Description                               |
| ----------------------- | ------- | ----------------------------------------- |
| orderKind               | string  | Type of order: `buy` or `sell`            |
| partiallyFillable       | boolean | Whether the order can be partially filled |
| sellAmount              | string  | Amount to sell in token units             |
| buyAmount               | string  | Amount to buy in token units              |
| expirationTimeInSeconds | number  | Order expiration time in seconds          |
| feeAmount               | string  | Fee amount in token units                 |

### Response

| Field       | Type   | Description                                            |
| ----------- | ------ | ------------------------------------------------------ |
| slippageBps | number | Slippage tolerance in basis points. Min: 0, Max: 10000 |

### Code Examples

```bash theme={null}
curl "https://api.cow.fi/1/markets/0x6b175474e89094c44da98b954eedeac495271d0f-0x2260fac5e5542a773aa44fbcfedf7c193bc2c599/slippageTolerance"
```

```javascript theme={null}
const baseToken = '0x6b175474e89094c44da98b954eedeac495271d0f'; // DAI
const quoteToken = '0x2260fac5e5542a773aa44fbcfedf7c193bc2c599'; // WBTC

const response = await fetch(
  `https://api.cow.fi/1/markets/${baseToken}-${quoteToken}/slippageTolerance`
);
const data = await response.json();
console.log(`Recommended slippage: ${data.slippageBps / 100}%`);
```

```python theme={null}
import requests

base_token = '0x6b175474e89094c44da98b954eedeac495271d0f'  # DAI
quote_token = '0x2260fac5e5542a773aa44fbcfedf7c193bc2c599'  # WBTC

response = requests.get(
    f'https://api.cow.fi/1/markets/{base_token}-{quote_token}/slippageTolerance'
)
data = response.json()
print(f"Recommended slippage: {data['slippageBps'] / 100}%")
```

### Response Example

```json theme={null}
{
  "slippageBps": 50
}
```

This response indicates a recommended slippage tolerance of 0.5% (50 basis points).

***

## Get Volatility Details (Internal)

**Endpoint:** `GET /{chainId}/markets/{baseTokenAddress}-{quoteTokenAddress}/volatilityDetails`

<Note>
  This endpoint is marked as `hide: true` in the API schema and is intended for internal debugging purposes. It may not be available in production environments.
</Note>

Retrieves detailed volatility information for both tokens in a trading pair.

***

## Notes

### Understanding Basis Points

Basis points (bps) are a unit of measure used in finance to describe percentages:

* 1 basis point = 0.01%
* 100 basis points = 1%
* 10,000 basis points = 100%

**Common slippage values:**

| Basis Points | Percentage | Use Case                             |
| ------------ | ---------- | ------------------------------------ |
| 10           | 0.1%       | Very stable pairs (e.g., USDC/DAI)   |
| 50           | 0.5%       | Stable liquid pairs (e.g., ETH/USDC) |
| 100          | 1%         | Standard liquid pairs                |
| 200-500      | 2-5%       | Less liquid or volatile pairs        |
| 1000+        | 10%+       | Highly volatile or illiquid pairs    |

### Market Notation

The market is specified as `{base}-{quote}` where:

* **Base token**: The asset you're trading (buying or selling)
* **Quote token**: The asset used to price the base token

Example: `DAI-WBTC` means DAI priced in WBTC

### Slippage Calculation Algorithm

The API calculates slippage tolerance based on:

1. **Historical volatility**: Price movements over recent time periods
2. **Liquidity depth**: Available liquidity in the market
3. **Market conditions**: Current market volatility metrics

### Caching

Slippage tolerance responses are cached for **120 seconds** (2 minutes):

```
Cache-Control: public, max-age=120
```

### Order-Specific Slippage

For more accurate slippage recommendations, include optional query parameters:

```bash theme={null}
curl "https://api.cow.fi/1/markets/0x6b175474e89094c44da98b954eedeac495271d0f-0x2260fac5e5542a773aa44fbcfedf7c193bc2c599/slippageTolerance?orderKind=sell&sellAmount=1000000000000000000000&expirationTimeInSeconds=1800"
```

### Error Handling

| Status Code | Reason                  | Solution                                     |
| ----------- | ----------------------- | -------------------------------------------- |
| 400         | Invalid token address   | Verify both addresses are valid              |
| 404         | Market data unavailable | Pair may not have sufficient trading history |
| 500         | Service error           | Retry after a short delay                    |

### Best Practices

1. **Use recommended slippage**: The API's recommendation balances trade success vs. slippage cost
2. **Adjust for urgency**: Increase slippage for faster execution in volatile markets
3. **Consider order size**: Larger orders may need higher slippage tolerance
4. **Cache responsibly**: Respect cache headers to reduce API load
5. **Handle errors**: Fall back to conservative default (e.g., 1-2%) if API is unavailable