首页 / 快速开始

快速开始

从注册到收到第一条到账确认 webhook,大约 5 分钟。注册免费、免信用卡,30 秒完成。

1. 注册账号,创建 API key

1. 在 tronhooks.com/app 注册(邮箱+密码,或 TronLink 钱包登录)。
2. 在 API keys 区创建 key(tw_live_…,主网)。key 明文只显示一次,立即保存。

2. 注册监控地址

curl -X POST https://tronhooks.com/v1/watches \
  -H "Authorization: Bearer tw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "T你的地址...",
    "asset_filter": "USDT",
    "direction": "incoming",
    "webhook_url": "https://your-server.example/tron-hook"
  }'

201 响应包含 watch 信息和 只显示一次 的签名密钥 secret(whsec_…)。

direction 可选 incoming(入账,默认)/ outgoing(转出)/ both(双向)。

3. 接收并验签

到账固化确认后,我们 POST 一条 JSON,带 X-Signature 头。必须对原始请求体验签:

import express from 'express';
import { constructEvent } from '@tronhooks/sdk';   // npm i @tronhooks/sdk

const app = express();
app.post('/tron-hook', express.raw({ type: 'application/json' }), (req, res) => {
  const event = constructEvent(req.body, req.header('x-signature'), process.env.WHSEC);
  console.log(`${event.amount} ${event.asset} → ${event.to}`);
  res.sendStatus(200); // 任何 2xx 都算确认收到
});

4. 随时对账

curl "https://tronhooks.com/v1/events?limit=10" \
  -H "Authorization: Bearer tw_live_..."

GET /v1/events 返回全部事件与投递状态——接收端宕机时的兜底。投递语义是 at-least-once:按 event_id 去重。

不写代码?Telegram 路径

1. 在 /app 注册。
2. 点 Connect Telegram → 打开链接 → 按 Start(群聊:把 @tronhooks_bot 拉进群,发 /bind 绑定码)。
3. 添加地址,通知目标选 → Telegram。到账确认后 TG 消息直达,带 Tronscan 链接。

如何测试

tronhooks 运行在 TRON 主网,不动真金也能完整验证:

1. TEST 按钮(零链上操作):控制台 watch 表单旁点 Send test,立即向你的 webhook / Telegram 发一条带签名的样例通知——验证接收端、验签和解析。
2. 监控一个活跃地址(立刻看到真实事件流):随便 watch 一个高频主网地址,几秒内就有真实确认事件。选址技巧:打开 Tronscan 的 USDT 转账列表,挑反复出现的地址(交易所热钱包最合适),看完删掉 watch 即可。
3. 用自己的地址走全链路:watch 自己的地址(方向选 both),给自己转 1 TRX(手续费几美分),确认后 ~3 秒收到带签名的回调 / TG 消息和 Tronscan 链接。

收不到回调?三个常见原因

1. URL 不可达或被安全规则拒绝:必须是公网可解析的 http(s) 地址,内网/保留地址(localhost、10.x、192.168.x 等)在创建和投递时都会被拒。开发期可用 webhook 调试器。
2. 验签失败:几乎都是没用原始 body(见上面的加粗提示)。
3. 看投递日志:控制台 → Events & delivery log → 点开事件,每次尝试的响应码都有记录(重试节奏 1m/5m/30m/2h/6h,之后进死信)。