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

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

版本：1\.9\.1
npm 元数据更新时间：2026-11-05T17:19:18.727Z
中文译文更新时间：2026-11-09T16:42:54.278Z
软件包许可：未声明

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

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

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

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

## 中文简介

A Circle SDK 用于最小代码的单链令牌互换

## 安装

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

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

## README

# 交换工具箱

[![npm version](https://badge.fury.io/js/@circle-fin%2Fswap-kit.svg)](https://badge.fury.io/js/@circle-fin%2Fswap-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)

**A Circle SDK用于单链令牌互换,最小代码,辅以强型安全及全面验证.**

_使交换像单一函数调用一样简单_

## 目录

-   [交换工具箱](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-swap-kit)
    -   [概览](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-overview)
    -   [安装](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-installation)
    -   [快速启动](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-quick-start)
    -   [配置](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-configuration)
        -   [自定义收费](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-custom-fees)
        -   [自定义提供者(类型)](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-custom-providers-typed)
        -   [交换配置选项](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-swap-configuration-options)
        -   [支持的托肯斯语Name](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-supported-tokens)
        -   [使用本地托肯语Name](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-using-native-token)
    -   [类型定义](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-type-definitions)
        -   [交换](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-swapparams)
        -   [自定义文件政策](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-customfeepolicy)
    -   [验证](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-validation)
    -   [许可证](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-license)
    -   [支助](https://npmcn.com/package/%40circle-fin/swap-kit/#readme-support)

## 概览

交换Kit为建立可树摇动的互换操作提供了基础:

-   🔒 **类型安全**: 完整类型脚本支持, 严格类型检查
-   ✅ **运行时间验证**: 参数验证的综合Zod计划
-   📝 **丰富的文档**: 完成 JSDoc 并附有可运行实例
-   🎯 **开发者经验**: IntelliSense 支持和清除错误消息
-   🔧 **弹性配置**:定制收费政策和互换战略

## 开发者文档

-   [交换套件文档](https://docs.arc.network/app-kit/swap)

## 安装

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

## 快速启动

交换 Kit 提供了两种使用模式—— 选择最适合您的项目:

-   链条选择受到互换支持的网络的限制. 支持的链条包括: 使用 CCTP v2 和至少一个支持的代号(USDC、USDT、EURC、EURC)的主网网络, 或登记在册的标志)。 目前的例子:Ethereum、Base、Polygon、Arbitrum、, 乐观主义,雪崩,莫纳德,索拉纳等. 使用 `getSupportedChains()` 获取 完整的最新名单.

### 基于类的使用

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

// Create a SwapKit instance
const kit = new SwapKit()

// Create an adapter
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY,
})

// Define swap parameters
const params = {
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'USDC',
  tokenOut: 'USDT',
  amountIn: '100.50',
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
    slippageBps: 300, // 3% slippage tolerance
    allowanceStrategy: 'permit',
  },
}

// Get an estimate
const estimate = await kit.estimate(params)
console.log(
  `Estimated output: ${estimate.estimatedOutput?.amount} ${estimate.estimatedOutput?.token}`,
)

// Execute the swap
const result = await kit.swap(params)
```

### 功能用法( Tree- Shakeable)

```typescript
import { createSwapKitContext, estimate, swap } from '@circle-fin/swap-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

// Create a swap context
const context = createSwapKitContext()

// Create an adapter
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY,
})

// Define swap parameters
const params = {
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'USDC',
  tokenOut: 'USDT',
  amountIn: '100.50',
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
    slippageBps: 300,
    allowanceStrategy: 'permit',
  },
}

// Get an estimate
const quoteResult = await estimate(context, params)
console.log(
  `Estimated output: ${quoteResult.estimatedOutput?.amount} ${quoteResult.estimatedOutput?.token}`,
)

