# Concepts

Source: https://tenergy.me/docs/concepts
Last updated: 2026-09-27

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.

## Next steps

- [Quickstart](https://tenergy.me/docs/quickstart) — the same ideas as five requests.
- [Environments](https://tenergy.me/docs/environments) — what Nile can and cannot prove.
- [Pricing reference](https://tenergy.me/docs/api/prices) — the price table, estimates and quotes.