traders-v2 contract

Boards

• pnl:1d / pnl:7d / pnl:30d / pnl:all — top 50 by upstream Data API leaderboard PnL for that window (Polymarket periods DAY / WEEK / MONTH / ALL).
• sharpe:30d / sharpe:all— top 50 by daily unannualized Sharpe among that window's top-500 PnL candidates.
• No 1d or 7d Sharpe boards (too few daily deltas at the observation floor).

Data feeds

• Data API: positions, closed-positions, trades (dual taker/all)
• user-PnL API: equity curve, Sharpe / Sortino / drawdown
• Gamma: tags, endDate, closedTime, resolution
• CLOB prices-history: CLV, alpha, contrarian, post-fill drift

Frozen Tier 2 choices

• Dual-pull endTs — freeze floor(now) before either /trades call; both query ≤ endTs. Maker = all ∖ taker.
• Maker side — Data API side is taker-perspective; invert BUY/SELL for maker fills before FIFO.
• FIFO — buy→sell per asset; negative inventory → unexplained-source lot (excluded from per-lot metrics; asset marked partial). Full lot logs on R2.
• FIFO ↔ positions — reconcile ending inventory; mismatch → ledger metrics partial.
• Holding / disposition / max concurrent — sold-lots-only until Gamma resolution closes; then recompute. Lot logs on R2 include resolution closes when Gamma resolves the asset.
• Held to resolution— share of resolved assets still held (non-dust) at resolve, using dust OR rule (shares < 0.01 or notional < $0.01).
• Dust — shares < 0.01 ornotional < $0.01.
• Capital velocity — Σ|size×price| / Σ(avgPrice×totalBought). Never peak user-PnL.
• CLV— last candle ≤ actual resolve (prefer Gamma closedTime; else endDate − 1h). Exclude if candle age > 24h.
• Alpha vs F&H — highest-mid outcome at first fill; publish α$ and ROI-gap.
• Contrarian — 24h lookback, ≥2 candles.
• Post-fill drift — K=6 hourly candles, min 2 available; labeled drift not impact. Mean drift and mean candle count are both published.
• Brier — notional-weighted headline; unweighted in detail.
• Tilt — next 5 fills after closed-position loss timestamp; overlapping windows share fills.
• MM gate — two-sided / spread capture require maker notional share ≥ 0.25.

Behavioral archetypes (archetypes-v1)

Labels describe how a wallet trades, not how skilled it is. Skill is a separate A/B/C/D/F grade from Brier, CLV, and Sortino/Calmar. Classification is a pure function of one wallet (frozen natural-unit anchors in trader-methodology.ts).

• Tourist gate (fail if ANY)— trades < 30 or markets < 10 oractive-days ratio < 0.02. Dormant / one-day-blitz wallets with tiny active-days ratio are intentionally Tourist even with high lifetime trade count.
• Market Maker override — maker share ≥ 0.70 and two-sided activity; skill grade N/A (forecast metrics do not apply to inventory flow).
• Soft scores — Scalper, News Sniper, Early-Bird Forecaster, Conviction Holder, Favorite Grinder, Longshot Hunter, Contrarian Fader, Tilted Gambler. Weight coverage floor 0.6; thin margin → secondary label. No CLV/Sortino/Brier in behavioral weights.
• Board fallback — Unclassified when coverage is insufficient for all soft archetypes.
• Tilt overlay — warning flag when tilt score is high but another archetype wins.
• Statistically unusual win pattern (improbableWins) — ≥3 cheap held-to-resolution wins whose late-weighted joint entry price ≤ 0.001, plus ≥2 confirmers (size outlier, selectivity, unhedged contrast). Late entries (entryTiming ≥ 0.7) discount the price in the product (stronger evidence). Threshold is deliberately conservative under multiple-testing across the candidate universe. Flag is statistical evidence only — never displaces the behavioral primary; may annotate the skill grade. Not shown on share images.
• Copy-trader remains an always-false flag until pairwise lag detection exists.

Completeness

Every metric carries source, window, methodology version, and completeness (complete / partial / unavailable). Partial or unavailable values render as N/A, never zero. PnL families (realized closed / open / leaderboard / user-series) are never silently combined.

Publish gate

A release activates iff ≥95% of candidate wallets produce a schema-valid TraderProfileSnapshot. Failed = throw / timeout / invalid schema. Metrics with completeness: partial do not fail the gate or count against the 95%. Boards must have exactly 50 rows.

Refresh cadence

Trader metrics are recomputed once per day (Cloudflare cron 0 2 * * * UTC). Profiles, FIFO ledgers, Gamma joins, and prices-history style scores all land in the same daily release. Pages read that snapshot only — no per-request Polymarket calls — so a 24h lag is expected and intentional to bound API cost.

Out of scope

Deposit-based bankroll, copy-trade discovery, Falcon paid metrics, ClickHouse release history, full CTF split/merge/redeem reconstruction (unexplained-source + reconcile only).