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 — 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
{
  "total_price_sun": 2700000,
  "total_price_trx": "2.7",        // what 100K energy will cost you
  "min_amount": 20000,             // order size limits — outside them POST /buy returns 400
  "max_amount": 100000000
}

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
  "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, never a second charge. A concurrent duplicate returns 409 duplicate_request; keys expire after 24 hours. Full contract: Idempotency.

Step 4 — check order status​

GET https://tronagg.ai/api/v1/order/{order_id}
{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": "COMPLETED",                  // PENDING → PROCESSING → COMPLETED | FAILED
  "resource_amount": 100000,
  "receiver_address": "TYourReceiverAddress...",
  "total_price_trx": "2.7",
  "delegation_txids": ["7f00e1..."],      // the on-chain delegation, once COMPLETED
  "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}).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"))

Next Steps​