--- title: SharpFlow emoji: πŸ”· colorFrom: green colorTo: gray sdk: docker app_port: 7860 pinned: false --- # pmct β€” Polymarket copy-trade research toolkit Research + backtest only. **No live trading, no wallet, no funds.** This toolkit scans Polymarket traders, finds the ones that are (a) long-term profitable and (b) trading a repeatable pattern, then backtests copy-trading them with **conviction-based position sizing** (ε€‰δ½θ·Ÿθ‘—ζŠŠζ‘η¨‹εΊ¦θ΅°). You run it on your own machine β€” it talks to Polymarket's public read APIs. ## Pipeline ``` 01_discover_wallets.py leaderboard + market whales -> data/candidates.json 02_analyze_wallets.py fetch history, compute metrics -> data/wallets.csv + pattern/repeatability features data/ledgers/*.parquet 03_screen.py apply the two gates, rank -> data/shortlist.csv 04_backtest.py conviction vs flat, equity curve -> data/backtest_*.png ``` ## Quick start ```bash cd polymarket-copytrade python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt cp config.example.yaml config.yaml # edit thresholds if you want python scripts/01_discover_wallets.py python scripts/02_analyze_wallets.py # slowest step (one API pass per wallet) python scripts/03_screen.py python scripts/04_backtest.py # backtests top of shortlist ``` ## The two screens (your rules) **Gate A β€” long-term consistent profit** (`screen:` in config): `total_pnl`, `roi`, `win_rate`, `max_drawdown_pct`, `monthly_profit_ratio` (share of active months that were green), plus `min_active_days` / `min_resolved_markets` so a lucky week can't pass. **Gate B β€” repeatable, replicable pattern** (`patterns.py`): each wallet is reduced to entry-price-band tightness, sizing consistency, topic concentration, and cadence regularity, scaled by trade count, into one `repeatability` ∈ [0,1]. Copy a strategy, not a coin flip. **Gate C β€” copyable, not market-making** (`max_rebate_share`): many top leaderboard wallets profit from maker/taker rebates and liquidity rewards β€” an edge you *cannot* copy. We measure `rebate_share` (incentive income Γ· authoritative profit) and reject wallets above the threshold. **Authoritative profit.** For wallets on the leaderboard we rank on Polymarket's own reported profit (`lb-api/profit`), not our reconstruction β€” the reconstructed PnL is only a cross-check / the fallback for unranked wallets. ## Conviction sizing (`sizing.py`) We never copy the target's dollar amount. Per entry we infer conviction ∈ [0,1]: ``` conviction = w_stake Β· stake_signal + w_edge Β· edge_signal stake_signal = how big this bet was vs the target's own typical bet edge_signal = |price βˆ’ 0.5| Β· 2 (distance from a coin flip) ``` Our stake = `bankroll Β· frac`, where `frac` scales from `min_frac_per_trade` (no conviction) up to `max_frac_per_trade` (full conviction), then is clamped by a `kelly_cap Β· kelly_fraction` ceiling and a `max_frac_per_market` aggregate cap. Defaults are tuned for a <$1k, conservative bankroll. ## Important caveats β€” read before trusting a number - **Endpoints verified live (2026-07)** against the real API: Gamma `/markets`, CLOB `/price` `/prices-history`, Data API `/activity` `/positions` `/holders` `/value`, and the leaderboard at `lb-api.polymarket.com/profit` `/volume` (windows: `all` `1d` `7d` `30d`). If Polymarket later moves a path, fix it in `pmct/client.py` (one place). - **History is capped at ~3500 most-recent activities per wallet.** The Data API refuses offset paging past 3000 ("max historical activity offset of 3000 exceeded"). Enough for pattern/behavior analysis; for lifetime profit we use the authoritative leaderboard number instead of reconstructing. - **Reconstructed PnL validated** to ~11% of the authoritative leaderboard figure on a full-history wallet ($3.61M vs $4.05M) β€” the gap is open-position marking + rebates + methodology. Trust `profit_final` (leaderboard) over `total_pnl`. - **Resolution is approximated** from the activity ledger (net share balance + redemptions), not from on-chain payout events. Good enough for ranking; not an accounting statement. Win-rate is the weakest metric β€” prefer profit + consistency. - **Backtest fills are approximate**: entry/exit = target's price Β± slippage; `copy_delay_sec` is folded into slippage rather than modeled tick-by-tick. Real copy-trading is worse than backtest β€” you react after the target moves the price. Treat backtest returns as an optimistic ceiling. - **Past performance β‰  future.** Prediction-market edges decay and crowd out. This is a research scaffold, not investment advice. ## Next step toward live (only after backtests convince you) The live agent would poll `data-api /activity` for your shortlisted wallets, detect new fills, and place mirrored orders via `py-clob-client` with the same `sizing.py` logic. That needs a funded Polygon wallet + CLOB API creds β€” not included here on purpose, since you're at the research stage. ```