Integrate CoW Protocol

CoW Protocol offers four integration approaches — from drop-in widget to full API control. Choose the path that fits your project.

Four ways to integrate

Whether you need a quick drop-in solution or full control over the trading stack, there’s an integration path for you.

Which approach should I use?

Start here. Answer the first question that applies:

If you…	Use	Time to integrate
Want to add a swap UI to a web app with minimal code	Widget	Minutes
Are building a custom trading UI in TypeScript/JavaScript	TypeScript SDK	Hours
Are building a trading bot, automation, or data pipeline in Python	Python SDK	Hours
Need full control from a backend service, use a language other than TS/Python, or need to understand the protocol at the lowest level	REST API	Days

Not sure? Start with the Widget if you just need a swap interface. Use the TypeScript SDK if you need programmatic control from a frontend or Node.js app. Use the API only if the SDKs don’t cover your use case.

Compare approaches

	Widget	SDK (TS)	SDK (Py)	API
Setup time	Minutes	Hours	Hours	Days
Language	JS (embed)	TypeScript	Python	Any
Custom UI	Theming only	Full control	N/A (backend)	Full control
Signing handled	Automatic	Automatic	Automatic	Manual
Fee computation	Automatic	Automatic	Automatic	Manual
Order monitoring	Built-in	SDK methods	SDK methods	Poll API
Order types	Swap, Limit, TWAP	Swap, Limit, TWAP, Programmatic	Swap, Limit, TWAP	All
Smart contract wallets	Supported	Supported	Supported	Manual

Widget Integration

Widget

Pre-built trading interface you can embed in any web app

The fastest way to add CoW Protocol trading to your application. The widget provides a complete, responsive trading interface that works out of the box.

• Zero configuration — works immediately with sensible defaults
• Responsive design — adapts to any container size
• Multi-network — supports all CoW Protocol chains
• Themeable — customize colors and styling to match your brand
• Interactive configurator — preview and generate code at widget.cow.fi

import { CowSwapWidget, CowSwapWidgetParams } from '@cowprotocol/widget-react'

const params: CowSwapWidgetParams = {
  appCode: 'My Dapp',
  width: '450px',
  height: '640px',
  sell: { asset: 'WETH' },
  buy: { asset: 'COW' },
}

<CowSwapWidget params={params} />

Best for: dApps that want a swap feature without building trading logic. DeFi dashboards, portfolio apps, NFT marketplaces.

SDK Integration

TypeScript SDK

TypeScript SDK with multiple levels of abstraction

For developers who want full control over the trading UI while leveraging CoW Protocol’s features programmatically. The SDK handles signing, fee computation, and order construction for you.

• Multiple abstraction levels — from high-level postSwapOrder() to low-level OrderBookApi
• Adapter support — works with Viem, Ethers v5, and Ethers v6
• Order management — create, sign, submit, cancel, and monitor orders
• All order types — market, limit, TWAP, and programmatic orders

npm install @cowprotocol/cow-sdk

import { TradingSdk, OrderKind } from '@cowprotocol/sdk-trading'

const sdk = new TradingSdk({ chainId: 1, appCode: 'my-app' }, {}, adapter)

const { orderId } = await sdk.postSwapOrder({
  kind: OrderKind.SELL,
  sellToken: WETH,
  sellTokenDecimals: 18,
  buyToken: USDC,
  buyTokenDecimals: 6,
  amount: '1000000000000000000', // 1 WETH
})

Best for: custom trading UIs, frontend dApps that need programmatic order control, Node.js backend services in TypeScript.

Key guides:

• Creating Swap Orders — market orders with automatic quoting
• Creating Limit Orders — price-specific orders
• Token Approvals — managing ERC-20 approvals
• Order Management — tracking and cancelling orders

When to use the SDK vs Widget

Use the SDK when you need to:

• Build a completely custom trading UI
• Implement complex trading logic (programmatic orders, hooks)
• Integrate into a backend service or bot
• Support smart contract wallets with custom signing

Use the Widget when you need to:

• Ship quickly with minimal development
• Provide a standard swap experience
• Minimize maintenance burden

Python SDK

cow-py

Python SDK for trading bots, data analysis, and automation

The Python SDK provides a high-level interface for CoW Protocol using web3.py and asyncio.

• One-call swaps — swap_tokens() handles quoting, signing, and submission
• Async/await — native asyncio support for concurrent operations
• Multi-chain — Ethereum, Gnosis, Arbitrum, Base, Polygon, Avalanche, BNB
• Type-safe — full type hints and Pydantic models
• Subgraph access — query trading data and analytics via GraphQL

pip install cowdao-cowpy

from cowdao_cowpy.cow.swap import swap_tokens
from cowdao_cowpy.common.chains import Chain

result = await swap_tokens(
    amount=sell_amount,
    account=account,
    chain=Chain.MAINNET,
    sell_token=SELL_TOKEN,
    buy_token=BUY_TOKEN,
)
print(f"Order: {result.uid}")

Best for: trading bots, automated strategies, data pipelines, backend services in Python.

API Integration

REST API

Direct HTTP access to the Orderbook API

Maximum flexibility for integrations that need full control over every aspect of the trading flow. You handle signing, fee computation, and order construction yourself.

• Full control — manage the entire order lifecycle via REST
• Language agnostic — works with any programming language
• Real-time data — access to orderbook state, auction data, and trade history

# Get a quote
curl -X POST "https://api.cow.fi/mainnet/api/v1/quote" \
  -H "Content-Type: application/json" \
  -d '{
    "sellToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "buyToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "sellAmountBeforeFee": "1000000000000000000",
    "kind": "sell",
    "from": "0xYourAddress"
  }'

Best for: backend services in languages other than TS/Python, custom order types, integrations that need protocol-level control.

The API requires handling order signing, fee computation, and settlement monitoring yourself. The API Integration Guide covers the complete flow step-by-step. For most use cases, the SDKs provide a faster path to production.

Testing your integration

All integration paths should be tested on Sepolia before going to production. See the Testing Guide for the step-by-step process: get test tokens, approve, place a test order, verify settlement, then graduate to mainnet.

---

Next steps

Widget tutorial

Step-by-step widget setup

TypeScript SDK

Get trading in minutes

Python SDK

Swap tokens with one function call

API Integration Guide

Full step-by-step API guide