96 lines
2.4 KiB
Markdown
96 lines
2.4 KiB
Markdown
# 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），避免频繁重复请求。
|
||
- 如需批量处理，可在外层编排多个地址循环调用。
|