跳转到主要内容

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.

简而言之
Blockradar Withdraw API 允许您将稳定币资产从钱包发送到外部区块链地址。它支持单笔提款、向多个收款人的批量提款,并在执行前提供费用估算。
Blockradar Withdraw 界面

前提条件

在使用 Withdraw API 之前,请确保您已具备:
1

API 密钥

Blockradar 控制台 获取您的 API 密钥。前往 Developers 生成密钥。
2

已创建钱包

通过 Create Wallet API 或控制台创建钱包。提款操作需要使用 walletId
3

资产 ID

在控制台的 Assets 中或通过 Get Assets API 获取要提取的代币的 assetId
4

充足余额

确保钱包中有足够的待提取资产余额,以及用于支付网络手续费的原生代币(ETH、BNB、MATIC 等)。

工作原理

Withdraw API 将稳定币资产从您的 Blockradar 钱包发送到任意外部区块链地址:

单笔提款

通过单次 API 调用将资产发送到一个收款地址。

批量提款

通过单次 API 调用将资产发送给多个收款人,减少开销并简化批量支付。

费用估算

在执行前计算网络手续费,以确保余额充足并向用户展示成本。

仅签名模式

签署交易但不广播,适用于离线签名或自定义提交等高级用例。

Master Wallet vs Child Address

Withdraw API 在两个层级可用:

Master Wallet

直接从主钱包提款。适合财务运营和集中式资金管理。

Child Address

从单个 child address 提款。适合用户专属操作和资金隔离管理。

端点

操作Master WalletChild Address
WithdrawPOST /v1/wallets/{walletId}/withdrawPOST /v1/wallets/{walletId}/addresses/{addressId}/withdraw
网络费用POST /v1/wallets/{walletId}/withdraw/network-feePOST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/network-fee
Sign-OnlyPOST /v1/wallets/{walletId}/withdraw/signPOST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/sign

单笔提款

将资产发送到单个收款地址。

请求参数

参数类型是否必填描述
assetIdstring是*要提取资产的 UUID。如果未提供 assets 数组则为必填。
addressstring是*目标地址。如果未提供 assets 数组则为必填。
amountstring是*提款金额。必须大于 0。如果未提供 assets 数组则为必填。
referencestring您内部用于跟踪此次提款的 ID。
notestring简短消息或内部备注。链上不可见。
metadataobject自定义键值对,用于补充交易细节。
标记为 * 的参数对于单笔提款是必填的,但如果您使用 assets 数组进行批量提款则不需要。

单笔提款示例

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "address": "0xRecipientAddress...",
    "amount": "100",
    "reference": "payout-12345",
    "note": "Monthly payout",
    "metadata": {
      "userId": "user_abc123",
      "payoutType": "salary"
    }
  }'

单笔提款响应

{
  "message": "Withdrawal initiated successfully",
  "statusCode": 200,
  "data": {
    "id": "tx-uuid-123",
    "hash": "0xabc123...",
    "status": "PENDING",
    "amount": "100",
    "recipientAddress": "0xRecipientAddress...",
    "reference": "payout-12345",
    "note": "Monthly payout",
    "metadata": {
      "userId": "user_abc123",
      "payoutType": "salary"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

批量提款

通过单次 API 调用向多个收款人发送资产。批量提款按顺序执行,每笔提款作为独立的区块链交易处理。

何时使用批量提款

  • 批量支付:一次性向多个员工、供应商或合作伙伴付款
  • 分发:将资产发送到多个地址
  • 多收款人转账:向不同地址发送不同金额
  • 提升运营效率:减少 API 调用并简化支付逻辑

批量请求参数

对于批量提款,请使用 assets 数组而不是单独的参数:
参数类型是否必填描述
assetsarray提款对象数组(每批最多 20 个)
assets 数组中的每一项:
字段类型是否必填描述
idstring要提取资产的 UUID
addressstring目标地址
amountstring提款金额。必须大于 0。
referencestring此次提款的可选参考备注
notestring简短消息或内部备注。链上不可见。
metadataobject自定义键值对,用于补充交易细节。

批量提款示例

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assets": [
      {
        "id": "asset-uuid-usdc",
        "address": "0xRecipient1...",
        "amount": "100",
        "reference": "payout-001",
        "note": "January salary"
      },
      {
        "id": "asset-uuid-usdc",
        "address": "0xRecipient2...",
        "amount": "150",
        "reference": "payout-002",
        "note": "January salary"
      },
      {
        "id": "asset-uuid-usdt",
        "address": "0xRecipient3...",
        "amount": "200",
        "reference": "payout-003",
        "note": "Vendor payment"
      }
    ]
  }'

批量提款响应

{
  "message": "Batch withdrawal initiated successfully",
  "statusCode": 200,
  "data": {
    "success": [
      {
        "index": 0,
        "id": "tx-uuid-1",
        "hash": "0xabc...",
        "status": "PENDING",
        "amount": "100",
        "recipientAddress": "0xRecipient1...",
        "reference": "payout-001"
      },
      {
        "index": 1,
        "id": "tx-uuid-2",
        "hash": "0xdef...",
        "status": "PENDING",
        "amount": "150",
        "recipientAddress": "0xRecipient2...",
        "reference": "payout-002"
      },
      {
        "index": 2,
        "id": "tx-uuid-3",
        "hash": "0xghi...",
        "status": "PENDING",
        "amount": "200",
        "recipientAddress": "0xRecipient3...",
        "reference": "payout-003"
      }
    ],
    "errors": []
  }
}

处理部分失败

批量提款支持部分成功。如果某些提款失败,其余的仍会执行:
const result = await batchWithdrawal.json();

// Process successful withdrawals
result.data.success.forEach(tx => {
  console.log(`✓ ${tx.reference}: ${tx.hash}`);
});

// Handle failed withdrawals
result.data.errors.forEach(error => {
  console.error(`✗ Index ${error.index}: ${error.error}`);
  // Retry logic or error reporting here
});

批量提款规则

规则
最大批次大小每次请求 20 笔提款
最小批次大小1 笔提款
执行顺序顺序执行
错误处理部分成功(失败不会中断后续提款)

估算网络费用

在执行提款前请始终估算费用,以确保有足够的原生代币余额,并向用户展示准确的成本。

单笔费用估算

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/network-fee \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "address": "0xRecipientAddress...",
    "amount": "100"
  }'

