Skip to main content

Integrate USDT TRC-20 payouts on TRON

Add a mass payout form to your website: the sender connects their own wallet, enters recipients and USDT amounts, reviews the fee, and signs the batch. The Volet.com payout contract sends USDT TRC-20 from the sender's wallet straight to the recipients' wallets, so funds never pass through a Volet.com account.

This guide covers TRON Mainnet. For other networks, see BNB Smart Chain and Ethereum.

Before you start​

  • Sender wallet — TronLink. The examples use the TronLink extension in Google Chrome, which provides TronWeb to your page once the sender connects.
  • Funds in the sender wallet — USDT TRC-20 for the payouts and the processing fee, plus TRX or staked Energy and Bandwidth for network costs. You do not need to fund a wallet to build the form: the sender pays when they send a batch.
  • Library — no installation for the browser part: TronLink injects TronWeb. The backend example uses the tronweb npm package. No Volet.com SDK is required.
  • Website — served over HTTPS, or from localhost during development.
  • Backend and database — to store each batch and verify the payouts.
  • Blockchain access — a TRON node or a hosted service, such as TronGrid. Public TronGrid endpoints may require an API key and apply rate limits.

How it works​

  1. The sender fills in the payout form on your website: recipient addresses, USDT amounts, and an optional partner address.
  2. The sender connects TronLink. Your website never needs their private key.
  3. Your frontend validates the batch and reads the processing fee from the contract with previewCommission().
  4. Your website shows the total of the payouts, the processing fee, the total USDT required, and an estimate of the network costs.
  5. When the sender confirms, your frontend checks the USDT balance and allowance. If the allowance is too low, TronLink asks the sender to sign an approve() transaction first.
  6. Your frontend checks the fee, wallet, network and recipients again, then TronLink asks the sender to sign batchPayout().
  7. Your backend saves the transaction hash (txid) and verifies each recipient's USDT transfer before marking that payout as completed.

A failed payout to one recipient does not necessarily cancel the others, so a successful transaction does not prove that everyone was paid. See Step 7: Verify each payout.

Payout contract​

Value
NetworkTRON Mainnet, chain ID 0x2b6653dc in TronLink
Payout contractTHwUFuithr9QuTFa4wBjN2zxFWjUrftV84 (TRONSCAN)
USDT contractTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
USDT decimals6 (1 USDT = 1,000,000 base units)
Network costs paid inTRX, or staked Energy and Bandwidth
Zero address (no partner)T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb

Always check the active network and the contract's usdt() result before you request a signature.

The contract provides these functions:

function usdt() external view returns (address);
function MAX_BATCH_SIZE() external view returns (uint256);
function paused() external view returns (bool);
function previewCommission(uint256 total, uint256 count)
external view returns (uint256 commission);
function previewCommissionSplit(uint256 total, uint256 count, address whiteLabel)
external view returns (uint256 platformCommission, uint256 partnerShare);
function getPartner(address partner)
external view returns (bool active, uint16 shareBps);
function batchPayout(
address[] calldata recipients,
uint256[] calldata amounts,
address whiteLabel
) external;

It emits the events BatchPayout, PayoutFailed, RefundSent, PartnerNotFound and CommissionTransferFailed. PayoutFailed lists the recipients and amounts that were not paid.

Check the contract ABI

The examples on this page include only the functions and events they use. Before you integrate, open the payout contract on TRONSCAN, take its full ABI from the Contract tab, and check the function signatures, parameter types and events in your code against it. Before you send real funds, also compare the token address from usdt(), the previewCommission() results and the contract events with this page.

Fees​

The processing fee is 0.1 USDT per recipient in the batch, added on top of the payout amounts. For example, a batch that pays 10, 20 and 30 USDT to 3 recipients needs 60 USDT for the payouts and 0.3 USDT for the fee: 60.3 USDT in total.

Always show the sender the live value from previewCommission() rather than a fee calculated in your code.

