Links
Comment on page

Get started

Bring reliable, MEV-protected swaps to your users

CoW Widget

☀️ Website: https://cow.fi/widget
🛠️ Configurator: https://widget.cow.fi
Integrate the CoW Swap widget to bring seamless, MEV-protected trading to your website or dApp. Delight your users while adding an extra revenue stream for your project - it's a win-win.

Install

This library will work with any front-end technology. There are three flavors/libraries of the widget you can choose from:
  • NPM-based Application: If you have a web app that uses NPM for its dependencies:
    npm install @cowprotocol/widget-lib
  • React Applications: If your application is React, it will be easier to inject the ready-to-use widget from this other alternative library:
    npm install @cowprotocol/widget-react
  • Pure HTML: If your web doesn't use NPM, there's an easy way to include the widget. Make sure this is at the end of your <head /> tag:
    <script src="https://cdn.jsdelivr.net/npm/@cowprotocol/widget-lib@latest/index.iife.js"></script>
This tutorial assumes you continue with the NPM-based approach (@cowprotocol/widget-lib ), so if you choose the React Application or Pure HTML, although will be very similar, the easiest is to copy the snippets from https://widget.cow.fi and then continue with the configuration below.

Quick start

import { cowSwapWidget, CowSwapWidgetParams } from '@cowprotocol/widget-lib'
// HTML element where the widget will be rendered
const widgetContainer = document.getElementById('cowswap-widget')
const params: CowSwapWidgetParams = {
appCode: 'My Cool App', // Name of your app (max 50 characters)
width: 600, // Width in pixels (or 100% to use all available space)
height: 640,
sell: { asset: 'DAI' }, // Sell token. Optionally add amount for sell orders
buy: { asset: 'USDC', amount: '0.1' }, // Buy token. Optionally add amount for buy orders
}
cowSwapWidget(widgetContainer, params)

App Code

You must specify the appCode parameter when initializing the widget. This parameter is used to identify the source of orders.
The key must be a UTF8 string of up to 50 chars.
It will be a part of orders meta-data, see more in the CoW Protocol Docs.

Interface fee

Coming soon! Fill this form if you are interested
You can add a additional trading fee that will be displayed and applied to the quoted amounts:
import { cowSwapWidget, CowSwapWidgetParams } from '@cowprotocol/widget-lib'
const widgetContainer = document.getElementById('cowswap-widget')
const params: CowSwapWidgetParams = {
interfaceFeeBips: '50', // 0.5%
}
cowSwapWidget(widgetContainer, params)

Wallet provider

You can pass the wallet provider from your application to seamlessly use the widget as part of your application. Also, if you can not specify the provider, in this case, the widget will work in standalone mode with the ability to connect any wallet supported in CoW Swap.
A provider must comply with EIP-1193 and implement the interface:
interface EthereumProvider {
on(event: string, args: unknown): void
request<T>(params: JsonRpcRequest): Promise<T>
enable(): Promise<void>
}
interface JsonRpcRequest {
id: number
method: string
params: unknown[]
}
An example of connecting a widget to Rabby Wallet or Metamask:
import { cowSwapWidget, CowSwapWidgetParams } from '@cowprotocol/widget-lib'
cowSwapWidget(document.getElementById('cowswap-widget'), {
provider: window.ethereum, // <-------
})

Configuration

CowSwapWidgetParams

All params except appCode are optional:
Parameter
Type
Default
Description
appCode
string
❗️Required
Name of your app (max 50 characters, e.g. "My Cool App"). Fill this form after you pick yours
width
string
450px
CSS value for the width of the widget
height
string
640px
CSS value for the height of the widget
provider
EthereumProvider
undefined
Ethereum EIP-1193 provider to connect to the wallet. - For a quick test, you can pass window.ethereum. - A better approach is to use a library such as https://web3modal.com - Alternativelly, you can leave it undefined, and the widget will manage the connection to the wallet
chainId
number
1
The blockchain ID on which the trade will take place. Supported: - 1 (Mainnet) - 5 (Goerli) - 100 (Gnosis chain)
tradeType
TradeType
swap
The type of trade. Can be swap or limit or advanced.
env
CowSwapWidgetEnv
prod
The environment of the widget: local , prod , dev , pr Only useful for develeopment of the Widget. In most cases you should leave the default. See COWSWAP_URLS const value for urls.
sell
TradeAsset
WETH
Sell token and optionally the sell amount (only for sell orders). Example: { asset: 'WBTC', amount: 12 } or { asset: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' }
buy
TradeAsset
undefined
Buy token and optionally the buy amount (only for buy orders). Example: { asset: 'WBTC', amount: 12 } or { asset: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' }
theme
CowSwapTheme
light
Theme of the widget. dark ,light or auto to let your system settings to decide
logoUrl
string
undefined
Sets a custom logo for the widget.
hideLogo
boolean
false
Hides the logo in the widget.
hideNetworkSelector
boolean
false
Disables an opportunity to change the network from the widget UI.
enabledTradeTypes
Array<TradeType>
['swap', 'limit', 'advanced']
CoW Swap provides three trading widgets: swap, limit and advanced orders. Using this option you can narrow down the list of available trading widgets.
interfaceFeeBips
string
undefined
Coming soon! Fill this form if you are interested

Widget updating

You can change all possible widget options on the fly:
import { cowSwapWidget, CowSwapWidgetParams } from '@cowprotocol/widget-lib'
const container = document.getElementById('cowswap-widget')
const params: CowSwapWidgetParams = {
appCode: 'My Cool App', // Name of your app (max 50 characters)
logoUrl: 'YOUR_LOGO_URL',
}
const updateWidget = cowSwapWidget(container, params)
// Update the widget
updateWidget({
...params,
theme: 'dark', // <- Change theme to dark
hideNetworkSelector: true, // <- Hide the network selector
})

Widget URL

Most of the widget parameters are controlled via the URL, which means that you can create the URL yourself and embed the iframe. An example of URL:
https://swap.cow.fi/#/100/swap/WXDAI/GNO?sellAmount=200&theme=dark