# @circle-fin/earn-kit 中文文档

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

版本：1\.13\.0
npm 元数据更新时间：2026-11-05T17:19:48.611Z
中文译文更新时间：2026-11-09T16:40:18.362Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40circle-fin/earn-kit
原文对照：https://npmcn.com/package/%40circle-fin/earn-kit/?lang=original

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

- 包体积（解压后）：2.3 MB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：11 个
- 首次发布：2026-05-18T23:34:50.157Z
- 最新版本发布：2026-11-05T17:19:48.332Z
- 近 30 天下载量：30996（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

DeFi 出借金库的SDK 存款、提款和奖励

## 安装

```sh
npm install @circle-fin/earn-kit
```

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

## README

# 荣杰

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

> **说明:** 恩杰快来了 本文中记录的API为: 早期整合和反馈;金库可用性和生产准备 将提前宣布.

Earn Kit是DeFi出借金库收入流的圆形SDK. 它提供类型 用于发现金库、取取钱包位置、预览的操作 押金、提款、奖励债权、执行押金、提款、以及 债权奖励交易.

## 安装

```bash
npm install @circle-fin/earn-kit
# or
yarn add @circle-fin/earn-kit
```

为您使用的钱包堆栈安装适配器 。 对于EVM流量:

```bash
npm install @circle-fin/adapter-viem-v2 viem
# or
yarn add @circle-fin/adapter-viem-v2 viem
```

## 快速启动

```typescript
import { Blockchain, EarnChain, EarnKit } from '@circle-fin/earn-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new EarnKit()
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY,
})

const quote = await kit.getDepositQuote({
  from: { adapter, chain: EarnChain.Arc_Testnet },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '100.50',
})

console.log(`Expected shares: ${quote.expectedShares.amount}`)

const depositResult = await kit.deposit({
  from: { adapter, chain: EarnChain.Arc_Testnet },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '100.50',
})

console.log(`Deposit submitted: ${depositResult.txHash}`)
```

## 存款

同链存款保持现有批准和收益行动流动。 跨链 只有在 `to` 已存在 `to.chain` 与 `from.chain`。 。 。 .

```typescript
const bridgeDeposit = await kit.deposit({
  from: { adapter, chain: Blockchain.Ethereum_Sepolia },
  to: {
    chain: EarnChain.Arc_Testnet,
    recipientAddress: '0x1234567890123456789012345678901234567890',
  },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '100.50',
})

console.log(`Bridge deposit submitted: ${bridgeDeposit.execId}`)
```

对于跨链存款, `to.recipientAddress` 是目的地钱包 接收金库位置 `from.address` 可作为可选 源钱包覆盖 。 返回的结果包含桥执行ID, 提交状态、源链、目的地链、金库地址、金额和 准备捆绑过期时间戳。 SDK 生成桥执行 ID 财务报告和审定财务报表 `retry()` 失败后恢复同一桥的行刑.

跨链收益存款目前支持Ethereum Sepolia, Arbitrum Sepolia, 以 CArc Testnet 为源链 链条.

## 退出费

提款时引出 `quote.fees`. 环取费 标记为 `type: 'circle'` 因此,集成器可以显示收费预览 电话 `withdraw`。 。 。 .

```typescript
const quote = await kit.getWithdrawalQuote({
  from: { adapter, chain: EarnChain.Arc_Testnet },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '50.00',
})

const circleFee = quote.fees.find((fee) => fee.type === 'circle')
if (circleFee === undefined) {
  console.log('Circle fee: 0')
} else {
  console.log(`Circle fee: ${circleFee.amount} ${circleFee.symbol}`)
}
```

当不适用圆形收费,包括后端收费旗被禁用时, `quote.fees` 没有 `type: 'circle'` 输入。 EinKit 格式收费金额 人类可读小数字符串, 与工具箱级其他引用一致 表面。 读取返回的收费项 `symbol` 而不是假设一个固定 收费标志.

## 断接操作( SCA 钱包)

同链 `deposit` 财务报告和审定财务报表 `withdraw` 通常提交两个顺序 交易: ERC-20/金库共享 `approve` 然后是恩典 `execute`。 。 。 . 当连接的适配器支持原子分批时, SDK 将 `approve` 财务报告和审定财务报表 `execute` 换成一批 适配器可以提交 批次通过EIP-5792, Circle钱包挑战,或ERC-4337用户操作. 这将删除用户批准但从未执行的部分状态窗口 ,并在单个钱包交互中确认.