The sender also pays TRON network costs (Energy and Bandwidth) for each transaction: the payout, and the approval when one is needed. They are covered by staked resources or burned TRX.

Partner address​

batchPayout() takes a whiteLabel argument for an optional partner wallet that shares the processing fee. A batch works without a partner: pass the TRON zero address.

With a partner, pass its wallet address. getPartner() shows whether the address is an active partner and its share in basis points, and previewCommissionSplit() shows how the fee is split between Volet.com and the partner. The fee the sender pays stays the same: previewCommission() does not depend on the partner.

To register a partner wallet, email [email protected] with the wallet address and the network.

Step 1: Add the payout form​

Add the form controls to your page. Each data-payout-row block is one recipient; add or remove blocks for more recipients.

<input id="partner-wallet" type="text" placeholder="Partner wallet (optional)">
<div data-payout-row>
<input name="address" type="text" placeholder="Recipient TRON address">
<input name="amount" type="text" placeholder="USDT amount">
</div>
<button id="connect" type="button">Connect TronLink</button>
<button id="preview" type="button">Preview payouts</button>
<button id="send" type="button">Send payouts</button>
<pre id="summary"></pre>

Add your own styling, row management, progress indicators and disabled-button states before you put the form into production.

Step 2: Connect the sender wallet​

Create tron-payouts.js, a browser-side module, and start it with the contract configuration and the connection function. Steps 3 and 4 add to the same file.

const TRON_MAINNET = '0x2b6653dc';
const PAYOUT_ADDRESS = 'THwUFuithr9QuTFa4wBjN2zxFWjUrftV84';
const USDT_ADDRESS = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t';
const TRON_ZERO = 'T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb';
// A cap of 300 TRX per transaction, not the expected cost.
const FEE_LIMIT_SUN = 300_000_000;