// Execute the swap
const result = await swap(context, params)
```

这两种模式都提供了相同的功能——基于类的方法提供了一个熟悉的基于类的界面,而功能方法则允许更好的树摇和更小的捆绑大小.

## 配置

## 自定义收费

交换Kit支持两种收取自定义开发商费的方法.

### 1\. 按百分比计算的费用

直接按百分比计算的收费:

```typescript
await kit.swap({
  from: { adapter, chain: Ethereum },
  tokenIn: 'USDC',
  tokenOut: 'DAI',
  amountIn: '100',
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
    customFee: {
      percentageBps: 1000, // 10% fee (100 = 1%)
      recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    },
  },
})
```

### 2\. 基于回调收费

对于复杂的收费逻辑:

**班级:**

```typescript
const kit = new SwapKit({
  customFeePolicy: {
    computeFee: async (ctx) => {
      // Full context with adapter, chain, tokens, amounts
      if (ctx.type === 'output') {
        // Output fee scenario
        // Access to minAmount and estimatedAmount
        const user = await getUser(ctx.from.address)
        if (user.isVIP) {
          return (parseFloat(ctx.minAmount) * 0.05).toString()
        }
        return (parseFloat(ctx.estimatedAmount) * 0.1).toString()
      }

      // Input fee scenario
      return (parseFloat(ctx.amountIn) * 0.05).toString()
    },

    resolveFeeRecipientAddress: (chain, ctx) => {
      return chain.type === 'solana'
        ? 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
        : '0x1234567890123456789012345678901234567890'
    },
  },
})

// Or set/update it later
kit.setCustomFeePolicy({
  computeFee: (ctx) => {
    if (ctx.from.chain.name === 'Ethereum') {
      return (parseFloat(ctx.amountIn) * 0.01).toString()
    }
    return (parseFloat(ctx.amountIn) * 0.005).toString()
  },
  resolveFeeRecipientAddress: (chain) => '0x...',
})

// Remove the fee policy when needed
kit.removeCustomFeePolicy()
```

**职能:**

```typescript
import {
  createSwapKitContext,
  setCustomFeePolicy,
  removeCustomFeePolicy,
} from '@circle-fin/swap-kit'

const context = createSwapKitContext({
  customFeePolicy: {
    computeFee: async (ctx) => {
      if (ctx.type === 'output') {
        return (parseFloat(ctx.estimatedAmount) * 0.1).toString()
      }
      return (parseFloat(ctx.amountIn) * 0.05).toString()
    },
    resolveFeeRecipientAddress: (chain, ctx) => {
      return chain.type === 'solana' ? 'Sol...' : '0x...'
    },
  },
})

// Or set/update later
setCustomFeePolicy(context, {
  computeFee: () => '0.05',
  resolveFeeRecipientAddress: (chain) => '0x...',
})

// Remove when needed
removeCustomFeePolicy(context)
```

* * *

### 自定义提供者(类型)

```typescript
import { createSwapKitContext } from '@circle-fin/swap-kit'

class ExperimentalSwapProvider {
  readonly name = 'ExperimentalSwapProvider'
  // implements SwappingProvider methods (supportsRoute, estimate, swap)
}

const extraProviders = [new ExperimentalSwapProvider()] as const
const context = createSwapKitContext({ providers: extraProviders })

// TypeScript knows the exact provider types:
type RegisteredProviders = typeof context.providers
//    ^? readonly [...DefaultProviders, ExperimentalSwapProvider]
```

上下文将默认提供者与您提供的任何自定义提供者合并,同时保留其文字 类型。 一直这样 `context.providers` 严格打字,做好未来供应商整合的准备.

### 认证

通过圆形 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
const params = {
  from: { adapter, chain: Ethereum },
  tokenIn: 'USDC',
  tokenOut: 'USDT',
  amountIn: '100',
  config: {
    // API key for authentication (optional — omit for permissionless mode)
    apiKey: process.env.CIRCLE_API_KEY,

    // Allowance strategy (default: 'permit')
    allowanceStrategy: 'permit', // or 'approve'

    // Maximum slippage in basis points (default: 300 = 3%)
    slippageBps: 300,

    // Minimum output amount (stop-limit)
    stopLimit: '95000000', // 95 USDT in smallest units

    // Custom fee for this specific swap (percentage approach)
    customFee: {
      percentageBps: 100, // 1% fee
      recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    },

    // Batch approve + swap into one atomic call when the wallet supports it
    // (default). Set false to send approval and swap as two transactions.
    batchTransactions: true,
  },
}
```

