---
title: "Wallet Profiler"
description: "Deep behavioral profiling and auto-profit strategies for Polymarket wallets. Analyze timing, market selection, order flow, and edge, then auto-execute."
icon: "fingerprint"
---

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