Skip to main content

Guide: deposit → buy → track

From an empty account to delivered Energy in four API calls — top up, confirm, buy, track. Plain request/response, any language, no webhooks needed.

Every call below is authenticated the same way:

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

Step 1 — get your deposit address​

GET https://tronagg.ai/api/v1/account
{
  "balance_trx": "0",
  "deposit_address": "TKVSa...",   // send TRX here to top up
  "wallet_address": ""             // your linked login wallet — NOT the deposit target
}

Send TRX to deposit_address from any wallet or exchange.

Step 2 — confirm the deposit landed​

GET https://tronagg.ai/api/v1/deposits?limit=10
{
  "deposits": [
    {
      "tx_hash": "a1b2c3...",
      "amount_sun": 100000000,
      "amount_trx": "100",
      "status": "confirmed",
      "credited_at": "2026-07-24T10:30:05Z",  // set within seconds — funds spendable NOW
      "verified_at": null,                    // fills in once the block is solidified (reorg-safe)
      "created_at": "2026-07-24T10:30:05Z"
    }
  ],
  "has_more": false
}
  • Poll every ~5 seconds until your deposit shows up with credited_at set.
  • credited_at is enough to proceed — you can buy immediately. verified_at is the final reorg-safe confirmation that follows a few minutes later.

Step 3 — buy energy​

POST https://tronagg.ai/api/v1/buy
Headers: { "Idempotency-Key": "any-unique-string" }
{
  "receiver_address": "TYourReceiverAddress...",
  "resource_amount": 131000
}
{
  "order_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": "PENDING",
  "total_price_sun": 3500000,
  "total_price_trx": "3.5",        // what you were charged
  "balance_after_sun": 96500000    // balance left after the charge
}
  • POST /buy charges your balance, so always send an Idempotency-Key (any unique string, ≤128 chars). On a timeout, repeat the call with the same key — you get the original order back, never a second charge.
  • Amount limits come back on GET /estimate as min_amount / max_amount.

Step 4 — track until delivered​

GET https://tronagg.ai/api/v1/order/{order_id}
{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": "COMPLETED",                    // PENDING → PROCESSING → COMPLETED | FAILED
  "resource_amount": 131000,
  "receiver_address": "TYourReceiverAddress...",
  "total_price_trx": "3.5",
  "delegation_txids": ["7f00e1..."],        // the on-chain delegation, once COMPLETED
  "error_message": null                     // set only on FAILED
}
  • Poll every 2–3 seconds — orders usually settle within seconds.
  • FAILED orders are refunded to your balance automatically; error_message says why.

That's the whole integration.

Full example (Python)​

first_integration.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("Deposit to:", client.get("/account").json()["deposit_address"])

while not any(d["credited_at"] for d in client.get("/deposits").json()["deposits"]):
    time.sleep(5)                                        # wait for the top-up

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

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

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

Optional: push instead of polling​

Register a webhook once and TRONAgg pushes a signed order.status_changed event when the order finishes — no more polling loop:

POST https://tronagg.ai/api/v1/webhooks
{ "name": "orders", "url": "https://your-service.example.com/tronagg/webhook" }

Store the signing_secret from the response — it is shown only once. Envelope, signature verification, and the full catalog: Webhook events.

Next steps​