CSV format for crypto payouts: build a file that never fails

In a batch payout, the CSV is the payload. Everything downstream, including the amounts, the fee and the transaction itself, is derived from it. A clean file makes the rest of the process uneventful, and an untidy one produces exactly the kind of quiet error that is only noticed when someone says they were not paid.

The good news is that the requirements are minimal. A payout file is one of the simplest data structures in finance: a list of addresses. The discipline is in resisting the temptation to make it more than that.

Treat the file as generated output from your source of truth, not as a document people edit by hand every month. If contractor records live in a system, export from there. Hand-maintained payout sheets accumulate errors over time.

A single column of addresses is enough. Add a header row if you like, since parsers can detect and skip it, but do not add anything else to that row. The second useful column is a label: a name, an employee reference, or an invoice number.

Do not include an amount column when you are running an equal split, because the amount is derived from the total and the recipient count. Including one invites confusion about which number wins.

Do not include a totals row at the bottom. A totals row is a spreadsheet convention, and to a parser it looks like one more recipient with a nonsense address. If you are lucky it fails validation. If the cell happens to be empty it may silently inflate your recipient count and shrink everyone's share.

Save the file as CSV with UTF-8 encoding. Spreadsheet applications sometimes default to a regional encoding that mangles non-Latin characters in labels, and while that does not affect the addresses, it makes your history unreadable for the people whose names got corrupted.

Watch for autocorrect. Word processors and some spreadsheet configurations replace straight quotes with curly ones and can insert non-breaking spaces. A non-breaking space inside an address is invisible on screen and fatal to validation, so trimming should handle all Unicode whitespace rather than just the plain space character.

Beware of scientific notation. Spreadsheets aggressively reformat anything that looks numeric. Addresses start with a letter so they are safe, but numeric labels such as invoice references can be silently transformed. Format label columns as text before pasting.

Tron mainnet addresses in the base58 format begin with T and are thirty four characters. They carry a checksum, so a single mistyped character produces an address that fails validation rather than one that quietly points somewhere else. This is a meaningful safety property and your tooling should use it.

Validation should also reject the hex form unless your tool explicitly supports it, reject addresses from other networks such as anything beginning with 0x, and report the row number of every failure so you can fix the source file rather than guessing.

An address that passes validation is well formed, not necessarily correct. Checksums catch typos; they cannot tell you that row twelve holds the wrong person's wallet. Only a confirmation step with the recipient can do that.

Duplicate addresses are ambiguous by nature. Sometimes a row was pasted twice. Sometimes one person is being paid for two roles and genuinely expects two shares. A tool that silently deduplicates will quietly underpay the second case, and one that silently accepts duplicates will overpay the first.

The right behaviour is to surface duplicates during review and let a human decide. Show which rows collide and what the resulting total for that address would be.

The same principle applies to blank rows and to rows where the label is present but the address is missing. Report, do not guess.

Before uploading, write down how many people you expect to pay. After parsing, compare that number to what the tool reports. This single check catches truncated exports, hidden filtered rows, accidental deletions and stray trailing lines, and it takes five seconds.

Hidden rows deserve special mention. If you filter a spreadsheet and export, some applications export everything and some export only what is visible. Neither behaviour is wrong, but assuming the wrong one will change who gets paid.

Make the count check part of the routine rather than something you do when you feel uncertain. Controls only work when they are unconditional.

For short lists, typing or pasting addresses directly is faster and involves fewer moving parts than producing a file. A good interface accepts one address per line, allows an optional label after a separator, and runs exactly the same validation as the file path.

Manual entry is also the natural way to handle a one-off correction, such as re-paying a single recipient whose earlier payment went to a stale address.

The trade-off is repeatability. A file can be regenerated and diffed against last month's; a hand-typed list cannot. For recurring payroll, prefer the file.

Before you sign, run through the same short list every time. Confirm the file came from your source of truth. Confirm the row count matches expectation. Confirm every address validated. Confirm duplicates were reviewed deliberately. Confirm the network selected in the tool matches the wallet. Confirm the total and the per-recipient share look sane.

None of these steps is clever, and that is the point. Payout errors are rarely caused by exotic problems; they are caused by ordinary ones that nobody checked for.

Store the exact file you used alongside the batch record. When a question arises later, the ability to show precisely what was uploaded settles it immediately.