租赁 API 接口参考

按接口查找参数，再查看对应的响应 Schema。下列路径相对于包含 /openapi/v1/rentals/ 的 OPENAPI_BASE_URL，请保留末尾斜杠。

JSON 包含完整接口路径，不包含生产服务域名；导入 Postman 等工具时配置服务 origin。示例仅说明结构，金额、可用性和有效期以实际报价为准。

公共约定

项目	约定
Authentication	`Authorization: Bearer YOUR_API_KEY`；不接受浏览器或管理员 Cookie 认证。
Content-Type	POST 使用 `application/json`；拒绝未定义的请求体字段，最大 8,192 字节。
Accept-Language	可选 `en` 或 `zh-hans`；标签和消息用于展示，程序不应据此判断状态。
权限	`read`：GET 查询；`rent`：查询、创建报价和提交订单。
金额	响应金额为整数 SUN 字符串；1 TRX = 1,000,000 SUN，避免浮点计算。
资源	整数能量／带宽单位，不是质押 TRX 或交易笔数；仍受部署限额约束。
时间	租期：整数秒；时间戳：ISO 8601 UTC（`Z` 或 `+00:00`）。
空值	`null` 是字段值，不表示字段缺失；除特别说明外，响应字段均会返回。
网络	网络由部署决定，使用对应网络的 Key，无需网络请求头。

在控制台创建密钥，完整密钥只展示一次，请保存在服务端。撤销阻止后续请求，不取消已受理订单。除本机回环开发外使用 HTTPS。

接口总览

Method	相对路径	权限	成功响应
GET	`balance/`	read / rent	200 · Balance
POST	`quotes/`	rent	201 · Quote
GET	`quotes/{quote_id}/`	read / rent	200 · Quote
POST	`orders/`	rent	202 · Order
GET	`orders/`	read / rent	200 · OrderPage
GET	`orders/{order_id}/`	read / rent	200 · Order

GET balance/

无请求体或查询参数；返回当前账户的 200 · Balance。

{
  "network": "mainnet",
  "asset": "TRX",
  "balance_sun": "5000000",
  "frozen_sun": "1680000",
  "available_sun": "3320000"
}

POST quotes/

需要 rent 权限；返回 201 · Quote。

请求体字段	类型	必填	约束
`receiver_address`	string	是	实际使用资源的钱包，必须通过 TRON 地址校验。
`energy_amount`	integer	是	0–2^63−1；正数须符合部署的最小及最大能量限制。
`bandwidth_amount`	integer	否	默认 0；0–2^63−1；能量为 0 时必须大于 0。
`duration_seconds`	integer	是	1–2^31−1 秒；须满足部署最短租期并有可用定价。

{
  "receiver_address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
  "energy_amount": 65000,
  "bandwidth_amount": 350,
  "duration_seconds": 600
}

两种资源不能同时为零。此 API 支持单租带宽，网页仍要求租赁能量。两种资源共用租期、独立定价；任一请求资源不可用时拒绝报价，不会静默移除。报价不冻结资金，也不预留库存。

特定错误：400 invalid_request、403 permission_denied、503 rentals_unavailable / rental_unavailable。

GET quotes//

路径参数	类型	必填	含义
`quote_id`	string · uuid	是	POST quotes/ 返回的报价 ID。

返回 200 · Quote。只允许查询本账户报价；不存在或不属于本账户返回 404 not_found。未使用报价过期超过七天后可能清理，已关联订单的报价保留。

POST orders/

需要 rent 权限；返回 202 · Order，相同请求的幂等重试也返回 202。受理不代表链上交付成功。

请求头	类型	必填	约束
`Idempotency-Key`	string	是	1–128 个字符，仅字母、数字及 `. _ : -`；首次提交前持久化。

请求体字段	类型	必填	约束
`quote_id`	string · uuid	是	本账户的报价，新订单须在有效期内。
`max_total_sun`	string / integer	是	正整数 SUN 授权上限，最大 2^63−1；建议使用十进制字符串。

{
  "quote_id": "11111111-1111-4111-8111-111111111111",
  "max_total_sun": "1680000"
}

授权上限不能覆盖定价，一份报价最多生成一笔订单。幂等范围为账户及网络，在不同 Key 和网页订单间共享：相同键、报价及上限返回原订单，改变任一字段返回 409 order_conflict。没有 external_order_id 字段。