const PAYOUT_ABI = [
{ type: 'function', name: 'usdt', stateMutability: 'pure', inputs: [], outputs: [{ type: 'address' }] },
{ type: 'function', name: 'MAX_BATCH_SIZE', stateMutability: 'view', inputs: [], outputs: [{ type: 'uint256' }] },
{ type: 'function', name: 'paused', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
{ type: 'function', name: 'previewCommission', stateMutability: 'view', inputs: [{ type: 'uint256', name: 'total' }, { type: 'uint256', name: 'count' }], outputs: [{ type: 'uint256', name: 'commission' }] },
{ type: 'function', name: 'previewCommissionSplit', stateMutability: 'view', inputs: [{ type: 'uint256', name: 'total' }, { type: 'uint256', name: 'count' }, { type: 'address', name: 'whiteLabel' }], outputs: [{ type: 'uint256', name: 'platformCommission' }, { type: 'uint256', name: 'partnerShare' }] },
{ type: 'function', name: 'getPartner', stateMutability: 'view', inputs: [{ type: 'address', name: 'partner' }], outputs: [{ type: 'bool', name: 'active' }, { type: 'uint16', name: 'shareBps' }] },
{ type: 'function', name: 'batchPayout', stateMutability: 'nonpayable', inputs: [{ type: 'address[]', name: 'recipients' }, { type: 'uint256[]', name: 'amounts' }, { type: 'address', name: 'whiteLabel' }], outputs: [] }
];

const USDT_ABI = [
{ type: 'function', name: 'balanceOf', stateMutability: 'view', inputs: [{ type: 'address', name: 'owner' }], outputs: [{ type: 'uint256' }] },
{ type: 'function', name: 'allowance', stateMutability: 'view', inputs: [{ type: 'address', name: 'owner' }, { type: 'address', name: 'spender' }], outputs: [{ type: 'uint256' }] },
{ type: 'function', name: 'approve', stateMutability: 'nonpayable', inputs: [{ type: 'address', name: 'spender' }, { type: 'uint256', name: 'amount' }], outputs: [{ type: 'bool' }] }
];

export async function connect() {
const wallet = window.tron;
if (!wallet?.isTronLink) throw new Error('Install and unlock TronLink.');
const accounts = await wallet.request({ method: 'eth_requestAccounts' });
// Ask TronLink to select TRON Mainnet; the sender may need to confirm.
await wallet.request({ method: 'wallet_switchEthereumChain', params: [{ chainId: TRON_MAINNET }] });

const tronWeb = wallet.tronWeb;
if (!tronWeb?.ready) throw new Error('TronLink did not provide TronWeb.');
const sender = tronWeb.defaultAddress.base58;
if (!sender || !tronWeb.isAddress(sender) || sender !== accounts[0]) {
throw new Error('Unexpected connected TRON address.');
}

const payout = await tronWeb.contract(PAYOUT_ABI, PAYOUT_ADDRESS);
const token = await tronWeb.contract(USDT_ABI, USDT_ADDRESS);

// Make sure this deployment pays out the expected token. TronWeb may return a hex address.
const tokenFromContract = String(await payout.usdt().call());
const tokenAddress = tokenFromContract.startsWith('0x')
? tronWeb.address.fromHex('41' + tokenFromContract.slice(2))
: tokenFromContract.startsWith('41')
? tronWeb.address.fromHex(tokenFromContract)
: tokenFromContract;
if (tokenAddress !== USDT_ADDRESS) throw new Error('Unexpected USDT token in the payout contract.');

return { wallet, tronWeb, sender, payout, token };
}

// Signatures go only to the wallet and network the batch was reviewed with.
async function assertWalletUnchanged(session) {
await session.wallet.request({ method: 'wallet_switchEthereumChain', params: [{ chainId: TRON_MAINNET }] });
if (session.wallet.tronWeb.defaultAddress.base58 !== session.sender) {
throw new Error('Wallet changed. Connect again and review the batch.');
}
}

Call connect() only when the sender selects Connect TronLink, never on page load.

Step 3: Preview the batch and the fee​

Add the validation and preview functions to tron-payouts.js. quote() turns the form rows into contract arguments in USDT base units and reads the fee, balance and allowance.

function toUsdtUnits(text) {
if (typeof text !== 'string' || !/^\d+(\.\d{1,6})?$/.test(text)) {
throw new Error(`Invalid USDT amount: ${text}`);
}
const [whole, fraction = ''] = text.split('.');
const units = BigInt(whole) * 1_000_000n + BigInt(fraction.padEnd(6, '0'));
if (units <= 0n) throw new Error('Each amount must be positive.');
return units;
}

export function formatUsdt(units) {
const fraction = (units % 1_000_000n).toString().padStart(6, '0').replace(/0+$/, '');
return `${units / 1_000_000n}${fraction ? '.' + fraction : ''} USDT`;
}

const toBigInt = (value) => BigInt(value.toString());

export async function quote(session, rows, partnerWallet = null) {
const { tronWeb, sender, payout, token } = session;
if (!Array.isArray(rows) || rows.length === 0) throw new Error('Add at least one recipient.');

if (await payout.paused().call()) throw new Error('The payout contract is paused.');
if (BigInt(rows.length) > toBigInt(await payout.MAX_BATCH_SIZE().call())) {
throw new Error('The batch has more recipients than the contract allows.');
}

const recipients = rows.map((row) => {
if (!row.address.startsWith('T') || !tronWeb.isAddress(row.address) || row.address === TRON_ZERO) {
throw new Error(`Invalid recipient address: ${row.address}`);
}
return row.address;
});
const amounts = rows.map((row) => toUsdtUnits(row.amount));
const whiteLabel = partnerWallet || TRON_ZERO;
if (!tronWeb.isAddress(whiteLabel)) throw new Error('Invalid partner address.');

const total = amounts.reduce((sum, amount) => sum + amount, 0n);
const commission = toBigInt(
await payout.previewCommission(total.toString(), recipients.length).call()
);
const split = await payout.previewCommissionSplit(
total.toString(), recipients.length, whiteLabel
).call();

return {
recipients, amounts, whiteLabel, total, commission,
platformCommission: toBigInt(split.platformCommission),
partnerShare: toBigInt(split.partnerShare),
required: total + commission,
balance: toBigInt(await token.balanceOf(sender).call()),
allowance: toBigInt(await token.allowance(sender, PAYOUT_ADDRESS).call())
};
}

Show the sender total, commission and required, formatted with formatUsdt(), together with an estimate of the network costs. Do not convert amounts with floating-point arithmetic: base units keep them exact.

Check the recipients before signing

A payout sent to a wrong address cannot be canceled or returned. Show the sender every recipient address and amount before they sign, and accept only TRON addresses that can receive USDT TRC-20.

Step 4: Approve USDT and send the batch​

Add the send function to tron-payouts.js. It checks that nothing changed since the sender reviewed the batch, requests an approval if the allowance is too low, waits until the approval is solidified, and then submits batchPayout().

function sameBatch(a, b) {
return a.required === b.required &&
a.whiteLabel === b.whiteLabel &&
a.recipients.length === b.recipients.length &&
a.recipients.every((address, i) => address === b.recipients[i] && a.amounts[i] === b.amounts[i]);
}

async function waitForSolidified(txid) {
for (let attempt = 0; attempt < 30; attempt++) {
const response = await fetch('https://api.trongrid.io/walletsolidity/gettransactioninfobyid', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ value: txid })
});
if (!response.ok) throw new Error('TronGrid is unavailable.');
const info = await response.json();
if (info.id) {
if (info.receipt?.result !== 'SUCCESS') throw new Error('The transaction failed.');
return info;
}
await new Promise((resolve) => setTimeout(resolve, 3000));
}
throw new Error(`Transaction ${txid} is still pending. Check it before retrying.`);
}

