Polymarket Toolkit

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

中文说明

Machine-readable product facts: ai-info.json · llms.txt. Both are generated from content/ai-identity.json; npm run check:ai-discovery fails on tool, package-version, or output drift.

Install as a plugin

• Claude Code (2.1.275 or later): /plugin install polymarket-toolkit --marketplace runesleo/x-reader
• Codex: codex plugin marketplace add runesleo/x-reader, then codex plugin add polymarket-toolkit@runesleo

The runesleo marketplace also lists Leo's other tools; see runesleo/x-reader.

Toolbox · pick a drawer

Full index: docs/toolbox.md

30-second try

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…

CLI (pm)

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 …

pm fees — why your number never matches the profile

./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?

./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 ($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. 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

Skills (AI agents)

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 · long-form docs in sections below.

---

What's in this repo

The core (src/, CLI, skills) never holds keys or sends transactions. Order execution lives only in the opt-in 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? 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/ sub-package (docs/executor.md) — CLOB V2 limit orders with dry-run default, notional cap, and default builder attribution via src/builder.ts (override / opt-out via env). See builder attribution 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 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
• 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): 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, 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 (split/merge/convert · infra alignment)
• Builder attribution helper — src/builder.ts + docs/builder-attribution.md for future CLOB executors, with default / override / opt-out paths
• Market scanner · crypto updown fields · handoff template — toolbox.md

v0.4 — Redeem wat