Oferta total ERC-20 e saldo da carteira: qual número é seu?

Para um token ERC-20, balanceOf(account) informa o saldo registrado para uma conta. totalSupply() informa a oferta total do contrato do token. Uma oferta grande na página de um token não significa que sua conta tenha uma grande quantidade dele.

Se você abriu um explorador para conferir seus tokens, escolha o saldo da conta. Para saber quantas unidades o contrato informa no total, escolha a oferta. Nenhum desses números, isoladamente, informa um valor em dólares, comprova controle sobre um endereço ou demonstra que um token é seguro.

Um contrato, duas perguntas diferentes

A especificação ERC-20 os define como métodos separados de leitura. totalSupply() não recebe uma conta como entrada. balanceOf precisa do endereço cujo saldo você quer consultar. O contrato do token que você chama determina sobre qual ativo está perguntando.

Leitura	Entrada além do contrato do token	Pergunta respondida
totalSupply()	Nenhuma	Que oferta este contrato informa?
balanceOf(account)	Endereço público da conta	Que saldo ele registra para esta conta?

Imagine, por exemplo, um token com oferta de 1000 unidades, das quais a conta A possui 25. Os resultados corretos são 1000 para a oferta e 25 para a conta A. A diferença é esperada. Não há uma quantidade perdida de 975 unidades para recuperar.

Essas quantidades foram inventadas para a explicação, não são leituras de um token real. Se você não sabe qual endereço identifica a conta e qual identifica o ativo, consulte o guia sobre endereço de carteira e contrato do token antes de ler qualquer um dos campos.

O que muda um saldo e o que muda a oferta?

Considere um token hipotético simples com transferências comuns, sem taxas nem contabilidade personalizada. Comece com 25 tokens na conta A e 975 na conta B:

Evento	Conta A	Conta B	Oferta total
Estado inicial	25	975	1000
A transfere 5 para B	20	980	1000
100 novos tokens são emitidos para B	20	1080	1100
B queima 10 por uma função de queima	20	1070	1090

A transferência muda quem possui as unidades. A emissão cria unidades, e a queima pelo mecanismo ilustrado remove unidades. A referência ERC20 da OpenZeppelin documenta a contabilidade de emissão e queima, incluindo a redução da oferta na queima.

Essa tabela descreve esse modelo simples. Um token pode personalizar transferências ou usar outras regras contábeis. Não considere o envio de tokens para um endereço descrito como “morto” uma prova de que totalSupply() caiu: verifique se o contrato realmente reduz a oferta. Um rótulo no endereço não executa uma função de queima.

Da mesma forma, seu saldo pode permanecer igual enquanto a oferta muda em outro lugar. O guia de oferta da OpenZeppelin explica que o ERC-20 deixa o mecanismo de oferta a cargo das implementações. Uma leitura da oferta atual não comprova que novas emissões futuras sejam impossíveis.

Leia os dois números sem mover tokens

Leia os dois números do mesmo contrato do token na mesma rede. O procedimento abaixo é uma verificação proposta, não um relato de teste de carteira realizado para este artigo. A documentação primária foi consultada em 23 de outubro de 2026.

1. Registre a rede e o endereço completo do contrato do token. Confira o endereço com as informações oficiais de implantação do emissor. Símbolos iguais em redes diferentes não bastam para comparar o mesmo ativo.
2. Registre a conta pública que pretende consultar. Obtenha o endereço nos detalhes dessa conta. Mantenha-o separado do contrato do token. O acompanhamento público também funciona com contas que você não controla, então uma consulta bem-sucedida não comprova propriedade.
3. Abra um explorador ou leitor de contratos confiável para essa rede. Selecione sua interface de leitura para o contrato verificado do token. Leia totalSupply() e depois balanceOf, passando o endereço da conta como entrada. Os rótulos das interfaces variam; use os nomes das funções para identificar as perguntas.
4. Guarde o estado consultado junto com os resultados. Registre o número do bloco quando disponível. Prefira fazer as duas chamadas no mesmo bloco. Leituras separadas de “latest” podem observar estados diferentes se ocorrer uma transferência, emissão ou queima entre elas.
5. Registre as unidades antes de comparar. Preserve as respostas brutas e anote se a interface já as formatou. Uma chamada que falha significa dados indisponíveis, não saldo zero.

A documentação Ethereum sobre ERC-20 ilustra chamadas separadas para oferta e saldo de uma conta. Você não precisa reproduzir a configuração de desenvolvimento dela para entender qual resultado precisa. Um explorador com métodos públicos de leitura pode fornecer as mesmas categorias de informação.

Ler o estado público não exige transferência nem aprovação de tokens. Se uma página pedir uma frase de recuperação ou assinatura para revelar esses valores, pare de usar esse procedimento. Nenhuma delas é uma entrada desta comparação.

Aplique as mesmas unidades aos dois números

Oferta e saldos das contas usam a mesma escala contábil do token. A explicação de decimais da OpenZeppelin trata explicitamente da formatação de ambos. Para um token hipotético com 6 casas decimais verificadas, a oferta bruta 1000000000 representa 1000 tokens e o saldo bruto 25000000 representa 25 tokens.

Não compare oferta bruta com saldo formatado. Não divida um número que a interface já converteu. O guia de casas decimais ERC-20 explica como estabelecer essa escala, a ausência de metadados e o arredondamento. Aqui, aplicar a escala é apenas um requisito para comparar duas medidas diferentes; isso não as torna iguais.

O que um número de oferta não esclarece

O totalSupply() do ERC-20 não é um cálculo padronizado de oferta circulante. Um provedor pode aplicar exclusões ao estimar a circulação. A metodologia dele precisa explicar essas exclusões; não é possível obtê-las apenas renomeando uma resposta do contrato. A oferta máxima é outra questão separada. A OpenZeppelin documenta uma extensão que limita a oferta, mas o ERC-20 não exige que todo token tenha esse recurso.

O resultado também pertence à implantação específica e ao estado que você consultou. Ele não combina automaticamente tokens entre redes, versões encapsuladas ou contratos relacionados. Somar implantações com nomes parecidos pode gerar um número sem significado claro, a menos que a relação e a contabilidade delas sejam estabelecidas separadamente.

Para conferir uma carteira, mantenha um pequeno registro final: rede, contrato do token, conta, bloco, saldo e unidades. Acrescente a oferta somente quando ela responder a uma pergunta separada. Se o saldo da conta for 25 tokens e a oferta do contrato for 1000, guarde os dois rótulos junto com os números. A diferença não significa que faltam tokens na conta.