单笔费用响应

{
  "message": "Network fee fetched successfully",
  "statusCode": 200,
  "data": {
    "networkFee": "0.00001247904",
    "networkFeeInUSD": "0.01",
    "transactionFee": "0",
    "nativeBalance": "0.5",
    "nativeBalanceInUSD": "450.00",
    "estimatedArrivalTime": 30
  }
}

批量费用估算

一次性估算多笔提款的费用:
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/network-fee \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assets": [
      {
        "id": "asset-uuid-1",
        "address": "0xRecipient1...",
        "amount": "100"
      },
      {
        "id": "asset-uuid-2",
        "address": "0xRecipient2...",
        "amount": "50"
      }
    ]
  }'

批量费用响应

{
  "message": "Network fee fetched successfully",
  "statusCode": 200,
  "data": {
    "fees": [
      {
        "index": 0,
        "assetId": "asset-uuid-1",
        "address": "0xRecipient1...",
        "amount": "100",
        "networkFee": "0.00001247904",
        "transactionFee": "0",
        "estimatedArrivalTime": 30
      },
      {
        "index": 1,
        "assetId": "asset-uuid-2",
        "address": "0xRecipient2...",
        "amount": "50",
        "networkFee": "0.00000504",
        "transactionFee": "0",
        "estimatedArrivalTime": 30
      }
    ],
    "totalNetworkFee": "0.00001751904",
    "totalNetworkFeeInUSD": "0.02",
    "totalTransactionFee": "0",
    "nativeBalance": "0.073690520542044578",
    "nativeBalanceInUSD": "66.54",
    "estimatedArrivalTime": 60,
    "errors": []
  }
}

费用响应字段

字段描述
networkFee以原生代币单位计的 Gas 费(单笔提款)
networkFeeInUSD转换为 USD 的 Gas 费(单笔提款)
fees各项费用估算的数组(批量提款)
totalNetworkFee所有网络费用之和(批量提款)
totalNetworkFeeInUSD总网络费用(USD,批量提款)
transactionFee平台交易费(如适用)
nativeBalance当前原生代币余额
nativeBalanceInUSD原生代币余额(USD)
estimatedArrivalTime预计确认时间(秒)
errors任何失败估算的数组(批量提款)

仅签名模式

签署交易但不将其广播到区块链。适用于:
  • 离线签名:准备交易以便稍后提交
  • 多重签名工作流:在提交前收集签名
  • 交易检查:在广播前审查交易细节

Sign-Only 示例

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/sign \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "address": "0xRecipientAddress...",
    "amount": "100"
  }'

Sign-Only 响应

