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>", ...}} 的响应体，没有 message 字段；部分标识会附带额外字段。未通过校验的请求（类型错误、未知字段）则返回 422，detail 为数组。参见错误标识。

方法	路径	用途
`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_min` 是允许的最小 `energy_per_unit`。`energy_max` 是单笔付款最多可购买的能量，即 `energy_per_unit × max_units`（没有上限时为 `null`）。
`quote_65k`	TRONAgg 对 65,000 能量的价格，结构与 `GET /quote` 相同。
`totals`	累计销售。利润为 `revenue_sun − cost_sun`。参见什么算作一笔销售。

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

什么算作一笔销售

totals 以及每个配置的 stats 统计的是已创建能量订单的付款。以下情况不计入：

失败的订单：其费用已退回你的余额；
TRX 转账后来在链上被回滚的付款。这类付款在 GET /payments 中仍可能显示为 completed，因此把销售记录逐条相加的结果可能与累计数据不一致。

revenue_sun 是客户发送的 TRX，包括多付的部分。cost_sun 是从你的余额扣取的金额。如果你的账户享有慢速交付补偿，一笔延迟交付的销售可能会退款到你的余额，但它仍保持 completed；cost_sun 和累计数据仍显示原始扣费。

`GET /quote`

任意数量能量的价格。cost_now_sun 是此刻一笔销售将被扣取的金额，已计入你的 VIP 折扣。cost_min_sun 和 cost_max_sun 是在已公布的每周价格表与当前费率范围内的最低和最高零售价格（不含 VIP 折扣），因此有 VIP 折扣时，cost_now_sun 可能低于 cost_min_sun。以 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`。当一笔销售因余额不足而失败时，会自动设为 `insufficient_balance`；之后若在你的余额达到或高于 `min_balance_sun` 时有付款到达，该暂停会自动解除。
`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` 时省略（或传 `null`）。之后无法更改。
`title`	可选，最多 40 个字符。首尾空格会被去除；空白标题保存为 `null`。
`energy_per_unit`	不低于 summary 中的 `energy_min`。
`base_payment_sun`	不低于 `GET /quote?energy=<energy_per_unit>` 返回的 `cost_max_sun`，且为 `1000`（0.001 TRX）的整数倍。
`max_units`	`1` 到 `max_units_cap`；`energy_per_unit × max_units` 不得超过 `energy_max`。

其他任何字段都会以 422 拒绝。创建配置需要该计划处于开启状态（否则 403 program_disabled），且你的余额达到或高于激活门槛（否则 422 below_min_balance）。generated 地址是永久的：可以暂停，但永远无法删除。

更新配置

PATCH /configs/{id}，可包含 title、energy_per_unit、base_payment_sun、max_units 中的任意字段。省略的字段保持不变，"title": null 会清空标题；三个数值字段不能为 null。修改数值字段会重新校验创建时的规则。新值适用于更新之后收到的付款。返回更新后的配置。

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: "user"，且是幂等的。暂停一个因 insufficient_balance 而暂停的配置，会把它变为用户暂停，从而不再自动恢复。发往该地址的付款仍会到达——发往 TRONAgg 专属地址的付款会记入你的余额——但不会交付能量，也不会退还给客户。被客服暂停的配置保持 pause_reason: "admin"。
恢复对运行中的配置不起作用。否则，被客服暂停的配置（pause_reason: "admin"）返回 409 admin_paused；其他任何暂停，只要该计划处于开启状态（否则 403 program_disabled）且你的余额达到或高于激活门槛（否则 422 below_min_balance），就会被解除。

删除配置

DELETE /configs/{id} 返回 204。只有 own 配置可以删除；generated 配置返回 409 generated_not_deletable，被客服暂停的配置返回 409 admin_paused。删除的配置会从 GET /configs 中消失，其地址可以再次使用；它的付款仍保留在 GET /payments 和你的累计数据中。

`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`	按检测到付款时的配置，这笔付款可购买的份数与能量（之后的修改不会改变它们）。只有当 `status` 为 `delivering` 或 `completed` 时才会交付能量；被跳过的付款也可能显示非零值。
`cost_sun`	TRONAgg 从你的余额扣取的金额；未下单时为 `null`。
`status`	`processing`、`delivering`、`completed`、`failed`（订单失败，其费用已退回你的余额；客户的 TRX 不会自动退还）或 `skipped`。
`skip_reason`	`skipped` 付款未交付任何内容的原因。参见被跳过的付款。如果被跳过的付款在订购能量之前其 TRX 转账已在链上被回滚，该字段为 `null`。请将此列表视为开放集合：未来可能新增原因。
`order_id`	这笔销售背后的能量订单；未下单时为 `null`。

completed 的付款仍可能不计入你的累计数据；参见什么算作一笔销售。

公开付款页面数据

GET https://tronagg.ai/api/v1/pay/{public_id} 无需鉴权。它返回付款页面所显示的内容；对于未知或已删除的配置，返回 404 和 {"detail": {"error": "not_found"}}。响应会缓存约 30 秒。

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

每发送一笔 base_payment_sun，就会向发送地址交付 energy_per_unit 能量，有效期 1 小时，每笔付款最多 max_units 份。available 为 true 表示现在发送的付款可以购买能量；当它为 false 时（例如配置已暂停），付款不会交付能量。

请向你的客户展示以下付款规则：

从应当接收能量的钱包发送普通 TRX，不要从交易所发送：能量会发往发送地址。
TRC20 代币以及低于 0.1 TRX 的转账会被忽略。
只交付整数份，最多 max_units 份。任何余数，以及超出 max_units × base_payment_sun 的部分，都不会退还。
从配置自身地址发送的付款不会交付任何内容。

错误标识

业务错误没有 message 字段。各标识附带的额外字段如下表所列。

状态码	`error`	含义
`403`	`program_disabled`	该计划目前不接受变更。
`422`	`below_min_balance`	你的余额低于激活门槛。额外字段：`min_balance_sun`、`balance_sun`。
`422`	`address_invalid`	不是有效的 TRON 地址，或为 `generated` 配置传入了 `address`。
`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`	每份能量，或能量 × 最多份数，超出了订单限制。额外字段：`energy_min`、`energy_max`（`null` = 无上限）。
`422`	`units_out_of_bounds`	`max_units` 超出 `1..max_units_cap` 范围。额外字段：`max_units_cap`。
`422`	`config_limit`	你的配置数量已达上限。额外字段：`max_configs`。
`422`	`generated_limit`	你的 TRONAgg 专属地址数量已达上限。额外字段：`max_generated`。
`409`	`generated_not_deletable`	TRONAgg 专属地址无法删除；请改为暂停。
`409`	`admin_paused`	已被 TRONAgg 客服暂停；请联系客服恢复或删除。
`404`	`not_found`	你的账户下没有该配置（在付款页面端点上则是：没有该链接）。
`503`	`service_unavailable`	价格暂时不可用；请稍后重试。由 `/summary`、`/quote`、创建，以及修改数值字段的更新返回。

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​

基础