价格查询 — API 参考

价目表、报价凭证与无状态预估。

方法	路径	概览
`GET`	`/v1/prices`	当前完整价目表
`GET`	`/v1/market`	公开全网能量租赁行情看板
`GET`	`/v1/market/history`	特定服务商的历史行情趋势
`GET`	`/v1/orderbook`	指定资源与周期的阶梯报价深度（Ask ladder）
`GET`	`/v1/estimate`	无状态快速价格预估
`POST`	`/v1/quotes`	创建具有约束力的锁价报价单
`GET`	`/v1/quotes/{quoteId}`	读取报价单详情

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

当前完整价目表

GET /v1/prices · getPrices

鉴权： 公开 —— 无需凭据；亦接受附带 API 密钥 (HMAC) 的请求。

包含当前所有可售资源、各租赁周期单价及适用的阶梯大额优惠。由于价格随全天不同时段动态调整，响应中包含当前价格承诺有效窗口（valid_until）、当前所属计价时段以及全天各个时段的 1h 能量价格计划表（schedule）。

主要用于前端展示资费价格表。下单锁价请使用报价单（POST /v1/quotes）—— 价目表展示的数据仅供参考，不构成强制约束。

公开接口。 无需认证凭据；匿名调用按来源 IP 限流。带签名的请求则计入密钥专属调用限额。

请求参数

参数名	位置	类型	必选	说明
`resource`	query	enum: `energy`, `bandwidth`, `activation`		仅筛选特定的资源类型。

响应

状态码	含义
`200`	OK
`401`	缺少、格式错误或已被拒绝的凭据。
`429`	请求过于频繁。
`500`	服务端内部错误。

响应字段 (`PriceTable`)

字段	类型	必选	说明
`network`	enum: `mainnet`, `nile`	是
`as_of`	string (date-time)	是
`valid_until`	string (date-time)	是	当前牌价可能发生变动的时间点。超过此时间请重新拉取，切勿过度缓存。
`period`	object		当前生效的计价时段。
`period.id`	string
`period.label`	string
`period.start`	string		HH:MM UTC
`period.end`	string		HH:MM UTC
`schedule`	array of object		当天所有计价时段列表，按开始时间排序，包含每个时段对应的 1 小时能量价格。
`schedule[].id`	string	是
`schedule[].label`	string	是
`schedule[].start_utc_minute`	integer	是	时段起始时间（UTC 00:00 起经过的分钟数）。
`schedule[].end_utc_minute`	integer	是	时段截止时间（UTC 00:00 起经过的分钟数）。
`schedule[].factor_bps`	integer	是	时段系数（基点，10,000 = ×1.00）。
`schedule[].price_sun_per_unit`	number \| null	是	该时段 1 小时能量单价（SUN/点）。未发售时为 null。
`available_energy`	integer (int64)		当前平台立即可售的能量总量（1 小时周期的订单簿总深度）。
`delivered_today`	integer (int64)		自今日 UTC 00:00 以来已累计交付的能量总额。
`payment_addresses`	object		无账户“直接转账 TRX”快捷通道收款地址。
`available_bandwidth`	integer (int64)
`items`	array of object	是
`items[].resource`	enum: `energy`, `bandwidth`, `activation`	是
`items[].tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`	是	租赁周期。
`items[].price_sun_per_unit`	integer	是	整个租赁周期内每单位资源的 SUN 单价。
`items[].min_amount`	integer	是
`items[].max_amount`	integer	是
`items[].volume_tiers`	array of object		大额梯度优惠。
`items[].volume_tiers[].min_amount`	integer	是
`items[].volume_tiers[].price_sun_per_unit`	integer	是
`activation`	object		激活未激活接收地址的单笔手续费。
`activation.price_sun`	integer (int64)		以 SUN 为单位的金额（1 TRX = 1,000,000 SUN）。始终为整数。

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

json

