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

> Deep behavioral profiling and auto-profit strategies for Polymarket wallets. Analyze timing, market selection, order flow, and edge, then auto-execute.

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

# Wallet Profiler

<Tip>
  **How it relates:** Wallet Profiler builds on [`score_wallet()`](/wallet-intelligence) scoring and extends it with 4-dimensional behavioral analysis and automatic strategy generation. For raw trade data, see [Wallet Analytics](/wallet-analytics). To execute, see [Copy-Trading](/copy-trading).
</Tip>

Goes beyond basic scoring to build a complete behavioral profile of any Polymarket wallet. Analyzes *how* a wallet trades across four dimensions and generates concrete strategies to profit from its patterns.

<CardGroup cols={2}>
  <Card title="Behavioral Profiling" icon="user-magnifying-glass">
    Temporal patterns, market selection, order flow, and edge detection across 20+ metrics.
  </Card>

  <Card title="Strategy Generation" icon="lightbulb">
    Up to 10 rule-based strategies with triggers, sizing, and execution params.
  </Card>

  <Card title="Auto-Execution" icon="bolt">
    One-call `hunt()` or pipeline `hunter()` to profile and trade automatically.
  </Card>

  <Card title="MCP Integration" icon="plug">
    Available as an MCP tool for AI agent workflows.
  </Card>
</CardGroup>

***

## Quick Start

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

# Full profile
profile = hz.profile_wallet("0x1234...")
print(profile.best_strategy)

# Auto-execute best strategy (standalone)
hz.hunt("0x1234...")

