TRON tooling

TRON blockchain development tools guide. Use TronWeb.js, gRPC, web3.py, Hardhat, and Foundry with Chainstack TRON nodes and endpoints.

Chainstack TRON nodes expose four API surfaces over a single node endpoint. Get started with a reliable TRON RPC endpoint, and see the official TRON API reference for the full method list.

API	Endpoint	Use it for
JSON-RPC	/jsonrpc	Ethereum-compatible read operations
Wallet	/wallet	TRON HTTP API — full node operations, including transactions
Solidity	/walletsolidity	TRON HTTP API — confirmed (solidified) data
gRPC	host on port 443	High-performance binary protocol — see available services

TRON nodes run in archive mode, which for TRON means the complete block and transaction history from genesis rather than historical state — see Historical data availability.

Tooling compatibility

TRON’s /jsonrpc endpoint provides limited Ethereum compatibility for read operations only — the methods required for transaction submission (eth_sendRawTransaction, eth_getTransactionCount) are not available. Ethereum-native tools like Foundry, Hardhat, and web3.py can read from a TRON node, but they cannot deploy contracts or send transactions directly. For writes, use TronWeb.js with the /wallet endpoint, or compile and test with Foundry or Hardhat and deploy through the hybrid workflow.

TRON nodes don’t support WebSocket connections for event subscriptions. To track that capability, follow the feature request for TRON event plugin support.

Historical data availability

