web / README.md
LinJennyLin's picture
Deploy SharpFlow (nav + example wallets + Polymarket copy)
d4c51f2 verified
|
Raw History Blame Contribute Delete
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.
```