File size: 5,095 Bytes
8b95d14
d4c51f2
 
 
8b95d14
 
d4c51f2
8b95d14
 
 
d4c51f2
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
---
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.
```