应用套件
用于构建稳定币(如USDC)应用的一站式 Circle SDK,为连接,互换,统一平衡管理等稳定币操作提供了一套统一的链上工具.
进行跨链转移,同链互换,统一平衡管理,并像单一函数调用一样简单发信
目录
概览
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遵循一个可调和的架构,将 Bridge Kit, Swap Kit, 统一平衡 Kit, 和 Earn Kit 整合在一起:
┌──────────────────────────────────────────────────────────────────────────┐
│ 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) │
└─────────────────┘
- 适配器: 处理特定区块链操作(钱包、交易、气体)
- 提供者: 执行协议(连接的CCTPv2、交换的Circle Service、统一平衡的网关、金库的收益)
- 桥/铺/统一余额/耳套:每种业务类型的专用包
- 应用套件: 提供一致 API 的统一管线层
这种分离确保了每个组成部分都有单一的责任,同时保持整个稳定币操作生命周期的无缝融合.
安装
npm install @circle-fin/app-kit
# or
yarn add @circle-fin/app-kit
适配器
选择目标链的适当适配器 :
# 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
链式定义
从工具包直接导入链定义 :
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从一个链转到另一个链:
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',
})
同钱交换
在同一条链上互换指使, 支持多个稳定币 :
// 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,
},
})
估计业务
在执行业务前获取费用估计数:
// 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 查询支持的链条
检查支持特定操作的链条 :
// 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余额——存入任何链条,花在任何其他上,查询余额,管理代表:
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 读取。 。 。 .
======================================================================================================= (=========================================================================================
说明: 恩杰快来了 此处所记录的API将公布,以便早日整合和反馈;库库的可用性和生产准备情况将在普遍可用之前宣布.
存入并退出 DeFi 出借金库, 索赔奖励和查询位置 :
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 读取。 。 。 .
配置
发送参数
这个 send() 从源适配器到收件人地址或适配器的同一链条上的方法转移符:
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 薄荷地址
说明: 对于互换业务而言,额外的稳定币和被包裹的资产是: 已支持。 见 交换参数 下节.
实例
// 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让它去
使用无权限(无键)路径.
config: {
apiKey: process.env.CIRCLE_API_KEY, // <ENV>_API_KEY:<keyId>:<keySecret>
}
API密钥是服务器唯一的秘密——由浏览器投掷提供. 别动 在您的服务器上, 并将准备的交易转发给客户端 .
从
kitKey数字 :config.kitKey以有利于config.apiKey它继续工作 和遗产KIT_KEY:<keyId>:<keySecret>值仍然被接受,所以您可以按照自己的速度移动。 当两者 字段已经设置,apiKey赢了.
交换参数
对于明确的同链互换:
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)
用不同的托肯交换示例
// 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,
},
})
桥梁参数
对于明确的跨链桥:
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支持桥接和互换操作的自定义开发商收费.
操作级别自定义费
对单个业务适用自定义收费:
// 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 级别 。 仅配置需要自定义收费的操作 .
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')
处理错误
该工具包采用了深思熟虑的错误处理方法:
- 硬错误 (推出):验证、配置和认证出错
- 软错误 (已归还):可收回的问题,如余额不足或网络出错
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'),
)
}
实例
基本分钱转让
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)
同名切入交换
// 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)
发送到不同的地址
// 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',
})
事件监测
// 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读取 为全API.kit.earn.*- 收入金库业务(存款、退款、追偿、获得沃厄斯、获得Position和引用帮助者)。 见@circle-fin/earn-kit读取 为全API.
发展
大楼
# From the root of the monorepo
nx build @circle-fin/app-kit
测试
# From the root of the monorepo
nx test @circle-fin/app-kit
地方发展
# 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
社区与支持
- 调和数字 : 加入我们的社区
许可证
这个项目根据Apache 2.0许可证获得许可. 联系人 支助 详细情况.