> ## 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.

# 存入稳定币

> 通过专属地址接收稳定币存款，支持自动归集和 Webhook 通知

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

## 前提条件

<Steps>
  <Step title="API 密钥">
    从 [Blockradar 控制台](https://dashboard.blockradar.co) 获取您的 API 密钥。进入 **Developers** 生成密钥。
  </Step>

  <Step title="主钱包">
    通过控制台或 API 创建钱包。所有存款操作都需要 `walletId`。
  </Step>

  <Step title="启用资产">
    在钱包上启用您希望接收的稳定币。钱包只会检测您明确添加的资产的存款 — 参见 [资产管理](/zh/use-cases/asset-management)。
  </Step>

  <Step title="Webhook URL">
    在控制台的 **Developers → Webhooks** 中配置 Webhook 端点以实时接收存款通知。
  </Step>
</Steps>

## 工作原理

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

<CardGroup cols={2}>
  <Card title="生成地址" icon="address-card">
    为每位客户或支付会话创建唯一的区块链地址。该地址的存款会自动归属到对应客户。
  </Card>

  <Card title="检测存款" icon="bell">
    Blockradar 监控所有生成的地址，一旦存款到达即触发 Webhook。无需轮询。
  </Card>

  <Card title="自动归集" icon="broom">
    存款会自动归集到您的主钱包，保持客户地址清爽，资金集中管理。
  </Card>

  <Card title="查询余额" icon="scale-balanced">
    在钱包或地址级别查询余额，支持单一资产或所有资产，并包含 USD 折算。
  </Card>
</CardGroup>

## 精细化控制设计

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

这意味着您可以：

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

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

***

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

接收存款之前，钱包需要知道要监控哪些稳定币。使用 [Get Assets](/zh/api-reference/miscellaneous/get-assets) 端点获取可用资产，然后添加您需要的资产。

<CodeGroup>
  ```bash Curl theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

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

<Tip>
  使用 [Get Wallet Assets](/zh/api-reference/asset/get-wallet-assets) 获取钱包专属的资产 ID。这些 ID 用于余额查询和其他 API 调用 — 与全局资产 ID 不同。
</Tip>

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

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

<CodeGroup>
  ```bash Curl theme={null}
  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"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

### 响应

```json theme={null}
{
  "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

```json theme={null}
{
  "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"
  }
}
```

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

***

## 查询余额

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

### 单一资产余额（钱包）

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

  ```javascript JavaScript theme={null}
  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})`);
  ```
</CodeGroup>

### 所有资产余额（地址）

<CodeGroup>
  ```bash Curl theme={null}
  curl --request GET \
    --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/balances \
    --header 'x-api-key: <api-key>'
  ```

  ```javascript JavaScript theme={null}
  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})`);
  });
  ```
</CodeGroup>

### 余额端点

| 范围  | 单一资产                                                                         | 所有资产                                                        |
| --- | ---------------------------------------------------------------------------- | ----------------------------------------------------------- |
| 主钱包 | `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` |

***

## 管理地址

### 列出所有地址

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

```bash theme={null}
GET /v1/wallets/{walletId}/addresses
```

### 获取指定地址

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

```bash theme={null}
GET /v1/wallets/{walletId}/addresses/{addressId}
```

### 更新地址

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

<CodeGroup>
  ```bash Curl theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  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());
  ```
</CodeGroup>

### 停用地址

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

```javascript theme={null}
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 })
  }
);
```

***

## 自动归集

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

您可以在地址级别进行控制：

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

### 手动归集

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

```bash theme={null}
POST /v1/wallets/{walletId}/sweep/assets
```

```json theme={null}
{
  "forceSweep": true
}
```

### Deposit Finder

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

```bash theme={null}
POST /v1/wallets/{walletId}/rescan/blocks
```

```json theme={null}
{
  "transactionHash": "0xabc123..."
}
```

***

## 完整流程示例

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

```javascript theme={null}
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 筛查](/zh/use-cases/aml-screening)）
* **监控 Webhook 日志** — 使用 `GET /v1/wallets/{walletId}/webhooks` 调试失败的投递

### 运营

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

***

## API 参考

### 钱包

| 端点                                                             | 说明              |
| -------------------------------------------------------------- | --------------- |
| [Get Wallet](/zh/api-reference/wallet/get-wallet)              | 获取钱包详情和配置       |
| [Get Balance](/zh/api-reference/wallet/get-balance)            | 查询主钱包上单一资产的余额   |
| [Get Balances](/zh/api-reference/wallet/get-balances)          | 查询主钱包上所有资产的余额   |
| [Trigger Sweep](/zh/api-reference/wallet/trigger-sweep-assets) | 手动将存款归集到主钱包     |
| [Deposit Finder](/zh/api-reference/wallet/deposit-finder)      | 重新扫描区块链以查找丢失的存款 |
| [Webhook Logs](/zh/api-reference/wallet/webhooks-logs)         | 查看 Webhook 投递历史 |

### 地址

| 端点                                                               | 说明            |
| ---------------------------------------------------------------- | ------------- |
| [Generate Address](/zh/api-reference/addresses/generate-address) | 创建新的客户存款地址    |
| [Get Addresses](/zh/api-reference/addresses/get-addresses)       | 列出钱包下所有地址     |
| [Get Address](/zh/api-reference/addresses/get-address)           | 获取指定地址的详情     |
| [Update Address](/zh/api-reference/addresses/update-address)     | 更新地址名称、元数据或配置 |
| [Get Balance](/zh/api-reference/addresses/get-balance)           | 查询地址上单一资产的余额  |
| [Get Balances](/zh/api-reference/addresses/get-balances)         | 查询地址上所有资产的余额  |
| [Get Transactions](/zh/api-reference/addresses/get-transactions) | 查看地址的存款历史     |

### 资产管理

| 端点                                                               | 说明          |
| ---------------------------------------------------------------- | ----------- |
| [Get Wallet Assets](/zh/api-reference/asset/get-wallet-assets)   | 列出钱包上已启用的资产 |
| [Add Asset](/zh/api-reference/asset/add-asset-to-wallet)         | 启用新的稳定币用于存款 |
| [Remove Asset](/zh/api-reference/asset/remove-asset-from-wallet) | 停止监控某个稳定币   |
| [Update Asset](/zh/api-reference/asset/update-wallet-asset)      | 更新资产级配置     |