polymarket-pnl

Polymarket Precise PnL

Compute precise, audit-grade PnL for any Polymarket address via the Data API cashflow method. Unlike position-level approximations used by most profilers, this reconstructs 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.

Trigger

Invoke this skill when the user wants:

• Audit-grade PnL for one or more Polymarket addresses
• Bulk PnL over a leaderboard or an address list
• Benchmark mode: compare a local PnL dataset vs. the official /profit values

If the user just wants a quick profile (win rate, positions, category breakdown), use the polymarket-profile skill instead — it's lighter and runs on curl alone.

Requirements

• python3 (3.9+)
• One Python package: httpx

Install once:

pip install -r ${SKILL_DIR}/requirements.txt
# or
pip install httpx

${SKILL_DIR} is the path where this skill lives (e.g. ~/.claude/skills/polymarket-pnl/).

Core CLI

All invocations run from the skill directory (or with python3 <skill_dir>/compute_precise_pnl.py):

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

# Bulk: top N on the leaderboard (auto-fetched)
python3 compute_precise_pnl.py --leaderboard 50

# Address list from a text file (one 0x per line, `#` for comments)
python3 compute_precise_pnl.py --addresses-file targets.txt

# Benchmark: compare your local PnL JSONL against the recomputed precise PnL
python3 compute_precise_pnl.py --leaderboard 100 \
  --benchmark local_pnl.jsonl \
  -o precise_vs_local.jsonl

Output is JSONL streamed to --output (default: ./precise_pnl.jsonl).

Output schema

Each line is one address record:

Known limitations

• Data API offset ceiling (~10k): extremely high-frequency accounts may hit it on one activity type. The record is still emitted with pagination_incomplete=True and the field list so you can flag or re-fetch via timestamp-chunked backfill.
• Same-second full-page boundary: the timestamp-based pagination uses end = oldest - 1 with a heuristic backfill pass that only triggers when the boundary timestamp already appears more than once in the current page. If a full page ends with exactly one row at timestamp T and additional same-second rows continue onto the next page, those rows may be skipped without pagination_incomplete being set. This affects a small subset of very-high-frequency accounts; most addresses stay within 1% of the official /profit. A stricter backfill is on the roadmap.
• pnl vs pnl_inclusive choice: Polymarket's official /profit endpoint inconsistently includes platform credits across addresses. The primary pnl field deliberately excludes them so the number is reproducible from public trade data alone.
• Requires httpx: the only third-party dependency, for its robust TLS/HTTP/1.1 handling against the Data API.
• No authentication: uses only public endpoints (data-api.polymarket.com, gamma-api.polymarket.com), so there are no API keys to manage but also no access to private endpoints.

Comparison with polymarket-profile

Use them together: polymarket-profile for the qualitative picture, polymarket-pnl when the PnL number has to hold up to scrutiny.

Data sources

All public, no authentication required:

Setup

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

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

New to Polymarket? Create an account here.

License

MIT — see repository root LICENSE.