# TRONAgg TRON Energy API

> Buy TRON Energy for any TRON address from code: a REST API with JSON over HTTPS, an `X-API-Key` header, idempotent purchases and public live pricing. TRONAgg is a TRON Energy provider. Orders are paid from a prepaid TRONAgg balance, and the Energy is delegated to the receiver for 1 hour, usually within seconds.

This file is written for AI agents and coding assistants. It is generated from the TRONAgg OpenAPI spec, so it changes when the API does.

- Last updated: 2026-10-24 (OpenAPI spec version 0.1.0)
- Base URL: `https://tronagg.ai/api/v1`. All paths below are relative to it.
- This file: https://tronagg.ai/tron-energy-api/llms.txt
- Page for people: https://tronagg.ai/tron-energy-api
- How to give this file to an assistant: https://tronagg.ai/tron-energy-api/ai
- OpenAPI 3.1 spec: https://tronagg.ai/openapi.json
- Full reference, webhooks and order history: https://docs.tronagg.ai/api-reference

## Essentials

- Format: JSON request and response bodies over HTTPS.
- Authentication: an `X-API-Key: <key>` header on every endpoint marked "API key" below. Public endpoints need no key.
- Units: integer amounts are in SUN (1 TRX = 1,000,000 SUN). Fields ending in `_trx`, `unit_price_sun` and the price fields of the public pricing endpoints are decimal strings: parse them with a decimal type, never a float.
- Resource: Energy only (`resource_type` is always `ENERGY`), delegated for 1 hour (`duration` is always `1h`).
- Order statuses are UPPERCASE. Timestamps are ISO 8601 in UTC.
- TRON addresses are base58, start with `T` and have 34 characters.

## Authentication and key safety

