Installation

Install the CoW Protocol SDK and configure your adapter for Viem, Ethers v6, or Ethers v5

Package Installation

Install the main SDK package using your preferred package manager:

npm

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

Install Viem Adapter

npm

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.

Ethers v6

Install Ethers v6 Adapter

npm

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.

Ethers v5

Install Ethers v5 Adapter

npm

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

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:

• Check the GitHub Issues
• Join the CoW Protocol Discord
• Review the Examples Repository