Integrate USDT BEP-20 payouts on BNB Smart Chain
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 BEP-20 from the sender's wallet straight to the recipients' wallets, so funds never pass through a Volet.com account.
This guide covers BNB Smart Chain Mainnet. For other networks, see TRON and Ethereum.
Before you start
- Sender wallet — MetaMask or another EIP-1193-compatible browser wallet. The examples use MetaMask in Google Chrome.
- Funds in the sender wallet — USDT BEP-20 for the payouts and the processing fee, plus BNB for network fees. You do not need to fund a wallet to build the form: the sender pays when they send a batch.
- Library — ethers.js v6. No Volet.com SDK is required.
- Website — served over HTTPS, or from
localhostduring development. - Backend and database — to store each batch and verify the payouts.
- RPC provider — a BNB Smart Chain node or hosted service for backend verification.
How it works
- The sender fills in the payout form on your website: recipient addresses, USDT amounts, and an optional partner address.
- The sender connects their wallet. Your website never needs their private key.
- Your frontend validates the batch and reads the processing fee from the contract with
previewCommission(). - Your website shows the total of the payouts, the processing fee, the total USDT required, and an estimate of the network fee.
- When the sender confirms, your frontend checks the USDT balance and allowance. If the allowance is too low, the wallet asks the sender to sign an
approve()transaction first. - Your frontend checks the fee, wallet, network and recipients again, then the wallet asks the sender to sign
batchPayout(). - 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 | |
|---|---|
| Network | BNB Smart Chain Mainnet, chain ID 56 (0x38) |
| Payout contract | 0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7 (BscScan) |
| USDT contract | 0x55d398326f99059fF775485246999027B3197955 (Binance-Peg USDT, shown as BSC-USD) |
| USDT decimals | 18 (1 USDT = 10^18 base units) |
| Network fee paid in | BNB |
| Zero address (no partner) | 0x0000000000000000000000000000000000000000 |
The same payout contract address also exists on Ethereum. The two deployments are not interchangeable: always check the wallet's chain ID 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.
The examples on this page include only the functions and events they use. Before you integrate, open the payout contract on BscScan, 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 token decimals, 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 the BNB Smart Chain network fee in BNB for each transaction: the payout, and the approval when one is needed.
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 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
Install ethers.js:
npm install ethers@^6
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 address">
<input name="amount" type="text" placeholder="USDT amount">
</div>
<button id="connect" type="button">Connect wallet</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 bnb-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.
import { ethers } from 'ethers';
const CHAIN_ID = 56n;
const PAYOUT_ADDRESS = '0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7';
const USDT_ADDRESS = '0x55d398326f99059fF775485246999027B3197955';
export const USDT_DECIMALS = 18;
const EXPLORER_TX = 'https://bscscan.com/tx/';
export const PAYOUT_ABI = [
'function usdt() view returns (address)',
'function MAX_BATCH_SIZE() view returns (uint256)',
'function paused() view returns (bool)',
'function previewCommission(uint256 total, uint256 count) view returns (uint256)',
'function previewCommissionSplit(uint256 total, uint256 count, address whiteLabel) view returns (uint256 platformCommission, uint256 partnerShare)',
'function getPartner(address partner) view returns (bool active, uint16 shareBps)',
'function batchPayout(address[] recipients, uint256[] amounts, address whiteLabel)',
'event BatchPayout(address indexed sender, uint256 total, uint256 commission, uint256 partnerShare, uint256 count, address indexed whiteLabel)',
'event PayoutFailed(address[] recipients, uint256[] amounts)',
'event RefundSent(address indexed sender, uint256 amount)',
'event PartnerNotFound(address indexed whiteLabel)',
'event CommissionTransferFailed(address indexed wallet, uint256 amount)'
];
const TOKEN_ABI = [
'function decimals() view returns (uint8)',
'function balanceOf(address owner) view returns (uint256)',
'function allowance(address owner, address spender) view returns (uint256)',
'function approve(address spender, uint256 amount) returns (bool)'
];
export async function connect() {
if (!window.ethereum) throw new Error('Install and unlock MetaMask.');
await window.ethereum.request({ method: 'eth_requestAccounts' });
const provider = new ethers.BrowserProvider(window.ethereum);
if ((await provider.getNetwork()).chainId !== CHAIN_ID) {
throw new Error('Select BNB Smart Chain in your wallet, then connect again.');
}
const signer = await provider.getSigner();
const sender = await signer.getAddress();
const payout = new ethers.Contract(PAYOUT_ADDRESS, PAYOUT_ABI, signer);
// Make sure this deployment pays out the expected token.
const tokenAddress = await payout.usdt();
if (tokenAddress.toLowerCase() !== USDT_ADDRESS.toLowerCase()) {
throw new Error('Unexpected USDT token in the payout contract.');
}
const token = new ethers.Contract(tokenAddress, TOKEN_ABI, signer);
if (Number(await token.decimals()) !== USDT_DECIMALS) {
throw new Error('Unexpected token decimals.');
}
return { sender, payout, token };
}
// Signatures go only to the wallet and network the batch was reviewed with.
async function assertWalletUnchanged(session) {
const [chainId, accounts] = await Promise.all([
window.ethereum.request({ method: 'eth_chainId' }),
window.ethereum.request({ method: 'eth_accounts' })
]);
if (BigInt(chainId) !== CHAIN_ID ||
accounts[0]?.toLowerCase() !== session.sender.toLowerCase()) {
throw new Error('Wallet or network changed. Connect again and review the batch.');
}
}
Call connect() only when the sender selects Connect wallet, never on page load. If the wallet is on another network, ask the sender to switch to BNB Smart Chain.
Step 3: Preview the batch and the fee
Add the validation and preview functions to bnb-payouts.js. quote() turns the form rows into contract arguments in USDT base units and reads the fee, balance and allowance.
function parseRows(rows) {
if (!Array.isArray(rows) || rows.length === 0) {
throw new Error('Add at least one recipient.');
}
const recipients = rows.map((row) => {
if (!ethers.isAddress(row.address)) throw new Error(`Invalid recipient address: ${row.address}`);
const address = ethers.getAddress(row.address);
if (address === ethers.ZeroAddress) throw new Error('The zero address cannot receive a payout.');
return address;
});
const amounts = rows.map((row) => {
if (typeof row.amount !== 'string' || !/^\d+(\.\d{1,18})?$/.test(row.amount)) {
throw new Error(`Invalid USDT amount: ${row.amount}`);
}
const amount = ethers.parseUnits(row.amount, USDT_DECIMALS);
if (amount <= 0n) throw new Error('Each amount must be positive.');
return amount;
});
return { recipients, amounts };
}
export async function quote(session, rows, partnerWallet = null) {
const { payout, token, sender } = session;
const { recipients, amounts } = parseRows(rows);
if (await payout.paused()) throw new Error('The payout contract is paused.');
if (BigInt(recipients.length) > await payout.MAX_BATCH_SIZE()) {
throw new Error('The batch has more recipients than the contract allows.');
}
if (partnerWallet && !ethers.isAddress(partnerWallet)) {
throw new Error('Invalid partner address.');
}
const whiteLabel = partnerWallet ? ethers.getAddress(partnerWallet) : ethers.ZeroAddress;
const total = amounts.reduce((sum, amount) => sum + amount, 0n);
const commission = await payout.previewCommission(total, recipients.length);
const [platformCommission, partnerShare] = await payout.previewCommissionSplit(
total, recipients.length, whiteLabel
);
return {
recipients, amounts, whiteLabel, total, commission,
platformCommission, partnerShare,
required: total + commission,
balance: await token.balanceOf(sender),
allowance: await token.allowance(sender, PAYOUT_ADDRESS)
};
}
Show the sender total, commission and required, formatted with ethers.formatUnits(value, USDT_DECIMALS), together with an estimate of the network fee in BNB. Do not convert amounts with floating-point arithmetic: parseUnits() keeps them exact.
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 BNB Smart Chain addresses that can receive USDT BEP-20.
Step 4: Approve USDT and send the batch
Add the send function to bnb-payouts.js. It checks that nothing changed since the sender reviewed the batch, requests an approval if the allowance is too low, 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 confirmed(tx, message) {
const receipt = await tx.wait();
if (!receipt || receipt.status !== 1) throw new Error(message);
}
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) {
await confirmed(await token.approve(PAYOUT_ADDRESS, current.required), 'USDT approval failed.');
}
// 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 tx = await payout.batchPayout(fresh.recipients, fresh.amounts, fresh.whiteLabel);
return { txid: tx.hash, explorerUrl: EXPLORER_TX + tx.hash };
}
Depending on the existing allowance, the sender signs one or two transactions:
| Existing allowance | Transactions to sign |
|---|---|
| Enough for the batch | Payout |
| Too low | Approval, payout |
The approval covers exactly the amount of this batch, never an unlimited amount. It must be confirmed before the payout transaction; an approve() transaction moves no funds.
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 { ethers } from 'ethers';
import { USDT_DECIMALS, connect, quote, send } from './bnb-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 usdt(units) {
return `${ethers.formatUnits(units, USDT_DECIMALS)} USDT`;
}
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.ethereum?.on?.('accountsChanged', resetSession);
window.ethereum?.on?.('chainChanged', resetSession);
async function onConnect() {
session = await connect();
reviewed = null;
show(`Connected: ${session.sender}`);
}
async function onPreview() {
if (!session) throw new Error('Connect a wallet first.');
reviewed = await quote(session, readRows(), readPartner());
show([
`Payouts: ${usdt(reviewed.total)}`,
`Processing fee: ${usdt(reviewed.commission)}`,
`Total required: ${usdt(reviewed.required)}`
].join(' | '));
}
async function onSend() {
if (!session || !reviewed) throw new Error('Connect a wallet and preview the batch first.');
if (!window.confirm('Send this batch? Your wallet 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.shortMessage ?? 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 and chain ID
- the sender address
- the recipient list and the exact amounts in USDT base units
- the partner address, or the 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 verifies each recipient against the USDT Transfer logs of the transaction. The example below runs in Node.js with ethers v6. It takes the batch from your database, not from the browser.
import { ethers } from 'ethers';
import { PAYOUT_ABI } from './bnb-payouts.js';
const provider = new ethers.JsonRpcProvider(process.env.BSC_RPC_URL);
const PAYOUT_ADDRESS = '0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7';
const USDT_ADDRESS = '0x55d398326f99059fF775485246999027B3197955';
const tokenEvents = new ethers.Interface([
'event Transfer(address indexed from, address indexed to, uint256 value)'
]);
const payoutEvents = new ethers.Interface(PAYOUT_ABI);
export async function verifyPayout(batch) {
const receipt = await provider.getTransactionReceipt(batch.txid);
if (!receipt) return { status: 'pending' };
if (receipt.status !== 1) return { status: 'failed' };
if (receipt.to?.toLowerCase() !== PAYOUT_ADDRESS.toLowerCase() ||
receipt.from.toLowerCase() !== batch.sender.toLowerCase()) {
return { status: 'review', reason: 'Unexpected sender or contract.' };
}
const finalized = await provider.getBlock('finalized');
if (!finalized || receipt.blockNumber > finalized.number) return { status: 'pending' };
const received = new Map();
const failed = [];
let refunded = 0n;
for (const log of receipt.logs) {
const source = log.address.toLowerCase();
if (source === USDT_ADDRESS.toLowerCase()) {
const event = tokenEvents.parseLog(log);
if (event?.name !== 'Transfer') continue;
const to = event.args.to.toLowerCase();
received.set(to, (received.get(to) ?? 0n) + event.args.value);
} else if (source === PAYOUT_ADDRESS.toLowerCase()) {
const event = payoutEvents.parseLog(log);
if (event?.name === 'PayoutFailed') failed.push(...event.args.recipients);
if (event?.name === 'RefundSent') refunded += event.args.amount;
}
}
const expected = new Map();
batch.recipients.forEach((address, i) => {
const key = address.toLowerCase();
expected.set(key, (expected.get(key) ?? 0n) + BigInt(batch.amounts[i]));
});
const results = [...expected].map(([address, amount]) => ({
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,
failed,
refunded: refunded.toString()
};
}
Mark as completed only the recipients with paid: true. For the others, reconcile the PayoutFailed and RefundSent events and check the sender's balance before you pay them in a new batch. Never resend a whole batch automatically.
This check covers the recipient transfers. In production, your backend also checks the transaction input against the saved batch, the partner and fee events, and handles an RPC provider that is unavailable or returns no finality data: keep the batch pending and retry.
Important notes
- Never ask senders for private keys or seed phrases. All signatures happen in the sender's wallet.
- Never request an unlimited USDT approval by default.
- Before each signature, show the payout contract address, the recipients, the processing fee and the network fee estimate.
- The wallet 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
| Problem | Cause | What to do |
|---|---|---|
| "Install and unlock MetaMask" | No EIP-1193 wallet in the browser, or it is locked | Ask the sender to install or unlock the wallet. |
| "Select BNB Smart Chain in your wallet" | The wallet is on another network | Ask the sender to switch to BNB Smart Chain and connect again. Do not request any signature on another network. |
| The sender rejects the connection, approval or payout | The sender canceled the request in the wallet | Keep the batch unsubmitted and show a clear message. |
| "Invalid recipient address" or "Invalid USDT amount" | A form row has an error | Block 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 fee | Show the total required and the BNB needed for network fees. |
| The approval is still pending | The approval transaction is not confirmed yet | Wait for confirmation. Never assume an approval from its transaction hash alone. |
| The payout transaction is still pending | The transaction is not in a finalized block yet | Track the original txid. Do not broadcast the same batch again. |
| The transaction succeeded, but a recipient has no USDT | The payout to that recipient failed | Mark 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 preview | Preview again and ask the sender to review the new totals. |
| "The payout contract is paused" | Payouts are temporarily stopped in the contract | Do not send. Try again later. |
Related
- Send non-custodial crypto payouts — how non-custodial payouts work
- Integrate USDT ERC-20 payouts on Ethereum — the same payout form on Ethereum
- Integrate USDT TRC-20 payouts on TRON — the same payout form on TRON with TronLink
- Pay out from your own wallet — how projects run batch payouts from a wallet they control
- ethers.js v6 documentation — the library used in the examples