能量、定价与订单

本页解释领域模型：能量、时长、定价、订单生命周期与幂等性。

能量与时长

一次租用是指将一定量的能量代理到目标地址，持续一段时长。允许的时长是固定的（见可选时长）；默认时长为 10 分钟，其他常用时长有 1 小时、1 天和 3 天。

定价

价格与余额始终以 TRX 的十进制字符串返回——绝不使用浮点数，也绝不使用 SUN 等更小单位——因此不会丢失精度（1 TRX = 10^6 SUN）。报价价格只是要约，只有凭该报价下单后才生效。

报价与订单

• **报价（quote）**是对某个数量、时长以及（可选的）目标地址的实时价格估算，会在短暂窗口后过期。
• **订单（order）**从预付余额冻结资金，并异步履约。

创建订单有两种方式：

1. 一步——直接提交数量、时长和目标地址；价格在下单时实时解析（见一键下单）。
2. 两步——创建报价以锁定价格，然后凭报价下单。凭报价下单时，订单的 target_address 必须与报价一致。

如果你希望在下单前锁定价格，请使用两步流程。

速充订单是第三种、无时长的能量或带宽充值方式：提交 energy_num 和目标地址，订单按实际用量结算（见速充下单）。它在你的历史中以 order_type: "FLASH" 区分。

订单生命周期

PENDING ──────► COMPLETED
   │
   ├──────────► FAILED
   │
   └──────────► RECONCILIATION_REQUIRED

• PENDING —— 已冻结，正在履约。
• COMPLETED —— 能量已代理到目标地址。
• FAILED —— 无法履约；冻结已释放。
• RECONCILIATION_REQUIRED —— 结果不明确，由我方团队处理。

webhook 是可选的。 如果在 API key 上配置了 callback_url，每次状态变化都会推送给你（见 Webhooks）；否则请轮询 GET /api/v1/energy/orders/:order_id。

幂等性

订单接受一个 idempotency_key。用相同载荷复用同一个 key 会返回原订单，而不会重复扣款；用不同载荷复用则会返回错误。为每个逻辑订单生成新的 key，并保留它以用于安全重试。

账户激活

报价可能包含 target_activated——目标地址在报价时刻是否已在链上激活。未激活地址在首次转账时会消耗额外能量；API 会如实报告，方便你提示用户。它是建议性的，不影响价格。