> ## Documentation Index
> Fetch the complete documentation index at: https://mathematicalcompany.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Whale Galaxy

> Auto-discover, rank, and track best/worst wallets across Polymarket. Detect coordinated trading clusters and whale movements.

<Warning>
  **Ultra Feature.** Requires an Ultra subscription. [Get started at api.mathematicalcompany.com](https://api.mathematicalcompany.com)
</Warning>

# Whale Galaxy

Scans the Polymarket ecosystem to discover, rank, cluster, and track wallets. Automatically identifies smart money, weak hands, and coordinated trading groups, then feeds the best targets into copy-trading or fade strategies.

<Note>
  Galaxy uses [`score_wallet()`](/wallet-intelligence) from Wallet Intelligence internally to rank wallets, and [`copy_trades()`](/copy-trading) from Copy-Trading to execute on targets. It's the top of the wallet analysis progression: [Analytics](/wallet-analytics) → [Intelligence](/wallet-intelligence) → [Profiler](/wallet-profiler) → [Copy-Trading](/copy-trading) → **Galaxy**.
</Note>

<CardGroup cols={2}>
  <Card title="Galaxy Scan" icon="satellite-dish">
    Score and rank wallets across top markets.
  </Card>

  <Card title="Cluster Detection" icon="circle-nodes">
    Pairwise co-trade analysis to find coordinated groups.
  </Card>

  <Card title="Whale Alerts" icon="bell">
    Real-time alerts when high-score wallets make moves.
  </Card>

  <Card title="Auto-Target" icon="bullseye">
    Automatically pick copy/fade targets from scan results.
  </Card>
</CardGroup>

***

## Galaxy Scan

```python theme={null}
import horizon as hz

snapshot = hz.scan_galaxy(top_n=20, max_markets=50)
print(f"Scanned {snapshot.market_count} markets, {snapshot.wallet_count} wallets")
for w in snapshot.top_wallets[:5]:
    print(f"  {w.address[:10]}... score={w.score:.2f} ({w.edge_category})")
```

***

## Cluster Detection

```python theme={null}
clusters = hz.detect_clusters(wallet_trades, window_secs=3600, min_overlap=3)
for c in clusters:
    print(f"  {c.cluster_type}: {len(c.wallets)} wallets, {c.co_trade_count} co-trades")
```

| Cluster Type  | Avg Delay | Interpretation            |
| ------------- | --------- | ------------------------- |
| `copy_chain`  | \< 60s    | One wallet copies another |
| `coordinated` | 60-300s   | Deliberate coordination   |
| `coincidence` | > 300s    | Likely independent        |

***

## Auto-Target

```python theme={null}
target = hz.auto_target(snapshot, strategy="auto")
print(target["mode"])     # "copy" or "fade"
print(target["wallets"])  # best wallet addresses
print(target["reasoning"])
```

***

## Pipeline Mode

```python theme={null}
hz.run(
    name="galaxy-aware-mm",
    markets=["0xcondition..."],
    pipeline=[
        hz.galaxy_tracker(config=hz.GalaxyConfig(
            top_n=20, alert_min_score=0.4,
        ), scan_interval_cycles=100),
        model,
        quoter,
    ],
    interval=5.0,
)
```

Injects `ctx.params["galaxy_snapshot"]` and `ctx.params["galaxy_alerts"]`.

***

## Galaxy Hunt (Standalone)

One-command autonomous mode: scan, pick targets, and start copy-trading.

```python theme={null}
hz.galaxy_hunt(
    top_n=10,
    size_scale=0.5,
    max_position=1000.0,
    exchange="paper",
    dry_run=True,  # preview before going live
)
```

***

## Wallet Categories

| Category      | Score Range | Description                                       |
| ------------- | ----------- | ------------------------------------------------- |
| `smart_money` | > 0.5       | Consistent winners worth copying                  |
| `neutral`     | 0.0 to 0.5  | Average performance                               |
| `weak_hand`   | -0.3 to 0.0 | Below average, potential fade targets             |
| `bot`         | \< -0.3     | Consistently losing, likely bots or noise traders |

***

## GalaxyConfig

| Parameter             | Default  | Description                             |
| --------------------- | -------- | --------------------------------------- |
| `top_n`               | `20`     | Number of top/bottom wallets to return  |
| `min_trades`          | `10`     | Minimum trades to include a wallet      |
| `cluster_window_secs` | `3600.0` | Time window for co-trade detection      |
| `cluster_min_overlap` | `3`      | Minimum shared markets for a cluster    |
| `alert_min_score`     | `0.3`    | Minimum wallet score to generate alerts |
| `alert_min_size_usdc` | `500.0`  | Minimum trade size for alerts           |