How AutoEnergy works

AutoEnergy manages one thing: keeping Energy delegated to an address while the subscription is active, and billing your TRONAgg balance for what it delivers. This page covers the delegation cycle, the full lifecycle, the billing model, every auto-close trigger, and the billing guarantees.

The delegation cycle

While a subscription is active, the address always carries a full standing delegation — coverage stays one step ahead of your transfers:

1. Activation parks ~131,000 Energy on the address. That is enough for any single TRC-20 transfer, including a heavy one to a first-time recipient, so the very first transfer is covered with no warm-up. The activation fee covers this standing delegation — there is no separate charge for it.
2. A transfer spends the delegated Energy. The transaction consumes the delegation instead of burning TRX from the wallet. Nothing changes in how you send.
3. The delegation refreshes within seconds. Right after the transfer, the spent delegation is reclaimed and fresh Energy lands on the address — you can watch both happen on any TRON explorer. The transfer itself is billed exactly once, by the class of the coverage it consumed (65k standard, 131k heavy), shortly after it confirms on-chain.

Net effect: each transfer costs its Energy class, and there is never a gap in which a sudden transfer would burn TRX.

Lifecycle

A subscription moves through three states:

subscribe → active → closed
              ↑          |
              └── reactivate ──┘

Status	Meaning
pending_activation	Created, activation charged, delegation being set up. Transient.
active	Energy is kept delegated to the address; per-transfer and daily billing apply.
closed	Delegation stopped. History is retained. Can be reactivated or soft-deleted.

Subscribe

When you subscribe an address, TRONAgg:

1. Validates the address (a malformed address is rejected).
2. Checks the entry threshold — your balance must cover the activation fee + one daily fee + one 131k transfer. This is a guard so a fresh subscription can actually operate, not the full amount charged.
3. Charges the activation fee (one-time).
4. Parks the standing delegation — ~131,000 Energy lands on the address within seconds (see the delegation cycle).

An address may hold only one live subscription at a time. Subscribing an address that already has a live subscription returns 409 address_busy. If you previously closed a subscription on that address, subscribing again returns 409 address_exists — reactivate or delete the closed one first.

Active

While active, the address stays Energy-ready per the delegation cycle: a standing ~131k delegation, refreshed within seconds of every transfer. You are billed as described in Billing.

Reactivate

A closed subscription can be reactivated. Reactivation recharges the activation fee, resets counters (e.g. tx_used_total), and resumes delegation. Reactivating a subscription that is not closed returns 409 not_reactivatable.

Close

Closing stops delegation. On-chain teardown is best-effort — TRONAgg's own status is the source of truth, so the subscription is reliably marked closed even if the teardown lags. A closed subscription stays in your list (with its history) until you delete it.

Delete

Deleting soft-deletes a closed subscription: it disappears from your list, its history is kept, and the address becomes free to add again as a brand-new subscription. Only a closed subscription can be deleted — deleting a live one returns 409 not_deletable.

Billing

All charges are debited from your TRONAgg balance and appear in the billing feed. There are three kinds of charge:

Charge	Ledger kind	When
Activation	autoenergy_activate	Once, on subscribe and on each reactivate
Daily subscription	autoenergy_daily	Each day the subscription is active; the first daily fee falls due ~24h after activation
Per-transfer	autoenergy_unit	Per transfer the address makes, priced by Energy class (65k vs 131k)

All amounts are admin-configurable — fetch the current values from GET /pricing.

Energy classes. A per-transfer charge is one of two classes:

• 65k — a standard TRC-20 transfer to a recipient that already holds the token.
• 131k — a heavier transfer (e.g. a first-time recipient), which consumes roughly twice the Energy.

Each usage event records its class, the units billed, the billed amount, and the on-chain used_tx_id of the transfer it covers.

Settings

Three settings shape when a subscription auto-closes. All are optional and can be changed at any time with PATCH /subscriptions/{address}.

Setting	Values	Default	Effect
idle_hours	24, 48, 72	24	Auto-close after this many hours with no activity.
quota_max_tx	integer ≥ 1, or null	null (no cap)	Auto-close once this many transfers have been billed.
expire_at	future ISO-8601 datetime, or null	null (no expiry)	Auto-close at this time.

On PATCH, an omitted field is left unchanged; sending an explicit null clears the cap or expiry.

Auto-close triggers

A subscription closes automatically for any of these reasons. The reason is exposed as close_reason on the subscription:

close_reason	Trigger
idle	No activity for the configured idle_hours window.
quota	tx_used_total reached quota_max_tx.
expired	The expire_at time passed.
insufficient_balance	Your TRONAgg balance could no longer cover a due charge.
daily_cap	An internal daily safety cap was reached.
manual	You closed it (GUI, bot, or API).
admin	Closed by a TRONAgg operator.

After any auto-close you can reactivate (recharges activation, resets counters) or delete the subscription.

Billing guarantees

Usage detection is TRONAgg's job, not yours. Every eligible transfer from the address is detected and billed exactly once — no transfer is missed, none is double-billed — and the charge shows up in your billing feed moments later.

Billing keys off the delegation being consumed: a charge is recorded once the on-chain transaction is confirmed and linked, so it lands in your feeds shortly after the transfer — never before, and never twice.