订单接口 — API 参考

购买租赁与订单状态查询。v1 版本不支持单笔订单主动取消：POST /v1/orders 采用同步扣款，订单绝不会处于未支付的悬挂队列中，created 状态极难被外界观测到。3002 order_not_cancellable 仅属于 POST /v1/batches/{id}/cancel 批量取消接口（已经开始处理的接收项无法取消）。

方法	路径	概览
`GET`	`/v1/orders`	订单列表
`POST`	`/v1/orders`	创建并支付订单
`GET`	`/v1/orders/{orderId}`	获取订单详情
`POST`	`/v1/orders/{orderId}/reclaim`	到期前提前归还资源

基于 openapi.yaml 在构建时生成。基准 URL 为 https://api.tenergy.me/v1，Nile 测试网环境为 https://api-nile.tenergy.me/v1（详见环境说明）。下述每个请求均遵循身份鉴权规范进行签名，除非鉴权行另有说明。

订单列表

GET /v1/orders · listOrders

鉴权： API 密钥 (HMAC)。

按时间倒序排列。多个过滤条件之间为逻辑 AND 关系。

传入 format=csv 将以流式方式返回包含所有匹配订单的 text/csv 文件（忽略 limit 和 cursor 分页参数），字段列与 JSON 格式严格对应：每个 Order 字段对应一列，activation.* 与 failure.* 扁平展开，delegate_hashes 用空格分隔。以 =、+、-、@ 或制表符开头的单元格会自动前置 ' 防止表格软件公式注入。

请求参数

参数名	位置	类型	说明
`status`	query	array of enum	订单状态过滤（`created`, `paid`, `allocating`, `delegated`, `confirmed`, `active`, `expired`, `reclaimed`, `failed`, `refunded`）。可重复传参匹配多状态。
`resource`	query	enum: `energy`, `bandwidth`, `activation`	资源类型过滤。
`receiver`	query	string	接收地址过滤。
`client_order_id`	query	string	精确匹配。网络超时重试排查订单最有效途径。
`created_after`	query	string (date-time)
`created_before`	query	string (date-time)
`from`	query	string (date-time)	创建时间起始边界（闭区间，含）。
`to`	query	string (date-time)	创建时间截止边界（开区间，不含）。
`format`	query	enum: `json`, `csv`	导出格式。
`limit`	query	integer	单页数量。
`cursor`	query	string	上次响应中 `next_cursor` 返回的不透明游标。

响应

状态码	含义
`200`	OK
`400`	格式错误的请求 —— 无效 JSON、未知字段或字段类型错误。
`401`	缺少、格式错误或已被拒绝的凭据。
`429`	请求过于频繁。
`500`	服务端内部错误。

响应字段

字段	类型	必选	说明
`data`	array of object (Order)	是
`data[].id`	string	是	平台全局订单 ID。
`data[].client_order_id`	string \| null		业务方自定义订单 ID。
`data[].account_id`	string	是
`data[].batch_id`	string \| null		由批量任务生成的订单时附带批次 ID。
`data[].subscription_id`	string \| null		由自动订阅生成的订单时附带订阅 ID。
`data[].resource`	enum: `energy`, `bandwidth`, `activation`	是	资源类别。
`data[].amount`	integer \| null		下单购买的资源数量。
`data[].delivered_amount`	integer \| null		链上实际质押完成的资源数量。
`data[].partial`	boolean		若为 true 表示部分质押到账，差额已自动按比例原路退款（详见 `refunded_amount_sun`）。部分交付属于标记字段而非状态枚举：订单依然经历 `confirmed` → `active` 正常流转。
`data[].tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d` \| null		租赁周期。
`data[].duration_seconds`	integer \| null		租赁持续秒数。
`data[].receiver`	string	是	Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。
`data[].source`	enum: `api`, `dashboard`, `transfer`, `bot`, `subscription`, `batch`, `proxy`		订单产生来源。
`data[].status`	enum: `created`, `paid`, `allocating`, `delegated`, `confirmed`, `active`, `expired`, `reclaimed`, `failed`, `refunded`	是	订单业务状态机。
`data[].confirm_status`	enum: `unconfirmed`, `confirmed`, `confirm_failed`	是	链上交易确认状态。`unconfirmed` 仅表示区块尚未收录，不代表失败。
`data[].price_sun_per_unit`	integer \| null		结算单价。
`data[].pay_amount_sun`	integer (int64)		资源本身的扣款金额。
`data[].activate_amount_sun`	integer (int64)		目标地址激活服务费（已激活地址为 0）。
`data[].total_amount_sun`	integer (int64)	是	实际扣费总计（`pay_amount_sun + activate_amount_sun`）。
`data[].refunded_amount_sun`	integer (int64)		截止目前已退款总额（失败、退款或部分交付差额）。
`data[].delegate_hash`	string \| null		首笔链上质押交易哈希（等同于 `delegate_hashes[0]`）。
`data[].delegate_hashes`	array of string		属于该订单的所有链上质押交易哈希（大额分拆质押时有多条）。
`data[].delegated_at`	string (date-time) \| null		链上质押广播时间。
`data[].reclaim_hash`	string \| null		提前回收资源的链上解质押交易哈希。
`data[].reclaimed_at`	string (date-time) \| null		提前回收时间。
`data[].expires_at`	string (date-time) \| null		质押租期截止时间。
`data[].activation`	object		账户链上激活处理结果。
`data[].activation.performed`	boolean		是否执行了激活操作。
`data[].activation.hash`	string \| null		激活交易哈希。
`data[].activation.amount_sun`	integer (int64)		激活扣费金额。
`data[].memo`	string \| null		订单业务备注。
`data[].created_at`	string (date-time)	是
`data[].updated_at`	string (date-time)
`data[].failure`	null \| object		失败详情（仅针对 `failed` 状态订单有效）。
`data[].failure.code`	integer	是
`data[].failure.slug`	string	是
`data[].failure.message`	string	是
`data[].failure.at`	string (date-time)
`next_cursor`	string \| null	是	下页游标；末页为 null。