> **说明:** 使用交易级别 `percentageBps` 简单收费,或包级 `setCustomFeePolicy()` 用于复杂的逻辑。 它们是相互排斥的.

### 支持的托肯斯语Name

交换Kit支持收费募集的16个令牌. 此列表必须至少包含一个符号( 输入 OR 输出) .

**稳定币 (6 小数):**

-   `USDC` - 硬币
-   `EURC` - 欧币
-   `USDT` - 绳子美元
-   `PYUSD` - 支付费用

**稳定币 (18 小数):**

-   `DAI` - 制造马来币
-   `USDE` - 爱思娜美元

**已包装的托肯斯 :**

-   `WBTC` - 包装了比特币(8个小数)
-   `WETH` - 包装了伊特鲁姆(18个小数)
-   `WSOL` - 包装索拉纳(9个小数)
-   `WAVAX` - 包裹了雪崩(18个小数)
-   `WPOL` - 环形多边形(18个小数)

**本地托肯语 :**

-   `NATIVE` - 决定连锁原生煤气代币(Etheum上的ETH、索拉纳上的SOL等)

**重要内容:** 支持的列表必须至少包含一个符号( 输入 OR 输出) 。 非支持 → 非支持互换是不允许的.

**实例:**

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

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

// Swap native gas token to stablecoin (generic)
await kit.swap({
  from: { adapter, chain: 'Ethereum' },
  tokenIn: 'NATIVE', // ETH on Ethereum, POL on Polygon, SOL on Solana, etc.
  tokenOut: 'USDC',
  amountIn: '1.5',
  config: { apiKey: process.env.CIRCLE_API_KEY },
})

// Swap wrapped ETH to stablecoin on Polygon
await kit.swap({
  from: { adapter, chain: 'Polygon' },
  tokenIn: 'WETH', // Wrapped ETH on Polygon
  tokenOut: 'USDC',
  amountIn: '0.5',
  config: { apiKey: process.env.CIRCLE_API_KEY },
})
```

**说明:** 使用 `NATIVE` 连锁店的内燃气代号 链式特定符号 `ETH`, (中文(简体) ), `POL` 不支持为互换令牌的别名——使用 `NATIVE` 或合同地址.

## 类型定义

### 交换

```typescript
interface SwapParams {
  from: AdapterContext // Source adapter and chain
  tokenIn: SupportedToken // Input token
  tokenOut: SupportedToken // Output token
  amountIn: string // Decimal string (e.g., '10.5')
  config?: SwapConfig // Optional configuration
}

// SupportedToken can be:
// - Stablecoin aliases (6 decimals): 'USDC' | 'EURC' | 'USDT' | 'PYUSD'
// - Stablecoin aliases (18 decimals): 'DAI' | 'USDE'
// - Wrapped tokens: 'WBTC' (8 dec) | 'WETH' | 'WSOL' (9 dec) | 'WAVAX' | 'WPOL' (18 dec)
// - Native token: 'NATIVE' (chain's native gas token)
type SupportedToken =
  | 'USDC'
  | 'EURC'
  | 'USDT'
  | 'USDE'
  | 'DAI'
  | 'PYUSD'
  | 'WBTC'
  | 'WETH'
  | 'WSOL'
  | 'WAVAX'
  | 'WPOL'
  | 'NATIVE'
