自动订阅 — API 参考

指定地址的资源自动监控与补仓。

方法	路径	概览
`GET`	`/v1/subscriptions/plans`	保底能量预定套餐及平均单次使用成本
`GET`	`/v1/subscriptions`	列出订阅列表
`POST`	`/v1/subscriptions`	为指定地址配置自动补仓订阅
`GET`	`/v1/subscriptions/{subscriptionId}`	读取单项订阅详情
`PATCH`	`/v1/subscriptions/{subscriptionId}`	修改或暂停订阅
`DELETE`	`/v1/subscriptions/{subscriptionId}`	取消订阅

基于 openapi.yaml 在构建时生成。基准 URL 为 https://api.tenergy.me/v1，Nile 测试网环境为 https://api-nile.tenergy.me/v1（详见环境说明）。下述每个请求均遵循身份鉴权规范进行签名，除非鉴权行另有说明。

保底能量预定套餐及平均单次使用成本

GET /v1/subscriptions/plans · listSubscriptionPlans

鉴权： 公开 —— 无需凭据。

公开接口；附带 API 密钥时会进行凭据校验。grid（动态阶梯）模式的套餐按当前时段计算 per_use 价格。服务端预先计算每日 10、50、200 和 1,000 次转账场景下的 average_price 平均单次成本。

响应

状态码	含义
`200`	当前可用套餐列表，按保底能量从低到高排序。

响应字段

字段	类型	必选	说明
`data`	array of object (SubscriptionPlan)	是
`data[].slug`	string	是
`data[].name`	string	是
`data[].reserve_energy`	integer	是	始终保持委托质押在地址上的保底能量额度。
`data[].daily_fee_sun`	integer	是
`data[].daily_fee_trx`	number	是
`data[].per_use`	object	是
`data[].per_use.mode`	enum: `flat`, `grid`	是	`grid` = 当前时段 1 小时能量单价 × 65,000。
`data[].per_use.energy_per_use`	integer	是
`data[].per_use.price_sun`	integer \| null	是	当 1 小时能量暂停发售时为 null。
`data[].per_use.price_trx`	number \| null	是
`data[].per_use.day_part`	string \| null	是	动态时段 ID；固定费率模式为 null。
`data[].throughput_rule`	string	是
`data[].refill`	object	是
`data[].refill.low`	integer	是	当可用能量低于此数值时触发补仓。
`data[].refill.high`	integer	是	自动补足至此数值。
`data[].uses_within_reserve_per_day`	integer	是
`data[].average_price`	array of object	是	平均每次使用成本：日租金 / N + 单次使用费用（N = 10, 50, 200, 1000）。
`data[].average_price[].uses_per_day`	integer	是
`data[].average_price[].average_sun`	integer \| null	是
`data[].average_price[].average_trx`	number \| null	是
`data[].average_price[].within_reserve`	boolean	是
`at`	string (date-time)	是

列出订阅列表

GET /v1/subscriptions · listSubscriptions

鉴权： API 密钥 (HMAC)。

请求参数

参数名	位置	类型	说明
`status`	query	enum: `active`, `paused`, `suspended`, `cancelled`	按订阅状态过滤。
`receiver`	query	string	按接收地址过滤。
`limit`	query	integer
`cursor`	query	string	上次响应中 `next_cursor` 返回的不透明游标。

响应

状态码	含义
`200`	OK
`401`	缺少、格式错误或已被拒绝的凭据。
`429`	请求过于频繁。
`500`	服务端内部错误。

响应字段

字段	类型	必选	说明
`data`	array of object (Subscription)	是
`data[].id`	string	是
`data[].receiver`	string	是	Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。
`data[].resource`	enum: `energy`, `bandwidth`	是
`data[].mode`	enum: `refill`, `renewal`	是
`data[].tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`	是	租赁周期。
`data[].threshold_amount`	integer
`data[].refill_amount`	integer
`data[].max_price_sun`	integer (int64) \| null
`data[].max_refills_per_day`	integer \| null
`data[].daily_fee_sun`	integer (int64)		订阅未取消时按自然日收取的监控服务费。
`data[].status`	enum: `active`, `paused`, `suspended`, `cancelled`	是	`paused` 由用户主动设置；`suspended` 在余额不足以完成下次补仓时由平台自动挂起（充值后自动恢复）；`cancelled` 为终止态。
`data[].label`	string \| null
`data[].last_refill_at`	string (date-time) \| null
`data[].last_order_id`	string \| null
`data[].refills_today`	integer
`data[].created_at`	string (date-time)	是
`data[].updated_at`	string (date-time)
`data[].plan`	string		套餐标识符（仅适用于套餐类订阅）。
`data[].reserve_energy`	integer \| null
`data[].delegated_energy`	integer		当前实际委托在地址上的能量数量。
`data[].next_billing_at`	string (date-time) \| null
`data[].grace_until`	string (date-time) \| null		扣费失败时质押保持宽限期截止时间。
`data[].events`	array of object (SubscriptionEvent)		仅在套餐订阅的 `GET /v1/subscriptions/{id}` 中返回：最近 20 条事件。
`data[].events[].id`	string	是
`data[].events[].kind`	enum: `refill`, `charge`, `pause`, `resume`, `cancel`, `top_up_failed`	是
`data[].events[].energy_delta`	integer \| null
`data[].events[].amount_sun`	integer \| null
`data[].events[].txid`	string \| null
`data[].events[].ts`	string (date-time)	是
`next_cursor`	string \| null	是

为指定地址配置自动补仓订阅

POST /v1/subscriptions · createSubscription

鉴权： API 密钥 (HMAC)。

