指南API 参考手册社区Discord博客FAQ漏洞赏金公告中心
API 参考手册
English(英文版)

FullNode HTTP API 概览

FullNode HTTP API 是 java-tron 节点提供的标准 HTTP 接口，面向最新链头状态，覆盖交易构建、签名辅助、广播、账户、资源、合约、治理和网络查询等能力。

FullNode HTTP API 是 java-tron 节点提供的标准 JSON-over-HTTP 接口，路径通常以 /wallet/ 开头。它面向节点当前看到的最新链头状态，适合构建交易、广播交易、查询最新账户状态、调用智能合约、管理账户资源和读取链上治理信息。

如果业务需要读取已固化状态，例如最终状态判断、余额确认或财务对账，应使用 Solidity HTTP API。如果需要账户历史、事件日志、TRC-20 转账历史或聚合统计，可以使用 TronGrid V1 API 或自建索引器。

入口与服务高度

项目说明
默认路径前缀/wallet/
默认端口8090（由节点 config.conf 的 node.http.fullNodePort 配置）
服务高度最新链头状态
主要用途交易构建与广播、最新状态读取、节点和链上信息查询
是否可写是，交易构建和广播类接口通过 FullNode HTTP 提供

API 分类

分类入口主要用途
地址工具地址工具地址生成、地址校验、地址格式转换等纯工具接口
交易交易构造、签名辅助、广播交易，以及查询签名权重
账户账户创建账户、查询账户、更新账户名、配置账户权限
账户资源账户资源Stake 2.0 / Stake 1.0 质押、解质押、资源代理和资源查询
查询网络查询网络查询区块、交易、链参数、节点状态、资源价格等信息
TRC-10 TokenTRC-10 Token协议层 TRC-10 Token 的发行、参与、转账和查询
智能合约智能合约部署合约、触发合约、只读调用、能量估算和合约配置
投票与超级代表投票与超级代表SR 注册、投票、奖励提取和 Brokerage 管理
提案提案链上治理提议的创建、批准、撤回和查询
待处理池待处理池查询本地节点 mempool 中的待处理交易

常见使用场景

构建和广播交易

通过 FullNode HTTP 发起写入通常分三步：

  1. 调用对应接口构造未签名 Transaction 对象，例如 /wallet/createtransaction 或 /wallet/triggersmartcontract。
  2. 在客户端或后端签名交易。
  3. 调用 /wallet/broadcasttransaction 广播已签名交易。

交易签名与广播流程见 交易签名与广播——API 工作流。

查询最新链头状态

FullNode HTTP 返回节点当前看到的最新链头状态，适合 DApp UI、交易广播后的即时状态展示和开发调试。由于最新链头可能还没有固化，不建议直接用它作为充值入账、财务结算或跨链桥放行依据。

调用智能合约

智能合约接口覆盖部署、触发、只读调用和能量估算。会改变链上状态的合约调用需要构造交易、签名并广播；只读调用可用于本地模拟和状态查询。

请求格式

大多数接口使用 POST，参数放在 JSON 请求体中。部分查询或工具接口支持 GET。每个接口支持的 HTTP 方法以具体接口文档为准。

从 GreatVoyage-v4.8.2 起，GET 请求可添加 int64_as_string=true 查询参数，使 protobuf 的有符号和无符号 64 位整数字段以十进制字符串返回，避免 JavaScript 将大整数解析为 Number 时丢失精度。该参数只对 GET 请求生效；POST 请求仍使用接口原有的 JSON 输出形式。

HTTP 请求体受 node.http.maxMessageSize 限制，默认值为 4194304 字节（约 4 MiB）。请求在进入目标 servlet 前超限时通常返回 HTTP 413 Payload Too Large；因此客户端不能假定所有 API 错误都会以 HTTP 200 和 JSON 响应体返回。

HTTP 单接口限流通过 rate.limiter.http 配置。启用非阻塞限流后，请求无法取得 permit 时会返回 HTTP 200，响应体包含 {"Error":"class java.lang.IllegalAccessException : lack of computing resources"}。这属于共享 HTTP 层拒绝；客户端可采用带抖动的退避重试，但应避免立即无间隔重放。

常见请求头：

Content-Type: application/json

请求示例：

curl --request POST \
  --url 'http://127.0.0.1:8090/wallet/getaccount' \
  --header 'Content-Type: application/json' \
  --data '{
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "visible": true
  }'

地址格式

大多数 FullNode HTTP API 支持 visible 参数，用来控制请求和响应中的地址格式：

visible地址格式示例特征
trueBase58Check通常以 T 开头
false 或省略Hex通常以 41 开头

Permission_id

创建或修改链上状态的接口通常支持 Permission_id 参数，用于指定使用账户中的哪个权限集签名交易。字段名区分大小写，不能写成 permission_id。没有设置时，交易使用默认 owner 或 active 权限，具体行为以账户权限配置和接口文档为准。

响应格式

TRON 节点用 Protocol Buffers 定义数据结构。HTTP API 返回的是从 protobuf 消息转换得到的 JSON，因此需要注意 proto3 的默认值省略规则。

Proto3 默认值省略

按 proto3 规范，字段值等于其类型默认值时，默认可能从 JSON 输出中省略。响应中缺少某字段不一定代表节点没有该数据，通常表示该字段持有默认值。

字段类型默认值JSON 中的常见行为
int32 / int640可能省略
boolfalse可能省略
string""可能省略
bytes空可能省略
enum第一个定义的值（索引 0）可能省略
repeated[]可能省略

例如 /wallet/getaccount 返回中的 frozenV2 字段可能省略默认值：

"frozenV2": [
  { "amount": 20000000000 },
  { "type": "ENERGY", "amount": 20400000000 },
  { "type": "TRON_POWER" }
]

解析时应按 protobuf 默认值补齐：

"frozenV2": [
  { "type": "BANDWIDTH", "amount": 20000000000 },
  { "type": "ENERGY", "amount": 20400000000 },
  { "type": "TRON_POWER", "amount": 0 }
]

直接解析原始 JSON 的客户端需要自己处理缺失字段；使用 protobuf 兼容 JSON 解析器时，通常会自动按默认值解释。

XSS 防护建议

尽管 TRON API 通过将 HTTP API 的 Content-Type 设置为 application/json 来降低 XSS 风险，但开发者仍应注意某些特定的 API endpoint 可能缺乏完整的输入验证。

为了确保用户数据安全，建议在将从 API 检索到的数据渲染到用户界面（UI）之前，对其进行适当的转义处理，尤其是 visible=true 时返回的字符串字段。

如需了解完整的 XSS 防护实践，请参阅 OWASP XSS Prevention Cheat Sheet。

相关资源

Updated 11 days ago

Updated 11 days ago