Skip to main content

API Integration

The CoW Protocol API provides direct access to the protocol's functionality through RESTful endpoints. This approach offers maximum flexibility and control for backend integrations and custom implementations.

Overview​

The API integration allows you to interact with CoW Protocol at the lowest level, giving you complete control over order management, quote fetching, and trade execution. This is ideal for advanced integrations, backend services, and custom trading logic.

Key APIs​

Order Book API​

The primary API for creating and managing orders on CoW Protocol.

  • Base URL: https://api.cow.fi/
  • Purpose: Quote generation, order submission, order management
  • Authentication: No API key required for basic operations

Key Endpoints​

  • POST /api/v1/quote - Get trading quotes
  • POST /api/v1/quote/stream - Stream progressively improving quotes as solvers respond (SSE)
  • POST /api/v1/orders - Submit signed orders
  • GET /api/v1/orders/{uid} - Get order details
  • DELETE /api/v1/orders/{uid} - Cancel orders
  • GET /api/v1/trades - Get trade history

Quick Start Example​

1. Get a Quote​

curl -X POST "https://api.cow.fi/mainnet/api/v1/quote" \
  -H "Content-Type: application/json" \
  -d '{
    "sellToken": "0xA0b86a33E6411Ec5d0b9dd2E7dC15A9CAA6C1F8e",
    "buyToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "sellAmountBeforeFee": "1000000",
    "kind": "sell",
    "from": "0xYourWalletAddress"
  }'

2. Sign and Submit Order​

// After getting a quote, sign the order
const order = {
  ...quoteResponse,
  signature: await signOrder(quoteResponse, signer),
  signingScheme: "eip712"
}

// Submit the signed order
const response = await fetch('https://api.cow.fi/mainnet/api/v1/orders', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(order)
})

const orderId = await response.text()

3. Monitor Order Status​

// Check order status
const orderResponse = await fetch(
  `https://api.cow.fi/mainnet/api/v1/orders/${orderId}`
)
const orderDetails = await orderResponse.json()

console.log('Order status:', orderDetails.status)

Streaming Quotes​

POST /api/v1/quote/stream takes the same request body as POST /api/v1/quote, but returns a Server-Sent Events stream instead of a single response. The first event arrives as soon as the fastest solver responds, and after that a quote is only emitted when it ranks better than the best one already sent, so the client can show a price immediately and every update improves on the last.

Each event's data is an OrderQuoteResponse, the same shape POST /api/v1/quote returns. The id on each event can be passed as quoteId when placing an order, the same as a quote from POST /api/v1/quote. The endpoint always queries all solvers and attempts verification (the request's priceQuality is ignored), and each event carries its own verified flag. A verified quote ranks above an unverified one regardless of the quoted amount, because unverified quotes often over-promise; a later event may therefore report a slightly worse price than an earlier one when it is the first verified quote. Solvers without a usable quote, and quotes that do not beat the best already sent, emit no event, so the stream may contain fewer events than there are solvers. Individual solver failures are not streamed; only if no solver returns a usable quote at all does the server send a final error event with a PriceEstimationError body (for example NoLiquidity), then close.

Because every event improves on the previous one, the last event received when the stream closes is the best available quote — clients do not need to rank events themselves.

curl -N -X POST "https://api.cow.fi/mainnet/api/v1/quote/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "sellToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "buyToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "sellAmountBeforeFee": "1000000000000000000",
    "kind": "sell",
    "from": "0xYourWalletAddress"
  }'

Choosing a timeout​

The first quote is delivered as soon as the fastest solver responds, so a usable price arrives faster than with POST /api/v1/quote, which waits for the whole competition. Streaming does not make any solver compute faster, though. The final quote is only as good as the responses that arrived before the stream was closed, and the timeout sets that boundary.

The stream stays open until the request timeout elapses or every solver has responded. Slower solvers sometimes return a better price, especially on thin or unusual pairs that only one or two solvers can quote. A short timeout returns sooner, but it can yield a worse quote or none at all. A longer timeout gives the competition time to find a better price.

This tradeoff is controlled by the client through the timeout. The value is set (in milliseconds) on the request, or the connection is closed once a good-enough quote has arrived.

The table below is a starting point, not a guarantee. The values should be measured against real traffic and raised for pairs that only slower solvers can price. Response times also differ by network, and these values shift as solver performance changes (guidance as of 2026-06).

Networktimeout (ms)
Base, Gnosis Chain, Linea1000
Mainnet, BNB Chain1800
Arbitrum, Polygon, Avalanche, Ink2500

Network Endpoints​

CoW Protocol APIs are available on multiple networks:

  • Mainnet: https://api.cow.fi/mainnet/api/v1/
  • Gnosis Chain: https://api.cow.fi/xdai/api/v1/
  • Arbitrum: https://api.cow.fi/arbitrum_one/api/v1/
  • Base: https://api.cow.fi/base/api/v1/
  • Sepolia (Testnet): https://api.cow.fi/sepolia/api/v1/

Order Signing​

Orders must be cryptographically signed before submission. The signing process involves:

  1. EIP-712 Domain: Chain-specific domain separator
  2. Order Struct: Structured order data
  3. Signature: ECDSA signature or pre-signed order
import { ethers } from 'ethers'

// Example order signing with ethers.js
const domain = {
  name: 'Gnosis Protocol',
  version: 'v2',
  chainId: 1,
  verifyingContract: '0x9008D19f58AAbD9eD0D60971565AA8510560ab41'
}

const types = {
  Order: [
    { name: 'sellToken', type: 'address' },
    { name: 'buyToken', type: 'address' },
    { name: 'receiver', type: 'address' },
    // ... other order fields
  ]
}

const signature = await signer._signTypedData(domain, types, orderData)

Error Handling​

The API returns standard HTTP status codes:

  • 200: Success
  • 400: Bad Request (invalid parameters)
  • 404: Order not found
  • 429: Rate limited
  • 500: Internal server error
try {
  const response = await fetch(apiUrl, requestOptions)

  if (!response.ok) {
    const error = await response.json()
    throw new Error(`API Error: ${error.description}`)
  }

  return await response.json()
} catch (error) {
  console.error('Order submission failed:', error)
}

When to Use the API​

  • Backend integration: Server-side order management
  • Custom trading logic: Advanced order types and strategies
  • High-frequency trading: Programmatic order placement
  • Multi-chain applications: Cross-chain arbitrage and liquidity
  • Analytics platforms: Order and trade data analysis

Rate Limits​

  • Quote requests: 10 requests/second
  • Order submission: 5 requests/second
  • General endpoints: 100 requests/minute

Next Steps​

For complete API documentation including all endpoints, parameters, and response schemas, see:

Resources​