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

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

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

机器人自动化对接的 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]：

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]：

• 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]。凭证可在 120 秒内锁定总扣费金额：

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

4. 提交幂等性订单

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

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

5. 监听链上委托确认

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

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

机器人常用接口速查

开发者架构最佳实践

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

更多规范细节请阅读完整的 快速入门指南、认证签名规范 以及 API 文档。