API Integration

Integrate CoW Protocol through RESTful API endpoints for maximum flexibility in backend 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/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)

Network Endpoints

CoW Protocol APIs are available on all supported networks:

Network	Production	Staging
Ethereum	https://api.cow.fi/mainnet/api/v1/	https://barn.api.cow.fi/mainnet/api/v1/
Gnosis Chain	https://api.cow.fi/xdai/api/v1/	https://barn.api.cow.fi/xdai/api/v1/
Arbitrum One	https://api.cow.fi/arbitrum_one/api/v1/	https://barn.api.cow.fi/arbitrum_one/api/v1/
Base	https://api.cow.fi/base/api/v1/	https://barn.api.cow.fi/base/api/v1/
Avalanche	https://api.cow.fi/avalanche/api/v1/	https://barn.api.cow.fi/avalanche/api/v1/
Polygon	https://api.cow.fi/polygon/api/v1/	https://barn.api.cow.fi/polygon/api/v1/
Lens	https://api.cow.fi/lens/api/v1/	https://barn.api.cow.fi/lens/api/v1/
BNB	https://api.cow.fi/bnb/api/v1/	https://barn.api.cow.fi/bnb/api/v1/
Linea	https://api.cow.fi/linea/api/v1/	https://barn.api.cow.fi/linea/api/v1/
Plasma	https://api.cow.fi/plasma/api/v1/	https://barn.api.cow.fi/plasma/api/v1/
Ink	https://api.cow.fi/ink/api/v1/	https://barn.api.cow.fi/ink/api/v1/
Sepolia	https://api.cow.fi/sepolia/api/v1/	https://barn.api.cow.fi/sepolia/api/v1/

Staging (barn) endpoints run the latest pre-release version and are useful for testing. Use production endpoints for live integrations.

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

For per-endpoint limits, backoff strategies, Cloudflare WAF details, and troubleshooting, see the Rate Limits & Quotas reference.

Error Handling

For a comprehensive list of every API error code with root causes and fixes, see the Error Reference. Key errors to handle:

Error	When	Quick fix
SellAmountDoesNotCoverFee	Quote request	Increase sell amount
NoLiquidity	Quote request	Check token addresses and liquidity
InvalidSignature	Order submission	Verify EIP-712 domain and signer match
InsufficientAllowance	Order submission	Approve VaultRelayer (0xC92E8bdf79f0507f65a392b0ab4667716BFE0110)
InsufficientBalance	Order submission	Check sell token balance covers amount

sellAmountBeforeFee vs sellAmount

A common source of confusion:

• sellAmountBeforeFee — used in the quote request. This is the total amount you want to sell, before any fees.
• sellAmount in the quote response — the sell amount after network costs have been deducted.
• feeAmount in the response — the network cost, in sell token units.

The relationship: sellAmountBeforeFee = response.sellAmount + response.feeAmount

For the full fee pipeline (how protocol fees, partner fees, and slippage transform these amounts), see the Fee Model.

Understanding Quotes and Fees

The quote response contains fee breakdowns and amount stages that are essential for building correct orders:

• Quote Selection — priceQuality options (fast/optimal/verified), timing between quote and order, freshness best practices
• How Intents Are Formed — detailed breakdown of feeAmount, sellAmount, buyAmount, the full fee pipeline (network costs → protocol fee → partner fee → slippage), and how to construct the final signed order

Market Orders vs Limit Orders

The API supports both order types. The difference is in how you construct the order, not which endpoint you call:

• Market (swap) orders — Fetch a quote first, then sign with the quoted amounts and a slippage tolerance. See Creating Swap Orders.
• Limit orders — You specify both sellAmount and buyAmount directly (no quote needed). The order fills when the market reaches your price. See Creating Limit Orders.

Both order types are submitted to the same POST /api/v1/orders endpoint.

Next Steps

• Quickstart: Raw API (cURL) — End-to-end walkthrough: quote → sign → submit → monitor
• Order Book API Reference — Complete endpoint documentation with all parameters and response schemas
• API Explorer — Interactive API documentation

Resources

• Order Book API Reference — Detailed API documentation
• API Explorer — Interactive documentation
• Rate Limits & Quotas — Per-endpoint limits, backoff code, and troubleshooting
• Quote Selection — Quoting strategies and timing
• How Intents Are Formed — Fee pipeline and order construction
• Order Signing Guide — Cryptographic signing details
• GitHub Examples — Code examples