Mirror positions from top Polymarket traders using Simmer API. Size-weighted aggregation across multiple wallets.
--- name: polymarket-copytrading description: Mirror positions from top Polymarket traders using Simmer API. Size-weighted aggregation across multiple wallets. metadata: author: Simmer (@simmer_markets) version: "1.8.4" displayName: Polymarket Copytrading difficulty: beginner --- # Polymarket Copytrading Mirror positions from successful Polymarket traders using the Simmer SDK. > **This is a template.** The default logic mirrors whale wallets by size-weighted allocation — remix it with your own wallet selection criteria, position filters, or rebalancing rules. The skill handles all the plumbing (wallet fetching, conflict detection, trade execution). Your agent provides the alpha. ## When to Use This Skill Use this skill when the user wants to: - Copytrade whale wallets on Polymarket - Paper trade (copytrade with $SIM) to test strategies without real money - Check what positions a wallet holds - Follow specific trader addresses - Check their copytrading positions ## Quick Commands ```bash # Check account balance and positions python scripts/status.py # Detailed position list python scripts/status.py --positions ``` **API Reference:** - Base URL: `https://api.simmer.markets` - Auth: `Authorization: Bearer $SIMMER_API_KEY` - Portfolio: `GET /api/sdk/portfolio` - Positions: `GET /api/sdk/positions` ## Finding Whale Wallets - **[predicting.top](https://predicting.top)** — Leaderboard of top Polymarket traders with wallet addresses - **[alphawhale.trade](https://alphawhale.trade)** — Tools for copying and tracking top performers - **Polymarket Leaderboard** — Official rankings (requires account) ## 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: ```bash 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 | **Top N auto-calculation (when not specified):** - Balance < $50: Top 5 positions - Balance $50-200: Top 10 positions - Balance $200-500: Top 25 positions - Balance $500+: Top 50 positions **Polymarket Constraints:** - Minimum 5 shares per order - SDK enforces $1.00 minimum position value (filters dust positions) > ⚠️ **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 ## $SIM Paper Trading Copytrading supports $SIM mode — mirror whale positions using simulated money on Simmer's LMSR markets. No wallet or USDC required. ```bash # Paper trade with $SIM (explicit) python copytrading_trader.py --venue sim --wallets 0x123... --live # Auto-detect: if your account has no linked wallet, $SIM is used automatically python copytrading_trader.py --wallets 0x123... --live ``` In $SIM mode: - Trades execute on Simmer's LMSR at real Polymarket prices - Each market gets an independent $10K $SIM balance - Positions tracked in your Simmer portfolio (source: `sdk:copytrading`) - Whale signals still come from real Polymarket data ## Running the Skill **Run a scan (dry run by default — no trades):** ```bash python copytrading_trader.py ``` **Execute real trades:** ```bash python copytrading_trader.py --live ``` **Check positions only:** ```bash python copytrading_trader.py --positions ``` **View current config:** ```bash python copytrading_trader.py --config ``` **Override wallets for one run:** ```bash python copytrading_trader.py --wallets 0x123...,0x456... ``` **Full rebalance mode (includes sells):** ```bash python copytrading_trader.py --rebalance ``` **Sell when whales exit positions:** ```bash python copytrading_trader.py --whale-exits ``` ## Reporting Results After each run, message the user with: - Current configuration (wallets, Top N, max position) - Number of wallets fetched and total positions found - Markets skipped due to conflicts - Trades executed (or skipped with reason) - Current portfolio positions Example output to share: ``` 🐋 Copytrading Scan Complete Configuration: • 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: - Following 2-5 wallets with **overlapping strategies** (e.g. all politics-focused, or all crypto-focused) - Wallets have similar conviction — mixing very different traders means most positions only appear in one wallet and get reduced sizing (50%) - Wallets trade markets available on Polymarket ### Conviction Tiers When following multiple wallets, positions are scored by conviction: - **High conviction** (held by 2+ wallets): full position sizing (`max_usd`) - **Low conviction** (held by 1 wallet): 50% position sizing 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)"** - Polymarket requires minimum 5 shares per order - Increase `--max-usd` or reduce `--top-n` to concentrate into fewer positions **"No wallets specified"** - Provide wallet addresses in your message, e.g., "copytrade 0x1234..." - Or set SIMMER_COPYTRADING_WALLETS environment variable for recurring scans **"Agent has no USDC balance"** - Need USDC in your Polymarket wallet, or use `--venue sim` for $SIM paper trading - Check wallet is linked at simmer.markets/dashboard **"Conflict skipped"** - Wallets disagree on this market (one long YES, other long NO) - Markets with net position < 10% are skipped **"All N positions filtered (X conflicts, Y drifted, Z stale)"** - All whale positions were removed by safety filters - Try different target wallets, or reduce to 1 wallet to disable conviction scoring - Drift filter skips positions where price moved >30% from whale's entry - Stale filter skips near-resolved markets (price >90% or <10%) **"Insufficient balance"** - Not enough USDC for all trades - Reduce SIMMER_COPYTRADING_TOP_N or SIMMER_COPYTRADING_MAX_USD **"Market could not be imported"** - Some markets may not be importable (resolved, private, etc.) - These are skipped automatically **"External wallet requires a pre-signed order"** - `WALLET_PRIVATE_KEY` is not set in the environment - The SDK signs orders automatically when this env var is present — no manual signing code needed - Fix: `export WALLET_PRIVATE_KEY=0x<your-polymarket-wallet-private-key>` - Do NOT attempt to sign orders manually or modify the skill code — the SDK handles it **"Balance shows $0 but I have USDC on Polygon"** - Polymarket uses **USDC.e** (bridged USDC, contract `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`) — not native USDC - If you bridged USDC to Polygon recently, you likely received native USDC - Swap native USDC to USDC.e, then retry
don't have the plugin yet? install it then click "run inline in claude" again.
by @clawhub
added explicit decision points for wallet input, execution mode, rebalancing, auto-sizing, conflict handling, api failures, and edge cases; structured procedure as 13 numbered steps with clear input/output per step; documented all environment variables, polymarket constraints, and external connections; added comprehensive error handling and decision branches throughout; clarified conviction scoring, top-n filtering, and safety filters as discrete steps; provided detailed output contracts for dry-run, live, error, config, and position reporting modes; outcome signals now measure user visibility of trades, positions, config, and clear error messaging.
Mirror positions from successful Polymarket traders using the Simmer SDK. Use this when you want to automatically buy the same positions as whale wallets, test strategies with paper money ($SIM), or track what specific traders hold. The skill aggregates positions across multiple wallets using size-weighted logic, filters out conflicts and stale markets, and executes trades respecting your spending limits. You provide the wallets; the skill handles wallet fetching, position aggregation, conflict detection, and trade execution.
External Connections
https://api.simmer.markets, auth: Bearer $SIMMER_API_KEY)0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174)Environment Variables
| Variable | Purpose | Example | Required |
|---|---|---|---|
SIMMER_API_KEY |
API authentication | sk_live_... |
yes |
SIMMER_COPYTRADING_WALLETS |
Persistent wallet list (semicolon-separated) | 0x1234...;0x5678... |
no (can override per-run) |
SIMMER_COPYTRADING_TOP_N |
Number of top positions to trade | 10 |
no (auto-calculated by balance) |
SIMMER_COPYTRADING_MAX_USD |
Max USD per position | 50 |
no (default: $50) |
SIMMER_COPYTRADING_MAX_TRADES |
Max trades per run | 10 |
no (default: 10) |
WALLET_PRIVATE_KEY |
Polymarket wallet private key (auto-signs orders) | 0x... |
no (required for live trades from external wallet) |
Balance-Based Auto-Sizing (Top N)
Polymarket Constraints
Fetch wallet configuration
SIMMER_COPYTRADING_WALLETS env var OR --wallets CLI flag OR user-provided addressesFetch positions from all target wallets
GET /api/sdk/positions for each wallet via Simmer SDKAggregate positions using size-weighted logic
Detect and skip conflicts
Apply safety filters (drift and staleness)
Score by conviction and apply Top N filter
Calculate position sizes (USD and shares)
SIMMER_COPYTRADING_MAX_USDmax_usdmax_usd * 0.5shares = usd / current_price (minimum 5 shares)--max-usd)Auto-import missing markets (if not already on Polymarket)
Determine execution mode
--live, account wallet status, --venue flag--live AND account has linked USDC wallet: use real USDC trades--live AND NO linked wallet (or --venue sim): use paper trading ($SIM on Simmer LMSR)--live flag (default): dry-run mode (no trades, show plan only)Calculate rebalance trades (if --rebalance or --whale-exits flag)
--rebalance: compare current holdings to target allocations; generate sells for positions whales have exited and buys for new positions--whale-exits only: generate sells for any position where all target wallets have exitedCheck spending limits
SIMMER_COPYTRADING_MAX_TRADESExecute trades (live mode only)
WALLET_PRIVATE_KEY (if external wallet)WALLET_PRIVATE_KEY is set)Fetch updated portfolio and report results
GET /api/sdk/portfolio to get updated positionsWallet Input
SIMMER_COPYTRADING_WALLETS is set, use persistent list.Execution Mode (--live flag)
--live flag is absent: dry-run only (show plan, no trades).--live flag is present AND account has linked USDC wallet: execute real trades on Polymarket.--live flag is present AND NO linked wallet (or --venue sim): execute paper trades on Simmer LMSR ($SIM).Rebalancing (--rebalance vs. --whale-exits vs. default)
--rebalance flag: buy new positions AND sell positions whales have exited (full rebalance).--whale-exits flag: only sell positions whales have exited, no new buys.Top N Auto-Calculation
SIMMER_COPYTRADING_TOP_N is set, use that.Conviction Scoring (single vs. multiple wallets)
Conflict Handling
Empty Result Sets
API Failures & Retries
Order Sizing Failures
--max-usd or reducing Top N.Market Import Failures
USDC.e Token Edge Case
0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174), not native USDC. Advise swap if needed.Dry-Run Output (default, no --live)
🐋 Copytrading Scan Complete (DRY RUN)
Configuration:
• Following 2 wallets
• Top 10 positions, max $50 each
• Account balance: $250.00 USDC
• Mode: buy-only (no sells)
Fetched positions:
• 0x1234...abcd: 15 positions
• 0x5678...efgh: 22 positions
• Combined: 28 unique markets
• Markets skipped (conflicts): 2
Top 10 by conviction:
1. "Will BTC hit $100k?" (2 wallets) - 18.5% allocation → BUY 45 YES @ $0.82 = $36.90
2. "Trump pardons X?" (2 wallets) - 12.3% allocation → BUY 120 NO @ $0.15 = $18.00
3. "Fed rate cut Jan?" (1 wallet) - 9.8% allocation → Already held
...
Proposed trades (not executed):
• BUY 45 YES shares on "Will BTC hit $100k?" @ $0.82 = $36.90
• BUY 120 NO shares on "Trump pardons X?" @ $0.15 = $18.00
• [Total: 2 trades, $54.90 spend]
Current portfolio positions:
• YES on "Will BTC hit $100k?" - 100 shares @ $0.75 avg = +$175.00 unrealized
• NO on "Fed rate cut Jan?" - 50 shares @ $0.40 avg = -$8.00 unrealized
...
To execute: re-run with --live
Live-Trade Output (--live flag)
🐋 Copytrading Scan Complete (EXECUTED)
Configuration:
• Following 2 wallets
• Top 10 positions, max $50 each
• Account balance: $250.00 USDC
• Mode: buy-only (no sells)
• Venue: Polymarket (USDC)
Fetched positions:
• 0x1234...abcd: 15 positions
• 0x5678...efgh: 22 positions
• Combined: 28 unique markets
• Markets skipped (conflicts): 2
Top 10 by conviction:
1. "Will BTC hit $100k?" (2 wallets) - 18.5% allocation
2. "Trump pardons X?" (2 wallets) - 12.3% allocation
...
Trades executed:
✓ BUY 45 YES shares on "Will BTC hit $100k?" @ $0.82 = $36.90 (txn 0xabc123...)
✓ BUY 120 NO shares on "Trump pardons X?" @ $0.15 = $18.00 (txn 0xdef456...)
[Total: 2 trades executed, $54.90 spent]
Updated portfolio positions:
• YES on "Will BTC hit $100k?" - 145 shares @ $0.81 avg = +$211.45 unrealized
• NO on "Trump pardons X?" - 120 shares @ $0.15 avg = -$18.00 unrealized
...
Account balance after trades: $195.10 USDC
Next scan in 4 hours (configurable).
Error Output Example
❌ Copytrading failed
Error: "Conflict skipped: all 28 positions filtered (15 conflicts, 8 drifted >30%, 5 stale price)"
→ Suggestion: try different wallets, reduce conviction filter, or lower price drift threshold
OR
Error: "Order too small: 3 shares < minimum 5"
→ Suggestion: increase --max-usd or reduce --top-n to concentrate into fewer positions
OR
Error: "Insufficient balance: need $180.50 for 4 trades, have $75.00"
→ Suggestion: add USDC to wallet or reduce Top N
Config Output (--config flag)
Current Copytrading Config:
• Wallets: 0x1234...abcd, 0x5678...efgh
• Top N: 10 (auto-calculated from balance $250)
• Max per position: $50 USD
• Max trades per run: 10
• Mode: buy-only (no sells)
• Venue: auto-detect (USDC if linked, else $SIM)
• API Key: [set]
• Wallet private key: [not set] (required for external wallet signing)
Positions Output (--positions flag)
Your Copytrading Positions:
YES on "Will BTC hit $100k?" - 100 shares @ $0.75 avg entry
• Current price: $0.82
• Unrealized P&L: +$7.00 (+7.0%)
• Source: copied from 0x1234...abcd (whale entry: $0.70)
NO on "Fed rate cut Jan?" - 50 shares @ $0.40 avg entry
• Current price: $0.42
• Unrealized P&L: -$1.00 (-2.0%)
• Source: copied from 0x5678...efgh (whale entry: $0.38)
Total portfolio value (Polymarket): $245.00 USDC
Total unrealized P&L: +$6.00 (+2.5%)
Success is when:
--positions flag shows current holdings with entry prices, unrealized P&L, whale sources--config flag displays active wallet list, Top N, max USD, execution modeIf --live is passed but no trades execute, the output explains why (conflicts, filtering, insufficient balance) rather than silently failing.
Credits: Original skill by Simmer (@simmer_markets). Enriched per Implexa standards.