# 离线验证 TRON Webhook 接入

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

先读取 [OpenAPI 契约](/docs/openapi.json) 和 [签名验证说明](/docs/webhooks/)。API key 与 webhook secret 只放本地环境变量或凭据存储，不放 URL 和公开示例。

```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"}'
```

## 接收端验收清单

使用本地事件样例与本地密钥即可测试，无需创建真实 watch 或发起链上交易。

1. 对样例的原始字节计算 HMAC-SHA256。正确签名通过；修改一个字节、错误密钥、缺少签名和非法签名均拒绝。
2. 同一个 `event_id` 重放两次，只能产生一条持久化收件记录和一次后续入账处理。
3. 重启接收端后重放，仍不能重复处理。仅存在内存里的 Set 不适合生产去重。
4. 金额保留十进制字符串，校验事件格式。`transfer.confirmed` 不是发送资金的指令。
5. 使用 `next_cursor` 完成分页；写请求结果不确定时先查询已有配置，并比较完整接收端再决定下一步。

[TypeScript SDK 0.2.0](/docs/ai/packages/tronhooks-sdk-0.2.0.tgz) 提供验签、Telegram watch 类型和稳定游标遍历；校验 [SHA-256 清单](/docs/ai/packages/manifest.json)，npm 注册表发布单独核实。以已安装版本的类型为准。[平台接入说明](/docs/zh/use-cases/platform-deposits/) 介绍持久化收件箱；[AI 接入指南](/docs/zh/ai/) 说明额度和错误处理。

日常验收不要调用控制台的测试通知操作，它会发送真实消息。

## 下载并离线运行

- [Node 接收端](/docs/ai/examples/receiver.mjs)：`node receiver.mjs --self-test`，Node 22.13+。
- [Python 接收端](/docs/ai/examples/receiver.py)：`python3 receiver.py --self-test`，Python 3.9+。
- [cURL 配置脚本](/docs/ai/examples/create-watch.sh)：默认仅预览，`--create` 明确执行真实写入。
- [部署限制与说明](/docs/ai/examples/README.md)：本地 SQLite 收件箱、反向代理、后台处理和对账职责。

两个接收端均测试原始字节验签、非法输入、重启后去重、同 ID 不同内容、金额精度和存储失败。它们负责接收并持久化事件，不是完整支付账本。