Spaces:
Running
Running
|
Download README.md from sharpflowapp/web: direct link, hf CLI and curl.
- Browser
- Download file 5.1 kB
-
https://huggingface.co/spaces/sharpflowapp/web/resolve/main/README.md
- Command line
-
hf download hf://spaces/sharpflowapp/web/README.md
-
curl -L -o README.md https://huggingface.co/spaces/sharpflowapp/web/resolve/main/README.md
5.1 kB
| 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 <wallet> 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. | |
| ``` | |