持续监控指定地址，并在其空闲资源低于 threshold_amount 时自动购买补充。支持两种模式：

mode: "refill" —— 按需自动补仓。定期轮询地址资源，一旦低于设定阈值即触发补仓订单。需为每次补仓订单付费，同时每日计取监控基础费。
mode: "renewal" —— 自动无缝续期。在当前 tier 租赁到期前自动续约重购，确保地址上的资源额度永不归零掉线。

计费机制：每次补仓或续约均作为普通订单按当时生效价格扣款，同时在订阅处于活跃期间按自然日收取 daily_fee_sun 服务费。当账户余额不足以支付下次补仓时，订阅转入 suspended 挂起状态（不会被删除），并触发 subscription.suspended 回调；充值到账后系统会自动恢复监控。

同一地址针对同一种资源类型最多只能存在一个订阅。重复创建将返回 3011 subscription_exists。

请求参数

参数名	位置	类型	必选	说明
`Idempotency-Key`	header	string		客户端指定的安全重试幂等键（8–128 个字符）。

请求体

JSON (SubscriptionRequest)，必填。

字段	类型	必选	说明
`receiver`	string	是	Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。
`resource`	enum: `energy`, `bandwidth`	是
`mode`	enum: `refill`, `renewal`	是	`refill` 余额不足自动补仓；`renewal` 到期前自动续订保活。
`tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`	是	租赁周期。
`threshold_amount`	integer	是	触发补仓的可用资源下限。
`refill_amount`	integer	是	每次补仓购买的资源数量。
`max_price_sun`	integer (int64)		最高可接受单笔总价（SUN），避免在市场极端行情高峰时高位补仓。超过时跳过当次补仓。
`max_refills_per_day`	integer		每日自动补仓次数上限熔断，防止地址发生高频交易意外抽干账户余额。强烈推荐设置。
`label`	string \| null

来自规范的请求体示例（示意数值）：

json

{
  "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "resource": "energy",
  "mode": "refill",
  "tier": "1h",
  "threshold_amount": 65000,
  "refill_amount": 131000,
  "max_price_sun": 3000000,
  "max_refills_per_day": 48
}

响应

状态码	含义
`201`	创建成功
`400`	格式错误的请求 —— 无效 JSON、未知字段或字段类型错误。
`401`	缺少、格式错误或已被拒绝的凭据。
`402`	账户余额不足以支付。
`409`	存在相同资源的重复订阅冲突。
`422`	语法合法但逻辑上无法满足操作要求。
`429`	请求过于频繁。
`500`	服务端内部错误。

响应字段 (`Subscription`)

与 GET /v1/subscriptions 响应中的字段结构相同。

读取单项订阅详情

GET /v1/subscriptions/{subscriptionId} · getSubscription

鉴权： API 密钥 (HMAC)。

请求参数

参数名	位置	类型	必选	说明
`subscriptionId`	path	string	是

响应

状态码	含义
`200`	OK
`401`	缺少、格式错误或已被拒绝的凭据。
`404`	目标对象不存在或属于其他账户。
`500`	服务端内部错误。

响应字段 (`Subscription`)

与订阅列表中的字段结构相同。

修改或暂停订阅

PATCH /v1/subscriptions/{subscriptionId} · updateSubscription

鉴权： API 密钥 (HMAC)。

可传入任意一个或多个可修改字段。status 仅接受 active 与 paused 两种输入值。suspended 是由系统在余额耗尽时自动标记并会在充值后自动解除；cancelled 需通过 DELETE 方法达成。空请求体将被拒绝并返回 2002 empty_patch。

请求参数

参数名	位置	类型	必选	说明
`subscriptionId`	path	string	是

请求体

JSON (SubscriptionPatch)，必填。

字段	类型	必选	说明
`status`	enum: `active`, `paused`
`tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`
`threshold_amount`	integer
`refill_amount`	integer
`max_price_sun`	integer (int64)
`max_refills_per_day`	integer
`label`	string \| null

响应

状态码	含义
`200`	已更新
`400`	格式错误的请求 —— 无效 JSON、未知字段或字段类型错误。
`401`	缺少、格式错误或已被拒绝的凭据。
`404`	目标对象不存在或属于其他账户。
`422`	语法合法但逻辑上无法满足操作要求。
`500`	服务端内部错误。

响应字段 (`Subscription`)

与 Subscription 对象字段相同。

取消订阅

DELETE /v1/subscriptions/{subscriptionId} · cancelSubscription

鉴权： API 密钥 (HMAC)。

终止未来的自动补仓动作。此前已经成功完成交付的质押资源不受影响，将继续维持至其租期正常到期；不支持提前退费或强制回收。订阅对象仍可通过接口读取，状态变为 status: "cancelled"。

请求参数

参数名	位置	类型	必选	说明
`subscriptionId`	path	string	是

响应

状态码	含义
`204`	已取消。无响应体。
`401`	缺少、格式错误或已被拒绝的凭据。
`404`	目标对象不存在或属于其他账户。
`500`	服务端内部错误。

自动订阅 — API 参考

保底能量预定套餐及平均单次使用成本

响应

响应字段

列出订阅列表

请求参数

响应

响应字段

为指定地址配置自动补仓订阅

请求参数

请求体

响应

响应字段 (Subscription)

读取单项订阅详情

请求参数

响应

响应字段 (Subscription)

修改或暂停订阅

请求参数

请求体

响应

响应字段 (Subscription)

取消订阅

请求参数

响应

响应字段 (`Subscription`)

响应字段 (`Subscription`)

响应字段 (`Subscription`)