crypto-whale-tracker

# 🐋 Crypto Whale Tracker

Track massive crypto transfers in real-time. Know what the whales are doing before the market reacts.

## Quick Start

```bash
# Track whale transfers above 100 BTC
bash scripts/whale_tracker.sh --coin BTC --threshold 100

# Monitor ETH whales with custom timeframe
bash scripts/whale_tracker.sh --coin ETH --threshold 500 --hours 24

# Generate HTML report
bash scripts/whale_tracker.sh --coin BTC --threshold 50 --format html --output whale_report.html

# Track specific wallet
bash scripts/whale_tracker.sh --wallet 0xABC123... --chain ethereum
```

## How It Works — Step by Step

### Step 1: Data Collection
The tool queries public APIs (Whale Alert free tier, Etherscan, Blockchair) to fetch recent large transactions. No API key is required for basic usage, but adding one increases rate limits.

### Step 2: Filtering
Transactions are filtered by your specified threshold. Only transfers above the minimum amount are included. Known exchange wallets are labeled automatically.

### Step 3: Classification
Each transfer is classified into categories:
- **Exchange → Exchange**: Likely OTC or internal transfer
- **Exchange → Unknown**: Possible withdrawal (bullish signal)
- **Unknown → Exchange**: Possible deposit for selling (bearish signal)
- **Unknown → Unknown**: Whale-to-whale transfer

### Step 4: Report Generation
Results are formatted into a clean report with:
- Transaction hash and timestamp
- Source and destination (with exchange labels)
- Amount in crypto and estimated USD value
- Movement classification and market signal

## Configuration

| Parameter | Default | Description |
|-----------|---------|-------------|
| `--coin` | BTC | Cryptocurrency to track (BTC, ETH, USDT, etc.) |
| `--threshold` | 100 | Minimum transfer amount |
| `--hours` | 12 | Lookback period in hours |
| `--format` | text | Output format: text, json, html, csv |
| `--output` | stdout | Output file path |
| `--wallet` | - | Track specific wallet address |
| `--chain`...