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
| Network | CAIP-2 Identifier |
|---|---|
| TRON Mainnet | tron:mainnet |
| TRON Nile (Testnet) | tron:nile |
| TRON Shasta (Testnet) | tron:shasta |
USDT Addresses
| Network | TRC-20 Contract |
|---|---|
| Mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t |
| Nile | TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf |
Install Dependencies
npm install @t402/tron @t402/core tronwebClient 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:
- Client signs a TRC-20 transfer authorization
- Authorization includes payment reference for tracking
- Facilitator submits the transaction
- 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 trackingTesting on Nile Testnet
Get testnet TRX and USDT from the Nile Testnet Faucet.
- Configure for testnet:
const routes = {
'/api/test/*': {
accepts: {
scheme: 'exact',
network: 'tron:nile',
payTo: 'TYourNileAddress',
price: '$0.001',
},
},
};-
Use Nile testnet wallet
-
Verify transactions on nile.tronscan.org
TronLink Integration
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
| Issue | Solution |
|---|---|
| Invalid signature | Ensure private key matches address |
| Insufficient energy | Freeze TRX for energy or pay TRX fee |
| Invalid address format | Use Base58Check format (starts with T) |
| Network timeout | Use reliable TRON API endpoint |
Error Codes
| Code | Description |
|---|---|
BANDWITH_ERROR | Insufficient bandwidth |
CONTRACT_VALIDATE_ERROR | Invalid contract call |
SIGERROR | Signature verification failed |
Related
- @t402/tron Reference - API documentation
- TRON Network Details - Chain configuration
- Multi-Chain App - Cross-chain integration