兑换与跨链

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

前置条件

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

API密钥

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

已创建钱包

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

资产ID

从控制台的资产页面或通过获取资产API获取源资产和目标资产的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来获取目标链当前支持的资产列表及其assetId值。

查看集成获取完整的支持网络和稳定币列表。

主钱包 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钱包）

报价示例

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

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);

报价响应

{
  "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传递的自定义数据

执行示例

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

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);

执行响应

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

无效的资产ID

{
  "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为同链兑换和跨链桥接提供统一接口。在上线生产之前，请先在测试网使用小额测试金额进行测试。

Get Started

Wallets

Receive Payments

Send Payments

Convert & Manage

Compliance & Recovery

Integrations

前置条件

工作原理

兑换

跨链桥

支持的资产和链

主钱包 vs 子地址

主钱包

子地址

端点

步骤1：获取报价

请求参数

报价示例

报价响应

理解报价字段

步骤2：执行兑换

请求参数

执行示例

执行响应

订单类型

Webhook事件

Webhook负载

完整流程示例

错误响应

最佳实践

用户体验

安全性

性能

API参考

支持

​前置条件

​工作原理

兑换

跨链桥

​支持的资产和链

​主钱包 vs 子地址

主钱包

子地址

​端点

​步骤1：获取报价

​请求参数

​报价示例

​报价响应

​理解报价字段

​步骤2：执行兑换

​请求参数

​执行示例

​执行响应

​订单类型

​Webhook事件

​Webhook负载

​完整流程示例

​错误响应

​最佳实践

​用户体验

​安全性

​性能

​API参考

​支持

前置条件

工作原理

支持的资产和链

主钱包 vs 子地址

端点

步骤1：获取报价

请求参数

报价示例

报价响应

理解报价字段

步骤2：执行兑换

请求参数

执行示例

执行响应

订单类型

Webhook事件

Webhook负载

完整流程示例

错误响应

最佳实践

用户体验

安全性

性能

API参考

支持