CSV Format for Bulk Token Transfers: Template + Common Errors

The CSV for a bulk token transfer needs exactly two columns — recipient address, then amount — one recipient per line, separated by a comma, with a dot as the decimal separator and no header row. That is the entire format. Download the ready-made template below, replace the placeholder rows with your real addresses, and you are done; the rest of this article exists because spreadsheets fight this simplicity in seven predictable ways, and because ten minutes of file hygiene is cheaper than one mis-sent irreversible transfer.

Download the template

Download the CSV template — three example rows in the correct format:

TYourRecipientAddressHere111111111,100
TYourRecipientAddressHere222222222,25.5
TYourRecipientAddressHere333333333,10

One deliberate safety property: the placeholder addresses are format-shaped (34 characters, starting with T) but not real TRON addresses, so the dApp's validator will reject them on upload. You cannot accidentally send funds to the template — replace every row with real recipients and the file passes.

The format, line by line

Each line is one recipient and follows one rule:

<TRON address>,<amount>

• Address: a TRON base58 address — starts with T, exactly 34 characters. No spaces around it, no quotes.
• Comma: the column separator. One comma per line, nothing else.
• Amount: a plain number. Dot for decimals (25.5), no thousands separators (10000, not 10,000), no currency symbols, no trailing spaces.
• No header row. The first line must already be a real recipient — address,amount as text will be flagged as an invalid address (which is the validator telling you to delete it).
• Duplicates are allowed but meaningful: the same address twice means two transfers to that wallet. Deduplicate first unless that is genuinely what you want.

The same two-column list can also be pasted directly into the dApp as plain text, and XLS/XLSX files with the same two columns work as-is — CSV is simply the most portable of the three.

Exporting from the tools you already use

The format is trivial; exporters are where it goes wrong. The three most common paths:

Google Sheets. Keep addresses in column A, amounts in column B, nothing else on the sheet — no title row, no notes column. Format the amount column as plain number (Format → Number → Number, then strip the thousands separator display; better yet, Format → Number → Plain text after entering values with dot decimals). Export via File → Download → Comma Separated Values. Sheets exports what you see, so if the column displays 10,000, that comma lands in your file.

Excel. The dangerous variable is the system locale: on many European systems Excel writes semicolon-separated "CSV" with comma decimals — a file that looks right and parses wrong. Two fixes: either set the workbook's decimal separator to a dot (Options → Advanced → uncheck "use system separators"), or skip the trap entirely and upload the .xlsx itself, which the dApp accepts with the same two-column layout.

Everything else (Notion, Airtable, a database dump): export whatever the tool produces, then paste the two columns through a plain-text editor once. This strips smart quotes, invisible characters, and rich-text leftovers in one move — ten seconds that regularly saves an upload cycle.

Whatever the path, open the final file once in a text editor, not a spreadsheet. What you see there — commas, dots, no quotes, no header — is exactly what the parser will see.

The seven classic errors

Years of support conversations reduce to this list:

1. Comma decimals. Spreadsheets in many locales (most of Europe, Brazil, and more) write 1,5 for one-and-a-half. In a comma-separated file that reads as two columns — an amount of 1 and garbage after it. Set the amount column's format to use dot decimals before exporting.
2. Thousands separators. 10,000 splits into columns the same fatal way; 10 000 with a space fails number parsing. Amounts must be bare: 10000.
3. A leftover header row. address,amount on line one. Delete it.
4. Whitespace and invisible characters. Addresses copied from chats, Telegram, or web pages arrive wrapped in spaces, tabs, or zero-width characters. The validator flags these, but trimming the column in your spreadsheet first saves a re-upload cycle.
5. Quoted values. Some exporters wrap every cell in quotes ("TAbc...","100"). Most parsers tolerate it, but mixed or stray quotes (a quote inside an address) break lines unpredictably. Export plain, unquoted CSV.
6. Wrong-network addresses. An Ethereum 0x… address or an exchange memo pasted into the address column. TRON addresses start with T and are 34 characters; anything else cannot receive TRC-20 tokens and will be flagged.
7. Base58 typos. A hand-edited address with one wrong character usually fails the checksum and gets flagged — this is the validator working as designed. The dangerous case is a valid address that belongs to the wrong person, which no software can catch: that is what the review screen is for.

Check the file before you send

A ninety-second pre-flight that catches nearly everything:

1. Sort by the address column in your spreadsheet — duplicates become adjacent and obvious, and malformed entries sort to the top or bottom.
2. Check the row count against how many recipients you expect. Off by one usually means a header row or a blank trailing line.
3. Sum the amount column and write the total down. After uploading, the dApp shows the parsed total on the review screen — the two numbers must match exactly. If they differ, a decimal or separator problem slipped through.
4. Skim the parsed list in the dApp. Validation has already flagged malformed addresses and duplicates at this point; your job is the human check — do the names, amounts, and total look like the payout you intended?
5. First time with this list? Send a small test batch to a few rows before the full run, as the step-by-step guide recommends. On-chain transfers are irreversible; rehearsal is the only undo button.

FAQ

Does the file need a specific name or encoding? No specific name. Use plain UTF-8 (what every spreadsheet exports by default). Avoid editors that add a byte-order mark or convert the file to rich text.

Can I use XLS/XLSX instead of CSV? Yes — the dApp accepts CSV, XLS, and XLSX with the same two-column layout, and you can also paste the list as text. CSV survives tool-to-tool transfers with the least surprises, which is why templates ship in it.

How do I put different tokens in one file? You don't — a file is one distribution of one token. The token is selected in the dApp before uploading; run separate batches for separate tokens.

Is there a limit on file size? Practically, no: lists beyond about 150 recipients are simply processed as several consecutive batch transactions in one flow. The fee calculator shows costs for any list size, and the full how-to covers the whole sending process around this file.