---
title: "Wallet Intelligence"
description: "Score wallets, detect exploitable patterns, identify bots, and auto-fade bad traders."
icon: "brain"
---

<Note>
  **Pro Feature.** Requires a Pro or Ultra subscription. [Get started at api.mathematicalcompany.com](https://api.mathematicalcompany.com)
</Note>

# Wallet Intelligence

Horizon's wallet intelligence module provides three capabilities built on Polymarket's public Data API:

<CardGroup cols={3}>
  <Card title="Wallet Scoring" icon="star">
    Evaluate any wallet's trading performance and compute a composite score from -1 (terrible) to +1 (excellent).
  </Card>
  <Card title="Adversarial Analysis" icon="crosshairs">
    Detect exploitable patterns in a wallet's trading: timing regularity, sizing predictability, directional bias, and more.
  </Card>
  <Card title="Bot Detection" icon="robot">
    Scan a market to classify wallets as bots vs humans with strategy type identification and confidence scores.
  </Card>
</CardGroup>

---

## Wallet Scoring

Score any wallet's historical trading performance.

```python
import horizon as hz

score = hz.score_wallet("0x1234abcd...")
print(score.composite_score)  # -1 to +1
print(score.win_rate)         # 0.0 to 1.0
print(score.sharpe)           # Sharpe estimate
print(score.total_pnl)       # Cumulative USDC PnL
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `address` | `str` | required | Wallet address (0x...) |
| `limit` | `int` | `500` | Max positions to analyze |

### Score Interpretation

| Composite Score | Interpretation |
|----------------|----------------|
| `> 0.5` | Excellent trader |
| `0.2 to 0.5` | Good trader |
| `-0.2 to 0.2` | Average |
| `-0.5 to -0.2` | Poor trader |
| `< -0.5` | Terrible trader (fade candidate) |

### WalletScore Fields

| Field | Type | Description |
|-------|------|-------------|
| `wallet` | `str` | Wallet address |
| `win_rate` | `float` | Fraction of profitable positions |
| `avg_pnl_pct` | `float` | Average PnL % per position |
| `sharpe` | `float` | Sharpe estimate (PnL% / stddev) |
| `total_pnl` | `float` | Cumulative USDC PnL |
| `trade_count` | `int` | Number of trades |
| `position_count` | `int` | Number of positions analyzed |
| `composite_score` | `float` | -1 (terrible) to +1 (excellent) |

---

## Adversarial Analysis

Detect exploitable patterns in a wallet's trading behavior.

```python
import horizon as hz

report = hz.analyze_wallet("0x1234abcd...")
print(f"Vulnerability: {report.vulnerability_score:.2f}")

for pattern in report.patterns:
    status = "EXPLOITABLE" if pattern.exploitable else "safe"
    print(f"  {pattern.name}: {pattern.value:.2f} [{status}]")
    if pattern.exploitable:
        print(f"    -> {pattern.counter_strategy}")
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `address` | `str` | required | Wallet address |
| `trade_limit` | `int` | `500` | Max trades to analyze |

### Detected Patterns

| Pattern | Metric | Exploitable When | Counter-Strategy |
|---------|--------|-----------------|------------------|
| `timing_regularity` | CV of inter-trade intervals | CV < 0.3 | Front-run before expected trade times |
| `sizing_predictability` | CV of trade sizes | CV < 0.3 | Size counter-trades to match |
| `directional_bias` | Buy ratio (buys/total) | \|ratio - 0.5\| > 0.25 | Fade the dominant direction |
| `reaction_speed` | Median reaction time (seconds) | < 60s | Pre-position before triggers |
| `concentration` | Herfindahl index across markets | > 0.3 | Target concentrated markets |
| `stop_levels` | Density of exit price clusters | > 30% | Hunt stops near cluster levels |

---

## Bot Detection

Scan a market to identify which wallets are bots and classify their strategy type.

```python
import horizon as hz

bots = hz.scan_bots("0xcondition_id_here")
for bot in bots:
    if bot.is_bot:
        print(f"{bot.wallet[:10]}... {bot.strategy_type} "
              f"(confidence={bot.confidence:.0%})")
        for e in bot.evidence:
            print(f" - {e}")
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `condition_id` | `str` | required | Market condition ID |
| `trade_limit` | `int` | `1000` | Max trades to analyze |
| `min_trades` | `int` | `5` | Min trades per wallet |

### Strategy Types

| Type | Description | Key Signals |
|------|-------------|-------------|
| `market_maker` | Provides two-sided liquidity | Balanced buy/sell, regular timing, consistent sizing |
| `grid_bot` | Places orders at regular intervals | Very regular sizing, balanced, moderate frequency |
| `momentum` | Follows price direction | Strong directional bias, high frequency |
| `sniper` | Fast, large, few trades | Sub-second intervals, large sizes, low count |
| `human` | Manual trader | Irregular timing, varied sizes, low frequency |

### BotDetection Fields

| Field | Type | Description |
|-------|------|-------------|
| `wallet` | `str` | Wallet address |
| `is_bot` | `bool` | True if classified as bot (confidence > 0.6) |
| `confidence` | `float` | 0.0 to 1.0 |
| `strategy_type` | `str` | Classification (see table above) |
| `evidence` | `list[str]` | Human-readable reasons |
| `trade_count` | `int` | Number of trades analyzed |
| `avg_interval_seconds` | `float` | Mean time between trades |
| `size_regularity` | `float` | 0 (random) to 1 (identical sizes) |

---

## What's Next?

<CardGroup cols={2}>
  <Card title="Fade a Wallet" icon="arrows-rotate" href="/copy-trading">
    To fade a wallet, use `copy_trades(inverse=True)` on the **Copy-Trading** page. `reverse_copy()` and `reverse_copier()` are convenience wrappers around this.
  </Card>
  <Card title="Deep Profiling" icon="fingerprint" href="/wallet-profiler">
    **Wallet Profiler** builds on `score_wallet()` with 4-dimensional behavioral analysis (temporal, market selection, order flow, edge) and automatic strategy generation.
  </Card>
</CardGroup>

<Warning>
  Wallet intelligence uses Polymarket's public Data API. Results are based on historical behavior and may not predict future performance. Use responsibly and ethically - these tools are designed for competitive market analysis, not harassment or manipulation.
</Warning>
