Token Holder Clustering Script

Description

Build a Python script that analyzes the holder distribution of a given ERC-20 token and clusters holders into behavioral categories: whale, retail, bot/MEV, and liquidity provider. Should use transaction frequency, volume patterns, and known contract identification to classify holders.

Requirements

• Python script with configurable token address
• Classify holders into whale/retail/bot/LP categories
• Use transaction patterns and volume analysis
• Output CSV and JSON with holder classifications

Acceptance Criteria

• Correctly identifies known whales and LPs
• Processes tokens with up to 10K holders
• Runs in under 5 minutes for typical tokens
• Includes visualization of holder distribution