> ## Documentation Index > Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt > Use this file to discover all available pages before exploring further. # 兑换与跨链 > 使用统一API跨链交换资产 兑换与跨链 简而言之
Blockradar的兑换API让您可以在同一链上交换资产（兑换）或在不同链之间移动资产（跨链桥）——使用单一统一的端点。 ## 前置条件 在使用兑换API之前，请确保您已具备： 从[Blockradar控制台](https://dashboard.blockradar.co)获取您的API密钥。导航至**设置 → API密钥**生成一个。 通过[创建钱包API](/zh/api-reference/wallets/create-wallet)或控制台创建钱包。您需要`walletId`来执行兑换操作。 从控制台的**资产**页面或通过[获取资产API](/zh/api-reference/miscellaneous/get-assets)获取源资产和目标资产的`assetId`。 确保您的钱包有足够的源资产余额来覆盖兑换金额和网络费用。 ## 工作原理 Blockradar根据您选择的资产自动判断您的交易是**兑换**还是**跨链桥**： 在**同一区块链**上交换不同资产。 *示例：Base上的USDC → USDT* 在**不同区块链**之间移动资产。 *示例：BSC上的USDC → Optimism上的USDC* 您无需指定是兑换还是跨链桥——API会根据您提供的`fromAssetId`和`toAssetId`自动处理。 ## 支持的资产和链 兑换API支持Blockradar支持链上的主要稳定币： | 稳定币 | 描述 | | ---- | --------------------- | | USDT | Tether USD | | USDC | USD Coin | | DAI | Dai Stablecoin | | BUSD | Binance USD | | cNGN | Naira Stablecoin | | EURC | Euro Coin | | IDRX | Indonesian Stablecoin | | JPYC | 日元稳定币 | 资产可用性因链而异。请始终使用[获取资产API](/zh/api-reference/miscellaneous/get-assets)来获取目标链当前支持的资产列表及其`assetId`值。 查看[集成](/zh/essentials/integrations)获取完整的支持网络和稳定币列表。 ## 主钱包 vs 子地址 兑换API在两个层面可用： 直接从主钱包执行兑换。适用于资金库操作。 从单个子地址执行兑换。适用于用户特定操作。 ### 端点 | 操作 | 主钱包 | 子地址 | | ---- | ------------------------------------------- | ----------------------------------------------------------------- | | 获取报价 | `POST /v1/wallets/{walletId}/swaps/quote` | `POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote` | | 执行 | `POST /v1/wallets/{walletId}/swaps/execute` | `POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/execute` | ## 步骤1：获取报价 在执行兑换之前始终获取报价，以向用户展示预期结果。 ### 请求参数 | 参数 | 类型 | 必填 | 描述 | | ------------------ | ------ | -- | ----------------------------------------------------- | | `fromAssetId` | string | 是 | 源资产ID | | `toAssetId` | string | 是 | 目标资产ID | | `amount` | string | 是 | 兑换金额 | | `order` | string | 否 | 报价偏好：`FASTEST`、`CHEAPEST`、`RECOMMENDED`、`NO_SLIPPAGE` | | `recipientAddress` | string | 否 | 外部钱包地址（用于发送到非Blockradar钱包） | ### 报价示例 ```bash Curl theme={null} curl --request POST \ --url https://api.blockradar.co/v1/wallets/{walletId}/swaps/quote \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "fromAssetId": "asset_usdc_base_mainnet", "toAssetId": "asset_usdt_bsc_mainnet", "amount": "100", "order": "RECOMMENDED" }' ``` ```javascript JavaScript theme={null} const quote = await fetch( `https://api.blockradar.co/v1/wallets/${walletId}/swaps/quote`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey }, body: JSON.stringify({ fromAssetId: 'asset_usdc_base_mainnet', toAssetId: 'asset_usdt_bsc_mainnet', amount: '100', order: 'RECOMMENDED' }) } ).then(r => r.json()); console.log('报价:', quote.data); ``` ### 报价响应 ```json theme={null} { "message": "兑换报价获取成功", "statusCode": 200, "data": { "amount": "99.45", "minAmount": "98.95", "rate": "0.9945", "impact": "0.12", "slippage": "0.5", "networkFee": "0.002", "networkFeeInUSD": "0.15", "estimatedArrivalTime": 180 } } ``` ### 理解报价字段 | 字段 | 描述 | | ---------------------- | -------------- | | `amount` | 兑换后您将收到的预估金额 | | `minAmount` | 最低保证金额（考虑滑点） | | `rate` | 有效汇率（目标金额/源金额） | | `impact` | 价格影响百分比 | | `slippage` | 允许的最大价格波动百分比 | | `networkFee` | 原生货币单位的Gas费用 | | `networkFeeInUSD` | 转换为USD的Gas费用 | | `estimatedArrivalTime` | 预计完成时间（秒） | 在用户确认兑换之前，至少显示：**将收到的金额**、**预计到账时间**和**费用**。 ## 步骤2：执行兑换 用户确认报价后，执行兑换。 ### 请求参数 | 参数 | 类型 | 必填 | 描述 | | ------------------ | ------ | -- | ----------------------------------------------------- | | `fromAssetId` | string | 是 | 源资产ID | | `toAssetId` | string | 是 | 目标资产ID | | `amount` | string | 是 | 兑换金额 | | `order` | string | 否 | 报价偏好：`FASTEST`、`CHEAPEST`、`RECOMMENDED`、`NO_SLIPPAGE` | | `recipientAddress` | string | 否 | 外部钱包地址（用于发送到非Blockradar钱包） | | `reference` | string | 否 | 您的内部追踪ID | | `metadata` | object | 否 | 通过webhook传递的自定义数据 | ### 执行示例 ```bash Curl theme={null} curl --request POST \ --url https://api.blockradar.co/v1/wallets/{walletId}/swaps/execute \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "fromAssetId": "asset_usdc_base_mainnet", "toAssetId": "asset_usdt_bsc_mainnet", "amount": "100", "order": "RECOMMENDED", "reference": "swap-order-12345", "metadata": { "userId": "user_abc123", "orderId": "order_xyz789" } }' ``` ```javascript JavaScript theme={null} const swap = await fetch( `https://api.blockradar.co/v1/wallets/${walletId}/swaps/execute`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey }, body: JSON.stringify({ fromAssetId: 'asset_usdc_base_mainnet', toAssetId: 'asset_usdt_bsc_mainnet', amount: '100', order: 'RECOMMENDED', reference: 'swap-order-12345', metadata: { userId: 'user_abc123', orderId: 'order_xyz789' } }) } ).then(r => r.json()); console.log('兑换已启动:', swap.data); ``` ### 执行响应 ```json theme={null} { "message": "兑换交易创建成功", "statusCode": 200, "data": { "id": "swap-uuid-123", "type": "SWAP", "status": "PENDING", "fromAsset": { "symbol": "USDC", "amount": "100", "blockchain": "base" }, "toAsset": { "symbol": "USDT", "amount": "99.45", "blockchain": "bsc" }, "reference": "swap-order-12345", "metadata": { "userId": "user_abc123", "orderId": "order_xyz789" }, "createdAt": "2024-01-15T10:30:00Z" } } ``` 兑换操作是异步的。初始响应显示`PENDING`状态。请监听`swap.success`或`swap.failed` webhook以确认完成。 ## 订单类型 根据您的用例选择正确的订单类型： | 订单类型 | 描述 | 适用场景 | | ------------- | -------- | ------- | | `FASTEST` | 速度优先于成本 | 时间敏感的交易 | | `CHEAPEST` | 最小化费用 | 成本敏感的操作 | | `RECOMMENDED` | 平衡方案（默认） | 大多数用例 | | `NO_SLIPPAGE` | 精确金额或失败 | 精确金额要求 | ## Webhook事件 通过webhook监控兑换完成情况： | 事件 | 描述 | | -------------- | ------ | | `swap.success` | 兑换成功完成 | | `swap.failed` | 兑换失败 | ### Webhook负载 ```json theme={null} { "event": "swap.success", "data": { "id": "swap-uuid-123", "type": "SWAP", "status": "SUCCESS", "fromAsset": { "symbol": "USDC", "amount": "100", "blockchain": "base", "hash": "0xabc..." }, "toAsset": { "symbol": "USDT", "amount": "99.45", "blockchain": "bsc", "hash": "0xdef..." }, "reference": "swap-order-12345", "metadata": { "userId": "user_abc123", "orderId": "order_xyz789" }, "completedAt": "2024-01-15T10:33:00Z" } } ``` ## 完整流程示例 这是一个展示报价 → 确认 → 执行流程的完整实现： ```javascript theme={null} async function executeSwap(walletId, fromAssetId, toAssetId, amount) { const apiKey = process.env.BLOCKRADAR_API_KEY; const baseUrl = 'https://api.blockradar.co/v1'; // 步骤1：获取报价 const quote = await fetch( `${baseUrl}/wallets/${walletId}/swaps/quote`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey }, body: JSON.stringify({ fromAssetId, toAssetId, amount, order: 'RECOMMENDED' }) } ).then(r => r.json()); // 步骤2：向用户显示报价 console.log(`您将收到: ${quote.data.amount}`); console.log(`最低金额: ${quote.data.minAmount}`); console.log(`网络费用: $${quote.data.networkFeeInUSD}`); console.log(`预计时间: ${quote.data.estimatedArrivalTime}秒`); // 步骤3：执行兑换（用户确认后） const swap = await fetch( `${baseUrl}/wallets/${walletId}/swaps/execute`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey }, body: JSON.stringify({ fromAssetId, toAssetId, amount, order: 'RECOMMENDED', reference: `swap-${Date.now()}` }) } ).then(r => r.json()); console.log('兑换已启动:', swap.data.id); console.log('状态:', swap.data.status); // 步骤4：监听webhook确认完成 return swap.data; } // 使用示例 executeSwap( 'wallet-uuid', 'asset_usdc_base_mainnet', 'asset_usdt_bsc_mainnet', '100' ); ``` ## 错误响应 ```json theme={null} { "message": "兑换余额不足", "statusCode": 400, "error": "INSUFFICIENT_BALANCE", "data": { "required": "100", "available": "50.25", "asset": "USDC" } } ``` ```json theme={null} { "message": "资产未找到", "statusCode": 404, "error": "ASSET_NOT_FOUND", "data": { "assetId": "invalid_asset_id" } } ``` ```json theme={null} { "message": "此交易对没有可用的兑换路由", "statusCode": 400, "error": "NO_ROUTE_AVAILABLE", "data": { "fromAsset": "USDC", "toAsset": "CUSTOM_TOKEN" } } ``` ```json theme={null} { "message": "金额低于最小兑换阈值", "statusCode": 400, "error": "AMOUNT_TOO_LOW", "data": { "minimum": "10", "provided": "1" } } ``` ```json theme={null} { "message": "价格变动超出滑点容忍范围", "statusCode": 400, "error": "SLIPPAGE_EXCEEDED", "data": { "expectedAmount": "99.45", "actualAmount": "97.00", "slippageTolerance": "0.5%" } } ``` ## 最佳实践 ### 用户体验 * **始终显示报价**：在执行前显示金额、费用和预计时间 * **处理滑点**：告知用户可能的价格变动 * **显示进度**：使用webhook更新用户兑换状态 ### 安全性 * **验证金额**：确保兑换金额在可接受范围内 * **使用引用**：用唯一的引用ID追踪兑换 * **监控webhook**：始终通过webhook验证兑换完成 ### 性能 * **缓存资产ID**：在本地存储资产ID以避免重复查询 * **使用适当的订单类型**：时间敏感选择`FASTEST`，成本敏感选择`CHEAPEST` * **实现重试**：对暂时性失败使用指数退避处理 ## API参考 | 端点 | 描述 | | --------------------------------------------------------- | ---------- | | [主钱包获取报价](/zh/api-reference/swap/master-wallet-get-quote) | 从主钱包获取兑换报价 | | [主钱包执行](/zh/api-reference/swap/master-wallet-execute) | 从主钱包执行兑换 | | [子地址获取报价](/zh/api-reference/swap/child-address-get-quote) | 从子地址获取兑换报价 | | [子地址执行](/zh/api-reference/swap/child-address-execute) | 从子地址执行兑换 | ## 支持 * **电子邮件**：[support@blockradar.co](mailto:support@blockradar.co) * **文档**：[API参考](/zh/api-reference/swap/master-wallet-get-quote) * **博客**：[如何使用Blockradar兑换或跨链资产](https://www.blockradar.co/blog/how-to-swap-or-bridge-assets-with-blockradar-a-follow-along-guide) 兑换API为同链兑换和跨链桥接提供统一接口。在上线生产之前，请先在测试网使用小额测试金额进行测试。