Skip to main content

Integrate USDT ERC-20 payouts on Ethereum

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 ERC-20 from the sender's wallet straight to the recipients' wallets, so funds never pass through a Volet.com account.

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

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 ERC-20 for the payouts and the processing fee, plus ETH 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 localhost during development.
  • Backend and database — to store each batch and verify the payouts.
  • RPC provider — an Ethereum Mainnet node or hosted service for backend verification.

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 their wallet. 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 fee.
  5. 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.
  6. Your frontend checks the fee, wallet, network and recipients again, then the wallet 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
NetworkEthereum Mainnet, chain ID 1 (0x1)
Payout contract0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7 (Etherscan)
USDT contract0xdAC17F958D2ee523a2206206994597C13D831ec7
USDT decimals6 (1 USDT = 1,000,000 base units)
Network fee paid inETH
Zero address (no partner)0x0000000000000000000000000000000000000000

The same payout contract address also exists on BNB Smart Chain. 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.

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 Etherscan, 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 Ethereum network fee in ETH 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 ethereum-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 = 1n;
const PAYOUT_ADDRESS = '0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7';
const USDT_ADDRESS = '0xdAC17F958D2ee523a2206206994597C13D831ec7';
export const USDT_DECIMALS = 6;
const EXPLORER_TX = 'https://etherscan.io/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 Ethereum Mainnet 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 Ethereum Mainnet.

Step 3: Preview the batch and the fee​

Add the validation and preview functions to ethereum-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,6})?$/.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 ETH. Do not convert amounts with floating-point arithmetic: parseUnits() keeps 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 Ethereum addresses that can receive USDT ERC-20.

Step 4: Approve USDT and send the batch​

Add the send function to ethereum-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) {
// Ethereum USDT rejects changing a non-zero allowance to another non-zero value.
if (current.allowance > 0n) {
await confirmed(await token.approve(PAYOUT_ADDRESS, 0n), 'Allowance reset failed.');
}
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 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 confirmed before the next 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 './ethereum-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 './ethereum-payouts.js';

const provider = new ethers.JsonRpcProvider(process.env.ETHEREUM_RPC_URL);
const PAYOUT_ADDRESS = '0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7';
const USDT_ADDRESS = '0xdAC17F958D2ee523a2206206994597C13D831ec7';

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​

ProblemCauseWhat to do
"Install and unlock MetaMask"No EIP-1193 wallet in the browser, or it is lockedAsk the sender to install or unlock the wallet.
"Select Ethereum Mainnet in your wallet"The wallet is on another networkAsk the sender to switch to Ethereum Mainnet and connect again. Do not request any signature on another network.
The sender rejects the connection, approval or payoutThe sender canceled the request in the walletKeep 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 ETH needed for network fees.
The approval is still pendingThe approval transaction is not confirmed yetWait for confirmation. Never assume an approval from its transaction hash alone.
The payout transaction is still pendingThe transaction is not in a finalized block yetTrack the original txid. Do not broadcast the same batch 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.