Energy Agent API

Every Energy Agent action in the workspace is also available over REST.

Basics

Base path: https://tronagg.ai/api/v1/agent
Auth: header X-API-Key: <your key>, the same key as the rest of the programmatic API. Create one in the workspace.
Money: every amount is an integer in SUN (1 TRX = 1,000,000 SUN), in fields ending in _sun.
Timestamps: ISO-8601, UTC.
Errors: the HTTP status plus a body of the form {"detail": {"error": "<slug>", ...}}, with no message field; some slugs add fields. A request that fails validation (wrong type, unknown field) gets 422 with a detail array instead. See Error slugs.

Method	Path	Purpose
`GET`	`/summary`	Program limits, your balance, the 65,000-Energy price range and your totals.
`GET`	`/quote?energy=`	TRONAgg's price range for an amount of Energy.
`GET`	`/configs`	Your configurations.
`POST`	`/configs`	Create a configuration.
`PATCH`	`/configs/{id}`	Change title, Energy, base payment or limit.
`POST`	`/configs/{id}/pause`	Pause a configuration.
`POST`	`/configs/{id}/resume`	Resume a configuration.
`DELETE`	`/configs/{id}`	Delete an own-wallet configuration.
`GET`	`/payments`	Your sales feed.
`GET`	`/api/v1/pay/{public_id}`	Public pay-page data. No auth.

`GET /summary`

curl https://tronagg.ai/api/v1/agent/summary -H "X-API-Key: ta_your_key_here"

{
  "enabled": true,
  "min_balance_sun": 10000000,
  "balance_sun": 48250000,
  "can_activate": true,
  "max_configs": 10,
  "max_generated": 3,
  "max_units_cap": 50,
  "energy_min": 65000,
  "energy_max": 1000000,
  "quote_65k": {
    "energy": 65000,
    "cost_now_sun": 1950000,
    "cost_min_sun": 1560000,
    "cost_max_sun": 2340000,
    "timezone": "UTC"
  },
  "totals": {
    "sales": 128,
    "energy": 9100000,
    "revenue_sun": 420000000,
    "cost_sun": 275000000
  }
}

Field	Meaning
`enabled`	Whether the program is currently accepting configurations.
`min_balance_sun`	The activation threshold: the balance needed to create or resume a configuration.
`balance_sun` / `can_activate`	Your balance and whether it meets the threshold.
`max_configs` / `max_generated`	How many configurations, and how many dedicated TRONAgg addresses, you can have.
`max_units_cap`	The highest allowed `max_units`.
`energy_min` / `energy_max`	`energy_min` is the smallest allowed `energy_per_unit`. `energy_max` is the most Energy one payment can buy, `energy_per_unit × max_units` (`null` when there is no maximum).
`quote_65k`	TRONAgg's price for 65,000 Energy, same shape as `GET /quote`.
`totals`	Lifetime sales. Profit is `revenue_sun − cost_sun`. See What counts as a sale.

All figures in the examples on this page are illustrative.

What counts as a sale

totals and each configuration's stats count payments that placed an Energy order. They leave out:

failed orders: their cost was refunded to your balance;
payments whose TRX transfer was later reversed on-chain. Such a payment can still show completed in GET /payments, so summing the feed may not match the totals.

revenue_sun is the TRX customers sent, overpayments included. cost_sun is what your balance was charged. If your account has slow-delivery compensation, a sale delivered late can be refunded to your balance while it stays completed; cost_sun and the totals still show the original charge.

`GET /quote`

The price of any amount of Energy. cost_now_sun is what a sale would be charged right now, your VIP discount included. cost_min_sun and cost_max_sun are the lowest and highest retail price (no VIP discount) over the published weekly schedule and the current rate, so with a VIP discount cost_now_sun can be below cost_min_sun. Use cost_max_sun as the lowest base payment you can set for that Energy per unit.

curl "https://tronagg.ai/api/v1/agent/quote?energy=131000" -H "X-API-Key: ta_your_key_here"

{
  "energy": 131000,
  "cost_now_sun": 3930000,
  "cost_min_sun": 3144000,
  "cost_max_sun": 4716000,
  "timezone": "UTC"
}

Configurations

A configuration object:

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "public_id": "k7Qm2xPa",
  "mode": "generated",
  "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "title": "Night Shift Energy",
  "energy_per_unit": 65000,
  "base_payment_sun": 3000000,
  "max_units": 10,
  "status": "active",
  "pause_reason": null,
  "created_at": "2026-09-29T10:00:00Z",
  "updated_at": "2026-09-29T10:00:00Z",
  "stats": {
    "sales": 12,
    "energy": 1040000,
    "revenue_sun": 48000000,
    "cost_sun": 31200000,
    "last_sale_at": "2026-09-29T12:41:07Z"
  }
}

