Your First API Call in 5 Minutes

This guide walks you through a complete energy purchase — from checking your balance to confirming delegation — using Python.

Prerequisites

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

Step 1: Check Your Account

Start by checking your balance and deposit address.

import requests

API_KEY = "ta_your_key_here"
BASE_URL = "https://tronagg.ai/api/v1"

response = requests.get(
    f"{BASE_URL}/account",
    headers={"X-API-Key": API_KEY}
)
account = response.json()
print(f"Balance: {account['balance_trx']} TRX")
print(f"Deposit to: {account['deposit_address']}")

If your balance is zero, deposit TRX to the deposit_address shown in the response, or via the Dashboard deposit page.

Step 2: Get a Price Estimate

Check how much energy will cost before committing to a purchase.

response = requests.get(
    f"{BASE_URL}/estimate",
    headers={"X-API-Key": API_KEY},
    params={"resource_amount": 100000, "duration": "1h"}
)
estimate = response.json()
print(f"100K energy costs {estimate['total_price_trx']} TRX")

Step 3: Buy Energy

Purchase energy by specifying the receiver address and amount. The cost is deducted from your balance immediately.

response = requests.post(
    f"{BASE_URL}/buy",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "receiver_address": "TYourReceiverAddress...",
        "resource_amount": 100000,
        "duration": "1h",
    }
)
purchase = response.json()
print(f"Order: {purchase['order_id']}, Status: {purchase['status']}")

tip

Replace TYourReceiverAddress... with the actual TRON address that needs energy. This is often the address of your smart contract caller.

Safe retries with Idempotency-Key

POST /buy charges your balance, so blindly retrying it after a network timeout risks a duplicate order. To retry safely, send an Idempotency-Key header — any unique string up to 128 characters (a UUID per logical order works well):

import uuid

response = requests.post(
    f"{BASE_URL}/buy",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),  # store it; reuse on retry
    },
    json={
        "receiver_address": "TYourReceiverAddress...",
        "resource_amount": 100000,
        "duration": "1h",
    },
    timeout=30,
)

How it behaves:

• Retry with the same key after a timeout or dropped connection: if the original request succeeded, you get the original response back — no second charge, no duplicate order.
• Two concurrent requests with the same key: the second receives 409 duplicate_request while the first is still processing.
• Failed requests release the key: if the purchase was rejected (e.g. insufficient balance), you may retry with the same key after fixing the cause.
• Keys are scoped to your account and expire after 24 hours.

Recommended client pattern

On timeout, don't treat the order as lost: retry POST /buy with the same Idempotency-Key (or check GET /order/{id} if you already have the ID). Use a read timeout of at least 30 seconds.

Step 4: Check Order Status

Orders typically complete within seconds. Use the order ID from the purchase response to check its status.

order_id = purchase["order_id"]

response = requests.get(
    f"{BASE_URL}/order/{order_id}",
    headers={"X-API-Key": API_KEY}
)
order = response.json()
print(f"Status: {order['status']}")

if order["status"] == "completed":
    print(f"Energy delegated! TXs: {order['delegation_txids']}")

Possible statuses: pending → completed or failed. For production-ready polling with timeouts, see Code Examples.

Next Steps

• Authentication -- key management, rotation, and security best practices
• Code Examples -- the same workflow in JavaScript, plus error handling patterns
• API Methods -- full request/response schemas for every endpoint