JSON-RPC API 概览

TRON JSON-RPC API 可以理解为面向 Ethereum 兼容场景的一组轻量接口，覆盖 FullNode 能力中的部分 EVM 风格查询与调用场景。它便于复用 Web3.js、ethers、viem 等以太坊生态工具链。

JSON-RPC API 不是 FullNode HTTP API 的完整替代品。由于 TRON 与 Ethereum 的底层机制不同，部分 Ethereum JSON-RPC 方法在 TRON 上没有对应实现，或行为存在差异。

兼容性约定

地址：状态查询、调用和交易构造接口只接受十六进制地址，可以是 20 字节 EVM 风格地址，也可以是以 41 开头的 21 字节 TRON 地址；两种形式均可带或不带 0x。JSON-RPC 不接受 Base58Check（T...）地址。日志过滤器使用 20 字节十六进制地址。
调用数据：eth_call、eth_estimateGas 和 buildTransaction 同时接受 data 与 input。两者同时存在时使用 input；非空的 input 必须带 0x 且 hex 位数为偶数，空字符串表示空字节；data 为兼容旧客户端保留较宽松解析。
区块标签：支持范围取决于具体方法。区块查询通常支持 latest、earliest、finalized，不支持 pending 和 safe；状态查询和 eth_call 的字符串 selector 只支持 latest。客户端不应假定所有方法支持相同标签。
HTTP 状态码：进入 JSON-RPC servlet 的协议或业务错误通常返回 HTTP 200，并通过 error 对象表达；请求体过大等传输层失败仍可能返回 HTTP 413。

入口与默认状态

项目	说明
默认状态	默认关闭，需要在 `node.jsonrpc` 配置块中手动开启
FullNode JSON-RPC 默认端口	`8545`
Solidity JSON-RPC 默认端口	`8555`
自建节点路径	端口根路径，例如 `http://127.0.0.1:8545/`
TronGrid 路径	`https://api.trongrid.io/jsonrpc`
主要用途	复用以太坊工具链、查询 EVM 风格数据、读取日志和调用合约

自建 java-tron 节点的 JSON-RPC 服务运行在对应端口的根路径。/jsonrpc 是 TronGrid 网关路径，不是自建节点的通用路径。

启用 JSON-RPC

在节点 config.conf 中启用：

node {
  jsonrpc {
    httpFullNodeEnable = true
    httpFullNodePort = 8545
    httpSolidityEnable = true
    httpSolidityPort = 8555
  }
}

FullNode JSON-RPC 面向最新链头；Solidity JSON-RPC 面向已固化状态。生产系统应按确认性要求选择对应端口。

API 分类

分类	入口	主要用途
`eth_*`	eth	查询账户、区块、交易、收据、合约代码、日志、过滤器和链信息
`net_*`	net	查询节点 P2P 连接状态和网络版本
`web3_*`	web3	查询客户端版本、计算 Keccak-256 哈希
`buildTransaction`	buildTransaction	构造 TRON 交易对象，用于后续签名和广播

常见使用场景

复用以太坊工具链

如果应用已有 Web3.js、ethers、viem 或类似工具链，可以通过 JSON-RPC 接入 TRON。常见用途包括读取区块高度、查询交易收据、读取合约代码、执行 eth_call 和查询事件日志。

查询合约事件

eth_getLogs 可按地址、区块范围和 topic 查询事件日志。实际查询范围、topic 数量和结果数量可能受节点或网关配置限制。高频历史事件检索可以考虑 TronGrid V1 API 或自建索引器。

GreatVoyage-v4.8.2 的默认节点配置将单次日志查询区块跨度限制为 5000，地址数和子 topic 数分别限制为 1000，活跃日志过滤器数量限制为 20000。节点运营者可通过 node.jsonrpc.maxBlockRange、maxAddressSize、maxSubTopics 和 maxLogFilterNum 调整这些上限；TronGrid 等网关可能采用不同限制。eth_getFilterLogs 与 eth_getLogs 使用同一组范围校验。

此外，默认 maxBatchSize 为 100，maxResponseSize 为 26214400 字节（25 MiB），maxMessageSize 为 4194304 字节（约 4 MiB）。这些均位于 node.jsonrpc 配置块中，独立于 FullNode HTTP API 的限制。

构造 TRON 交易

buildTransaction 是 TRON 提供的扩展方法，用于构造不同类型的 TRON 交易。交易构造后仍需要签名和广播；完整流程可结合 FullNode HTTP API 的交易构建与广播接口理解。

请求格式

JSON-RPC 请求使用 POST，请求体包含 jsonrpc、method、params 和 id：

curl --request POST \
  --url 'http://127.0.0.1:8545/' \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

TronGrid 网关示例：

curl --request POST \
  --url 'https://api.trongrid.io/jsonrpc' \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }'

Hex 编码规则

JSON-RPC 中的数值和字节数据都使用十六进制字符串，但规则不同。

数值

数值使用 0x 前缀和紧凑编码，不允许前导零：

示例	是否有效	说明
`0x0`	是	数值 0
`0x41`	是	十进制 65
`0x0400`	否	不允许前导零
`ff`	否	缺少 `0x` 前缀

字节数据

字节数据也使用 0x 前缀，但每个字节必须用两位 hex 表示：

示例	是否有效	说明
`0x`	是	空字节
`0x41`	是	1 字节
`0x004200`	是	3 字节
`0xf0f0f`	否	hex 位数不是偶数
`004200`	否	缺少 `0x` 前缀

与 FullNode HTTP API 的区别

能力	JSON-RPC API	FullNode HTTP API
以太坊工具链兼容	强	弱
接口覆盖范围	覆盖部分 EVM 风格查询与调用场景	覆盖标准节点 HTTP 能力
事件日志查询	支持 EVM 风格日志	标准节点 HTTP 覆盖较有限
默认开启状态	默认关闭	默认开启