业务状态与处理
| 看到的结果 | 确切含义 | 下一步 |
|---|---|---|
| HTTP200且code0 | 本次请求得到业务响应 | 读取data；批量操作继续检查每个items元素 |
| 创建归集items[].status=pending | 该钱包已建立任务 | 保存任务ID，查归集详情或等待结果回调 |
| 创建归集items[].status=failed | 该钱包未成功创建任务 | 查看reason，处理后以新的业务请求重新提交 |
| 归集详情status=succeeded | 已核验链上实际转账成功 | 按txid对账，读取实际费用 |
| 归集详情status=unknown | 原交易广播结果暂未确认 | 继续查原任务，不能发起另一笔归集 |
| 到账记录存在 | 以 status 判断有效或已撤销，以 revision 判断版本 | 按到账 ID 更新状态；链上对账使用 network + txid + log_index |
| 通知详情status=failed | 本轮推送异常 | 到账/归集结果仍然有效；修复接收端后人工重推 |
归集任务状态
| status | 含义 | 是否结束 |
|---|---|---|
| pending | 等待准备，可能正在等待带宽、租赁或资源到账 | 否 |
| ready | 已完成当前准备，等待后续执行 | 否 |
| signed | 已生成并保存签名交易 | 否 |
| broadcast | 已广播，等待链上确认 | 否 |
| unknown | 广播结果未知，核验原交易中 | 否 |
| succeeded | 已核验实际USDT转账成功 | 是 |
| failed | 任务失败，查看reason | 是 |
| cancelled | 未签名任务因策略等变化取消 | 是 |
对未结束的任务持续查询原ID，不重复创建。failed 后也应阅读 reason、txid 和回调，确认业务结果再决定发起新操作；旧 request_id 只会重放原来的创建响应。
准备阶段
preparation_stage 是任务的准备进度，不能代替 status 判断成功。
| 值 | 含义 |
|---|---|
| queued | 等待资源与业务条件检查 |
| waiting_bandwidth | 免费带宽不足，等待恢复 |
| renting | 正在准备或查询CatFee租赁 |
| waiting_energy | 等待订单确认及链上能量到账 |
| ready | 准备完成 |
费用先使用已有能量，再判断钱包TRX能否支付全部能量缺口，最后才租赁。等待免费带宽期间不购买能量，不主动燃烧TRX支付带宽。租赁费用与链上实际手续费分开返回。
金额和空值
- requested_amount：创建时请求金额。all模式为null；fixed为每个钱包的固定金额。
- amount：任务准备后固定的实际转账金额；不能用创建时的余额代替。
- balance_usdt、balance_trx：最近一次同步的余额；null代表尚未同步，不代表0。
- actual_fee：链上实际钱包手续费，SUN。尚未确认时可能为字符串"0"，不能据此判断已完成或免费，必须同时检查任务status。
- energy_rental：未建立租赁记录为null；其paid_cost与activation_cost属于平台CatFee支出。
- txid：任务未形成链上交易时可能无值，按接口字段表处理。
- 所有金额均为最小单位整数字符串，1000000等于1 USDT或1 TRX；不要转浮点数。
回调的三个状态层级
| 层级 | 状态 | 含义 |
|---|---|---|
| 通知主记录/本轮 | pending、delivering、delivered、failed | 待推送、推送中、已成功、推送异常 |
| 每次尝试 | sending、succeeded、failed、unknown | 请求中、得到成功应答、失败、结果未知 |
| 链上业务 | deposit.confirmed、deposit.reverted 或归集任务终态 | 资金实际结果，与推送状态独立 |
每轮最多20次、间隔至少30秒、10分钟截止。唯一成功应答是HTTP200及JSON {"code":"SUCCESS"}。接收端先验证并解密，再将业务和事件去重记录一起提交，最后返回成功。同一事件重复到达时不得重复入账，已完成事件仍返回成功。
只有推送异常的通知可重新开启一轮，事件ID不变。详情中的历史轮次、HTTP状态、返回正文和网络错误用于定位问题。
到账查询与通知
到账详情data、到账列表items[]和到账通知解密正文共用完整 24 个字段，包括custom_id、chain、asset、decimals、block_time和created_at。status 为 confirmed 或 reverted；按 id 和 revision 更新到账状态，投递状态通过独立通知接口查询。重试时业务正文不变化。