跳到主要内容

指南：面向地址群的 AutoEnergy

只需订阅一次地址，AutoEnergy 就会让它保持能量就绪——每笔被覆盖的转账都会自动处理并计费。你无需管理委托、时机或补充。本指南演示如何在一组地址上使用它。

所有调用都用你的 API 密钥鉴权：

Headers: { "X-API-Key": "ta_your_key_here" }

订阅一个地址​

POST https://tronagg.ai/api/v1/autoenergy/subscriptions
{
  "address": "TAddressOne...",   // 必填——唯一的必需字段
  "idle_hours": 48,              // 可选：连续这么多小时没有转账就自动关闭，24–72（默认 24）
  "quota_max_tx": 1000           // 可选：计满 N 笔转账后自动关闭（null = 不设上限）
}
{
  "address": "TAddressOne...",
  "status": "active",            // 成功时为 "active"
  "plan": {                      // 示例数值——当前价格请读取 GET /autoenergy/pricing
    "activation_fee_trx": "3",   // 一次性，立即扣取
    "daily_sub_trx": "3",        // 每 24 小时一次，激活 24 小时后首次扣取
    "unit_price_65k_trx": "1.95", // 每笔被覆盖的转账，按能量档位计费
    "unit_price_131k_trx": "3.9"
  },
  "tx_used_total": 0,
  "quota_max_tx": 1000,
  "idle_hours": 48,
  "expire_at": null,
  "activated_at": "2026-07-24T10:30:05Z"
}

计费方式：

  • 订阅需要余额达到准入门槛：激活费 + 一次每日费 + 一笔 131k 档转账。
  • 每日费在激活 24 小时后首次扣取，之后每次距上一次扣费满 24 小时再扣。
  • 如果某次每日费无法支付，或在一笔计费转账之后你的余额低于一次每日费 + 一笔 131k 档转账，订阅会以 insufficient_balance 自动关闭。
  • 如果套餐设置了 min_daily_tx，某个 24 小时周期内转账笔数不足时，会按套餐的 penalty_sun 扣取一次（autoenergy_penalty）。

对每个地址重复即可。这个循环可以安全地重复运行——两个 409 代码会告诉你哪些已经存在：

409 代码含义处理
address_busy该地址已有一个生效中的订阅。如果 GET .../subscriptions/{address} 能返回它，则无需操作——已经完成。若那里返回 404，说明该地址由其他账户覆盖。
address_exists你在该地址上有一个已关闭的订阅。POST .../{address}/reactivate

监控整组地址​

一个调用即可返回全部订阅及实时计数——这就是你整组地址的看板，可按任意节奏重复运行：

GET https://tronagg.ai/api/v1/autoenergy/subscriptions
[
  {
    "address": "TAddressOne...",
    "status": "active",
    "tx_used_total": 5,               // 迄今已计入的转账笔数（可能略超过 quota_max_tx）
    "quota_max_tx": 1000,
    "last_activity_at": "2026-07-24T12:01:44Z",
    "closed_at": null,
    "close_reason": null
  },
  {
    "address": "TAddressTwo...",
    "status": "closed",
    "tx_used_total": 42,
    "close_reason": "quota"           // quota | expired | idle | insufficient_balance | manual | …
  }
]
  • GET .../subscriptions/{address} 返回单个地址的同样对象。
  • 请将 close_reason 视为开放集合——妥善处理未知的值。
  • idle_hours 之后可通过 PATCH .../subscriptions/{address} 修改；"idle_hours": null 会关闭空闲自动关闭。

审计用量与账单​

按地址逐项查询：

GET https://tronagg.ai/api/v1/autoenergy/subscriptions/{address}/usage
[
  {
    "energy_class": "131k",           // 该笔转账覆盖的能量：65k 或 131k
    "used_tx_id": "7f00e1...",        // 消耗它的那笔转账
    "billed_sun": 3900000,            // 费用无法收取时为 0（订阅随后关闭）
    "billed_trx": "3.9",
    "occurred_at": "2026-07-24T12:01:44Z"
  }
]
GET https://tronagg.ai/api/v1/autoenergy/subscriptions/{address}/billing
[                                     // 最新的在前
  { "kind": "autoenergy_daily",    "amount_trx": "3",   "at": "2026-07-25T10:30:41Z" },
  { "kind": "autoenergy_unit",     "amount_trx": "3.9", "at": "2026-07-24T12:01:44Z" },
  { "kind": "autoenergy_activate", "amount_trx": "3",   "at": "2026-07-24T10:30:05Z" }
]

同样的 autoenergy_* 扣费也会出现在你的账户级账本 GET /transactions 中。

关闭与重新激活​

POST https://tronagg.ai/api/v1/autoenergy/subscriptions/{address}/close
POST https://tronagg.ai/api/v1/autoenergy/subscriptions/{address}/reactivate
  • close 立即结束订阅（close_reason: "manual"）。关闭之后发送的转账不会计费；关闭之前发生的转账可能在稍后仍以扣费形式出现。关闭一个已关闭的订阅返回 204，不做任何更改。
  • reactivate 恢复一个已关闭的订阅：再次扣取激活费（准入门槛与订阅时相同），重置 tx_used_total，并重新开始 24 小时的每日费周期。

完整示例（Python）​

fleet.py
import httpx

client = httpx.Client(
    base_url="https://tronagg.ai/api/v1",
    headers={"X-API-Key": "ta_your_key_here"},
)

FLEET = ["TAddressOne...", "TAddressTwo...", "TAddressThree..."]

for address in FLEET:                       # 订阅，可安全地重复运行
    resp = client.post("/autoenergy/subscriptions",
                       json={"address": address, "idle_hours": 48, "quota_max_tx": 1000})
    if resp.status_code == 409 and resp.json()["detail"]["error"] == "address_exists":
        resp = client.post(f"/autoenergy/subscriptions/{address}/reactivate")

for s in client.get("/autoenergy/subscriptions").json():   # 整组看板
    cap = s["quota_max_tx"] or "∞"
    print(f"{s['address']}: {s['status']} — {s['tx_used_total']}/{cap} 笔转账")

可选：实时事件​

如果轮询订阅列表不够及时，可以注册一个 Webhook 接收推送：

  • autoenergy.delegated——每覆盖一笔转账发送一个事件。
  • autoenergy.closed——某个订阅被自动关闭（配额用尽、到期、空闲、余额不足等），附带其 close_reason。你自己调用 close 不会触发它。

没有这些事件，上面的一切照常工作。

下一步​