bc-netts-energy/docs/api.md

REST API 文档

POST /api/v1/energy/rent

为指定 TRON 地址分析能量需求、确保 Host Mode 状态，并根据配置自动购买能量周期。

请求体

{
  "from_address": "T地址",      // 必填，需与 Netts Host Mode 地址一致
  "to_address": "T地址",        // 必填，归集目标地址
  "amount": "200.0",           // 可选，USDT 数量，默认 100.00
  "callback_url": "https://..."// 可选，覆盖配置中的 callback
}

成功响应

{
  "from_address": "TFrom...",
  "to_address": "TTo...",
  "amount": "200.0",
  "address_added": true,
  "recommended_energy": 131000,
  "energy_needed": 131000,
  "cycles_before": 2,
  "cycles_after": 5,
  "cycles_purchased": 3,
  "total_cycles": 5,
  "order_id": "ORD-20231109-XXXX",
  "order_status": "confirmed",
  "total_cost": 9.75,
  "next_delegation_time": 1700000000,
  "analysis": {
    "sender_address": "...",
    "receiver_address": "...",
    "usdt_amount": "200.0",
    "recommended_energy": 131000,
    "energy_needed": 131000,
    "bandwidth_needed": 345,
    "cost_breakdown": {
      "energy_cost": "4.5",
      "bandwidth_cost": "1.0",
      "total_cost_trx": "5.5"
    },
    "savings_analysis": {
      "vs_direct_burn": "21.0",
      "vs_staking": "7.5",
      "savings_percentage": 80.1
    }
  },
  "status": {
    "mode": "normal",
    "status": "active",
    "cycles_remaining": 5,
    "open_orders": 0,
    "expiry_time": 1700100000
  }
}

字段说明：

字段	含义
address_added	是否在本次调用中自动执行了 time/add
cycles_before / cycles_after	调用前后剩余周期
cycles_purchased	本次下单购买的周期数（如果无需下单，字段不存在）
analysis	直接透传 Netts usdt/analyze 的结果
status	透传 Netts time/status 的核心字段

错误响应

{
  "error": "failed to ensure energy",
  "details": "address Txxx not in host mode and autoAddHost disabled"
}

HTTP 状态码：

状态码	说明
200	成功
400	请求体格式错误或地址校验失败
502	与 Netts API 通信失败、或 Netts 返回错误

使用建议

• 在归集任务执行前调用，确保能量充足。
• 结果可缓存短时间（例如 60s），避免频繁重复请求。
• 如需批量处理，可在外层编排多个地址循环调用。