# 波场能量租赁API对接指南：电报机器人与业务系统搭建 | TEnergy

Source: https://tenergy.me/zh/learn/energy-api-for-bots

1.  [TEnergy](/zh)
2.  [学习](/zh/learn)
3.  波场能量租赁API对接：机器人与业务自动化搭建

# 波场能量租赁API对接：机器人与业务自动化搭建

为Telegram机器人与支付后台接入波场TRON能量租赁API。详解预估、HMAC-SHA256签名、120秒锁价、幂等性下单与Webhooks五步流程。

发布于 2026年10月2日 · 更新于 2026年10月3日

在开发 Telegram 自动化机器人、独立充提网关或批量归集脚本时，直接接入波场能量租赁 REST API 能够实现全自动化的链上资源调度。无需自行准备巨额 TRX 资金用于质押（且免去 Stake 2.0 的 14 天赎回锁定期），也无需在每笔转账时高额燃烧账户内的 TRX 余额，系统即可按需实时获取能量[\[3\]](#source-3)。

整个自动化对接遵循清晰的五步标准化生命周期[\[1\]](#source-1)：公开预估费用、生成 HMAC-SHA256 请求签名[\[2\]](#source-2)、获取 120 秒报价凭证、提交具备幂等性保护的订单，并通过 Webhook 异步接收链上委托生效通知。

在将机器人正式部署到生产环境前，建议先连接我们的 Nile 测试网接口（`https://api-nile.tenergy.me/v1`）进行完整业务演练与异常测试。

## 机器人自动化对接的 5 步完整流程

REST API 为自动化后台提供了确定性的生命周期管理：

```
[机器人 / 业务后台]                    [能量 API 接口]                    [波场区块链]
         |                                   |                                |
         |--- 1. GET /v1/estimate ---------->|                                |
         |<-- 返回总 SUN 费用与费率 ----------|                                |
         |                                   |                                |
         |--- 2. POST /v1/quotes ----------->|                                |
         |<-- 返回 quote_id (120秒锁价) ------|                                |
         |                                   |                                |
         |--- 3. POST /v1/orders ----------->|                                |
         |<-- 201 Created (ord_...) ---------|--- delegateResource ---------->|
         |                                   |                                |
         |<-- 4. Webhook: order.confirmed ---|<-- 链上区块确认 ----------------|
         |                                   |                                |
         |--- 5. 广播 USDT 转账交易 ------------------------------------------->|
```

### 1\. 免密钥预估单笔转账成本

为了向机器人用户实时展示预计扣费或计算转账支出，调用公开的 `GET /v1/estimate` 接口[\[1\]](#source-1)：

bash

```bash
curl -sG https://api.tenergy.me/v1/estimate \
  -d resource=energy -d amount=65000 -d tier=1h \
  -d receiver=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE
```

接口将返回 `total_amount_sun`（按 1 TRX = 1,000,000 SUN 计算）、`price_sun_per_unit` 以及接收方地址在链上的激活状态。

### 2\. 构建 HMAC-SHA256 请求签名

所有需要认证的请求均需附带三个标准 HTTP 请求头[\[2\]](#source-2)：

-   `X-API-KEY`：您的 API Key 标识（以 `ak_live_` 或 `ak_test_` 开头）。
-   `X-API-TIMESTAMP`：ISO 8601 UTC 格式时间戳（允许 5 秒以内的时间漂移）。
-   `X-API-SIGN`：计算出的签名字符串 `base64(HMAC-SHA256(secret, timestamp + METHOD + path + query + body))`。

### 3\. 获取 120 秒锁价凭证

为避免用户确认过程或订单队列中的价格波动，调用 `POST /v1/quotes` 获取报价凭证[\[1\]](#source-1)。凭证可在 120 秒内锁定总扣费金额：

json

```json
{
  "resource": "energy",
  "amount": 65000,
  "tier": "1h",
  "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}
```

### 4\. 提交幂等性订单

将获取到的 `quote_id` 以及您系统内部生成的全局唯一单号 `client_order_id` 传入 `POST /v1/orders`[\[1\]](#source-1)。若因网络瞬断重试请求，系统会识别该单号并返回原订单，避免因重复发单造成的资金损失。

json

```json
{
  "quote_id": "qt_01J9Z5NB2K4R",
  "client_order_id": "bot-order-94812"
}
```

### 5\. 监听链上委托确认

在广播具体的 USDT 转账前，请确认能量已成功委托到账：

-   **Webhooks（推荐）：** 在平台控制台配置接收 URL。能量完成链上打包后，网关会向您发送带有签名的 `order.confirmed` 事件[\[2\]](#source-2)。
-   **轮询查询：** 针对本地脚本，每隔 1–2 秒查询一次 `GET /v1/orders/cid:bot-order-94812`，直到订单状态变为 `active`（基于链上 `delegateResource`[\[3\]](#source-3)）。

## 机器人常用接口速查

| 接口端点 | 请求方式 | 鉴权要求 | 功能说明 |
| --- | --- | --- | --- |
| `/v1/estimate` | `GET` | 否 | 公开估算指定数量与地址的租赁费用 |
| `/v1/prices` | `GET` | 否 | 获取全天各时段价格表与在售时长 |
| `/v1/balance` | `GET` | 是 | 查询当前开发账户的可用余额（SUN） |
| `/v1/quotes` | `POST` | 是 | 申请 120 秒固定报价凭证 (`quote_id`) |
| `/v1/orders` | `POST` | 是 | 创建能量委托订单，具备幂等防重保障 |
| `/v1/orders/cid:{id}` | `GET` | 是 | 依据机器人内部订单号查询执行进度 |

## 开发者架构最佳实践

1.  **环境严格隔离：** 机器人联调阶段请始终使用 Nile 测试网端点（`https://api-nile.tenergy.me/v1`），测试密钥以 `ak_test_` 开头，资金账本与生产环境完全独立。
2.  **每单必带客户端单号：** 为机器人的每一次下单行为生成唯一 `client_order_id`，避免在网络超时重试时发生重复扣款。
3.  **检查 partial 状态字段：** 如果库存不足，订单可能部分成交，未交付部分自动退款，代码中应检查 `partial` 标识。
4.  **确认后再行广播：** 请在收到 `order.confirmed` 通知或订单变为 `active` 后再广播 USDT 转账，确保交易享受能量抵扣。

更多规范细节请阅读完整的 [快速入门指南](/zh/docs/quickstart)、[认证签名规范](/zh/docs/authentication) 以及 [API 文档](/zh/api)。

## 来源

1.  [TEnergy API 开发者文档：快速入门与订单生命周期](https://tenergy.me/zh/docs/quickstart) [↩](#cite-ref-1 "返回正文")
2.  [TEnergy API 开发者文档：HMAC-SHA256 签名规范](https://tenergy.me/zh/docs/authentication) [↩](#cite-ref-2 "返回正文")
3.  [波场 TRON Stake 2.0 开发者规范（delegateResource）](https://developers.tron.network/docs/stake-20) [↩](#cite-ref-3 "返回正文")
4.  [波场浏览器 Tronscan 上的 Tether USD (USDT) 合约 TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t](https://tronscan.org/#/contract/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t) [↩](#cite-ref-4 "返回正文")

## 常见问题

01

### 机器人如何自动化对接波场能量租赁？

业务后台可通过五步标准 REST API 完成自动化：免密调用预估接口、HMAC-SHA256 签名、报价锁价、携带客户端单号下单，并通过 Webhook 接收链上委托确认。

02

### 机器人查询实时能量价格需要 API 密钥吗？

不需要。GET /v1/estimate 与 GET /v1/prices 均为公开接口，无需身份认证即可直接调用。

03

### 网络超时或重试时如何防止重复扣费？

创建订单时必须传入唯一的 client\_order\_id。若遇超时重试同一请求，接口会返回已有订单（HTTP 200），不会产生二次扣费。

04

### 应该使用轮询还是 Webhook 监听订单状态？

具备公网 HTTPS 域名的服务端推荐使用签名 Webhook（监听 order.confirmed 事件）；无公网入口的本地运行环境可轮询 GET /v1/orders/cid:{client\_order\_id} 接口。

没有找到答案？请在 Telegram 联系 [@tenergymebot](https://t.me/tenergymebot)，或发邮件至 [support@tenergy.me](mailto:support@tenergy.me)，我们会把答案补充到这里。
