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

curl "https://api.cow.fi/1/markets/0x6b175474e89094c44da98b954eedeac495271d0f-0x2260fac5e5542a773aa44fbcfedf7c193bc2c599/slippageTolerance"

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}%`);

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

{
  "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

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.

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:

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