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. Energy is sold for 5m, 10m, 15m,
30m, 1h and 1d. An order is filled by the cheapest provider term not shorter than the
one asked (a 5m order may be bought as 15m); the order’s filled_tier says which term was
bought. A term not on sale answers 2003 tier_unavailable; paid by a plain transfer, without
an account, a term under an hour may be 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 day is split into seven day parts, 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
Coming soon: not available yet.
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; until subscriptions launch: 3021 subscriptions_unavailable |
Direct TRX transfer
We publish 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.