whalecli

# WhaleWatch CLI — Agent Skill

Track crypto whale movements. Close the loop from on-chain signal → agent reasoning → prediction market bet.

## Install

```bash
uv pip install whalecli
```

## Quick Start

```bash
# 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
```

## 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

```bash
whalecli scan --chain ETH --hours 4 --threshold 70 --format json
```

**Output (JSON):**
```json
{
  "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 stream` — Real-time JSONL streaming

```bash
whalecli stream --chain ETH --interval 60 --thresh...