# @circle-fin/usdckit 中文文档

规范地址：https://npmcn.com/package/%40circle-fin/usdckit/

版本：0\.25\.4
npm 元数据更新时间：2026-06-29T02:57:18.148Z
中文译文更新时间：2026-11-09T17:02:45.193Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40circle-fin/usdckit
原文对照：https://npmcn.com/package/%40circle-fin/usdckit/?lang=original
项目主页：https://docs-w3s-node-sdk.circle.com/
源码仓库：https://github.com/crcl-main/w3s-node-sdk

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

- 包体积（解压后）：10.3 MB，1358 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：12 个
- 首次发布：2025-03-24T11:25:25.128Z
- 最新版本发布：2026-06-29T02:57:18.014Z
- 近 30 天下载量：3395（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 7 个）

## 中文简介

> **重要内容:** 我们把产品升级到 [应用套件](https://docs.arc.io/app-kit) 并推荐它用于所有生产部署。 USDCKit将继续作为私人β产品提供. 谢谢.

## 安装

```sh
npm install @circle-fin/usdckit
```

也可以使用：`pnpm add @circle-fin/usdckit`、`yarn add @circle-fin/usdckit`、`bun add @circle-fin/usdckit`

## README

# USDCKit 维基百科

> **重要内容:** 我们把产品升级到 [应用套件](https://docs.arc.io/app-kit) 并推荐它用于所有生产部署。 USDCKit将继续作为私人β产品提供. 谢谢.

## 导言

USDCKit是一个节点.js SDK,简化了与USDC的互动. 使用 USDCKit , 您可以将 USDC 整合到您的应用程序中, 并允许安全高效的块链交易 。 USDCKit旨在提供多链基金管弦功能,使USDC支付能够使用加密获取(C2B)、发薪(B2C)、汇款(C2C)和B2B跨境支付等案例.

SDK是用TypeScript来构建的,并支持涉及稳定币的高层次使用案例,使其成为开发商用数字货币工作的重要工具.

这个指南会帮助你快速高效地启动, 无论你正在建立一个钱包, 一个支付网关, 或任何在两者之间。 它包括下列项目:

-   [使用USDCKit的好处](https://npmcn.com/package/%40circle-fin/usdckit/#readme-benefits-of-using-usdckit)
-   [快速开始使用 USDCKit 写入您的第一行代码](https://npmcn.com/package/%40circle-fin/usdckit/#readme-quickstart-steps)
-   [运行 Stablecoin 获取流的样本代码](https://npmcn.com/package/%40circle-fin/usdckit/documents/Developer_Resources.Stablecoin_Acquiring_Flow.html)

### 使用USDCKit的好处

-   **更快的时间上市**USDCKit简化了对稳定币付款的接受和管理,最低编码。 它提供可重复使用的支付模块,并消除技术复杂性以加快整合.
-   **重点付款**建设USDCKit是为了提供创建完整的端到端稳定币支付流量所需的所有功能和工具,其功能适合支付使用案例. 它还包括特定支付产品的样本代码,从而更容易开发出自己的. 目前发布的重点是"稳定币获取使用"案例.
-   **无瓶颈的可扩展支付**. 用USDCKit的高性能基础设施高效地处理数百万笔交易
-   **企业级合规管理**遵守全球监管标准,通过合规引擎进行实时交易筛选

#### 主要特点

除了基本的钱包管理、转账和余额查询外, USDCKit还支持一些其他突出的功能

-   **基金**: 自动集资,多向一调剂并优化燃气效率.
-   **跨链转移**:在不同链上钱包之间转移资金.
-   **切换**: 将一个令牌类型无缝地转换为另一个.
-   **交易筛选**: 防止钱包与外国资产管制处受制裁地址进行交易.

## 快速启动步骤

### 设置

USDCKit建在圆形钱包上方。 你需要设置一个 [圆形开发者控制台](https://console.circle.com/signup) 在使用服务前进行帐号。 请遵循这些步骤:

1.  **注册**
    
    转到 [圆形开发者控制台](https://console.circle.com/signup) 并注册一个账户。 此账户将用于管理您访问 Circle 开发者服务, 如 Dev 控制钱包和智能合同平台 。 跟着 [指令](https://developers.circle.com/interactive-quickstarts/get-started#create-a-web3-services-account) 更多细节.
    
2.  **生成 API 密钥**
    
    导航到 [API 客户端密钥( C)](https://console.circle.com/api-keys) 并生成新的 **API 密钥**。确保存储 **API 密钥** 安全地使用它来认证您的请求。 跟着 [指令](https://developers.circle.com/interactive-quickstarts/get-started#create-your-api-key) 更多细节.
    
3.  **注册实体机密**
    
    运行以下命令以创建和注册 **实体机密**。命令将提示您进入 **API 密钥** 从上一步骤生成.
    
    ```bash
    npx @circle-fin/usdckit register-entity-secret
    ```
    
    运行命令后, 您的新命令 **实体机密** 将显示在控制台并保存到环境文件( q)`.env` (默认情况下). A 类 **回收文件** 亦被存储( a)`recovery.dat` (默认情况下).
    
    基于UI的设立方法 **实体机密** 也为 [可用](https://developers.circle.com/interactive-quickstarts/dev-controlled-wallets#setup-your-entity-secret)。 。 。 .
    

### 安装

要从国家预防机制安装 USDCKit, 请在您的项目目录中运行以下命令 :

```bash
npm install @circle-fin/usdckit
```

### 初始化

要从 USDCKit 开始, 请初始化客户端 **API 密钥** 财务报告和审定财务报表 [实体机密](https://developers.circle.com/w3s/entity-secret-management#what-is-an-entity-secret) 从 [设置](https://npmcn.com/package/%40circle-fin/usdckit/#readme-setup)

```typescript
import { createCircleClient } from '@circle-fin/usdckit'
import { ETH_SEPOLIA } from '@circle-fin/usdckit/chains'

const client = createCircleClient({
  apiKey: 'CIRCLE_API_KEY',
  entitySecret: 'CIRCLE_ENTITY_SECRET',

  // Optional.  Defaults to `ETH_SEPOLIA`
  chain: ETH_SEPOLIA,
})
```

## 使用量

### 创建账户

要创建新账户(又称钱包),请使用 [创建账户](https://npmcn.com/package/%40circle-fin/usdckit/functions/providers_circle-wallets.createAccount.html) 方法。 这将生成一个新的账户,您可以使用该账户进行各种操作,例如传输令牌和取回余额等.

USDCKit目前支持创建 **道德操守办公室** (外部自有账户)和 **索马里** (智能-合同-账户). 参见此 [页 次](https://npmcn.com/package/%40circle-fin/usdckit/documents/Developer_Resources.Account_Type_and_Gas_Fee_Management.html) 用于了解更多信息,并为您的业务选择最合适的账户类型.

```typescript
// Creates an account on the default chain ETH_SEPOLIA (EOA)
const account = await client.createAccount()

// Creates an account on the ARB_SEPOLIA (SCA)
const account = await client.createAccount({ accountType: 'SCA', chain: ARB_SEPOLIA })
```

### 查询账户

要查询现有账户,请使用 [获取账户](https://npmcn.com/package/%40circle-fin/usdckit/functions/providers_circle-wallets.getAccounts.html) 方法。 这将返回与提供的账户查询相关的账户细节 .

```typescript
// Query by Address
const account = await client.getAccounts({ address: '0xabc123...def456' })

// Query by refId
const account = await client.getAccounts({ refId: 'user-1' })

// Query by balance greater or equal to
const account = await client.getAccounts({ amountGte: 1000 })
```

### 有测试网的基金账户

要资助一个有测试网符号的账户,你可以使用 [滴水点滴](https://npmcn.com/package/%40circle-fin/usdckit/functions/providers_circle-wallets.drip.html) 方法。 这种方法为测试目的提供了本土代币(USDC)和EURC.

```typescript
// Receive native tokens, USDC, and EURC
await client.drip({ account })

// Receive native
await client.drip({ account, token: null })

// Receive USDC
await client.drip({ account, token: client.chain.contracts.USDC })
```

### 传输令牌

这个 [转让](https://npmcn.com/package/%40circle-fin/usdckit/functions/actions.transfer.html) 方法允许在账户之间传输本地或ERC-20令牌。 多源账户可以单调调. 使用 `fees` 参数。 USDC可以通过CCTP在跨链的账户之间转移. 以下是如何使用 `transfer()` 用于每种标志的方法.

```typescript
// Create Transfer - Native Tokens
const transaction_native = await client.transfer({
  from: account,
  to: anotherAccount,
  amount: '0.00000001', // or use base units `1n`
})

// Create Transfer - USDC
const transaction_usdc = await client.transfer({
  from: account,
  to: anotherAccount,
  token: ETH_SEPOLIA.contracts.USDC,
  amount: '0.01',
  chain: ETH_SEPOLIA,
})

// Create Transfer - EURC
const transaction_eurc = await client.transfer({
  from: account,
  to: anotherAccount,
  token: ETH_SEPOLIA.contracts.EURC,
  amount: '0.01',
  chain: ETH_SEPOLIA,
})

// Create Transfer - USDT
const transaction_usdt = await client.transfer({
  from: account,
  to: anotherAccount,
  token: '0xdac17f958d2ee523a2206206994597c13d831ec7',
  amount: '0.01',
  chain: ETH,
})

// Create Transfer - Cross chain transfer (only supported for USDC)
const transaction_usdc = await client.transfer({
  from: accountOnETH_SEPOLIA,
  to: accountOnMATIC_AMOY,
  token: ETH_SEPOLIA.contracts.USDC,
  amount: '0.01',
})
```

#### 批量传输

从多个来源账户转入单一目的账户

```typescript
// Create Transfer - Batch transfer
const transaction_batch = await client.transfer({
  from: [account_1, account_2],
  to: account_3,
  token: client.chain.contracts.USDC,
  amount: '0.01',
})
```

#### 扫地盘

[扫描](https://npmcn.com/package/%40circle-fin/usdckit/functions/actions.sweep.html) 函数从一个账户向另一个账户转移所有指定符号。 在这个例子中,它从 `account_1` 改为 `account_2`。 。 。 .

```typescript
const [tx] = await client.sweep({
  from: account_1,
  to: account_2,
  token: client.chain.contracts.USDC,
})
```

### 交换令牌

这个 [互换](https://npmcn.com/package/%40circle-fin/usdckit/functions/actions.swapExactIn.html) 动作将一个 ERC-20 令牌换为另一个

```typescript
// Get the quote for the swap
const quote = await client.getSwapQuote({
  tokenIn: client.chain.contracts.USDC,
  tokenInAmount: '100',
  tokenOut: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
})
// Verify the quote
if (quote.tokenInAmount < 9_500_000n) throw new Error('Quote is invalid')

// Swap 100 USDC for WETH
const txHash = await client.swap({ ...quote, account })
```

直接互换而不引号

```typescript
// Swap 100 USDC for WETH
const txHash = await client.swap({
  tokenIn: client.chain.contracts.USDC,
  tokenInAmount: '100',
  tokenOut: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
  account,
})
```

### 获取账户余额

使用 [获取 KokenBalances](https://npmcn.com/package/%40circle-fin/usdckit/functions/providers_circle-wallets.getTokenBalances.html) 以获取指定账户的符号余额.

```typescript
const balance = await client.getTokenBalances({ account: account_2 })
```

### 启用日志

通过配置 `logLevel` 参数创建客户端时。 这使得您可以看到 USDCKit 操作的详细日志,这对调试和监测目的有帮助.

见 [创建环形](https://npmcn.com/package/%40circle-fin/usdckit/functions/index.createCircleClient.html) 更多细节.

```typescript
const client = createClient({
  ...,
  logLevel: 'debug',
})

```

## 样本

### 运行 Stablecoin 获取流的样本代码

我们在稳定币获取流程上的样本代码显示了典型获取平台的结构和技术实施。 它引导您通过设置不同的钱包来收集稳定币支付,以及使用不同的SDK方法来调节资金流的过程.

-   参见 [稳定币获取流程样本代码](https://npmcn.com/package/%40circle-fin/usdckit/documents/Developer_Resources.Stablecoin_Acquiring_Flow.html)

## 未来计划

目前的个人发行标志着USDCKit的第一个版本,我们承认需要额外的工具来创造出平稳的稳定币支付体验. 因此,我们正在积极研究几个单元,并十分感谢你们的反馈。 我们的路线图包括但不限于以下内容:

-   提高天然气效率
-   资金大规模支付
-   支付/订阅

## 反馈和支持

如有问题或需要帮助,请勿犹豫直接联系球队([usdckit@circle.com (英语)](mailto:usdckit@circle.com)) (中文(简体) ). 我们在这里支持你的每一步.

编码愉快!

## 常见问题

### @circle-fin/usdckit 是什么？

重要内容: 我们把产品升级到 应用套件 并推荐它用于所有生产部署。 USDCKit将继续作为私人β产品提供\. 谢谢\.

### 如何安装 @circle-fin/usdckit？

在项目目录运行 npm install @circle-fin/usdckit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 usdckit，可以用 npx usdckit 直接运行。

### @circle-fin/usdckit 支持 TypeScript 吗？

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

### @circle-fin/usdckit 支持 ESM 还是 CommonJS？

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

### @circle-fin/usdckit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @circle-fin/usdckit 可以商用吗？

@circle-fin/usdckit 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @circle-fin/usdckit 的下载量有多少？

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

### @circle-fin/usdckit 还在维护吗？

最新版本 0\.25\.4 发布于 2026/06/29（4 个月前）；至今共发布 27 个版本，其中过去 12 个月发布了 7 个；首次发布于 2025/03/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。