Concepts
A short glossary for anyone integrating with the API. For live numbers, call the API — nothing below is a price or a schedule.
Energy and bandwidth
TRON accounts spend two chain resources on every transaction: energy (consumed by smart contract calls, including TRC-20 transfers such as USDT) and bandwidth (consumed by transaction size). Without enough of either, the sender must burn TRX instead. We rent both by the unit for a fixed window and delegate them on chain to the address you name — nothing leaves your wallet, and no private key is ever required.
Tiers
A tier is a rental window, named by its length. The API sells 5m and 1h. 1d exists
but is switched off: an order for it answers 2003 tier_unavailable. Check available on each
GET /v1/prices row rather than assuming a fixed list.
Day parts
Prices move with the time of day: the platform defines two or more day parts (for example
an off-peak and a peak window), each with its own price per unit. Boundaries are set in UTC on
the server; the site displays them converted to your own time zone. Always read the current
day part from GET /v1/prices rather than hardcoding one.
Order states
An order moves through one state machine: created → paid → allocating → delegated → confirmed → active → expired | reclaimed, with failed and refunded as terminal branches
reached on error. Partial delivery is not a separate state — it is a flag (partial: true)
plus a delivered_amount below the amount ordered, on an order that is otherwise
confirmed/active as normal.
Quote TTL
A quote pins a price for a short window (120 seconds). Order against quote_id before it
expires to be charged exactly the quoted total; after that, take a fresh quote.
Idempotency with client_order_id
Every order creation should carry a client_order_id you generate. Re-sending the same
request with the same id returns the original order instead of creating a second one — the
safe way to retry a timed-out request without risking a double purchase.
Subscriptions
A subscription keeps an address supplied with energy. It is three numbers: a reserve R, a refill-below level (low) and a refill-up-to level (high).
| Preset | Reserve | Daily fee |
|---|---|---|
| Basic | 131,000 | 6 TRX |
| 1.3M | 1,300,000 | 60 TRX |
| 2.62M | 2,620,000 | 120 TRX |
| 5.24M | 5,240,000 | 240 TRX |
| Rule | Value |
|---|---|
| Reserve | 131,000 ≤ R ≤ 5,240,000, step 1,000 |
| low | ≥ 65,000 |
| high | high − low ≥ 65,000 and high ≤ R; Basic (low = high = R) is the exception |
| Daily fee | ceil(R × 6 / 131,000) whole TRX; the first day at start, then every 24 hours |
| Refills | Charged at the live 1h price |
| Access | An API key with subscriptions.read / subscriptions.write, or the dashboard session |
| Errors | A broken rule: 3020 subscription_rule_invalid with details.violations; while subscriptions are switched off: 3021 subscriptions_unavailable |
Direct TRX transfer
A brand publishes payment addresses: send TRX to one, with an optional memo, and the transfer becomes an energy order. No account is needed.
| Case | What happens |
|---|---|
| Memo holds a TRON address | Energy goes to that address (the receiver, not an account) |
| Empty memo | Energy goes to the sender |
| TRX sent by a contract | Energy goes to the transaction’s signer |
| Price | The price at the moment the transfer arrives |
| Below the window’s minimum, or a memo that is not a valid address | Kept, not filled |
| The part that does not buy a whole 1,000-unit step | Kept |
Nothing on this path is refunded, so check the memo before sending.
Confirmations
| Payment | Filled or credited after |
|---|---|
| Direct transfer below 50 TRX | 1 confirmation |
| Direct transfer from 50 TRX | 19 confirmations |
| Account top-up (TRX or USDT to the deposit address) | 19 confirmations, about a minute |
The dashboard shows a top-up as soon as it is seen on chain; the balance is credited at 19.