Field	Meaning
`public_id`	The pay page id: `https://tronagg.ai/pay/<public_id>`.
`mode`	`own` (your wallet) or `generated` (a dedicated TRONAgg address).
`status`	`active` or `paused`.
`pause_reason`	`user` (you paused it), `insufficient_balance`, `admin` (paused by TRONAgg support), or `null` when active. `insufficient_balance` is set automatically when a sale fails for lack of balance, and lifts itself when a payment arrives while your balance is at or above `min_balance_sun`.
`stats`	Sales for this configuration. Profit is `revenue_sun − cost_sun`. See What counts as a sale.

List configurations

GET /configs returns { "items": [ ...configurations ] }. Deleted configurations are not listed.

Create a configuration

POST /configs returns 201 with the new configuration.

curl -X POST https://tronagg.ai/api/v1/agent/configs \
  -H "X-API-Key: ta_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "own",
    "address": "TXYZ...yourAddress",
    "title": "Night Shift Energy",
    "energy_per_unit": 65000,
    "base_payment_sun": 3000000,
    "max_units": 10
  }'

Field	Rules
`mode`	`own` or `generated`. Can't be changed later.
`address`	Required for `own`; omit it (or send `null`) for `generated`. Can't be changed later.
`title`	Optional, up to 40 characters. Surrounding spaces are trimmed; a blank title is stored as `null`.
`energy_per_unit`	At least `energy_min` from the summary.
`base_payment_sun`	At least `cost_max_sun` from `GET /quote?energy=<energy_per_unit>`, and a multiple of `1000` (0.001 TRX).
`max_units`	`1` to `max_units_cap`; `energy_per_unit × max_units` must not exceed `energy_max`.

Any other field is rejected with 422. Creating a configuration needs the program enabled (403 program_disabled) and your balance at or above the activation threshold (422 below_min_balance). A generated address is permanent: it can be paused but never deleted.

Update a configuration

PATCH /configs/{id} with any of title, energy_per_unit, base_payment_sun, max_units. Omitted fields stay unchanged and "title": null clears the title; the three numeric fields can't be null. Changing a numeric field re-checks the create rules. New values apply to payments received after the update. Returns the updated configuration.

curl -X PATCH https://tronagg.ai/api/v1/agent/configs/0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b \
  -H "X-API-Key: ta_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"base_payment_sun": 3500000}'

Pause and resume

POST /configs/{id}/pause and POST /configs/{id}/resume return the updated configuration.

Pause sets pause_reason: "user" and is idempotent. Pausing a configuration that was paused for insufficient_balance turns it into a user pause, so it no longer resumes by itself. Payments to the address still arrive — on a dedicated TRONAgg address they are credited to your balance — but deliver no Energy, and nothing is returned to the customer. A configuration paused by support keeps pause_reason: "admin".
Resume does nothing on an active configuration. Otherwise a configuration paused by support (pause_reason: "admin") returns 409 admin_paused; any other pause is lifted if the program is enabled (403 program_disabled) and your balance is at or above the activation threshold (422 below_min_balance).

Delete a configuration

DELETE /configs/{id} returns 204. Only own configurations can be deleted; a generated one returns 409 generated_not_deletable, and one paused by support returns 409 admin_paused. A deleted configuration disappears from GET /configs and its address can be used again; its payments stay in GET /payments and in your totals.

`GET /payments`

Your sales feed, newest first. Optional filters: config_id, status, page (default 1), page_size (default 20).

curl "https://tronagg.ai/api/v1/agent/payments?status=skipped&page=1&page_size=20" \
  -H "X-API-Key: ta_your_key_here"

{
  "items": [
    {
      "id": "0199a1b2-d4e5-7f60-9a1b-2c3d4e5f6a7b",
      "config_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "tx_hash": "5c8f0d6b1e9a...",
      "payer": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7",
      "amount_sun": 2500000,
      "units": 0,
      "energy": 0,
      "cost_sun": null,
      "status": "skipped",
      "skip_reason": "below_base",
      "order_id": null,
      "created_at": "2026-09-29T12:44:19Z"
    }
  ],
  "page": 1,
  "page_size": 20,
  "has_more": false
}

