Token Holder Snapshot Tool

WHAT IT DOES

Token Holder Snapshot Tool lets you capture a complete list of all holders of any ERC-20 token at a specific block height. You provide the token contract address and optionally a block number, and the tool reads the chain to reconstruct every holder's balance. It processes all Transfer events up to the target block, building a map of addresses and their current token balances. This is essential for airdrop planning, governance voting power calculations, community analysis, and compliance reporting. It reads the current network chain ID from your wallet provider to ensure queries are directed to the correct network.

HOW TO USE

Connect your wallet using the "Connect" button (required for RPC access). Select the target network (Ethereum Mainnet, Sepolia, Polygon, BSC, Arbitrum, Optimism, and testnets are supported). Enter the token contract address and optionally a specific block number (leave empty for the latest block). Set a minimum balance threshold to filter out dust holders. Click "Take snapshot" — the tool will scan the blockchain for all Transfer events, reconstruct balances, and display the list of holders with their balances. Results are shown in a sortable table with links to block explorers.

TECHNICAL MECHANISM

The tool uses eth_getLogs to fetch all Transfer events from the token contract from block 0 to the target block. Because public RPC providers cap the block range per request (often 10,000 blocks), the tool automatically chunks requests into smaller ranges. If a chunk fails due to range limits, it halves the chunk size and retries (PLAYBOOK-C §5.1). This ensures the scan completes even on restrictive RPCs. The tool then processes each Transfer event, updating a balance map: subtracting from the sender and adding to the recipient. Zero balances are pruned to keep the result set clean. The final balances are filtered by the minimum threshold and sorted descending. The entire operation is read-only — no transactions are signed or sent. The tool uses ethers.js v5.7.2 and the wallet's provider for all chain interactions.

WHAT IT CANNOT SEE

The tool cannot verify if the token contract is a valid ERC-20 or if balances are accurate beyond what the contract reports. It cannot detect holders of non-standard tokens or tokens with complex transfer logic (e.g., fee-on-transfer, rebasing, or tokens with custom hooks). It is limited by RPC provider rate limits and eth_getLogs block range caps — scanning very large ranges may be slow or fail on free RPCs. It cannot read holders of tokens deployed before the earliest block the provider allows. It cannot capture balances of tokens that use proxy patterns or custom balance storage. The tool does not detect token approvals or allowances.

PLEASE NOTE

This tool is for educational and analytical purposes. For production use, consider using a dedicated indexing service. The accuracy of the snapshot depends on the completeness of the Transfer event logs — tokens that do not emit Transfer events correctly will not be captured. Always verify the token address and network before running a snapshot. The tool does not persist any data; all state is lost on page reload. EVM chains only.