JSON-RPC API overview

TRON JSON-RPC API can be understood as a lightweight interface set for Ethereum-compatible scenarios. It covers part of the node's EVM-style query and call capabilities and makes it easier to reuse Web3.js, ethers, viem, and other Ethereum tooling.

JSON-RPC API is not a full replacement for FullNode HTTP API. Because TRON and Ethereum differ in their underlying mechanisms, some Ethereum JSON-RPC methods do not have corresponding implementations on TRON, or behave differently.

Compatibility conventions

• Addresses: State-query, call, and transaction-building methods accept only hexadecimal addresses: either a 20-byte EVM-style address or a 21-byte TRON address beginning with 41, in both cases with or without 0x. JSON-RPC does not accept Base58Check (T...) addresses. Log filters use 20-byte hexadecimal addresses.
• Call data: eth_call, eth_estimateGas, and buildTransaction accept both data and input. For eth_call and eth_estimateGas, input is used when both fields are present. For buildTransaction, the two fields must decode to identical bytes when both are provided; otherwise, the method returns an invalid-parameters error. A non-empty input requires a 0x prefix and an even number of hex digits; an empty string represents empty bytes. data retains more lenient parsing for compatibility with legacy clients.
• Block tags: Support is method-specific. Block-query methods generally support latest, earliest, and finalized, but not pending or safe. State-query methods and the string selector of eth_call support only latest. Clients should not assume that every method supports the same tags.
• HTTP status codes: Protocol or application errors that reach the JSON-RPC servlet generally return HTTP 200 with an error object. Transport-level failures, such as an oversized request body, may still return HTTP 413.

Entry point and default status

A self-hosted java-tron node serves JSON-RPC at the root path of the configured port. /jsonrpc is a TronGrid gateway path, not the generic path for self-hosted nodes.

Enable JSON-RPC

Enable it in the node config.conf file:

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

FullNode JSON-RPC serves the latest head state. Solidity JSON-RPC serves solidified state. Production systems should choose the port based on the finality requirements of the read path.

API categories

Common use cases

Reuse Ethereum tooling

If your application already uses Web3.js, ethers, viem, or similar tooling, you can connect it to TRON through JSON-RPC. Common use cases include reading block height, querying transaction receipts, reading contract code, running eth_call, and querying event logs.

Query contract events

eth_getLogs can query event logs by address, block range, and topic. The actual block range, topic count, and result size may be limited by node or gateway configuration. For high-frequency historical event search, consider TronGrid V1 API or a self-hosted indexer.

In the GreatVoyage-v4.8.2 default node configuration, a single log query spans at most 5000 blocks, includes at most 1000 addresses and 1000 subtopics, and the node maintains at most 20000 active log filters. Node operators can adjust these limits through node.jsonrpc.maxBlockRange, maxAddressSize, maxSubTopics, and maxLogFilterNum. Gateways such as TronGrid may use different limits. eth_getFilterLogs and eth_getLogs use the same block-range validation.

The defaults also set maxBatchSize to 100, maxResponseSize to 26214400 bytes (25 MiB), and maxMessageSize to 4194304 bytes (approximately 4 MiB). These settings belong to the node.jsonrpc block and are independent of the FullNode HTTP API limits.

Build TRON transactions

buildTransaction is a TRON extension method used to construct different types of TRON transactions. The constructed transaction still needs to be signed and broadcast. The full flow can be understood together with FullNode HTTP transaction construction and broadcast APIs.

Request format

JSON-RPC requests use POST and include jsonrpc, method, params, and id in the request body:

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 gateway example:

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 encoding rules

Values and byte data are both represented as hex strings in JSON-RPC, but they follow different rules.

Quantities

Quantities use a 0x prefix and compact encoding. Leading zeroes are not allowed:

Byte data

Byte data also uses a 0x prefix, but each byte must use two hex digits:

Difference from FullNode HTTP API

Related resources

• FullNode HTTP API — standard TRON node HTTP read/write interface
• Solidity HTTP API — read-only interface based on solidified blocks
• TRON vs Ethereum — protocol differences between TRON and Ethereum
• Networks — public endpoints for Mainnet, Shasta, and Nile