API Integration

​

Overview

​

Key APIs

​

Order Book API

• 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

​

Order Signing

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

• 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

​

Error Handling

​

sellAmountBeforeFee vs sellAmount

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

​

Understanding Quotes and Fees

• 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

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

​

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