{
  "network": "mainnet",
  "as_of": "2026-09-11T18:04:05.123Z",
  "valid_until": "2026-09-11T18:09:05.123Z",
  "period": {"id":"peak_late","label":"Late peak","start":"16:00","end":"00:00"},
  "schedule": [
    {
      "id": "drop",
      "label": "Drop",
      "start_utc_minute": 0,
      "end_utc_minute": 60,
      "factor_bps": 13500,
      "price_sun_per_unit": 27
    },
    {
      "id": "off_peak",
      "label": "Off-peak",
      "start_utc_minute": 60,
      "end_utc_minute": 540,
      "factor_bps": 10000,
      "price_sun_per_unit": 20
    },
    {
      "id": "ramp_9",
      "label": "Morning ramp",
      "start_utc_minute": 540,
      "end_utc_minute": 660,
      "factor_bps": 11000,
      "price_sun_per_unit": 22
    },
    {
      "id": "ramp_11",
      "label": "Midday ramp",
      "start_utc_minute": 660,
      "end_utc_minute": 720,
      "factor_bps": 12000,
      "price_sun_per_unit": 24
    },
    {
      "id": "ramp_12",
      "label": "Pre-peak ramp",
      "start_utc_minute": 720,
      "end_utc_minute": 840,
      "factor_bps": 15000,
      "price_sun_per_unit": 30
    },
    {
      "id": "peak",
      "label": "Peak",
      "start_utc_minute": 840,
      "end_utc_minute": 960,
      "factor_bps": 17000,
      "price_sun_per_unit": 34
    },
    {
      "id": "peak_late",
      "label": "Late peak",
      "start_utc_minute": 960,
      "end_utc_minute": 1440,
      "factor_bps": 15000,
      "price_sun_per_unit": 30
    }
  ],
  "available_energy": 412000000,
  "delivered_today": 80600000,
  "available_bandwidth": 1800000,
  "items": [
    {
      "resource": "energy",
      "tier": "1h",
      "price_sun_per_unit": 30,
      "min_amount": 32000,
      "max_amount": 3000000,
      "volume_tiers": []
    }
  ],
  "activation": {"price_sun":1200000}
}

公开全网能量租赁行情看板

GET /v1/market · getMarket

鉴权： 公开 —— 无需凭据；亦接受附带 API 密钥 (HMAC) 的请求。

各大公共服务商最新采集的 1 小时 / 1 天能量报价（由后台任务每 5 分钟轮询），并包含 TEnergy 自身的官方报价行。按 price_sun_1h 升序排序。savings_pct = 1 − price / burn_sun；stale 标识该行数据是否超过 15 分钟未更新。

响应

状态码	含义
`200`	行情看板数据。
`401`	缺少、格式错误或已被拒绝的凭据。
`429`	请求过于频繁。
`500`	服务端内部错误。

响应字段 (`MarketBoard`)

字段	类型	必选	说明
`as_of`	string (date-time)	是
`burn_sun`	number	是	链上直接销毁 TRX 的基准价格（100 SUN/点）。
`providers`	array of object	是
`providers[].slug`	string	是
`providers[].name`	string	是
`providers[].rank`	integer \| null	是	1 = 1 小时价格最低排名；未报价为 null。
`providers[].price_sun_1h`	number \| null	是
`providers[].price_sun_1d`	number \| null	是
`providers[].savings_pct`	number \| null	是	相比燃烧 TRX 的节省百分比（保留 2 位小数）。
`providers[].available_energy`	integer \| null	是
`providers[].total_energy`	integer \| null	是
`providers[].kinds`	array of enum: `api`, `bot`, `pool`, `market`, `web`	是
`providers[].links`	object	是
`providers[].links.site`	string \| null
`providers[].links.telegram`	string \| null
`providers[].links.twitter`	string \| null
`providers[].links.github`	string \| null
`providers[].links.docs`	string \| null
`providers[].links.referral`	string \| null
`providers[].links.logo`	string \| null
`providers[].ts`	string (date-time) \| null	是
`providers[].stale`	boolean	是
`summary`	object	是
`summary.avg_price_sun_1h`	number \| null	是	有效报价的 1 小时能量平均价格。
`summary.active_providers`	integer	是

特定服务商的历史行情趋势

GET /v1/market/history · getMarketHistory

鉴权： 公开 —— 无需凭据；亦接受附带 API 密钥 (HMAC) 的请求。

返回指定服务商的历史采样点序列（按时间正序排列）。不存在的标识符返回空数组。

请求参数

参数名	位置	类型	必选	说明
`slug`	query	string	是	服务商唯一标识符。
`hours`	query	integer		查询的历史小时跨度。

响应

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

响应字段

字段	类型	必选
`slug`	string	是
`hours`	integer	是
`points`	array of object	是
`points[].ts`	string (date-time)	是
`points[].price_sun_1h`	number \| null	是
`points[].price_sun_1d`	number \| null	是
`points[].available_energy`	integer \| null	是

