# polymarket-toolkit [Health: Active] **Category:** πŸ’» Developer Tools **Repository:** https://github.com/runesleo/polymarket-toolkit **GitHub Stars:** 193 **npm Downloads (last month):** 2 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/polymarket-toolkit ## Description Read-only Polymarket data tools for AI agents: profiles, PnL, market scans. No keys, no orders. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `uvx` (confidence: high): ```json "mcpServers": { "polymarket-toolkit": { "command": "uvx", "args": ["httpx"] } } ``` ## Documentation & README # Polymarket Toolkit **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. > **Nothing to install?** [**probpocket.com/lookup**](https://probpocket.com/lookup/?utm_source=toolkit&utm_content=readme-top) answers the same first question in a browser: paste an address, see lifetime PnL, what the wallet actually makes its money on, and how its leaderboard days compare with its real settled total. Free, no signup. Same public APIs as this CLI. [δΈ­ζ–‡θ―΄ζ˜Ž](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/README.zh.md) Machine-readable product facts: [ai-info.json](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/ai-info.json) Β· [llms.txt](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/llms.txt). Both are generated from `content/ai-identity.json`; `npm run check:ai-discovery` fails on tool, package-version, or output drift. ## Toolbox Β· pick a drawer | I want to… | Start here | |------------|------------| | **Research an address** | `pm profile ` Β· skills `polymarket-profile` / `polymarket-pnl` / `polymarket-brier` | | **See whether they actually cash out** | `pm cashflow ` β€” on-chain pUSD withdrawals, separated from trade settlement | | **Check execution quality** | `pm markout ` β€” markout vs market baseline (adverse selection) | | **Classify a trader** | `pm mix ` β€” passive market maker or aggressive taker | | **Scan markets & prices** | `pm markets` Β· [`examples/01,09,11`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/examples/) Β· [`docs/cookbook.md`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/cookbook.md) | | **Wire my own data pipeline** | [`src/index.ts`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/src/index.ts) Β· cookbook Β· `examples/14` | | **Validation checklists** | [`docs/templates/`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/templates/) β€” handoff Β· backtest Β· paper Β· live-gate Β· runbook | | **PnL cross-check (LB snapshot)** | `pm pnl-check` Β· [`docs/fee-inclusive-pnl.md`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/fee-inclusive-pnl.md) | | **Track leaderboard / redeem / activity** | `pm lb` Β· `pm redeem` Β· `pm activity` Β· [`examples/05–08,15–20`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/examples/) | | **Give an AI agent tools** | [`skills/`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/skills/) β€” copy into Claude / OpenClaw / Cursor | Full index: [**docs/toolbox.md**](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/toolbox.md) ### 30-second try ```bash 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`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/v2-ctf-ops-faq.md) + `./bin/pm v2-check 0x…` ## CLI (`pm`) Node **22+** (uses `--experimental-strip-types`). From repo root: ```bash ./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`. | Command | What it does | |---------|--------------| | `pm profile` | LB PnL + open positions sample + Brier hint | | `pm activity` | Activity pagination + **~4000 row cap warnings** | | `pm scan` | Top markets by 24h volume + spread | | `pm updown` | Crypto updown event fields / resolution source | | `pm v2-check` | V2 CTF split/merge checklist + activity sample | | `pm lb` | Leaderboard snapshot + day-over-day diff | | `pm pnl-check` | LB snapshot + hints β€” not audit-grade PnL | | `pm limits` | Official API rate limit pacing | | `pm brier` | Brier score from settled positions (sample) | | `pm markout` | Execution quality β€” markout vs market baseline | | `pm mix` | Execution style β€” maker/taker split, cross-checked against fees | | `pm fees` | Lifetime taker fees from `/activity` Β· pre-fee β†’ net PnL | | `pm redeem` | Read-only redeem watchdog JSON | | `pm markets` | Quick Gamma market list | Audit-grade PnL (Python): `python3 skills/polymarket-pnl/compute_precise_pnl.py --address …` ### `pm fees` β€” why your number never matches the profile ```bash ./bin/pm fees 0xYourProxy ``` > **Polymarket's own PnL β€” profile, `lb-api`, the `user-pnl` curve β€” is *pre-fee*. > A cashflow replay is *post-fee*. `gap β‰ˆ lifetime taker fees βˆ’ maker rebates`.** The fee is already in `/activity`: `usdcSize` is **not** `size Γ— price`, and the residual is what you were charged. That means lifetime fees, per-fill taker proof, and the pre-fee β†’ net conversion come from one REST call β€” no RPC, no receipt decoding, no credentials. Verified by predicting the gap before comparing, on four wallets: a heavy-taker wallet landed at a **$0.84 residual against a $1,308.87 prediction**, and a pure maker matched the official number to **$0.40**. ⚠️ The taker test is one-directional. `fee > 0` proves you were the taker β€” makers are never charged. `fee == 0` means maker **or** fee-exempt category, so it is reported as an upper bound on passive share, never as a maker count. ⚠️ Fees are recent. The earliest on record here is late June 2026, rate stepping 0.03 β†’ 0.05 β†’ 0.07. Any reconciliation that passed before then proves nothing about today. ### `pm markout` β€” is this address getting picked off? ```bash ./bin/pm markout 0x9a18f10966262d9be5d662754256380583fabb54 --fills 200 ``` Markout is where a fill stands some seconds later: `(reference βˆ’ fill) Γ— direction`, in cents per share. Negative means the price walked away from you β€” adverse selection. Three things this command does that a hand-rolled version usually gets wrong: - **Passive fills are included.** `/trades?user=` behaves like `takerOnly=true` by default, so a market maker's entire passive side is missing unless you ask for it. - **The reference is a windowed VWAP, not the next print.** Prints alternate between bid and ask, and that bounce alone makes every SELL look good and every BUY look bad. - **Everything is measured against a baseline** β€” the same tokens over the same span, minus this wallet. Levels drift; the excess is the part that means something. Read the excess column and the coverage column together. In short-dated markets a large `tau` leaves most fills with nothing ahead of them to be priced against, and the mean then describes the surviving handful rather than the trader. **Why these three defaults exist.** I ran 15 strategies on Polymarket over half a year, and the ones that cost the most failed at measurement, not at strategy: the same logic made +77% on paper and lost βˆ’74% live; 18.3% of my own trade records were quietly wrong, two thirds of those being false wins; market-making went 0 for 10 while the platform shipped three fee formulas in a single night. Each flag above is one of those mistakes turned into a default, so it isn't paid for twice. The full write-up β€” 15 strategies, 5 deep pits, 14,000 words β€” is at [leolabs.me/pm-quant](https://leolabs.me/pm-quant) ($49). It comes with monthly supplement notes; the current one measures a ~300ms server-side floor on taker orders that no colo or private line removes, against 56ms for maker. ## TypeScript library Zero-dependency helpers in [`src/index.ts`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/src/index.ts). Run demos with Node 22+: ```bash npx tsx examples/01-fetch-gamma-markets.ts node --experimental-strip-types examples/01-fetch-gamma-markets.ts ``` - **Examples:** [`examples/`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/examples/) β€” one numbered script per API pattern - **Cookbook:** [`docs/cookbook.md`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/cookbook.md) β€” bilingual recipes ## Skills (AI agents) | Skill | What it does | |-------|-------------| | `polymarket-profile` | Deep profile β€” PnL, win rate, positions, categories, strategy detection | | `polymarket-brier` | Prediction accuracy scoring, calibration analysis | | `polymarket-pnl` | Audit-grade PnL via cashflow reconstruction (~0.2% MAPE vs. official) | Install: copy the chosen skill into the skills directory configured by your agent client. `polymarket-pnl` also needs: `pip install httpx` Skill details: [`skills/*/SKILL.md`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/skills/) Β· long-form docs in sections below. --- ## What's in this repo | Included | Not included | |----------|--------------| | Read-only APIs, CLI, skills, docs, templates | Private keys, signing, or trade execution | | V2 FAQ + `pm v2-check` diagnostics | Runnable merge/split/redeem modules | | `polymarket-pnl` audit script | Custodial wallets or one-click trading | | Builder attribution helper for future CLOB executors | Builder API credentials or reward guarantees | | Opt-in [`executor/`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/executor) sub-package (isolated deps, dry-run default) | Custody, strategy logic, or one-click trading | | [`mcp/`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/mcp) MCP server β€” read-only tools for AI agents ([docs/mcp.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/mcp.md)) | MCP-exposed order placement | The core (`src/`, CLI, skills) never holds keys or sends transactions. Order execution lives only in the opt-in [`executor/`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/executor) sub-package, which signs with **your** env-provided key, defaults to dry-run, and is never imported by the core. For normal redemption, use the official Polymarket app. New to [Polymarket](https://polymarket.com/?r=githuball&via=runes-leo&utm_source=github&utm_content=polymarket-toolkit)? Sign up via the link above (**affiliate disclosure:** the author may earn referral rewards; no extra cost to you). Building your own order executor? Start from the opt-in [`executor/`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/executor) sub-package ([docs/executor.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/executor.md)) β€” CLOB V2 limit orders with dry-run default, notional cap, and default builder attribution via [`src/builder.ts`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/src/builder.ts) (override / opt-out via env). See [builder attribution](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/builder-attribution.md) for the disclosure and FAQ. Read-only CLI/skills still do not send orders. --- ## Release notes ### v0.7 β€” MCP server for AI agents - **`mcp/`** β€” [Model Context Protocol](https://modelcontextprotocol.io) server exposing 12 read-only tools (`pm_profile`, `pm_activity`, `pm_brier`, `pm_mix`, `pm_markout`, `pm_pnl_check`, `pm_scan`, `pm_updown`, `pm_leaderboard`, `pm_redeem_watchdog`, `pm_v2_check`, `pm_rate_limits`) β€” [docs/mcp.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/mcp.md) - The CLI is the contract: every tool shells out to `pm`, so the server is exactly as read-only as the CLI; inputs are allowlist-validated before reaching argv - Order placement is deliberately **not** exposed over MCP β€” the executor stays a separate, human-wired opt-in ### v0.6 β€” Opt-in executor sub-package - **`executor/`** β€” isolated CLOB V2 order execution module ([docs/executor.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/executor.md)): own dependencies, never imported by the zero-dependency core - **Safety ladder** β€” dry-run by default (`EXECUTOR_LIVE=1` to post), notional cap `EXECUTOR_MAX_USD` (default $10), fail-closed credential validation - **Builder attribution wired end-to-end** β€” default / override / opt-out via core [`src/builder.ts`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/src/builder.ts), full disclosure in docs - Core CLI/skills remain read-only and key-free β€” scope table updated above ### v0.5 β€” Toolbox CLI + roadmap flagships - **`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`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/v2-ctf-ops-faq.md) (split/merge/convert Β· infra alignment) - **Builder attribution helper** β€” [`src/builder.ts`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/src/builder.ts) + [`docs/builder-attribution.md`](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/builder-attribution.md) for future CLOB executors, with default / override / opt-out paths - **Market scanner** Β· **crypto updown fields** Β· **handoff template** β€” [toolbox.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/toolbox.md) ### v0.4 β€” Redeem watchdog **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. ```ts 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](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/toolbox.md). ### v0.3 β€” polymarket-pnl skill **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. --- ## Redeem Watchdog Helpers Inspect redeemable positions for a public proxy wallet without touching keys, allowances, relayers, or transactions. ### What you get - **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. ### Example ```bash npx tsx examples/15-redeem-watchdog.ts 0x63ce342161250d705dc0b16df89036c8e5f9ba9a 25 ``` ```json { "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. ### Safety boundary 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. --- ## polymarket-profile Turn any Polymarket address into a complete trading profile. ### What you get - **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. ### How it works 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) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### Setup **Claude Code:** ```bash # Replace the placeholder with the skills directory configured by your client export AGENT_SKILLS_DIR=/path/to/your/agent/skills cp -R skills/polymarket-profile "$AGENT_SKILLS_DIR/" ``` **OpenClaw:** ```bash 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. ### Requirements - 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](https://polymarket.com/?r=githuball&via=runes-leo&utm_source=github&utm_content=polymarket-toolkit). ### Supported input | Input | Example | Resolution | |-------|---------|------------| | 0x address | `0x63ce342161250d705dc0b16df89036c8e5f9ba9a` | Direct | | Profile URL | `polymarket.com/profile/Theo4` | Auto-resolve via leaderboard | | Username | `Theo4` | Auto-resolve via leaderboard | Username lookup works for all leaderboard-ranked users (auto-resolved via `lb-api`). Unranked accounts (zero trading history) require the 0x address directly. ### Data sources All public, no authentication required: | API | What it provides | |-----|-----------------| | `lb-api.polymarket.com` | PnL, leaderboard rankings | | `data-api.polymarket.com` | Positions, activity history | | `gamma-api.polymarket.com` | Market metadata, categories, tags | ### Known limitations - 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` --- ## polymarket-brier Rate any trader's prediction accuracy with Brier Score β€” the standard metric used by Metaculus, Good Judgment Project, and forecasting research. ### Why not just look at PnL? | Trader Type | PnL | Brier Score | Signal Value | |-------------|-----|-------------|-------------| | Skilled predictor | High | Good (low) | Best signal source | | Market maker | High | Poor (high) | Earns spread, not predictions | | SPLIT arbitrageur | High | N/A | Market-neutral, no directional view | | Accurate but cautious | Low | Good (low) | Good signal, small sizing | ### Example ``` 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% | ``` ### Setup ```bash # Claude Code export AGENT_SKILLS_DIR=/path/to/your/agent/skills cp -R skills/polymarket-brier "$AGENT_SKILLS_DIR/" # 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](https://polymarket.com/?r=githuball&via=runes-leo&utm_source=github&utm_content=polymarket-toolkit). --- ## polymarket-pnl 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. ### Why not just use position-level cashPnL? 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. ### Example ``` 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 ``` ### Setup ```bash # Claude Code export AGENT_SKILLS_DIR=/path/to/your/agent/skills cp -R skills/polymarket-pnl "$AGENT_SKILLS_DIR/" pip install httpx # the only runtime dependency # OpenClaw cp -R skills/polymarket-pnl ~/.openclaw/skills/ pip install httpx ``` ### CLI usage ```bash # 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. ### When to use `polymarket-profile` vs `polymarket-pnl` - **`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](https://polymarket.com/?r=githuball&via=runes-leo&utm_source=github&utm_content=polymarket-toolkit). --- ## Validation templates Strategy validation docs from hypothesis β†’ tiny-live (MIT templates): | Template | Purpose | Path | |----------|---------|------| | AI handoff | Cross-session task handoff (7 fields) | [handoff-template.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/templates/handoff-template.md) | | Backtest report | Conclusions + abandon line | [backtest-report-template.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/templates/backtest-report-template.md) | | Paper checklist | Anti-fake-paper Β· fill rules + logging | [paper-checklist.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/templates/paper-checklist.md) | | Live gate (12 steps) | Tiny-live technical + ops gates | [live-gate-checklist.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/templates/live-gate-checklist.md) | | Platform change runbook | V2 / API migration response | [platform-change-runbook.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/templates/platform-change-runbook.md) | Also: [fee-inclusive-pnl.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/fee-inclusive-pnl.md) Β· full index: [toolbox.md](https://github.com/runesleo/polymarket-toolkit/blob/HEAD/docs/toolbox.md) > Templates are document skeletons; runnable paper/live execution code lives in your own repo. --- ## Roadmap **Analysis Tools** - [x] PnL Calculator β€” Cashflow-reconstructed PnL, ~0.2% MAPE vs. official leaderboard - [x] Brier Score Rating β€” Prediction quality scoring per address - [x] `pm profile` CLI β€” Quick address snapshot - [ ] Trading Style Tags β€” Conservative / Aggressive / Event-driven / Market Maker labels **Market Intelligence** - [x] Market Scanner Lite β€” `pm scan` (24h volume + spread) - [x] 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** - [x] V2 CTF split/merge FAQ + `pm v2-check` (read-only) - [x] Activity API cap warnings **Validation templates** - [x] Strategy handoff β€” docs/templates/handoff-template.md - [x] Backtest report β€” docs/templates/backtest-report-template.md - [x] Paper checklist β€” docs/templates/paper-checklist.md - [x] Live gate 12 steps β€” docs/templates/live-gate-checklist.md - [x] Platform change runbook β€” docs/templates/platform-change-runbook.md **Tracking & Alerts** - [x] Leaderboard Tracker Lite β€” `pm lb` + snapshot diff - [x] fee-inclusive PnL guide β€” docs/fee-inclusive-pnl.md + `pm pnl-check` - [ ] Whale Alert β€” Large position changes from top traders - [x] Redeem Watchdog β€” public redeemable-position status for agent dashboards **API** (planned) - [ ] REST API for all tools above β€” integrate Polymarket intelligence into your own apps ## More from this workshop Full map: **[runesleo](https://github.com/runesleo/runesleo)** β€” all open-source projects and working systems. - [x-reader](https://github.com/runesleo/x-reader) β€” universal content reader MCP, 10+ platforms - [claude-code-workflow](https://github.com/runesleo/claude-code-workflow) β€” QuietHarness: shared AI working system for Claude Code / Codex / Cursor - [ai-health-vault](https://github.com/runesleo/ai-health-vault) β€” AI + Obsidian health management system - [claude-video-kit](https://github.com/runesleo/claude-video-kit) β€” Agent Skill + Remotion video pipeline ## About the author *Leo ([@runes_leo](https://x.com/runes_leo)) β€” AI Γ— Crypto independent builder. Trading on [Polymarket](https://polymarket.com/?r=githuball&via=runes-leo&utm_source=github&utm_content=polymarket-toolkit), building data and trading systems with Claude Code and Codex.* *[leolabs.me](https://leolabs.me) β€” writing Β· community Β· open-source tools Β· indie projects Β· all platforms.* *[X Subscription](https://x.com/runes_leo/creator-subscriptions/subscribe) β€” 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.*