---
title: "Galaxy Whale Discovery"
description: "Discover, cluster, and hunt profitable wallets across the Polymarket galaxy."
icon: "satellite"
---

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

Scan the entire Polymarket ecosystem to discover top-performing wallets, detect coordinated trading clusters, and automatically target the best whales for copy trading.

## Full Code

```python
"""Galaxy whale discovery: scan, cluster, and hunt."""

import horizon as hz

# ── Step 1: Scan the galaxy ──
print("Scanning galaxy for top wallets...")
galaxy = hz.scan_galaxy(top_n=20)

print(f"\nTop {len(galaxy.wallets)} wallets:")
for i, wallet in enumerate(galaxy.wallets, 1):
    print(
        f"  {i:2d}. {wallet.address[:10]}... "
        f"score={wallet.score:.0f} "
        f"category={wallet.category} "
        f"roi={wallet.roi:.0%}"
    )

# ── Step 2: Detect clusters ──
print("\nDetecting coordinated clusters...")
clusters = hz.detect_clusters(galaxy)

for cluster in clusters:
    print(f"\n  Cluster: {cluster.label}")
    print(f"    Wallets: {len(cluster.members)}")
    print(f"    Correlation: {cluster.avg_correlation:.2f}")
    print(f"    Combined AUM: ${cluster.combined_aum:,.0f}")
    for addr in cluster.members[:3]:
        print(f"     - {addr[:10]}...")

# ── Step 3: Auto-target ──
print("\nSelecting targets...")
targets = hz.auto_target(
    galaxy,
    min_score=70,
    max_targets=3,
    exclude_bots=True,
)

for t in targets:
    print(f"  Target: {t.address[:10]}... score={t.score:.0f} strategy={t.recommended_strategy}")

# ── Step 4: Autonomous execution ──
print("\nStarting galaxy hunt (dry run)...")
hunt_result = hz.galaxy_hunt(
    targets=targets,
    size_scale=0.3,
    max_position=30.0,
    dry_run=True,       # preview only, no orders
)

for trade in hunt_result.planned_trades:
    print(f"  Would copy: {trade.side} {trade.size:.0f} @ {trade.price:.4f} on {trade.market_id}")

print(f"\nEstimated daily edge: ${hunt_result.estimated_daily_edge:.2f}")
```

## How It Works

1. **`scan_galaxy()`** queries Polymarket for the most active wallets, scores each one, and returns a ranked list with categories (whale, shark, bot, retail)
2. **`detect_clusters()`** finds groups of wallets that trade in coordination (potential insider rings or copy-bot networks)
3. **`auto_target()`** selects the best wallets to copy based on score, excluding bots and already-clustered addresses
4. **`galaxy_hunt()`** executes the copy strategy across all targets; use `dry_run=True` to preview

## Pipeline Mode

Run the galaxy tracker as a continuous pipeline function:

```python
"""Continuous galaxy tracking inside a live strategy."""

import horizon as hz
from horizon.context import FeedData

config = hz.GalaxyConfig(
    scan_interval=300,     # re-scan every 5 minutes
    min_score=70,
    max_targets=3,
    size_scale=0.3,
    exclude_bots=True,
)

tracker = hz.galaxy_tracker(config)


def fair_value(ctx: hz.Context) -> float:
    """Use feed as baseline."""
    feed = ctx.feeds.get("polymarket", FeedData())
    return feed.price if feed.price > 0 else 0.50


hz.run(
    name="galaxy_hunter",
    markets=["election-winner"],
    feeds={
        "polymarket": hz.PolymarketBook("election-winner"),
    },
    pipeline=[fair_value, tracker],
    risk=hz.Risk(max_position=100, max_drawdown_pct=5),
    interval=5.0,
    mode="paper",
)
```

The tracker periodically re-scans the galaxy and injects whale alerts into `ctx.params["whale_alerts"]` for downstream pipeline stages.

## Run It

```bash
python examples/galaxy_whale_hunter.py
```

See [Whale Galaxy](/whale-galaxy) for the full reference.
