提取稳定币 - Blockradar

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

前提条件

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

API 密钥

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

已创建钱包

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

资产 ID

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

充足余额

确保钱包中有足够的待提取资产余额，以及用于支付网络手续费的原生代币（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` 数组则为必填。Stellar 收款地址格式请参阅 Stellar 收款地址。
`amount`	string	是*	提款金额。必须大于 0。如果未提供 `assets` 数组则为必填。
`reference`	string	否	您内部用于跟踪此次提款的 ID。
`note`	string	否	简短消息或内部备注。链上不可见；在 Stellar 上例外，它会作为 memo 附加到交易中。
`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"
    }
  }'

const withdrawal = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/withdraw`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assetId: 'asset-uuid-here',
      address: '0xRecipientAddress...',
      amount: '100',
      reference: 'payout-12345',
      note: 'Monthly payout',
      metadata: {
        userId: 'user_abc123',
        payoutType: 'salary'
      }
    })
  }
).then(r => r.json());

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

单笔提款响应

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

Stellar 收款地址

在 Stellar 上，address 字段接受三种收款地址格式。相同的规则适用于单笔提款、批量提款、费用估算和仅签名模式，并且在 master wallet 和 child address 端点上均适用。

格式	收款方类型	支持的资产
`G...`	经典账户	所有资产（XLM 和代币）
`M...`	Muxed 账户	所有资产（XLM 和代币）
`C...`	Soroban 合约	仅限代币资产（例如 USDC、EURC）

Muxed 账户（`M...`）

Muxed 地址在经典 G... 账户之上嵌入了一个路由 ID。交易所和托管平台使用它来为正确的最终用户入账，而无需依赖 memo。发送到 muxed 地址的资金会结算到其底层的 G... 账户中。在 Stellar 上，note 字段会作为链上 memo 附加到交易中。对于 muxed 收款地址，不会附加任何 memo——路由 ID 已经嵌入在地址本身中。您的 note 仍会保存在 Blockradar 的交易记录中。

Soroban 合约（`C...`）

向合约地址进行的代币提款会作为该代币 Stellar Asset Contract 上的 transfer 调用执行，并通过 Soroban RPC 提交。在链上，其结果是一次合约调用而非经典的 payment 操作——如果收款方的工具只监控 payment 操作，请留意这一点。合约收款地址仅支持代币资产：

支持：代币提款（例如 USDC、EURC）、相应的网络费用估算以及仅签名模式。
不支持：原生 XLM 提款——将 XLM 发送到 C... 地址会返回 400 错误。法币提现、Swap和自动结算的目标地址也必须是经典 G... 或 muxed M... 地址。

向 G... 或 M... 收款地址进行代币提款时，目标账户必须已存在并持有该资产的信任线（trustline）（请参阅地址激活）。合约收款地址没有信任线要求，且合约转账不会附加 memo。

批量提款

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

何时使用批量提款

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

批量请求参数

对于批量提款，请使用 assets 数组而不是单独的参数：

参数	类型	是否必填	描述
`assets`	array	是	提款对象数组（每批最多 20 个）

assets 数组中的每一项：

字段	类型	是否必填	描述
`id`	string	是	要提取资产的 UUID
`address`	string	是	目标地址。Stellar 收款地址格式请参阅 Stellar 收款地址。
`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"
      }
    ]
  }'

const batchWithdrawal = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/withdraw`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      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'
        }
      ]
    })
  }
).then(r => r.json());

console.log('Batch withdrawal result:', batchWithdrawal.data);

批量提款响应

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

const fee = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/withdraw/network-fee`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assetId: 'asset-uuid-here',
      address: '0xRecipientAddress...',
      amount: '100'
    })
  }
).then(r => r.json());

console.log('Network fee:', fee.data.networkFee);
console.log('Fee in USD:', fee.data.networkFeeInUSD);

单笔费用响应

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

const batchFee = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/withdraw/network-fee`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assets: [
        {
          id: 'asset-uuid-1',
          address: '0xRecipient1...',
          amount: '100'
        },
        {
          id: 'asset-uuid-2',
          address: '0xRecipient2...',
          amount: '50'
        }
      ]
    })
  }
).then(r => r.json());

console.log('Total network fee:', batchFee.data.totalNetworkFee);
console.log('Total fee in USD:', batchFee.data.totalNetworkFeeInUSD);

批量费用响应

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

const signedTx = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/withdraw/sign`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assetId: 'asset-uuid-here',
      address: '0xRecipientAddress...',
      amount: '100'
    })
  }
).then(r => r.json());

console.log('Signed transaction:', signedTx.data.signedTransaction);

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

const childWithdrawal = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/withdraw`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assetId: 'asset-uuid-here',
      address: '0xRecipientAddress...',
      amount: '50',
      reference: 'user-withdrawal-123'
    })
  }
).then(r => r.json());

console.log('Child address withdrawal:', childWithdrawal.data);

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

Gas 不足

{
  "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	签名但不广播

支持

邮箱：[email protected]
文档：API 参考
Webhook 指南：Webhooks

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

​前提条件

​工作原理

单笔提款

批量提款

费用估算

仅签名模式

​Master Wallet vs Child Address

Master Wallet

Child Address

​端点

​单笔提款

​请求参数

​单笔提款示例

​单笔提款响应

​Stellar 收款地址

​Muxed 账户（M...）

​Soroban 合约（C...）

​批量提款

​何时使用批量提款

​批量请求参数

​批量提款示例

​批量提款响应

​处理部分失败

​批量提款规则

​估算网络费用

​单笔费用估算

​单笔费用响应

​批量费用估算

​批量费用响应

​费用响应字段

​仅签名模式

​Sign-Only 示例

​Sign-Only 响应

​Child Address 提款

​Webhook 事件

​Webhook 负载

​完整流程示例

​错误响应

​最佳实践

​安全

​费用管理

​错误处理

​性能

​API 参考

​Master Wallet 端点

​Child Address 端点

​支持

前提条件

工作原理

Master Wallet vs Child Address

端点

单笔提款

请求参数

单笔提款示例

单笔提款响应

Stellar 收款地址

Muxed 账户（`M...`）

Soroban 合约（`C...`）

批量提款

何时使用批量提款

批量请求参数

批量提款示例

批量提款响应

处理部分失败

批量提款规则

估算网络费用

单笔费用估算

单笔费用响应

批量费用估算

批量费用响应

费用响应字段

仅签名模式

Sign-Only 示例

Sign-Only 响应

Child Address 提款

Webhook 事件

Webhook 负载

完整流程示例

错误响应

最佳实践

安全

费用管理

错误处理

性能

API 参考

Master Wallet 端点

Child Address 端点

支持