Trading SDK - CoW DAO Documentation

Overview

The TradingSdk class provides a comprehensive interface for interacting with CoW Protocol’s trading functionality. It simplifies order creation, quote fetching, order management, and token approvals.

Installation

npm install @cowprotocol/sdk-trading
# or
pnpm add @cowprotocol/sdk-trading
# or
yarn add @cowprotocol/sdk-trading

Constructor

new TradingSdk(
  traderParams?: Partial<TraderParameters>,
  options?: Partial<TradingSdkOptions>,
  adapter?: AbstractProviderAdapter
)

Partial<TraderParameters>

Default trader parameters to use for all operations

Show child attributes

SupportedChainId

Chain ID for the network (e.g., 1 for Mainnet, 100 for Gnosis Chain)

string

Unique application identifier for order tracking

SignerLike

Wallet signer (can be provided per-operation instead)

CowEnv

Environment to use

Partial<TradingSdkOptions>

SDK configuration options

Show child attributes

boolean

Enable detailed logging of trading steps

OrderBookApi

Custom OrderBookApi instance (useful for Partner API)

AbstractProviderAdapter

Provider adapter (ViemAdapter, EthersV5Adapter, or EthersV6Adapter)

Basic Setup

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

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

const sdk = new TradingSdk(
  {
    chainId: SupportedChainId.SEPOLIA,
    appCode: 'YOUR_APP_CODE',
  },
  {
    enableLogging: true,
  },
  adapter
)

Methods

postSwapOrder

Create a market order by fetching a quote and posting it in a single call.

async postSwapOrder(
  params: TradeParameters,
  advancedSettings?: SwapAdvancedSettings
): Promise<OrderPostingResult>

TradeParameters

required

Trade parameters

Show child attributes

OrderKind

required

Order type: SELL (sell exact amount) or BUY (buy exact amount)

string

required

Sell token address

number

required

Decimals of sell token

string

required

Buy token address

number

required

Decimals of buy token

string

required

Amount in atoms (smallest unit of token)

number

Slippage tolerance in basis points (50 = 0.5%)

number

Order validity duration in seconds (default 30 minutes)

string

Address to receive bought tokens (defaults to order creator)

boolean

Whether order can be partially filled

PartnerFee

Partner fee configuration

SwapAdvancedSettings

Advanced trading settings

Show child attributes

Partial<OrderQuoteRequest>

Override quote request parameters (signingScheme, priceQuality, etc.)

AppDataParams

Order metadata (hooks, referrer, etc.)

string

Unique order identifier (UID)

Example

import { OrderKind } from '@cowprotocol/sdk-trading'

const params = {
  kind: OrderKind.SELL,
  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
  sellTokenDecimals: 18,
  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
  buyTokenDecimals: 18,
  amount: '1000000000000000000', // 1 token
  slippageBps: 200, // 2%
  validFor: 1200, // 20 minutes
}

const { orderId } = await sdk.postSwapOrder(params)
console.log('Order created:', orderId)

getQuote

Get a quote for a trade and optionally post it later.

async getQuote(
  params: TradeParameters,
  advancedSettings?: SwapAdvancedSettings
): Promise<QuoteAndPost>

QuoteResults

Quote information including amounts, costs, and order data

Show child attributes

TradeParameters

Original trade parameters

number

Suggested slippage based on market conditions

AmountsAndCosts

Detailed breakdown of amounts, fees, and costs

Show child attributes

Amounts

Amounts before network costs

Amounts

Amounts after network costs

Amounts

Final amounts after slippage tolerance

NetworkCosts

Network fee costs

OrderParams

Order parameters ready for signing

OrderQuoteResponse

Raw quote response from API

AppDataInfo

Order metadata information

TypedDataDomain

EIP-712 typed data for signing

() => Promise<OrderPostingResult>

Function to post the order using the fetched quote

Example

const { quoteResults, postSwapOrderFromQuote } = await sdk.getQuote(params)

const buyAmount = quoteResults.amountsAndCosts.afterSlippage.buyAmount
console.log('You will receive at least:', buyAmount)

