Working project name. Replace before public commit if you want.
A read-only research tool that tests the hypothesis: "Copying Polymarket's most consistently profitable wallets (Pelosi-tracker style) produces excess returns."
The tool ingests Polymarket's public APIs, identifies candidate "smart money" wallets via the profit leaderboard, filters out market-maker / arbitrageur signatures, replays their trades through a walk-forward backtest, and surfaces results in a small Next.js dashboard.
No live trading. No auto-execution. No order placement. Phase 1 is purely analytical — answering "does the strategy work historically?" before we ever consider trading it.
The original framing was "scrape biggest bets each day" but the actual hypothesis is about copying consistently profitable wallets, not just biggest ones. The largest single trades are typically market-makers, arbitrageurs, or whales taking obvious post-news positions — not insider-flavored alpha. The leaderboard + activity approach is the more direct test.
Read-only first because the value of building auto-execution before validating the signal is zero. If the backtest says no, we're done — cheaply. If it says yes, we have a clear case to build the execution layer in a follow-up project.
Phase 1 is complete when we can answer, with defensible numbers:
- Does following top-leaderboard wallets beat a passive baseline? Baseline = holding USDC over the backtest window (zero return).
- What's the risk-adjusted return after slippage and fill-lag assumptions? Report Sharpe, max drawdown, win rate, and ROI on capital deployed.
- How sensitive is the result to parameters? Lag (5 / 15 / 30 / 60 min), position size, watchlist size (top 20 / 100 / 500), MM filter strictness.
- Does the result hold under walk-forward evaluation? Watchlist at time T determined only from data available before T.
A "yes, build Phase 2" decision requires: positive risk-adjusted return after realistic slippage, holding across at least 3 of 4 sensitivity buckets, under walk-forward (not single-split) evaluation.
A "no, kill the project" decision is equally valuable — the backtest is the experiment.
- Trading, order placement, wallet auth, anything that touches a private key
- Polymarket US specifically — we test on global Polymarket where the volume and history live
- Real-time WebSocket consumption — REST polling is sufficient for daily research
- Mobile app, push notifications, alerts
- Social integrations (Discord, Twitter, etc.)
- Authentication for the dashboard — runs locally for one user
Phase 1 (this project): Tracker + backtester + dashboard. Runs entirely local — no cloud, no hosting. Estimate: 2–3 weeks of focused work.
Phase 2 (conditional on Phase 1 result): Live alerts on tracked wallet activity. Email / push. Real-time CLOB WebSocket integration. Still no auto-execution. Deployed to Vercel with hands-off scheduled syncing; database moves to a hosted SQL store.
Phase 3 (conditional on Phase 2 producing actionable signals you actually act on): Polymarket US integration for execution. Position sizing, risk limits, kill switch. Different repo.
Deployment is split cleanly by phase. Do not build Phase 2 infrastructure during Phase 1.
Phase 1 — local-first. Everything runs on the developer's machine: the Next.js dashboard via next start at localhost:3000, sync scripts run on demand from the CLI, the backtester run from the CLI. The database is a local SQLite file (data/polysmart.db). No Vercel, no vercel.json, no cron infrastructure, no hosted services. This is sufficient because a backtest runs against a frozen historical dataset — it does not need continuous syncing.
Phase 2 — Vercel. Live alerts need hands-off daily syncing and remote dashboard access, so Phase 2 deploys the Next.js app to Vercel with Vercel Cron for scheduled syncs. Because Vercel is serverless (ephemeral filesystem), the database must move off local SQLite to a network-accessible SQL store — Turso (hosted libSQL; near-zero migration from Phase 1 SQLite) or Neon (serverless Postgres; small dialect migration). Turso is preferred for the cheap migration path. Not Firestore — the data is relational and the backtester workload is analytical; see TECHNICAL_SPEC.md §Deployment for the full reasoning. Firebase Cloud Messaging remains a fine option for push-notification delivery if wanted — that is separate from the database choice.
| Decision | Choice | Reasoning |
|---|---|---|
| Data scope | Global Polymarket only | Phase 1 needs years of resolved markets; Polymarket US is months old |
| Evaluation method | Walk-forward | Only honest test against survivorship bias on the leaderboard |
| Stack | TypeScript + Next.js + SQLite | Matches Breezlist precedent; light data work doesn't need Python ecosystem |
| Hosting (Phase 1) | Local only — no cloud | Backtest runs on frozen historical data; needs no live cron or hosting |
| Hosting (Phase 2) | Vercel + Vercel Cron | Live alerts need hands-off syncing and remote access |
| Database (Phase 1) | SQLite, single local file | Embedded, zero-ops, correct for a single-user analytical tool |
| Database (Phase 2) | Turso (or Neon) — not Firestore | Data is relational + workload is analytical; document stores can't join or GROUP BY, and bill per read on scans |
| Backtest window | 18 months of resolved markets, 60-day pre-watchlist minimum per wallet | Enough data for statistical bite without going so far back the user base looked different |
| MM/arb detection | Heuristic, not ML | Tunable thresholds in code; ML is overkill at this scope |
| Source of truth for fill prices | Derived from trade history, not /prices-history |
More honest about achievable fills |
- CLAUDE.md — operating manual for the Claude Code session. Commands, conventions, gotchas. Read first.
- TECHNICAL_SPEC.md — architecture, data model, backtest algorithm, file layout. Read when you need to know the how.
The thing to remember about this project: the answer to "is the signal real" is more valuable than any code we ship. If the backtest comes back negative, that's success. The temptation will be to keep tweaking parameters until something looks profitable — that's how you torture the data into false positives. Set the success bar before running the first backtest, not after seeing the numbers.