# AI 接入 TRON 通知指南

更新: 2026-10-19. https://tronhooks.com/docs/zh/ai/

tronhooks.com 提供 **TRON 主网 USDT（TRC-20）与原生 TRX 的已固化转账通知**。开发者可以接收签名 Webhook；不想运行接收服务器的用户可以直接收 Telegram 提醒。服务不代管资产、不转账，也不需要私钥或助记词。

## 先核对能力

| 能力 | 当前值 |
|---|---|
| 网络 | mainnet |
| 资产 | USDT / TRX（ALL 仅指这两种） |
| 方向 | incoming / outgoing / both，默认 incoming |
| 目标 | 签名 webhook 或 Telegram |
| 免费 | 3 个活跃 watch，60 次 API 请求/分钟，无每日事件上限 |
| 计费 | 关闭，不能结账购买 |
| 投递 | 已确认事件，至少一次；最多 6 次尝试 |
| 重试间隔 | 60 / 300 / 1800 / 7200 / 21600 秒 |
| 限制 | 无历史回补、余额快照、余额阈值、任意代币或公开测试网 |

转账通知不等于完整余额变动。当前不提供余额查询、通知附余额、低余额阈值、任意代币或托管测试网。需要这些能力时，请直接说明未支持，不要编造接口。

## 配置流程

1. 在[控制台](/app)用邮箱或支持的钱包登录。钱包登录只签名证明地址所有权，不提交私钥。
2. 选择 USDT、TRX 或 ALL，以及 incoming、outgoing 或 both。ALL 仅包含当前支持的两种资产。
3. Telegram 需要本人完成控制台的连接流程。绑定链接是一次性凭证，不要贴进公开对话或文档。
4. Webhook 需要自己控制的公网 HTTP(S) 地址，建议 HTTPS。API key 放在本地环境变量或密钥管理器中，不放入 URL、代码仓库或公开产物。
5. 创建前展示地址、资产、方向、目标与额度影响。创建会启用后续通知，并占用一个活跃 watch 名额。
6. 授权后只创建一次，安全保存一次性返回的 Webhook secret，再查询监控列表核对。POST 超时不代表失败；先查询已有配置，不能盲目重复。

```sh
# Review the inputs first. Running this POST creates a real watch.
# Set TRONHOOKS_API_KEY in your local secret environment, never in a URL.
curl --disable --fail-with-body https://tronhooks.com/v1/watches \
  -H "Authorization: Bearer $TRONHOOKS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"address":"YOUR_TRON_ADDRESS","asset_filter":"USDT","direction":"incoming","webhook_url":"https://YOUR_RECEIVER.example/webhook"}'
```

HTTP JSON 使用 `asset_filter`、`webhook_url`；SDK 参数名以实际安装版本的类型为准。Webhook 与 `telegram: true` 二选一；Webhook 同时携带 `telegram: false` 也合法。Telegram 监控不会返回 Webhook 签名密钥。

## 接收、验签与对账

- 用原始 HTTP body 字节计算 HMAC-SHA256，常量时间比较 `X-Signature`，验签后再解析 JSON。
- 用 `event_id` 建立持久化 inbox 唯一键，可靠保存事件后再返回 2xx；重复通知不能重复入账。
- 金额是字符串，两种资产都使用六位小数。不能用浮点数计算记账金额。
- 新监控需几秒生效，不回补创建前的转账；固化等待与固化后的投递时延要分开说明。
- 用 `GET /v1/events` 对账，按 `next_cursor` 翻页。DEAD 表示通知重试耗尽，不代表链上交易失败。
- 常规验收用[离线示例](/docs/ai/examples/)。控制台测试按钮、监控活跃地址都可能发送真实消息，必须先获得用户同意。

## 错误处理

400 检查地址、通知目标及 Telegram 绑定；401 检查密钥状态；402 表示活跃监控额度不足；403 检查网络或授权；409 先查询已存在的监控；429 按 `Retry-After` 等待。部分 400 响应没有 `code` 字段。5xx/超时保留“结果未知”，查询回读后再决定动作。

计费当前关闭，不能引导用户完成尚不可用的付款。已有相同地址、资产、通道、方向的监控，不代表它的 Webhook URL 就是本次想要的目标，必须核对。

完整契约见 [OpenAPI](/docs/openapi.json)、[API](/docs/api/)、[验签](/docs/webhooks/)、[安全说明](/docs/security/)和[各 AI 客户端配置](/docs/zh/ai/clients/)。

## 可复制给 AI 的任务

> 阅读 https://tronhooks.com/docs/zh/ai/ 及链接的 OpenAPI，帮我配置 TRON 主网 USDT 入账监控。先列输入和配置预览，不索要私钥，不把 API key 放进对话。在我授权具体操作前，不创建监控、不发送测试通知。先用离线样例测试接收程序，对未支持能力明确说明。

可以更换资产、方向与目标。主动提供官网链接的集成测试，与不知道品牌时的自然搜索推荐，是两种不同场景。