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

# 从 0 到集成完成

> 在 2 小时内从零开始完成稳定币实时集成。

本指南带您完成使用 Blockradar 接受稳定币存款所需的一切，从账户设置到处理第一个 webhook 事件。单个开发者可以在 2 小时内完成集成并上线。

<Info>
  边读边构建。完成后您将拥有一个可运行的稳定币支付流程。
</Info>

## 您将构建什么

完成本指南后，您将拥有：

* 一个 Blockradar 账户和测试网上的主钱包
* 生成并与用户绑定的子地址
* 接收实时存款事件的 webhook 处理器
* 存款后更新用户余额的模式

***

## 第一步：创建账户

<Steps>
  <Step title="注册">
    访问 [dashboard.blockradar.co/signup](https://dashboard.blockradar.co/signup) 并完成注册流程。不到 60 秒即可完成。
  </Step>

  <Step title="检查 Live 模式">
    在控制台右上角您会看到一个 **Live 模式**开关。默认关闭，这意味着所有操作在**测试网**上运行，这是一个没有真实资金的安全沙盒。跟随本指南时请保持关闭状态。
  </Step>
</Steps>

***

## 第二步：创建主钱包

### 什么是主钱包？

主钱包是您稳定币基础设施的基础。将其视为您的金库——它控制您为用户创建的所有子地址。每个主钱包绑定到一条特定的区块链，因此如果您想支持 Ethereum、Base 和 BNB Chain 上的存款，需要为每条链单独创建一个主钱包。

### 创建您的第一个钱包

<Steps>
  <Step title="前往钱包页面">
    在控制台中点击**创建主钱包**。
  </Step>

  <Step title="选择网络">
    选择 \*\*Base Sepolia（测试网）\*\*来跟随本指南。
  </Step>

  <Step title="命名您的钱包">
    起一个名字如 `base-testnet`，然后点击**创建**。
  </Step>
</Steps>

***

## 第三步：为用户生成地址

### 什么是子地址？

当用户注册您的应用并需要接收稳定币时，他们需要一个钱包地址——类似于银行账号，但在区块链上。在 Blockradar 中，这些称为**子地址**。它们在您的主钱包下生成，并继承其网络配置。

<Note>
  在任何 EVM 兼容链（Base、Ethereum、BNB Chain 等）上生成的地址可在所有 EVM 链上使用。一个地址覆盖所有 EVM 网络。
</Note>

### 通过 API 生成地址

当用户在您的平台注册时调用此端点：

```bash theme={null}
curl -X POST https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  -H "x-api-key: 您的API密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "客户钱包",
    "disableAutoSweep": false,
    "enableGaslessWithdraw": true,
    "metadata": {
      "user_id": 1234,
      "email": "user@example.com"
    }
  }'
```

### metadata 字段

`metadata` 对象是此请求中最重要的部分之一。您在此处附加的任何内容都将包含在 Blockradar 为该地址发送的每个 webhook 中。这就是您的后端识别交易属于哪个用户的方式。

**最佳实践：** 始终在 metadata 中包含 `user_id`，以便将每笔存款直接映射到数据库中的用户。

***

## 第四步：配置自动归集和无 Gas 交易

### 自动归集

当自动归集启用（`disableAutoSweep: false`）时，存入子地址的资金会自动合并到您的主钱包中。

<Warning>
  要使自动归集正常工作，您的主钱包必须持有足够的原生代币来支付 Gas 费用。
</Warning>

**测试网 Gas 代币水龙头：**

| 网络               | 代币    | 水龙头                                                                                      |
| ---------------- | ----- | ---------------------------------------------------------------------------------------- |
| Base Sepolia     | ETH   | [alchemy.com/faucets/base-sepolia](https://www.alchemy.com/faucets/base-sepolia)         |
| Ethereum Sepolia | ETH   | [alchemy.com/faucets/ethereum-sepolia](https://www.alchemy.com/faucets/ethereum-sepolia) |
| BNB 测试网          | BNB   | [bnbchain.org/en/testnet-faucet](https://www.bnbchain.org/en/testnet-faucet)             |
| Polygon 测试网      | MATIC | [faucet.polygon.technology](https://faucet.polygon.technology/)                          |
| Tron 测试网         | TRX   | [nileex.io](https://nileex.io/join/getJoinPage)                                          |
| Solana Devnet    | SOL   | [faucet.solana.com](https://faucet.solana.com/)                                          |

### 无 Gas 交易

当 `enableGaslessWithdraw: true` 时，您的用户可以从其地址发送稳定币，而无需持有任何原生代币。您的主钱包代为支付 Gas 费用。

***

## 第五步：配置 Webhook

Blockradar 使用 webhook 在区块链事件发生时通知您的后端——存款、提款、归集等。

### 注册您的 Webhook 端点

1. 在控制台中前往您的主钱包
2. 点击**开发者 → Webhook**
3. 输入您的后端端点 URL（必须是 `POST` 端点）

### 在后端处理 Webhook

```javascript theme={null}
app.post("/webhook-handler", (req, res) => {
  const event = req.body;
  console.log("收到 Webhook:", event);
  res.sendStatus(200);
});
```

### 常见 Webhook 事件

| 事件                      | 描述            |
| ----------------------- | ------------- |
| `deposit.success`       | 子地址收到存款       |
| `deposit.swept.success` | 资金已从子地址归集到主钱包 |
| `withdraw.success`      | 提款已成功发送       |
| `swap.success`          | 兑换已成功执行       |

***

## 第六步：处理存款事件

### 示例负载

```json theme={null}
{
  "event": "deposit.success",
  "data": {
    "amountPaid": "10.0",
    "currency": "USD",
    "senderAddress": "0xabc...",
    "recipientAddress": "0xdef...",
    "metadata": {
      "user_id": 1234
    }
  }
}
```

### 处理方式

<Steps>
  <Step title="识别用户">
    从负载中提取 `metadata.user_id`，将存款映射到数据库中的用户。
  </Step>

  <Step title="读取金额">
    使用 `data.amountPaid` 确定存款金额。
  </Step>

  <Step title="更新余额">
    在数据库中为用户余额记账。
  </Step>
</Steps>

***

## 您构建了什么

现在您拥有一个完整的稳定币支付流程：

* 测试网上的主钱包
* 通过 metadata 与用户绑定的子地址
* 将资金合并到金库的自动归集
* 为用户消除摩擦的无 Gas 交易
* 实时更新余额的 webhook 处理器

## 下一步

<CardGroup cols={2}>
  <Card title="发送付款" icon="arrow-up-from-bracket" href="/zh/use-cases/pay-outs">
    以编程方式向用户或合作伙伴发送稳定币。
  </Card>

  <Card title="添加 AML 筛查" icon="shield-halved" href="/zh/use-cases/aml-screening">
    在发送或接收资金前筛查地址。
  </Card>

  <Card title="探索兑换" icon="arrows-rotate" href="/zh/use-cases/swap">
    让用户通过单个 API 调用在稳定币之间兑换。
  </Card>

  <Card title="上线生产" icon="rocket" href="https://dashboard.blockradar.co">
    在控制台启用 Live 模式，开始接受真实资金。
  </Card>
</CardGroup>