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

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

版本：1\.21\.0
npm 元数据更新时间：2026-11-05T17:22:53.705Z
中文译文更新时间：2026-11-09T16:43:40.344Z
软件包许可：未声明

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

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

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

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

## 中文简介

用于构建稳定币(如USDC)应用的一站式 Circle SDK 解决方案,包括连接、互换和更多的链上操作

## 安装

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

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

## README

# 应用套件

[![npm version](https://badge.fury.io/js/@circle-fin%2Fapp-kit.svg)](https://badge.fury.io/js/@circle-fin%2Fapp-kit) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Discord](https://img.shields.io/discord/473781666251538452?label=Discord&logo=discord)](https://discord.com/invite/buildoncircle)

**用于构建稳定币(如USDC)应用的一站式 Circle SDK,为连接,互换,统一平衡管理等稳定币操作提供了一套统一的链上工具.**

_进行跨链转移,同链互换,统一平衡管理,并像单一函数调用一样简单发信_

## 目录

-   [应用套件](https://npmcn.com/package/%40circle-fin/app-kit/#readme-app-kit)
    -   [目录](https://npmcn.com/package/%40circle-fin/app-kit/#readme-table-of-contents)
    -   [概览](https://npmcn.com/package/%40circle-fin/app-kit/#readme-overview)
        -   [为什么是App Kit?](https://npmcn.com/package/%40circle-fin/app-kit/#readme-why-app-kit)
    -   [建筑流程](https://npmcn.com/package/%40circle-fin/app-kit/#readme-architecture-flow)
    -   [安装](https://npmcn.com/package/%40circle-fin/app-kit/#readme-installation)
        -   [适配器](https://npmcn.com/package/%40circle-fin/app-kit/#readme-adapters)
    -   [快速启动](https://npmcn.com/package/%40circle-fin/app-kit/#readme-quick-start)
        -   [{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}](https://npmcn.com/package/%40circle-fin/app-kit/#readme--cross-chain-bridge)
        -   [同钱交换](https://npmcn.com/package/%40circle-fin/app-kit/#readme--same-chain-swap)
        -   [估计业务](https://npmcn.com/package/%40circle-fin/app-kit/#readme--estimate-operations)
        -   [QQ 查询支持的链条](https://npmcn.com/package/%40circle-fin/app-kit/#readme--query-supported-chains)
        -   [统一余额](https://npmcn.com/package/%40circle-fin/app-kit/#readme--unified-balance)
        -   [\======================================================================================================= (=========================================================================================](https://npmcn.com/package/%40circle-fin/app-kit/#readme--earn)
    -   [配置](https://npmcn.com/package/%40circle-fin/app-kit/#readme-configuration)
        -   [发送参数](https://npmcn.com/package/%40circle-fin/app-kit/#readme-send-parameters)
        -   [交换参数](https://npmcn.com/package/%40circle-fin/app-kit/#readme-swap-parameters)
        -   [桥梁参数](https://npmcn.com/package/%40circle-fin/app-kit/#readme-bridge-parameters)
    -   [自定义收费](https://npmcn.com/package/%40circle-fin/app-kit/#readme-custom-fees)
        -   [操作级别自定义费](https://npmcn.com/package/%40circle-fin/app-kit/#readme-operation-level-custom-fees)
        -   [Kit- Level 自定义收费政策](https://npmcn.com/package/%40circle-fin/app-kit/#readme-kit-level-custom-fee-policies)
    -   [处理错误](https://npmcn.com/package/%40circle-fin/app-kit/#readme-error-handling)
    -   [实例](https://npmcn.com/package/%40circle-fin/app-kit/#readme-examples)
        -   [基本分钱转让](https://npmcn.com/package/%40circle-fin/app-kit/#readme-basic-cross-chain-transfer)
        -   [同名切入交换](https://npmcn.com/package/%40circle-fin/app-kit/#readme-same-chain-token-swap)
        -   [发送到不同的地址](https://npmcn.com/package/%40circle-fin/app-kit/#readme-send-to-different-address)
        -   [事件监测](https://npmcn.com/package/%40circle-fin/app-kit/#readme-event-monitoring)
    -   [API 参考](https://npmcn.com/package/%40circle-fin/app-kit/#readme-api-reference)
        -   [核心方法](https://npmcn.com/package/%40circle-fin/app-kit/#readme-core-methods)
    -   [发展](https://npmcn.com/package/%40circle-fin/app-kit/#readme-development)
        -   [大楼](https://npmcn.com/package/%40circle-fin/app-kit/#readme-building)
        -   [测试](https://npmcn.com/package/%40circle-fin/app-kit/#readme-testing)
        -   [地方发展](https://npmcn.com/package/%40circle-fin/app-kit/#readme-local-development)
    -   [社区与支持](https://npmcn.com/package/%40circle-fin/app-kit/#readme-community--support)
    -   [许可证](https://npmcn.com/package/%40circle-fin/app-kit/#readme-license)

## 概览

App Kit生态系统是Circle的开源努力,以SDK来简化稳定币的开发,这些SDK易于正确使用并难以被滥用. Kit是跨框架的 (viem, ethers, @solana/web3) , 并且干净地融入到任何堆栈中 。 他们有明智的默认, 但提供逃生舱门 完全控制。 一个可插接的架构使执行具有灵活性,所有工具包都具有互通性,因此可以编组,以适应广泛的使用案例.

App Kit 提供了一个 **统一接口** 用于跨链转移,同链互换,信使发送,赚取金库业务,统一余额管理. 它将Bridge Kit,Swap Kit,Ein Kit,和统一平衡Kit的功率合并为一个单一的,有凝聚力的API,每个操作都有明确的方法.

### 为什么是App Kit?

-   **统一接口**: 单 SDK 表面用于桥接,互换,发送,赚取,并统一平衡操作
-   **明确操作方法**选择 `bridge`, (中文(简体) ), `swap`, (中文(简体) ), `send`, (中文(简体) ), `earn`,或 `unifiedBalance` 基于您正在构建的流量
-   **零配置默认值**: 内建可靠的 RPC 端点 - 立即开始建设
-   **带上自己的基础设施**: 在需要时与您的现有设置无缝整合
-   **\* 生产准备安全**: 用于连接和信任的互换供应商的收银圈 CCTPv2
-   **QQ 开发者经验**: 完整的类型Script支持,全面验证,以及即时连接
-   **++ 多链支持**: 跨桥 **52个链条** 与 **1300条桥梁路线总数** 通过 Circle 的 CCTPv2
    -   **主网(26个链)**: Arbitrum, Arc, Avalanche, Base, Codex, Cronos, Edge, Ethereum, HyperEVM, 注射式,墨水, Linea, Monad, Morph, OP Mainnet, Pharos, Plasma, Plume, Polygon PoS, Sei, 索拉纳, 索尼克, 单链, 世界链, XDC, X层
    -   **测试网(26个链)**: Arc Testnet, Arbitrum Sepolia, Avalanche Fuji, Base Sepolia, Codex Testnet, Cronos Testnet, Edge Testnet, Ethereum Sepolia, HyperEVM Testnet, Impiret Testnet, Iink Testnet, Linea Sepolia, Monad Testnet, 莫夫特网, OP Sepolia, Pharos Atlantic, Plasma Testnet, Plume Testnet, Polygon Pos Amoy, See Testnet, Solana Devnet, Sonic Testnet, Unchain Sepolia, 世界链塞波利亚, XDC Apothem, X地层 Testnet
-   **++ 交换支持**:由 Circle 稳定币服务提供动力的同链令牌互换
-   **QQ 收入支持**: DeFi 通过 `kit.earn`
-   **\* 弹性适配器**: 支持EVM(viem,以太)和索拉纳(@solana/web3)
-   **实时活动监测**:跟踪整个运行周期的进展情况
-   **强力错误处理**:优雅的部分成功恢复
-   **飞行前验证**: 在执行前对业务进行成本估算核查

## 开发者文档

-   [App Kit 文档](https://docs.arc.network/app-kit)

## 建筑流程

App Kit遵循一个可调和的架构,将 Bridge Kit, Swap Kit, 统一平衡 Kit, 和 Earn Kit 整合在一起:

```text
┌──────────────────────────────────────────────────────────────────────────┐
│                                 App Kit                                  │
│                           (Unified Interface)                            │
└───────────────────────────────────┬──────────────────────────────────────┘
                                    │
       ┌────────────────┬───────────┴──────┬──────────────────┐
       │                │                  │                  │
       ▼                ▼                  ▼                  ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│  Bridge Kit  │ │   Swap Kit   │ │ Unified Balance  │ │   Earn Kit   │
│ (Cross-Chain)│ │ (Same-Chain) │ │      Kit         │ │  (Vaults)    │
└──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ └──────┬───────┘
       │                │                  │                  │
       ▼                ▼                  ▼                  ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│   Provider   │ │   Provider   │ │     Provider     │ │   Provider   │
│   (CCTPv2)   │ │  (Service)   │ │   (Gateway v1)   │ │   (Earn)     │
└──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ └──────┬───────┘
       │                │                  │                  │
       └────────────────┴───────────┬──────┴──────────────────┘
                                    │
                                    ▼
                           ┌─────────────────┐
                           │     Adapter     │
                           │  (Blockchain)   │
                           └─────────────────┘
```

1.  **适配器**: 处理特定区块链操作(钱包、交易、气体)
2.  **提供者**: 执行协议(连接的CCTPv2、交换的Circle Service、统一平衡的网关、金库的收益)
3.  **桥/铺/统一余额/耳套**:每种业务类型的专用包
4.  **应用套件**: 提供一致 API 的统一管线层

这种分离确保了每个组成部分都有单一的责任,同时保持整个稳定币操作生命周期的无缝融合.

## 安装

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

### 适配器

选择目标链的适当适配器 :

```bash
# For EVM chains (Ethereum, Base, Arbitrum, etc.)
npm install @circle-fin/adapter-viem-v2 viem
# or
yarn add @circle-fin/adapter-viem-v2 viem

# For EVM chains using Ethers.js
npm install @circle-fin/adapter-ethers-v6 ethers
# or
yarn add @circle-fin/adapter-ethers-v6 ethers

# For Solana
npm install @circle-fin/adapter-solana @solana/web3.js
# or
yarn add @circle-fin/adapter-solana @solana/web3.js
```

### 链式定义

从工具包直接导入链定义 :

```typescript
import { Ethereum, Base, Polygon, Solana } from '@circle-fin/app-kit/chains'

// Use with adapter context
const result = await kit.bridge({
  from: { adapter, chain: Ethereum },
  to: { adapter, chain: Base },
  amount: '10.50',
})
```

一个由40个CCTPv2支持的链条组成的编译子集可供从App Kit导入.

## 快速启动

### {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}

将USDC从一个链转到另一个链:

```typescript
import { AppKit } from '@circle-fin/app-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

// Initialize the kit
const kit = new AppKit()

// Create ONE adapter that works across all chains
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as string,
})

// Bridge from Ethereum to Base
const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '10.50',
})
```

### 同钱交换

在同一条链上互换指使, 支持多个稳定币 :

```typescript
// Swap USDC to USDT on Ethereum
const result = await kit.swap({
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'USDC',
  tokenOut: 'USDT',
  amountIn: '100.0',
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
  },
})

// Swap DAI to USDC (18 decimals handled automatically)
const daiSwap = await kit.swap({
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'DAI',
  tokenOut: 'USDC',
  amountIn: '500.0',
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
  },
})

// Swap native ETH to stablecoin
const nativeSwap = await kit.swap({
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'NATIVE', // ETH on Ethereum
  tokenOut: 'USDC',
  amountIn: '1.5',
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
  },
})
```

### 估计业务

在执行业务前获取费用估计数:

```typescript
// Estimate bridge operation
const bridgeEstimate = await kit.estimateBridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '10.50',
})

// Estimate swap operation
const swapEstimate = await kit.estimateSwap({
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'USDC',
  tokenOut: 'USDT',
  amountIn: '100.0',
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
  },
})

console.log('Bridge fees:', bridgeEstimate.fees)
console.log(
  'Swap estimated output:',
  swapEstimate.estimatedOutput?.amount,
  swapEstimate.estimatedOutput?.token,
)
```

### QQ 查询支持的链条

检查支持特定操作的链条 :

```typescript
// Get all chains (bridge, swap, earn, borrow, and unified balance)
const allChains = kit.getSupportedChains()

// Get all chains that support bridging
const bridgeChains = kit.getSupportedChains('bridge')

// Get all chains that support swapping
const swapChains = kit.getSupportedChains('swap')

// Get chains that support earn vault operations
const earnChains = kit.getSupportedChains('earn')

// Get chains that support borrow operations
const borrowChains = kit.getSupportedChains('borrow')

// Get chains that support unified balance operations
const ubChains = kit.getSupportedChains('unifiedBalance')
```

### 统一余额

管理统一、跨链的USDC余额——存入任何链条,花在任何其他上,查询余额,管理代表:

```typescript
import { AppKit } from '@circle-fin/app-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

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

// Query balances across all chains
const balances = await kit.unifiedBalance.getBalances({
  token: 'USDC',
  sources: { adapter },
})

// Deposit USDC into unified balance
const deposit = await kit.unifiedBalance.deposit({
  from: { adapter, chain: 'Ethereum' },
  amount: '100',
  token: 'USDC',
})

// Spend from unified balance on a different chain
const spend = await kit.unifiedBalance.spend({
  amount: '50',
  token: 'USDC',
  from: { adapter, allocations: [{ amount: '50', chain: 'Ethereum' }] },
  to: { adapter, chain: 'Base' },
})

// Estimate spend fees before executing
const estimate = await kit.unifiedBalance.estimateSpend({
  amount: '50',
  token: 'USDC',
  from: { adapter, allocations: [{ amount: '50', chain: 'Ethereum' }] },
  to: { adapter, chain: 'Base' },
})

// Manage delegates
await kit.unifiedBalance.addDelegate({
  from: { adapter, chain: 'Ethereum' },
  delegateAddress: '0xDelegate…',
})

// Listen to unified balance events
kit.on('unifiedBalance.gateway.spend.succeeded', (payload) => {
  console.log('Spend succeeded:', payload)
})
```

完整的统一余额 API,见 [`@circle-fin/unified-balance-kit` 读取](https://npmcn.com/package/%40circle-fin/unified-balance-kit/README.md)。 。 。 .

### \======================================================================================================= (=========================================================================================

> **说明:** 恩杰快来了 此处所记录的API将公布,以便早日整合和反馈;库库的可用性和生产准备情况将在普遍可用之前宣布.

存入并退出 DeFi 出借金库, 索赔奖励和查询位置 :

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

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

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

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

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

// Execute a cross-chain deposit into an Earn vault
const bridgeDeposit = await kit.earn.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}`)

// Cross-chain Earn deposits currently support Ethereum Sepolia, Arbitrum
// Sepolia, and Base Sepolia as sources, with Arc Testnet as the Earn
// destination.

// Query a vault position
const position = await kit.earn.getPosition({
  from: { adapter, chain: EarnChain.Arc_Testnet },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
})

// Claim accrued rewards
await kit.earn.claimRewards({
  from: { adapter, chain: EarnChain.Arc_Testnet },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
})
```

同链收益存款保留现有交易结果. 跨链收入 返回桥提交细节,例如 `execId`, (中文(简体) ), `status`,以及 `expiresAt`。 。 。 .

有关En API的完整信息,请参见 [`@circle-fin/earn-kit` 读取](https://npmcn.com/package/%40circle-fin/earn-kit/README.md)。 。 。 .

## 配置

### 发送参数

这个 `send()` 从源适配器到收件人地址或适配器的同一链条上的方法转移符:

```typescript
interface SendParams {
  from: AdapterContext // Source wallet and chain
  to: Adapter | string // Destination wallet or address
  amount: string // Amount to transfer (e.g., '10.50')
  token?: TokenAlias | string // Optional, defaults to 'USDC'
}
```

**脚本支持**

这个 `token` 字段接受已知的别名和自定义的符号合同地址:

**已知的别名( 用于发送操作) :**

-   `'USDC'` - 硬币(6个小数)
-   `'USDT'` - 绳索美元(6个小数)
-   `'NATIVE'` - 连锁店的本国货币(ETH、SOL等)
-   `'EURC'` - 欧币,与 `eurcAddress` 配置

**自定义地址 :**

-   EVM合同地址(例如, `0x6B175474E89094C44Da98b954EedeAC495271d0F`(中文(简体) )
-   索拉纳 SPL 薄荷地址

**说明**: 对于互换业务而言,额外的稳定币和被包裹的资产是: 已支持。 见 [交换参数](https://npmcn.com/package/%40circle-fin/app-kit/#readme-swap-parameters) 下节.

**实例**

```typescript
// Using USDC (default)
await kit.send({
  from: { adapter, chain: 'Ethereum' },
  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  amount: '10.0',
  token: 'USDC',
})

// Using USDT
await kit.send({
  from: { adapter, chain: 'Ethereum' },
  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  amount: '100.0',
  token: 'USDT',
})

// Using NATIVE
await kit.send({
  from: { adapter, chain: 'Ethereum' },
  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  amount: '1.5',
  token: 'NATIVE', // ETH on Ethereum
})

// Using a custom ERC-20 token address (e.g., DAI)
await kit.send({
  from: { adapter, chain: 'Ethereum' },
  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  amount: '50.0',
  token: '0x6B175474E89094C44Da98b954EedeAC495271d0F', // DAI contract address
})

// Using a custom SPL token on Solana
await kit.send({
  from: { adapter, chain: 'Solana' },
  to: 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN',
  amount: '50.0',
  token: 'So11111111111111111111111111111111111111112', // Wrapped SOL
})
```

### 认证

服务支持操作将 Circle API 键作为 `config.apiKey`让它去 使用无权限(无键)路径.

```typescript
config: {
  apiKey: process.env.CIRCLE_API_KEY, // <ENV>_API_KEY:<keyId>:<keySecret>
}
```

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

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

### 交换参数

对于明确的同链互换:

```typescript
interface SwapParams {
  from: AdapterContext // Source wallet and chain
  tokenIn: SupportedToken // Input token
  tokenOut: SupportedToken // Output token
  amountIn: string // Amount to swap
  to?: string // Optional recipient address
  config?: SwapConfig // Optional swap configuration
}

// SupportedToken includes:
// - Stablecoins (6 decimals): 'USDC', 'EURC', 'USDT', 'PYUSD'
// - Stablecoins (18 decimals): 'DAI', 'USDE'
// - Wrapped assets: 'WBTC', 'WETH', 'WSOL', 'WAVAX', 'WPOL', 'CIRBTC'
// - Native: 'NATIVE' (chain's native currency)
```

**用不同的托肯交换示例**

```typescript
// Swap between 6-decimal stablecoins
await kit.swap({
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'EURC',
  tokenOut: 'USDC',
  amountIn: '100.0',
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
  },
})

// Swap DAI (18 decimals) to USDT
await kit.swap({
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'DAI',
  tokenOut: 'USDT',
  amountIn: '500.0', // SDK automatically handles 18-decimal precision
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
  },
})

// Swap native token to stablecoin
await kit.swap({
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'NATIVE', // ETH on Ethereum
  tokenOut: 'USDC',
  amountIn: '2.5',
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
  },
})
```

### 桥梁参数

对于明确的跨链桥:

```typescript
interface BridgeParams {
  from: AdapterContext // Source wallet and chain
  to: BridgeDestination // Destination wallet/address and chain
  amount: string // Amount to transfer (e.g., '10.50')
  token?: 'USDC' // Optional, defaults to 'USDC'
  config?: BridgeConfig // Optional bridge configuration
}
```

## 自定义收费

App Kit支持桥接和互换操作的自定义开发商收费.

### 操作级别自定义费

对单个业务适用自定义收费:

```typescript
// Bridge with custom fee
await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '1000',
  config: {
    customFee: {
      value: '10', // 10 USDC fee
      recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
    },
  },
})

// Swap with custom fee
await kit.swap({
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'USDC',
  tokenOut: 'USDT',
  amountIn: '1000',
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
    customFee: {
      value: '10',
      recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
    },
  },
})
```

### Kit- Level 自定义收费政策

关于动态收费计算,请在 App Kit 级别 。 仅配置需要自定义收费的操作 .

```typescript
import { AppKit } from '@circle-fin/app-kit'

const kit = new AppKit()

kit.setCustomFeePolicy({
  bridge: {
    computeFee: (params) => {
      const amount = Number(params.amount)
      return (amount * 0.01).toFixed(6)
    },
    resolveFeeRecipientAddress: (chain) => {
      return chain.type === 'solana'
        ? 'SolanaAddressBase58...'
        : '0xEvmAddress...'
    },
  },
  swap: {
    computeFee: (params) => {
      const amount = Number(params.amountIn)
      return (amount * 0.005).toFixed(6)
    },
    resolveFeeRecipientAddress: (chain) => {
      return chain.type === 'solana'
        ? 'SolanaAddressBase58...'
        : '0xEvmAddress...'
    },
  },
  unifiedBalance: {
    computeFee: (params) => {
      const amount = Number(params.amount)
      return (amount * 0.01).toFixed(6)
    },
    resolveFeeRecipientAddress: (destinationChain) => {
      return destinationChain.type === 'solana'
        ? 'SolanaAddressBase58...'
        : '0xEvmAddress...'
    },
  },
})

// All subsequent configured operations will use these policies
await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '1000', // Custom fee calculated automatically
})

// Remove one operation-scoped policy without affecting the others
kit.removeCustomFeePolicy('bridge')
```

## 处理错误

该工具包采用了深思熟虑的错误处理方法:

-   **硬错误** (推出):验证、配置和认证出错
-   **软错误** (已归还):可收回的问题,如余额不足或网络出错

```typescript
import { AppKit } from '@circle-fin/app-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

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

const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '100.0',
})

if (result.state === 'success') {
  console.log('Operation successful!')
} else {
  // Handle partial completion with recovery information
  console.log(
    'Successful steps:',
    result.steps.filter((s) => s.state === 'success'),
  )
}
```

## 实例

### 基本分钱转让

```typescript
import { AppKit } from '@circle-fin/app-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

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

// Bridge USDC from Ethereum to Base
const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '50.0',
})

console.log('Bridge result:', result)
```

### 同名切入交换

```typescript
// Swap USDC to USDT on Ethereum
const result = await kit.swap({
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'USDC',
  tokenOut: 'USDT',
  amountIn: '100.0',
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
  },
})

console.log('Swap result:', result)
```

### 发送到不同的地址

```typescript
// Send to a different address on the same chain
const result = await kit.send({
  from: { adapter, chain: 'Ethereum' },
  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  amount: '10.50',
  token: 'USDC',
})
```

### 事件监测

```typescript
// Listen to bridge events
kit.on('bridge.approve', (payload) => {
  console.log('Approval transaction:', payload.values.txHash)
})

kit.on('bridge.burn', (payload) => {
  console.log('Burn transaction:', payload.values.txHash)
})

// Listen to all events
kit.on('*', (payload) => {
  console.log('Action:', payload.method)
})

// Execute operation
await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '10.0',
})
```

## API 参考

### 核心方法

-   `kit.send(params)` - 向同一链条上的接收者发送信号
-   `kit.bridge(params)` - 执行跨链桥操作
-   `kit.retryBridge(result, retryContext)` - 重试失败的桥梁操作
-   `kit.swap(params)` - 执行同链互换业务
-   `kit.estimateBridge(params)` - 获取连接费用估算
-   `kit.estimateSwap(params)` - 获得交换费用估计
-   `kit.estimateSend(params)` - 获取发送业务的成本估算
-   `kit.getSwapStatus(params)` - 获取互换当前状态
-   `kit.waitForSwap(params)` - 在交换达到终端状态之前
-   `kit.getTokenRates(params)` - 获取缓存的美元利率
-   `kit.getSupportedChains(operationType?)` - 按操作类型分列的查询支持链(`'bridge'`, (中文(简体) ), `'swap'`, (中文(简体) ), `'earn'`, (中文(简体) ), `'borrow'`, (中文(简体) ), `'unifiedBalance'`(中文(简体) )
-   `kit.setCustomFeePolicy(policy)` - 制定业务范围海关收费政策
-   `kit.removeCustomFeePolicy(operation)` - 取消业务范围自定义收费政策
-   `kit.on(event, handler)` - 听操作事件
-   `kit.off(event, handler)` - 删除事件听众
-   `kit.unifiedBalance.*` - 统一平衡业务(存款、支出、获得贷款、估计支出、代表等)。 见 [`@circle-fin/unified-balance-kit` 读取](https://npmcn.com/package/%40circle-fin/unified-balance-kit/README.md) 为全API.
-   `kit.earn.*` - 收入金库业务(存款、退款、追偿、获得沃厄斯、获得Position和引用帮助者)。 见 [`@circle-fin/earn-kit` 读取](https://npmcn.com/package/%40circle-fin/earn-kit/README.md) 为全API.

## 发展

### 大楼

```bash
# From the root of the monorepo
nx build @circle-fin/app-kit
```

### 测试

```bash
# From the root of the monorepo
nx test @circle-fin/app-kit
```

### 地方发展

```bash
# Install dependencies
yarn install

# Build all packages
yarn build

# Build the app-kit specifically
nx build @circle-fin/app-kit

# Run tests
nx test @circle-fin/app-kit
```

## 社区与支持

-   **调和**数字 : [加入我们的社区](https://discord.com/invite/buildoncircle)

## 许可证

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

* * *

**准备好开始建造了吗?**

[加入磁盘](https://discord.com/invite/buildoncircle)

_由 Circle 创建_

## 常见问题

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

用于构建稳定币\(如USDC\)应用的一站式 Circle SDK 解决方案,包括连接、互换和更多的链上操作

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

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

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

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

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

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

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

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

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

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

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

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

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

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