{
  "message": "Transaction signed successfully",
  "statusCode": 200,
  "data": {
    "id": "tx-uuid-123",
    "signedTransaction": "0xf86c...",
    "status": "SIGNED",
    "amount": "100",
    "recipientAddress": "0xRecipientAddress...",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Child Address 提款

从单个 child address 而非 master wallet 进行提款:
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/withdraw \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "address": "0xRecipientAddress...",
    "amount": "50",
    "reference": "user-withdrawal-123"
  }'
Child address 提款也支持使用 assets 数组进行批量操作,格式与 master wallet 批量提款相同。

Webhook 事件

通过 webhook 监控提款完成情况:
事件描述
withdraw.success提款已完成并在区块链上确认
withdraw.failed提款执行失败
withdraw.cancelled提款在完成前被取消

Webhook 负载

{
  "event": "withdraw.success",
  "data": {
    "id": "081d6315-159f-4c38-b02a-c4708836c5bd",
    "reference": "payout-12345",
    "senderAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
    "recipientAddress": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22",
    "amount": "100",
    "amountPaid": "100",
    "fee": null,
    "currency": "USD",
    "blockNumber": 6928833,
    "hash": "0x5fcb7dd11cbb5a6d64da08cf7e0d63c1a1e7b9d1b89e3e8d1c6a5f4b3a2c1d0e",
    "status": "SUCCESS",
    "type": "WITHDRAW",
    "note": "Monthly payout",
    "asset": {
      "id": "asset-uuid",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6
    },
    "wallet": {
      "id": "wallet-uuid",
      "name": "Main Treasury"
    },
    "blockchain": {
      "id": "blockchain-uuid",
      "name": "ethereum",
      "network": "mainnet"
    },
    "metadata": {
      "userId": "user_abc123",
      "payoutType": "salary"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:31:00Z"
  }
}

完整流程示例

以下是展示费用估算 → 用户确认 → 提款流程的完整实现:
async function processWithdrawal(walletId, assetId, recipientAddress, amount) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';

  // Step 1: Estimate network fee
  const feeResponse = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/network-fee`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        assetId,
        address: recipientAddress,
        amount
      })
    }
  ).then(r => r.json());

  // Step 2: Check if we have enough native balance for gas
  const fee = feeResponse.data;
  if (parseFloat(fee.nativeBalance) < parseFloat(fee.networkFee)) {
    throw new Error(`Insufficient gas: need ${fee.networkFee}, have ${fee.nativeBalance}`);
  }

  // Step 3: Display fee to user (in your UI)
  console.log(`Network fee: ${fee.networkFee} (≈$${fee.networkFeeInUSD})`);
  console.log(`Estimated time: ${fee.estimatedArrivalTime}s`);

  // Step 4: Execute withdrawal (after user confirmation)
  const withdrawal = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        assetId,
        address: recipientAddress,
        amount,
        reference: `withdraw-${Date.now()}`
      })
    }
  ).then(r => r.json());

  console.log('Withdrawal initiated:', withdrawal.data.id);
  console.log('Transaction hash:', withdrawal.data.hash);

  // Step 5: Listen for webhook to confirm completion
  return withdrawal.data;
}

// Usage
processWithdrawal(
  'wallet-uuid',
  'asset-uuid-usdc',
  '0xRecipientAddress...',
  '100'
);

错误响应

{
  "message": "Insufficient balance for withdrawal",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "100",
    "available": "50.25",
    "asset": "USDC"
  }
}
{
  "message": "Insufficient native token balance for gas",
  "statusCode": 400,
  "error": "INSUFFICIENT_GAS",
  "data": {
    "required": "0.005",
    "available": "0.001",
    "token": "ETH"
  }
}
{
  "message": "Invalid recipient address",
  "statusCode": 400,
  "error": "INVALID_ADDRESS",
  "data": {
    "address": "invalid_address_here"
  }
}
{
  "message": "Asset not found",
  "statusCode": 404,
  "error": "ASSET_NOT_FOUND",
  "data": {
    "assetId": "invalid-asset-uuid"
  }
}
{
  "message": "Amount must be greater than 0",
  "statusCode": 400,
  "error": "INVALID_AMOUNT",
  "data": {
    "amount": "0"
  }
}
{
  "message": "Batch size exceeds maximum limit",
  "statusCode": 400,
  "error": "BATCH_SIZE_EXCEEDED",
  "data": {
    "maximum": 20,
    "provided": 25
  }
}

最佳实践

安全

  • 验证地址:在发起提款前始终验证收款地址
  • 使用引用:使用唯一的 reference ID 跟踪提款,便于对账
  • 实现 webhook:监听 withdraw.successwithdraw.failed 事件以确认状态
  • 检查 AML:Blockradar 会自动筛查地址—请审查任何被标记的交易

费用管理

  • 执行前估算:在提款前始终调用 network-fee 端点
  • 监控原生余额:确保有足够的 ETH/BNB/MATIC 用于支付 Gas 费
  • 使用批量提升效率:将多笔提款分组以减少 API 调用和运营开销

错误处理

  • 处理部分失败:在批量提款中,同时检查 successerrors 数组
  • 实现重试:对临时故障使用指数退避
  • 记录所有交易:存储交易 ID 和哈希以便调试和对账

性能

  • 使用合适的批次大小:较大的批次可减少 API 调用,但会增加单次请求时间
  • 缓存资产 ID:在本地存储资产 ID 以避免重复查询
  • 实施限流:遵守 API 速率限制以避免被节流

API 参考

Master Wallet 端点

Endpoint描述
Withdraw执行单笔或批量提款
Network Fee估算提款费用
Sign-Only签名但不广播

Child Address 端点

Endpoint描述
Withdraw执行单笔或批量提款
Network Fee估算提款费用
Sign-Only签名但不广播

支持

Withdraw API 提供了向外部地址发送稳定币资产的灵活接口。先从单笔提款和费用估算入手,随着需求增长再引入批量操作以处理批量支付。