Field	Meaning
`payer`	The customer address that sent the TRX and receives the Energy.
`amount_sun`	What the customer paid.
`units` / `energy`	What this payment buys under the configuration as it was when the payment was detected (later edits don't change them). Energy is delivered only when `status` is `delivering` or `completed`; a skipped payment can still show non-zero values.
`cost_sun`	What TRONAgg charged your balance; `null` unless an order was placed.
`status`	`processing`, `delivering`, `completed`, `failed` (the order failed and its cost was refunded to your balance; the customer's TRX is not returned automatically) or `skipped`.
`skip_reason`	Why a `skipped` payment delivered nothing. See Skipped payments. It is `null` on a skipped payment whose TRX transfer was reversed on-chain before Energy was ordered. Treat the list as open: new reasons may be added.
`order_id`	The Energy order behind the sale; `null` unless one was placed.

A completed payment can still be left out of your totals; see What counts as a sale.

Public pay-page data

GET https://tronagg.ai/api/v1/pay/{public_id} needs no authentication. It returns what a pay page shows, and 404 with {"detail": {"error": "not_found"}} for an unknown or deleted configuration. Responses are cached for about 30 seconds.

{
  "public_id": "k7Qm2xPa",
  "title": "Night Shift Energy",
  "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "energy_per_unit": 65000,
  "base_payment_sun": 3000000,
  "max_units": 10,
  "available": true,
  "referral_code": "nightshift"
}

Every base_payment_sun sent delivers energy_per_unit Energy for 1 hour to the sending address, up to max_units units per payment. available is true when a payment sent now would buy Energy; while it is false (for example, the configuration is paused), payments deliver no Energy.

Show your customers these payment rules:

Send plain TRX from the wallet that should receive the Energy, not from an exchange: the Energy goes to the sending address.
TRC20 tokens and transfers under 0.1 TRX are ignored.
Only whole units, up to max_units, are delivered. Any remainder, and anything above max_units × base_payment_sun, is not returned.
A payment sent from the configuration's own address delivers nothing.

Error slugs

Business errors have no message field. The extra fields are listed per slug.

Status	`error`	Meaning
`403`	`program_disabled`	The program is not accepting changes right now.
`422`	`below_min_balance`	Your balance is below the activation threshold. Extra fields: `min_balance_sun`, `balance_sun`.
`422`	`address_invalid`	Not a valid TRON address, or an `address` was sent for a `generated` configuration.
`409`	`address_taken`	The address already belongs to an active configuration.
`422`	`address_reserved`	The address can't be used for an own-wallet configuration.
`422`	`base_below_cost`	The base payment is below TRONAgg's highest hourly price. Extra field: `cost_max_sun`.
`422`	`base_not_mtrx`	The base payment is not a positive multiple of 0.001 TRX.
`422`	`energy_out_of_bounds`	Energy per unit, or Energy × max units, is outside the order limits. Extra fields: `energy_min`, `energy_max` (`null` = no maximum).
`422`	`units_out_of_bounds`	`max_units` is outside `1..max_units_cap`. Extra field: `max_units_cap`.
`422`	`config_limit`	You already have the maximum number of configurations. Extra field: `max_configs`.
`422`	`generated_limit`	You already have the maximum number of dedicated TRONAgg addresses. Extra field: `max_generated`.
`409`	`generated_not_deletable`	A dedicated TRONAgg address can't be deleted; pause it instead.
`409`	`admin_paused`	Paused by TRONAgg support; contact support to resume or delete it.
`404`	`not_found`	No such configuration on your account (or, on the pay-page endpoint, no such link).
`503`	`service_unavailable`	Prices are temporarily unavailable; retry later. Returned by `/summary`, `/quote`, create, and an update that changes a numeric field.

Webhook events

Two events report agent activity through Telegram and webhooks. Both are on by default for new webhooks.

`agent.sale`

Fires when a payment is turned into an Energy order.

{
  "config_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "public_id": "k7Qm2xPa",
  "title": "Night Shift Energy",
  "payer": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7",
  "amount_sun": 6000000,
  "units": 2,
  "energy": 130000,
  "cost_sun": 3900000,
  "order_id": "0199a1b2-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "tx_hash": "8e1a4f2c7b3d..."
}

Your profit on the sale is amount_sun − cost_sun. Track the delivery itself with order.status_changed or GET /order/{id}.

`agent.payment_skipped`

Fires when a payment is skipped.

{
  "config_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "public_id": "k7Qm2xPa",
  "title": "Night Shift Energy",
  "payer": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7",
  "amount_sun": 3000000,
  "reason": "insufficient_balance",
  "paused": true,
  "tx_hash": "3b7d9e0f1a2c..."
}

Field	Meaning
`reason`	One of the skip reasons. Treat it as an open set.
`paused`	`true` when this payment also paused your configurations (`insufficient_balance`).

Basics​

GET /summary​

What counts as a sale​

GET /quote​

Configurations​

List configurations​

Create a configuration​

Update a configuration​

Pause and resume​

Delete a configuration​

GET /payments​

Public pay-page data​

Error slugs​

Webhook events​

agent.sale​

agent.payment_skipped​