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 this many hours without a transfer, 24–72 (default 24)
  "quota_max_tx": 1000           // optional: auto-close once N transfers are counted (null = no cap)
}
{
  "address": "TAddressOne...",
  "status": "active",            // "active" on success
  "plan": {                      // example values — read GET /autoenergy/pricing for current prices
    "activation_fee_trx": "3",   // one-off, charged now
    "daily_sub_trx": "3",        // every 24h, first charged 24h after activation
    "unit_price_65k_trx": "1.95", // per covered transfer, by energy class
    "unit_price_131k_trx": "3.9"
  },
  "tx_used_total": 0,
  "quota_max_tx": 1000,
  "idle_hours": 48,
  "expire_at": null,
  "activated_at": "2026-07-24T10:30:05Z"
}

How billing works:

  • Subscribing needs the entry threshold in balance: activation fee + one daily fee + one 131k transfer.
  • The daily fee is first charged 24h after activation, then every 24h after the previous charge.
  • The subscription closes automatically with insufficient_balance if a daily fee can't be paid, or if, after a billed transfer, your balance is below one daily fee + one 131k transfer.
  • If the plan sets min_daily_tx, a 24h cycle with fewer transfers is charged the plan's penalty_sun once (autoenergy_penalty).

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

409 codeMeansDo
address_busyThe address already has a live subscription.If GET .../subscriptions/{address} returns it, nothing — already done. A 404 there means another account covers the address.
address_existsYou have a closed subscription on it.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 counted so far (can slightly exceed quota_max_tx)
    "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.
  • idle_hours can be changed later with PATCH .../subscriptions/{address}; "idle_hours": null turns idle auto-close off.

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": 3900000,            // 0 if the charge couldn't be collected (the subscription then closes)
    "billed_trx": "3.9",
    "occurred_at": "2026-07-24T12:01:44Z"
  }
]
GET https://tronagg.ai/api/v1/autoenergy/subscriptions/{address}/billing
[                                     // newest first
  { "kind": "autoenergy_daily",    "amount_trx": "3",   "at": "2026-07-25T10:30:41Z" },
  { "kind": "autoenergy_unit",     "amount_trx": "3.9", "at": "2026-07-24T12:01:44Z" },
  { "kind": "autoenergy_activate", "amount_trx": "3",   "at": "2026-07-24T10:30:05Z" }
]

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 ends the subscription immediately (close_reason: "manual"). Nothing sent after the close is billed; transfers made before it may still appear as charges shortly after. Closing an already-closed subscription returns 204 and changes nothing.
  • reactivate resumes a closed subscription: it charges the activation fee again (same entry threshold as subscribing), resets tx_used_total, and restarts the 24h daily-fee cycle.

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:

  • autoenergy.delegated — one event per covered transfer.
  • autoenergy.closed — a subscription closed automatically (quota, expiry, idle, balance, …), with its close_reason. Your own close calls don't send it.

Everything above keeps working without them.

Next steps​