Formato CSV para transferências de tokens em massa: modelo + erros comuns

O CSV de uma transferência de tokens em massa precisa de exatamente duas colunas — endereço do destinatário e, depois, o valor —, um destinatário por linha, separados por vírgula, com ponto como separador decimal e sem linha de cabeçalho. Esse é o formato inteiro. Baixe o modelo pronto abaixo, substitua as linhas de exemplo pelos seus endereços reais e pronto; o resto deste artigo existe porque as planilhas lutam contra essa simplicidade de sete maneiras previsíveis, e porque dez minutos de higiene do arquivo custam menos que uma única transferência irreversível enviada errado.

Baixe o modelo

Baixar o modelo CSV — três linhas de exemplo no formato correto:

TYourRecipientAddressHere111111111,100
TYourRecipientAddressHere222222222,25.5
TYourRecipientAddressHere333333333,10

Uma propriedade de segurança proposital: os endereços de exemplo têm o formato certo (34 caracteres, começando com T), mas não são endereços TRON reais, então o validador da dApp os rejeita no upload. Não há como enviar fundos ao modelo por acidente — substitua cada linha por destinatários reais e o arquivo passa.

O formato, linha por linha

Cada linha é um destinatário e segue uma regra:

<endereço TRON>,<valor>

• Endereço: um endereço TRON em base58 — começa com T, exatamente 34 caracteres. Sem espaços ao redor, sem aspas.
• Vírgula: o separador de colunas. Uma vírgula por linha, nada mais.
• Valor: um número simples. Ponto para decimais (25.5), sem separador de milhar (10000, não 10,000), sem símbolo de moeda, sem espaços no final.
• Sem linha de cabeçalho. A primeira linha já deve ser um destinatário real — address,amount como texto será marcado como endereço inválido (é o validador avisando para apagá-lo).
• Duplicatas são permitidas, mas têm significado: o mesmo endereço duas vezes significa duas transferências para essa carteira. Remova duplicatas antes, a menos que isso seja realmente o que você quer.

A mesma lista de duas colunas também pode ser colada diretamente na dApp como texto, e arquivos XLS/XLSX com as mesmas duas colunas funcionam do jeito que estão — o CSV é apenas o mais portátil dos três.

Exportando das ferramentas que você já usa

O formato é trivial; é na exportação que tudo dá errado. Os três caminhos mais comuns:

Planilhas Google. Endereços na coluna A, valores na coluna B, nada mais na aba — sem linha de título, sem coluna de anotações. Formate a coluna de valores como número simples (Formatar → Número → Número, depois remova a exibição do separador de milhar; melhor ainda, Formatar → Número → Texto simples depois de digitar os valores com ponto decimal). Exporte por Arquivo → Fazer download → Valores separados por vírgula (.csv). O Planilhas exporta o que você vê: se a coluna mostra 10,000, essa vírgula vai parar no seu arquivo.

Excel. A variável perigosa é a configuração regional do sistema: em muitos sistemas — inclusive os configurados para o Brasil — o Excel grava um "CSV" separado por ponto e vírgula com vírgula decimal, um arquivo que parece certo e é lido errado. Duas soluções: defina o ponto como separador decimal na pasta de trabalho (Opções → Avançado → desmarque "Usar separadores do sistema"), ou evite a armadilha por completo e envie o próprio .xlsx, que a dApp aceita com o mesmo layout de duas colunas.

Todo o resto (Notion, Airtable, um dump de banco de dados): exporte o que a ferramenta gerar e depois passe as duas colunas uma vez por um editor de texto puro. Isso remove de uma vez aspas tipográficas, caracteres invisíveis e restos de texto formatado — dez segundos que frequentemente poupam um novo upload.

Seja qual for o caminho, abra o arquivo final uma vez num editor de texto, não numa planilha. O que você vê ali — vírgulas, pontos, sem aspas, sem cabeçalho — é exatamente o que o parser vai ver.

