# REST API 文档

## POST `/api/v1/energy/rent`

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

### 请求体

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

### 成功响应

```json
{
  "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` 的核心字段 |

### 错误响应

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

HTTP 状态码：

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

### 使用建议

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