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

# Wallet Intelligence

> Score wallets, detect exploitable patterns, identify bots, and auto-fade bad traders.

<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 theme={null}
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 theme={null}
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 theme={null}
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>