Polymarket Copytrading
by @simmer
Mirror positions from top Polymarket traders. Polling mode (free) for portfolio-style copying, Reactor mode (Pro) for event-driven real-time mirroring via Si...
clawhub install polymarket-copytradingπ About This Skill
name: polymarket-copytrading description: Mirror positions from top Polymarket traders. Polling mode (free) for portfolio-style copying, Reactor mode (Pro) for event-driven real-time mirroring via Simmer's on-chain signal infrastructure. metadata: author: Simmer (@simmer_markets) version: "1.10.2" displayName: Polymarket Copytrading difficulty: beginner
Polymarket Copytrading
Mirror positions from successful Polymarket traders using the Simmer SDK. Two modes share the same skill, use whichever fits your strategy:
| | Polling mode (free) | Reactor mode (Pro) |
|---|---|---|
| Entrypoint | copytrading_trader.py | copytrading_trader.py --reactor |
| Cadence | Batch scan, runs on cron or manual | Polls every 2s for pre-resolved whale signals |
| Latency | Minutes (Polymarket Data API polling) | Seconds (Simmer detects events in real-time, pre-confirmation) |
| Strategy | Size-weighted aggregation across wallets, conviction tiering, rebalance to target allocations, drift/stale filters | Event-by-event mirror with fixed mirror_fraction sizing, programmatic filters |
| Best for | Portfolio-aware, multi-whale, periodic scans | Real-time reaction to specific whales as they trade |
| Requires | SIMMER_API_KEY | SIMMER_API_KEY + Simmer Pro plan |
> This is a template. The default logic mirrors whale wallets β remix it with your own wallet selection, sizing rules, filters, or cap logic. The skill handles all the plumbing (signal polling, trade execution, dedup, signing). Your agent provides the alpha.
Setup Flow
When user asks to install or configure this skill:
1. Install the Simmer SDK (version 0.9.19 or newer β reactor mode requires it)
pip install -U 'simmer-sdk>=0.9.19'
2. Ask for Simmer API key
- They can get it from simmer.markets/dashboard β SDK tab
- Store in environment as SIMMER_API_KEY
3. Ask for wallet private key (required for live trading on Polymarket)
- This is the private key for their Polymarket wallet (the wallet that holds USDC)
- Store in environment as WALLET_PRIVATE_KEY
- The SDK uses this to sign orders client-side automatically β no manual signing needed
- Not needed for $SIM paper trading
4. Ask about settings (or confirm defaults) - Target wallets: Whale addresses to copy - Max per position: Amount per trade (default $50) - Top N positions: How many positions to track (auto-calculated from balance) - Max trades per run: Safety cap (default 10)
When to Use This Skill
Use this skill when the user wants to:
Quick Commands
# Check account balance and positions
python scripts/status.pyDetailed position list
python scripts/status.py --positions
API Reference:
https://api.simmer.marketsAuthorization: Bearer $SIMMER_API_KEYGET /api/sdk/portfolioGET /api/sdk/positionsFinding Whale Wallets
Quick Start (Ad-Hoc Usage)
User provides wallet(s) directly in chat:
User: "Copytrade this wallet: 0x1234...abcd"
User: "What positions does 0x5678...efgh have?"
User: "Follow these whales: 0xaaa..., 0xbbb..."
β Run with --wallets flag:
python copytrading_trader.py --wallets 0x1234...abcd
python copytrading_trader.py --wallets 0xaaa...,0xbbb... --dry-run
This is the simplest way - no setup needed, just pass wallets directly.
Persistent Setup (Optional)
For automated recurring scans, wallets can be saved in environment:
| Setting | Environment Variable | Default |
|---------|---------------------|---------|
| Target wallets | SIMMER_COPYTRADING_WALLETS | (none) |
| Top N positions | SIMMER_COPYTRADING_TOP_N | auto |
| Max per position | SIMMER_COPYTRADING_MAX_USD | 50 |
| Max trades/run | SIMMER_COPYTRADING_MAX_TRADES | 10 |
| Order type | SIMMER_COPYTRADING_ORDER_TYPE | GTC |
Top N auto-calculation (when not specified):
Polymarket Constraints:
> β οΈ Start Conservative: Begin with small amounts (--max-usd 5-10) and --dry-run to understand how the skill behaves before scaling up.
How It Works
> By default, only buys execute. Pass --rebalance to also sell positions the whales have exited, or --whale-exits to sell only on whale exits.
Each cycle the script: 1. Fetches positions from all target wallets via Simmer API 2. Combines using size-weighted aggregation (larger wallets = more influence) 3. Detects conflicts (one wallet long YES, another long NO) and skips those markets 4. Scores by conviction: positions held by 2+ wallets get full sizing, single-wallet positions get 50% sizing 5. Filters out drifted (>30% from entry) and stale (>90% or <10% price) positions 6. Applies Top-N filtering to concentrate on highest-conviction positions 7. Auto-imports missing markets from Polymarket 8. Calculates rebalance trades to match target allocations 9. Executes trades via Simmer SDK (respects spending limits) 10. Reports results back to user
Reactor Mode (Pro) β event-driven real-time mirroring
> Requires Simmer Pro. The reactor stream is gated by users.is_pro. Upgrade at simmer.markets/dashboard if you see a 402 error on connect.
Reactor mode polls Simmer for pre-resolved whale trade signals derived from real-time on-chain settlement data. Simmer detects whale trades as they happen β even before on-chain confirmation β and delivers trade-ready signals to your skill. Unlike polling mode (which batches and rebalances), reactor reacts to each whale trade individually.
How it's different from polling mode
mirror_fraction Γ whale size, capped at max_size. No conviction tiering, no rebalance math.min_size are stored in Simmer's reactor config and applied on the server before events reach your skill β you only see matches.--once for cron-style single poll and exit.Configure your reactor watchlist
Reactor uses Simmer-side config (not env vars), so dashboard edits take effect in seconds without restarting the skill.
# Set your watchlist via the Simmer API
curl -X PATCH "https://api.simmer.markets/api/sdk/reactor/config" \
-H "Authorization: Bearer $SIMMER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"wallets": ["0x1234...abcd", "0x5678...efgh"],
"min_size": 1000,
"max_size": 50,
"mirror_fraction": 0.01,
"daily_cap": 100,
"venue": "sim",
"enabled": true
}'
Fields:
| Field | Meaning |
|---|---|
| wallets | Whale addresses to follow (EVM format, lowercased server-side) |
| min_size | Minimum whale trade size to consider (shares) |
| max_size | Cap on your mirror trade size (shares) |
| mirror_fraction | Fraction of whale size to mirror (e.g. 0.01 = 1%) |
| daily_cap | Max total spend per day in venue-native units |
| venue | sim / polymarket / kalshi |
| enabled | Pause reactor by setting false β server will stop delivering events |
| price_buffer | Fraction added above whale's fill price for your buy order. Default 0.02 (2%). Prevents order failures on thin books after whale clears liquidity. Range 0β0.2. |
Run reactor mode
Recommended: cron with --once β polls for pending signals once and exits. Run on a 1-minute cron for reliable, persistent coverage:
# Linux crontab
*/1 * * * * cd /path/to/skill && python copytrading_trader.py --reactor --once --liveOpenClaw cron
openclaw cron add --name "reactor-poll" --cron "*/1 * * * *" --tz UTC --session isolated \
--message "Run: cd /path/to/skill && python3 copytrading_trader.py --reactor --once"One-off check
python copytrading_trader.py --reactor --once
> Why cron? Reactor signals expire after a short window. A cron ensures your agent checks for signals reliably, even after reboots or process crashes. If your polling process stops, signals expire silently β cron prevents this.
Advanced: loop mode β polls every 2s continuously. Lower latency but requires a process manager (launchd, systemd, supervisor) to auto-restart on crash. Not recommended for agent runtimes with exec timeouts.
# With a process manager (launchd, systemd, supervisor)
python copytrading_trader.py --reactorPlain shell (will not auto-restart)
nohup python copytrading_trader.py --reactor > reactor.log 2>&1 &
Set REACTOR_POLL_INTERVAL_SECONDS to tune the polling cadence (default 2s).
> Note: Reactor mode always executes live trades (venue is set in your reactor config). Use venue: "sim" in your config to paper trade.
What happens per signal
1. Skill polls GET /api/sdk/reactor/pending for pre-resolved whale signals
2. Circuit breaker check: if 5+ consecutive failures in recent reactions, skip this tick
3. For each signal: compute mirror size (taker_size Γ mirror_fraction, capped by max_size, floored at 5-share Polymarket minimum)
4. If below minimum β skipped_filter reaction, no trade
5. SimmerClient.trade() with skill_slug="polymarket-copytrading" and source="sdk:copytrading:reactor"
6. On success: DELETE the signal from /api/sdk/reactor/pending/{tx_hash} and POST a mirrored reaction
7. On failure: POST a failed reaction, leave signal (60s TTL clears it)
Example output
[reactor] price_buffer=0.020 (from config)
[reactor] --once: single poll against /api/sdk/reactor/pending
[reactor] 0 pending signals
When a whale trade matches your watchlist:
[reactor] price_buffer=0.020 (from config)
[reactor] loop mode: polling /api/sdk/reactor/pending every 2.0s
[reactor] 1 pending signal(s)
[reactor] 0xbaa2bc... BUY 7067 shares on "Will Iran strike Iraq by April 30, 2026?"
[reactor] mirror: 70.67 shares @ $0.673 (buffer +2.0%) β GTC order placed
[reactor] β
mirrored β trade_id=a23dc52a, signal deleted
External wallets just work
Reactor mode runs in your harness, so SimmerClient.trade() signs locally with your existing wallet setup (managed, or external via WALLET_PRIVATE_KEY). No server-side signing, no OWS dependency, no new keys to manage.
When to use polling vs reactor
$SIM Paper Trading
Copytrading supports $SIM mode β mirror whale positions using simulated money on Simmer's LMSR markets. No wallet or USDC required.
# Paper trade with $SIM (explicit)
python copytrading_trader.py --venue sim --wallets 0x123... --liveAuto-detect: if your account has no linked wallet, $SIM is used automatically
python copytrading_trader.py --wallets 0x123... --live
In $SIM mode:
sdk:copytrading)Running the Skill
Run a scan (dry run by default β no trades):
python copytrading_trader.py
Execute real trades:
python copytrading_trader.py --live
Check positions only:
python copytrading_trader.py --positions
View current config:
python copytrading_trader.py --config
Override wallets for one run:
python copytrading_trader.py --wallets 0x123...,0x456...
Full rebalance mode (includes sells):
python copytrading_trader.py --rebalance
Sell when whales exit positions:
python copytrading_trader.py --whale-exits
Reporting Results
After each run, message the user with:
Example output to share:
π Copytrading Scan CompleteConfiguration:
β’ Following 2 wallets
β’ Top 10 positions, max $50 each
β’ Balance: $250.00 USDC
Fetched positions:
β’ 0x1234...abcd: 15 positions
β’ 0x5678...efgh: 22 positions
β’ Combined: 28 unique markets
β’ Conflicts skipped: 2
Top 10 by allocation:
1. "Will BTC hit $100k?" - 18.5% β BUY YES
2. "Trump pardons X?" - 12.3% β BUY NO
3. "Fed rate cut Jan?" - 9.8% β Already held
...
Trades executed: 4 buys ($180 total)
β’ Bought 45 YES shares on "Will BTC hit $100k?" @ $0.82
β’ Bought 120 NO shares on "Trump pardons X?" @ $0.15
...
Next scan in 4 hours.
Example Conversations
User: "Copytrade 0x1234...abcd"
β Run: python copytrading_trader.py --wallets 0x1234...abcd
β Report what positions that wallet has and what trades would execute
User: "What is 0x5678...efgh holding?"
β Run: python copytrading_trader.py --wallets 0x5678...efgh --dry-run
β Show their positions without trading
User: "Follow these wallets: 0xaaa..., 0xbbb..., 0xccc..."
β Run: python copytrading_trader.py --wallets 0xaaa...,0xbbb...,0xccc...
β Aggregate positions across all wallets, report results
User: "Copytrade this whale but only top 5 positions"
β Run: python copytrading_trader.py --wallets 0x... --top-n 5
User: "How are my positions doing?"
β Run: python copytrading_trader.py --positions
β Show current Polymarket positions with P&L
User: "Show copytrading config"
β Run: python copytrading_trader.py --config
β Display current settings
User: "Sell positions that whales have exited"
β Run: python copytrading_trader.py --whale-exits
β Compares your positions to whales, sells any they've closed
User: "Do a full rebalance to match the whales"
β Run: python copytrading_trader.py --rebalance
β Includes both buys AND sells to match whale allocations
Finding Good Wallets to Follow
Common approaches: 1. Leaderboard tracking: Check Polymarket leaderboards for consistent performers 2. Whale watchers: Follow known profitable traders on social media 3. Specific strategies: Follow wallets known for weather, politics, or crypto trades
The skill works best when:
Conviction Tiers
When following multiple wallets, positions are scored by conviction:
max_usd)High-conviction positions are prioritized in Top N selection. Single-wallet positions still trade, but with reduced size. Using just 1 wallet disables conviction scoring (all positions get full sizing).
Troubleshooting
"Order too small" / "below minimum (5)"
--max-usd or reduce --top-n to concentrate into fewer positions"No wallets specified"
"Agent has no USDC balance"
--venue sim for $SIM paper trading"Conflict skipped"
"All N positions filtered (X conflicts, Y drifted, Z stale)"
"Insufficient balance"
"Market could not be imported"
"External wallet requires a pre-signed order"
WALLET_PRIVATE_KEY is not set in the environmentexport WALLET_PRIVATE_KEY=0x"Balance shows $0 but I have funds on Polygon"
π Tips & Best Practices
"Order too small" / "below minimum (5)"
--max-usd or reduce --top-n to concentrate into fewer positions"No wallets specified"
"Agent has no USDC balance"
--venue sim for $SIM paper trading"Conflict skipped"
"All N positions filtered (X conflicts, Y drifted, Z stale)"
"Insufficient balance"
"Market could not be imported"
"External wallet requires a pre-signed order"
WALLET_PRIVATE_KEY is not set in the environmentexport WALLET_PRIVATE_KEY=0x"Balance shows $0 but I have funds on Polygon"