## When to Use

**Trigger phrases:**
- "What are the whales doing?"
- "Check whale activity on ETH/BTC"
- "Are whales accumulating or distributing?"
- "Any large wallet movements?"
- "What's the on-chain signal?"
- "Run a whale scan"

**Automatic triggers (no user prompt needed):**
- Every 60 minutes during market-active hours (via heartbeat)
- Before placing a Simmer/Polymarket bet (pre-bet whale sanity check)
- When fear/greed index crosses a threshold (corroboration)

## CLI Commands

### `whalecli scan` — One-shot whale analysis

Events (one JSON per line):
- `stream_start` — stream initialized
- `whale_alert` — score exceeded threshold
- `whale_activity` — activity detected below threshold
- `heartbeat` — periodic health check
- `stream_end` — clean shutdown

### `whalecli wallet` — Manage tracked wallets

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success (alerts found or scan complete) |
| 1 | No alerts (scan ran but nothing above threshold) |
| 2 | API error (rate limit, invalid key) |
| 3 | Network error (timeout, connection refused) |
| 4 | Data error (invalid address, wallet not found) |

## Scoring Algorithm

4-dimension whale scoring (0–100 points):

- **Net Flow (0–40):** USD net flow with log10 scaling, wallet age weighting
- **Velocity (0–25):** Current activity vs 30-day baseline (log2 ratio)
- **Correlation (0–20):** Peer wallet direction agreement (min 2 peers)
- **Exchange Flow (0–15):** CEX address registry lookup + direction match

**Interpretation:**
- 80–100: Strong whale signal (high confidence)
- 60–79: Moderate activity (worth monitoring)
- 40–59: Low activity (noise)
- 0–39: Minimal (ignore)

## Agent Integration Pattern

## FearHarvester Integration

The closed loop: Fear & Greed → Whale Signal → Simmer Bet

# Initialize config (creates ~/.config/whalecli/config.toml)
whalecli config init

# Set API key (free tier: 5 req/sec)
whalecli config set api.etherscan_api_key YOUR_KEY

# Add a whale wallet
whalecli wallet add 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --label "vitalik.eth" --chain ETH

# Scan all wallets (last 24h)
whalecli scan --format json

# Stream real-time alerts (JSONL, one event per line)
whalecli stream --chain ETH --interval 60

{
  "scan_id": "scan_20260222_103015_a1b2",
  "chain": "ETH",
  "window_hours": 4,
  "wallets": [
    {
      "address": "0xd8dA...",
      "label": "vitalik.eth",
      "score": 82,
      "direction": "accumulating",
      "score_breakdown": {
        "net_flow": 35,
        "velocity": 20,
        "correlation": 15,
        "exchange_flow": 12
      },
      "net_flow_usd": 15000000,
      "tx_count": 12
    }
  ],
  "summary": {
    "total_wallets": 5,
    "accumulating": 3,
    "distributing": 1,
    "neutral": 1,
    "avg_score": 65
  },
  "alerts_triggered": 2
}

whalecli wallet add 0x... --label "whale1" --chain ETH
whalecli wallet list --format json
whalecli wallet remove 0x...
whalecli wallet import wallets.csv

whalecli alert set --score 75 --webhook https://example.com/hook
whalecli alert set --threshold 1000000 --window 1h
whalecli alert list --format json

whalecli config init
whalecli config set api.etherscan_api_key YOUR_KEY
whalecli config show

import subprocess, json

def whale_scan(chain="ETH", hours=4, threshold=70):
    """Run whale scan and return parsed results."""
    result = subprocess.run(
        ["whalecli", "scan", "--chain", chain,
         "--hours", str(hours), "--threshold", str(threshold),
         "--format", "json"],
        capture_output=True, text=True, timeout=30
    )
    if result.returncode == 2:
        raise RuntimeError(f"API error: {result.stderr}")
    if not result.stdout.strip():
        return {"wallets": [], "alerts_triggered": 0}
    return json.loads(result.stdout)

# Example: pre-bet whale check
scan = whale_scan(chain="ETH", hours=4)
if scan["summary"]["accumulating"] > scan["summary"]["distributing"]:
    print("Whales accumulating — bullish signal")