if (confirm('Accept this quote?')) {
  const { orderId } = await postSwapOrderFromQuote()
  console.log('Order created:', orderId)
}

getQuoteOnly

Get a quote without requiring a wallet connection. Useful for displaying quotes before users connect.

async getQuoteOnly(
  params: TradeParameters & { owner: string },
  advancedSettings?: SwapAdvancedSettings
): Promise<QuoteResults>

string

required

Address to quote for (doesn’t need to be connected)

Example

const quoteResults = await sdk.getQuoteOnly({
  owner: '0x1234...', // Any valid address
  kind: OrderKind.SELL,
  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
  sellTokenDecimals: 18,
  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
  buyTokenDecimals: 18,
  amount: '1000000000000000000',
})

console.log('Quote:', quoteResults.amountsAndCosts)

postLimitOrder

Create a limit order with specific buy and sell amounts.

async postLimitOrder(
  params: LimitTradeParameters,
  advancedSettings?: LimitOrderAdvancedSettings
): Promise<OrderPostingResult>

LimitTradeParameters

required

Limit order parameters

Show child attributes

string

required

Sell token address

number

required

Decimals of sell token

string

required

Buy token address

number

required

Decimals of buy token

string

required

Exact sell amount in atoms

string

required

Desired buy amount in atoms

number

ID of quote to use for the limit order

number

Exact expiration timestamp (Unix seconds)

Example

const params = {
  kind: OrderKind.BUY,
  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
  sellTokenDecimals: 18,
  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
  buyTokenDecimals: 18,
  sellAmount: '1000000000000000000', // 1 token
  buyAmount: '500000000000000000', // 0.5 token
}

const { orderId } = await sdk.postLimitOrder(params)
console.log('Limit order created:', orderId)

postSellNativeCurrencyOrder

Create an order to sell native currency (ETH, xDAI, etc.) using EthFlow.

async postSellNativeCurrencyOrder(
  params: TradeParameters,
  advancedSettings?: SwapAdvancedSettings
): Promise<OrderPostingResult>

Use the special native currency address 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE as the sellToken.

Example

const params = {
  kind: OrderKind.SELL,
  sellToken: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // Native ETH
  sellTokenDecimals: 18,
  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
  buyTokenDecimals: 18,
  amount: '100000000000000000', // 0.1 ETH
}

const { orderId, txHash } = await sdk.postSellNativeCurrencyOrder(params)
console.log('Native currency order:', orderId, txHash)

getOrder

Retrieve details of an existing order.

async getOrder(params: { orderUid: string }): Promise<EnrichedOrder>

string

required

Unique order identifier

EnrichedOrder

Complete order information including status, amounts, and execution details

Example

const order = await sdk.getOrder({ orderUid: '0xd64389...' })
console.log('Order status:', order.status)
console.log('Sell amount:', order.sellAmount)
console.log('Buy amount:', order.buyAmount)

offChainCancelOrder

Cancel an order off-chain (soft cancel - fast and free).

async offChainCancelOrder(params: { orderUid: string }): Promise<boolean>

string

required

Order UID to cancel

boolean

True if cancellation was successful

Off-chain cancellation may not work if the order is already being executed.

Example

const success = await sdk.offChainCancelOrder({ orderUid: '0xd64389...' })
if (success) {
  console.log('Order cancelled successfully')
}

onChainCancelOrder

Cancel an order on-chain (hard cancel - requires gas but guaranteed).

async onChainCancelOrder(params: { orderUid: string }): Promise<string>

string

required

Order UID to cancel

string

Transaction hash of the cancellation

Example

const txHash = await sdk.onChainCancelOrder({ orderUid: '0xd64389...' })
console.log('Cancellation transaction:', txHash)

getCowProtocolAllowance

Check current token allowance for CoW Protocol.

async getCowProtocolAllowance(params: {
  tokenAddress: string
  owner: string
}): Promise<bigint>

string

required

ERC-20 token contract address

string

required

Token owner address

bigint

Current allowance amount

Example

