Skip to main content

Your First API Call in 5 Minutes

Four calls — check your account, price the energy, buy it, confirm delivery. Plain request/response, any language.

Prerequisites

You need an API key to follow along. Create one in the Dashboard if you haven't already.

Every call below is authenticated the same way:

Headers: { "X-API-Key": "ta_your_key_here" }

Step 1 — check your account​

GET https://tronagg.ai/api/v1/account
{
"balance_trx": "120.5",
"deposit_address": "TKVSa...", // send TRX or USDT (TRC-20) here to top up
"wallet_address": "", // your linked login wallet, or "" if none — NOT the deposit target
"usdt_balance": "0.000000", // separate USDT balance (6 decimals)
"usdt_auto_convert": true,
"usdt_cover_shortfall": true
}

If your balance is zero, send TRX or USDT (TRC-20) to deposit_address from any wallet or exchange, or top up via the Dashboard. Purchases are paid in TRX: USDT goes to a separate USDT balance and converts to TRX automatically by default (1% fee, minimum USDT deposit 5 USDT) — see funding in the integration guide.

Step 2 — get a price estimate​

GET https://tronagg.ai/api/v1/estimate?resource_amount=100000&receiver_address=TYourReceiverAddress...
{
"duration": "1h",
"unit_price_sun": "27.000000", // decimal string — parse with a decimal type
"total_price_sun": 2700000,
"total_price_trx": "2.7", // what 100K energy will cost you
"activation_fee_sun": 0, // one-time fee if the receiver isn't activated on TRON yet (included in the total)
"activation_fee_trx": "0",
"min_amount": 64000, // order size limits (null = no limit) — outside them POST /buy returns 400
"max_amount": 1000000 // (illustrative values — read yours from this response)
}

receiver_address is optional, but pass it: if the address has never been activated on TRON, POST /buy adds a one-time activation fee, and only an estimate with the receiver includes it.

Step 3 — buy energy​

POST https://tronagg.ai/api/v1/buy
Headers: { "Idempotency-Key": "any-unique-string" }
{
"receiver_address": "TYourReceiverAddress...", // the address that needs energy
"resource_amount": 100000
}
{
"order_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"status": "PENDING",
"total_price_sun": 2700000,
"total_price_trx": "2.7", // deducted from your balance immediately
"activation_fee_sun": 0, // included in the total when the receiver needed activation
"balance_after_sun": 117800000
}
  • Always send an Idempotency-Key (any unique string, ≤128 chars). POST /buy charges your balance — on a timeout, repeat the call with the same key and you get the original order back instead of a second charge. A concurrent duplicate returns 409 duplicate_request; if that persists, check GET /orders before retrying with a new key. Keys expire after 24 hours. Full contract: Idempotency.
  • An invalid receiver_address returns 400 invalid_address before anything is charged.

Step 4 — check order status​

GET https://tronagg.ai/api/v1/order/{order_id}
{
"id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"status": "COMPLETED", // PENDING → COMPLETED | FAILED
"resource_amount": 100000,
"receiver_address": "TYourReceiverAddress...",
"total_price_trx": "2.7",
"delegation_txids": ["7f00e1..."], // the on-chain delegation once COMPLETED (may be empty for some deliveries)
"error_message": null // set only on FAILED
}
  • Orders typically complete within seconds — poll every 2–3 seconds.
  • FAILED orders are refunded to your balance automatically.
Don't want to poll?

Configure a webhook once and TRONAgg pushes you an order.status_changed event the moment the order is COMPLETED or FAILED.

Full example (Python)​

quickstart.py
import time, uuid
import httpx

client = httpx.Client(
base_url="https://tronagg.ai/api/v1",
headers={"X-API-Key": "ta_your_key_here"},
)

print("Balance:", client.get("/account").json()["balance_trx"], "TRX")

estimate = client.get(
"/estimate",
params={"resource_amount": 100_000, "receiver_address": "TYourReceiverAddress..."},
).json()
print("100K energy costs", estimate["total_price_trx"], "TRX")

order_id = client.post(
"/buy",
headers={"Idempotency-Key": str(uuid.uuid4())},
json={"receiver_address": "TYourReceiverAddress...", "resource_amount": 100_000},
).json()["order_id"]

while (order := client.get(f"/order/{order_id}").json())["status"] not in ("COMPLETED", "FAILED"):
time.sleep(3)

print(order["status"], order.get("delegation_txids"))

Bandwidth can be rented the same way: pass resource_type=BANDWIDTH to GET /estimate and "resource_type": "BANDWIDTH" in the POST /buy body.

Next Steps​