指定资源与周期的阶梯报价深度（Ask ladder）

GET /v1/orderbook · getOrderBook

鉴权： 公开 —— 无需凭据。

按订单规模阶梯定价保障 100% 履约交付。平台公布由多个档位组成的阶梯报价表（价格 @ 额度，按价格由低到高排列）。大单自动沿阶梯逐层消耗吃单：最便宜的一档优先成交，耗尽后进入次便宜档，依此类推。规模越大或高峰期下单综合单价略有提升，但始终保证有货可买，杜绝“售罄”状态。

订单簿各档位的交付来源类型（class）：

class	含义
`instant`	平台自有独家储备，毫秒级快速到账
`market`	平台向批发同业市场即时采购
`deep`	链上深层储备市场，无限量兜底保障

请求参数

参数名	位置	类型	说明
`resource`	query	enum: `energy`, `bandwidth`
`tier`	query	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`
`amount`	query	integer	测算消耗该额度所需的成交档位明细与加权单价。

响应

状态码	含义
`200`	OK
`429`	请求过于频繁。
`500`	服务端内部错误。

响应字段 (`OrderBook`)

字段	类型	必选	说明
`resource`	enum: `energy`, `bandwidth`	是
`tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`	是
`as_of`	string (date-time)	是
`valid_until`	string (date-time)	是	订单簿每数秒重新刷新；切勿超期缓存。
`floor_sun`	number	是	牌价基准底价。
`depth`	integer	是	当前阶梯总可交付深度。
`levels`	array of object (OrderBookLevel)	是	深度档位明细。
`levels[].price_sun`	number	是	该档位的单价（SUN）。
`levels[].amount`	integer	是	该档位可提供的数量。
`levels[].class`	enum: `instant`, `market`, `deep`	是	交付来源分类。
`walk`	object (OrderBookWalk) \| null		传递了 `amount` 时的吃单测算详情。
`walk.amount`	integer	是
`walk.fills`	array of object (OrderBookFill)	是
`walk.fills[].price_sun`	number	是
`walk.fills[].amount`	integer	是
`walk.fills[].class`	enum: `instant`, `market`, `deep`	是
`walk.unit_price_sun`	number	是	吃单后的成交量加权平均单价。
`walk.total_sun`	integer (int64)	是	最终成交总价（SUN）。始终为整数。
`walk.complete`	boolean	是
`walk.outstanding`	integer
`cheaper_from`	string (date-time) \| null		下个更便宜计价时段的开始时间。

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

json

{
  "resource": "energy",
  "tier": "1h",
  "as_of": "2026-09-19T18:04:05.123Z",
  "valid_until": "2026-09-19T18:04:08.123Z",
  "floor_sun": 20,
  "depth": 14200000,
  "levels": [
    {"price_sun":30,"amount":1200000,"class":"instant"},
    {"price_sun":34,"amount":3000000,"class":"market"},
    {"price_sun":58,"amount":10000000,"class":"deep"}
  ],
  "walk": null,
  "cheaper_from": "2026-09-20T01:00:00.000Z"
}

无状态快速价格预估

GET /v1/estimate · estimateOrder

鉴权： 公开 —— 无需凭据；亦接受附带 API 密钥 (HMAC) 的请求。

实时预估当前采购指定数量资源所需的花费，不产生任何副作用也不提前锁定价格。轻量快速，可随前端输入逐字发起请求。

此预估不具备约束力。若需要向最终用户保证预估金额即为最终扣款金额，请调用报价单接口生成 quote_id，并在调用 POST /v1/orders 下单时传入该字段。

请求参数

参数名	位置	类型	必选	说明
`resource`	query	enum: `energy`, `bandwidth`, `activation`	是
`amount`	query	integer (int64)	是	采购的能量或带宽数量。
`tier`	query	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`	是	租赁周期。
`receiver`	query	string		接收地址。如果提供，且该地址尚未在链上激活，将自动计算包含激活费。

响应

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

响应字段 (`Estimate`)

字段	类型	必选	说明
`resource`	enum: `energy`, `bandwidth`, `activation`	是
`amount`	integer	是
`tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`	是
`receiver`	string \| null
`price_sun_per_unit`	integer	是
`energy_amount_sun`	integer (int64)		仅资源的费用（不含激活费）。
`activate_amount_sun`	integer (int64)		目标地址未激活时的激活费。
`total_amount_sun`	integer (int64)	是	最终总金额（以 SUN 为单位，1 TRX = 1,000,000 SUN）。始终为整数。
`receiver_activated`	boolean \| null
`as_of`	string (date-time)	是

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