TRON nodes on Chainstack run in archive mode. For TRON, archive means the complete block and transaction history — not historical state. Unlike EVM archive nodes, java-tron has no state-at-block queries; this is a protocol limitation (java-tron#6289), not a Chainstack one. Billing is independent of the node mode — every TRON request is billed as full (1 RU); see Request units.

Available on your node:

• Complete block and transaction history from genesis — block and transaction methods accept any historical block, for example /wallet/getblockbynum and eth_getBlockByNumber
• Historical TRX balances — /wallet/getaccountbalance and /wallet/getblockbalance with a block_identifier

Not available on any TRON node:

• Historical contract or account state, beyond the TRX balance lookups above — eth_getBalance, eth_call, eth_getCode, and eth_getStorageAt accept only the latest block parameter and return QUANTITY not supported, just support TAG as latest for anything else; triggerconstantcontract always runs against current state. java-tron tracks archive-node support in java-tron#6289.

gRPC API

TRON nodes on Chainstack support gRPC for high-performance access. gRPC uses HTTP/2 and Protocol Buffers for efficient binary serialization, making it ideal for high-throughput applications and data indexing.

Endpoint format

Your TRON gRPC endpoints are available at:

• Mainnet: tron-mainnet.core.chainstack.com:443
• Nile Testnet: tron-nile.core.chainstack.com:443

Authentication

gRPC endpoints use x-token authentication. Pass your token in the request metadata:

• x-token — your authentication token from the Chainstack console

Find your gRPC endpoint and x-token in the Chainstack console under your TRON node’s Access and credentials section.

Available services

The TRON proto files define several gRPC services. Here’s what a Chainstack TRON node currently serves:

Service	Status on Chainstack
protocol.Wallet	Available — the full node API: accounts, blocks, contracts, and transaction operations
protocol.Database	Available — block metadata helpers
protocol.WalletSolidity	Available — the solidity node API: read-only access to solidified (confirmed) data
protocol.WalletExtension	Not available yet
protocol.Monitor	Not available yet

Both protocol.Wallet and protocol.WalletSolidity run on the same endpoint and port. Select the one you need by the service (stub) in your generated client, not by a different URL:

• Wallet — the latest state and all write operations
• WalletSolidity — solidified (confirmed), read-only data

This differs from self-hosted java-tron, which splits the two across separate gRPC ports (50051 for the full node and 50061 for the solidity node); Chainstack routes both through the single :443 endpoint.

Calling a service that isn’t served — protocol.WalletExtension or protocol.Monitor — returns the gRPC UNIMPLEMENTED status (Method not found). The same solidified data is also available over the HTTP /walletsolidity API — see TRON methods.

The endpoint supports gRPC server reflection, but the reflection list includes every service in the TRON protos — including ones that aren’t served, such as protocol.WalletExtension and protocol.Monitor. Don’t infer availability from reflection or the proto definitions; the table above reflects actual behavior.

Proto files

The endpoint supports server reflection for discovery, but to generate typed clients you need the protocol buffer definitions. Get them from the official TRON protocol repository:

git clone https://github.com/tronprotocol/protocol.git

The main service definitions are in:

• api/api.proto — Wallet service with methods like GetNowBlock, GetBlockByNum, GetAccount
• core/Tron.proto — Core data types (blocks, transactions, accounts)

Generate client code

To use gRPC with TRON, generate client code from the proto files.

Python

Install dependencies and generate the Python stubs:

pip install grpcio grpcio-tools

# Clone proto files
git clone https://github.com/tronprotocol/protocol.git
mkdir -p googleapis/google/api

# Download Google API dependencies
curl -sL https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/annotations.proto \
  -o googleapis/google/api/annotations.proto
curl -sL https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto \
  -o googleapis/google/api/http.proto

# Generate Python code
python -m grpc_tools.protoc \
  -I./protocol \
  -I./googleapis \
  --python_out=./generated \
  --grpc_python_out=./generated \
  $(find ./protocol -name "*.proto")

Node.js

Install dependencies:

npm install @grpc/grpc-js @grpc/proto-loader

Clone the proto files:

git clone https://github.com/tronprotocol/protocol.git

Go

Install the protoc compiler and Go plugins:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Clone and generate:

git clone https://github.com/tronprotocol/protocol.git

protoc --go_out=. --go-grpc_out=. \
  -I./protocol \
  protocol/api/api.proto protocol/core/Tron.proto

Usage examples

Python

import grpc
import sys
sys.path.insert(0, './generated')

from api import api_pb2, api_pb2_grpc

ENDPOINT = "tron-mainnet.core.chainstack.com:443"
X_TOKEN = "YOUR_X_TOKEN"

def get_now_block():
    # Create secure channel with TLS
    credentials = grpc.ssl_channel_credentials()
    channel = grpc.secure_channel(ENDPOINT, credentials)

    # Create stub
    stub = api_pb2_grpc.WalletStub(channel)

    # Add x-token to metadata
    metadata = [("x-token", X_TOKEN)]

    # Call GetNowBlock
    response = stub.GetNowBlock(
        api_pb2.EmptyMessage(),
        metadata=metadata,
        timeout=15
    )

    print(f"Block number: {response.block_header.raw_data.number}")
    print(f"Transactions: {len(response.transactions)}")

    channel.close()

get_now_block()

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const path = require('path');

const ENDPOINT = 'tron-mainnet.core.chainstack.com:443';
const X_TOKEN = 'YOUR_X_TOKEN';

// Load proto files
const packageDefinition = protoLoader.loadSync(
  path.join(__dirname, 'protocol/api/api.proto'),
  {
    keepCase: true,
    longs: String,
    enums: String,
    defaults: true,
    oneofs: true,
    includeDirs: [
      path.join(__dirname, 'protocol'),
      path.join(__dirname, 'googleapis')
    ]
  }
);

const proto = grpc.loadPackageDefinition(packageDefinition);

// Create credentials with TLS
const credentials = grpc.credentials.createSsl();

// Create client
const client = new proto.protocol.Wallet(ENDPOINT, credentials);

// Add x-token to metadata
const metadata = new grpc.Metadata();
metadata.add('x-token', X_TOKEN);

// Call GetNowBlock
client.GetNowBlock({}, metadata, (error, response) => {
  if (error) {
    console.error('Error:', error);
    return;
  }
  console.log('Block number:', response.block_header.raw_data.number);
  console.log('Transactions:', response.transactions.length);
});

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/metadata"

    // Import your generated proto packages
    pb "your-module/api"
)

const (
    endpoint = "tron-mainnet.core.chainstack.com:443"
    xToken   = "YOUR_X_TOKEN"
)

