> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cow.bleu.builders/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate CoW Protocol

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

<div style={{ background: 'linear-gradient(135deg, #012F7A 0%, #3F80FF 100%)', borderRadius: '12px', padding: '2rem', marginBottom: '2rem', color: 'white' }}>
  <h2 style={{ color: 'white', marginTop: 0 }}>Four ways to integrate</h2>
  <p style={{ opacity: 0.9, color: 'white' }}>Whether you need a quick drop-in solution or full control over the trading stack, there's an integration path for you.</p>
</div>

## 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](#widget-integration)**      | Minutes           |
| Are building a custom trading UI in TypeScript/JavaScript                                                                             | **[TypeScript SDK](#sdk-integration)** | Hours             |
| Are building a trading bot, automation, or data pipeline in Python                                                                    | **[Python SDK](#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](#api-integration)**       | Days              |

<Note>
  **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.
</Note>

## 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

<Card title="Widget" icon="window" href="/cow-swap/widget/overview">
  Pre-built trading interface you can embed in any web app
</Card>

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](https://widget.cow.fi)

```typescript theme={null}
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

<Card title="TypeScript SDK" icon="code" href="/cow-sdk/quickstart">
  TypeScript SDK with multiple levels of abstraction
</Card>

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

```bash theme={null}
npm install @cowprotocol/cow-sdk
```

```typescript theme={null}
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](/cow-sdk/guides/creating-swap-orders) — market orders with automatic quoting
* [Creating Limit Orders](/cow-sdk/guides/creating-limit-orders) — price-specific orders
* [Token Approvals](/cow-sdk/guides/token-approvals) — managing ERC-20 approvals
* [Order Management](/cow-sdk/guides/order-management) — tracking and cancelling orders

<Accordion title="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
</Accordion>

## Python SDK

<Card title="cow-py" icon="python" href="/cow-py/quickstart">
  Python SDK for trading bots, data analysis, and automation
</Card>

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

```bash theme={null}
pip install cowdao-cowpy
```

```python theme={null}
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

<Card title="REST API" icon="square-terminal" href="/cow-protocol/howto/integrate/api">
  Direct HTTP access to the Orderbook API
</Card>

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

```bash theme={null}
# 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.

<Warning>
  The API requires handling order signing, fee computation, and settlement monitoring yourself. The [API Integration Guide](/cow-protocol/howto/integrate/api) covers the complete flow step-by-step. For most use cases, the SDKs provide a faster path to production.
</Warning>

## Testing your integration

All integration paths should be tested on Sepolia before going to production. See the **[Testing Guide](/cow-protocol/howto/integrate/testing)** for the step-by-step process: get test tokens, approve, place a test order, verify settlement, then graduate to mainnet.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Widget tutorial" icon="window" href="/cow-swap/widget/overview">
    Step-by-step widget setup
  </Card>

  <Card title="TypeScript SDK" icon="code" href="/cow-sdk/quickstart">
    Get trading in minutes
  </Card>

  <Card title="Python SDK" icon="python" href="/cow-py/quickstart">
    Swap tokens with one function call
  </Card>

  <Card title="API Integration Guide" icon="square-terminal" href="/cow-protocol/howto/integrate/api">
    Full step-by-step API guide
  </Card>
</CardGroup>