Solidity HTTP API 概览

Solidity HTTP API 是 java-tron 节点基于已固化区块提供的只读 JSON-over-HTTP 接口，路径通常以 /walletsolidity/ 开头。它返回的数据来自最新已固化区块，适合需要最终状态的交易确认、余额对账、状态读取和索引器回填。

Solidity HTTP API 与 FullNode HTTP API 使用相同的请求和响应结构，但服务高度不同。FullNode HTTP 面向最新链头，Solidity HTTP 面向已固化区块。

入口与服务高度

TRON 主网上，区块通常约 1 分钟固化。固化高度只会前进，不会回退。固化机制见 共识与 DPoS —— 区块固化。

API 分类

常见使用场景

充值入账确认

需要最终状态时，应使用 Solidity HTTP 查询交易和回执。只有当包含该交易的区块已经固化后，才适合作为最终确认依据。

常用接口包括：

POST /walletsolidity/gettransactionbyid
POST /walletsolidity/gettransactioninfobyid
POST /walletsolidity/getblockbynum

广播前的构建、签名和提交步骤仍由 FullNode HTTP 完成；广播后的 receipt 查询和固化确认路径见 交易签名与广播——API 工作流。

余额和资源对账

需要稳定对账时，应优先读取 Solidity HTTP 的账户和资源状态，避免把未固化链头状态写入最终账本。

合约只读调用

当你需要基于最终状态执行合约只读查询时，使用 Solidity HTTP 的合约接口。它适合读取 Token 余额、合约配置和业务状态；会改变链上状态的合约调用仍需要走 FullNode HTTP 构造、签名和广播交易。

与 FullNode HTTP API 的区别

两个接口读取同一条 TRON 链；区别是读取高度和接口能力，不是数据来源不同。

Solidity HTTP 不提供的能力

Solidity HTTP 只读，不提供以下能力：

• 构造会改变链上状态的交易，例如转账、质押、投票、资源代理、合约触发等。
• 广播交易，例如 /wallet/broadcasttransaction、/wallet/broadcasthex。
• 依赖本地节点临时状态的接口，例如待处理池查询。

所有写操作都应使用 FullNode HTTP API。

完整的写入交易生命周期，包括构建、签名、广播和用 SolidityNode receipt 确认最终结果，见 交易签名与广播——API 工作流。

请求格式和地址格式

Solidity HTTP 使用与 FullNode HTTP 相同的 JSON 请求和响应格式。大多数接口支持 visible 参数：

请求示例：

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

响应格式

Solidity HTTP 返回与 FullNode HTTP 相同的 protobuf 派生 JSON 结构，也遵循 proto3 默认值省略规则。响应中缺少某字段通常表示该字段持有默认值，而不是节点数据错误。

完整规则和示例见 FullNode HTTP API 概览。

XSS 防护建议

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

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

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

相关资源

• FullNode HTTP API —— 标准 TRON 节点 HTTP 读写接口
• JSON-RPC API —— 以太坊兼容的 JSON-RPC 接口
• TronGrid V1 API —— 账户历史、事件日志和聚合数据查询
• 交易签名与广播——API 工作流 —— 构建、签名、广播和固化确认的端到端路径
• 确认语义 —— 区分最新链头、已固化状态、交易本体和 receipt
• 共识与 DPoS —— 区块固化 —— TRON 区块固化机制