FullNode HTTP API overview

FullNode HTTP API is the standard JSON-over-HTTP interface provided by java-tron nodes. Its paths usually start with /wallet/. It serves the latest head state seen by the node and is suitable for building transactions, broadcasting transactions, querying latest account state, calling smart contracts, managing account resources, and reading governance data.

If your application needs solidified state, such as deposit crediting, custodial balance confirmation, or accounting, use Solidity HTTP API. If you need account history, event logs, TRC-20 transfer history, or aggregate statistics, use TronGrid V1 API or a self-hosted indexer.

Entry point and served height

API categories

Common use cases

Build and broadcast transactions

A write through FullNode HTTP usually has three steps:

1. Call the corresponding endpoint to build an unsigned Transaction, such as /wallet/createtransaction or /wallet/triggersmartcontract.
2. Sign the transaction in the client or backend.
3. Call /wallet/broadcasttransaction to broadcast the signed transaction.

For the transaction signing and broadcast flow, see Sign and broadcast — the API workflow.

Query latest head state

FullNode HTTP returns the latest head state seen by the node. It is suitable for DApp UIs, immediate transaction display after broadcast, and development debugging. Because latest head state may not yet be solidified, do not use it directly as the basis for deposit crediting, accounting settlement, or bridge release decisions.

Call smart contracts

Smart-contract APIs cover deployment, state-changing triggers, read-only calls, and Energy estimation. State-changing contract calls require transaction construction, signing, and broadcast. Read-only calls can be used for local simulation and state queries.

Request format

Most endpoints use POST with JSON parameters in the request body. Some query or utility endpoints support GET. The supported HTTP method for each endpoint is documented on that endpoint page.

Starting with GreatVoyage-v4.8.2, a GET request can include the int64_as_string=true query parameter to return signed and unsigned 64-bit protobuf integer fields as decimal strings. This prevents precision loss when JavaScript parses large integers as Number. The parameter applies only to GET requests; POST responses retain each endpoint's existing JSON format.

HTTP request bodies are limited by node.http.maxMessageSize, which defaults to 4194304 bytes (approximately 4 MiB). A request rejected before it reaches the target servlet generally returns HTTP 413 Payload Too Large; clients therefore cannot assume that every API error is returned as HTTP 200 with a JSON body.

Per-endpoint HTTP rate limiting is configured under rate.limiter.http. With non-blocking rate limiting enabled, a request that cannot obtain a permit returns HTTP 200 with {"Error":"class java.lang.IllegalAccessException : lack of computing resources"}. This is a rejection by the shared HTTP layer. Clients may retry with jittered backoff, but should not replay the request immediately without delay.

Common request header:

Content-Type: application/json

Request example:

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

Address format

Most FullNode HTTP APIs support the visible parameter, which controls the address format used in requests and responses:

Permission_id

APIs that create or modify on-chain state usually support the Permission_id parameter, which specifies which account permission set signs the transaction. The field name is case-sensitive and must not be written as permission_id. If it is not set, the transaction uses the default owner or active permission, depending on account permission configuration and endpoint behavior.

Response format

TRON nodes define data structures with Protocol Buffers. HTTP API responses are JSON converted from protobuf messages, so clients need to understand proto3 default value omission.

Proto3 default value omission

Under proto3 rules, fields whose values equal their type defaults may be omitted from JSON output. A missing field does not necessarily mean the node lacks that data. It usually means the field carries its default value.

For example, the frozenV2 field returned by /wallet/getaccount may omit default values:

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

After applying protobuf defaults, interpret it as:

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

Clients that parse raw JSON directly need to handle missing fields. Protobuf-compatible JSON parsers usually apply default values automatically.

XSS protection guidance

Although TRON APIs reduce XSS risk by setting the HTTP API Content-Type to application/json, developers should still be aware that certain API endpoints may not perform complete input validation.

To keep user data safe, escape data retrieved from APIs before rendering it in the user interface (UI), especially string fields returned when visible=true.

For complete XSS protection practices, see the OWASP XSS Prevention Cheat Sheet.

Related resources

• API task map — choose concept docs and API reference pages by development task
• Solidity HTTP API — read-only APIs based on solidified blocks
• JSON-RPC API — Ethereum-compatible JSON-RPC interface
• TronGrid V1 API — account history, event logs, and aggregate data queries
• API reference — TRON API categories and selection guide