> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://chainstack.com/build-better-with-tron/), and see the official [TRON API reference](https://developers.tron.network/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](#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](#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](#tronwebjs) with the `/wallet` endpoint, or compile and test with Foundry or Hardhat and deploy through the [hybrid workflow](#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](https://ideas.chainstack.com/p/implement-tron-event-plugin).

## 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](https://github.com/tronprotocol/java-tron/issues/6289)), not a Chainstack one. Billing is independent of the node mode — every TRON request is billed as full (1 RU); see [Request units](/docs/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](https://github.com/tronprotocol/java-tron/issues/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](/docs/tron-methods).

<Note>
  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.
</Note>

### 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:

```shell theme={"system"}
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.

<Tabs>
  <Tab title="Python">
    Install dependencies and generate the Python stubs:

    ```shell theme={"system"}
    pip install grpcio grpcio-tools
    ```

    ```shell theme={"system"}
    # 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")
    ```
  </Tab>

  <Tab title="Node.js">
    Install dependencies:

    ```shell theme={"system"}
    npm install @grpc/grpc-js @grpc/proto-loader
    ```

    Clone the proto files:

    ```shell theme={"system"}
    git clone https://github.com/tronprotocol/protocol.git
    ```
  </Tab>

  <Tab title="Go">
    Install the protoc compiler and Go plugins:

    ```shell theme={"system"}
    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:

    ```shell theme={"system"}
    git clone https://github.com/tronprotocol/protocol.git

    protoc --go_out=. --go-grpc_out=. \
      -I./protocol \
      protocol/api/api.proto protocol/core/Tron.proto
    ```
  </Tab>
</Tabs>

### Usage examples

<CodeGroup>
  ```python Python theme={"system"}
  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()
  ```

  ```javascript Node.js theme={"system"}
  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);
  });
  ```

  ```go Go theme={"system"}
  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))
  }
  ```
</CodeGroup>

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](https://developers.tron.network/docs/trons-grpc-calls).

## TronWeb.js

[TronWeb](https://tronweb.network/) is the official JavaScript library for TRON. It supports all TRON operations including contract deployment and transactions.

### Get balance

```js theme={"system"}
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

```js theme={"system"}
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](/docs/manage-your-node#view-node-access-and-credentials).

## web3.py

web3.py performs read operations on TRON through the `/jsonrpc` endpoint. For contract deployment and transactions, use [TronWeb.js](#tronwebjs).

Build DApps using [web3.py](https://github.com/ethereum/web3.py) and TRON nodes deployed with Chainstack.

1. Install [web3.py](https://web3py.readthedocs.io/).

2. Connect over HTTP.

### HTTP

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

<CodeGroup>
  ```python Key protected theme={"system"}
  from web3 import Web3

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

  ```python Password protected theme={"system"}
  from web3 import Web3

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

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](/docs/manage-your-node#view-node-access-and-credentials).

## Hardhat

Hardhat performs read operations on TRON through the `/jsonrpc` endpoint. For contract deployment, use the [hybrid workflow](#hybrid-workflow) or [TronWeb.js](#tronwebjs) directly.

Configure [Hardhat](https://hardhat.org/) to compile contracts and perform read operations through your TRON nodes.

1. Install [Hardhat](https://hardhat.org/) and create a project.

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

   ```javascript theme={"system"}
   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](/docs/manage-your-node#view-node-access-and-credentials).

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](#hybrid-workflow) below.

1. Install [Foundry](https://getfoundry.sh/).

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:

```shell theme={"system"}
cast block-number --rpc-url YOUR_CHAINSTACK_ENDPOINT
```

To get an account balance:

```shell theme={"system"}
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:

   ```shell theme={"system"}
   forge init my-tron-project
   cd my-tron-project
   ```

2. Write your contract in `src/`:

   ```solidity theme={"system"}
   // 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:

   ```shell theme={"system"}
   forge build
   ```

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

### Deploy with TronWeb.js

1. Install TronWeb:

   ```shell theme={"system"}
   npm init -y
   npm install tronweb
   ```

2. Create a deployment script `deploy.js`:

   ```js theme={"system"}
   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:

   ```shell theme={"system"}
   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](/docs/manage-your-node#view-node-access-and-credentials).