json

{
  "resource": "energy",
  "amount": 65000,
  "tier": "1h",
  "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "price_sun_per_unit": 20,
  "energy_amount_sun": 1300000,
  "activate_amount_sun": 0,
  "total_amount_sun": 1300000,
  "receiver_activated": true,
  "as_of": "2026-09-11T18:04:05.123Z"
}

创建具有约束力的锁价报价单

POST /v1/quotes · createQuote

鉴权： API 密钥 (HMAC)。

在短暂的时间窗口内锁定购买价格。在创建订单时将返回的 id 传入 quote_id，即可确保扣款金额严格等于报价单中的 total_amount_sun，即使期间时段切换导致全网牌价发生变动。

报价单锁定的是价格，而非现货库存。若在真正创建订单前全网现货已全部售罄，订单将返回 5001 insufficient_supply 并不产生任何实际扣费。

请求参数

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

请求体

JSON (QuoteRequest)，必填。

字段	类型	必选	说明
`resource`	enum: `energy`, `bandwidth`, `activation`	是
`amount`	integer		数量（能量与带宽必填；账户激活时忽略）。
`tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`	是
`receiver`	string		Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。

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

json

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

响应

状态码	含义
`201`	报价单已创建
`400`	格式错误的请求 —— 无效 JSON、未知字段或字段类型错误。
`401`	缺少、格式错误或已被拒绝的凭据。
`422`	语法合法但逻辑上无法满足操作要求。
`429`	请求过于频繁。
`500`	服务端内部错误。

响应字段 (`Quote`)

字段	类型	必选	说明
`id`	string	是
`resource`	enum: `energy`, `bandwidth`, `activation`	是
`amount`	integer
`tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`	是
`receiver`	string \| null
`price_sun_per_unit`	integer		向上取整的整点单价（兼容旧客户端）。
`unit_price_sun`	number		本次报价锁定的精确成交量加权平均单价（精确至 0.01 SUN）。
`fills`	array of object (OrderBookFill)		阶梯报价深度匹配分布。单价统一成交时为空数组。
`fills[].price_sun`	number	是
`fills[].amount`	integer	是
`fills[].class`	enum: `instant`, `market`, `deep`	是
`energy_amount_sun`	integer (int64)
`activate_amount_sun`	integer (int64)
`total_amount_sun`	integer (int64)	是	最终总金额（以 SUN 为单位，1 TRX = 1,000,000 SUN）。始终为整数。
`created_at`	string (date-time)	是
`expires_at`	string (date-time)	是	报价单过期时间。报价有效期为 120 秒。

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

json

{
  "id": "qt_01J9Z5NB2K4R",
  "resource": "energy",
  "amount": 65000,
  "tier": "1h",
  "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "price_sun_per_unit": 20,
  "energy_amount_sun": 1300000,
  "activate_amount_sun": 0,
  "total_amount_sun": 1300000,
  "created_at": "2026-09-11T18:04:05.123Z",
  "expires_at": "2026-09-11T18:06:05.123Z"
}

读取报价单详情

GET /v1/quotes/{quoteId} · getQuote

鉴权： API 密钥 (HMAC)。

返回已生成的报价单详情及其有效性（expires_at 是否晚于当前时间）。

请求参数

参数名	位置	类型	必选	说明
`quoteId`	path	string	是

响应

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

响应字段 (`Quote`)

与 POST /v1/quotes 响应字段相同。

价格查询 — API 参考

当前完整价目表

请求参数

响应

响应字段 (PriceTable)

公开全网能量租赁行情看板

响应

响应字段 (MarketBoard)

特定服务商的历史行情趋势

请求参数

响应

响应字段

指定资源与周期的阶梯报价深度（Ask ladder）

请求参数

响应

响应字段 (OrderBook)

无状态快速价格预估

请求参数

响应

响应字段 (Estimate)

创建具有约束力的锁价报价单

请求参数

请求体

响应

响应字段 (Quote)

读取报价单详情

请求参数

响应

响应字段 (Quote)

响应字段 (`PriceTable`)

响应字段 (`MarketBoard`)

响应字段 (`OrderBook`)

响应字段 (`Estimate`)

响应字段 (`Quote`)

响应字段 (`Quote`)