export async function send(session, rows, reviewed, partnerWallet = null) {
const { payout, token } = session;

await assertWalletUnchanged(session);
const current = await quote(session, rows, partnerWallet);
if (!sameBatch(current, reviewed)) {
throw new Error('The batch or the fee changed. Review the updated quote.');
}
if (current.balance < current.required) throw new Error('Not enough USDT in the sender wallet.');

if (current.allowance < current.required) {
if (current.allowance > 0n) {
await waitForSolidified(
await token.approve(PAYOUT_ADDRESS, '0').send({ feeLimit: FEE_LIMIT_SUN })
);
}
await waitForSolidified(
await token.approve(PAYOUT_ADDRESS, current.required.toString()).send({ feeLimit: FEE_LIMIT_SUN })
);
}

// The fee can change while the approval confirms. Check again before the payout signature.
await assertWalletUnchanged(session);
const fresh = await quote(session, rows, partnerWallet);
if (!sameBatch(fresh, reviewed) ||
fresh.balance < fresh.required ||
fresh.allowance < fresh.required) {
throw new Error('The fee, balance or allowance changed. Review the batch before retrying.');
}

const txid = await payout.batchPayout(
fresh.recipients, fresh.amounts.map(String), fresh.whiteLabel
).send({ feeLimit: FEE_LIMIT_SUN });
return { txid, explorerUrl: `https://tronscan.org/#/transaction/${txid}` };
}

Depending on the existing allowance, the sender signs one to three transactions:

Existing allowanceTransactions to sign
Enough for the batchPayout
ZeroApproval, payout
Non-zero but too lowAllowance reset to zero, approval, payout

The approval covers exactly the amount of this batch, never an unlimited amount. Each approval must be solidified before the next transaction, which usually takes about a minute; an approve() transaction moves no funds.

FEE_LIMIT_SUN is the most a transaction may spend on network costs (300 TRX), not what it costs. Estimate the Energy a batch needs and set a cap that fits it.

Step 5: Connect the buttons​

Wire the module to the form. Requests to the wallet start only from the sender's clicks, and the recipients and amounts always come from the form.

import { connect, formatUsdt, quote, send } from './tron-payouts.js';

