polymarket-toolkit-mcp 0.7.0

package/dist/cli.js

@@ -0,0 +1,994 @@
+// ../src/index.ts
+var LB_API_BASE = "https://lb-api.polymarket.com";
+var DATA_API_BASE = "https://data-api.polymarket.com";
+var GAMMA_API_BASE = "https://gamma-api.polymarket.com";
+var DEFAULT_TIMEOUT_MS = 2e4;
+async function pmGetJson(url) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), DEFAULT_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      signal: ctrl.signal,
+      headers: { accept: "application/json" }
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`HTTP ${res.status} ${res.statusText}${body ? `: ${body.slice(0, 200)}` : ""}`);
+    }
+    return await res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchLbProfitForAddress(address, window = "all") {
+  const u = new URL(`${LB_API_BASE}/profit`);
+  u.searchParams.set("address", address);
+  u.searchParams.set("window", window);
+  return pmGetJson(u);
+}
+async function fetchLbProfitLeaderboardPage(options) {
+  const u = new URL(`${LB_API_BASE}/profit`);
+  u.searchParams.set("window", options.window ?? "all");
+  u.searchParams.set("limit", String(options.limit ?? 500));
+  u.searchParams.set("offset", String(options.offset ?? 0));
+  return pmGetJson(u);
+}
+async function resolveLbUsernameToProxyWallet(username, maxPages = 4) {
+  const needle = username.trim().toLowerCase();
+  if (!needle) return null;
+  for (let page = 0; page < maxPages; page++) {
+    const rows = await fetchLbProfitLeaderboardPage({
+      limit: 500,
+      offset: page * 500
+    });
+    if (!rows.length) break;
+    for (const row of rows) {
+      const n = (row.name ?? "").toLowerCase();
+      const p = (row.pseudonym ?? "").toLowerCase();
+      if (n === needle || p === needle) {
+        return row.proxyWallet ?? null;
+      }
+    }
+    if (rows.length < 500) break;
+  }
+  return null;
+}
+async function fetchDataLeaderboardPnL(options) {
+  const u = new URL(`${DATA_API_BASE}/v1/leaderboard`);
+  u.searchParams.set("timePeriod", options.timePeriod ?? "all");
+  u.searchParams.set("orderBy", options.orderBy ?? "PNL");
+  u.searchParams.set("category", options.category ?? "overall");
+  u.searchParams.set("limit", String(options.limit ?? 50));
+  u.searchParams.set("offset", String(options.offset ?? 0));
+  return pmGetJson(u);
+}
+async function fetchPositionsPage(user, options = {}) {
+  const u = new URL(`${DATA_API_BASE}/positions`);
+  u.searchParams.set("user", user);
+  u.searchParams.set("sizeThreshold", String(options.sizeThreshold ?? 0));
+  u.searchParams.set("limit", String(options.limit ?? 100));
+  u.searchParams.set("offset", String(options.offset ?? 0));
+  return pmGetJson(u);
+}
+function round6(value) {
+  return Math.round(value * 1e6) / 1e6;
+}
+function numeric(value) {
+  const n = Number(value ?? 0);
+  return Number.isFinite(n) ? n : 0;
+}
+async function fetchRedeemablePositionsPage(user, options = {}) {
+  const u = new URL(`${DATA_API_BASE}/positions`);
+  u.searchParams.set("user", user);
+  u.searchParams.set("redeemable", "true");
+  u.searchParams.set("sizeThreshold", "0");
+  u.searchParams.set("limit", String(options.limit ?? 100));
+  u.searchParams.set("offset", String(options.offset ?? 0));
+  return pmGetJson(u);
+}
+function summarizeRedeemablePositions(positions) {
+  const byCondition = /* @__PURE__ */ new Map();
+  for (const position of positions) {
+    if (position.redeemable !== true) continue;
+    const conditionId = position.conditionId || "unknown";
+    const slug = position.slug || position.eventSlug || position.title || conditionId;
+    const raw = position.currentValue == null ? numeric(position.size) : numeric(position.currentValue);
+    const estimatedCurrentValue = raw > 0 ? raw : 0;
+    const row = byCondition.get(conditionId) ?? {
+      conditionId,
+      slug,
+      count: 0,
+      estimatedCurrentValue: 0
+    };
+    row.count += 1;
+    row.estimatedCurrentValue += estimatedCurrentValue;
+    byCondition.set(conditionId, row);
+  }
+  const topConditions = [...byCondition.values()].map((row) => ({ ...row, estimatedCurrentValue: round6(row.estimatedCurrentValue) })).sort((a, b) => b.estimatedCurrentValue - a.estimatedCurrentValue);
+  return {
+    redeemableCount: topConditions.reduce((total, row) => total + row.count, 0),
+    conditionCount: topConditions.length,
+    estimatedRedeemableValue: round6(
+      topConditions.reduce((total, row) => total + row.estimatedCurrentValue, 0)
+    ),
+    topConditions
+  };
+}
+function resolveRedeemMode(options = {}) {
+  const mode = (options.mode ?? "").trim().toLowerCase().replace(/-/g, "_");
+  if (mode === "low_watermark" || mode === "watermark" || mode === "on_demand") return "low_watermark";
+  if (mode === "watchdog" || mode === "watch" || mode === "status" || mode === "dry_run") return "watchdog";
+  return typeof options.lowWatermark === "number" && Number.isFinite(options.lowWatermark) && options.lowWatermark > 0 ? "low_watermark" : "watchdog";
+}
+async function fetchActivityPage(user, options = {}) {
+  const u = new URL(`${DATA_API_BASE}/activity`);
+  u.searchParams.set("user", user);
+  u.searchParams.set("limit", String(options.limit ?? 500));
+  if (options.end != null) u.searchParams.set("end", String(options.end));
+  if (options.type) u.searchParams.set("type", options.type);
+  return pmGetJson(u);
+}
+async function fetchGammaEventsBySlug(slug) {
+  const u = new URL(`${GAMMA_API_BASE}/events`);
+  u.searchParams.set("slug", slug);
+  return pmGetJson(u);
+}
+async function fetchGammaMarkets(query = {}) {
+  const u = new URL(`${GAMMA_API_BASE}/markets`);
+  for (const [k, v] of Object.entries(query)) {
+    u.searchParams.set(k, String(v));
+  }
+  return pmGetJson(u);
+}
+function computeBrierScoreFromSettledPositions(positions) {
+  const settled = positions.filter((p) => p.redeemable === true);
+  if (!settled.length) return { brier: Number.NaN, n: 0, wins: 0 };
+  let sumSq = 0;
+  let wins = 0;
+  for (const p of settled) {
+    const f = Number(p.avgPrice);
+    const won = Number(p.currentValue) > 0;
+    if (won) wins++;
+    const actual = won ? 1 : 0;
+    sumSq += (f - actual) ** 2;
+  }
+  return { brier: sumSq / settled.length, n: settled.length, wins };
+}
+var ACTIVITY_API_ROW_CAP_HINT = 4e3;
+function fingerprintActivityPage(rows) {
+  return JSON.stringify(rows);
+}
+function analyzeActivityPaginationWarnings(options) {
+  const warnings = [];
+  if (options.sawDuplicatePage) {
+    warnings.push({
+      code: "DUPLICATE_PAGE",
+      message: `Activity API returned an identical page twice (reported ~${ACTIVITY_API_ROW_CAP_HINT} row cap). Treat results as INCOMPLETE \u2014 shard by time window or use skills/polymarket-pnl \`pagination_incomplete\` flags.`
+    });
+  }
+  if (options.sawStaleCursor) {
+    warnings.push({
+      code: "STALE_CURSOR",
+      message: "Activity cursor (`end`) did not advance between pages. Pagination may have stalled."
+    });
+  }
+  if (options.sawDuplicatePage || options.sawStaleCursor) {
+    warnings.push({
+      code: "INCOMPLETE",
+      message: "Activity pagination did not produce a complete scan. Shard by time window before relying on totals."
+    });
+  }
+  if (options.totalRows >= ACTIVITY_API_ROW_CAP_HINT - 500) {
+    warnings.push({
+      code: "APPROACHING_CAP",
+      message: `Fetched ${options.totalRows} activity rows (approaching ~${ACTIVITY_API_ROW_CAP_HINT} cap). Next pages may repeat JSON.`
+    });
+  }
+  return warnings;
+}
+function activityWarningsLikelyIncomplete(warnings) {
+  return warnings.some((w) => w.code === "APPROACHING_CAP" || w.code === "INCOMPLETE");
+}
+async function fetchActivityPages(user, options = {}) {
+  const limit = options.limit ?? 500;
+  const maxPages = options.maxPages ?? 20;
+  const collected = [];
+  let end;
+  let lastFingerprint = "";
+  let sawDuplicatePage = false;
+  let sawStaleCursor = false;
+  let pagesFetched = 0;
+  for (let page = 0; page < maxPages; page++) {
+    const batch = await fetchActivityPage(user, { limit, end, type: options.type });
+    pagesFetched += 1;
+    if (!batch.length) break;
+    const fp = fingerprintActivityPage(batch);
+    if (lastFingerprint && fp === lastFingerprint) {
+      sawDuplicatePage = true;
+      break;
+    }
+    lastFingerprint = fp;
+    collected.push(...batch);
+    if (batch.length < limit) break;
+    const lastTs = batch[batch.length - 1]?.timestamp;
+    if (lastTs == null) break;
+    if (end !== void 0 && end === lastTs) {
+      sawStaleCursor = true;
+      break;
+    }
+    end = lastTs;
+  }
+  const warnings = analyzeActivityPaginationWarnings({
+    totalRows: collected.length,
+    sawDuplicatePage,
+    sawStaleCursor
+  });
+  const likelyIncomplete = activityWarningsLikelyIncomplete(warnings);
+  return {
+    rows: collected,
+    pagesFetched,
+    warnings,
+    likelyIncomplete
+  };
+}
+
+// ../src/cli/util.ts
+var EVM_RE = /^0x[a-fA-F0-9]{40}$/;
+function isEvmAddress(value) {
+  return EVM_RE.test(value.trim());
+}
+function normalizeAddress(value) {
+  const v = value.trim();
+  if (!isEvmAddress(v)) {
+    throw new Error(`Invalid EVM address: ${value}`);
+  }
+  return v.toLowerCase();
+}
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+function usage() {
+  console.log(`pm \u2014 Polymarket Toolkit CLI (builders \xB7 public APIs only)
+
+Usage:
+  pm profile <address|username> [--json]   Address snapshot (PnL, positions, Brier)
+  pm activity <address> [--type TRADE]     Activity pagination + cap warnings
+  pm scan [--limit N] [--min-volume N]     Market scanner (24h volume \xB7 spread)
+  pm updown <event-slug> [--json]          Crypto updown Gamma fields / resolution
+  pm v2-check [address]                    V2 split/merge infra checklist (+ activity)
+  pm lb [--category overall] [--save]      Leaderboard snapshot + diff
+  pm lb --diff [--category overall]        Diff vs yesterday snapshot
+  pm pnl-check <address>                   LB snapshot + hints; not audit-grade PnL
+  pm limits [gamma|data|clob|all]          API rate limit pacing table
+  pm redeem <address> [low_watermark]      Redeem watchdog (read-only)
+  pm brier <address|username> [--json]     Brier score from settled positions
+  pm markets [--limit N] [--active]        List Gamma markets (quick scan)
+  pm help                                  Show this message
+
+Examples:
+  pm profile 0x63ce342161250d705dc0b16df89036c8e5f9ba9a
+  pm redeem 0x63ce342161250d705dc0b16df89036c8e5f9ba9a 25
+  pm markets --limit 5 --active
+
+Skills (for AI agents): skills/polymarket-profile \xB7 polymarket-pnl \xB7 polymarket-brier
+Cookbook: docs/cookbook.md \xB7 Examples: examples/
+
+No API keys. No signing. Read-only public APIs only.
+`);
+}
+
+// ../src/cli/commands/activity.ts
+async function resolveAddress(input) {
+  const trimmed = input.trim();
+  if (isEvmAddress(trimmed)) return normalizeAddress(trimmed);
+  const resolved = await resolveLbUsernameToProxyWallet(trimmed);
+  if (!resolved) throw new Error(`Could not resolve "${trimmed}" via leaderboard.`);
+  return normalizeAddress(resolved);
+}
+async function runActivity(argv) {
+  const json = argv.includes("--json");
+  const typeIdx = argv.indexOf("--type");
+  const activityType = typeIdx >= 0 ? argv[typeIdx + 1] : void 0;
+  const limitIdx = argv.indexOf("--limit");
+  const limit = limitIdx >= 0 ? Number(argv[limitIdx + 1] ?? 500) : 500;
+  const maxPagesIdx = argv.indexOf("--max-pages");
+  const maxPages = maxPagesIdx >= 0 ? Number(argv[maxPagesIdx + 1] ?? 10) : 10;
+  const skipNext = /* @__PURE__ */ new Set(["--type", "--limit", "--max-pages"]);
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") continue;
+    if (skipNext.has(a)) {
+      i++;
+      continue;
+    }
+    if (a.startsWith("--")) continue;
+    positional.push(a);
+  }
+  const input = positional[0];
+  if (!input) {
+    throw new Error("usage: pm activity <address|username> [--type TRADE] [--limit N] [--max-pages N] [--json]");
+  }
+  const address = await resolveAddress(input);
+  const result = await fetchActivityPages(address, {
+    limit,
+    maxPages,
+    type: activityType
+  });
+  const payload = {
+    address,
+    type: activityType ?? null,
+    rowCount: result.rows.length,
+    pagesFetched: result.pagesFetched,
+    likelyIncomplete: result.likelyIncomplete,
+    warnings: result.warnings,
+    sample: result.rows.slice(0, 5).map((r) => ({
+      type: r.type,
+      timestamp: r.timestamp,
+      title: r.title?.slice(0, 60),
+      usdcSize: r.usdcSize
+    }))
+  };
+  if (json) {
+    printJson(payload);
+    return;
+  }
+  console.log(`Activity \xB7 ${address}`);
+  console.log(`  Rows: ${result.rows.length} (${result.pagesFetched} pages)`);
+  if (result.warnings.length) {
+    for (const w of result.warnings) {
+      console.log(`  \u26A0\uFE0F  [${w.code}] ${w.message}`);
+    }
+  }
+  if (result.likelyIncomplete) {
+    console.log("  Status: INCOMPLETE \u2014 do not trust totals beyond this point.");
+  }
+  for (const row of payload.sample) {
+    console.log(`  \xB7 ${row.type} ts=${row.timestamp} ${row.title ?? ""} $${row.usdcSize ?? "?"}`);
+  }
+}
+
+// ../src/cli/commands/brier.ts
+async function resolveAddress2(input) {
+  const trimmed = input.trim();
+  if (isEvmAddress(trimmed)) return normalizeAddress(trimmed);
+  const resolved = await resolveLbUsernameToProxyWallet(trimmed);
+  if (!resolved) throw new Error(`Could not resolve "${trimmed}" via leaderboard.`);
+  return normalizeAddress(resolved);
+}
+async function runBrier(argv) {
+  const json = argv.includes("--json");
+  const input = argv.find((a) => !a.startsWith("--"));
+  if (!input) throw new Error("usage: pm brier <address|username> [--json]");
+  const address = await resolveAddress2(input);
+  const positions = await fetchPositionsPage(address, { limit: 200 });
+  const settled = positions.filter((p) => p.redeemable === true);
+  const result = computeBrierScoreFromSettledPositions(settled);
+  const payload = {
+    address,
+    brier: Number.isFinite(result.brier) ? result.brier : null,
+    settledMarkets: result.n,
+    wins: result.wins,
+    rating: !Number.isFinite(result.brier) ? "insufficient_sample" : result.brier <= 0.15 ? "good" : result.brier <= 0.25 ? "moderate" : "poor",
+    note: "First 200 positions page; full calibration use skills/polymarket-brier."
+  };
+  if (json) {
+    printJson(payload);
+    return;
+  }
+  console.log(`Brier \xB7 ${address}`);
+  if (!Number.isFinite(result.brier)) {
+    console.log("  No settled positions in sample.");
+    return;
+  }
+  console.log(`  Score: ${result.brier.toFixed(3)} (${payload.rating})`);
+  console.log(`  Settled: ${result.n} \xB7 Wins: ${result.wins}`);
+}
+
+// ../src/leaderboard.ts
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+function todayUtcDate() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+function snapshotPath(baseDir, category, timePeriod, date) {
+  return join(baseDir, `${date}_${category}_${timePeriod}.json`);
+}
+function saveSnapshot(baseDir, snapshot) {
+  mkdirSync(baseDir, { recursive: true });
+  const path = snapshotPath(baseDir, snapshot.category, snapshot.timePeriod, snapshot.date);
+  writeFileSync(path, JSON.stringify(snapshot, null, 2));
+  return path;
+}
+function loadSnapshot(baseDir, category, timePeriod, date) {
+  const path = snapshotPath(baseDir, category, timePeriod, date);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function diffLeaderboardSnapshots(previous, current) {
+  const key = (r) => (r.proxyWallet ?? r.userName ?? "").toLowerCase();
+  const prevMap = new Map(previous.rows.map((r, i) => [key(r), { row: r, rank: i + 1 }]));
+  const currMap = new Map(current.rows.map((r, i) => [key(r), { row: r, rank: i + 1 }]));
+  const newFaces = [];
+  const dropped = [];
+  const rankChanges = [];
+  for (const [k, { row, rank }] of currMap) {
+    const prev = prevMap.get(k);
+    if (!prev) {
+      newFaces.push(row);
+      continue;
+    }
+    if (prev.rank !== rank) {
+      rankChanges.push({
+        userName: row.userName ?? k.slice(0, 10),
+        proxyWallet: row.proxyWallet ?? "",
+        from: prev.rank,
+        to: rank,
+        pnl: row.pnl != null ? Number(row.pnl) : null
+      });
+    }
+  }
+  for (const [k, { row }] of prevMap) {
+    if (!currMap.has(k)) dropped.push(row);
+  }
+  rankChanges.sort((a, b) => Math.abs(b.from - b.to) - Math.abs(a.from - a.to));
+  return { newFaces, dropped, rankChanges };
+}
+
+// ../src/cli/commands/lb.ts
+import { join as join2 } from "node:path";
+var SNAPSHOT_DIR = join2(process.cwd(), ".pm-toolkit", "lb-snapshots");
+var CATEGORIES = ["overall", "politics", "crypto", "sports", "weather", "finance", "tech", "culture"];
+async function runLb(argv) {
+  const json = argv.includes("--json");
+  const save = argv.includes("--save");
+  const diff = argv.includes("--diff");
+  const catIdx = argv.indexOf("--category");
+  const category = catIdx >= 0 ? argv[catIdx + 1] ?? "overall" : "overall";
+  const periodIdx = argv.indexOf("--period");
+  const timePeriod = periodIdx >= 0 ? argv[periodIdx + 1] ?? "day" : "day";
+  const topIdx = argv.indexOf("--top");
+  const top = topIdx >= 0 ? Number(argv[topIdx + 1] ?? 10) : 10;
+  if (!CATEGORIES.includes(category)) {
+    throw new Error(`Unknown category ${category}. Try: ${CATEGORIES.join(", ")}`);
+  }
+  const today = todayUtcDate();
+  const yesterday = new Date(Date.now() - 864e5).toISOString().slice(0, 10);
+  if (diff) {
+    const curr = loadSnapshot(SNAPSHOT_DIR, category, timePeriod, today) ?? await fetchAndBuild(category, timePeriod, top, today);
+    const prev = loadSnapshot(SNAPSHOT_DIR, category, timePeriod, yesterday);
+    if (!prev) {
+      throw new Error(`No snapshot for ${yesterday}. Run: pm lb --category ${category} --save`);
+    }
+    const delta = diffLeaderboardSnapshots(prev, curr);
+    if (json) {
+      printJson({ today: curr.date, yesterday: prev.date, category, timePeriod, ...delta });
+      return;
+    }
+    console.log(`LB diff \xB7 ${category} \xB7 ${timePeriod} \xB7 ${prev.date} \u2192 ${curr.date}
+`);
+    console.log(`New faces (${delta.newFaces.length}):`);
+    for (const r of delta.newFaces.slice(0, 10)) {
+      console.log(`  + #${r.rank} ${r.userName} ${r.proxyWallet?.slice(0, 10)} pnl=${r.pnl}`);
+    }
+    console.log(`
+Rank movers (top ${Math.min(10, delta.rankChanges.length)}):`);
+    for (const m of delta.rankChanges.slice(0, 10)) {
+      console.log(`  ${m.userName}: ${m.from} \u2192 ${m.to} (pnl=${m.pnl})`);
+    }
+    return;
+  }
+  const snapshot = await fetchAndBuild(category, timePeriod, top, today);
+  if (save) {
+    const path = saveSnapshot(SNAPSHOT_DIR, snapshot);
+    console.error(`Saved ${path}`);
+  }
+  if (json) {
+    printJson(snapshot);
+    return;
+  }
+  console.log(`Leaderboard \xB7 ${category} \xB7 ${timePeriod} \xB7 top ${top}
+`);
+  for (const r of snapshot.rows) {
+    console.log(`  #${r.rank} ${r.userName ?? "?"} \xB7 pnl=${r.pnl} \xB7 ${r.proxyWallet?.slice(0, 12)}\u2026`);
+  }
+  console.log(`
+Tip: pm lb --category ${category} --save \xB7 pm lb --diff --category ${category}`);
+}
+async function fetchAndBuild(category, timePeriod, top, date) {
+  const rows = await fetchDataLeaderboardPnL({
+    limit: top,
+    offset: 0,
+    timePeriod,
+    category,
+    orderBy: "PNL"
+  });
+  return { date, category, timePeriod, rows };
+}
+
+// ../src/rate-limits.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { dirname, join as join3 } from "node:path";
+import { fileURLToPath } from "node:url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var REGISTRY_PATH = join3(__dirname, "../docs/data/polymarket-api-rate-limits.json");
+var cached = null;
+function loadRateLimitRegistry() {
+  if (!cached) {
+    cached = JSON.parse(readFileSync2(REGISTRY_PATH, "utf8"));
+  }
+  return cached;
+}
+function suggestedDelaySeconds(family, scope = "general", safetyFactor = 0.85) {
+  const registry = loadRateLimitRegistry();
+  const fam = registry.families[family];
+  if (!fam) throw new Error(`Unknown API family: ${family}`);
+  const match = fam.limits.find((l) => l.scope === scope) ?? fam.limits.find((l) => l.scope === "general");
+  if (!match) throw new Error(`No limit for ${family}/${scope}`);
+  return Math.round(match.window_seconds / match.requests / safetyFactor * 1e4) / 1e4;
+}
+
+// ../src/cli/commands/limits.ts
+async function runLimits(argv) {
+  const json = argv.includes("--json");
+  const family = argv.find((a) => !a.startsWith("--")) ?? "all";
+  const registry = loadRateLimitRegistry();
+  if (family === "all") {
+    const summary = Object.entries(registry.families).map(([key, fam2]) => ({
+      family: key,
+      base_url: fam2.base_url,
+      scopes: fam2.limits.map((l) => ({
+        ...l,
+        suggested_delay_s: suggestedDelaySeconds(key, l.scope)
+      }))
+    }));
+    if (json) {
+      printJson({ updated_at: registry.updated_at, source: registry.source.url, families: summary });
+      return;
+    }
+    console.log(`Rate limits \xB7 updated ${registry.updated_at}`);
+    console.log(`Source: ${registry.source.url}
+`);
+    for (const fam2 of summary) {
+      console.log(`${fam2.family} \xB7 ${fam2.base_url}`);
+      for (const s of fam2.scopes.slice(0, 4)) {
+        console.log(`  ${s.scope}: ${s.requests}/${s.window_seconds}s \xB7 sleep ~${s.suggested_delay_s}s`);
+      }
+    }
+    return;
+  }
+  const fam = registry.families[family];
+  if (!fam) throw new Error(`Unknown family. Try: ${Object.keys(registry.families).join(", ")}`);
+  if (json) {
+    printJson(fam);
+    return;
+  }
+  console.log(`${family} \xB7 ${fam.base_url}
+`);
+  for (const l of fam.limits) {
+    console.log(`  ${l.scope}: ${l.requests} req / ${l.window_seconds}s \xB7 delay ~${suggestedDelaySeconds(family, l.scope)}s`);
+  }
+}
+
+// ../src/cli/commands/markets.ts
+async function runMarkets(argv) {
+  const limitIdx = argv.indexOf("--limit");
+  const limit = limitIdx >= 0 ? Number(argv[limitIdx + 1] ?? 10) : 10;
+  const active = argv.includes("--active");
+  const rows = await fetchGammaMarkets({
+    limit,
+    ...active ? { active: true, closed: false } : {}
+  });
+  const mapped = rows.map((m) => ({
+    question: m.question,
+    slug: m.slug,
+    volume: m.volume != null ? Number(m.volume) : null,
+    liquidity: m.liquidity != null ? Number(m.liquidity) : null
+  }));
+  printJson({ count: mapped.length, markets: mapped });
+}
+
+// ../src/cli/commands/pnl-check.ts
+async function runPnlCheck(argv) {
+  const json = argv.includes("--json");
+  const input = argv.find((a) => !a.startsWith("--"));
+  if (!input) throw new Error("usage: pm pnl-check <0x-address> [--json]");
+  const address = normalizeAddress(input);
+  if (!isEvmAddress(address)) throw new Error("Invalid address");
+  const [lbRows, tradePage, rebatePage] = await Promise.all([
+    fetchLbProfitForAddress(address, "all"),
+    fetchActivityPage(address, { limit: 500, type: "TRADE" }),
+    fetchActivityPage(address, { limit: 200, type: "MAKER_REBATE" })
+  ]);
+  const lbPnl = lbRows[0]?.amount != null ? Number(lbRows[0].amount) : null;
+  const name = lbRows[0]?.name ?? address.slice(0, 10);
+  const payload = {
+    address,
+    name,
+    lbPnlAllTime: lbPnl,
+    lbSource: "lb-api.polymarket.com/profit?window=all",
+    activitySample: {
+      tradeRowsFirstPage: tradePage.length,
+      makerRebateRowsFirstPage: rebatePage.length
+    },
+    interpretation: [
+      "LB PnL is a quick official snapshot and hint surface; it is not audit-grade PnL.",
+      "Position-level profile PnL is approximate.",
+      "For cashflow replay run: python3 skills/polymarket-pnl/compute_precise_pnl.py --address \u2026"
+    ],
+    docs: "docs/fee-inclusive-pnl.md"
+  };
+  if (json) {
+    printJson(payload);
+    return;
+  }
+  console.log(`PnL check \xB7 ${name} \xB7 ${address}
+`);
+  console.log(`  LB all-time: ${lbPnl != null ? `$${lbPnl.toLocaleString()}` : "n/a"}`);
+  console.log(`  Activity sample: ${payload.activitySample.tradeRowsFirstPage} TRADE rows (page 1)`);
+  console.log(`  Rebates sample: ${payload.activitySample.makerRebateRowsFirstPage} MAKER_REBATE rows (page 1)`);
+  console.log("  Scope: LB snapshot + hints; not audit-grade PnL.");
+  console.log("\n  \u2192 Audit: python3 skills/polymarket-pnl/compute_precise_pnl.py --address " + address);
+  console.log("  \u2192 Read: docs/fee-inclusive-pnl.md");
+}
+
+// ../src/cli/commands/profile.ts
+async function resolveIdentity(input) {
+  const trimmed = input.trim();
+  if (isEvmAddress(trimmed)) {
+    return { address: normalizeAddress(trimmed), displayName: null };
+  }
+  const resolved = await resolveLbUsernameToProxyWallet(trimmed);
+  if (!resolved) {
+    throw new Error(
+      `Could not resolve "${trimmed}" via leaderboard. Pass a 0x proxy wallet or a ranked username.`
+    );
+  }
+  return { address: normalizeAddress(resolved), displayName: trimmed };
+}
+async function lbAmount(address, window) {
+  const rows = await fetchLbProfitForAddress(address, window);
+  const head = rows[0];
+  if (!head || head.amount == null) return null;
+  const n = Number(head.amount);
+  return Number.isFinite(n) ? n : null;
+}
+function fmtUsd(n) {
+  if (n == null) return "n/a";
+  return `$${n.toLocaleString("en-US", { maximumFractionDigits: 2 })}`;
+}
+async function runProfile(argv) {
+  const json = argv.includes("--json");
+  const positional = argv.filter((a) => !a.startsWith("--"));
+  const input = positional[0];
+  if (!input) throw new Error("usage: pm profile <address|username> [--json]");
+  const { address, displayName } = await resolveIdentity(input);
+  const [pnlAll, pnl7d, pnl30d, positionsRaw, lbMeta] = await Promise.all([
+    lbAmount(address, "all"),
+    lbAmount(address, "7d"),
+    lbAmount(address, "30d"),
+    fetchPositionsPage(address, { limit: 100 }),
+    fetchLbProfitForAddress(address, "all")
+  ]);
+  const positions = positionsRaw;
+  const open = positions.filter((p) => p.redeemable !== true);
+  const settledForBrier = positions.filter((p) => p.redeemable === true);
+  const brier = computeBrierScoreFromSettledPositions(settledForBrier);
+  const unrealized = open.reduce((sum, p) => sum + Number(p.currentValue ?? 0), 0);
+  const topOpen = [...open].sort((a, b) => Math.abs(Number(b.currentValue ?? 0)) - Math.abs(Number(a.currentValue ?? 0))).slice(0, 5);
+  const name = displayName ?? lbMeta[0]?.name ?? lbMeta[0]?.pseudonym ?? address.slice(0, 10);
+  const payload = {
+    address,
+    displayName: name,
+    pnl: { all: pnlAll, d7: pnl7d, d30: pnl30d, source: "lb-api.polymarket.com/profit" },
+    positions: {
+      openCount: open.length,
+      settledSampleCount: settledForBrier.length,
+      unrealizedValue: unrealized,
+      topOpen: topOpen.map((p) => ({
+        title: p.title ?? p.slug ?? "unknown",
+        currentValue: Number(p.currentValue ?? 0),
+        cashPnl: Number(p.cashPnl ?? 0)
+      }))
+    },
+    brier: {
+      score: Number.isFinite(brier.brier) ? brier.brier : null,
+      settledMarkets: brier.n,
+      wins: brier.wins,
+      note: "First 100 positions page only; use polymarket-pnl skill for audit-grade PnL."
+    },
+    limitations: [
+      "LB PnL only; 7d/30d may be empty for inactive accounts.",
+      "Positions capped at first API page (100 rows).",
+      "For full profile + categories use skills/polymarket-profile."
+    ]
+  };
+  if (json) {
+    printJson(payload);
+    return;
+  }
+  console.log(`\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`);
+  console.log(`  Polymarket Profile \xB7 ${name}`);
+  console.log(`  ${address}`);
+  console.log(`\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`);
+  console.log(`
+\u{1F4CA} PnL (LB API)`);
+  console.log(`  All-time:  ${fmtUsd(pnlAll)}`);
+  console.log(`  7d:        ${fmtUsd(pnl7d)}`);
+  console.log(`  30d:       ${fmtUsd(pnl30d)}`);
+  console.log(`
+\u{1F4C2} Positions (first page)`);
+  console.log(`  Open: ${open.length} \xB7 Unrealized \u2248 ${fmtUsd(unrealized)}`);
+  for (const p of payload.positions.topOpen) {
+    console.log(`  \xB7 ${p.title.slice(0, 48)} \u2014 ${fmtUsd(p.currentValue)}`);
+  }
+  if (brier.n > 0) {
+    console.log(`
+\u{1F3AF} Brier (settled in sample)`);
+    console.log(`  Score: ${brier.brier.toFixed(3)} \xB7 ${brier.wins}/${brier.n} winning markets`);
+  }
+  console.log(`
+\u26A0\uFE0F  ${payload.limitations[2]}`);
+  console.log(`    Audit PnL: skills/polymarket-pnl`);
+}
+
+// ../src/cli/commands/redeem.ts
+async function runRedeem(argv) {
+  const address = argv[0];
+  if (!address) throw new Error("usage: pm redeem <address> [low_watermark]");
+  const lowWatermark = argv[1] ? Number(argv[1]) : void 0;
+  const user = normalizeAddress(address);
+  const rows = await fetchRedeemablePositionsPage(user, { limit: 100, offset: 0 });
+  const summary = summarizeRedeemablePositions(
+    rows
+  );
+  const mode = resolveRedeemMode({ lowWatermark });
+  printJson({
+    user,
+    mode,
+    lowWatermark: lowWatermark ?? null,
+    ...summary,
+    topConditions: summary.topConditions.slice(0, 5)
+  });
+}
+
+// ../src/scanner.ts
+function num(value) {
+  const n = Number(value ?? 0);
+  return Number.isFinite(n) ? n : 0;
+}
+function numOrNull(value) {
+  if (value == null || value === "") return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+function rankMarketsForScan(markets, options = {}) {
+  const minVol = options.minVolume24hr ?? 0;
+  const limit = options.limit ?? 20;
+  const rows = [];
+  for (const m of markets) {
+    if (m.closed === true || m.active === false) continue;
+    const volume24hr = num(m.volume24hrClob ?? m.volume24hr ?? m.volumeNum);
+    if (volume24hr < minVol) continue;
+    rows.push({
+      slug: m.slug ?? "unknown",
+      question: (m.question ?? m.slug ?? "unknown").slice(0, 120),
+      volume24hr,
+      spread: numOrNull(m.spread),
+      liquidity: num(m.liquidityNum ?? m.liquidity),
+      bestBid: numOrNull(m.bestBid),
+      bestAsk: numOrNull(m.bestAsk),
+      acceptingOrders: m.acceptingOrders !== false
+    });
+  }
+  rows.sort((a, b) => b.volume24hr - a.volume24hr || (a.spread ?? 999) - (b.spread ?? 999));
+  return rows.slice(0, limit);
+}
+
+// ../src/cli/commands/scan.ts
+async function runScan(argv) {
+  const json = argv.includes("--json");
+  const limitIdx = argv.indexOf("--limit");
+  const limit = limitIdx >= 0 ? Number(argv[limitIdx + 1] ?? 20) : 20;
+  const minVolIdx = argv.indexOf("--min-volume");
+  const minVolume = minVolIdx >= 0 ? Number(argv[minVolIdx + 1] ?? 0) : 1e3;
+  const raw = await fetchGammaMarkets({
+    limit: 150,
+    active: true,
+    closed: false
+  });
+  const ranked = rankMarketsForScan(raw, { minVolume24hr: minVolume, limit });
+  const payload = {
+    count: ranked.length,
+    minVolume24hr: minVolume,
+    markets: ranked,
+    note: "Sorted by 24h volume \xB7 read-only Gamma snapshot"
+  };
+  if (json) {
+    printJson(payload);
+    return;
+  }
+  console.log(`Market scan \xB7 top ${ranked.length} by 24h volume (min $${minVolume})
+`);
+  for (const m of ranked) {
+    const spread = m.spread != null ? `${(m.spread * 100).toFixed(2)}%` : "n/a";
+    console.log(
+      `  $${m.volume24hr.toLocaleString()} vol \xB7 spread ${spread} \xB7 ${m.question.slice(0, 55)}`
+    );
+    console.log(`    slug: ${m.slug}`);
+  }
+}
+
+// ../src/cli/commands/updown.ts
+async function runUpdown(argv) {
+  const json = argv.includes("--json");
+  const slug = argv.find((a) => !a.startsWith("--"));
+  if (!slug) {
+    throw new Error("usage: pm updown <event-slug> [--json]\n  example: pm updown btc-updown-15m-1779796800");
+  }
+  const events = await fetchGammaEventsBySlug(slug);
+  const event = events[0];
+  if (!event) {
+    throw new Error(`No Gamma event for slug: ${slug}`);
+  }
+  const markets = (event.markets ?? []).map((m) => ({
+    question: m.question,
+    slug: m.slug,
+    conditionId: m.conditionId,
+    groupItemTitle: m.groupItemTitle,
+    outcomePrices: m.outcomePrices,
+    bestBid: m.bestBid,
+    bestAsk: m.bestAsk,
+    spread: m.spread,
+    resolutionSource: m.resolutionSource ?? event.resolutionSource,
+    endDate: m.endDate ?? event.endDate
+  }));
+  const payload = {
+    slug,
+    title: event.title,
+    endDate: event.endDate,
+    resolutionSource: event.resolutionSource,
+    marketCount: markets.length,
+    markets,
+    pitfalls: [
+      "No universal priceToBeat field \u2014 verify resolutionSource + official rules",
+      "Do not use CLOB mid as oracle target without recording your own window open",
+      "See docs/crypto-updown-price-source.md"
+    ]
+  };
+  if (json) {
+    printJson(payload);
+    return;
+  }
+  console.log(`${event.title ?? slug}`);
+  console.log(`  end: ${event.endDate ?? "n/a"}`);
+  console.log(`  resolutionSource: ${(event.resolutionSource ?? "see market page").slice(0, 120)}`);
+  console.log(`  markets: ${markets.length}
+`);
+  for (const m of markets.slice(0, 8)) {
+    console.log(`  \xB7 ${m.groupItemTitle ?? m.question?.slice(0, 50)}`);
+    console.log(`    prices: ${m.outcomePrices} \xB7 bid/ask: ${m.bestBid}/${m.bestAsk} \xB7 spread: ${m.spread}`);
+  }
+  if (markets.length > 8) console.log(`  \u2026 +${markets.length - 8} more`);
+  console.log("\n\u26A0\uFE0F  Read docs/crypto-updown-price-source.md before trading on derived target price.");
+}
+
+// ../src/cli/commands/v2-check.ts
+var CHECKLIST = [
+  "CTF contract unchanged (0x4D97\u20266045) \u2014 split/merge target",
+  "Exchange contract = V2 (not legacy V1 address in your config)",
+  "CLOB client: @polymarket/clob-client-v2 for V2 order path",
+  "Relayer host: relayer-v2.polymarket.com (if using gasless)",
+  "Collateral: pUSD / wrap path matches your env (post cutover)",
+  "Per-market negRisk flag \u2192 correct adapter (merge/split path)",
+  "CTF setApprovalForAll(adapter + exchange) after wallet migration",
+  "Order body: no stale nonce field (V2 SDK)",
+  "Separate CLOB auth errors from on-chain merge reverts"
+];
+async function runV2Check(argv) {
+  const json = argv.includes("--json");
+  const input = argv.find((a) => !a.startsWith("--") && a !== "v2-check");
+  const payload = {
+    checklist: CHECKLIST,
+    docs: "docs/v2-ctf-ops-faq.md",
+    note: "Read-only checklist. On-chain execution is out of scope for this repo."
+  };
+  if (input) {
+    const address = isEvmAddress(input) ? normalizeAddress(input) : null;
+    if (!address) {
+      throw new Error("Optional address must be 0x\u2026 proxy wallet");
+    }
+    const [merges, splits, conversions] = await Promise.all([
+      fetchActivityPages(address, { limit: 200, maxPages: 3, type: "MERGE" }),
+      fetchActivityPages(address, { limit: 200, maxPages: 3, type: "SPLIT" }),
+      fetchActivityPages(address, { limit: 200, maxPages: 3, type: "CONVERSION" })
+    ]);
+    const lastTs = (rows) => {
+      const arr = rows;
+      return arr.length ? arr[arr.length - 1]?.timestamp ?? null : null;
+    };
+    payload.address = address;
+    payload.recentActivity = {
+      merge: { count: merges.rows.length, lastTimestamp: lastTs(merges.rows), warnings: merges.warnings },
+      split: { count: splits.rows.length, lastTimestamp: lastTs(splits.rows), warnings: splits.warnings },
+      conversion: {
+        count: conversions.rows.length,
+        lastTimestamp: lastTs(conversions.rows),
+        warnings: conversions.warnings
+      }
+    };
+  }
+  if (json) {
+    printJson(payload);
+    return;
+  }
+  console.log("V2 / CTF readiness checklist (builder \xB7 read-only)\n");
+  CHECKLIST.forEach((line, i) => console.log(`  ${i + 1}. ${line}`));
+  console.log(`
+Full FAQ: docs/v2-ctf-ops-faq.md`);
+  if (payload.recentActivity) {
+    console.log(`
+Recent on-chain activity sample \xB7 ${payload.address}`);
+    const ra = payload.recentActivity;
+    for (const [k, v] of Object.entries(ra)) {
+      console.log(`  ${k.toUpperCase()}: ${v.count} rows (sample) \xB7 last ts=${v.lastTimestamp ?? "n/a"}`);
+    }
+    console.log("  \u2192 If MERGE count=0 after cutover but SPLIT>0, suspect infra drift (see FAQ).");
+  } else {
+    console.log("\nTip: ./bin/pm v2-check 0xYourProxy \u2014 attach MERGE/SPLIT activity sample");
+  }
+}
+
+// ../src/cli/main.ts
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    usage();
+    return;
+  }
+  switch (cmd) {
+    case "profile":
+      await runProfile(rest);
+      break;
+    case "redeem":
+      await runRedeem(rest);
+      break;
+    case "activity":
+      await runActivity(rest);
+      break;
+    case "brier":
+      await runBrier(rest);
+      break;
+    case "markets":
+      await runMarkets(rest);
+      break;
+    case "scan":
+      await runScan(rest);
+      break;
+    case "updown":
+      await runUpdown(rest);
+      break;
+    case "v2-check":
+      await runV2Check(rest);
+      break;
+    case "lb":
+      await runLb(rest);
+      break;
+    case "pnl-check":
+      await runPnlCheck(rest);
+      break;
+    case "limits":
+      await runLimits(rest);
+      break;
+    default:
+      console.error(`Unknown command: ${cmd}
+`);
+      usage();
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+});