@cowprotocol/cow-sdk

中文文档

9.3.3发布于 2026/11/04(MIT OR Apache-2.0)TypeScriptESM + CJS构建来源已验证近 30 天下载 9.2万

COW 协议 SDK - 获取引用、配置您的顺序和交易

文档目录19 节

📚 文档网站
🌐 支持的网络
🔗 相关资源
开始
用法实例
安装
COW SDK 软件
SDK 组件
核心
高级
v6 – v7 迁移指南
基本使用大小写
开发者归属( UTM 跟踪)
合作伙伴 API
适配器
可用的适配器
安装
适配器设置示例
低级 SDK 使用示例

COW SDK 软件

📚 文档网站

🌐 支持的网络

SDK支持所有 CoW 协议启用的网络:

以利亚 (1)- (一) SupportedChainId.MAINNET
肠道链 (100个) - SupportedChainId.GNOSIS_CHAIN
一号线 (42161) - 翻译: SupportedChainId.ARBITRUM_ONE
基础 (8453) - (中文(简体) ) SupportedChainId.BASE
多边形 (137个) SupportedChainId.POLYGON
雪崩 (43114号) - SupportedChainId.AVALANCHE
英国银行 (56个) SupportedChainId.BNB
线性a (第59144段) - SupportedChainId.LINEA
等离子体 (9745年) - (英语) SupportedChainId.PLASMA
墨迹 (57073) - (英语) SupportedChainId.INK
罗宾链 (4663个) - SupportedChainId.ROBINHOOD (快来了)
塞波利亚 (11155111号) SupportedChainId.SEPOLIA (试验网)

开始

用法实例

反应实例 :

节点.js

安装

pnpm add @cowprotocol/cow-sdk

yarn add @cowprotocol/cow-sdk

COW SDK 软件

使用CoW协议,可以进行互换,限制订单,TWAP订单等多种操作. 这个 @cowprotocol/cow-sdk 提供不同抽象级的工具,允许您方便地执行基本情景,同时保持控制所有可能案例的灵活性.

在大多数情况下,你只需要使用 贸易SDK

SDK 组件

核心

TradingSdk - 使用内置引号取取取、订单签名和张贴的主要交换和限制订单工具
OrderSigningUtils - 使用加密算法签署订单和取消合同的水电费
OrderBookApi - 提供从CoW协议订单簿取回订单和交易的能力,以及添加和取消订单和交易的能力
MetadataApi - API,用于获取命令元数据和其他信息

高级

BridgingSdk - 跨链信使转让和连接功能
ConditionalOrder - SDK 用于TWAP等程序令更多信息(中文(简体) )
CowShedSdk - 利用有智能合同能力的EOA的账户抽象

v6 – v7 迁移指南

这些版本99%的后向兼容. 唯一的区别是,在v7中,您需要设置一个适应您使用的库的适配器: Viem, (中文(简体) ), Ethers6,或 Ethers5。。。 .

在(v6)之前:

import { SupportedChainId, TradingSdk, MetadataApi, OrderBookApi } from '@cowprotocol/cow-sdk'

const options = {}

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

在(v7)之后:

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

// NEW: Instantiate and set adapter
const adapter = new ViemAdapter({
  provider: createPublicClient({
    chain: sepolia,
    transport: http('YOUR_RPC_URL')
  }),
  // You can also set `walletClient` instead of `signer` using `useWalletClient` from wagmi
  signer: privateKeyToAccount('YOUR_PRIVATE_KEY' as `0x${string}`)
})

const options = {}

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

多数其他软件包(例如, MetadataApi 或者说 BridgingSdk)有一个参数来设置适配器. 您也可以使用 setGlobalAdapter数字 :

import { setGlobalAdapter, CowShedSdk } from '@cowprotocol/cow-sdk'

const adapter = {...}

// Set global adapter
setGlobalAdapter(adapter)

const cowShedSdk = new CowShedSdk()

