For anyone who wants to research Polymarket on their own — run the CLI yourself, or install skills for Claude / Cursor / OpenClaw and let AI run the tools. Read-only public APIs. No API keys. No signing.

中文说明

Full index: docs/toolbox.md

git clone https://github.com/runesleo/polymarket-toolkit.git && cd polymarket-toolkit
./bin/pm profile 0x63ce342161250d705dc0b16df89036c8e5f9ba9a

What you get: LB PnL snapshot + first-page positions. For audit-grade PnL, use the polymarket-pnl skill.

V2 merge/split broken? → docs/v2-ctf-ops-faq.md + ./bin/pm v2-check 0x…

Node 22+ (uses --experimental-strip-types). From repo root:

./bin/pm help
./bin/pm profile 0x63ce342161250d705dc0b16df89036c8e5f9ba9a
./bin/pm profile Theo4 --json
./bin/pm brier 0x63ce342161250d705dc0b16df89036c8e5f9ba9a
./bin/pm redeem 0x63ce342161250d705dc0b16df89036c8e5f9ba9a 25
./bin/pm markets --limit 5 --active
./bin/pm activity 0x63ce342161250d705dc0b16df89036c8e5f9ba9a --type TRADE --max-pages 5

Prefer ./bin/pm from repo root (no install step). Or: npm run pm -- profile … · optional npm link for global pm.

Audit-grade PnL (Python): python3 skills/polymarket-pnl/compute_precise_pnl.py --address …

Zero-dependency helpers in src/index.ts. Run demos with Node 22+:

npx tsx examples/01-fetch-gamma-markets.ts
node --experimental-strip-types examples/01-fetch-gamma-markets.ts

• Examples: examples/ — one numbered script per API pattern
• Cookbook: docs/cookbook.md — bilingual recipes

Install: cp -R skills/polymarket-profile ~/.claude/skills/ (same for OpenClaw).
polymarket-pnl also needs: pip install httpx

