跳转到主要内容

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.

Swap 与 Bridge
简而言之
Blockradar 的 Swap API 让您可以通过单一的统一 endpoint 在同一条链上交换资产（swap），或在不同链之间转移资产（bridge）。

​
前提条件

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

API 密钥

从 Blockradar Dashboard 获取您的 API 密钥。前往 Developers 进行生成。
2

已创建钱包

通过 Create Wallet API 或 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 还是 bridge——API 会根据您提供的 fromAssetId 和 toAssetId 自动处理。

​
支持的资产与链

Swap API 在 Blockradar 支持的链上支持主要稳定币：
Stablecoin描述
USDTTether USD
USDCUSD Coin
DAIDai Stablecoin
BUSDBinance USD
cNGN奈拉稳定币
EURCEuro Coin
IDRX印尼盾稳定币
JPYC日元稳定币
资产可用性因链而异。请始终使用 Get Assets API 获取目标链上当前支持的资产列表及其 assetId 值。
请参阅集成了解支持的网络与稳定币完整列表。

​
Master Wallet 与 Child Address

Swap API 在两个层级上提供：

Master Wallet

直接从您的 master wallet 执行 swap。适合资金管理操作。

Child Address

从单个 child address 执行 swap。非常适合面向特定用户的操作。

​
Endpoints

操作Master WalletChild Address
获取报价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 步：获取报价

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

​
请求参数

参数类型是否必填描述
fromAssetIdstring是用于交换的源 asset ID
toAssetIdstring是用于交换的目标 asset 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": "Swap quote fetched successfully",
  "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
  }
}

​
理解报价字段

字段描述
amountswap 完成后您预计将收到的金额
minAmount最低保证金额（已计入 slippage）
rate实际兑换汇率 (toAmount / fromAmount)
impact价格影响百分比
slippage允许的最大价格波动百分比
networkFee以原生代币单位计的 gas 费
networkFeeInUSD折算为 USD 的 gas 费
estimatedArrivalTime预计完成时间（秒）
在用户确认 swap 之前，至少应展示：预计收到的金额、预计到账时间和手续费。

​
第 2 步：执行 Swap

用户确认报价后，执行 swap。

​
请求参数

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

​
执行示例

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": "Swap transaction created successfully",
  "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"
  }
}
Swap 操作是异步的。初始响应显示 PENDING 状态。请监听 swap.success 或 swap.failed webhook 以确认完成。

​
订单类型

根据您的使用场景选择合适的订单类型：
订单类型描述适用场景
FASTEST优先速度而非成本时间敏感的交易
CHEAPEST最小化手续费成本敏感的操作
RECOMMENDED平衡方案（默认）大多数使用场景
NO_SLIPPAGE精确金额或失败对金额精度有要求的场景

​
Webhook 事件

通过 webhooks 监控 swap 完成情况：
事件描述
swap.successswap 成功完成
swap.failedswap 失败

​
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';

  // Step 1: Get quote
  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());

  // Step 2: Display quote to user
  console.log(`You will receive: ${quote.data.amount}`);
  console.log(`Minimum amount: ${quote.data.minAmount}`);
  console.log(`Network fee: $${quote.data.networkFeeInUSD}`);
  console.log(`Estimated time: ${quote.data.estimatedArrivalTime}s`);

  // Step 3: Execute swap (after user confirmation)
  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 initiated:', swap.data.id);
  console.log('Status:', swap.data.status);

  // Step 4: Listen for webhook to confirm completion
  return swap.data;
}

// Usage
executeSwap(
  'wallet-uuid',
  'asset_usdc_base_mainnet',
  'asset_usdt_bsc_mainnet',
  '100'
);

​
错误响应

{
  "message": "Insufficient balance for swap",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "100",
    "available": "50.25",
    "asset": "USDC"
  }
}

{
  "message": "Asset not found",
  "statusCode": 404,
  "error": "ASSET_NOT_FOUND",
  "data": {
    "assetId": "invalid_asset_id"
  }
}

{
  "message": "No swap route available for this pair",
  "statusCode": 400,
  "error": "NO_ROUTE_AVAILABLE",
  "data": {
    "fromAsset": "USDC",
    "toAsset": "CUSTOM_TOKEN"
  }
}

{
  "message": "Amount below minimum swap threshold",
  "statusCode": 400,
  "error": "AMOUNT_TOO_LOW",
  "data": {
    "minimum": "10",
    "provided": "1"
  }
}

{
  "message": "Price moved beyond slippage tolerance",
  "statusCode": 400,
  "error": "SLIPPAGE_EXCEEDED",
  "data": {
    "expectedAmount": "99.45",
    "actualAmount": "97.00",
    "slippageTolerance": "0.5%"
  }
}

​
最佳实践

​
用户体验

  • 始终展示报价：在执行前展示金额、手续费和预计时间
  • 处理 slippage：告知用户可能存在的价格波动
  • 展示进度：使用 webhooks 向用户更新 swap 状态

​
安全性

  • 校验金额：确保 swap 金额在可接受的范围内
  • 使用 references：用唯一的 reference ID 追踪 swap
  • 监控 webhooks：始终通过 webhooks 验证 swap 完成情况

​
性能

  • 缓存 asset IDs：将 asset IDs 缓存在本地，避免重复查询
  • 使用合适的订单类型：对时间敏感选用 FASTEST，对成本敏感选用 CHEAPEST
  • 实现重试：使用指数退避处理临时性故障

​
API 参考

Endpoint描述
Master Wallet Get Quote从 master wallet 获取 swap 报价
Master Wallet Execute从 master wallet 执行 swap
Child Address Get Quote从 child address 获取 swap 报价
Child Address Execute从 child address 执行 swap

​
支持

Swap API 为同链 swap 与跨链 bridge 提供统一接口。在迁移到生产环境之前，请先在 testnets 上使用小额测试金额进行验证。