区块链状态 — API 参考

只读 TRON 链上辅助方法。

方法	路径	概览
`GET`	`/v1/resources/{address}`	查询地址的资源状态
`POST`	`/v1/estimate/transfer`	估算 TRC-20 转账所需能量

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

查询地址的资源状态

GET /v1/resources/{address} · getAddressResources

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

返回链上关于该地址的当前信息：是否已激活、拥有多少空闲能量和带宽、有多少被质押委托及来源委托方，以及其中哪些委托来自我方平台。

通过我方全节点读取并附带短暂缓存（as_of 标识数据新鲜度）。建议在下单前调用以确认是否真正需要购买能量 —— 最便宜的能量就是无需购买的能量。

公开接口。 无需认证凭据；匿名调用按来源 IP 限流，并且 our_active_orders 恒返回 []。若附带签名，则会列出该账户名下正在向该地址交付的有效订单，并计入密钥的限流配额。

请求参数

参数名	位置	类型	必选	说明
`address`	path	string	是	Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。

响应

状态码	含义
`200`	OK
`400`	格式错误的请求 —— 无效 JSON、未知字段或字段类型错误。
`401`	缺少、格式错误或已被拒绝的凭据。
`429`	请求过于频繁（超出限流）。
`500`	服务端内部错误。
`503`	服务暂时不可用。在创建订单时该状态为故障安全（fail-secure）：未存储任何数据且未扣费，使用相同的 `client_order_id` 重试是安全的。

响应字段 (`AddressResources`)

字段	类型	必选	说明
`address`	string	是	Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。
`activated`	boolean	是	若地址从未在链上接收过任何转账，则为 false。
`balance_sun`	integer (int64)		以 SUN 为单位的金额（1 TRX = 1,000,000 SUN）。始终为整数。
`holds_usdt`	boolean \| null		该地址是否持有非零 USDT (TRC-20) 余额 —— 即链上 USDT 合约的 `balanceOf > 0`。向从未持有 USDT 的地址转账会新建合约存储槽位，消耗约两倍的能量（约 131k 而非 65k）。读取失败时为 `null`；响应的其余部分不受影响。
`energy`	object	是
`energy.limit`	integer		该地址可使用的能量总上限。
`energy.used`	integer
`energy.available`	integer		`limit - used`。当前发起转账立即可用的能量。
`energy.delegated_in`	integer		总上限中来自于他人委托质押的部分。
`bandwidth`	object	是
`bandwidth.limit`	integer
`bandwidth.used`	integer
`bandwidth.available`	integer
`bandwidth.delegated_in`	integer
`bandwidth.free_net_limit`	integer		每日免费带宽配额，已包含在 `limit` 中。
`our_active_orders`	array of object		本账户当前向该地址派发的有效订单列表。来自其他服务商或账户的委托会计入 `delegated_in`，但不会在此列出。
`our_active_orders[].order_id`	string
`our_active_orders[].amount`	integer
`our_active_orders[].resource`	enum: `energy`, `bandwidth`, `activation`		`energy` —— TRON 能量，TRC-20 转账消耗的资源。· `bandwidth` —— TRON 带宽（网络），由交易数据大小消耗。· `activation` —— 一次性账户激活；不适用 `amount` 和 `tier`。
`our_active_orders[].expires_at`	string (date-time)
`as_of`	string (date-time)	是	从链上读取该数据的时间戳。服务端会缓存数秒。

来自合约规范的 200 响应示例（示意数据，实际数据由 API 返回）：

json

{
  "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "activated": true,
  "balance_sun": 4120000,
  "holds_usdt": true,
  "energy": {"limit":131000,"used":0,"available":131000,"delegated_in":131000},
  "bandwidth": {"limit":1600,"used":0,"available":1600,"delegated_in":0,"free_net_limit":600},
  "our_active_orders": [
    {
      "order_id": "ord_01J9Z5P8T3WQ",
      "amount": 65000,
      "resource": "energy",
      "expires_at": "2026-09-11T19:04:07.900Z"
    }
  ],
  "as_of": "2026-09-11T18:40:00.000Z"
}

估算 TRC-20 转账所需能量

POST /v1/estimate/transfer · estimateTransferEnergy

鉴权： API 密钥 (HMAC)。

