# @cowprotocol/sdk-subgraph 中文文档

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

版本：1\.3\.2
npm 元数据更新时间：2026-11-04T11:31:25.767Z
中文译文更新时间：2026-11-10T21:36:05.605Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：26.9 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2025-08-01T17:45:33.564Z
- 最新版本发布：2026-11-04T11:31:25.326Z
- 近 30 天下载量：3713（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 42 个）

## 中文简介

牛协议子图

## 安装

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

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

## README

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

# SDK 子图

## 测试覆盖率

| 发言 | 分支 | 职能 | 行数 |
| --- | --- | --- | --- |
| ![Statements](https://img.shields.io/badge/statements-7.15%25-red.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-14%25-red.svg?style=flat) | ![Functions](https://img.shields.io/badge/functions-25.92%25-red.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-6.96%25-red.svg?style=flat) |

这个软件包提供了一个TypeScript客户端,用于从TheGraph子图查询CoW协议数据. 它为跨越多条链获取历史交易数据、量统计和其他协议计量提供了简单而安全的方式.

## 包括什么

-   **子图Api 客户端** - 查询CoW协议子图的主要客户端
-   **预建查询** - 对总数、数量和统计的共同查询
-   **多链支持** - 支持埃特鲁姆、克诺斯链、阿比特鲁姆、基地和塞波利亚
-   **类型安全对策** - 完整输入的图表QL回复
-   **自定义查询支持** - 在全类型安全的情况下运行任何 GraphQL 查询

## 安装

```bash
npm install @cowprotocol/sdk-subgraph
or
pnpm add @cowprotocol/sdk-subgraph
or
yarn add @cowprotocol/sdk-subgraph
```

## 使用量

### 基本设置

你需要来自TheGraph的图形API密钥. 来一个 [格拉夫工作室](https://thegraph.com/studio/apikeys/)。 。 。 .

```typescript
import { SubgraphApi } from '@cowprotocol/sdk-subgraph'
import { SupportedChainId } from '@cowprotocol/sdk-config'

// Initialize with your API key
const subgraphApi = new SubgraphApi('YOUR_GRAPH_API_KEY')

// Optionally configure for specific chain
const mainnetApi = new SubgraphApi('YOUR_GRAPH_API_KEY', {
  chainId: SupportedChainId.MAINNET,
})
```

### 查询协议总计

获得协议总统计数据,包括信物、订单、交易商、结算、数量和收费.

```typescript
import { SubgraphApi } from '@cowprotocol/sdk-subgraph'

const subgraphApi = new SubgraphApi('YOUR_GRAPH_API_KEY')

// Get protocol totals
const totals = await subgraphApi.getTotals()
console.log('Total tokens:', totals.tokens)
console.log('Total orders:', totals.orders)
console.log('Total volume USD:', totals.volumeUsd)
console.log('Total fees USD:', totals.feesUsd)
```

### 查询卷数据

获取特定时间段的历史量数据.

```typescript
// Get volume for last 7 days
const last7DaysVolume = await subgraphApi.getLastDaysVolume(7)
console.log('Daily volumes:', last7DaysVolume.dailyTotals)

// Get volume for last 24 hours
const last24HoursVolume = await subgraphApi.getLastHoursVolume(24)
console.log('Hourly volumes:', last24HoursVolume.hourlyTotals)
```

### 自定义查询

以全类型安全运行任何 GraphQL 查询 .

```typescript
import { gql } from 'graphql-request'

// Custom query for top tokens by volume
const query = gql`
  query TokensByVolume {
    tokens(first: 5, orderBy: totalVolumeUsd, orderDirection: desc) {
      address
      symbol
      totalVolumeUsd
      priceUsd
    }
  }
`

const result = await subgraphApi.runQuery(query)
console.log('Top tokens:', result.tokens)
```

## 测试

### 运行测试

```bash
# Run all tests
pnpm test

# Run tests in watch mode
pnpm run test:watch

# Run tests with coverage
pnpm run test:coverage
```

### 测试配置

测试使用 `jest-fetch-mock` 以模拟 GraphQL 回复。 测试不需要私钥,因为所有API的通话都被嘲笑.

```typescript
// Example test structure
import { SubgraphApi } from '@cowprotocol/sdk-subgraph'
import fetchMock from 'jest-fetch-mock'

describe('SubgraphApi', () => {
  beforeEach(() => {
    fetchMock.resetMocks()
  })

  test('should get totals', async () => {
    fetchMock.mockResponseOnce(
      JSON.stringify({
        data: {
          totals: [
            {
              tokens: '192',
              orders: '365210',
              volumeUsd: '49548634.23',
            },
          ],
        },
      }),
    )

    const api = new SubgraphApi('FakeApiKey')
    const totals = await api.getTotals()

    expect(totals.tokens).toBe('192')
  })
})
```

## API 密钥要求

要使用此软件包, 您需要来自 TheGraph 的图形 API 密钥 :

1.  转到 [格拉夫工作室](https://thegraph.com/studio/apikeys/)
2.  创建新的 API 密钥
3.  初始化子图时使用 API 键

```typescript
const subgraphApi = new SubgraphApi('your-api-key-here')
```

> **说明:** 所有子图查询都需要 API 键. 确保您的 API 密钥安全, 并且永远不要在客户端代码中曝光 .

## 常见问题

### @cowprotocol/sdk-subgraph 是什么？

牛协议子图

### 如何安装 @cowprotocol/sdk-subgraph？

在项目目录运行 npm install @cowprotocol/sdk-subgraph，或使用 pnpm add / yarn add / bun add。

### @cowprotocol/sdk-subgraph 支持 TypeScript 吗？

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

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

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

### @cowprotocol/sdk-subgraph 可以商用吗？

@cowprotocol/sdk-subgraph 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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

### @cowprotocol/sdk-subgraph 还在维护吗？

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