- The user creates a key in the TRONAgg workspace under API Keys (https://tronagg.ai/workspace/api-keys). Keys start with `ta_`.
- Send the key in the `X-API-Key` header only. Never put it in a URL, a query string or a request body.
- Read the key from the environment (`TRONAGG_API_KEY`) or a secret store. Never log, print, echo, commit or repeat the key, and never paste it into a chat or into code you show the user.
- A key can spend the account's balance: treat it like a password.
- A key can be limited to IP addresses or CIDR ranges; a request from anywhere else gets `403` with `ip_not_allowed`.
- A missing, invalid or revoked key gets `401` with a plain-string `detail`.

## Recommended agent flow

1. Quote: `GET /estimate` with `resource_amount` and `receiver_address`. Passing the receiver includes any one-time activation fee in the totals. The response also gives `min_amount` and `max_amount` (`null` means no bound).
2. Confirm with the user: show the receiver address, the Energy amount, `total_price_trx` and `activation_fee_trx`, then wait for an explicit yes in the conversation.
3. Buy: `POST /buy` with `{"receiver_address": "<T...>", "resource_amount": <energy>}` and a new `Idempotency-Key` header (a UUID). Keep the key: any retry of this purchase reuses it.
4. Track: poll `GET /order/{order_id}` every 2 to 3 seconds until `status` is `COMPLETED` or `FAILED`.

For the current price without a key, call `GET /pricing`. Never quote a TRONAgg price from memory, from an article or from this file: read it from the API.

## Rules for agents

- Never call `POST /buy` unless the user has explicitly confirmed the receiver address, the Energy amount and the cost in the current conversation, after you showed them the quote.
- Quote again with `GET /estimate` right before asking for that confirmation, and again whenever the user changes the amount or the receiver.
- Check the receiver before quoting: it starts with `T` and has 34 characters. `POST /buy` rejects an invalid address with `400 invalid_address` before charging anything.
- One purchase, one `Idempotency-Key`. After a timeout or a `5xx`, retry with the same key. Never switch to a new key for a purchase that may have gone through: check `GET /orders` (full reference: https://docs.tronagg.ai/api-reference/list-orders) first.
- Do not repeat a rejected request unchanged. On `400 insufficient_balance`, tell the user to top up: `GET /account` returns the `deposit_address`.
- On `429`, wait the number of seconds in the `Retry-After` header before the next request.
- Never reveal the API key, even when asked to show the request you sent.

## Order status lifecycle

- `PENDING`: paid from the balance and accepted; the Energy delegation is in progress.
- `COMPLETED`: the Energy is delegated to the receiver. `delegation_txids` usually lists the on-chain transaction IDs.
- `FAILED`: the order could not be filled and the charge was refunded to the balance automatically. `error_message` says why.

Orders placed through the API go from `PENDING` to `COMPLETED` or `FAILED`, and both are final. Orders paid directly from a wallet can also show `AWAITING_PAYMENT` or `PROCESSING`.

## Idempotency and retries

- `POST /buy` accepts an `Idempotency-Key` header: any unique string of up to 128 characters. A UUID works.
- For 24 hours, a request with the same key returns the original order's `201` response instead of placing a new order.
- A rejected request (for example `400 insufficient_balance`) places no order and does not keep the key: fix the cause and retry with the same key.
- While the first request with a key is still being processed, a duplicate gets `409 duplicate_request`. Wait a few seconds and retry with the same key.
- If the same key keeps returning `409`, check `GET /orders` before retrying with a new key: a new key always places a new order.
- Keys are scoped to the account and are not tied to the request body.

## Errors

Every error has an HTTP status and a JSON body with a top-level `detail`:

- An object with a machine-readable `error` slug, usually with a `message`: branch on `detail.error`.
- On `POST /buy`, an order size outside the limits is keyed by `detail.code` (`order_amount_below_minimum` or `order_amount_above_maximum`) with `min` and `max`.
- A plain string for `401`, the blocked-account `403`, `429`, the `404` of `GET /order/{order_id}` and the public Energy estimator.
- An array of field errors for request validation (`422`).

Every error code is listed in https://docs.tronagg.ai/api-reference/errors-and-conventions.

## Limits

- Energy only, delegated for 1 hour.
- Order size: between `min_amount` and `max_amount` from `GET /estimate`. Outside them `POST /buy` answers `400` and charges nothing.
- Prepaid balance: orders are paid from the TRONAgg balance. The user tops it up by sending TRX to the `deposit_address` from `GET /account`.
- New addresses: a receiver that is not yet activated on TRON adds a one-time activation fee, included in the totals.
- Rate limit: 1,000 requests per minute per account, shared by all of its keys. Past that the API answers `429` with a `Retry-After` header.
- The Energy estimator is limited to 10 requests per minute per IP.

## Endpoints

The purchase flow first, then the public endpoints that need no key.

### GET /estimate

Get Estimate. Auth: API key (`X-API-Key`). Reference: https://docs.tronagg.ai/api-reference/get-estimate

Returns TRONAgg's current price for `resource_amount` Energy delivered for 1 hour — what `POST /buy` would charge your balance right now (your VIP price if you have one).

**Parameters:**
- `resource_amount` — amount of Energy to buy (in Energy units, not TRX)
- `receiver_address` (optional) — the address that will receive the Energy. Pass it to include the one-time account-activation fee when the address is not yet activated on TRON. Without it the quote leaves that fee out, while `POST /buy` still charges it.

The response includes the unit price in SUN, the total cost, any activation fee, and the order-size limits (`min_amount` / `max_amount`). Use it to preview costs before committing to a purchase.

Parameters:

- `resource_amount` (query, integer, required, > 0): Amount of Energy to quote, in Energy units (not TRX). `POST /buy` accepts amounts between `min_amount` and `max_amount` from this response.
- `receiver_address` (query, string, optional): Address that will receive the Energy. When it is not yet activated on TRON, the one-time activation fee is added to the totals and returned in `activation_fee_sun`.

Response `200` fields:

- `duration` (string): Rental duration — always `1h`.
- `unit_price_sun` (string): Price per Energy unit in SUN, as a decimal string. It can be fractional — parse it with a decimal type, not as an integer.
- `total_price_sun` (integer): Total your balance would be charged, in SUN — includes `activation_fee_sun`.
- `total_price_trx` (string): The same total in TRX (decimal string).
- `activation_fee_sun` (integer): One-time account-activation fee in SUN, included in the totals. Non-zero only when you pass a `receiver_address` that is not yet activated on TRON.
- `activation_fee_trx` (string): The activation fee in TRX (decimal string); `"0"` when there is none.
- `min_amount` (integer, nullable): Smallest `resource_amount` `POST /buy` accepts; `null` = no lower bound. Outside the bounds `POST /buy` returns `400`.
- `max_amount` (integer, nullable): Largest `resource_amount` `POST /buy` accepts; `null` = no upper bound. Outside the bounds `POST /buy` returns `400`.
- `energy_pass_energy` (integer): Energy units your Energy Pass would cover right now; the totals are what your balance pays for the rest. `0` without an active Energy Pass.

Status codes:

- `200`: OK
- `400`: `unsupported_resource` or `invalid_duration` — only Energy for a 1-hour duration is offered.
- `401`: The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.
- `403`: The account is blocked (plain-string `detail`: `Account is blocked`), or `ip_not_allowed` — the request's source IP is outside this key's IP allowlist.
- `422`: Request validation failed (e.g. `resource_amount` missing or not above 0) — `detail` is an array of field errors.
- `429`: `Rate limit exceeded` — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.
- `503`: `service_unavailable` — Energy purchasing is temporarily unavailable.

Example:

```bash
curl -s -G https://tronagg.ai/api/v1/estimate \
  -d resource_amount=65000 \
  -d receiver_address=TYourReceiverAddress \
  -H "X-API-Key: $TRONAGG_API_KEY"
```

### POST /buy

Buy Energy. Auth: API key (`X-API-Key`). Reference: https://docs.tronagg.ai/api-reference/buy-energy

Purchase Energy for a receiver address. The cost is deducted from your account balance immediately — including a one-time account-activation fee (`activation_fee_sun`) when the receiver is not yet activated on TRON. The order starts as `PENDING`; Energy is typically delegated within seconds. Use the **Get Order** endpoint to poll for completion.

`receiver_address` is checked before anything is charged: an invalid address returns `400 invalid_address`.

Send an `Idempotency-Key` header so that a retry after a timeout returns the original order instead of placing a second one — see [Idempotency](https://docs.tronagg.ai/api-reference/errors-and-conventions#idempotency).

Parameters:

- `Idempotency-Key` (header, string, optional, max 128 characters): Any unique string of up to 128 characters (a UUID works well). A retry with the same key within 24 hours returns the original order's response instead of placing a new order.

Request body (`application/json`):

- `receiver_address` (string, required): TRON address that will receive the Energy delegation (base58, starts with `T`, 34 characters). Checked before anything is charged.
- `resource_amount` (integer, required, > 0): Amount of Energy to buy, within `min_amount` / `max_amount` from `GET /estimate`.

Response `201` fields:

- `order_id` (string (uuid)): Order UUID — pass it to `GET /order/{order_id}`.
- `status` (string): Order status — `PENDING` for a newly placed order.
- `total_price_sun` (integer): Total deducted from your balance, in SUN — includes `activation_fee_sun`.
- `total_price_trx` (string): Total deducted from your balance, in TRX (decimal string).
- `activation_fee_sun` (integer): One-time account-activation fee in SUN, included in the total. Non-zero only when the receiver was not yet activated on TRON.
- `balance_after_sun` (integer): Account balance after purchase in SUN
- `energy_pass_energy` (integer): Energy units of this order paid by your Energy Pass; `total_price_sun` covers the rest. If the order fails, these units return to your Energy Pass allowance rather than to your balance. `0` without an Energy Pass.

Status codes:

- `201`: Created
- `400`: Purchase rejected; nothing was charged:
  - `insufficient_balance` — your balance is below the order total (no `message`; carries `current_balance` and `required_amount` in SUN)
  - `order_amount_below_minimum` / `order_amount_above_maximum` — keyed by `code`, with `min` / `max`
  - `invalid_address` — `receiver_address` is not a valid TRON address
  - `invalid_idempotency_key` — `Idempotency-Key` longer than 128 characters
  - `unsupported_resource` — only Energy is offered
- `401`: The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.
- `403`: The account is blocked (plain-string `detail`: `Account is blocked`), or `ip_not_allowed` — the request's source IP is outside this key's IP allowlist. Or `reseller_suspended` (no `message`) — purchasing is suspended for your account; contact support.
- `409`: `duplicate_request` — a request with the same `Idempotency-Key` is still being processed. Retry with the same key after a few seconds. If it keeps returning 409, check `GET /orders` before retrying with a new key.
- `422`: Request body validation failed (e.g. a missing field, `resource_amount` not above 0, or a `duration` other than `1h`) — `detail` is an array of field errors.
- `429`: `Rate limit exceeded` — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.
- `500`: `internal_error` — unexpected error; the order was not placed. Retry later.
- `503`: `service_unavailable` — Energy purchasing is temporarily unavailable; or `reseller_activation_balance_low` (no `message`) — purchasing is temporarily unavailable for your account. Retry later.

Example:

```bash
curl -s -X POST https://tronagg.ai/api/v1/buy \
  -H "X-API-Key: $TRONAGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "receiver_address": "TYourReceiverAddress",
    "resource_amount": 65000
  }'
```

### GET /order/{order_id}

Get Order. Auth: API key (`X-API-Key`). Reference: https://docs.tronagg.ai/api-reference/get-order

Retrieve details for a specific order by its UUID. Use this to track order progress after creating a purchase.

**Order statuses** (always upper-case):
- `PENDING` — order placed and paid; Energy delegation in progress
- `COMPLETED` — Energy delegated (`delegation_txids` usually lists the on-chain delegation transaction IDs)
- `FAILED` — the order could not be fulfilled and was refunded automatically (see `error_message`)

Orders placed through the API go `PENDING` → `COMPLETED` or `FAILED`. Orders paid directly from a wallet may also show `AWAITING_PAYMENT` or `PROCESSING`.

Parameters:

- `order_id` (path, string (uuid), required): Order UUID: the `order_id` that `POST /buy` returned.

Response `200` fields:

- `id` (string (uuid)): Order UUID.
- `status` (string): Order status, upper-case: `PENDING`, `COMPLETED` or `FAILED` for orders placed through the API; orders paid directly from a wallet may also show `AWAITING_PAYMENT` or `PROCESSING`.
- `resource_type` (string): Always `ENERGY`.
- `resource_amount` (integer): Amount of Energy ordered, in Energy units.
- `duration_sec` (integer): Delegation duration in seconds (`3600` = 1 hour).
- `total_price_sun` (integer): Total charged in SUN, including `activation_fee_sun`.
- `total_price_trx` (string): Total charged in TRX (decimal string).
- `activation_fee_sun` (integer): One-time account-activation fee in SUN included in the total; `0` when the receiver was already activated.
- `receiver_address` (string): Address the Energy is delegated to.
- `provider_name` (string): Always `TRONAgg`. Kept for backward compatibility.
- `provider_slug` (string): Always `tronagg`. Kept for backward compatibility.
- `created_at` (string (date-time)): When the order was placed (ISO 8601, UTC).
- `completed_at` (string (date-time), nullable): When the order reached a final status, `COMPLETED` or `FAILED` (ISO 8601, UTC); `null` until then.
- `error_message` (string, nullable): Why the order failed — set only when `status` is `FAILED`.
- `delegation_txids` (array of string): On-chain delegation transaction IDs. Usually filled once the order is `COMPLETED`, but may be empty for some deliveries.

Status codes:

- `200`: OK
- `401`: The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.
- `403`: The account is blocked (plain-string `detail`: `Account is blocked`), or `ip_not_allowed` — the request's source IP is outside this key's IP allowlist.
- `404`: `Order not found` — no such order, or it is not yours. `detail` is a plain string.
- `422`: `order_id` is not a valid UUID — `detail` is an array of field errors.
- `429`: `Rate limit exceeded` — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.

Example:

```bash
curl -s "https://tronagg.ai/api/v1/order/$ORDER_ID" \
  -H "X-API-Key: $TRONAGG_API_KEY"
```

### GET /account

Get Account. Auth: API key (`X-API-Key`). Reference: https://docs.tronagg.ai/api-reference/get-account

Returns your account information: balance in TRX, the deposit address for topping up, and your linked login wallet address (an empty string if no wallet is linked).

Response `200` fields:

- `balance_trx` (string): Account balance in TRX
- `deposit_address` (string): TRON address to send TRX deposits to
- `wallet_address` (string): Your linked TRON login wallet address; an empty string if no wallet is linked. Not a deposit target — send TRX to `deposit_address`.

Status codes:

- `200`: OK
- `401`: The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.
- `403`: The account is blocked (plain-string `detail`: `Account is blocked`), or `ip_not_allowed` — the request's source IP is outside this key's IP allowlist.
- `429`: `Rate limit exceeded` — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.

Example:

```bash
curl -s https://tronagg.ai/api/v1/account \
  -H "X-API-Key: $TRONAGG_API_KEY"
```

### GET /pricing

Current Energy Price. Auth: public, no key. Reference: https://docs.tronagg.ai/api-reference/get-pricing

Our **live Energy price** — the same numbers the [tronagg.ai/pricing](https://tronagg.ai/pricing) page shows, as JSON. No API key required.

The snapshot carries our current price per Energy unit (in SUN), the anonymous market average across the public providers we track, how far below that average we sit, and the cost of the standard reference orders (65k Energy = 1 USDT transfer, 131k = 2) in TRX and ≈ USD.

**Good to know**
- Prices refresh about every minute; responses are cached server-side for ~60s
- `below_market_percent` is `null` whenever we are not actually below the market average — the field never asserts a false claim
- The market average is an anonymous aggregate — individual provider prices are never exposed

Response `200` fields:

- `updated_at` (string (date-time)): When our price was last updated (UTC).
- `currency` (object): Currency conversion context for the USD figures.
- `currency.trx_usd` (string, optional, nullable): Current TRX/USD rate, or `null` when unavailable.
- `energy` (object): Our current Energy price and how it sits against the market average.
- `energy.price_sun` (string): Our current price per Energy unit, in SUN (1 TRX = 1,000,000 SUN).
- `energy.market_avg_price_sun` (string, optional, nullable): Market average price per Energy unit, in SUN — an anonymous mean across the public providers we track, never an individual provider's price. `null` when no market data is available.
- `energy.below_market_percent` (string, optional, nullable): How far below the market average our price sits, in percent. `null` whenever we are not below the market average.
- `energy.market_provider_count` (integer): How many public providers we track for the market average. Providers without a current price are left out of the average itself.
- `energy.reference_orders` (array of object): Cost of the standard reference orders (65k Energy = 1 USDT transfer, 131k = 2) at our current price.
- `energy.reference_orders[].energy` (integer): Energy amount of the reference order.
- `energy.reference_orders[].usdt_transfers` (integer): How many typical USDT transfers that Energy covers.
- `energy.reference_orders[].trx` (string): Cost at our current price, in TRX.
- `energy.reference_orders[].usd` (string, optional, nullable): Approximate cost in USD, or `null` when the TRX/USD rate is unavailable.

Status codes:

- `200`: Current pricing snapshot

Example:

```bash
curl -s https://tronagg.ai/api/v1/pricing
```

### GET /pricing/history

Energy Price History. Auth: public, no key. Reference: https://docs.tronagg.ai/api-reference/get-pricing-history

Our Energy price vs the anonymous market average **over time**. No API key required.

Pass `hours` for an hourly series (up to 168h / 7 days) or `days` for a daily series (up to 365). With neither, the series defaults to the **last 24 hours, hourly**. `hours` wins when both are given.

Each point carries our price (SUN), the market average (SUN), and our price for a 65,000-Energy order — one USDT transfer — in TRX.

**How buckets work**
- Buckets are UTC-aligned. The series covers the last N hours or days and may include the current, partial bucket, so it can hold up to N+1 points
- Each point is the last price recorded in its bucket (for `days`, the day's closing hourly rate), not an average over the bucket
- Buckets without a recorded price of ours are left out

**Good to know**
- Responses are cached server-side for ~60s
- Buckets with no recorded market data have `market_avg_price_sun: null`

Parameters:

- `hours` (query, integer, optional, 1 to 168): Hourly window, up to 168h (7d). Takes precedence over `days`.
- `days` (query, integer, optional, 1 to 365): Daily window, up to 365d. Ignored if `hours` is set.

Response `200` fields:

- `granularity` ("hourly" | "daily"): Bucket size of the series: `hourly` (via `hours`) or `daily` (via `days`).
- `duration` (string): Rental duration the series is priced at (currently always `1h`).
- `history` (array of object): Series points, oldest first.
- `history[].timestamp` (string (date-time)): Bucket start (UTC).
- `history[].our_price_sun` (string): Our price per Energy unit in SUN — the last price recorded in this bucket.
- `history[].market_avg_price_sun` (string, optional, nullable): Anonymous market average in SUN: the mean of each tracked public provider's last price recorded in this bucket. `null` when no market data was recorded.
- `history[].trx_65k` (string): Our price for a 65,000-Energy order (one USDT transfer) at `our_price_sun`, in TRX.

Status codes:

- `200`: Price history series
- `422`: Validation error — `hours` or `days` out of range

Example:

```bash
curl -s -G https://tronagg.ai/api/v1/pricing/history \
  -d hours=24
```

### GET /pricing/auto-energy

AutoEnergy Plan Pricing (Public). Auth: public, no key. Reference: https://docs.tronagg.ai/api-reference/get-pricing-autoenergy

Public pricing for the default [AutoEnergy](https://docs.tronagg.ai/api-reference/autoenergy-subscribe) plan — the activation fee, daily subscription fee, per-transfer charges, and minimum-usage fee, each in both SUN and TRX. No API key required.

Same shape as [`GET /autoenergy/pricing`](https://docs.tronagg.ai/api-reference/autoenergy-pricing), but always shows the default plan, which may differ from a tariff assigned to your account. Responses are cached server-side for ~60s.

Response `200` fields:

- `id` (string (uuid)): Plan UUID.
- `name` (string): Plan name, e.g. `Basic`.
- `activation_fee_sun` (integer): One-time activation fee, in SUN.
- `activation_fee_trx` (string): One-time activation fee, in TRX.
- `daily_sub_sun` (integer): Daily subscription fee, in SUN. Charged every 24h, first 24h after activation.
- `daily_sub_trx` (string): Daily subscription fee, in TRX. Charged every 24h, first 24h after activation.
- `unit_price_65k_sun` (integer): Per 65k-Energy transfer, in SUN.
- `unit_price_65k_trx` (string): Per 65k-Energy transfer, in TRX.
- `unit_price_131k_sun` (integer): Per 131k-Energy transfer, in SUN.
- `unit_price_131k_trx` (string): Per 131k-Energy transfer, in TRX.
- `min_daily_tx` (integer, nullable): Minimum transfers per 24-hour billing cycle; fewer triggers the minimum-usage fee. Null when the plan has no minimum.
- `penalty_sun` (integer): Minimum-usage fee, in SUN, charged once per completed 24h cycle with fewer than `min_daily_tx` transfers (0 when none).
- `penalty_trx` (string): Minimum-usage fee, in TRX, charged once per completed 24h cycle with fewer than `min_daily_tx` transfers (`"0"` when none).

Status codes:

- `200`: Default AutoEnergy plan pricing

Example:

```bash
curl -s https://tronagg.ai/api/v1/pricing/auto-energy
```

### GET /calculator/estimate-energy

Energy Estimator. Auth: public, no key. Reference: https://docs.tronagg.ai/api-reference/energy-estimator

Find out **exactly how much energy** a TRC20 transfer will consume before you buy a rental — no guessing, no overpaying. TRONAgg simulates the `transfer(address,uint256)` call on-chain against live network state and returns the precise energy the transaction would burn, plus the equivalent TRX cost at the current `getEnergyFee` rate.

Defaults to **USDT**; pass `contract_address` to estimate any other TRC20 token.

**Why use it**
- Size your energy rental precisely instead of relying on rough averages
- Compare energy cost across different TRC20 tokens
- Detect first-time receivers (a brand-new recipient costs ~2x more energy)

**Good to know**
- Energy prices move in real time — round the returned value **up** when placing an order
- Rate limits: 10 req/min per IP, shared by both estimator endpoints (`429`), and 60 req/min shared to the TRON node (`503`)

For a quick USDT-only check, see the [USDT shortcut](https://docs.tronagg.ai/api-reference/estimate-energy-usdt) which takes the two addresses straight in the URL.

Parameters:

- `from_address` (query, string, required): Sender TRON address (T..., 34 chars)
- `to_address` (query, string, required): Receiver TRON address (T..., 34 chars)
- `contract_address` (query, string, optional, default TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t): TRC20 contract address. Defaults to USDT.

Response `200` fields:

- `from_address` (string): Sender TRON address
- `contract_address` (string): TRC20 contract address (USDT unless overridden)
- `to_address` (string): Receiver TRON address
- `energy_used` (integer): Exact energy units the transfer would consume
- `fee` (number): TRX burned at the current network rate (energy_used x energy_fee / 1,000,000)

Status codes:

- `200`: OK
- `422`: Invalid TRON address — `detail` is a string, e.g. `Invalid TRON address format: …`. A missing required parameter returns a `detail` array of field errors instead.
- `429`: Rate limit exceeded — more than 10 requests/min from your IP, counted across both estimator endpoints
- `502`: The TRON node could not simulate the transfer (contract error, invalid transaction, etc.)
- `503`: The global outbound rate limit to the TRON node is exhausted — retry shortly

Example:

```bash
curl -s -G https://tronagg.ai/api/v1/calculator/estimate-energy \
  -d from_address=TYourSenderAddress \
  -d to_address=TYourReceiverAddress
```

## Full example: quote, buy, track

Python (requests):

```python
import os, time, uuid
import requests

BASE_URL = "https://tronagg.ai/api/v1"
HEADERS = {"X-API-Key": os.environ["TRONAGG_API_KEY"]}
receiver = "TYourReceiverAddress"

quote = requests.get(
    f"{BASE_URL}/estimate",
    headers=HEADERS,
    params={"resource_amount": 65000, "receiver_address": receiver},
).json()
print("Total:", quote["total_price_trx"], "TRX")

res = requests.post(
    f"{BASE_URL}/buy",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={"receiver_address": receiver, "resource_amount": 65000},
)
if res.status_code != 201:
    raise RuntimeError(res.json()["detail"])
order_id = res.json()["order_id"]

while True:
    time.sleep(3)
    order = requests.get(f"{BASE_URL}/order/{order_id}", headers=HEADERS).json()
    if order["status"] in ("COMPLETED", "FAILED"):
        break
print(order["status"], order["delegation_txids"])
```

JavaScript (Node.js 18 or later):

```js
import { randomUUID } from "node:crypto";
import { setTimeout as sleep } from "node:timers/promises";

const BASE_URL = "https://tronagg.ai/api/v1";
const headers = { "X-API-Key": process.env.TRONAGG_API_KEY };
const receiver = "TYourReceiverAddress";

const quote = await fetch(
  `${BASE_URL}/estimate?resource_amount=65000&receiver_address=${receiver}`,
  { headers },
).then((res) => res.json());
console.log("Total:", quote.total_price_trx, "TRX");

const res = await fetch(`${BASE_URL}/buy`, {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({ receiver_address: receiver, resource_amount: 65000 }),
});
const purchase = await res.json();
if (res.status !== 201) throw new Error(JSON.stringify(purchase.detail));

let order;
do {
  await sleep(3000);
  order = await fetch(`${BASE_URL}/order/${purchase.order_id}`, { headers })
    .then((r) => r.json());
} while (!["COMPLETED", "FAILED"].includes(order.status));
console.log(order.status, order.delegation_txids);
```

The same flow in cURL, Go and PHP: https://tronagg.ai/tron-energy-api#quickstart

## MCP alternative

TRONAgg also runs a remote MCP server at `https://mcp.tronagg.ai/mcp`. Add it to Claude, ChatGPT, Cursor or any MCP client to use TRONAgg as tools instead of writing HTTP calls. The price, quote and Energy estimate tools work without a key; buying needs the API key in an `X-API-Key` header on the connector and an explicit confirmation of the amount, receiver and cost. Setup for each assistant: https://tronagg.ai/agents