const $ = (selector) => document.querySelector(selector);
let session = null;
let reviewed = null;

function readRows() {
return [...document.querySelectorAll('[data-payout-row]')].map((row) => ({
address: row.querySelector('[name="address"]').value.trim(),
amount: row.querySelector('[name="amount"]').value.trim()
}));
}

function readPartner() {
return $('#partner-wallet').value.trim() || null;
}

function show(text) {
$('#summary').textContent = text;
}

// A quote is valid only for the wallet and network it was made with.
function resetSession() {
session = null;
reviewed = null;
show('Wallet or network changed. Connect again.');
}
window.tron?.on?.('accountsChanged', resetSession);
window.tron?.on?.('chainChanged', resetSession);

async function onConnect() {
session = await connect();
reviewed = null;
show(`Connected: ${session.sender}`);
}

async function onPreview() {
if (!session) throw new Error('Connect TronLink first.');
reviewed = await quote(session, readRows(), readPartner());
show([
`Payouts: ${formatUsdt(reviewed.total)}`,
`Processing fee: ${formatUsdt(reviewed.commission)}`,
`Total required: ${formatUsdt(reviewed.required)}`
].join(' | '));
}

async function onSend() {
if (!session || !reviewed) throw new Error('Connect TronLink and preview the batch first.');
if (!window.confirm('Send this batch? TronLink will ask you to sign each transaction.')) return;
const result = await send(session, readRows(), reviewed, readPartner());
reviewed = null;
show(`Submitted: ${result.explorerUrl}`);
// Send result.txid to your backend together with the batch, then verify it (Step 7).
}

for (const [id, handler] of [['#connect', onConnect], ['#preview', onPreview], ['#send', onSend]]) {
$(id).addEventListener('click', () => {
handler().catch((error) => show(error.message ?? String(error)));
});
}

If the sender edits the form after the preview, send() stops with "The batch or the fee changed", and the sender previews again.

Step 6: Record the batch​

Store each batch in your backend before the sender signs it, and never overwrite it. Keep:

  • your own batch ID
  • the network
  • the sender address
  • the recipient list and the exact amounts in USDT base units
  • the partner address, or the TRON zero address
  • the quoted processing fee
  • the approval transaction hashes, if any
  • the payout transaction hash (txid)
  • the final status of each recipient

batchPayout() does not accept a batch ID, so the link between your batch and its transaction exists only in your database. Use it to prevent duplicates: if a transaction is still pending, track its txid and do not send the same batch again.

Step 7: Verify each payout​

A transaction hash shows only that the batch was submitted. A successful receipt or a BatchPayout event also does not prove that every recipient was paid: a failed payout to one recipient does not necessarily cancel the others, and the contract reports it with PayoutFailed and may refund the sender with RefundSent.

Your backend reads the solidified transaction data from a SolidityNode:

POST https://api.trongrid.io/walletsolidity/gettransactionbyid
POST https://api.trongrid.io/walletsolidity/gettransactioninfobyid

Both take the transaction hash in the body: {"value": "<txid>"}.

Then it verifies each recipient against the USDT Transfer events of the transaction. The example below runs in Node.js with the tronweb package. It takes the batch from your database, not from the browser.

import { TronWeb } from 'tronweb';

const tronWeb = new TronWeb({ fullHost: 'https://api.trongrid.io' });
const PAYOUT_ADDRESS = 'THwUFuithr9QuTFa4wBjN2zxFWjUrftV84';
const USDT_ADDRESS = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t';
// keccak256('Transfer(address,address,uint256)')
const TRANSFER_TOPIC = 'ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';

const hex = (base58) => tronWeb.address.toHex(base58).toLowerCase(); // '41…'

async function solidity(method, txid) {
const response = await fetch(`https://api.trongrid.io/walletsolidity/${method}`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'TRON-PRO-API-KEY': process.env.TRONGRID_API_KEY
},
body: JSON.stringify({ value: txid })
});
if (!response.ok) throw new Error('TronGrid is unavailable.');
return response.json();
}

