Website Twitter Analytics Blog Snapshot Grants

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:

ParameterTypeDefaultDescription

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
PreviousHow to test a solver locallyNextIntroduction

Last updated