Batching是自动的,不需要更改代码——它只有在 **全部** 如下情况:

-   行动是 **同链** `deposit` 或者说 `withdraw` (连锁存款) 使用EIP-3009签名,而不是 `approve` + 键 `execute`因此批量处理不 (适用).
-   这个 `from.chain` 是一个EVM链.
-   所签有效载荷含有正向符号拉出并未得到批准 跳过.
-   钱包适配器报告对链和地址的原子批次支持.

SDK在提交前先读取当前备抵. 当需要补上时, 批发 `[approve, execute]`;当津贴已经支付该数额时, 它提交 `[execute]` 无需通过同一批次的 API 核准。 操作中没有带有批准符号的输入、EOA钱包和 没有批次支持的钱包保持现有相继行为不变. 要强迫相继流动, 即使一个批量的可处理钱包, 设置 `batchTransactions: false` 操作中 `config`数字 :

```typescript
await kit.deposit({
  from: { adapter, chain: EarnChain.Arc_Testnet },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '100.50',
  config: { batchTransactions: false }, // always use sequential approve -> execute
})
```

## 发现缺陷

将链条上可用的每个金库进行平移, 不管理平移 :

```typescript
for await (const vault of kit.exploreVaultsIterator({
  chain: 'Arc_Testnet',
  sortBy: 'apy',
})) {
  console.log(`${vault.name}: ${(vault.currentApy * 100).toFixed(2)}% APY`)
}
```

对于需要总计的已页 UI, 一次获取一页 :

```typescript
const { vaults, pagination } = await kit.exploreVaults({
  chain: 'Arc_Testnet',
  page: 1,
})
console.log(`Page 1 of ${pagination.totalPages} (${pagination.totalCount} vaults)`)
```

## 支持的链条

使用 `kit.getSupportedChains()` 函数 `getSupportedChains(context)` 帮助从配置的收入提供者读取支持的链条定义 .

## 核心业务

-   `getVaults`: 获取一个或多个金库的金库元数据.
-   `exploreVaultsIterator`: 懒散地将链条上可用的每个金库都填平 带有任择议定书、资产、APY和TVL过滤器。 获取页面于 需求,所以没有页面算术来管理.
-   `exploreVaults`: 以 pagination 元数据, 用于页面化的 UIs .
-   `getPosition`: 获取金库的钱包位置 .
-   `getDepositQuote`:预览押金.
-   `getWithdrawalQuote`: 预览退出.
-   `getClaimRewardsQuote`: 预览可要求的奖励.
-   `deposit`:执行存款交易.
-   `withdraw`:执行退出交易.
-   `claimRewards`:要求奖励,或在没有交易的情况下返回 可索赔.
-   `getCrossChainDepositStatus`: 读取当前跨链桥状态 存款人 `execId`。 。 。 .
-   `waitForCrossChainDeposit`: 调查跨链存款,直到其达到 终端桥站状态(或等待预算缓冲).

## 配置

Ein Kit 没有 API 密钥。 API 密钥可以在每次操作中传递 允许的访问和归属 :

```typescript
await kit.getVaults({
  vaults: [
    {
      chain: 'Arc_Testnet',
      vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
    },
  ],
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
  },
})
```

API密钥是服务器唯一的秘密——由浏览器投掷提供. 别动 在您的服务器上, 并将准备的交易转发给客户端 .

> **从 `kitKey`数字 :** `config.kitKey` 以有利于 `config.apiKey`它继续工作 和遗产 `KIT_KEY:<keyId>:<keySecret>` 值仍然被接受,所以您可以按照自己的速度移动。 当两者 字段已经设置, `apiKey` 赢了.

## 许可证

这个项目根据Apache 2.0许可证获得许可. 联系人 [支助](https://help.circle.com/s/submit-ticket) 详细情况.

## 常见问题

### @circle-fin/earn-kit 是什么？

DeFi 出借金库的SDK 存款、提款和奖励

### 如何安装 @circle-fin/earn-kit？

在项目目录运行 npm install @circle-fin/earn-kit，或使用 pnpm add / yarn add / bun add。

### @circle-fin/earn-kit 支持 TypeScript 吗？

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

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

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

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

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

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

@circle-fin/earn-kit 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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