# Pipeline mode (inside hz.run)
hz.run(
    markets=["some-market"],
    pipeline=[hz.hunter("0x1234...")],
    interval=30.0,
)
```

***

## Analysis Dimensions

### Temporal Analysis

Answers *when* does the wallet trade?

| Metric            | Description                                                                     |
| ----------------- | ------------------------------------------------------------------------------- |
| Hour distribution | Trade count per hour (0-23 UTC) with peak hour and Shannon entropy              |
| Day distribution  | Day-of-week distribution with weekend ratio                                     |
| Session           | Dominant session: US (13-21 UTC), Asia (0-8), Europe (7-16), or round-the-clock |
| Burst analysis    | Burstiness metric B = (sigma - mu) / (sigma + mu) of inter-trade intervals      |
| Active days       | Percentage of days in the analysis window with at least one trade               |

### Market Selection

Answers *what* does the wallet trade?

| Metric                | Description                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------- |
| Categories            | Inferred from market titles: politics, crypto, sports, economics, entertainment, science |
| Win rate per category | Performance breakdown by category (requires position data)                               |
| Herfindahl index      | Market concentration (0 = diversified, 1 = single market)                                |
| Early entrant score   | Fraction of buys near opening prices (0.45-0.55)                                         |

### Order Flow

Answers *how* does the wallet enter and exit?

| Metric           | Description                                                                       |
| ---------------- | --------------------------------------------------------------------------------- |
| Building style   | `single_entry` / `scaling_in` / `dca` (based on avg buys per market)              |
| Exit style       | `single_exit` / `scaling_out`                                                     |
| Hold time        | Average hours from first buy to first sell per market                             |
| Size trend       | `increasing` / `decreasing` / `stable` (linear regression on chronological sizes) |
| Dip buyer score  | Fraction of buys below market average price (0-1)                                 |
| Rip seller score | Fraction of sells above market average price (0-1)                                |

### Edge Detection

Answers *is the wallet good?* Includes the composite score from [`score_wallet()`](/wallet-intelligence) and extends it with deeper metrics:

| Metric           | Description                                                                |
| ---------------- | -------------------------------------------------------------------------- |
| Timing quality   | Average (current - entry) / entry across positions                         |
| Win rate by size | Win rates for small / medium / large trades (33rd/66th percentile buckets) |
| Streak type      | `streaky` / `mean_reverting` / `random` (lag-1 autocorrelation)            |
| Edge in bps      | Estimated edge derived from average PnL percentage                         |
| Confidence       | 0.1 to 0.9 based on sample size (10+ to 200+ positions)                    |

***

## Strategy Generation

The profiler generates up to 10 rule-based strategies, each with a concrete trigger condition, implementation type, and execution params:

| Strategy                | Trigger                             | Type           |
| ----------------------- | ----------------------------------- | -------------- |
| `fade_loser`            | composite \< -0.3                   | fade           |
| `copy_winner`           | composite > 0.3 + info score > 0.15 | copy           |
| `session_pre_position`  | Bursty + dominant session > 60%     | session\_trade |
| `front_run_timing`      | Timing CV \< 0.3                    | front\_run     |
| `stop_hunt`             | Stop cluster > 30%                  | counter\_trade |
| `fade_direction`        | Directional bias + negative edge    | fade           |
| `copy_best_category`    | Category win rate > 60%             | copy           |
| `concentration_exploit` | HHI > 0.3 + negative score          | fade           |
| `copy_dip_buyer`        | Dip score > 0.6 + positive edge     | copy           |
| `timing_exploit`        | Hour entropy \< 2.0                 | session\_trade |

Each `ProfitStrategy` contains:

| Field           | Description                                                                 |
| --------------- | --------------------------------------------------------------------------- |
| `name`          | Strategy identifier                                                         |
| `description`   | Human-readable explanation                                                  |
| `mechanism`     | How the strategy works                                                      |
| `expected_edge` | `"high"` / `"medium"` / `"low"`                                             |
| `risk_level`    | `"high"` / `"medium"` / `"low"`                                             |
| `confidence`    | 0-1                                                                         |
| `impl_type`     | `"copy"` / `"fade"` / `"front_run"` / `"counter_trade"` / `"session_trade"` |
| `params`        | Execution parameters (inverse, size\_scale, poll\_interval, etc.)           |

***

## Auto-Execution

<Note>
  `hunt()` and `hunter()` use [Copy-Trading](/copy-trading) under the hood - they profile the wallet, pick the best strategy, then delegate to `copy_trades()` / `copy_trader()` with the appropriate params.
</Note>

### `hunt(wallet)`: Standalone

Profiles the wallet, picks the best strategy, and auto-executes via `copy_trades()` with the appropriate params.

```python theme={null}
hz.hunt(
    "0x1234...",
    size_scale=0.5,
    max_position=1000.0,
    exchange="paper",
    dry_run=True,
)
```

### `hunter(wallet)`: Pipeline

Creates a pipeline function that profiles on first call and delegates to `copy_trader()` each subsequent cycle.

```python theme={null}
hz.run(
    markets=["some-market"],
    pipeline=[hz.hunter("0x1234...", size_scale=0.5, dry_run=True)],
    interval=30.0,
)
```

The profile is stored in `ctx.params["wallet_profile"]` for inspection.

***

## MCP Tool

The profiler is available as an MCP tool:

```
profile_wallet(address="0x1234...", trade_limit=500)
```

Returns a flattened dict with all metrics and strategies.

***

## Data Types

| Type                     | Fields                                                                                              |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| `FullWalletProfile`      | wallet, score, analysis, temporal, market\_selection, order\_flow, edge, strategies, best\_strategy |
| `ProfitStrategy`         | name, description, mechanism, expected\_edge, risk\_level, confidence, impl\_type, params           |
| `TemporalProfile`        | hour/day distributions, session, burst, active\_days                                                |
| `MarketSelectionProfile` | categories, concentration, diversity, early entrant                                                 |
| `OrderFlowProfile`       | building/exit styles, hold time, size trend, dip/rip scores                                         |
| `EdgeDetection`          | information score, timing quality, win rate buckets, streaks, edge bps                              |

***

## Algorithms

All analysis is pure Python (no ML dependencies):

| Algorithm                | Purpose                         |
| ------------------------ | ------------------------------- |
| Shannon entropy          | Distribution uniformity         |
| Coefficient of variation | Regularity detection            |
| Linear regression slope  | Size trend detection            |
| Lag-1 autocorrelation    | Streak analysis                 |
| Herfindahl index         | Market concentration            |
| Burstiness metric        | B = (sigma - mu) / (sigma + mu) |
| tanh normalization       | Bounding scores to \[-1, +1]    |
| Keyword matching         | Market category inference       |

<Warning>
  Wallet profiling uses Polymarket's public Data API. Results are based on historical behavior and may not predict future performance. Use responsibly and ethically.
</Warning>