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 允许您将稳定币资产从钱包发送到外部区块链地址。它支持单笔提款、向多个收款人的批量提款,并在执行前提供费用估算。
前提条件
在使用 Withdraw API 之前,请确保您已具备:
充足余额
确保钱包中有足够的待提取资产余额,以及用于支付网络手续费的原生代币(ETH、BNB、MATIC 等)。
工作原理
Withdraw API 将稳定币资产从您的 Blockradar 钱包发送到任意外部区块链地址:
单笔提款
通过单次 API 调用将资产发送到一个收款地址。
批量提款
通过单次 API 调用将资产发送给多个收款人,减少开销并简化批量支付。
费用估算
在执行前计算网络手续费,以确保余额充足并向用户展示成本。
仅签名模式
签署交易但不广播,适用于离线签名或自定义提交等高级用例。
Master Wallet vs Child Address
Withdraw API 在两个层级可用:
Master Wallet
直接从主钱包提款。适合财务运营和集中式资金管理。
Child Address
从单个 child address 提款。适合用户专属操作和资金隔离管理。
| 操作 | Master Wallet | Child Address |
|---|
| Withdraw | POST /v1/wallets/{walletId}/withdraw | POST /v1/wallets/{walletId}/addresses/{addressId}/withdraw |
| 网络费用 | POST /v1/wallets/{walletId}/withdraw/network-fee | POST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/network-fee |
| Sign-Only | POST /v1/wallets/{walletId}/withdraw/sign | POST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/sign |
单笔提款
将资产发送到单个收款地址。
请求参数
| 参数 | 类型 | 是否必填 | 描述 |
|---|
assetId | string | 是* | 要提取资产的 UUID。如果未提供 assets 数组则为必填。 |
address | string | 是* | 目标地址。如果未提供 assets 数组则为必填。 |
amount | string | 是* | 提款金额。必须大于 0。如果未提供 assets 数组则为必填。 |
reference | string | 否 | 您内部用于跟踪此次提款的 ID。 |
note | string | 否 | 简短消息或内部备注。链上不可见。 |
metadata | object | 否 | 自定义键值对,用于补充交易细节。 |
标记为 * 的参数对于单笔提款是必填的,但如果您使用 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 数组而不是单独的参数:
| 参数 | 类型 | 是否必填 | 描述 |
|---|
assets | array | 是 | 提款对象数组(每批最多 20 个) |
assets 数组中的每一项:
| 字段 | 类型 | 是否必填 | 描述 |
|---|
id | string | 是 | 要提取资产的 UUID |
address | string | 是 | 目标地址 |
amount | string | 是 | 提款金额。必须大于 0。 |
reference | string | 否 | 此次提款的可选参考备注 |
note | string | 否 | 简短消息或内部备注。链上不可见。 |
metadata | object | 否 | 自定义键值对,用于补充交易细节。 |
批量提款示例
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.success 和 withdraw.failed 事件以确认状态
- 检查 AML:Blockradar 会自动筛查地址—请审查任何被标记的交易
费用管理
- 执行前估算:在提款前始终调用 network-fee 端点
- 监控原生余额:确保有足够的 ETH/BNB/MATIC 用于支付 Gas 费
- 使用批量提升效率:将多笔提款分组以减少 API 调用和运营开销
错误处理
- 处理部分失败:在批量提款中,同时检查
success 和 errors 数组
- 实现重试:对临时故障使用指数退避
- 记录所有交易:存储交易 ID 和哈希以便调试和对账
- 使用合适的批次大小:较大的批次可减少 API 调用,但会增加单次请求时间
- 缓存资产 ID:在本地存储资产 ID 以避免重复查询
- 实施限流:遵守 API 速率限制以避免被节流
API 参考
Master Wallet 端点
| Endpoint | 描述 |
|---|
| Withdraw | 执行单笔或批量提款 |
| Network Fee | 估算提款费用 |
| Sign-Only | 签名但不广播 |
Child Address 端点
| Endpoint | 描述 |
|---|
| Withdraw | 执行单笔或批量提款 |
| Network Fee | 估算提款费用 |
| Sign-Only | 签名但不广播 |
Withdraw API 提供了向外部地址发送稳定币资产的灵活接口。先从单笔提款和费用估算入手,随着需求增长再引入批量操作以处理批量支付。