export async function verifyPayout(batch) {
const [tx, info] = await Promise.all([
solidity('gettransactionbyid', batch.txid),
solidity('gettransactioninfobyid', batch.txid)
]);
if (!info.id) return { status: 'pending' };
if (info.receipt?.result !== 'SUCCESS') return { status: 'failed' };

const call = tx.raw_data?.contract?.[0]?.parameter?.value;
if (call?.owner_address?.toLowerCase() !== hex(batch.sender) ||
call?.contract_address?.toLowerCase() !== hex(PAYOUT_ADDRESS)) {
return { status: 'review', reason: 'Unexpected sender or contract.' };
}

// Log addresses come without the 41 prefix.
const usdtLogAddress = hex(USDT_ADDRESS).slice(2);
const received = new Map();
for (const log of info.log ?? []) {
if (log.address?.toLowerCase() !== usdtLogAddress || log.topics?.[0] !== TRANSFER_TOPIC) continue;
const to = '41' + log.topics[2].slice(24);
received.set(to, (received.get(to) ?? 0n) + BigInt('0x' + log.data));
}

const expected = new Map();
batch.recipients.forEach((address, i) => {
const key = hex(address);
expected.set(key, (expected.get(key) ?? 0n) + BigInt(batch.amounts[i]));
});

const results = [...expected].map(([address, amount]) => ({
address: tronWeb.address.fromHex(address),
expected: amount.toString(),
received: (received.get(address) ?? 0n).toString(),
paid: received.get(address) === amount
}));

return {
status: results.every((result) => result.paid) ? 'paid' : 'partial',
results
};
}

Mark as completed only the recipients with paid: true. For the others, look up the PayoutFailed and RefundSent events of the transaction, for example on TRONSCAN, and check the sender's balance before you pay them in a new batch. Never resend a whole batch automatically.

A transaction that is not solidified yet is pending, not failed: keep the batch pending and retry. This check covers the recipient transfers. In production, your backend also checks the transaction input against the saved batch and the partner and fee events. See TRON confirmation semantics for how solidification works.

Important notes​

  • Never ask senders for private keys or seed phrases. All signatures happen in TronLink.
  • Never request an unlimited USDT approval by default.
  • Before each signature, show the payout contract address, the recipients, the processing fee and the network cost estimate.
  • TronLink is the last approval step. Verifying the result is the responsibility of your application.
  • Confirmed blockchain transactions cannot be canceled or reversed.

If something goes wrong​

ProblemCauseWhat to do
"Install and unlock TronLink"TronLink is not installed in the browser, or it is lockedAsk the sender to install or unlock TronLink.
TronLink asks to switch the networkThe wallet is not on TRON MainnetAsk the sender to confirm the switch. Do not request any signature on another network.
The sender rejects the connection, approval or payoutThe sender canceled the request in TronLinkKeep the batch unsubmitted and show a clear message.
"Invalid recipient address" or "Invalid USDT amount"A form row has an errorBlock preview and sending until the sender corrects that recipient.
"Not enough USDT in the sender wallet"The balance is lower than the payouts plus the feeShow the total required and the TRX needed for network costs.
A transaction fails with an out-of-energy errorThe sender has too little TRX or Energy, or the fee limit is too low for the batchAsk the sender to add TRX or stake for Energy, or raise the fee limit for large batches.
"Transaction is still pending"The approval or payout is not solidified yetTrack the original txid. Do not broadcast the same transaction again.
The transaction succeeded, but a recipient has no USDTThe payout to that recipient failedMark only verified transfers as completed. Reconcile the failed recipients and any refund before a new batch.
"The batch or the fee changed"The form, the fee or the partner settings changed after the previewPreview again and ask the sender to review the new totals.
"The payout contract is paused"Payouts are temporarily stopped in the contractDo not send. Try again later.
TronGrid returns errors or rate-limit responsesPublic endpoints without an API key are rate-limitedUse a TronGrid API key or your own node, and retry.