您可能还需要绑定 SDK 在您的应用程序的账户状态. 当账户或网络在app/wallet中发生变化时,也应当在SDK中更新. 这是一个例子 WAGMI (见 examples/react/wagmi:

import { useAccount, usePublicClient, useWalletClient } from 'wagmi'
import { useEffect, useState } from 'react'
import { ViemAdapter, ViemAdapterOptions } from '@cowprotocol/sdk-viem-adapter'
import { tradingSdk } from '../cowSdk.ts'
import { setGlobalAdapter } from '@cowprotocol/cow-sdk'

export function useBindCoWSdkToWagmi(): boolean {
  const { chainId } = useAccount()
  const { data: walletClient } = useWalletClient()
  const publicClient = usePublicClient()

  const [isSdkReady, setIsSdkReady] = useState(false)

  /**
   * Sync Trading SDK with wagmi account state (chainId and signer)
   */
  useEffect(() => {
    if (!walletClient || !chainId) return

    setGlobalAdapter(
      new ViemAdapter({
        provider: publicClient,
        walletClient,
      } as unknown as ViemAdapterOptions),
    )

    tradingSdk.setTraderParams({ chainId })

    setIsSdkReady(true)
  }, [publicClient, walletClient, chainId])

  return isSdkReady
}

基本使用大小写

这个例子说明创建互换的主要用途,并显示如何:

获取引用
核实金额
调整互换参数
签名并发布命令

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

// EthersV5Adapter and EthersV6Adapter are also available
// @cowprotocol/sdk-ethers-v5-adapter, @cowprotocol/sdk-ethers-v6-adapter
const adapter = new ViemAdapter({
  provider: createPublicClient({
    chain: sepolia,
    transport: http('YOUR_RPC_URL')
  }),
  // You can also set `walletClient` instead of `signer` using `useWalletClient` from wagmi
  signer: privateKeyToAccount('YOUR_PRIVATE_KEY' as `0x${string}`)
})

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

const parameters: TradeParameters = {
  kind: OrderKind.SELL,
  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
  sellTokenDecimals: 18,
  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
  buyTokenDecimals: 18,
  amount: '120000000000000',
}

// Get quote
const { quoteResults, postSwapOrderFromQuote } = await sdk.getQuote(parameters)

const buyAmount = quoteResults.amountsAndCosts.afterSlippage.buyAmount

// Verify amount
if (confirm(`You will receive at least: ${buyAmount}. Proceed?`)) {
  // Sign and post order
  const orderId = await postSwapOrderFromQuote()

  console.log('Order created, ID:', orderId)
}

这个例子表明,根据《煤矿议定书》进行贸易最简单.

对于更高级的用例,您可以使用额外的参数,例如: receiver, (中文(简体) ), partiallyFillable, (中文(简体) ), validTo还有其他. 参见贸易 SDK 文件详细情况.

开发者归属( UTM 跟踪)

SDK在所有命令中自动包含UTM跟踪,将交易量归属于开发者. 默认参数 :

{
  utmSource: 'cowmunity',
  utmMedium: '[email protected]',  // SDK version
  utmCampaign: 'developer-cohort',
  utmContent: '',
  utmTerm: 'js'
}

自定义或禁用 通过 advancedSettings.appData.metadata.utm数字 :

// Custom UTM
await sdk.getQuote(parameters, {
  appData: {
    metadata: {
      utm: { utmContent: 'my-integration-v2' }
    }
  }
})

// Disable UTM
await sdk.getQuote(parameters, {
  appData: {
    metadata: {
      utm: {}
    }
  }
})

说明: 提供任何 utm 字段给予您全部控制 - SDK 将不会添加默认值 .

提示 : 使用 utmContent 涂鸦而不影响你 appCode编辑 appCode 参数在 COW 协议的沙丘仪表板时 utmContent 用于自定义识别器或实验,同时将你的体积归结于SDK整合器的集体影响.

合作伙伴 API

合作伙伴可以通过合作伙伴API网关使用经认证的API访问,并有更高的费率限制. 创建时通过您的 API 密钥 OrderBookApi 实例:

import { OrderBookApi, SupportedChainId } from '@cowprotocol/cow-sdk'

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

默认情况下, SDK 线路请求通过 partners.cow.fi (项目)或 partners.barn.cow.fi (粘接)并包括 X-API-Key 头曰. 如果您提供自定义 baseUrls,它们优先于默认的伙伴主机,但 X-API-Key 标题仍然随请求一起发送.

见 OrderBookApi 文档更多细节,包括使用贸易SDK.

适配器

CoW SDK支持多个块链适配器与不同的Web3库合作. 您需要安装和配置下列适配器:

可用的适配器

EthersV6 绘图器 - 对于乙醚.js v6
EthersV5 绘图器 - 对于乙醚.js v5
维埃姆亚当特 - 为了Viem

安装

# For ethers v6
pnpm add @cowprotocol/sdk-ethers-v6-adapter ethers

# For ethers v5
pnpm add @cowprotocol/sdk-ethers-v5-adapter ethers@^5.7.0

# For viem
pnpm add @cowprotocol/sdk-viem-adapter viem

适配器设置示例

EthersV6 绘图器

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 })

