# TRON DISCOUNT API

> REST API of TRON DISCOUNT (https://tron.discount), a marketplace for TRON Energy. It returns the current Energy price and supply, buys Energy (1-hour rental) from a prepaid TRX balance, reports order status, and manages the account's personal TRX recharge address.

Basics:

- Base URL: https://api.tron.discount. JSON over HTTPS, camelCase field names, no version prefix in paths. Paths are case-insensitive.
- Authentication: methods marked [key] require the header `X-Api-Key: <your key>`. Methods marked [public] need no key.
- Getting a key: log in with TronLink at https://tron.discount/buyer-settings and issue a key. It is shown only once. Issuing a new key or revoking the current one invalidates the old key within a few seconds (not instantly: a recently used key is briefly cached).
- Send the key in the header only, never in the query string, and call keyed methods from your server so the key stays secret.
- Units: 1 TRX = 1,000,000 SUN. Prices are in SUN per 1 unit of Energy. Balances and deposit amounts are in TRX.
- Resource and duration: Energy only, rented for exactly 1 hour.
- Times are UTC in ISO 8601. Some values are returned without a trailing Z; treat them as UTC anyway.
- The price, the minimum order, the available Energy and the deposit address change over time. Read them from GET /energy/info right before ordering; never hardcode them.

Endpoints:

**GET /energy/info** [public]

Current platform parameters. Response fields:

- `isSystemActive` (boolean): whether the platform accepts orders right now. When false, do not send deposits or place orders.
- `maximumEnergyAvailable` (integer): Energy currently available for purchase.
- `energyUnitPriceInSun` (integer): price of 1 unit of Energy in SUN.
- `minEnergyOrderAmount` (integer): minimum Energy per order.
- `depositAddress` (string): the platform's TRON address for the deposit flow (see Typical flows).
- `serverTime` (date-time): current server time, UTC.

**GET /energy/order/{depositHash}** [public]

Status of an order created by a TRX transfer to `depositAddress`. `depositHash` is the hash of that transfer: 64 hexadecimal characters.

- 200: `depositHash`, `delegationHash` (null until Energy is delegated), `refundHash` (null unless a refund was sent), `status`, `created`, `executed`, `targetAddress` (address that receives the Energy), `depositAmount` (TRX), `energyAmount`.
- 400: the hash is not 64 hexadecimal characters. The body is the plain text `Invalid deposit hash`, not JSON.
- 404: no order for this hash. Right after the transfer this usually means the deposit has not been picked up yet; keep polling.

**POST /energy/order** [key]

Buys Energy and charges its cost to the prepaid balance; no on-chain transfer per order. Request body (JSON):

- `receiveAddress` (string, required): TRON mainnet address that receives the Energy. The base58check checksum is verified, so a typo is rejected.
- `resourceValue` (integer, required): Energy to buy; at least `minEnergyOrderAmount` and not above the per-order maximum.
- `rentDurationInHours` (integer, optional): only 1 is supported, which is also the default.
- `clientOrderId` (string, optional, up to 64 characters): your own order number, unique per account. Repeating a request with the same value returns the original order and does not charge again, so a lost response can be retried safely. Strongly recommended.

Responses:

- 200: `id` (use it to query the status), `status` (`Created` for a new order), `chargedInSun` (= resourceValue x priceInSun), `priceInSun` (price locked in at acceptance), `balance` (prepaid balance left, TRX). A repeated `clientOrderId` also returns 200 with the original order.
- 400: `{code, message}` with an error code (see Errors).
- 401: the key is missing, malformed, revoked or unknown.
- 503: `{code, message}` with `system_inactive`; nothing was charged, retry later.

**GET /energy/order/api/{id}** [key]

Status of an order placed with POST /energy/order, by its numeric `id`. Orders paid from the balance have no deposit hash.

- 200: `id`, `clientOrderId`, `status`, `receiveAddress`, `resourceValue`, `rentDurationInHours`, `chargedInSun`, `delegationHash` (empty until the Energy is sent; use it to verify delivery on-chain), `created`, `updated`.
- 401: bad key. 404: this account has no order with this id; orders of other accounts are never visible.

**GET /account/recharge-address** [key]

The account's personal TRX recharge address. TRX sent to it is credited to the prepaid balance.

- 200: `address`, `ready`, `nextChangeAllowedAt`. `ready` is false while no address is assigned yet (a brand-new account, or right after a regeneration that did not complete in time); `address` can be null then. `nextChangeAllowedAt` is the earliest time of the next change; a change is allowed now when it is null (the address was never changed) or already in the past.
- 401: bad key.

**POST /account/recharge-address/regenerate** [key]

Replaces the recharge address, at most once per 24 hours. Synchronous: the new address is usually returned within a second.

- 200: `newAddress` (null only if the assignment did not complete in time; then read it later with GET /account/recharge-address), `oldAddress`, `oldAddressActiveUntil`, `nextChangeAllowedAt`.
- The old address keeps accepting deposits for 180 days. Transfers to it after `oldAddressActiveUntil` are NOT credited.
- 401: bad key. 429: `{code, message}` with `address_change_too_soon`; the `Retry-After` header gives the seconds to wait.

Order statuses (both order types use the same string values):

- `Created`: order created, not processed yet.
- `Pending`: payment received, order is being processed.
- `ResourcesDelegated`: final, success. Energy has been delegated to the target address; `delegationHash` is the on-chain proof.
- `RefundRequested`: a refund has been requested, not processed yet.
- `PendingRefund`: the refund is being processed.
- `Refunded`: final, no Energy. For API orders the cost is returned to the prepaid balance; for deposit orders the TRX is sent back to the sender (`refundHash`).
- `Unknown`: a status this API version does not recognize; treat it as not final.

Errors:

- Business errors of POST /energy/order and POST /account/recharge-address/regenerate return JSON `{code, message}`. Branch on `code` only; `message` is human-readable and may change.
- Codes: `insufficient_balance` (not enough prepaid balance, nothing charged; top up and repeat with the same clientOrderId), `invalid_address` (receiveAddress is not a valid TRON address), `invalid_resource_value` (resourceValue below minEnergyOrderAmount or above the per-order maximum), `invalid_rent_duration` (rentDurationInHours is not 1), `invalid_client_order_id` (clientOrderId longer than 64 characters), `invalid_request` (the request cannot be processed; an empty or malformed body normally gets the framework response described below instead), `system_inactive` (503, not accepting orders now), `address_change_too_soon` (429, recharge address changed less than a day ago).
- Not every 400 has a `code`. GET /energy/order/{depositHash} answers an invalid hash with plain text. A missing, empty or malformed JSON body, or a field of the wrong type, is rejected by the framework with a standard 400 validation response (`application/problem+json` with an `errors` object) and no `code` field.
- 401, 404 and 429 are signalled by the HTTP status; do not rely on the format of their bodies, except the 429 code above.

Typical flows:

- Deposit flow, no key: GET /energy/info; check `isSystemActive`; send TRX from your wallet to `depositAddress`, enough to cover at least `minEnergyOrderAmount` at `energyUnitPriceInSun`. Energy for the amount sent is delegated to the sending address, or to another TRON address written in the transaction Note. Then poll GET /energy/order/{hash of your transfer}.
- Prepaid flow, with a key: GET /account/recharge-address; top up the balance by sending TRX to it; POST /energy/order with a unique `clientOrderId`; poll GET /energy/order/api/{id}.
- Polling: an order ends in one of two final statuses, `ResourcesDelegated` or `Refunded`; stop polling on either. Energy usually arrives within about a minute. Poll every few seconds with an overall timeout, and if no final status arrives in time, stop and contact support with the order id or deposit hash.

## Docs

- [API guide](https://tron.discount/api): Human-readable documentation with curl examples for every endpoint
- [OpenAPI specification](https://api.tron.discount/swagger.json): Machine-readable OpenAPI 3 schema; it does not describe the X-Api-Key header, see Basics above
- [Buyer settings](https://tron.discount/buyer-settings): Issue or revoke an API key and see the recharge address; TronLink login required

## Optional

- [TRON DISCOUNT llms.txt](https://tron.discount/llms.txt): Overview of the marketplace for buyers and sellers
- [FAQ](https://tron.discount/faq): Common questions about buying Energy
- [Contact](https://tron.discount/contact): Support by email support@tron.discount or the Telegram bot https://t.me/TronDiscountSupportBot