
简而言之
Blockradar 的 Swap API 让您可以通过单一的统一 endpoint 在同一条链上交换资产(swap),或在不同链之间转移资产(bridge)。
Blockradar 的 Swap API 让您可以通过单一的统一 endpoint 在同一条链上交换资产(swap),或在不同链之间转移资产(bridge)。
前提条件
在使用 Swap API 之前,请确保您已具备:1
API 密钥
从 Blockradar Dashboard 获取您的 API 密钥。前往 Developers 进行生成。
2
已创建钱包
在 dashboard 中(参见创建主钱包)创建钱包。您将需要
walletId 来执行 swap 操作。3
资产 ID
在 dashboard 的 Assets 中或通过 Get Assets API 获取源资产和目标资产的
assetId。4
充足余额
确保您的钱包持有足够的源资产余额,以覆盖 swap 金额及网络手续费。
工作原理
Blockradar 会根据您选择的资产自动判断该交易是 swap 还是 bridge:Swap
在同一区块链上交换不同资产。示例:Base 上的 USDC → USDT
Bridge
在不同区块链之间转移资产。示例:BSC 上的 USDC → Optimism 上的 USDC
支持的资产与链
Swap API 在 Blockradar 支持的链上支持主要稳定币:请参阅集成了解支持的网络与稳定币完整列表。
Master Wallet 与 Child Address
Swap API 在两个层级上提供:Master Wallet
直接从您的 master wallet 执行 swap。适合资金管理操作。
Child Address
从单个 child address 执行 swap。非常适合面向特定用户的操作。
Endpoints
第 1 步:获取报价
在执行 swap 之前,始终获取报价以向用户展示预期结果。请求参数
当用户输入想要花费的金额时,使用
amountSide: "source"。当用户输入想要收到的金额,并需要 Blockradar 计算所需源金额时,使用 amountSide: "target"。Stellar 收款人路由
只有当目标链为 Stellar 时,才支持recipientRouting。它是本指南中所有报价和执行端点共用的通用路由约定。现有的 EVM、Solana 和 Tron 请求不受影响、保持不变:它们不得发送 recipientRouting;包含该字段的请求会被拒绝。
recipientAddress 仍是可选字符串;请勿将其作为对象发送。请勿发送单独的收款人 memo 字段。
Stellar 目标规则
- Muxed
M...收款人:省略recipientRouting。路由 ID 已嵌入 muxed 地址中,提供路由数据会被拒绝。 - 带路由 ID 的基础
G...收款人:发送{ type: "memo_id", value: "123" }。value必须是介于0和18446744073709551615之间的非空数字字符串。Blockradar 会在请求报价或执行前将地址规范化为M...。 - 不带路由 ID 的基础
G...收款人:发送{ type: "none" },且不要包含value。没有recipientRouting的G...收款人会被拒绝。目标基础账户必须在报价或执行前拥有 Stellar USDC trustline。 - 默认 Blockradar Stellar 钱包:在
recipientRouting中显式发送{ type: "none" }。
请求示例
所有示例在以下每个端点上使用相同的请求体结构:POST /v1/wallets/{walletId}/swaps/quotePOST /v1/wallets/{walletId}/swaps/executePOST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quotePOST /v1/wallets/{walletId}/addresses/{addressId}/swaps/execute
Non-Stellar destination — no routing field
Stellar G... without a routing ID
Stellar G... with a routing ID
Stellar M... recipient — no routing field
Default Blockradar Stellar wallet
从 Stellar 专用字段迁移
报价示例
报价响应
data.recipientRouting 也可能报告路由 ID 已嵌入规范化后的目标地址中:
data.recipientRouting 为可选字段,且仅由报价响应返回。请勿期望在执行响应中看到它。
理解报价字段
第 2 步:执行 Swap
用户确认报价后,执行 swap。请求参数
执行示例
执行响应
订单类型
根据您的使用场景选择合适的订单类型:Webhook 事件
通过 webhooks 监控 swap 完成情况:Webhook 负载
完整流程示例
以下是展示报价 → 确认 → 执行流程的完整实现:错误响应
余额不足
余额不足
无效的 Asset ID
无效的 Asset ID
Swap 路径不可用
Swap 路径不可用
金额过低
金额过低
Slippage 超限
Slippage 超限
最佳实践
用户体验
- 始终展示报价:在执行前展示金额、手续费和预计时间
- 处理 slippage:告知用户可能存在的价格波动
- 展示进度:使用 webhooks 向用户更新 swap 状态
安全性
- 校验金额:确保 swap 金额在可接受的范围内
- 使用 references:用唯一的 reference ID 追踪 swap
- 监控 webhooks:始终通过 webhooks 验证 swap 完成情况
性能
- 缓存 asset IDs:将 asset IDs 缓存在本地,避免重复查询
- 使用合适的订单类型:对时间敏感选用
FASTEST,对成本敏感选用CHEAPEST - 实现重试:使用指数退避处理临时性故障
API 参考
支持
Swap API 为同链 swap 与跨链 bridge 提供统一接口。在迁移到生产环境之前,请先在 testnets 上使用小额测试金额进行验证。

