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 here to top up
  "wallet_address": ""             // your linked login wallet, or "" if none — NOT the deposit target
}

If your balance is zero, send TRX to deposit_address from any wallet or exchange, or top up via the Dashboard.

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"))

Rent Bandwidth for one hour​

The same endpoints also rent Bandwidth for 1 hour. Energy remains the default when resource_type is omitted. For Bandwidth, set it on both the quote and the purchase. resource_amount counts Bandwidth units, not TRX.

With TRONAGG_API_KEY and RECEIVER_ADDRESS set in your environment, request a quote first:

curl --fail-with-body \
  -H "X-API-Key: $TRONAGG_API_KEY" \
  "https://tronagg.ai/api/v1/estimate?resource_type=BANDWIDTH&resource_amount=1000&receiver_address=$RECEIVER_ADDRESS"

Check the returned min_amount/max_amount and total before buying: 1,000 units is an example, not a guaranteed minimum. The receiver-aware quote includes activation when needed. If Bandwidth pricing is unavailable, do not proceed with an Energy quote.

To place that order, create an idempotency key once and keep it for any retries of this purchase:

IDEMPOTENCY_KEY="$(uuidgen)"
curl --fail-with-body -X POST \
  -H "X-API-Key: $TRONAGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d "{\"receiver_address\":\"$RECEIVER_ADDRESS\",\"resource_amount\":1000,\"resource_type\":\"BANDWIDTH\"}" \
  "https://tronagg.ai/api/v1/buy"

The purchase charges your TRONAgg balance. Track the returned order_id using Step 4. Bandwidth purchases are not available to reseller end-user accounts.

The hourly schedule is public: GET https://tronagg.ai/api/v1/pricing/schedule?resource_type=BANDWIDTH needs no API key. Its weekday and weekend arrays contain 24 SUN-per-Bandwidth rates each, indexed by hour in the returned timezone; both arrays are empty when unpublished. Use /estimate for the current order limits and receiver-specific total.

Next Steps​