# @cowprotocol/cow-sdk 中文文档

规范地址：https://npmcn.com/package/%40cowprotocol/cow-sdk/

版本：9\.3\.3
npm 元数据更新时间：2026-11-04T11:32:33.255Z
中文译文更新时间：2026-11-10T21:09:12.181Z
软件包许可：\(MIT OR Apache-2\.0\)

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cowprotocol/cow-sdk
原文对照：https://npmcn.com/package/%40cowprotocol/cow-sdk/?lang=original
项目主页：https://github.com/cowprotocol/cow-sdk#readme
源码仓库：https://github.com/cowprotocol/cow-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：91.4 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：cross-fetch ^3\.x，multiformats ^9\.x，@openzeppelin/merkle-tree ^1\.x
- 首次发布：2022-04-03T21:50:33.572Z
- 最新版本发布：2026-11-04T11:32:32.922Z
- 近 30 天下载量：92450（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：324（近 12 个月 73 个）

## 中文简介

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

## 安装

```sh
npm install @cowprotocol/cow-sdk
```

也可以使用：`pnpm add @cowprotocol/cow-sdk`、`yarn add @cowprotocol/cow-sdk`、`bun add @cowprotocol/cow-sdk`

## README

![](https://github.com/cowprotocol/cow-sdk/raw/main/docs/images/CoW.png)

# COW SDK 软件

## 📚 [文档网站](https://docs.cow.fi/)

## 🌐 **支持的网络**

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` (试验网)

## 🔗 **相关资源**

-   **[COW 协议文档](https://docs.cow.fi/)**
-   **[API 参考](https://api.cow.fi/docs/)**
-   **[CoW 协议网站](https://cow.fi/)**
-   **[实例仓库](https://github.com/cowprotocol/cow-sdk/tree/main/examples)**
-   **问题**数字 : [GitHub 问题](https://github.com/cowprotocol/cow-sdk/issues)
-   **解析器**数字 : [CoW 协议分解](https://discord.com/invite/cowprotocol)
-   **文档**数字 : [(原始内容存档于2018-03-26). docs.cow.fi](https://docs.cow.fi/)

## 开始

### 用法实例

**反应实例 :**

-   [反应( viem)](https://github.com/cowprotocol/cow-sdk/tree/main/examples/react/viem)
-   [反应( wagmi)](https://github.com/cowprotocol/cow-sdk/tree/main/examples/react/wagmi)
-   [反应( ethers v6)](https://github.com/cowprotocol/cow-sdk/tree/main/examples/react/ethers6)
-   [反应( ethers v5)](https://github.com/cowprotocol/cow-sdk/tree/main/examples/react/ethers5)

**节点.js**

-   [节点.js (viem)](https://github.com/cowprotocol/cow-sdk/blob/main/examples/nodejs/viem/src/index.ts)
-   [节点.js (采石活佛 v6)](https://github.com/cowprotocol/cow-sdk/blob/main/examples/nodejs/ethers6/src/index.ts)
-   [节点.js (ethers v5)](https://github.com/cowprotocol/cow-sdk/blob/main/examples/nodejs/ethers5/src/index.ts)

### 安装

```bash
pnpm add @cowprotocol/cow-sdk
```

```bash
yarn add @cowprotocol/cow-sdk
```

## COW SDK 软件

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

> 在大多数情况下,你只需要使用 **[贸易SDK](https://github.com/cowprotocol/cow-sdk/tree/main/packages/trading/README.md)**

## SDK 组件

### 核心

-   **[`TradingSdk`](https://github.com/cowprotocol/cow-sdk/tree/main/packages/trading/README.md)** - 使用内置引号取取取、订单签名和张贴的主要交换和限制订单工具
-   **[`OrderSigningUtils`](https://github.com/cowprotocol/cow-sdk/tree/main/packages/order-signing/README.md)** - 使用加密算法签署订单和取消合同的水电费
-   **[`OrderBookApi`](https://github.com/cowprotocol/cow-sdk/tree/main/packages/order-book/README.md)** - 提供从CoW协议订单簿取回订单和交易的能力,以及添加和取消订单和交易的能力
-   **[`MetadataApi`](https://github.com/cowprotocol/cow-sdk/tree/main/packages/app-data/README.md)** - API,用于获取命令元数据和其他信息

### 高级

-   **[`BridgingSdk`](https://github.com/cowprotocol/cow-sdk/tree/main/packages/bridging/README.md)** - 跨链信使转让和连接功能
-   **[`ConditionalOrder`](https://github.com/cowprotocol/cow-sdk/tree/main/packages/composable/README.md)** - SDK 用于TWAP等程序令[更多信息](https://docs.cow.fi/cow-protocol/concepts/order-types/programmatic-orders)(中文(简体) )
-   **[`CowShedSdk`](https://github.com/cowprotocol/cow-sdk/tree/main/packages/cow-shed/README.md)** - 利用有智能合同能力的EOA的账户抽象

## v6 – v7 迁移指南

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

**在(v6)之前:**

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

const options = {}

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

**在(v7)之后:**

```typescript
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`数字 :

```typescript
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`:

```typescript
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
}

```

## 基本使用大小写

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

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

```typescript
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 文件](https://github.com/cowprotocol/cow-sdk/tree/main/packages/trading/README.md) 详细情况.

## 开发者归属( UTM 跟踪)

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

```typescript
{
  utmSource: 'cowmunity',
  utmMedium: 'cow-sdk@7.1.6',  // SDK version
  utmCampaign: 'developer-cohort',
  utmContent: '',
  utmTerm: 'js'
}
```

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

```typescript
// 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 协议的沙丘仪表板](https://dune.com/cowprotocol/cowswap)时 `utmContent` 用于自定义识别器或实验,同时将你的体积归结于SDK整合器的集体影响.

## 合作伙伴 API

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

```typescript
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 文档](https://github.com/cowprotocol/cow-sdk/tree/main/packages/order-book/README.md#partner-api-authenticated-access) 更多细节,包括使用贸易SDK.

## 适配器

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

### 可用的适配器

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

### 安装

```bash
# 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 绘图器

```typescript
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 绘图器

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

#### 维埃姆亚当特

```typescript
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链网络.

我们将开展下列行动:

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

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

```typescript
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 是什么？

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 和提交记录判断。