计算从 from_address 向 to_address 发起 TRC-20 转账所消耗的能量，以及租赁相应能量的成本。未指定 contract_address 时默认使用 USDT（TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t）。

数值取决于收款方是否已经持有该代币的非零余额 —— 首次收款人消耗的能量约为两倍 —— 这就是为什么必须同时提供两个地址。预估结果是通过在我方节点上执行 triggerConstantContract 模拟运行得出的，因此它反映的是当前智能合约的真实状态，而非静态经验表。

下单前请预留安全余量：模拟是在当前执行的，而转账是在稍后广播上链的，在此期间收款方的余额可能发生变化。recommended_amount 已经包含了平台的安全冗余，建议以此数值进行下单。

请求体

JSON (TransferEstimateRequest)，必填。

字段	类型	必选	说明
`from_address`	string	是	Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。
`to_address`	string	是	Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。
`contract_address`	string		TRC-20 合约地址。默认是 USDT `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`。
`amount`	string \| null		以代币最小单位计量的转账金额，以十进制字符串表示以防大数精度丢失。对模拟影响极小；若未知可省略。
`tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`		租赁时长的计费周期。默认为 `1h`。

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

json

{
  "from_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "to_address": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

响应

状态码	含义
`200`	OK
`400`	格式错误的请求 —— 无效 JSON、未知字段或字段类型错误。
`401`	缺少、格式错误或已被拒绝的凭据。
`429`	请求过于频繁。
`500`	服务端内部错误。
`503`	服务暂时不可用。在创建订单时为故障安全：未存储任何数据且未扣费，重试相同 `client_order_id` 是安全的。

响应字段 (`TransferEstimate`)

字段	类型	必选	说明
`from_address`	string	是	Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。
`to_address`	string	是	Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。
`contract_address`	string	是	Base58Check 编码的 TRON 地址（以 `T` 开头，34 个字符）。
`recipient_holds_token`	boolean		接收方是否已持有该代币的非零余额。首次接收方大约需要消耗两倍的能量，这是影响成本的最大单一因素。
`energy_required`	integer	是	模拟转账消耗的精确能量。
`recommended_amount`	integer	是	实际建议下单的能量数量 —— `energy_required` 加上状态漂移的安全余量。请按此数量下单，而非 `energy_required`。
`bandwidth_required`	integer
`tier`	enum: `5m`, `15m`, `1h`, `1d`, `3d`, `30d`		租赁周期。`GET /v1/prices` 列出当前实际可售的周期。切勿在代码中硬编码此列表；请求 `/prices` 中不存在的周期将被拒绝并返回 `2003 tier_unavailable`。
`price_sun_per_unit`	integer
`energy_amount_sun`	integer (int64)		以 SUN 为单位的金额（1 TRX = 1,000,000 SUN）。始终为整数。
`activate_amount_sun`	integer (int64)		当 `to_address` 尚未激活时的账户激活费用。
`total_amount_sun`	integer (int64)		总金额，以 SUN 为单位（1 TRX = 1,000,000 SUN）。始终为整数。
`burn_alternative_sun`	integer (int64)		供对比：按网络当前基础能量价格直接燃烧 TRX 所需花费的成本。根据链上参数 (`getEnergyFee`) 动态计算，而非固定常量。自 2025-08-29 起，该参数为每点能量 100 SUN；示例中为 `130,285 × 100`。任何仍在使用 210 的代码或示例均使用的是已废弃的旧常量。
`as_of`	string (date-time)	是	预估生成时间。

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

json

{
  "from_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "to_address": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "recipient_holds_token": false,
  "energy_required": 130285,
  "recommended_amount": 131000,
  "bandwidth_required": 345,
  "tier": "1h",
  "price_sun_per_unit": 20,
  "energy_amount_sun": 2620000,
  "activate_amount_sun": 1200000,
  "total_amount_sun": 3820000,
  "burn_alternative_sun": 13028500,
  "as_of": "2026-09-11T18:41:00.000Z"
}

区块链状态 — API 参考

查询地址的资源状态

请求参数

响应

响应字段 (AddressResources)

估算 TRC-20 转账所需能量

请求体

响应

响应字段 (TransferEstimate)

响应字段 (`AddressResources`)

响应字段 (`TransferEstimate`)