特定错误：400 invalid_request、403 permission_denied、409 insufficient_balance / order_conflict、503 rentals_unavailable / rental_unavailable。报价过期或关闭新租赁不阻止恢复已受理请求。

GET orders/

查询参数	类型	必填	约束
`idempotency_key`	string	否	按原请求键筛选，返回值仍为 OrderPage。
`limit`	integer	否	1–100，默认 20。
`cursor`	string	否	上一页返回的 next_cursor，原样传入，最多 4096 字符。

返回 200 · OrderPage，按创建时间从新到旧排列，包含本账户的 API 与网页余额订单。无匹配返回 results: []，不是 404；分页参数无效返回 400 invalid_request。游标绑定账户及资源。

GET orders/?idempotency_key=YOUR_PERSISTED_REQUEST_ID

GET orders//

路径参数	类型	必填	含义
`order_id`	string · uuid	是	提交或查询订单返回的订单 ID。

返回 200 · Order；读取交付明细及费用结算确认结果。不存在或不属于本账户返回 404 not_found。

响应 Schema

Balance

字段	类型	含义
`network`	string	`mainnet` 或 `nile`。
`asset`	string	`TRX`
`balance_sun`	string · SUN	总余额，包含冻结部分。
`frozen_sun`	string · SUN	当前冻结金额。
`available_sun`	string · SUN	balance_sun − frozen_sun，可用于新租赁。

Quote

字段	类型	含义
`id`	string · uuid	用于下单的报价 ID。
`receiver_address`	string	资源接收地址。
`energy_amount` / `bandwidth_amount`	integer	请求的资源数量。
`duration_seconds`	integer	共用租期，单位秒。
`rental_fee_sun`	string · SUN	能量租赁费，单租带宽时为 0。
`bandwidth_fee_sun`	string · SUN	完整带宽租赁费，未租带宽时为 0。
`activation_fee_sun`	string · SUN	适用的地址激活费，无则为 0。
`total_sun`	string · SUN	上述三项费用合计。
`expires_at`	string · date-time	报价失效时间，不是租赁到期时间。

能量费和带宽费分别向上取整至 0.01 TRX，全部费用以实际报价确认，不要从示例推算应付金额。

{
  "id": "11111111-1111-4111-8111-111111111111",
  "receiver_address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
  "energy_amount": 65000,
  "bandwidth_amount": 350,
  "duration_seconds": 600,
  "rental_fee_sun": "1400000",
  "bandwidth_fee_sun": "280000",
  "activation_fee_sun": "0",
  "total_sun": "1680000",
  "expires_at": "2026-10-25T08:02:00Z"
}

Order

字段	类型	含义
`id`	string · uuid	订单 ID。
`status`	string · enum	稳定状态值，见下文状态表。
`status_label`	string	本地化展示标签。
`receiver_address`	string	资源接收地址。
`energy_amount` / `bandwidth_amount`	integer	订单请求的资源数量。
`duration_seconds`	integer	租期秒数。
`total_sun`	string · SUN	订单原始总价；部分交付时不等于最终实扣金额。
`rental` / `bandwidth` / `activation`	object · FeeSettlement	分别对应能量、带宽和激活费结算。
`deliveries`	array · Delivery	各资源交付记录；准备前可为空，未租资源不创建记录。
`created_at`	string · date-time	订单创建时间。
`starts_at` / `expires_at`	string · date-time / null	确定租赁起止时间后返回，此前为 null。
`delegate_txid`	string / null	仅能量交付交易，带宽单租时为 null；能量记录未广播时可能为空串。优先读取 deliveries。
`notice`	string / null	部分交付／失败订单的本地化提示，其他情况为 null。

交付前已受理订单示例（202）：

{
  "id": "22222222-2222-4222-8222-222222222222",
  "status": "ready",
  "status_label": "Awaiting delivery",
  "receiver_address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
  "energy_amount": 65000,
  "bandwidth_amount": 350,
  "duration_seconds": 600,
  "total_sun": "1680000",
  "rental": {
    "amount_sun": "1400000",
    "status": "held",
    "status_label": "Frozen"
  },
  "bandwidth": {
    "amount_sun": "280000",
    "status": "held",
    "status_label": "Frozen"
  },
  "activation": {
    "amount_sun": "0",
    "status": "not_applicable",
    "status_label": "Not applicable"
  },
  "deliveries": [],
  "created_at": "2026-10-25T08:00:00Z",
  "starts_at": null,
  "expires_at": null,
  "delegate_txid": null,
  "notice": null
}

