> For the complete documentation index, see [llms.txt](https://docs.catfee.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catfee.io/solutions/sweep-assist.md).

# 归集助手

Sweep Assist（归集助手）是 CatFee 面向 TRON 多地址收款、USDT 归集和热钱包整理场景提供的自动补能服务。

当您的收款地址达到归集条件时，CatFee 会按照预设规则为目标地址补充 TRON 能量，帮助后续 USDT 转账或归集脚本稳定执行。归集助手只负责补充能量，不接触私钥，不托管钱包，也不会替您转移 USDT、TRX 或其他资产。

<figure><img src="https://1836196186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6OSDuieZV2PmhnU7qYgh%2Fuploads%2Fgit-blob-09d5e183fbc8c92f7996d35a3828de2d013ff45b%2Fsweep-assist-workflow-zh-v2.png?alt=media" alt="归集助手工作流程：监控收款地址，命中补能规则后自动代理能量，确认上链后发送 Webhook 通知，最后由客户业务系统发起 USDT 归集。"><figcaption><p>CatFee 负责监控、补能与通知，客户通过自己的钱包或脚本完成资产归集。</p></figcaption></figure>

## 适合谁使用

归集助手适合需要管理多个 TRON 收款地址，并希望降低人工补能、人工值守和归集失败成本的用户。

**商户收款归集**

适合电商、支付团队、OTC 商户等多地址收款场景。多个收款地址陆续收到 USDT 后，系统可在达到归集阈值时自动补能，减少人工判断能量和手动补能带来的处理延迟。

**钱包与交易所运营**

适合钱包、交易所和资金运营团队。热钱包整理、充值地址处理和内部地址池归集通常需要稳定执行，归集助手可帮助运营团队保留补能记录、费用记录和失败状态，方便后续核对。

**DApp 与链上工具**

适合支付工具、链上工具和内部系统开发者。当业务地址能量状态不稳定时，用户转账可能失败，自研监控和补能系统也会增加开发维护成本。归集助手可作为地址监控和补能执行层，降低接入复杂度。

**小额高频收款**

适合个人或小型团队管理大量小额收款地址的场景。地址数量多时，逐个检查余额和能量效率较低，使用规则触发补能可以减少重复操作。

> **已有归集脚本？**
>
> 通常不需要大幅改造。归集助手可以作为现有归集流程前的一层能量保障：CatFee 负责在规则命中时补能，归集转账仍由您的钱包、脚本或业务系统发起。

## 核心能力

* **规则监控**：按地址池配置触发条件，例如 USDT 余额达到指定阈值。
* **批量地址管理**：支持将多个收款地址放入同一规则统一管理，后续可按业务需要增删地址。
* **自动补能**：规则命中后为目标地址补充 TRON 能量，减少 USDT 转账因能量不足失败的概率。
* **Webhook 通知**：能量代理确认上链后，通过回调通知您的业务系统，便于衔接归集脚本或通知客户。
* **预算控制**：可通过规则启停、单次补能数量和预算限制控制成本。
* **执行记录**：每次补能都会生成目标地址、能量数量、费用明细和执行状态，便于运营复盘和财务核对。
* **非托管边界**：不需要私钥，不控制钱包权限，不代转资产。

## 工作流程

### 1. 创建归集补能规则

在 CatFee Dashboard 中创建归集补能配置。创建配置时先设置基础规则，创建完成后再添加需要监控的收款地址。

常见配置项包括：

* **余额阈值（Balance Threshold）**：当监控地址的 USDT 余额大于或等于该阈值时，系统触发补能。例如设置为 `10`，表示地址余额达到 10 USDT 后触发补能。
* **补能数量（Energy Quantity）**：每次触发时补充的能量数量，最低为 65,000 Energy，可根据归集转账需要设置。
* **带宽保护（Bandwidth Protection）**：开启后会预留带宽，降低归集转账因带宽不足失败的概率。
* **备注（Remark）**：用于标记规则用途，例如主钱包归集、商户地址池或某个业务线。

创建配置后，需要继续添加监控地址。如果新增地址尚未激活，系统会自动激活该地址，并按 Dashboard 实际展示收取地址激活费用。

### 2. 导入收款地址

将需要监控的 TRON 收款地址导入规则。适合按业务线、商户、钱包地址池或归集批次分组管理。

导入后，系统会持续检查地址状态。您也可以根据业务变化新增、删除或调整地址。

### 3. 系统自动监控

规则启用后，CatFee 会持续检查地址是否达到触发条件。例如：

* 地址 USDT 余额达到 30 USDT、100 USDT 或其他自定义阈值。
* 地址进入需要归集的运营状态。
* 地址池中某个地址符合补能规则。

当前主要支持基于地址余额的触发条件。更多触发方式，例如时间触发、手动触发和组合规则，会以后续 Dashboard 实际能力为准。

### 4. 命中规则后自动补能

当地址满足条件时，系统会按照规则补充 TRON 能量。规则触发后，通常会在 1 个 TRON 区块内执行补能，约 3 秒。

补能完成后，您的归集脚本、钱包操作或内部系统即可继续发起 USDT 归集转账。

如需自动衔接后续流程，可订阅 `EVENT_DELEGATION` 代理确认事件，在能量代理确认上链后接收 [Webhook 通知](#webhook)。

### 5. 查看记录和费用

每次补能都会生成执行记录，通常包含：

* 执行时间
* 目标地址
* 补能数量
* 补能费用
* 交易 Hash 或执行状态
* 成功、失败、余额不足等结果说明

规则未命中前不会产生补能订单。补能失败不会扣费，失败状态会保留在记录中，方便排查地址、余额、规则或网络状态。

## Webhook 补能通知 <a href="#webhook" id="webhook"></a>

归集助手为目标地址代理能量并确认上链后，CatFee 可通过 HTTP `POST` 向您配置的回调地址发送 `EVENT_DELEGATION`（代理确认事件）。您的业务系统可以据此通知客户能量已到账，或衔接已有的 USDT 归集脚本。

### 配置与处理流程

1. 进入 **用户中心 → API 设置**，填写 `callbackUrl` 并勾选 `EVENT_DELEGATION` 事件。回调地址支持 HTTP 或 HTTPS，订阅需在页面配置，不支持通过 API 动态订阅。
2. 接收 JSON 回调，通过请求头 `X-EVENT-TYPE` 识别 `EVENT_DELEGATION`，并检查 `data.resource_type` 为 `ENERGY`，区分能量与带宽代理通知。
3. 根据 `data.receiver` 匹配您管理的收款地址及对应客户，结合业务中的待归集记录，通知客户或发起后续归集流程。
4. 使用 `X-EVENT-ID` 作为幂等键，避免重复通知客户或重复触发归集。成功接收并处理后返回 `HTTP 200`；已处理过的事件也应返回 `200`，否则平台会按重试策略重新通知。

### 关键回调字段

以下字段位于请求体的 `data` 中：

| 字段                     | 说明                                |
| ---------------------- | --------------------------------- |
| `resource_type`        | 资源类型，能量为 `ENERGY`，带宽为 `BANDWIDTH` |
| `receiver`             | 接收能量的目标地址，用于匹配收款地址及客户             |
| `quantity`             | 本次代理的资源数量                         |
| `delegation_hash`      | 代理交易 Hash，用于核对链上交易                |
| `delegation_timestamp` | 代理时间                              |

{% hint style="info" %}
`EVENT_DELEGATION` 表示能量或带宽代理已确认上链，不代表 USDT 已完成归集。后续资产转账仍由您的钱包、脚本或业务系统发起。
{% endhint %}

完整事件结构、字段定义、请求头与重试策略请参阅 [回调（Webhook）文档](/getting-started/webhook.md)。

## 配置示例

以下示例只用于理解配置思路，真实配置项和价格以 CatFee Dashboard 实际展示为准。

| 场景    | 触发条件          | 补能策略                     | 地址范围    | 余额要求             |
| ----- | ------------- | ------------------------ | ------- | ---------------- |
| 小额收款  | USDT 余额 ≥ 30  | 自定义补能数量，最低 65,000 Energy | 32 个地址  | 确保 CatFee 账户余额充足 |
| 商户归集  | USDT 余额 ≥ 100 | 自定义补能数量，最低 65,000 Energy | 128 个地址 | 确保 CatFee 账户余额充足 |
| 热钱包运营 | 业务余额达到运营阈值    | 自定义补能数量，最低 65,000 Energy | 500+ 地址 | 确保 CatFee 账户余额充足 |

## 费用与控制

归集助手按实际补能执行计费。规则命中前不会产生补能订单，规则暂停后也不会产生新的补能订单。

您可以通过以下方式控制成本：

* **暂停规则**：运营调整、活动结束或预算收紧时，可直接暂停规则。
* **控制单次补能数量**：根据转账类型选择合适的能量数量，避免过度补能。
* **查看执行记录**：通过目标地址、能量数量和费用明细核对成本。
* **关注账户余额**：账户余额不足时，Dashboard 会显示余额预警，建议及时充值，避免归集流程中断。

## 安全边界

归集助手只解决能量准备问题，不负责资产归集本身。

| 边界      | 说明                                          |
| ------- | ------------------------------------------- |
| 不需要私钥   | CatFee 不要求用户提交私钥，也不要求托管钱包                   |
| 不代转资产   | CatFee 只补充 TRON 能量，不代替用户发起 USDT、TRX 或其他资产转账 |
| 用户保留控制权 | 用户可以随时暂停、修改或删除规则，也可以调整地址列表和补能策略             |
| 记录可审计   | 补能结果和费用明细可用于运营复盘、财务核对和问题排查                  |

## 操作建议

1. 先梳理需要监控的收款地址，并按业务线或用途分组。
2. 根据归集策略设置 USDT 余额阈值，例如小额收款使用较低阈值，商户归集使用较高阈值。
3. 根据目标转账类型选择补能数量，例如 65,000 Energy 或 131,000 Energy。
4. 设置预算限制和余额提醒，避免账户余额不足导致补能失败。
5. 先用少量地址验证规则，再逐步扩大到完整地址池。
6. 定期导出或查看执行记录，用于运营复盘和成本核对。

## 常见问题

### 什么是归集助手？

归集助手是 CatFee 面向 USDT 多地址收款和资金归集场景提供的自动补能能力。用户配置监控地址、余额阈值和补能规则后，当地址达到归集条件时，系统会为目标地址补充 TRON 能量，减少 USDT 转账因能量不足而失败或中断。

### CatFee 会控制我的钱包吗？

不会。归集助手是非托管服务，不需要私钥，也不会控制您的钱包权限。CatFee 只在规则命中时为目标地址补充 TRON 能量。

### 补能后会自动帮我归集 USDT 吗？

不会。归集助手只解决 TRON 能量准备问题，不负责转移资产。补能完成后，仍由您的钱包操作、归集脚本或内部系统发起 USDT 归集转账。

### 什么情况下会自动补能？

当您配置的 TRON 地址满足触发条件时会自动补能，例如 USDT 余额达到指定归集阈值。您可以在 Dashboard 中配置监控条件和补能策略。

### 补能需要多长时间？

规则触发后，系统通常会在 1 个 TRON 区块内执行补能，约 3 秒。能量到账后，您的 USDT 归集脚本或转账流程即可继续执行。

### 如果补能失败会怎样？

如果自动补能失败，系统会记录失败状态，并在 Dashboard 中展示执行结果，方便您排查地址、余额、规则或网络状态等问题。补能失败不会扣费。

### 是否支持批量导入地址？

支持。归集助手适合商户、钱包和交易所管理大量 TRON 收款地址。您可以通过 Dashboard 批量导入地址列表，并统一配置补能规则。

### 可以随时修改或删除规则吗？

可以。您可以随时暂停、修改或删除归集补能规则，也可以调整地址列表、USDT 余额阈值和补能数量。规则暂停后不会产生新的补能订单。

### 我已经有归集脚本，还需要改造吗？

通常不需要大幅改造。CatFee 归集补能可以作为现有 USDT 归集流程前的一层能量保障。补能完成后，继续由原有脚本、钱包或内部系统发起归集。如果需要 API 对接，请联系 CatFee 技术支持确认方案。