创建并支付订单

POST /v1/orders · createOrder

鉴权： API 密钥 (HMAC)。

为指定接收地址购买资源租赁，并直接从账户余额中扣除相应资金。

响应不代表已完成链上质押。 返回 201 意味着订单已被受理、完成扣款并派发到底层供应层；status 字段反映当次响应时刻的处理进度。绝大多数情况下交付是同步完成的，接口将在几秒内直接返回附带 delegate_hash 的订单对象 —— 此时状态为 confirmed 或 active。请将 confirmed 与 active 一视同仁：均代表资源已成功交付到接收方地址上。 若供应层需要更多时间撮合，状态会体现为 allocating —— 建议轮询 GET /v1/orders/{id} 或监听 order.confirmed Webhook 回调。

注意检查 partial 字段。 若部分配额质押成功而部分未达，订单会以 partial: true 返回，此时 delivered_amount 小于 amount，未交付差额已自动退回账户余额。

幂等性保证。 务必传递 client_order_id。重试相同 ID 且内容一致的请求将返回原订单及 HTTP 200，不重复扣费。发生网络超时时，请直接重试完全相同的请求。

价格保护。 支持传入 quote_id（严格按锁价金额扣费）或 max_price_sun（若市场最新牌价超出该值则拒绝下单并返回 3006 price_above_limit）。

请求参数

参数名	位置	类型	必选	说明
`Idempotency-Key`	header	string		客户端指定的安全重试幂等键（8–128 个字符）。

请求体

JSON (OrderRequest)，必填。

字段	类型	说明
`client_order_id`	string	账户内唯一的自定义业务订单号。强烈建议必传以实现完美幂等。
`quote_id`	string	来自 `POST /v1/quotes` 的有效报价单 ID。用于锁定扣费金额。
`resource`	enum: `energy`, `bandwidth`, `activation`	资源类别。
`amount`	integer	采购数量。
`tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`	租赁周期。
`receiver`	string	Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。
`activate`	boolean	若地址未激活是否自动激活并收取激活费。设置为 false 时遇未激活地址将返回 `3004 receiver_not_activated` 并不扣费。
`max_price_sun`	integer (int64)	最高可接受扣费上限（SUN）。防止无报价单时的行情滑点。
`memo`	string \| null	自定义备注信息。

来自规范的请求体示例（示意数值）：

json

{
  "client_order_id": "acme-2026-09-11-000418",
  "resource": "energy",
  "amount": 65000,
  "tier": "1h",
  "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "activate": true
}

响应

状态码	含义
`200`	该 `client_order_id` 已存在且请求内容一致：返回已存在订单，不重复扣费。
`201`	订单创建成功并已完成扣款。
`400`	格式错误的请求 —— 无效 JSON、未知字段或字段类型错误。
`401`	缺少、格式错误或已被拒绝的凭据。
`402`	账户余额不足。
`409`	幂等请求体冲突或对象状态冲突。
`422`	语法合法但逻辑上无法满足操作要求。
`429`	请求过于频繁。
`500`	服务端内部错误。
`503`	服务暂时不可用（故障安全：未持久化且未扣款）。

