carlosibcu/polymarket-analyst

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.