存入稳定币 - Blockradar

简而言之
Blockradar 允许您为每位客户生成专属的区块链地址来接收稳定币存款。存款会被自动检测、触发 Webhook 通知，并可以归集到您的主钱包 — 让您完全掌控资金在平台中的流转方式。

前提条件

API 密钥

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

主钱包

通过控制台或 API 创建钱包。所有存款操作都需要 walletId。

启用资产

在钱包上启用您希望接收的稳定币。钱包只会检测您明确添加的资产的存款 — 参见资产管理。

Webhook URL

在控制台的 Developers → Webhooks 中配置 Webhook 端点以实时接收存款通知。

工作原理

Blockradar 的存款流程基于一个简单的理念：每位客户都有自己的地址，每笔存款都会被自动跟踪。

生成地址

为每位客户或支付会话创建唯一的区块链地址。该地址的存款会自动归属到对应客户。

检测存款

Blockradar 监控所有生成的地址，一旦存款到达即触发 Webhook。无需轮询。

自动归集

存款会自动归集到您的主钱包，保持客户地址清爽，资金集中管理。

查询余额

在钱包或地址级别查询余额，支持单一资产或所有资产，并包含 USD 折算。

精细化控制设计

大多数区块链基础设施将钱包视为扁平、统一的容器。Blockradar 则不同。钱包层级的每一层（主钱包、子地址和单个资产）都可独立配置，让金融科技公司可以根据产品需求精确定制存款体验。这意味着您可以：

每个钱包启用不同的稳定币 — 一个钱包启用 USDC，另一个启用 USDT，或者在同一钱包上同时启用两者。由您决定每个钱包监控什么。
按地址配置归集行为 — 默认将存款自动归集到主钱包，但可为特定地址禁用，让资金保留在原地。
为每个地址附加元数据 — 用您自己的用户 ID、会话令牌或内部引用标记地址，使存款直接映射到您的系统。
按需激活或停用地址 — 无需删除即可暂停地址，之后可随时重新激活。

这种精细化能力对于构建多币种钱包、市场托管或按用户分离的存款流程等产品尤为重要 — 在刚性的钱包模型中这些场景需要变通方案，而 Blockradar 原生支持。

第 1 步：在钱包上启用资产

接收存款之前，钱包需要知道要监控哪些稳定币。使用 Get Assets 端点获取可用资产，然后添加您需要的资产。

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/assets \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "global-asset-id-for-usdc"
  }'

const asset = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/assets`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assetId: 'global-asset-id-for-usdc'
    })
  }
).then(r => r.json());

console.log('Asset enabled:', asset.data.asset.symbol);

添加后，Blockradar 会立即开始监控您的钱包及其所有地址的该代币存款。

使用 Get Wallet Assets 获取钱包专属的资产 ID。这些 ID 用于余额查询和其他 API 调用 — 与全局资产 ID 不同。

第 2 步：为客户生成地址

为每位客户或每次存款会话创建一个专属地址。该地址的每笔存款都会自动归属到客户。

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Customer 12345",
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    }
  }'

const address = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      name: 'Customer 12345',
      metadata: {
        userId: 'user_12345',
        plan: 'premium'
      }
    })
  }
).then(r => r.json());

console.log('Deposit address:', address.data.address);

响应

{
  "statusCode": 201,
  "message": "Address generated successfully",
  "data": {
    "id": "address-uuid",
    "address": "0xe1037B45b48390285e5067424053fa35c478296b",
    "name": "Customer 12345",
    "type": "INTERNAL",
    "isActive": true,
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "configurations": {
      "autoSweep": true,
      "gaslessWithdraw": false
    },
    "blockchain": {
      "name": "base",
      "symbol": "ETH",
      "network": "mainnet"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

地址参数

参数	类型	必填	说明
`name`	string	否	地址的可读标签
`metadata`	object	否	映射到您内部系统的自定义键值对
`disableAutoSweep`	boolean	否	设为 `true` 将存款保留在地址中，不归集到主钱包
`enableGaslessWithdraw`	boolean	否	在此地址启用免 Gas 提现

将生成的 address 分享给客户。客户发送稳定币后，Blockradar 会检测到存款并触发 Webhook。

第 3 步：监听存款

配置您的 Webhook 端点以实时接收存款通知。

Webhook 事件

事件	说明
`deposit.success`	客户地址上的存款已在链上确认
`deposit.swept.success`	存款已自动归集到主钱包

Webhook Payload

{
  "event": "deposit.success",
  "data": {
    "id": "tx-uuid",
    "hash": "0xabc123...",
    "type": "DEPOSIT",
    "status": "SUCCESS",
    "amount": "100",
    "senderAddress": "0xCustomerExternalWallet...",
    "recipientAddress": "0xe1037B45b48390285e5067424053fa35c478296b",
    "asset": {
      "id": "asset-uuid",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6
    },
    "wallet": {
      "id": "wallet-uuid",
      "name": "Deposits Wallet"
    },
    "blockchain": {
      "name": "base",
      "network": "mainnet"
    },
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

您在生成地址时附加的 metadata 会随该地址的每个 Webhook 一并返回，让您无需额外查询即可将存款映射回用户。

查询余额

可以在层级的任何级别查询余额 — 主钱包或单个地址，单一资产或所有资产。

单一资产余额（钱包）

curl --request GET \
  --url 'https://api.blockradar.co/v1/wallets/{walletId}/balance?assetId={assetId}' \
  --header 'x-api-key: <api-key>'

const balance = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/balance?assetId=${assetId}`,
  { headers: { 'x-api-key': apiKey } }
).then(r => r.json());