FeeSettlement

字段	类型	含义
`amount_sun`	string · SUN	该费用项金额。
`status`	string · enum	`held`, `charged`, `released`, `not_applicable`
`status_label`	string	本地化标签，程序使用 status 判断。

状态	含义
`held`	已冻结，尚未扣费。
`charged`	已实际扣费。
`released`	已释放原冻结。
`not_applicable`	零费用或未租资源，没有发生冻结、扣费或释放。

若激活费原先已冻结，后来被第三方激活，则为 released，不是 not_applicable。带宽单租的 rental 为零且不适用；未租带宽的 bandwidth 同样如此。

Delivery

字段	类型	含义
`resource`	string · enum	`ENERGY`, `BANDWIDTH`
`amount`	integer	该交付对应的资源单位数。
`status`	string · enum	`preparing`, `pending`, `delegated`, `undelegating`, `undelegated`, `failed`
`delegate_txid`	string / null	委托交易哈希，未生成时为 null。
`recall_txid`	string / null	回收交易哈希，未生成时为 null。

delegated 表示委托已确认，undelegated 表示回收已确认。这些是资源级状态，不能与订单的 active 等状态混用；能量交易成功不代表带宽也成功。

OrderPage

字段	类型	含义
`results`	array · Order	本页订单，无匹配时为空数组。
`next_cursor`	string / null	下一页游标；null 表示没有下一页。

{
  "results": [],
  "next_cursor": null
}

ApiError

字段	类型	含义
`code`	string	稳定的程序判断代码。
`message`	string	本地化展示消息。
`request_id`	string	问题定位编号，同时位于 X-Request-ID 响应头。

{
  "code": "order_conflict",
  "message": "The request conflicts with an existing order.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}

订单状态与恢复

订单状态	含义
`created` / `ready`	已创建／等待交付，资源尚未确认到账。
`delegating`	交付中或交易结果不明，保留相应冻结并核验原交易。
`active`	全部请求资源交付已确认。
`partial`	部分成功、其他明确失败；逐项结算费用。
`expiring` / `expired` / `undelegating`	即将到期／已到期／回收中。
`closed`	所有成功交付资源均已回收。
`failed` / `cancelled`	失败／取消；仍需读取逐项费用与交付记录。

超时、500 或响应丢失后，先按原幂等键查询，或使用原键及原内容重试。原结果不明时不能生成新键，也不能因某组件失败就把另一笔结果不明的交易视为失败。成功部分扣费并按期回收，正常到期不退租赁费。

错误码与限流

HTTP	code	含义
400	`invalid_request`	JSON、字段、资源数量、分页或请求头无效。
401	`invalid_credentials`	Key 缺失、撤销、过期、无效或账户不可用。
403	`permission_denied`	只读 Key 尝试报价或下单。
404	`not_found`	记录不存在或不属于当前账户。
405	`method_not_allowed`	方法不支持，查看 Allow。
409	`insufficient_balance` / `order_conflict`	余额不足、报价过期或下单冲突。
429	`rate_limited`	遵守 Retry-After: 60 后再重试。
503	`rentals_unavailable` / `rental_unavailable` / `temporarily_unavailable`	租赁关闭，或定价、库存、链上服务、限流服务不可用。
500	`internal_error`	未预期错误；重试前查询原请求。

以上是已匹配业务接口的应用错误。无效路径、Host 校验、反向代理及 Cloudflare 可能返回 HTML 或其他结构；解码 JSON 前检查 HTTP 状态及 Content-Type。正常业务响应及已处理错误包含 X-Request-ID。

限流类别	默认每 60 秒	共享范围
Authentication	120	客户端 IP
GET reads	120	账户下所有 Key
POST quotes/	10	账户下所有 Key
POST orders/	10	账户下所有 Key

部署可调整限额；重试也计入额度，查询应设置间隔并退避，避免紧密循环。限流服务故障返回 503。充值地址、密钥管理及资金流水仍使用控制台，此 API 不提供提现或退款操作。