Proportional Holder Payout Tool

WHAT IT DOES

Proportional Holder Payout Tool lets you distribute a payout token proportionally to all holders of a target token based on their holdings at a specific snapshot block. Instead of manually collecting addresses and calculating amounts, you specify the target token (the token being held), the payout token (the token you want to distribute), and a snapshot block number. The tool scans the blockchain to find all holders of the target token at that block, computes each holder's proportional share of the payout token based on their balance relative to the total supply, and distributes the payout token in a single batched transaction via the BotGentz sender contract. This is ideal for protocol rewards, dividend distributions, or community acknowledgments.

HOW TO USE

Connect your EVM wallet and select the network. Enter the target token address (the token whose holders you want to reward), the payout token address (the token you are distributing), and the snapshot block number. Click "Scan holders" to fetch all holders of the target token at the specified block—the tool scans Transfer events to reconstruct balances and displays the total supply and number of unique holders. Review the results, then click "Execute payout". The tool computes each holder's proportional share, approves the sender contract to spend the payout token, and distributes the tokens in one batch transaction.

TECHNICAL MECHANISM

The tool reconstructs holder balances at the snapshot block by scanning all Transfer events from block 0 up to the snapshot block using an adaptive chunking strategy—when an RPC endpoint hits a block range limit, the tool halves the chunk size and retries, ensuring the scan completes even on restrictive providers. For each Transfer event, it updates the sender and receiver balances in a local map, filtering out zero-balance addresses. It then computes the total supply of the target token at the snapshot. For each holder, it calculates the payout amount as (holder_balance / total_supply) * payout_token_balance. The tool uses the BotGentz sender contract's transferMultipleERC20 function to batch all transfers, and checks that the native balance covers the sender contract's fee.

WHAT IT CANNOT SEE

This tool cannot distribute to holders who have zero balance at the snapshot—they are automatically filtered out. It relies on accurate holder data from the target token contract; tokens with transfer fees, rebasing mechanics, or non-standard balance logic (e.g., tokens that update balances in hooks) may produce inaccurate results. The tool does not support tokens with dynamic total supply or tokens that use a different balance accounting method. Gas costs scale with the number of unique holders, which can be significant for tokens with many holders. The tool also cannot distribute to holders who are not represented in the Transfer event logs (e.g., genesis allocations).

PLEASE NOTE

The snapshot block must be in the past and accessible to the RPC provider. The tool uses Transfer events to reconstruct balances, which may be slow for tokens with a long history—use a block number that is not too far in the past for better performance. The BotGentz sender contract charges a fee in native tokens (ETH, BNB, MATIC, etc.)—ensure you have enough native balance to cover the fee. This tool is for EVM chains only and does not support non-EVM networks.