跳转到主要内容
兑换与跨链
简而言之
Blockradar的兑换API让您可以在同一链上交换资产（兑换）或在不同链之间移动资产（跨链桥）——使用单一统一的端点。

​
前置条件

在使用兑换API之前，请确保您已具备：
1

API密钥

从Blockradar控制台获取您的API密钥。导航至设置 → API密钥生成一个。
2

已创建钱包

通过创建钱包API或控制台创建钱包。您需要walletId来执行兑换操作。
3

资产ID

从控制台的资产页面或通过获取资产API获取源资产和目标资产的assetId。
4

充足余额

确保您的钱包有足够的源资产余额来覆盖兑换金额和网络费用。

​
工作原理

Blockradar根据您选择的资产自动判断您的交易是兑换还是跨链桥：

兑换

在同一区块链上交换不同资产。示例：Base上的USDC → USDT

跨链桥

在不同区块链之间移动资产。示例：BSC上的USDC → Optimism上的USDC
您无需指定是兑换还是跨链桥——API会根据您提供的fromAssetId和toAssetId自动处理。

​
支持的资产和链

兑换API支持Blockradar支持链上的主要稳定币：
稳定币描述
USDTTether USD
USDCUSD Coin
DAIDai Stablecoin
BUSDBinance USD
cNGNNaira Stablecoin
EURCEuro Coin
IDRXIndonesian Stablecoin
资产可用性因链而异。请始终使用获取资产API来获取目标链当前支持的资产列表及其assetId值。
查看集成获取完整的支持网络和稳定币列表。

​
主钱包 vs 子地址

兑换API在两个层面可用：

主钱包

直接从主钱包执行兑换。适用于资金库操作。

子地址

从单个子地址执行兑换。适用于用户特定操作。

​
端点

操作主钱包子地址
获取报价POST /v1/wallets/{walletId}/swaps/quotePOST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote
执行POST /v1/wallets/{walletId}/swaps/executePOST /v1/wallets/{walletId}/addresses/{addressId}/swaps/execute

​
步骤1：获取报价

在执行兑换之前始终获取报价，以向用户展示预期结果。

​
请求参数

参数类型必填描述
fromAssetIdstring是源资产ID
toAssetIdstring是目标资产ID
amountstring是兑换金额
orderstring否报价偏好：FASTEST、CHEAPEST、RECOMMENDED、NO_SLIPPAGE
recipientAddressstring否外部钱包地址（用于发送到非Blockradar钱包）

​
报价示例

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/swaps/quote \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "fromAssetId": "asset_usdc_base_mainnet",
    "toAssetId": "asset_usdt_bsc_mainnet",
    "amount": "100",
    "order": "RECOMMENDED"
  }'

​
报价响应

{
  "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：执行兑换

用户确认报价后，执行兑换。

​
请求参数

参数类型必填描述
fromAssetIdstring是源资产ID
toAssetIdstring是目标资产ID
amountstring是兑换金额
orderstring否报价偏好：FASTEST、CHEAPEST、RECOMMENDED、NO_SLIPPAGE
recipientAddressstring否外部钱包地址（用于发送到非Blockradar钱包）
referencestring否您的内部追踪ID
metadataobject否通过webhook传递的自定义数据

​
执行示例

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/swaps/execute \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <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"
    }
  }'

​
执行响应

{
  "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负载

{
  "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"
  }
}

​
完整流程示例

这是一个展示报价 → 确认 → 执行流程的完整实现： 
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'
);

​
错误响应

{
  "message": "兑换余额不足",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "100",
    "available": "50.25",
    "asset": "USDC"
  }
}

{
  "message": "资产未找到",
  "statusCode": 404,
  "error": "ASSET_NOT_FOUND",
  "data": {
    "assetId": "invalid_asset_id"
  }
}

{
  "message": "此交易对没有可用的兑换路由",
  "statusCode": 400,
  "error": "NO_ROUTE_AVAILABLE",
  "data": {
    "fromAsset": "USDC",
    "toAsset": "CUSTOM_TOKEN"
  }
}

{
  "message": "金额低于最小兑换阈值",
  "statusCode": 400,
  "error": "AMOUNT_TOO_LOW",
  "data": {
    "minimum": "10",
    "provided": "1"
  }
}

{
  "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参考

端点描述
主钱包获取报价从主钱包获取兑换报价
主钱包执行从主钱包执行兑换
子地址获取报价从子地址获取兑换报价
子地址执行从子地址执行兑换

​
支持

兑换API为同链兑换和跨链桥接提供统一接口。在上线生产之前，请先在测试网使用小额测试金额进行测试。