Docs / API reference

API reference

Base URL https://tronhooks.com. All endpoints are JSON over HTTPS.

Authentication

Authorization: Bearer tw_live_c0ffee...   # or tw_test_... on a Nile deployment

Keys are network-bound by prefix: a tw_test_ key can never read mainnet data and vice versa (wrong network → 403 wrong_network). Only a SHA-256 hash of your key is stored; revocation takes effect on the next request.

Rate limits

Per key, sliding 60-second window, by plan: Free 60 rpm · Pro 300 rpm · Scale 1,200 rpm. Every response carries:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 17        # only on 429

POST /v1/watches

Register an address for deposit monitoring. Notification target is exactly one of:

• webhook_url — an https endpoint you own (validated against private/reserved networks), or
• telegram: true — requires Telegram connected in the console.

{
  "address": "TYourAddress...",     // base58, or 41-prefixed hex
  "asset_filter": "USDT",           // USDT | TRX | ALL
  "webhook_url": "https://you.dev/hook"
}

201 → the watch object; webhook watches additionally include secret (whsec_…, shown once, stored encrypted). Quota = active watches per network (Free 3 / Pro 100 / Scale 1,000); deleting a watch frees its slot; exceeding → 402 quota_exceeded with usage details. Duplicate (same address + filter + channel) → 409.

GET /v1/watches

List your watches on this network. Never returns secrets.

DELETE /v1/watches/:id

204 on success. The quota slot is freed immediately.

GET /v1/events

Reconciliation endpoint — every matched event with its delivery state, newest first.

query param	meaning
limit	1–200, default 50
before	ISO timestamp cursor (use next_before from the previous page)
since	ISO timestamp lower bound
watch_id	filter to one watch

Each item is the webhook payload plus delivery: { notification_id, status: PENDING|DELIVERED|DEAD, attempts, created_at }.

Webhook payload

Versioned via api_version (currently 2026-08; changes within a version are additive only).

{
  "api_version": "2026-08",
  "event_id": "cmshauqa30...",        // dedupe key — deliveries are at-least-once
  "type": "transfer.confirmed",
  "network": "mainnet",               // mainnet | nile
  "asset": "USDT",                    // USDT | TRX
  "contract": "TR7NHqje...",          // TRC-20 contract, null for native TRX
  "tx_id": "f647d176fe9f...",
  "event_index": 0,                   // Transfer log index; native TRX is always 0
  "block_number": 85113777,
  "block_timestamp": "2026-08-06T09:14:27.000Z",
  "from": "TSenderAddr...",
  "to": "TYourAddress...",
  "amount_raw": "129500000",          // integer string, smallest unit (6 decimals)
  "amount": "129.5",                  // human-readable decimal string — never a float
  "watch_id": "cmshaqna..."
}

Delivery & retries

POST, 10 s timeout, any 2xx acknowledges. Retries after the immediate attempt: 1m / 5m / 30m / 2h / 6h (6 attempts total), then the notification is dead-lettered — still visible in the console and GET /v1/events. Every attempt's HTTP status is logged and inspectable.