Installation

Package Installation

Install the main SDK package using your preferred package manager:

npm install @cowprotocol/cow-sdk

Choose Your Adapter

The CoW SDK requires an adapter to interact with the blockchain. Choose the adapter that matches your Web3 library:

Viem

Modern, lightweight TypeScript library

Ethers v6

Latest version of ethers.js

Ethers v5

Legacy ethers.js version

Viem
Ethers v6
Ethers v5

Install Viem Adapter

npm install @cowprotocol/sdk-viem-adapter viem

Setup Example

import { ViemAdapter } from '@cowprotocol/sdk-viem-adapter'
import { createPublicClient, http, privateKeyToAccount } from 'viem'
import { sepolia } from 'viem/chains'

const account = privateKeyToAccount('YOUR_PRIVATE_KEY' as `0x${string}`)
const transport = http('YOUR_RPC_URL')
const provider = createPublicClient({ 
  chain: sepolia, 
  transport 
})

const adapter = new ViemAdapter({ 
  provider, 
  signer: account 
})

Using wagmi? You can use useWalletClient() hook instead of privateKeyToAccount for the signer parameter.

Install Ethers v6 Adapter

npm install @cowprotocol/sdk-ethers-v6-adapter ethers

Setup Example

import { EthersV6Adapter } from '@cowprotocol/sdk-ethers-v6-adapter'
import { JsonRpcProvider, Wallet } from 'ethers'

const provider = new JsonRpcProvider('YOUR_RPC_URL')
const wallet = new Wallet('YOUR_PRIVATE_KEY', provider)

const adapter = new EthersV6Adapter({ 
  provider, 
  signer: wallet 
})

Ethers v6 is the recommended version if you’re using the ethers.js library.

Install Ethers v5 Adapter

npm install @cowprotocol/sdk-ethers-v5-adapter ethers@^5.7.0

Setup Example

import { EthersV5Adapter } from '@cowprotocol/sdk-ethers-v5-adapter'
import { ethers } from 'ethers'

const provider = new ethers.providers.JsonRpcProvider('YOUR_RPC_URL')
const wallet = new ethers.Wallet('YOUR_PRIVATE_KEY', provider)

const adapter = new EthersV5Adapter({ 
  provider, 
  signer: wallet 
})

Ethers v5 is considered legacy. Consider upgrading to v6 or using Viem for new projects.

Peer Dependencies

The CoW Protocol SDK has the following peer dependencies that may need to be installed depending on your use case:

Required

{
  "cross-fetch": "^3.x"
}

npm install cross-fetch

Optional

These dependencies are only required for specific advanced features:

{
  "ipfs-only-hash": "^4.x",
  "multiformats": "^9.x",
  "@openzeppelin/merkle-tree": "^1.x"
}

ipfs-only-hash and multiformats - Required for app-data metadata features
@openzeppelin/merkle-tree - Required for merkle tree operations in programmatic orders

Verification

Verify your installation by importing the SDK:

import { SupportedChainId, TradingSdk, OrderKind } from '@cowprotocol/cow-sdk'
import { ViemAdapter } from '@cowprotocol/sdk-viem-adapter'

console.log('CoW Protocol SDK installed successfully!')

Version Information

Current SDK version: v7.4.1

If you’re migrating from v6, see the Migration Guide for important breaking changes and upgrade instructions.

TypeScript Configuration

The CoW Protocol SDK is written in TypeScript and includes type definitions. Ensure your tsconfig.json has:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

Environment Setup

Node.js Requirements

The SDK requires Node.js version 16 or higher:

node --version  # Should be v16.0.0 or higher

Environment Variables

For development, create a .env file to store sensitive information:

.env

PRIVATE_KEY=0x...
RPC_URL=https://...

Security: Never commit private keys or RPC URLs to version control. Always use environment variables or secure key management solutions.

Framework-Specific Setup

React / Next.js

For React applications, you’ll typically use the SDK with wagmi or Rainbow Kit:

import { useAccount, usePublicClient, useWalletClient } from 'wagmi'
import { ViemAdapter } from '@cowprotocol/sdk-viem-adapter'
import { setGlobalAdapter } from '@cowprotocol/cow-sdk'

function useCoWAdapter() {
  const { data: walletClient } = useWalletClient()
  const publicClient = usePublicClient()
  
  if (walletClient && publicClient) {
    return new ViemAdapter({
      provider: publicClient,
      walletClient
    })
  }
}

See the React Integration Example for complete setup.

Node.js

For Node.js scripts and backend services:

import 'dotenv/config'
import { createPublicClient, http, privateKeyToAccount } from 'viem'
import { mainnet } from 'viem/chains'
import { ViemAdapter } from '@cowprotocol/sdk-viem-adapter'

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)
const provider = createPublicClient({
  chain: mainnet,
  transport: http(process.env.RPC_URL)
})

const adapter = new ViemAdapter({ provider, signer: account })

See the Node.js Usage Example for complete setup.

Next Steps

Quickstart Guide

Create your first swap in under 5 minutes

Adapters Concepts

Learn more about adapter configuration

Trading SDK API

Explore the complete TradingSdk API

Examples

Browse working code examples

Troubleshooting

Module not found errors

Ensure all peer dependencies are installed. Run:

npm install cross-fetch

or install optional dependencies if using advanced features.

Type errors with adapter

Make sure you’re using the correct adapter for your Web3 library version. Check that:

Viem adapter requires viem version 1.x or higher
Ethers v6 adapter requires ethers version 6.x
Ethers v5 adapter requires ethers version 5.7.x

RPC connection issues

Verify your RPC URL is correct and accessible:

const provider = createPublicClient({
  chain: sepolia,
  transport: http('https://sepolia.gateway.tenderly.co') // Use a reliable RPC
})

Consider using services like Alchemy, Infura, or Tenderly for production.

Network mismatch errors

Ensure the chain ID in your adapter setup matches the chain ID in the TradingSdk:

// Both should use the same chain
const provider = createPublicClient({ chain: sepolia, ... })
const sdk = new TradingSdk({ chainId: SupportedChainId.SEPOLIA, ... })

Getting Help

If you encounter issues during installation:

Get Started

Core Concepts

Guides

Advanced Features

Migration

Package Installation

Choose Your Adapter

Viem

Ethers v6

Ethers v5

Install Viem Adapter

Setup Example

Install Ethers v6 Adapter

Setup Example

Install Ethers v5 Adapter

Setup Example

Peer Dependencies

Required

Optional

Verification

Version Information

TypeScript Configuration

Environment Setup

Node.js Requirements

Environment Variables

Framework-Specific Setup

React / Next.js

Node.js

Next Steps

Quickstart Guide

Adapters Concepts

Trading SDK API

Examples

Troubleshooting

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced Features

Migration

​Package Installation

​Choose Your Adapter

Viem

Ethers v6

Ethers v5

​Install Viem Adapter

​Setup Example

​Install Ethers v6 Adapter

​Setup Example

​Install Ethers v5 Adapter

​Setup Example

​Peer Dependencies

​Required

​Optional

​Verification

​Version Information

​TypeScript Configuration

​Environment Setup

​Node.js Requirements

​Environment Variables

​Framework-Specific Setup

​React / Next.js

​Node.js

​Next Steps

Quickstart Guide

Adapters Concepts

Trading SDK API

Examples

​Troubleshooting

​Getting Help

Build docs developers (and LLMs) love

Package Installation

Choose Your Adapter

Install Viem Adapter

Setup Example

Install Ethers v6 Adapter

Setup Example

Install Ethers v5 Adapter

Setup Example

Peer Dependencies

Required

Optional

Verification

Version Information

TypeScript Configuration

Environment Setup

Node.js Requirements

Environment Variables

Framework-Specific Setup

React / Next.js

Node.js

Next Steps

Troubleshooting

Getting Help