Energy Agent API

工作台中的每一项 Energy Agent 操作也都可以通过 REST 完成。

基础

基础路径： https://tronagg.ai/api/v1/agent
鉴权： 请求头 X-API-Key: <你的密钥>，与其余程序化 API 使用同一密钥。可在工作台创建。
金额： 所有金额都是以 SUN 为单位的整数（1 TRX = 1,000,000 SUN），字段名以 _sun 结尾。
时间戳： ISO-8601，UTC。
错误： HTTP 状态码加上形如 {"detail": {"error": "<slug>", ...}} 的响应体。参见错误标识。

方法	路径	用途
`GET`	`/summary`	计划限制、你的余额、65,000 能量的价格区间以及你的累计数据。
`GET`	`/quote?energy=`	TRONAgg 对指定能量数量的价格区间。
`GET`	`/configs`	你的配置。
`POST`	`/configs`	创建配置。
`PATCH`	`/configs/{id}`	修改标题、能量、基础付款或上限。
`POST`	`/configs/{id}/pause`	暂停配置。
`POST`	`/configs/{id}/resume`	恢复配置。
`DELETE`	`/configs/{id}`	删除自有钱包配置。
`GET`	`/payments`	你的销售记录。
`GET`	`/api/v1/pay/{public_id}`	公开付款页面数据，无需鉴权。

`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
  }
}

字段	含义
`enabled`	该计划当前是否接受配置。
`min_balance_sun`	激活门槛：创建或恢复配置所需的余额。
`balance_sun` / `can_activate`	你的余额，以及是否达到门槛。
`max_configs` / `max_generated`	你最多可拥有的配置数量，以及 TRONAgg 专属地址数量。
`max_units_cap`	允许的 `max_units` 最大值。
`energy_min` / `energy_max`	单笔付款的订单量限制（没有上限时 `energy_max` 为 `null`）。
`quote_65k`	TRONAgg 对 65,000 能量的价格：当前、价格表中最低的小时和最高的小时。
`totals`	累计销售。利润为 `revenue_sun − cost_sun`。

本页示例中的所有数值仅为示意。

`GET /quote`

任意能量数量的价格区间，计算方式与真实购买完全相同（已计入你的 VIP 折扣）。以 cost_max_sun 作为该每份能量可设置的最低基础付款。

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

配置

配置对象：

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

字段	含义
`public_id`	付款页面 ID：`https://tronagg.ai/pay/<public_id>`。
`mode`	`own`（你的钱包）或 `generated`（TRONAgg 专属地址）。
`status`	`active` 或 `paused`。
`pause_reason`	`user`、`insufficient_balance`、`admin`（被 TRONAgg 客服暂停），运行中时为 `null`。
`stats`	该配置的销售数据。利润为 `revenue_sun − cost_sun`。

列出配置

GET /configs 返回 { "items": [ ...configurations ] }。已删除的配置不会列出。

创建配置

POST /configs 返回 201 和新配置。

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
  }'

字段	规则
`mode`	`own` 或 `generated`。之后无法更改。
`address`	`own` 时必填，`generated` 时省略。之后无法更改。
`title`	可选，最多 40 个字符。
`energy_per_unit`	介于 summary 中的 `energy_min` 与 `energy_max` 之间。
`base_payment_sun`	不低于该 `energy_per_unit` 的 `cost_max_sun`，且为 `1000`（0.001 TRX）的整数倍。
`max_units`	`1` 到 `max_units_cap`；`energy_per_unit × max_units` 不得超过 `energy_max`。

创建配置需要你的余额达到或高于激活门槛。generated 地址是永久的：可以暂停，但永远无法删除。

更新配置

PATCH /configs/{id}，可包含 title、energy_per_unit、base_payment_sun、max_units 中的任意字段。适用与创建时相同的规则。返回更新后的配置。

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}'

暂停与恢复

POST /configs/{id}/pause 和 POST /configs/{id}/resume 返回更新后的配置。恢复需要你的余额达到或高于激活门槛；被客服暂停的配置（pause_reason: "admin"）返回 409 admin_paused。

删除配置

DELETE /configs/{id} 返回 204。只有 own 配置可以删除；generated 配置返回 409 generated_not_deletable。

`GET /payments`

你的销售记录，最新的在前。可选筛选参数：config_id、status、page（默认 1）、page_size（默认 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
}

字段	含义
`payer`	发送 TRX 并接收能量的客户地址。
`amount_sun`	客户支付的金额。
`units` / `energy`	计入的份数与交付的能量。
`cost_sun`	TRONAgg 从你的余额扣取的金额，未扣费时为 `null`。
`status`	`processing`、`delivering`、`completed`、`failed`（扣费已退回你的余额）或 `skipped`。
`skip_reason`	`status` 为 `skipped` 时设置。参见被跳过的付款。
`order_id`	该笔销售对应的能量订单（如已下单）。

公开付款页面数据

GET https://tronagg.ai/api/v1/pay/{public_id} 无需鉴权。它返回付款页面所显示的内容；对于未知或已删除的配置返回 404。

{
  "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 为 false。此时发送的付款会被跳过。

错误标识

状态码	`error`	含义
`403`	`program_disabled`	该计划当前不接受变更。
`422`	`below_min_balance`	你的余额低于激活门槛。附加字段：`min_balance_sun`、`balance_sun`。
`422`	`address_invalid`	不是有效的 TRON 地址。
`409`	`address_taken`	该地址已属于一个运行中的配置。
`422`	`address_reserved`	该地址不能用于自有钱包配置。
`422`	`base_below_cost`	基础付款低于 TRONAgg 的最高小时价格。附加字段：`cost_max_sun`。
`422`	`base_not_mtrx`	基础付款不是 0.001 TRX 的整数倍。
`422`	`energy_out_of_bounds`	每份能量，或能量 × 最多份数，超出了订单限制。
`422`	`units_out_of_bounds`	`max_units` 超出 `1..max_units_cap` 范围。
`422`	`config_limit`	你的配置数量已达上限。
`422`	`generated_limit`	你的 TRONAgg 专属地址数量已达上限。
`409`	`generated_not_deletable`	TRONAgg 专属地址无法删除；请改为暂停。
`409`	`admin_paused`	已被 TRONAgg 客服暂停；请联系客服恢复。
`404`	`not_found`	你的账户下没有该配置。

Webhook 事件

有两个事件通过 Telegram 和 Webhook 报告 Energy Agent 活动。新建 Webhook 时两者默认开启。

`agent.sale`

当一笔付款被转换为能量订单时触发。

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

你在这笔销售上的利润为 amount_sun − cost_sun。交付本身可通过 order.status_changed 或 GET /order/{id} 跟踪。

`agent.payment_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..."
}

字段	含义
`reason`	跳过原因之一。请将其视为开放集合。
`paused`	当这笔付款同时导致你的配置暂停时（`insufficient_balance`）为 `true`。

基础​

GET /summary​

GET /quote​

配置​

列出配置​

创建配置​

更新配置​

暂停与恢复​

删除配置​

GET /payments​

公开付款页面数据​

错误标识​

Webhook 事件​

agent.sale​

agent.payment_skipped​

基础