console.log(`Balance: ${balance.data.balance} (≈$${balance.data.convertedBalance})`);

所有资产余额（地址）

curl --request GET \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/balances \
  --header 'x-api-key: <api-key>'

const balances = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/balances`,
  { headers: { 'x-api-key': apiKey } }
).then(r => r.json());

balances.data.forEach(b => {
  console.log(`${b.asset.asset.symbol}: ${b.balance} (≈$${b.convertedBalance})`);
});

余额端点

范围	单一资产	所有资产
主钱包	`GET /v1/wallets/{walletId}/balance?assetId={assetId}`	`GET /v1/wallets/{walletId}/balances`
子地址	`GET /v1/wallets/{walletId}/addresses/{addressId}/balance?assetId={assetId}`	`GET /v1/wallets/{walletId}/addresses/{addressId}/balances`

管理地址

列出所有地址

获取钱包下的每个地址，并附带活跃与非活跃计数分析。

GET /v1/wallets/{walletId}/addresses

获取指定地址

获取单个地址的完整详细信息，包括其配置与元数据。

GET /v1/wallets/{walletId}/addresses/{addressId}

更新地址

修改地址的名称、元数据、活跃状态或归集配置。

curl --request PATCH \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Customer 12345 — upgraded",
    "metadata": {
      "userId": "user_12345",
      "plan": "enterprise"
    },
    "disableAutoSweep": true
  }'

const updated = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}`,
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      name: 'Customer 12345 — upgraded',
      metadata: {
        userId: 'user_12345',
        plan: 'enterprise'
      },
      disableAutoSweep: true
    })
  }
).then(r => r.json());

停用地址

将 isActive 设为 false 以停止监控地址。地址及其历史记录会保留 — 您可以随时重新激活。