func main() {
    // Create TLS credentials
    creds := credentials.NewTLS(nil)

    // Connect to gRPC endpoint
    conn, err := grpc.Dial(endpoint, grpc.WithTransportCredentials(creds))
    if err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer conn.Close()

    // Create client
    client := pb.NewWalletClient(conn)

    // Add x-token to context
    ctx := metadata.AppendToOutgoingContext(
        context.Background(),
        "x-token", xToken,
    )

    // Call GetNowBlock
    response, err := client.GetNowBlock(ctx, &pb.EmptyMessage{})
    if err != nil {
        log.Fatalf("GetNowBlock failed: %v", err)
    }

    fmt.Printf("Block number: %d\n", response.BlockHeader.RawData.Number)
    fmt.Printf("Transactions: %d\n", len(response.Transactions))
}

where YOUR_X_TOKEN is your authentication token from the Chainstack console.

For the full list of available gRPC methods, see the official TRON gRPC documentation.

TronWeb.js

TronWeb is the official JavaScript library for TRON. It supports all TRON operations including contract deployment and transactions.

Get balance

const { TronWeb } = require('tronweb');

const tronWeb = new TronWeb({
    fullHost: 'YOUR_CHAINSTACK_ENDPOINT'
});

const address = 'TWiEv2wfqQ8FkbAJ6bXt1uA2Uav9ZWvXip';

async function getBalance() {
    try {
        const balanceInSun = await tronWeb.trx.getBalance(address);
        const balanceInTRX = tronWeb.fromSun(balanceInSun);

        console.log(`Address: ${address}`);
        console.log(`Balance in SUN: ${balanceInSun}`);
        console.log(`Balance in TRX: ${balanceInTRX}`);
    } catch (error) {
        console.error('Error getting balance:', error);
    }
}

getBalance();

where YOUR_CHAINSTACK_ENDPOINT is your TRON node base endpoint without the /jsonrpc, /wallet, or /walletsolidity postfixes.

Deploy a contract

const { TronWeb } = require('tronweb');

const tronWeb = new TronWeb({
    fullHost: 'YOUR_CHAINSTACK_ENDPOINT',
    privateKey: 'YOUR_PRIVATE_KEY'
});

// Contract ABI and bytecode
const abi = [/* your contract ABI */];
const bytecode = 'your_contract_bytecode';

async function deployContract() {
    try {
        console.log('Deploying contract...');
        console.log('From address:', tronWeb.defaultAddress.base58);

        const transaction = await tronWeb.transactionBuilder.createSmartContract({
            abi: abi,
            bytecode: bytecode,
            feeLimit: 100000000,
            callValue: 0,
            userFeePercentage: 100,
            originEnergyLimit: 10000000
        }, tronWeb.defaultAddress.base58);

        const signedTx = await tronWeb.trx.sign(transaction);
        const result = await tronWeb.trx.sendRawTransaction(signedTx);

        if (result.result) {
            console.log('Contract deployed!');
            console.log('Transaction ID:', result.txid);
            console.log('Contract address:', tronWeb.address.fromHex(result.transaction.contract_address));
        }
    } catch (error) {
        console.error('Deployment error:', error.message || error);
    }
}

deployContract();

where

• YOUR_CHAINSTACK_ENDPOINT — your TRON node base endpoint without the /jsonrpc, /wallet, or /walletsolidity postfixes
• YOUR_PRIVATE_KEY — the private key of the account that you use to deploy the contract

See also node access details.

web3.py

web3.py performs read operations on TRON through the /jsonrpc endpoint. For contract deployment and transactions, use TronWeb.js.

Build DApps using web3.py and TRON nodes deployed with Chainstack.

1. Install web3.py.

2. Connect over HTTP.

HTTP

Use the HTTPProvider to connect to your node endpoint and get the latest block number.

Key protected

from web3 import Web3

web3 = Web3(Web3.HTTPProvider('YOUR_CHAINSTACK_ENDPOINT'))
print(web3.eth.block_number)

from web3 import Web3

web3 = Web3(Web3.HTTPProvider('https://%s:%s@%s'% ("USERNAME", "PASSWORD", "HOSTNAME")))
print(web3.eth.block_number)

