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>", ...}}. 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`	Order size limits for one payment (`energy_max` is `null` when there is no maximum).
`quote_65k`	TRONAgg's price for 65,000 Energy: now, lowest and highest hour of the schedule.
`totals`	Lifetime sales. Profit is `revenue_sun − cost_sun`.

All figures in the examples on this page are illustrative.

`GET /quote`

The price range for any amount of Energy, computed exactly like a real purchase (your VIP discount included). 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`, `insufficient_balance`, `admin` (paused by TRONAgg support), or `null` when active.
`stats`	Sales for this configuration. Profit is `revenue_sun − cost_sun`.

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`, omitted for `generated`. Can't be changed later.
`title`	Optional, up to 40 characters.
`energy_per_unit`	Between `energy_min` and `energy_max` from the summary.
`base_payment_sun`	At least `cost_max_sun` for `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`.

Creating a configuration needs your balance at or above the activation threshold. 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. The same rules as on create apply. 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. Resuming needs your balance at or above the activation threshold; a configuration paused by support (pause_reason: "admin") returns 409 admin_paused.

Delete a configuration

DELETE /configs/{id} returns 204. Only own configurations can be deleted; a generated one returns 409 generated_not_deletable.

`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`	Units counted and Energy delivered.
`cost_sun`	What TRONAgg charged your balance, `null` when nothing was charged.
`status`	`processing`, `delivering`, `completed`, `failed` (charge refunded to your balance) or `skipped`.
`skip_reason`	Set when `status` is `skipped`. See Skipped payments.
`order_id`	The Energy order behind the sale, when one was placed.

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 for an unknown or deleted configuration.

{
  "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"
}

available is false when the configuration can't take payments right now, for example while it is paused. Payments sent then are skipped.

Error slugs

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.
`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 multiple of 0.001 TRX.
`422`	`energy_out_of_bounds`	Energy per unit, or Energy × max units, is outside the order limits.
`422`	`units_out_of_bounds`	`max_units` is outside `1..max_units_cap`.
`422`	`config_limit`	You already have the maximum number of configurations.
`422`	`generated_limit`	You already have the maximum number of dedicated TRONAgg addresses.
`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.
`404`	`not_found`	No such configuration on your account.

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​

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​