Os sete erros clássicos

Anos de conversas com o suporte se resumem a esta lista:

1. Vírgula decimal. Planilhas em muitas regiões (a maior parte da Europa, o Brasil e outras) escrevem 1,5 para um e meio. Num arquivo separado por vírgulas, isso vira duas colunas — um valor 1 e lixo depois. Configure a coluna de valores para usar ponto decimal antes de exportar.
2. Separadores de milhar. 10,000 se divide em colunas da mesma forma fatal; 10 000 com espaço falha na leitura do número. Os valores precisam ser limpos: 10000.
3. Uma linha de cabeçalho esquecida. address,amount na primeira linha. Apague-a.
4. Espaços e caracteres invisíveis. Endereços copiados de chats, Telegram ou páginas web chegam com espaços, tabulações ou caracteres de largura zero. O validador os marca, mas limpar a coluna na planilha antes poupa um novo upload.
5. Valores entre aspas. Alguns exportadores colocam cada célula entre aspas ("TAbc...","100"). A maioria dos parsers tolera, mas aspas misturadas ou perdidas (uma aspa no meio de um endereço) quebram linhas de forma imprevisível. Exporte CSV simples, sem aspas.
6. Endereços da rede errada. Um endereço Ethereum 0x… ou um memo de exchange colado na coluna de endereços. Endereços TRON começam com T e têm 34 caracteres; qualquer outra coisa não pode receber tokens TRC-20 e será marcada.
7. Erros de digitação em base58. Um endereço editado à mão com um caractere errado normalmente falha na soma de verificação e é marcado — é o validador funcionando como deveria. O caso perigoso é um endereço válido que pertence à pessoa errada, e nenhum software consegue detectar isso: é para isso que serve a tela de revisão.

Confira o arquivo antes de enviar

Uma checagem de noventa segundos que pega quase tudo:

1. Ordene pela coluna de endereços na planilha — as duplicatas ficam lado a lado e evidentes, e entradas malformadas vão para o topo ou para o fim.
2. Confira a quantidade de linhas com o número de destinatários esperado. Diferença de um geralmente significa linha de cabeçalho ou linha vazia no final.
3. Some a coluna de valores e anote o total. Depois do upload, a dApp mostra o total lido na tela de revisão — os dois números precisam bater exatamente. Se forem diferentes, passou algum problema de decimal ou separador.
4. Passe os olhos na lista lida na dApp. A validação já marcou endereços malformados e duplicatas; o seu trabalho é a checagem humana — os nomes, valores e o total parecem o pagamento que você pretendia fazer?
5. Primeira vez com essa lista? Envie um pequeno lote de teste para algumas linhas antes do envio completo, como recomenda o guia passo a passo. Transferências on-chain são irreversíveis; o ensaio é o único botão de desfazer.

FAQ

O arquivo precisa de nome ou codificação específicos? Nenhum nome específico. Use UTF-8 simples (o que qualquer planilha exporta por padrão). Evite editores que adicionam marca de ordem de bytes (BOM) ou convertem o arquivo em texto formatado.

Posso usar XLS/XLSX em vez de CSV? Sim — a dApp aceita CSV, XLS e XLSX com o mesmo layout de duas colunas, e você também pode colar a lista como texto. O CSV sobrevive à passagem entre ferramentas com menos surpresas, por isso os modelos são distribuídos nesse formato.

Como colocar tokens diferentes num mesmo arquivo? Não dá — um arquivo é uma distribuição de um único token. O token é escolhido na dApp antes do upload; para tokens diferentes, execute lotes separados.

Existe limite de tamanho do arquivo? Na prática, não: listas acima de cerca de 150 destinatários são simplesmente processadas como várias transações em lote consecutivas no mesmo fluxo. A calculadora de taxas mostra custos para qualquer tamanho de lista, e o guia completo cobre todo o processo de envio em torno deste arquivo.