where YOUR_CHAINSTACK_ENDPOINT is your node HTTPS endpoint with the /jsonrpc postfix, protected either with the key or password.

See also node access details.

Hardhat

Hardhat performs read operations on TRON through the /jsonrpc endpoint. For contract deployment, use the hybrid workflow or TronWeb.js directly.

Configure Hardhat to compile contracts and perform read operations through your TRON nodes.

1. Install Hardhat and create a project.

2. Create a new environment in hardhat.config.js:

   require("@nomiclabs/hardhat-waffle");
   ...
   module.exports = {
     solidity: "0.8.19",
     networks: {
       tron: {
           url: "YOUR_CHAINSTACK_ENDPOINT",
       },
     }
   };
   

   where YOUR_CHAINSTACK_ENDPOINT is your node HTTPS endpoint with the /jsonrpc postfix, protected either with the key or password. See node access details.

3. Compile your contracts with npx hardhat compile, then deploy using TronWeb.js.

Foundry

Foundry performs read operations on TRON through the /jsonrpc endpoint. For contract deployment, use the hybrid workflow below.

1. Install Foundry.

2. Use --rpc-url to run read operations through your Chainstack node.

Cast

Use cast to query the network.

To get the latest block number:

cast block-number --rpc-url YOUR_CHAINSTACK_ENDPOINT

To get an account balance:

cast balance 0xYOUR_HEX_ADDRESS --rpc-url YOUR_CHAINSTACK_ENDPOINT

where YOUR_CHAINSTACK_ENDPOINT is your node HTTPS endpoint with the /jsonrpc postfix, protected either with the key or password.

Hybrid workflow

Use Foundry for fast compilation and testing, then deploy to TRON with TronWeb.js.

Set up the project

1. Initialize a Foundry project:

   forge init my-tron-project
   cd my-tron-project
   

2. Write your contract in src/:

   // src/MyContract.sol
   // SPDX-License-Identifier: MIT
   pragma solidity ^0.8.19;
   
   contract MyContract {
       string public message;
   
       constructor(string memory _message) {
           message = _message;
       }
   
       function setMessage(string memory _message) public {
           message = _message;
       }
   }
   

3. Compile with Foundry:

   forge build
   

   The compiled artifacts are in out/MyContract.sol/MyContract.json.

Deploy with TronWeb.js

1. Install TronWeb:

   npm init -y
   npm install tronweb
   

2. Create a deployment script deploy.js:

   const { TronWeb } = require('tronweb');
   const fs = require('fs');
   
   const tronWeb = new TronWeb({
       fullHost: 'YOUR_CHAINSTACK_ENDPOINT',
       privateKey: 'YOUR_PRIVATE_KEY'
   });
   
   // Load Foundry artifacts
   const artifact = JSON.parse(
       fs.readFileSync('./out/MyContract.sol/MyContract.json', 'utf8')
   );
   
   async function deploy() {
       try {
           console.log('Deploying from:', tronWeb.defaultAddress.base58);
   
           const transaction = await tronWeb.transactionBuilder.createSmartContract({
               abi: artifact.abi,
               bytecode: artifact.bytecode.object,
               feeLimit: 150000000,
               callValue: 0,
               userFeePercentage: 100,
               originEnergyLimit: 10000000,
               parameters: ['Hello TRON!']  // Constructor arguments
           }, tronWeb.defaultAddress.base58);
   
           const signedTx = await tronWeb.trx.sign(transaction);
           const result = await tronWeb.trx.sendRawTransaction(signedTx);
   
           if (result.result) {
               console.log('Contract deployed!');
               console.log('Transaction ID:', result.txid);
               console.log('Contract address:', tronWeb.address.fromHex(result.transaction.contract_address));
           }
       } catch (error) {
           console.error('Error:', error.message || error);
       }
   }
   
   deploy();
   

3. Run the deployment:

   node deploy.js
   

where

• YOUR_CHAINSTACK_ENDPOINT — your TRON node base endpoint without the /jsonrpc, /wallet, or /walletsolidity postfixes
• YOUR_PRIVATE_KEY — the private key of the account that you use to deploy the contract

See also node access details.