const allowance = await sdk.getCowProtocolAllowance({
  tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
  owner: '0x123...',
})

console.log('Current allowance:', allowance.toString())

approveCowProtocol

Approve CoW Protocol to spend tokens.

async approveCowProtocol(params: {
  tokenAddress: string
  amount: bigint
}): Promise<string>

string

required

ERC-20 token contract address

bigint

required

Amount to approve

string

Transaction hash of approval

Example

import { parseUnits } from 'viem'

const txHash = await sdk.approveCowProtocol({
  tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
  amount: parseUnits('1000', 6), // 1000 USDC
})

console.log('Approval transaction:', txHash)

getPreSignTransaction

Get pre-sign transaction for smart contract wallets.

async getPreSignTransaction(params: {
  orderUid: string
  account: string
}): Promise<{ to: string; data: string }>

string

required

Order UID to pre-sign

string

required

Smart contract wallet address

{ to: string, data: string }

Transaction to execute for pre-signing

Example

const preSignTx = await sdk.getPreSignTransaction({
  orderUid: '0xd64389...',
  account: '0xSmartContractWallet...',
})

console.log('Execute this transaction:', preSignTx)

setTraderParams

Update default trader parameters.

setTraderParams(params: Partial<TraderParameters>): TradingSdk

Partial<TraderParameters>

required

New trader parameters to merge with existing ones

Example

sdk.setTraderParams({
  chainId: SupportedChainId.MAINNET,
  env: 'prod',
})

Smart Contract Wallet Support

For smart contract wallets (like Safe), use the PRESIGN signing scheme:

import { SigningScheme } from '@cowprotocol/sdk-trading'

const params = {
  // ... trade parameters
}

const advancedSettings = {
  quoteRequest: {
    signingScheme: SigningScheme.PRESIGN,
  },
}

const { orderId } = await sdk.postSwapOrder(params, advancedSettings)

const preSignTx = await sdk.getPreSignTransaction({
  orderUid: orderId,
  account: '0xSmartContractWallet...',
})

// Execute preSignTx with your smart contract wallet

Partner API Integration

To use the Partner API with higher rate limits:

import { OrderBookApi } from '@cowprotocol/sdk-order-book'

const orderBookApi = new OrderBookApi({
  chainId: SupportedChainId.MAINNET,
  apiKey: 'your-partner-api-key',
})

const sdk = new TradingSdk(
  { chainId: SupportedChainId.MAINNET, appCode: 'YOUR_APP' },
  { orderBookApi },
  adapter
)

Error Handling

try {
  const { orderId } = await sdk.postSwapOrder(params)
  console.log('Order created:', orderId)
} catch (error) {
  if (error.message.includes('insufficient allowance')) {
    // Handle allowance error
    await sdk.approveCowProtocol({ tokenAddress, amount })
  } else if (error.message.includes('slippage')) {
    // Handle slippage error
    console.error('Price moved too much')
  } else {
    console.error('Order creation failed:', error)
  }
}

​Overview

​Installation

​Constructor

​Basic Setup

​Methods

​postSwapOrder

​Example

​getQuote

​Example

​getQuoteOnly

​Example

​postLimitOrder

​Example

​postSellNativeCurrencyOrder

​Example

​getOrder

​Example

​offChainCancelOrder

​Example

​onChainCancelOrder

​Example

​getCowProtocolAllowance

​Example

​approveCowProtocol

​Example

​getPreSignTransaction

​Example

​setTraderParams

​Example

​Smart Contract Wallet Support

​Partner API Integration

​Error Handling

​See Also

Overview

Installation

Constructor

Basic Setup

Methods

postSwapOrder

Example

getQuote

Example

getQuoteOnly

Example

postLimitOrder

Example

postSellNativeCurrencyOrder

Example

getOrder

Example

offChainCancelOrder

Example

onChainCancelOrder

Example

getCowProtocolAllowance

Example

approveCowProtocol

Example

getPreSignTransaction

Example

setTraderParams

Example

Smart Contract Wallet Support

Partner API Integration

Error Handling

See Also