EthersV5 绘图器

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 })

维埃姆亚当特

import { ViemAdapter } from '@cowprotocol/sdk-viem-adapter'
import { http, createPublicClient, 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 })

// You can also set `walletClient` instead of `signer` using `useWalletClient` from wagmi
const adapter = new ViemAdapter({ provider, signer: account })

低级 SDK 使用示例

这个例子表明低水平的API用法具有实用的情景: 交换 0.4 GNO 页:1 WETH 在Gnosis链网络.

我们将开展下列行动:

获取引用
签名命令
将命令发给命令书
获取创建顺序的数据
得到交易订单
取消命令( 签名 + 发送)

试试活的: https://codesandbox.io/p/devbox/cow-sdk-example-forked-x63k52 (英语)

import { OrderBookApi, OrderSigningUtils, SupportedChainId, OrderQuoteSideKindSell, SigningScheme, setGlobalAdapter } from '@cowprotocol/cow-sdk'
import { EthersV6Adapter } from '@cowprotocol/sdk-ethers-v6-adapter'
import { JsonRpcProvider, Wallet } from 'ethers'

const account = 'YOUR_WALLET_ADDRESS'
const chainId = 100 // Gnosis Chain
const provider = new JsonRpcProvider('YOUR_RPC_URL')
const wallet = new Wallet('YOUR_PRIVATE_KEY', provider)
const adapter = new EthersV6Adapter({ provider, signer: wallet })

setGlobalAdapter(adapter)

const receiver = account

const quoteRequest = {
  sellToken: '0x6a023ccd1ff6f2045c3309768ead9e68f978f6e1', // WETH on Gnosis Chain
  buyToken: '0x9c58bacc331c9aa871afd802db6379a98e80cedb', // GNO on Gnosis Chain
  from: account,
  receiver,
  sellAmountBeforeFee: (0.4 * 10 ** 18).toString(), // 0.4 WETH
  kind: OrderQuoteSideKindSell.SELL,
}

const orderBookApi = new OrderBookApi({ chainId: SupportedChainId.GNOSIS_CHAIN })

async function main() {
  const { quote } = await orderBookApi.getQuote(quoteRequest)

  const orderData = {
    ...quote,
    // Add fee to sellAmount for sell orders
    sellAmount: (BigInt(quote.sellAmount) + BigInt(quote.feeAmount)).toString(),
    receiver,
    feeAmount: "0",
  };

  const orderSigningResult = await OrderSigningUtils.signOrder(orderData, chainId, adapter.signer)

  const orderId = await orderBookApi.sendOrder({
    ...orderData,
    ...orderSigningResult,
    signingScheme: SigningScheme.EIP712,
  })

  const order = await orderBookApi.getOrder(orderId)

  const trades = await orderBookApi.getTrades({ orderId })

  const orderCancellationSigningResult = await OrderSigningUtils.signOrderCancellations([orderId], chainId, adapter.signer)

  const cancellationResult = await orderBookApi.sendSignedOrderCancellations({
    ...orderCancellationSigningResult,
    orderUids: [orderId],
  })

  console.log('Results:', { orderId, order, trades, orderCancellationSigningResult, cancellationResult })
}

