TRON Integration Guide

This tutorial shows how to integrate T402 payments with the TRON blockchain using TRC-20 tokens.

Overview

TRON uses TRC-20 tokens for USDT transfers. The T402 TRON implementation supports:

  • TRC-20 USDT on mainnet and testnets
  • ECDSA secp256k1 signatures
  • Reference-based replay protection

Prerequisites

  • Node.js 18+ or Python 3.10+
  • TRON wallet with testnet USDT
  • Basic understanding of TRON concepts

Network Identifiers

NetworkCAIP-2 Identifier
TRON Mainnettron:mainnet
TRON Nile (Testnet)tron:nile
TRON Shasta (Testnet)tron:shasta

USDT Addresses

NetworkTRC-20 Contract
MainnetTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
NileTXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf

Install Dependencies

npm install @t402/tron @t402/core tronweb

Client Setup

Create a client that can sign TRON payment authorizations.

import { t402Client } from '@t402/core/client';
import { ExactTronScheme, toClientTronSigner } from '@t402/tron';
import TronWeb from 'tronweb';
 
// Create TronWeb instance
const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  privateKey: 'your_private_key_hex',
});
 
// Create TRON signer
const tronSigner = toClientTronSigner({
  tronWeb,
  privateKey: 'your_private_key_hex',
});
 
// Create t402 client
const client = new t402Client()
  .register('tron:mainnet', new ExactTronScheme(tronSigner))
  .register('tron:nile', new ExactTronScheme(tronSigner));

Server Setup

Configure your server to accept TRON payments.

import express from 'express';
import { paymentMiddleware } from '@t402/express';
import { t402ResourceServer, createFacilitatorClient } from '@t402/core/server';
import { registerExactTronServerScheme } from '@t402/tron/exact/server';
 
const app = express();
 
// Create facilitator client
const facilitator = createFacilitatorClient({
  url: 'https://facilitator.t402.io',
});
 
// Create t402 server
const server = new t402ResourceServer(facilitator);
registerExactTronServerScheme(server, {});
 
// Define routes with TRON payment
const routes = {
  '/api/premium/*': {
    accepts: {
      scheme: 'exact',
      network: 'tron:mainnet',
      payTo: 'TYourTronAddress',
      price: '$0.01',
    },
    description: 'Premium API access',
  },
};
 
// Apply middleware
app.use(paymentMiddleware(routes, server));
 
app.get('/api/premium/data', (req, res) => {
  res.json({ data: 'Premium content' });
});
 
app.listen(3000);

Make Payment Requests

import { wrapFetchWithPayment } from '@t402/fetch';
 
const fetchWithPay = wrapFetchWithPayment(fetch, client);
 
// Automatic payment handling
const response = await fetchWithPay('https://api.example.com/api/premium/data', {
  method: 'GET',
});
 
const data = await response.json();
console.log(data);

TRON-Specific Concepts

TRC-20 Transfers

TRON uses TRC-20 tokens (similar to ERC-20). The payment flow:

  1. Client signs a TRC-20 transfer authorization
  2. Authorization includes payment reference for tracking
  3. Facilitator submits the transaction
  4. TRC-20 contract processes the transfer

Address Formats

TRON uses Base58Check addresses starting with T:

import { validateTronAddress, formatAddress } from '@t402/tron';
 
// Validate address
const isValid = validateTronAddress('TT1MqNNj2k5qdGA6nrrCodW6oyHbbAreQ5');
 
// Convert hex to base58
const base58 = formatAddress('41...');

Energy and Bandwidth

TRON transactions consume energy and bandwidth:

import { estimateTransactionFee } from '@t402/tron';
 
const fee = estimateTransactionFee({
  amount: '1000000', // 1 USDT
  network: 'tron:mainnet',
});
// Returns: { energy: 65000, bandwidth: 350, trxFee: '14' }

USDT transfers on TRON are often free for accounts with sufficient frozen TRX for energy/bandwidth.

Payment Reference

Each payment includes a unique reference:

import { generatePaymentReference } from '@t402/tron';
 
const reference = generatePaymentReference();
// Returns: unique hex string for tracking

Testing on Nile Testnet

Get testnet TRX and USDT from the Nile Testnet Faucet.

  1. Configure for testnet:
const routes = {
  '/api/test/*': {
    accepts: {
      scheme: 'exact',
      network: 'tron:nile',
      payTo: 'TYourNileAddress',
      price: '$0.001',
    },
  },
};
  1. Use Nile testnet wallet

  2. Verify transactions on nile.tronscan.org

For browser-based applications:

// Check if TronLink is available
if (typeof window.tronWeb !== 'undefined') {
  const tronWeb = window.tronWeb;
 
  // Request account access
  const address = await tronWeb.request({ method: 'tron_requestAccounts' });
 
  // Create signer from TronLink
  const signer = toClientTronSigner({
    tronWeb,
  });
 
  const client = new t402Client()
    .register('tron:mainnet', new ExactTronScheme(signer));
}

Troubleshooting

Common Issues

IssueSolution
Invalid signatureEnsure private key matches address
Insufficient energyFreeze TRX for energy or pay TRX fee
Invalid address formatUse Base58Check format (starts with T)
Network timeoutUse reliable TRON API endpoint

Error Codes

CodeDescription
BANDWITH_ERRORInsufficient bandwidth
CONTRACT_VALIDATE_ERRORInvalid contract call
SIGERRORSignature verification failed