swap-tokens

用途

swap-tokens 用于构建浏览器端或服务端的代币兑换（Swap）功能。它提供两套 SDK 选择：App Kit（@circle-fin/app-kit）是 Circle 的全能 SDK，覆盖 swap、bridge、send、earn 与统一余额；独立 Swap Kit（@circle-fin/swap-kit）则以更轻量的包提供相同的 swap API。除非用户只需要 swap 功能，否则推荐使用 App Kit。

主要能力

同链兑换：在单条链上把一种代币换成另一种。
跨链兑换：在同一次 swap() 调用中设置 to.chain 与 to.recipientAddress，先估算路由，源交易通常返回 progress.status: "PENDING"，再通过 waitForSwap({ result }) 或轮询 getSwapStatus() 直到目标段终态。
默认无密钥（permissionless）：省略 kitKey 即可发起无密钥请求。kit key 仅用于服务端认证请求，属于机密，绝不能出现在浏览器代码中。
支持浏览器与服务端：浏览器钱包（EVM 的 EIP-1193 提供者、Solana 的 Wallet Standard 提供者）无需私钥变量；服务端可使用自托管私钥或 Circle 开发者控制钱包。
汇率估算：通过 estimateSwap()（App Kit）或 estimate()（Swap Kit）预览预期输出与费用。
滑点与费用配置：默认滑点 300 bps（3%），可通过 slippageBps 配置；也可用 stopLimit 设置绝对最小输出量，两者同时设置时 stopLimit 优先。允许策略可选 "permit" 或 "approve"。提供方费用为 2 bps（0.02%），支持自定义开发者费用（Circle 保留 10%，90% 归配置的接收地址）。
第三方聚合器路由：兑换通过第三方 DEX 聚合器路由，当前为 LiFi，聚合器可能因路由而异且会变化，用户执行兑换时受适用聚合器服务条款约束。

使用方式

安装（任选其一作为基础包，再按需添加适配器）：

App Kit + Viem 适配器（推荐）：

npm install @circle-fin/app-kit @circle-fin/adapter-viem-v2 viem

可选：Solana 支持

npm install @circle-fin/adapter-solana-kit @solana/kit @solana/web3.js

可选：Circle Wallets（开发者控制）支持

npm install @circle-fin/adapter-circle-wallets

仅 swap 的独立 Swap Kit（更轻量）：

npm install @circle-fin/swap-kit @circle-fin/adapter-viem-v2 viem

环境变量（服务端）：

PRIVATE_KEY= # EVM 钱包私钥（hex，0x 前缀） KIT_KEY= # 可选，仅服务端认证请求使用 CIRCLE_API_KEY= # Circle API 密钥（Circle Wallets 适配器） CIRCLE_ENTITY_SECRET= # 实体密钥（Circle Wallets 适配器） SOLANA_PRIVATE_KEY= # Solana 钱包私钥（base58）

浏览器钱包集成不需要上述任何私钥变量，从已连接的钱包提供者获取签名者并保持请求无密钥。

SDK 初始化：

import { AppKit } from "@circle-fin/app-kit"; const kit = new AppKit();

import { SwapKit } from "@circle-fin/swap-kit"; const kit = new SwapKit();

决策指南（写代码前必须与用户逐项确认）：

未来是否需要 bridge 或 send 功能？需要或不确定选 App Kit；仅 swap 且永不需要选 Swap Kit。
兑换在哪里运行、钱包如何连接？浏览器 EVM 钱包用 Viem provider 适配器并省略 kitKey；浏览器 Solana 钱包用 Solana provider 适配器并省略 kitKey；服务端自托管私钥进入问题 3；服务端 Circle 开发者控制钱包用 Circle Wallets 适配器。
服务端使用哪条链生态？EVM 用 Viem 私钥适配器；Solana 用 Solana 适配器。若源链与目标链不同，还需阅读跨链兑换参考。

估算示例（App Kit）：

const estimate = await kit.estimateSwap({ from: { adapter, chain: "Ethereum" }, tokenIn: "USDT", tokenOut: "USDC", amountIn: "100.00", });

Swap Kit 使用 kit.estimate({...})。

错误处理：所有兑换操作应包裹在 try/catch 中并检查结果。

适用场景

在浏览器 dApp 中集成无密钥代币兑换。
在服务端使用自托管私钥或 Circle 开发者控制钱包执行兑换。
需要同链或跨链兑换、汇率估算、滑点与费用控制的场景。

限制与安全规则

安全规则不可协商：绝不硬编码、提交或记录机密（私钥、API 密钥、实体密钥、kit key），始终使用环境变量或密钥管理器；绝不在浏览器代码或公共环境变量（VITE_、NEXT_PUBLIC_ 等）中放置私钥、Circle API 密钥、实体密钥或 kit key；绝不把私钥作为明文 CLI 参数传递。
兑换前必须展示已审核的链、代币、金额与估算；绝不自动调用 swap()（不在估算后、effect 中、渲染期间或模块启动时调用）。
必须警告主网兑换会转移真实资金，建议先用小额测试；金额超过安全阈值（如 >100 美元等值）时须警告。
提交前必须校验所有输入（地址、金额、链名、代币符号）；与未审计或未知合约交互前须警告。
绝不在浏览器中传入 kitKey；当前 SDK 版本会在发送请求前拒绝浏览器提供的 kit key。
绝不在浏览器中导入 @circle-fin/adapter-circle-wallets 主入口，它仅限服务端。
不要执行兑换交易或运行转移资金的脚本，始终生成代码供用户自行审核与运行。
浏览器安全包版本要求：App Kit >=1.11.0、Swap Kit >=1.5.0、Unified Balance Kit >=1.3.1、Bridge Kit >=1.12.2，以及对应的 2026 年 7 月 28 日适配器包；应升级旧版本而非添加手动 polyfill。
链标识符为字符串（如 "Ethereum"、"Base"、"Solana"、"Arc"、"Arc_Testnet"），不是数字链 ID。
Arc 上 NATIVE 与 USDC 是同一资产，USDC ↔ NATIVE 兑换为同资产空操作，必须在估算/路由/费用前检测并拒绝，包括一侧为 USDC 合约 0x3600000000000000000000000000000000000000、另一侧为 NATIVE 的情况。
支持的链与代币列表须完整使用，不得硬编码子集。支持的主网链：Arbitrum、Arc、Avalanche、Base、Ethereum、HyperEVM、Ink、Linea、Monad、Optimism、Plume、Polygon、Sei、Solana、Sonic、Unichain、World_Chain、XDC；测试网：Arc_Testnet。支持的代币别名：USDC、EURC、USDT、PYUSD、DAI、USDE、WBTC、WETH、WSOL、WAVAX、WPOL、NATIVE，也可用合约地址指定。
跨链兑换若估算明确报告无支持路由，不要执行；可提供源链换 USDC、USDC 跨链、目标链兑换的备选方案，展示完整计划与估算后，仅由用户触发的 UI 操作启动。不要将验证、传输、超时或限流错误视为无路由的证据。
建议使用精确金额授权而非无限授权；使用 "approve" 策略时把授权限定为本次兑换的具体金额。
费用接收地址须与兑换源在同一网络。
应使用 SDK 导出的类型而非自定义接口。

暂未提供

关于具体收费价格、平台覆盖范围、实际兑换效果等资料暂未提供。