```

### 交换

估计结果包括将估计数与投入联系起来的投入上下文字段:

```typescript
interface SwapEstimate {
  // Input context (populated from your params)
  tokenIn: SupportedToken // e.g., 'NATIVE'
  tokenOut: SupportedToken // e.g., 'USDC'
  amountIn: string // e.g., '0.00001'
  chain: string // e.g., 'Ethereum'
  fromAddress: string // e.g., '0x2971...5EE9f'
  toAddress: string // e.g., '0x2971...5EE9f'

  // Estimate details
  transaction: object // Raw transaction to sign and submit
  stopLimit: string // Minimum output in base units
  estimatedOutput?: string // Human-readable expected output
  fees?: ServiceSwapFee[] // Fee breakdown
}
```

### 交换结果

互换结果使用简化链字段:

```typescript
interface SwapResult {
  tokenIn: SupportedToken
  tokenOut: SupportedToken
  chain: string // e.g., 'Ethereum'
  amountIn: string // Human-readable amount
  fromAddress: string
  toAddress: string
  txHash: string
  explorerUrl?: string
  fees?: ServiceSwapFee[]
  config?: SwapResultConfig
}
```

### 将链名解为链定义

两者 `SwapEstimate` 财务报告和审定财务报表 `SwapResult` 返回简化 `chain` 字符串( 例如, ), `'Ethereum'`(中文(简体) ) 如果需要全链定义,请使用 `getChainByEnum` 工具栏 :

```typescript
import { getChainByEnum } from '@circle-fin/swap-kit'

// After getting a swap result or estimate
const result = await kit.swap(params)

// Resolve the chain name back to full ChainDefinition
const chainDef = getChainByEnum(result.chain)
console.log(chainDef.chainId) // 1 (for Ethereum)
console.log(chainDef.rpcEndpoints) // ['https://...']
```

### 自定义文件政策

```typescript
interface CustomFeePolicy {
  computeFee: (params: SwapParams) => Promise<string> | string
  resolveFeeRecipientAddress: (
    chain: ChainDefinition,
    params: SwapParams,
  ) => Promise<string> | string
}
```

## 验证

交换 Kit 提供了全面的运行时间验证 :

```typescript
import { assertSwapParams, swapParamsSchema } from '@circle-fin/swap-kit'

try {
  assertSwapParams(params, swapParamsSchema)
  // Parameters are valid
} catch (error) {
  console.error('Validation failed:', error.message)
}
```

## 用法模式:类与功能

交换Kit支持基于类和功能的编程风格. 根据您的偏好选择 :

### 使用基于类( SwapKit) 时 :

-   你喜欢传统的班级模式
-   您的代码库已经使用基于类的库
-   您想要一个类似于其他 SDK 的熟悉的 API
-   {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你不需要强势的震动树的优化

### 使用功能( 创建SwapKitContext + 操作) 当 :

-   您更喜欢功能编程模式
-   ~ 你需要最大的树摇晃 对于更小的捆绑
-   您只想要导入特定操作
-   你正在打造一个 性能关键应用程序

两种办法:

-   提供相同的功能
-   使用相同的基本操作
-   QQ 提供全部类型脚本支持
-   \* 包括全面验证

**示例:选择一种办法**

```typescript
// Class-based: Great for general use
import { SwapKit } from '@circle-fin/swap-kit'
const kit = new SwapKit()
await kit.swap(params)

// Functional: Great for tree-shaking
import { createSwapKitContext, swap } from '@circle-fin/swap-kit'
const context = createSwapKitContext()
await swap(context, params)
```

## 许可证

阿帕奇 - 2.0

## 支助

关于问题,请访问 [GitHub 仓库](https://github.com/circlefin/stablecoin-kits)。 。 。 .

## 常见问题

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

A Circle SDK 用于最小代码的单链令牌互换

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

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

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

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

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

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

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

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

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

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

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

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

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

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