响应字段 (`Order`)

字段结构与 GET /v1/orders 列表项中的 Order 相同。

获取订单详情

GET /v1/orders/{orderId} · getOrder

鉴权： API 密钥 (HMAC)。

返回订单全量信息及两组专属明细：fills（订单簿档位吃单加权明细）与 delegations（链上真实质押交易及交易哈希）。

请求参数

参数名	位置	类型	必选	说明
`orderId`	path	string	是	平台订单 ID（`ord_…`）或带 `cid:` 前缀的自定义业务订单号（如 `cid:acme-2026-09-11-000418`）。

响应

状态码	含义
`200`	OK
`401`	缺少、格式错误或已被拒绝的凭据。
`404`	目标对象不存在或属于其他账户。
`429`	请求过于频繁。
`500`	服务端内部错误。

响应字段

包含 Order 对象的全部通用字段，并附带以下特有字段：

字段	类型	必选	说明
`fills`	array of object	是	订单簿各档位撮合成交分布明细。
`fills[].class`	enum: `instant`, `market`, `deep`	是
`fills[].amount`	integer	是	该档位成交数量。
`fills[].price_sun`	number \| null	是	撮合成交单价。
`delegations`	array of object	是	链上真实质押交易详情。
`delegations[].amount`	integer	是	该笔交易交付的能量数量。
`delegations[].tx_id`	string	是	链上交易广播哈希。

到期前提前归还资源

POST /v1/orders/{orderId}/reclaim · reclaimOrder

鉴权： API 密钥 (HMAC)。

提前解除对目标地址的资源委托质押。适用于转账已在链上打包确认后的场景：释放闲置能量供其他业务使用。

不予退款。 租赁与回收属于独立动作；提前释放资源不会退回任何租赁费用。

幂等性。 多次调用返回相同的 reclaim_hash 且无副作用。已自然到期的订单调用亦返回 200。

通过第三方同业市场补充撮合的订单不支持提前回收（将返回 3008 reclaim_unavailable）。

请求参数

参数名	位置	类型	必选	说明
`orderId`	path	string	是
`Idempotency-Key`	header	string		客户端指定的安全重试幂等键。

响应

状态码	含义
`200`	资源已成功提前解质押（或此前已解质押）。
`202`	解质押请求已受理，正在等待链上广播确认。可在几秒后重试查询或监听 `order.reclaimed` 回调。
`401`	缺少、格式错误或已被拒绝的凭据。
`404`	目标对象不存在或属于其他账户。
`409`	无可回收资源（`3007`）或订单来自第三方渠道不支持提前回收（`3008`）。
`429`	请求过于频繁。
`500`	服务端内部错误。

响应字段 (`Order`)

返回更新后的完整 Order 对象。

来自规范的 200 响应示例（示意数值）：

json

{
  "id": "ord_01J9Z5P8T3WQ",
  "client_order_id": "acme-2026-09-11-000418",
  "account_id": "acc_01J9Z4K2M7Q8",
  "resource": "energy",
  "amount": 65000,
  "delivered_amount": 65000,
  "partial": false,
  "tier": "1h",
  "duration_seconds": 3600,
  "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "source": "api",
  "status": "reclaimed",
  "confirm_status": "confirmed",
  "price_sun_per_unit": 20,
  "pay_amount_sun": 1300000,
  "activate_amount_sun": 0,
  "total_amount_sun": 1300000,
  "refunded_amount_sun": 0,
  "delegate_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "delegate_hashes": ["a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"],
  "delegated_at": "2026-09-11T18:04:07.900Z",
  "reclaim_hash": "51fa77da06e8fbebf504fbf088d1d9611059398d51fa77da06e8fbebf504fbf0",
  "reclaimed_at": "2026-09-11T18:12:31.000Z",
  "expires_at": "2026-09-11T19:04:07.900Z",
  "activation": {"performed":false,"hash":null,"amount_sun":0},
  "created_at": "2026-09-11T18:04:05.400Z",
  "updated_at": "2026-09-11T18:12:31.000Z",
  "failure": null
}

订单接口 — API 参考

订单列表

请求参数

响应

响应字段

创建并支付订单

请求参数

请求体

响应

响应字段 (Order)

获取订单详情

请求参数

响应

响应字段

到期前提前归还资源

请求参数

响应

响应字段 (Order)

响应字段 (`Order`)

响应字段 (`Order`)