polymarket-analyst

name

polymarket-analyst

description

Deep-dive analyst for Polymarket prediction market trader accounts. Use this skill whenever a user wants to: analyze a Polymarket wallet address or username, profile top/winning Polymarket traders, reverse-engineer trading strategies on Polymarket, track whale activity, compute P&L or performance metrics for any trader, compare multiple trader accounts, or understand what makes a profitable Polymarket account. Always trigger when the user mentions "Polymarket", "prediction market trader", "wallet analysis", "whale tracking", "copy trading", or asks about strategy detection on prediction markets. Even if the request sounds like a general research question ("who are the best Polymarket traders?"), use this skill to pull live data instead of guessing.

Polymarket Analyst Skill

Purpose

This skill fetches live on-chain and REST API data for one or more Polymarket trader addresses, computes a comprehensive performance profile, classifies the likely trading strategy, and produces a structured analyst report — all reproducibly and from public data.

Think of it as running a quantitative analyst's playbook on any Polymarket wallet.

---

Quick-start Workflow

1. Parse inputs          →  wallet address(es) from user message
2. Fetch raw data        →  scripts/fetch_trader_data.py
3. Compute metrics       →  scripts/analyze_trader.py
4. Strategy attribution  →  references/strategies.md
5. Generate report       →  structured Markdown output

When the user provides a leaderboard URL, a username, or asks for "top traders", run step 2 with the --leaderboard flag first to discover addresses, then profile each one.

---

Step 1 — Parse Inputs

Extract from the user's request:

• Wallet address(es): 0x... Polygon addresses (case-insensitive)
• Usernames / labels: resolve via the Gamma profile endpoint
• Time window: default = all-time; accept "last 30 days", "2024", etc.
• Market filter: specific event or category (politics, sports, crypto…)
• Mode: single account | compare accounts | leaderboard scan

If no address is provided and the user mentions a leaderboard or "top traders", fetch the public leaderboard automatically (see references/api.md §Leaderboard).

---

Step 2 — Fetch Raw Data

Run the data-fetching script for each address:

python3 scripts/fetch_trader_data.py \
  --address 0xABCD... \
  --output /tmp/polymarket_data/0xABCD \
  [--days 90]          # optional time window in days

This script calls the three Polymarket API surfaces (no auth required for public data — see references/api.md for all endpoints):

Source	What it returns
Data API /activity	All trades with timestamps, sides, prices, amounts
Data API /positions	Open and closed positions with P&L
Data API /portfolio	Aggregated profit, volume, win rate
Gamma API /markets	Market metadata (category, resolution, title)
CLOB API /prices-history	Price time-series for each token traded

The script saves everything to structured JSON under --output:

/tmp/polymarket_data/0xABCD/
  activity.json     # raw trades
  positions.json    # positions with cashout amounts
  portfolio.json    # summary stats
  markets.json      # metadata for each market traded
  prices/           # per-token price history (fetched lazily)

Read references/api.md if you need to call endpoints manually or troubleshoot rate limits.

---

Step 3 — Compute Metrics

Run the analysis script on the fetched data:

python3 scripts/analyze_trader.py \
  --data-dir /tmp/polymarket_data/0xABCD \
  --output   /tmp/polymarket_data/0xABCD/analysis.json

The script computes all metrics defined in references/metrics.md. The output analysis.json has this structure:

{
  "address": "0xABCD...",
  "snapshot_date": "2026-02-17",
  "performance": { ... },
  "behavior": { ... },
  "market_concentration": { ... },
  "timing": { ... },
  "risk": { ... },
  "strategy_signals": { ... }
}

Read references/metrics.md for the full definition of every field.

---

Step 4 — Strategy Attribution

After computing metrics, classify the trader using the decision logic in references/strategies.md. The six canonical Polymarket strategies are:

1. Information Arbitrage — trades correlated with external information events
2. Cross-Platform Arbitrage — exploits price gaps vs. Kalshi, Manifold, etc.
3. High-Probability Bond — buys contracts >$0.88 for near-certain yield
4. Market Making / Liquidity Provision — tight bid-ask, high fill rate
5. Domain Specialist — concentrated in one category with above-average accuracy
6. Speed / News Trading — enters within minutes of breaking news

Read references/strategies.md for the signal thresholds and heuristics that map metric values to each strategy label. A trader may show signals of multiple strategies — report the primary (highest-confidence) one and any secondaries.

---

Step 5 — Generate Report

Produce the analyst report as Markdown. Always use this exact structure:

---

# Polymarket Trader Analysis — {short_address}
**Snapshot:** {date}  |  **Window:** {window}

## Executive Summary
One paragraph: who is this trader, how much have they made, what is their
apparent edge, and what is their primary strategy.

## Performance Metrics

| Metric | Value |
|--------|-------|
| Total Realized P&L | $XXX,XXX |
| Win Rate (closed positions) | XX.X% |
| # Closed Positions | N |
| Avg. Position Size | $XXX |
| Largest Single Win | $XXX,XXX |
| Largest Single Loss | $–XXX |
| Profit Factor | X.X |
| Sharpe Ratio (approx.) | X.X |
| Max Drawdown | –X.X% |
| Avg. Hold Time | X days |

## Market Concentration

List top 5 categories by # of positions and by P&L contribution.
Note whether specialization correlates with better win rate.

## Timing & Entry Patterns

Describe:
- How early does the trader enter vs. market creation date?
- Is there clustering around news events?
- Any time-of-day or day-of-week patterns?

## Position Sizing & Risk Management

Describe Kelly-fraction behavior, whether position sizes grow after wins
(Martingale risk) or stay flat (disciplined), max simultaneous open positions.

## Strategy Attribution

**Primary strategy:** {strategy_name} — confidence: {High/Medium/Low}
**Secondary signals:** {strategy_name}, {strategy_name}

Explain in 2-3 sentences the evidence for the primary strategy label.

## Red Flags / Caveats

Note any signs of lucky variance (few trades, extreme hit-or-miss), potential
insider timing, or data gaps.

## Comparable Accounts

(If running a leaderboard scan) List other wallets with similar profiles.

---
*Data sources: Polymarket Data API, CLOB API, Gamma API (public endpoints).
No private data accessed.*

---

Multi-Account Comparison

When the user asks to compare accounts or scan the leaderboard:

1. Run steps 2–3 for each address (parallelize if possible)
2. Build a comparison table with all key metrics side-by-side
3. Rank accounts by the metric the user cares about (default: total P&L)
4. Identify clusters of similar strategy profiles

---

Error Handling

Situation	Action
Address not found / no trades	Report "No trading history found for {address}"
API rate limit (HTTP 429)	Wait 5 s, retry up to 3 times; if still failing, note partial data
Very few trades (<20)	Warn that metrics may not be statistically significant
Market metadata missing	Use token ID from activity as fallback label
Price history unavailable	Skip timing/entry metrics, note the gap

---

Reference Files

• references/api.md — Full Polymarket API reference (endpoints, params, schemas)
• references/metrics.md — Definition of every computed metric
• references/strategies.md — Strategy classification logic and thresholds

Read the relevant reference file when you need deeper detail on any step.