Skip to main content

Guide: AutoEnergy for a fleet

Subscribe an address once and AutoEnergy keeps it Energy-ready — every covered transfer is handled and billed automatically. You never manage delegations, timing, or top-ups. This guide runs it across a group of addresses.

All calls are authenticated with your API key:

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

Subscribe an address​

POST https://tronagg.ai/api/v1/autoenergy/subscriptions
{
  "address": "TAddressOne...",   // required — the only mandatory field
  "idle_hours": 48,              // optional: auto-close after idle 24 / 48 / 72h (default 24)
  "quota_max_tx": 1000           // optional: auto-close after N covered transfers (null = no cap)
}
{
  "address": "TAddressOne...",
  "status": "active",            // briefly "pending_activation" right after subscribing
  "plan": {
    "activation_fee_trx": "3",   // one-off, charged now
    "daily_sub_trx": "3",        // charged daily while active
    "unit_price_65k_trx": "1.7", // per covered transfer, by energy class
    "unit_price_131k_trx": "2.1"
  },
  "tx_used_total": 0,
  "quota_max_tx": 1000,
  "idle_hours": 48,
  "expire_at": null,
  "activated_at": "2026-07-24T10:30:05Z"
}

Repeat per address. The loop is safe to re-run — two 409 codes tell you what's already there:

409 codeMeansDo
address_busyA live subscription already covers the address.Nothing — already done.
address_existsA closed subscription exists.POST .../{address}/reactivate

Watch the fleet​

One call returns every subscription with live counters — that's your whole-fleet dashboard, re-run it on any schedule:

GET https://tronagg.ai/api/v1/autoenergy/subscriptions
[
  {
    "address": "TAddressOne...",
    "status": "active",
    "tx_used_total": 5,               // transfers covered & billed so far
    "quota_max_tx": 1000,
    "last_activity_at": "2026-07-24T12:01:44Z",
    "closed_at": null,
    "close_reason": null
  },
  {
    "address": "TAddressTwo...",
    "status": "closed",
    "tx_used_total": 42,
    "close_reason": "quota"           // quota | expired | idle | insufficient_balance | manual | …
  }
]
  • GET .../subscriptions/{address} returns the same object for one address.
  • Treat close_reason as an open set — handle unknown values gracefully.

Audit usage and billing​

Per-address itemization:

GET https://tronagg.ai/api/v1/autoenergy/subscriptions/{address}/usage
[
  {
    "energy_class": "131k",           // energy covered for that transfer: 65k or 131k
    "used_tx_id": "7f00e1...",        // the transfer that consumed it
    "billed_sun": 2100000,
    "billed_trx": "2.1",
    "occurred_at": "2026-07-24T12:01:44Z"
  }
]
GET https://tronagg.ai/api/v1/autoenergy/subscriptions/{address}/billing
[
  { "kind": "autoenergy_activate", "amount_trx": "3",   "at": "2026-07-24T10:30:05Z" },
  { "kind": "autoenergy_daily",    "amount_trx": "3",   "at": "2026-07-25T00:00:01Z" },
  { "kind": "autoenergy_unit",     "amount_trx": "2.1", "at": "2026-07-24T12:01:44Z" }
]

The same autoenergy_* charges appear in your account-wide ledger via GET /transactions.

Close and reactivate​

POST https://tronagg.ai/api/v1/autoenergy/subscriptions/{address}/close
POST https://tronagg.ai/api/v1/autoenergy/subscriptions/{address}/reactivate
  • close stops coverage immediately (close_reason: "manual"); nothing further is covered or billed.
  • reactivate resumes a closed subscription and resets tx_used_total.

Full example (Python)​

fleet.py
import httpx

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

FLEET = ["TAddressOne...", "TAddressTwo...", "TAddressThree..."]

for address in FLEET:                       # subscribe, safe to re-run
    resp = client.post("/autoenergy/subscriptions",
                       json={"address": address, "idle_hours": 48, "quota_max_tx": 1000})
    if resp.status_code == 409 and resp.json()["detail"]["error"] == "address_exists":
        resp = client.post(f"/autoenergy/subscriptions/{address}/reactivate")

for s in client.get("/autoenergy/subscriptions").json():   # fleet dashboard
    cap = s["quota_max_tx"] or "∞"
    print(f"{s['address']}: {s['status']} — {s['tx_used_total']}/{cap} transfers")

Optional: real-time events​

If polling the inventory isn't fresh enough, register a webhook and get pushed:

Everything above keeps working without them.

Next steps​