Token Snapshotter

WHAT IT DOES

Token Snapshotter captures a complete picture of token holder balances at a specific block in the past or at the latest block. Enter a token contract address and optionally a block number, and the tool reconstructs the balance of every holder at that exact point in blockchain history. It displays the token name, symbol, decimals, total supply at the snapshot block, total number of unique holders, and a ranked list of holders with their balances and percentage of the total supply. This is essential for airdrops, governance voting weight calculations, and analyzing token distribution over time.

HOW TO USE

Connect your wallet using the BGWallet bridge (MetaMask or any Web3 wallet). Ensure you are on the same network as the token — Ethereum, BNB Chain, Polygon, Arbitrum, Optimism, Base, or any EVM chain. Enter the token contract address in the first input field. Optionally, enter a specific block number to take the snapshot at that point in history — leave empty for the latest block. You can also set a minimum balance threshold to filter out small holders. Click "Take snapshot" to start the analysis. The tool scans all Transfer events up to the specified block, reconstructs balances, and displays the results in a table with balances and percentage of supply. The tool automatically handles large token histories by chunking log requests to respect RPC limits.

TECHNICAL MECHANISM

The tool first reads the token's metadata — name, symbol, decimals, and totalSupply at the snapshot block using the blockTag parameter in ethers. It then constructs a filter for the Transfer event (the only event that changes balances) and fetches all logs from block 0 to the specified snapshot block. Because public RPCs cap the number of blocks that can be queried in a single eth_getLogs request, the tool uses a chunked scanning strategy (PLAYBOOK-C §5.1): it walks forward in configurable chunks (default 100,000 blocks). If a chunk request fails due to RPC limits, the tool halves the chunk size and retries, continuing until the entire range is scanned. For each Transfer log, it parses the from address, to address, and value, and updates an in-memory balance map (subtracting from the sender, adding to the receiver, and skipping the zero address for mints). After processing all logs up to the snapshot block, the map contains the exact balance for each address at that historical moment. Holders are then filtered by the threshold (if set), sorted by balance descending, and displayed with percentage of total supply. The tool does not rely on external indexers — all data comes directly from the blockchain through your wallet provider.

WHAT IT CANNOT SEE

The tool cannot take snapshots at arbitrary past block numbers if the RPC does not support historical state (some lightweight RPCs only serve recent blocks). It cannot detect balances of tokens with privacy features (e.g., Tornado Cash, zk-proofs, or confidential transfers) that hide sender, receiver, or amount. It cannot accurately handle tokens with dynamic supply changes such as rebasing tokens (e.g., Ampleforth) or tokens with reflection mechanisms (e.g., Safemoon) where balances change automatically with every transaction. It cannot export snapshots in external formats like CSV or JSON beyond the on-screen display — you would need to copy the data manually. It cannot take snapshots of ERC-721 or ERC-1155 tokens. It cannot show the transaction history for each holder or provide any analysis beyond the snapshot data. The tool is read-only and does not sign any transactions.

PLEASE NOTE

This tool works exclusively on EVM-compatible chains (Ethereum, BNB Chain, Polygon, Arbitrum, Optimism, Base, Avalanche C-Chain, Fantom, and others). Solana, Tron, Starknet, SUI, TON, Aptos, Bitcoin, Cosmos, and XRP are not supported. The tool only supports ERC-20 tokens — ERC-721 and ERC-1155 are not supported. Performance depends on the token's transfer history size; tokens with millions of transfers may take longer to scan. The tool does not store any data — all reads happen live from the blockchain through your wallet provider. The tool is provided as-is with no warranty or liability. Always verify contract addresses from trusted sources.