Skill details: skills/*/SKILL.md · long-form docs in sections below.

This repo never holds keys or sends transactions. For normal redemption, use the official Polymarket app.

New to Polymarket? Sign up via the link above (affiliate disclosure: the author may earn referral rewards; no extra cost to you).

Building your own order executor using this repo? Default builder attribution lives in src/builder.ts (opt-out via env). See builder attribution. Read-only CLI/skills do not send orders today.

• pm CLI — profile · activity · scan · updown · v2-check · brier · redeem · markets
• Activity cap detection — duplicate-page warnings near ~4000 rows
• V2 CTF FAQ — docs/v2-ctf-ops-faq.md (split/merge/convert · infra alignment)
• Market scanner · crypto updown fields · handoff template — toolbox.md

New public helper: redeem watchdog — inspect redeemable positions without private keys.

Polymarket's pUSD-era redemption flow handles normal user redemption inside the official app. This release does not replace or work around that flow. It adds a read-only status lane for agents and dashboards: which wallet still has rows surfaced as redeemable=true by the public Data API, what their currentValue is (winning rows pay out, losing rows pay $0), and whether a strategy account is below a configured cash watermark. v0.4 adds fetchRedeemablePositionsPage, summarizeRedeemablePositions, and resolveRedeemMode for that workflow. It never signs or sends transactions.

import {
  fetchRedeemablePositionsPage,
  summarizeRedeemablePositions,
} from "./src/index.ts";

const positions = await fetchRedeemablePositionsPage("0x...");
console.log(summarizeRedeemablePositions(positions as never[]));

Also: pm CLI (toolbox drawers) — see docs/toolbox.md.

New Skill: polymarket-pnl — Audit-grade PnL via Data API cashflow reconstruction.

Most profilers (including polymarket-profile) use position-level cashPnL which is an approximation. polymarket-pnl replays every BUY / SELL / REDEEM / MERGE / SPLIT / REBATE event and reconciles against current unrealized position value. Validated against Polymarket's official /profit endpoint on the public leaderboard: MAPE ~0.2%, all top accounts within 1% error. Use this when the number has to hold up to scrutiny.

Inspect redeemable positions for a public proxy wallet without touching keys, allowances, relayers, or transactions.

• Redeemable scan — fetchRedeemablePositionsPage(user) calls Data API /positions?redeemable=true
• Condition rollup — summarizeRedeemablePositions(rows) groups rows by conditionId and sums currentValue (losing rows contribute $0, which is the correct payable amount — not their size)
• Policy label — resolveRedeemMode({ lowWatermark }) returns "watchdog" or "low_watermark". There is intentionally no "active" value: this toolkit never executes a redeem, so an active label belongs in your own wallet system, not here.

npx tsx examples/15-redeem-watchdog.ts 0x63ce342161250d705dc0b16df89036c8e5f9ba9a 25

{
  "mode": "low_watermark",
  "redeemableCount": 3,
  "conditionCount": 3,
  "estimatedRedeemableValue": 0,
  "topConditions": [
    { "conditionId": "0x...", "slug": "btc-updown-5m-1771773600", "count": 1, "estimatedCurrentValue": 0 }
  ]
}

Three rows surfaced as redeemable=true but every currentValue is 0 — they are losing tokens that redeem to $0. The Data API still surfaces them after resolution; the helper reports them honestly without inflating payable value.

This toolkit only reads public APIs. It does not redeem tokens, sign Safe transactions, call relayers, move funds, or require private keys. The official Polymarket app remains the right place for normal user redemption. Treat this helper as a dashboard/agent primitive; execution stays in your own wallet system.

Turn any Polymarket address into a complete trading profile.

• PnL Overview — Total profit/loss, 7d/30d trends
• Win Rate — Accurate settlement-based calculation (not position-level approximation)
• Open Positions — Current holdings with unrealized PnL and expiry dates
• Activity Breakdown — TRADE / SPLIT / MERGE / REDEEM volume with full pagination
• Category Distribution — Where the money goes: Crypto, Politics, Sports, Weather, etc.
• Top Wins & Losses — Best and worst settled positions
• Strategy Pattern — Auto-detected: Market Maker, SPLIT Arbitrage, Diversified, Whale, etc.

The skill instructs your AI agent to call Polymarket's public APIs (lb-api, data-api, gamma-api), process the data, and output a structured profile. No API key needed, no local database, no setup.

You: Profile this Polymarket address: 0x63ce342161250d705dc0b16df89036c8e5f9ba9a

AI: Fetching data... (paginating 12 pages of activity)

    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      Polymarket Profile: 0x8dxd
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    📊 Overview
      Total PnL:  $2,382,780.64
      Win Rate:   6/11 (54.5%)
      ...

    🎯 Strategy: Market Maker (high-frequency, concentrated in Crypto)
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Claude Code:

# Copy the skill to your skills directory
cp -R skills/polymarket-profile ~/.claude/skills/

OpenClaw:

cp -R skills/polymarket-profile ~/.openclaw/skills/

Any other AI agent: Just paste the content of skills/polymarket-profile/SKILL.md into your conversation and ask your AI to follow the instructions.

• An AI agent that can run curl commands
• Internet access to Polymarket APIs (some endpoints may need a proxy in certain regions)
• That's it. No API keys, no database, no dependencies.

New to Polymarket? Create an account here.

Username lookup works for all leaderboard-ranked users (auto-resolved via lb-api). Unranked accounts (zero trading history) require the 0x address directly.

All public, no authentication required:

• Username → address auto-resolution works for leaderboard-ranked users only (unranked accounts need 0x address)
• Category mapping uses Gamma API tags + keyword fallback (not 100% accurate)
• Top Wins/Losses uses position-level cashPnl (approximate, not per-trade)
• Large accounts (10K+ trades) may take 30+ seconds to paginate
• lb-api 7d/30d PnL may return empty for inactive accounts
• Activity API ~4000 row cap: continuing pagination may return identical JSON — use pm activity / fetchActivityPages or polymarket-pnl with pagination_incomplete

Rate any trader's prediction accuracy with Brier Score — the standard metric used by Metaculus, Good Judgment Project, and forecasting research.

You: What's the Brier Score for Theo4?

AI: Fetching settled positions...

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    Brier Score: Theo4
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  📊 Prediction Accuracy
    Brier Score:      0.12 (Good)
    Settled Markets:  36
    Correct:          29/36 (81%)

  📐 Calibration
    | Confidence | Positions | Forecast | Actual | Gap  |
    |------------|-----------|----------|--------|------|
    | High       | 12        | 87%      | 83%    | -4%  |
    | Moderate   | 15        | 68%      | 67%    | -1%  |
    | Coin flip  | 6         | 52%      | 50%    | -2%  |
    | Contrarian | 3         | 28%      | 33%    | +5%  |

# Claude Code
cp -R skills/polymarket-brier ~/.claude/skills/

# OpenClaw
cp -R skills/polymarket-brier ~/.openclaw/skills/

After installation: "What's the Brier Score for 0x63ce..." or "How accurate is Theo4's predictions?"

New to Polymarket? Create an account here.

Audit-grade PnL for any Polymarket address via Data API cashflow reconstruction. Replays every BUY / SELL / REDEEM / MERGE / SPLIT / REBATE event and reconciles against current unrealized position value.

Position-level cashPnL (what most profilers surface) is rounded at the position level and drops partial fills, making it approximate. polymarket-pnl walks the full activity log — every trade event, every REDEEM, every MERGE — and computes PnL from the cashflow identity:

PnL = SUM(SELL + REDEEM + MERGE + REBATE) - SUM(BUY + SPLIT) + unrealized_position_value

Validated on Polymarket's own leaderboard: precise_pnl matches the official /profit endpoint within 0.2% MAPE on top traders.

You: Compute precise PnL for the top 10 leaderboard addresses.

AI: Fetching leaderboard... (10 addresses)
    Processing 0x56687bf447... (15,993 trades)
    ...

    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      Benchmark: Precise PnL vs Leaderboard (official /profit)
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      ✅ 0x56687bf447... precise=$22,032,643.17  official=$22,053,933.75  err=0.1%
      ✅ 0x1f2dd6d473... precise=$16,580,235.20  official=$16,619,506.63  err=0.2%
      ...

      MAPE: 0.2%  |  <10%: 10/10  |  <30%: 10/10

# Claude Code
cp -R skills/polymarket-pnl ~/.claude/skills/
pip install httpx  # the only runtime dependency

# OpenClaw
cp -R skills/polymarket-pnl ~/.openclaw/skills/
pip install httpx

# Single address
python3 compute_precise_pnl.py --address 0x63ce342161250d705dc0b16df89036c8e5f9ba9a

# Bulk over the leaderboard
python3 compute_precise_pnl.py --leaderboard 50 -o top50.jsonl

# Benchmark a local PnL dataset vs. recomputed precise PnL
python3 compute_precise_pnl.py --leaderboard 100 \
  --benchmark local_pnl.jsonl \
  -o benchmark.jsonl

Output is JSONL with one record per address. See skills/polymarket-pnl/SKILL.md for the full output schema.

• polymarket-profile — curl-only, qualitative profile (win rate, positions, categories). Best for "who is this address?"
• polymarket-pnl — Python + audit-grade cashflow reconstruction. Best for "what is their real PnL?" — writing research, benchmarking a model, or building a dataset.

New to Polymarket? Create an account here.

Strategy validation docs from hypothesis → tiny-live (MIT templates):

Also: fee-inclusive-pnl.md · full index: toolbox.md

Templates are document skeletons; runnable paper/live execution code lives in your own repo.

Analysis Tools

• PnL Calculator — Cashflow-reconstructed PnL, ~0.2% MAPE vs. official leaderboard
• Brier Score Rating — Prediction quality scoring per address
• pm profile CLI — Quick address snapshot
• Trading Style Tags — Conservative / Aggressive / Event-driven / Market Maker labels

Market Intelligence

• Market Scanner Lite — pm scan (24h volume + spread)
• Crypto updown fields — pm updown + docs/crypto-updown-price-source.md
• Market Liquidity Gauge — Depth / maker concentration (deeper)
• LP Reward Scanner — Incentive programs / APY estimate

Platform / V2

• V2 CTF split/merge FAQ + pm v2-check (read-only)
• Activity API cap warnings

Validation templates

• Strategy handoff — docs/templates/handoff-template.md
• Backtest report — docs/templates/backtest-report-template.md
• Paper checklist — docs/templates/paper-checklist.md
• Live gate 12 steps — docs/templates/live-gate-checklist.md
• Platform change runbook — docs/templates/platform-change-runbook.md

Tracking & Alerts

• Leaderboard Tracker Lite — pm lb + snapshot diff
• fee-inclusive PnL guide — docs/fee-inclusive-pnl.md + pm pnl-check
• Whale Alert — Large position changes from top traders
• Redeem Watchdog — public redeemable-position status for agent dashboards

API (planned)

• REST API for all tools above — integrate Polymarket intelligence into your own apps

Leo (@runes_leo) — AI × Crypto independent builder. Trading on Polymarket, building data and trading systems with Claude Code and Codex.

leolabs.me — writing · community · open-source tools · indie projects · all platforms.

X Subscription — paid content weekly, or just buy me a coffee 😁

Learn in public, Build in public.

Affiliate disclosure: Polymarket signup links in this repo may earn referral rewards; unrelated to MIT toolkit functionality.