生产 API

快速开始

创建 API 凭证、签名请求并提交首笔生产环境 Energy 订单。

本页内容

这是从空白集成到成功创建订单的最短路径。

1. 创建凭证

打开 控制台 → API，选择 创建 API 密钥，并保存两个值：

api_key：公开凭证标识符；
api_secret：只显示一次的 API 签名密钥。

将签名密钥保留在服务器上，例如 RENTRON_API_SECRET。绝不要暴露给浏览器、移动应用、URL 或日志。

2. 检查服务器时间

curl https://api.rentron.xyz/v1/time

{"unix_time":1784376000}

已签名请求的时间戳必须与服务器时间相差不超过五分钟。

3. 读取订单选项

签名 GET /v1/energy/options。它会返回每份数量、允许时长和是否接收新订单。

{"energy_per_portion":65000,"max_energy":1300000,"duration_minutes":[15,60,240,1440],"intake_enabled":true}

4. 创建订单

只序列化一次 JSON，并对实际发送的准确字节进行签名。

{"client_request_id":"order-1042","address":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8","energy":65000,"duration_minutes":60,"expected_total_trx":"3.200000"}

POST /v1/energy/orders HTTP/1.1
Host: api.rentron.xyz
Content-Type: application/json
Authorization: HMAC-SHA256 {api_key}:{base64_signature}
X-Request-Timestamp: 1784376000

新订单返回 201 Created、订单 JSON 和 Location: /v1/energy/orders/{id}。完全相同的重放会以 200 OK 返回已有订单。请传入最新报价中的精确 total_trx。若返回 energy_price_changed，请获取新报价后再次确认；此时尚未创建订单或冻结资金。

5. Energy 可用时即可发起交易

在 1、2、5 秒后，然后每隔 10 秒轮询 Location。一旦 energy_usable 变为 true，就可以发起您自己的交易：

{"status":"available","delivery_final":false,"energy_usable":true,"rental_expires_at":1784379612}

available 表示 Energy 已分配到该地址并且可以使用，您付费的时长正在计时，直到 rental_expires_at。大约一分钟后，独立验证确认分配完成，状态变为 delivered。请依据 energy_usable 判断，而不是 delivered：等待验证只会消耗您已经付费的租赁时长。

6. 等待最终状态

如果您需要记录完整生命周期，请继续轮询。仅当两个值都为 true 时停止：

{"lifecycle_final":true,"delivery_final":true}

下一步：查询订单、轮询和重试、API 错误。