await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}`,
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({ isActive: false })
  }
);

自动归集

默认情况下，子地址的存款会自动归集到主钱包。这样可以让客户地址保持清爽，将资金集中到财务或支付管理中。您可以在地址级别进行控制：

设置	行为
自动归集启用（默认）	确认后存款会自动移动到主钱包
自动归集禁用	存款保留在子地址，直到手动归集或提现

手动归集

如果禁用了自动归集，您可以按需触发归集：

POST /v1/wallets/{walletId}/sweep/assets

{
  "forceSweep": true
}

Deposit Finder

如果存款未出现（例如 Webhook 丢失），使用 Deposit Finder 重新扫描区块链：

POST /v1/wallets/{walletId}/rescan/blocks

{
  "transactionHash": "0xabc123..."
}

完整流程示例

以下是一个完整实现：启用资产、生成客户地址并处理存款 Webhook。

async function setupCustomerDeposit(walletId, userId) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';
  const headers = {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  };

  // 第 1 步：为客户生成专属地址
  const addressRes = await fetch(
    `${baseUrl}/wallets/${walletId}/addresses`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name: `User ${userId}`,
        metadata: { userId, createdAt: new Date().toISOString() }
      })
    }
  ).then(r => r.json());

  const depositAddress = addressRes.data.address;
  console.log('Share this address with customer:', depositAddress);

  return depositAddress;
}

// Webhook 处理器（Express.js 示例）
app.post('/webhooks/blockradar', (req, res) => {
  const { event, data } = req.body;

  if (event === 'deposit.success') {
    const userId = data.metadata?.userId;
    const amount = data.amount;
    const symbol = data.asset.symbol;

    console.log(`Deposit received: ${amount} ${symbol} from user ${userId}`);

    // 在您的系统中为用户账户记账
    creditUserAccount(userId, amount, symbol);
  }

  if (event === 'deposit.swept.success') {
    console.log(`Deposit swept to master wallet: ${data.amount} ${data.asset.symbol}`);
  }

  res.sendStatus(200);
});

最佳实践

地址管理

每位客户一个地址 — 为每位用户或每次支付会话生成唯一地址以简化归属
使用元数据 — 附加您的内部用户 ID 和引用，使 Webhook 负载直接映射到您的系统
停用而非删除 — 将不再使用的地址设为 isActive: false，保留历史记录

安全

验证 Webhook — 验证传入的 Webhook 请求来自 Blockradar
启用 AML 筛查 — Blockradar 可自动筛查存款地址（参见 AML 筛查）
监控 Webhook 日志 — 使用 GET /v1/wallets/{walletId}/webhooks 调试失败的投递

运营

只启用需要的资产 — 精简的资产列表可减少 Webhook 噪声并保持余额查询高效
先在 testnet 测试 — 生成地址、模拟存款并验证 Webhook 处理器后再切换到 mainnet
使用 Deposit Finder — 如客户报告未收到的存款，先重新扫描区块链再进一步排查

API 参考

钱包

端点	说明
Get Wallet	获取钱包详情和配置
Get Balance	查询主钱包上单一资产的余额
Get Balances	查询主钱包上所有资产的余额
Trigger Sweep	手动将存款归集到主钱包
Deposit Finder	重新扫描区块链以查找丢失的存款
Webhook Logs	查看 Webhook 投递历史

地址

端点	说明
Generate Address	创建新的客户存款地址
Get Addresses	列出钱包下所有地址
Get Address	获取指定地址的详情
Update Address	更新地址名称、元数据或配置
Get Balance	查询地址上单一资产的余额
Get Balances	查询地址上所有资产的余额
Get Transactions	查看地址的存款历史

资产管理

端点	说明
Get Wallet Assets	列出钱包上已启用的资产
Add Asset	启用新的稳定币用于存款
Remove Asset	停止监控某个稳定币
Update Asset	更新资产级配置

​前提条件

​工作原理

生成地址

检测存款

自动归集

查询余额

​精细化控制设计

​第 1 步：在钱包上启用资产

​第 2 步：为客户生成地址

​响应

​地址参数

​第 3 步：监听存款

​Webhook 事件

​Webhook Payload

​查询余额

​单一资产余额（钱包）

​所有资产余额（地址）

​余额端点

​管理地址

​列出所有地址

​获取指定地址

​更新地址

​停用地址

​自动归集

​手动归集

​Deposit Finder

​完整流程示例

​最佳实践

​地址管理

​安全

​运营

​API 参考

​钱包

​地址

​资产管理

前提条件

工作原理

精细化控制设计

第 1 步：在钱包上启用资产

第 2 步：为客户生成地址

响应

地址参数

第 3 步：监听存款

Webhook 事件

Webhook Payload

查询余额

单一资产余额（钱包）

所有资产余额（地址）

余额端点

管理地址

列出所有地址

获取指定地址

更新地址

停用地址

自动归集

手动归集

Deposit Finder

完整流程示例

最佳实践

地址管理

安全

运营

API 参考

钱包

地址

资产管理