版本与发布记录

@cowprotocol/cow-sdk 共发布 324 个版本，首次发布于 2022/04/04；过去 12 个月发布了 73 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`9.3.3`latest	2026/11/04	6 天前
`9.3.2`	2026/11/04	6 天前
`9.3.1`	2026/11/03	7 天前
`9.3.0`	2026/10/26	15 天前
`9.2.22`	2026/10/23	18 天前
`9.2.21`	2026/10/13	28 天前

其他发布通道：next → 7.0.1-beta.0。

关于 @cowprotocol/cow-sdk 的常见问题

@cowprotocol/cow-sdk 是什么？

COW 协议 SDK - 获取引用、配置您的顺序和交易

如何安装 @cowprotocol/cow-sdk？

在项目目录运行 npm install @cowprotocol/cow-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：cross-fetch（^3.x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@cowprotocol/cow-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@cowprotocol/cow-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@cowprotocol/cow-sdk 可以商用吗？

@cowprotocol/cow-sdk 使用 (MIT OR Apache-2.0) 许可。可在 MIT、Apache-2.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@cowprotocol/cow-sdk 的下载量有多少？

根据 npm 官方下载统计，@cowprotocol/cow-sdk 在 2026/10/11 – 2026/11/09 这 30 天内被下载 92,450 次，日均约 3,082 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@cowprotocol/cow-sdk 还在维护吗？

最新版本 9.3.3 发布于 2026/11/04（6 天前）；至今共发布 324 个版本，其中过去 12 个月发布了 73 个；首次发布于 2022/04/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @cowprotocol/cow-sdk

pnpmpnpm add @cowprotocol/cow-sdk
yarnyarn add @cowprotocol/cow-sdk
bunbun add @cowprotocol/cow-sdk

peer 依赖cross-fetch ^3.xmultiformats ^9.x可选@openzeppelin/merkle-tree ^1.x可选

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

92,450

约 9.2万次日均 3,082 次

统计周期 2026/10/11 – 2026/11/09
数据来自 npm 官方下载统计，今天更新

最新版本9.3.3发布于 6 天前

开源许可(MIT OR Apache-2.0)多许可可选

包体积91.4 kB9 个文件 · 解压后

运行依赖7 个另有 3 个 peer 依赖

模块格式ESM + CJS无副作用，可 tree-shake

TypeScript自带类型

发布版本324 个近 12 个月 73 个

首次发布2022/04/044 年前

元数据更新2026/11/04

每一个软件包背后，
都有分享与创造的人。

@cowprotocol/cow-sdk

COW SDK 软件

📚 文档网站

🌐 支持的网络

🔗 相关资源

开始

用法实例

安装

COW SDK 软件

SDK 组件

核心

高级

v6 – v7 迁移指南

基本使用大小写

开发者归属( UTM 跟踪)

合作伙伴 API

适配器

可用的适配器

安装

适配器设置示例

EthersV6 绘图器

EthersV5 绘图器

维埃姆亚当特

低级 SDK 使用示例

版本与发布记录

关于 @cowprotocol/cow-sdk 的常见问题

@cowprotocol/cow-sdk 是什么？

如何安装 @cowprotocol/cow-sdk？

@cowprotocol/cow-sdk 支持 TypeScript 吗？

@cowprotocol/cow-sdk 支持 ESM 还是 CommonJS？

@cowprotocol/cow-sdk 可以商用吗？

@cowprotocol/cow-sdk 的下载量有多少？

@cowprotocol/cow-sdk 还在维护吗？