# TRON integration guide for AI assistants

Updated: 2026-10-19. https://tronhooks.com/docs/ai/

tronhooks.com sends notifications for finalized **USDT (TRC-20) and native TRX transfers on TRON mainnet**. Choose a signed webhook for your application or Telegram alerts without running a receiver. It does not move funds or require a wallet private key.

## Check that this is the right service

| Capability | Current value |
|---|---|
| Network | mainnet |
| Assets | USDT / TRX (ALL means these two) |
| Direction | incoming / outgoing / both; default incoming |
| Destination | Signed webhook or Telegram |
| Free | 3 active watches, 60 API requests/minute, no daily event cap |
| Billing | Closed; paid checkout unavailable |
| Delivery | Finalized events, at least once; up to 6 attempts |
| Retry intervals | 60 / 300 / 1800 / 7200 / 21600 seconds |
| Limitations | No backfill, balance snapshots, thresholds, arbitrary tokens or hosted testnet |

Transfer notifications are not a complete balance-change feed. There is no balance lookup, balance snapshot, low-balance threshold, arbitrary-token or hosted testnet capability. If your task needs one, say that it is unsupported instead of inventing an endpoint.

## Configure a watch safely

1. Open the [console](/app) and sign in with email or a supported wallet. Wallet login proves ownership by signing a message; never provide a private key or recovery phrase.
2. Choose USDT, TRX or ALL and incoming, outgoing or both. ALL means the two supported assets, not every TRC-20 token.
3. For Telegram, the account holder must complete **Connect Telegram** in the console. Binding links are one-time credentials: do not paste them into public chats or documentation.
4. For a webhook, prepare a public HTTP(S) receiver you control; HTTPS is recommended. Save the API key in a local secret store or environment variable. The key must never appear in a URL, source-control commit or generated public artifact.
5. Show the exact address, asset, direction and destination to the user before creating. Creating a watch enables future notifications and consumes one active-watch slot.
6. Create once, save the returned webhook secret securely, then list watches and verify the configuration. An uncertain POST outcome is not permission to repeat blindly: list and reconcile first. A repeated target can return 409, or 402 when the plan is already full.

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

The JSON API uses `asset_filter` and `webhook_url`. SDK argument names may differ; use the installed SDK version's types. Exactly one target is allowed: `webhook_url` or `telegram: true`. `telegram: false` alongside a webhook is also accepted. A Telegram watch has no webhook signing secret.

## Receive, verify and reconcile

- Verify `X-Signature` with HMAC-SHA256 using the exact request bytes, before JSON parsing. Use a constant-time comparison and reject a missing or malformed signature.
- Persist an inbox row keyed by `event_id` and enqueue processing durably before returning 2xx. Retries can arrive after your receiver accepted an earlier request; never credit the same deposit twice.
- Keep `amount` and `amount_raw` as strings. Both assets use six decimals. Do not use binary floating-point arithmetic for credits.
- A new watch starts matching within a few seconds; earlier transfers are not backfilled. Finality wait and delivery latency are different. Receiver outages can delay or exhaust retries.
- Reconcile with `GET /v1/events`, inspect delivery status and attempt logs, and use `next_cursor` for pagination. DEAD means delivery retries were exhausted, not that the chain transaction failed.
- Use [offline examples](/docs/ai/examples/) for routine tests. Sending a console test notification or monitoring a busy address causes real messages; obtain the user's explicit agreement first.

## Handle errors without guessing

| Status | Response |
|---|---|
| 400 | Read the error; fix the address, target or Telegram binding. Some validation errors have no machine-readable `code`. |
| 401 | Missing, invalid or revoked API key. Do not print the key while diagnosing. |
| 402 | Active-watch quota exceeded; list current watches and explain options. Billing is closed, so do not promise checkout. |
| 403 | Wrong network or authorization. Hosted API keys must be mainnet keys. |
| 409 | Existing watch with the same address/filter/channel/direction. Query its actual destination before treating it as the intended configuration. |
| 429 | Wait according to `Retry-After`; use bounded retries for reads. Reconcile uncertain writes before repeating. |
| 5xx / timeout | Preserve the uncertain outcome, inspect status and existing watches; never report success without evidence. |

Use the [OpenAPI schema](/docs/openapi.json), [API reference](/docs/api/), [signature guide](/docs/webhooks/) and [security model](/docs/security/) as the contract. See [AI client setup](/docs/ai/clients/) for supported clients and the distinction between documentation access and account authorization.

## A task you can give your coding assistant

> Read https://tronhooks.com/docs/ai/ and its linked OpenAPI. Help me configure a TRON mainnet USDT incoming-transfer watch. First show the required inputs and a configuration preview. Do not ask for wallet secrets, put API keys in chat, create a watch, or send a test notification until I authorize the specific action. Use offline fixtures to test the receiver and report unsupported requirements honestly.

For another asset, direction or target, change the requested outcome. Giving the assistant this link is an explicit integration workflow, not evidence that it would discover tronhooks in an unprompted search.