{"id":"cb8cd98e-8598-4947-a824-292271846aa3","entityType":"agent","slug":"clawhub-simmer-polymarket-copytrading","name":"polymarket-copytrading","canonicalUrl":"https://www.xpersona.co/agent/clawhub-simmer-polymarket-copytrading","canonicalPath":"/agent/clawhub-simmer-polymarket-copytrading","generatedAt":"2026-10-09T15:07:38.292Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:02:09.073Z","emptyReason":null},"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.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 4.7K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17eez0vajry6hjb97y9mbtv2s85wekv:polymarket-copytrading","sourceUrl":"https://clawhub.ai/simmer/polymarket-copytrading","homepage":"https://clawhub.ai/simmer/skills/polymarket-copytrading","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/simmer/polymarket-copytrading","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/simmer/skills/polymarket-copytrading","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":73,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"polymarket-copytrading technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:02:09.073Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:02:09.073Z","emptyReason":null},"stars":null,"forks":null,"downloads":4674,"packageName":null,"latestVersion":"1.12.4","tractionLabel":"4.7K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:02:09.073Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T05:02:09.073Z","lastCrawledAt":"2026-10-09T05:02:09.073Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T05:02:09.073Z","lastVerifiedAt":null,"highlights":[{"version":"1.12.4","createdAt":"2026-09-23T03:10:45.894Z","changelog":"- Bumped version to 1.12.4. - Minor documentation updates in SKILL.md. - Removed deprecated skill-card.md file. - No changes to user-facing features or logic.","fileCount":10,"zipByteSize":35930},{"version":"1.12.3","createdAt":"2026-09-06T01:11:17.423Z","changelog":"polymarket-copytrading 1.12.3 - Updated version metadata to 1.12.3. - Documentation refresh in SKILL.md; reflects current behavior and recommendations. - Removed deprecated skill-card.md file. - No changes to user-facing commands or functionality.","fileCount":10,"zipByteSize":35346},{"version":"1.12.2","createdAt":"2026-08-05T01:17:18.628Z","changelog":"daily_cap semantics: skill-enforced at execution + server-side 3x runaway guard on proposals; capped feeds surface skipped_daily_cap in reactor status","fileCount":10,"zipByteSize":35136},{"version":"1.12.1","createdAt":"2026-06-26T03:19:50.563Z","changelog":"Reactor now mirrors maker (limit-order) fills, not just taker fills (SIM-3297); announces caps=maker so the server delivers them safely","fileCount":10,"zipByteSize":35083},{"version":"1.12.0","createdAt":"2026-06-26T01:58:32.753Z","changelog":"Reactor: delete signals by signal_id (SIM-3297) so maker-leg fills aren't re-executed until TTL","fileCount":10,"zipByteSize":34928},{"version":"1.11.2","createdAt":"2026-06-11T04:03:21.204Z","changelog":"- Added tests directory and initial unit tests for venue routing logic. - Improved code quality and testability in copytrading_trader.py. - Removed obsolete skill-card.md documentation file. - Updated documentation to reflect latest version and minor improvements.","fileCount":10,"zipByteSize":34463},{"version":"1.11.1","createdAt":"2026-05-23T14:43:31.072Z","changelog":"Relocate DISCLAIMER reference from line 50 to first 30 lines + add quantitative bounding language (caps, paper-mode mention) to deflect ASI-taxonomy flags. Catalog-reshape Tier 2 step 2.","fileCount":8,"zipByteSize":29762},{"version":"1.10.2","createdAt":"2026-04-24T10:06:35.875Z","changelog":"Polymarket Copytrading v1.10.2 - Documentation and metadata updates for clarity and consistency. - No functional or API changes; all existing behavior is preserved. - Version bump to maintain alignment with project updates.","fileCount":6,"zipByteSize":24614}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17eez0vajry6hjb97y9mbtv2s85wekv:polymarket-copytrading","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17eez0vajry6hjb97y9mbtv2s85wekv:polymarket-copytrading` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/simmer/polymarket-copytrading before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simmer-polymarket-copytrading/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simmer-polymarket-copytrading/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simmer-polymarket-copytrading/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-simmer-polymarket-copytrading/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-simmer-polymarket-copytrading/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-simmer-polymarket-copytrading/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T15:07:38.286Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simmer-polymarket-copytrading/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simmer-polymarket-copytrading/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simmer-polymarket-copytrading/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simmer-polymarket-copytrading/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:02:09.073Z","emptyReason":null},"readme":"Skill: polymarket-copytrading\n\nOwner: simmer\n\nSummary: 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.\n\nTags: latest:1.12.4\n\nVersion history:\n\nv1.12.4 | 2026-09-23T03:10:45.894Z | auto\n\n- Bumped version to 1.12.4.\n- Minor documentation updates in SKILL.md.\n- Removed deprecated skill-card.md file.\n- No changes to user-facing features or logic.\n\nv1.12.3 | 2026-09-06T01:11:17.423Z | auto\n\npolymarket-copytrading 1.12.3\n\n- Updated version metadata to 1.12.3.\n- Documentation refresh in SKILL.md; reflects current behavior and recommendations.\n- Removed deprecated skill-card.md file.\n- No changes to user-facing commands or functionality.\n\nv1.12.2 | 2026-08-05T01:17:18.628Z | user\n\ndaily_cap semantics: skill-enforced at execution + server-side 3x runaway guard on proposals; capped feeds surface skipped_daily_cap in reactor status\n\nv1.12.1 | 2026-06-26T03:19:50.563Z | user\n\nReactor now mirrors maker (limit-order) fills, not just taker fills (SIM-3297); announces caps=maker so the server delivers them safely\n\nv1.12.0 | 2026-06-26T01:58:32.753Z | user\n\nReactor: delete signals by signal_id (SIM-3297) so maker-leg fills aren't re-executed until TTL\n\nv1.11.2 | 2026-06-11T04:03:21.204Z | auto\n\n- Added tests directory and initial unit tests for venue routing logic.\n- Improved code quality and testability in copytrading_trader.py.\n- Removed obsolete skill-card.md documentation file.\n- Updated documentation to reflect latest version and minor improvements.\n\nv1.11.1 | 2026-05-23T14:43:31.072Z | user\n\nRelocate DISCLAIMER reference from line 50 to first 30 lines + add quantitative bounding language (caps, paper-mode mention) to deflect ASI-taxonomy flags. Catalog-reshape Tier 2 step 2.\n\nv1.10.2 | 2026-04-24T10:06:35.875Z | auto\n\nPolymarket Copytrading v1.10.2\n\n- Documentation and metadata updates for clarity and consistency.\n- No functional or API changes; all existing behavior is preserved.\n- Version bump to maintain alignment with project updates.\n\nv1.10.1 | 2026-04-23T05:56:28.366Z | user\n\nV2 migration (2026-04-28): updated troubleshooting copy to point users at the Wrap USDC.e → pUSD flow at simmer.markets/dashboard + docs.simmer.markets/v2-migration. Also refines clawhub.json envVars schema (WALLET_PRIVATE_KEY now correctly optional for managed-wallet users).\n\nv1.9.3 | 2026-04-22T09:15:14.619Z | user\n\nSchema fix: primaryEnv + envVars with required:false for optional credentials. Clears OpenClaw 'disproportionate requirements' verdict.\n\nv1.9.2 | 2026-04-22T08:25:15.134Z | user\n\nDeclare WALLET_PRIVATE_KEY in requires.env for OpenClaw moderation alignment.\n\nv1.9.1 | 2026-04-16T09:55:54.182Z | user\n\nAdd Setup Flow section with pip install simmer-sdk\n\nv1.9.0 | 2026-04-14T09:58:23.884Z | auto\n\n**Polymarket Copytrading v1.9.0**  \nMajor update: Adds real-time event-driven mirroring (Reactor mode) alongside existing polling (batch) mode.\n\n- Introduces Reactor mode (Pro): real-time, event-driven copytrading via Simmer PolyNode signals, with per-wallet, per-trade sizing and server-side filters.\n- SKILL.md extensively updated: documents both classic portfolio/polling and new Reactor (Pro) modes, with comparison table, setup, and usage examples.\n- Configuration options expanded—now includes order type (`SIMMER_COPYTRADING_ORDER_TYPE`) and more server-driven controls for Reactor mode.\n- Maintains all existing features for polling mode; users can freely choose or mix modes as needed.\n- Requirements updated; see requirements.txt for any new dependencies.\n\nv1.8.5 | 2026-04-03T02:46:59.382Z | user\n\nAdd auto_redeem() call at start of each cycle for external wallet support\n\nv1.8.4 | 2026-04-02T05:39:30.640Z | user\n\nAdd requirements.txt for standalone subprocess execution (fixes reactor autoReact)\n\nv1.8.3 | 2026-03-29T07:03:55.946Z | auto\n\n**polymarket-copytrading v1.8.3 Changelog**\n\n- Updated core logic in `copytrading_trader.py` (details not specified in the diff).\n- No user-facing documentation changes.\n- Version bump from 1.8.2 to 1.8.3.\n\nv1.8.2 | 2026-03-29T03:39:57.415Z | auto\n\nPolymarket Copytrading 1.8.2\n\n- Updated version to 1.8.2.\n- Removed the legacy _meta.json metadata file.\n- Documentation and metadata have been refreshed to match the current version.\n\nv1.8.1 | 2026-03-25T08:48:43.234Z | auto\n\n**Version 1.8.1 Changelog**\n\n- Updated SKILL.md metadata version from 1.7.0 to 1.8.0.\n- Added _meta.json file to the repository.\n- No changes to core skill logic or feature set.\n\nv1.8.0 | 2026-03-21T10:21:19.084Z | user\n\nAdd --reactive mode for reactor plugin integration: trades specific whale event markets instead of full portfolio rebalance, auto-imports missing markets, resolves YES/NO outcome from PolyNode data\n\nv1.7.1 | 2026-03-17T09:40:55.408Z | auto\n\npolymarket-copytrading 1.7.1\n\n- Updated internal logic in copytrading_trader.py (specifics not detailed).\n- No user-facing changes to documentation or config.\n- Version and feature set otherwise unchanged from 1.7.0.\n\nv1.7.0 | 2026-03-13T16:43:18.766Z | auto\n\n**Version 1.7.0 – Adds signal conviction and position quality filters**\n\n- Positions now receive conviction scores: full size if held by 2+ wallets, reduced (50%) if only in one wallet.\n- New filters exclude positions that are highly drifted (over 30% from entry) or have stale prices (over 90% or under 10%).\n- Leaderboard advice updated: mixing different trader types reduces conviction; overlapping strategies are recommended.\n- Documentation updated to describe new scoring, filtering, and rebalancing logic.\n\nv1.5.4 | 2026-03-08T16:02:29.643Z | auto\n\n- Bumped version to 1.5.4 in SKILL.md.\n- Clarified that, by default, only buys execute—use `--rebalance` or `--whale-exits` for selling positions.\n- No other functional or structural changes noted.\n\nv1.5.3 | 2026-03-05T19:09:56.820Z | auto\n\npolymarket-copytrading v1.5.3\n\n- Updated version metadata to 1.5.3 in SKILL.md for clarity and consistency.\n- No user-facing functional changes; documentation and metadata update only.\n\nv1.5.2 | 2026-03-05T13:26:46.037Z | user\n\nRename venue simmer to sim\n\nv1.5.1 | 2026-03-03T02:53:00.729Z | user\n\nAgentSkills format — moved platform config to clawhub.json for cross-agent compatibility\n\nv1.5.0 | 2026-02-28T07:03:05.430Z | auto\n\n**Added configurable whale wallet addresses as an environment variable.**\n\n- New tunable option: `SIMMER_COPYTRADING_WALLETS` for setting whale wallet addresses via environment variable or UI.\n- Updated metadata to include this setting for easier configuration and persistent copytrading setups.\n- No functional changes to trading logic or workflow.\n- Minor documentation update to reflect new configuration option.\n\nv1.3.13 | 2026-02-27T10:04:49.199Z | auto\n\n- Added \"difficulty: beginner\" field to skill metadata for easier discovery and categorization.\n- No user-facing behavior or logic changes; documentation and usage remain unchanged.\n\nv1.3.12 | 2026-02-27T05:51:38.980Z | auto\n\n- Updated logic in copytrading_trader.py to improve behavior or fix an issue (see commit for details).\n- No changes to user interface or configuration.\n- Documentation (SKILL.md) remains unchanged.\n\nv1.3.11 | 2026-02-27T03:55:19.820Z | user\n\nAdd is_live_now field to Market dataclass; forward-compatible filter to skip not-yet-open markets\n\nv1.3.10 | 2026-02-24T15:15:11.958Z | auto\n\nNo file changes detected for version 1.3.10.\n\n- No updates or modifications found in this version.\n- Functionality and documentation remain unchanged from the previous release.\n\nv1.3.9 | 2026-02-24T13:04:04.600Z | auto\n\n**Polymarket Copytrading 1.4.0 – Adds $SIM Paper Trading Support**\n\n- Introduced support for paper trading with $SIM: easily test copytrading strategies risk-free without a wallet or USDC.\n- Now detects and switches to $SIM mode automatically if no wallet is linked.\n- Updated SKILL metadata for automaton compatibility; WALLET_PRIVATE_KEY no longer required.\n- Expanded documentation in SKILL.md to describe how to use $SIM mode for simulated trading.\n- Retains all core aggregation, filtering, and reporting features for live and simulated copytrading.\n\nv1.3.8 | 2026-02-17T07:52:52.533Z | auto\n\nVersion 1.3.8 of polymarket-copytrading\n\n- Documentation updates to SKILL.md only; no code changes.\n- No new features, bug fixes, or interface changes.\n\nv1.3.7 | 2026-02-17T06:35:56.929Z | auto\n\n- Added WALLET_PRIVATE_KEY as a required environment variable in metadata.\n- Updated troubleshooting section to cover external wallet signing and WALLET_PRIVATE_KEY usage.\n- Bumped version to 1.3.7.\n\nv1.3.6 | 2026-02-17T04:03:21.729Z | auto\n\n- Added simmer-sdk to required pip dependencies in metadata\n- Updated version to 1.3.6\n- Clarified that this skill is a template for customization with your own strategies\n- No changes to core logic or user-facing commands\n\nv1.3.5 | 2026-02-14T13:47:59.996Z | auto\n\n- Expanded documentation in SKILL.md with comprehensive setup, usage, troubleshooting, and API references.\n- Clarified commands for checking wallet positions, following multiple traders, and configuring allocation limits.\n- Added explanations of aggregation logic, Top-N filters, conflict handling, and portfolio rebalancing modes.\n- Included sample user conversations and expected output formats for easier onboarding.\n- Provided guidance for finding top traders and recommended best practices for safe copytrading.\n\nArchive index:\n\nArchive v1.12.4: 10 files, 35930 bytes\n\nFiles: clawhub.json (1951b), copytrading_trader.py (54603b), DISCLAIMER.md (1925b), requirements.txt (33b), scripts/status.py (5272b), skill-card.md (2965b), SKILL.md (22233b), tests/__init__.py (0b), tests/test_venue_routing.py (14531b), _meta.json (142b)\n\nFile v1.12.4:SKILL.md\n\n---\nname: polymarket-copytrading\ndescription: 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.\nmetadata:\n  author: Simmer (@simmer_markets)\n  version: \"1.12.4\"\n  displayName: Polymarket Copytrading\n  difficulty: beginner\n---\n# Polymarket Copytrading\n\nMirror positions from successful Polymarket traders using the Simmer SDK. Two modes share the same skill, use whichever fits your strategy.\n\n> 🚨 **Framework, not a production trading system.** Read [DISCLAIMER.md](./DISCLAIMER.md) before connecting to a wallet with real funds. Per-position cap defaults to $50; per-run cap defaults to 10 trades. Use `$SIM` paper-mode to validate any new whale selection before scaling to real USDC.\n\n> **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.\n\n| | **Polling mode** (free) | **Reactor mode** (Pro) |\n|---|---|---|\n| Entrypoint | `copytrading_trader.py` | `copytrading_trader.py --reactor` |\n| Cadence | Batch scan, runs on cron or manual | Polls every 2s for pre-resolved whale signals |\n| Latency | Minutes (Polymarket Data API polling) | Seconds (Simmer detects events in real-time, pre-confirmation) |\n| 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 |\n| Best for | Portfolio-aware, multi-whale, periodic scans | Real-time reaction to specific whales as they trade |\n| Requires | `SIMMER_API_KEY` | `SIMMER_API_KEY` + Simmer Pro plan |\n\n## Setup Flow\n\nWhen user asks to install or configure this skill:\n\n1. **Install the Simmer SDK** (version 0.9.19 or newer — reactor mode requires it)\n   ```bash\n   pip install -U 'simmer-sdk>=0.9.19'\n   ```\n\n2. **Ask for Simmer API key**\n   - They can get it from simmer.markets/dashboard → SDK tab\n   - Store in environment as `SIMMER_API_KEY`\n\n3. **Ask for wallet private key** (required for live trading on Polymarket)\n   - This is the private key for their Polymarket wallet (the wallet that holds USDC)\n   - Store in environment as `WALLET_PRIVATE_KEY`\n   - The SDK uses this to sign orders client-side automatically — no manual signing needed\n   - Not needed for $SIM paper trading\n\n4. **Ask about settings** (or confirm defaults)\n   - Target wallets: Whale addresses to copy\n   - Max per position: Amount per trade (default $50)\n   - Top N positions: How many positions to track (auto-calculated from balance)\n   - Max trades per run: Safety cap (default 10)\n\n## When to Use This Skill\n\nUse this skill when the user wants to:\n- Copytrade whale wallets on Polymarket\n- Paper trade (copytrade with $SIM) to test strategies without real money\n- Check what positions a wallet holds\n- Follow specific trader addresses\n- Check their copytrading positions\n\n## Quick Commands\n\n```bash\n# Check account balance and positions\npython scripts/status.py\n\n# Detailed position list\npython scripts/status.py --positions\n```\n\n**API Reference:**\n- Base URL: `https://api.simmer.markets`\n- Auth: `Authorization: Bearer $SIMMER_API_KEY`\n- Portfolio: `GET /api/sdk/portfolio`\n- Positions: `GET /api/sdk/positions`\n\n## Finding Whale Wallets\n\n- **[predicting.top](https://predicting.top)** — Leaderboard of top Polymarket traders with wallet addresses\n- **[alphawhale.trade](https://alphawhale.trade)** — Tools for copying and tracking top performers\n- **Polymarket Leaderboard** — Official rankings (requires account)\n\n## Quick Start (Ad-Hoc Usage)\n\n**User provides wallet(s) directly in chat:**\n```\nUser: \"Copytrade this wallet: 0x1234...abcd\"\nUser: \"What positions does 0x5678...efgh have?\"\nUser: \"Follow these whales: 0xaaa..., 0xbbb...\"\n```\n\n→ Run with `--wallets` flag:\n```bash\npython copytrading_trader.py --wallets 0x1234...abcd\npython copytrading_trader.py --wallets 0xaaa...,0xbbb... --dry-run\n```\n\nThis is the simplest way - no setup needed, just pass wallets directly.\n\n## Persistent Setup (Optional)\n\nFor automated recurring scans, wallets can be saved in environment:\n\n| Setting | Environment Variable | Default |\n|---------|---------------------|---------|\n| Target wallets | `SIMMER_COPYTRADING_WALLETS` | (none) |\n| Top N positions | `SIMMER_COPYTRADING_TOP_N` | auto |\n| Max per position | `SIMMER_COPYTRADING_MAX_USD` | 50 |\n| Max trades/run | `SIMMER_COPYTRADING_MAX_TRADES` | 10 |\n| Order type | `SIMMER_COPYTRADING_ORDER_TYPE` | GTC |\n| Cadence mode | `COPYTRADING_CADENCE_MODE` | `polling` |\n| Force Simmer venue | `COPYTRADING_FORCE_SIMMER_VENUE` | (unset) |\n\n### Cadence mode (v1.11+)\n\n`COPYTRADING_CADENCE_MODE` controls how many trades the skill attempts per polling run. Choose based on how frequently your setup runs:\n\n| Preset | Max trades/run | When to use |\n|--------|---------------|-------------|\n| `polling` | 10 | **Default.** Original polling-mode behavior — unchanged for existing installs |\n| `balanced` | 50 | More active polling, want a higher per-run budget |\n| `aggressive` | 200 | High-frequency polling setups |\n\n```bash\nexport COPYTRADING_CADENCE_MODE=balanced\n```\n\nExisting installs default to `polling` — **no behavior change** unless you explicitly set this variable.\n\n> **Reactor mode note:** `cadence_mode` controls polling-mode trade budget only. In Reactor mode, each whale signal is handled individually by `_process_reactor_signal` — the per-run cap doesn't apply. If you hit `Daily trade limit reached (10/day)` in Reactor mode, raise the server-side limit via:\n> ```bash\n> curl -X PATCH \"https://api.simmer.markets/api/sdk/user/settings\" \\\n>   -H \"Authorization: Bearer $SIMMER_API_KEY\" \\\n>   -H \"Content-Type: application/json\" \\\n>   -d '{\"max_trades_per_day\": 200}'\n> ```\n\n> **Position cap:** The per-market position cap is controlled by `SIMMER_COPYTRADING_MAX_USD` (default 50). Raise it to allow larger positions per market.\n\n**Top N auto-calculation (when not specified):**\n- Balance < $50: Top 5 positions\n- Balance $50-200: Top 10 positions\n- Balance $200-500: Top 25 positions\n- Balance $500+: Top 50 positions\n\n**Polymarket Constraints:**\n- Minimum 5 shares per order\n- SDK enforces $1.00 minimum position value (filters dust positions)\n\n> ⚠️ **Start Conservative:** Begin with small amounts (`--max-usd 5-10`) and `--dry-run` to understand how the skill behaves before scaling up.\n\n## How It Works\n\n> **By default, only buys execute.** Pass `--rebalance` to also sell positions the whales have exited, or `--whale-exits` to sell only on whale exits.\n\nEach cycle the script:\n1. Fetches positions from all target wallets via Simmer API\n2. Combines using size-weighted aggregation (larger wallets = more influence)\n3. Detects conflicts (one wallet long YES, another long NO) and skips those markets\n4. Scores by conviction: positions held by 2+ wallets get full sizing, single-wallet positions get 50% sizing\n5. Filters out drifted (>30% from entry) and stale (>90% or <10% price) positions\n6. Applies Top-N filtering to concentrate on highest-conviction positions\n7. Auto-imports missing markets from Polymarket\n8. Calculates rebalance trades to match target allocations\n9. Executes trades via Simmer SDK (respects spending limits)\n10. Reports results back to user\n\n## Reactor Mode (Pro) — event-driven real-time mirroring\n\n> **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.\n\nReactor 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.\n\n### How it's different from polling mode\n\n- **Event-driven, not batched.** Each whale settlement is evaluated and acted on independently.\n- **Fixed per-event sizing.** `mirror_fraction` × whale size, capped at `max_size`. No conviction tiering, no rebalance math.\n- **Server-side watchlist filter.** Your watchlist + `min_size` are stored in Simmer's reactor config and applied on the server before events reach your skill — you only see matches.\n- **Pre-resolved signals.** The server resolves Polymarket condition IDs to Simmer market UUIDs before writing the signal — the skill receives trade-ready payloads.\n- **Mirrors maker AND taker fills (v1.12.1+).** The reactor copies a whale's trade whether they took liquidity (market order) or posted it (a resting limit order). Earlier versions only saw market-order fills, so feeds for whales who mostly post limit orders were quiet — those pick up on v1.12.1+. Your `mirror_fraction` / `max_size` / `daily_cap` still bound exposure, so more complete copying never exceeds your configured caps.\n- **Two run modes.** Loop mode (default, polls every 2s) or `--once` for cron-style single poll and exit.\n- **Circuit breaker.** 5 consecutive trade failures → signals are skipped until the next success. Prevents runaway failures from draining your wallet.\n- **Server-side dedup.** Signals have a 60-second TTL in Redis and are deleted after successful execution. No local state files needed.\n- **Buys only (MVP).** Reactor currently mirrors whale **buys only** — sell signals are filtered out server-side by the relay. If a whale exits a position, reactor won't mirror the sell. Sell mirroring is planned for a future release.\n\n### Configure your reactor watchlist\n\nReactor uses Simmer-side config (not env vars), so dashboard edits take effect in seconds without restarting the skill.\n\n```bash\n# Set your watchlist via the Simmer API\ncurl -X PATCH \"https://api.simmer.markets/api/sdk/reactor/config\" \\\n  -H \"Authorization: Bearer $SIMMER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"wallets\": [\"0x1234...abcd\", \"0x5678...efgh\"],\n    \"min_size\": 1000,\n    \"max_size\": 50,\n    \"mirror_fraction\": 0.01,\n    \"daily_cap\": 100,\n    \"venue\": \"sim\",\n    \"enabled\": true\n  }'\n```\n\nFields:\n\n| Field | Meaning |\n|---|---|\n| `wallets` | Whale addresses to follow (EVM format, lowercased server-side) |\n| `min_size` | Minimum whale trade size to consider (shares) |\n| `max_size` | Cap on your mirror trade size (shares) |\n| `mirror_fraction` | Fraction of whale size to mirror (e.g. 0.01 = 1%) |\n| `daily_cap` | Max total spend per day in venue-native units. Enforced by this skill at execution time. The server additionally stops proposing new signals once a day's proposed total exceeds 3x this value (runaway guard) — capped feeds show `skipped_daily_cap` entries in reactor status rather than going silent. |\n| `venue` | `sim` / `polymarket` / `kalshi` |\n| `enabled` | Pause reactor by setting `false` — server will stop delivering events |\n| `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. |\n\n### Run reactor mode\n\n**Recommended: cron with `--once`** — polls for pending signals once and exits. Run on a 1-minute cron for reliable, persistent coverage:\n\n```bash\n# Linux crontab\n*/1 * * * * cd /path/to/skill && python copytrading_trader.py --reactor --once --live\n\n# OpenClaw cron\nopenclaw cron add --name \"reactor-poll\" --cron \"*/1 * * * *\" --tz UTC --session isolated \\\n  --message \"Run: cd /path/to/skill && python3 copytrading_trader.py --reactor --once\"\n\n# One-off check\npython copytrading_trader.py --reactor --once\n```\n\n> **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.\n\n**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.\n\n```bash\n# With a process manager (launchd, systemd, supervisor)\npython copytrading_trader.py --reactor\n\n# Plain shell (will not auto-restart)\nnohup python copytrading_trader.py --reactor > reactor.log 2>&1 &\n```\n\nSet `REACTOR_POLL_INTERVAL_SECONDS` to tune the polling cadence (default 2s).\n\n> **Note:** Reactor mode always executes live trades (venue is set in your reactor config). Use `venue: \"sim\"` in your config to paper trade.\n\n### What happens per signal\n\n1. Skill polls `GET /api/sdk/reactor/pending` for pre-resolved whale signals\n2. Circuit breaker check: if 5+ consecutive failures in recent reactions, skip this tick\n3. For each signal: compute mirror size (`taker_size × mirror_fraction`, capped by `max_size`, floored at 5-share Polymarket minimum)\n4. If below minimum → `skipped_filter` reaction, no trade\n5. `SimmerClient.trade()` with `skill_slug=\"polymarket-copytrading\"` and `source=\"sdk:copytrading:reactor\"`\n6. On success: DELETE the signal from `/api/sdk/reactor/pending/{tx_hash}` and POST a `mirrored` reaction\n7. On failure: POST a `failed` reaction, leave signal (60s TTL clears it)\n\n### Example output\n\n```\n[reactor] price_buffer=0.020 (from config)\n[reactor] --once: single poll against /api/sdk/reactor/pending\n[reactor] 0 pending signals\n```\n\nWhen a whale trade matches your watchlist:\n\n```\n[reactor] price_buffer=0.020 (from config)\n[reactor] loop mode: polling /api/sdk/reactor/pending every 2.0s\n[reactor] 1 pending signal(s)\n[reactor] 0xbaa2bc... BUY 7067 shares on \"Will Iran strike Iraq by April 30, 2026?\"\n[reactor] mirror: 70.67 shares @ $0.673 (buffer +2.0%) → GTC order placed\n[reactor] ✅ mirrored — trade_id=a23dc52a, signal deleted\n```\n\n### Reactor venue auto-routing (v1.11+)\n\nWhen Reactor signals arrive sized above Simmer's 500 $SIM per-trade cap, the skill automatically routes them to Polymarket instead of failing silently. This lets you follow whale sizing without hitting the LMSR hard cap:\n\n```\n[reactor] 0xbaa2bc... amount 800.00 $SIM > 500 $SIM cap → routing to polymarket\n[reactor] ✅ 0xbaa2bc... mirrored 800.00 USD trade_id=a23dc52a\n```\n\n**Edge cases:**\n- **No Polymarket wallet configured**: skill falls back to a 500 $SIM-capped trade and logs the routing decision. You won't miss the signal entirely.\n- **`COPYTRADING_FORCE_SIMMER_VENUE=true`**: disables auto-routing. Signals above 500 $SIM are capped at 500 and traded on Simmer venue.\n- **Signal already targets Polymarket**: no change — auto-routing only fires on `sim` venue signals.\n\n### External wallets just work\n\nReactor 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.\n\n### When to use polling vs reactor\n\n- **Use polling** when you want portfolio-style copying: aggregate across multiple whales, rebalance to target allocations, run periodically from cron, filter drifted/stale positions. Doesn't require Pro.\n- **Use reactor** when you want real-time reaction to individual whale trades, fixed per-event sizing, and pre-resolved signals. Requires Pro.\n- **Use both** if you want: polling for your steady-state portfolio alignment + reactor for opportunistic real-time mirroring. Different flags, same skill, same API key.\n\n---\n\n## $SIM Paper Trading\n\nCopytrading supports $SIM mode — mirror whale positions using simulated money on Simmer's LMSR markets. No wallet or USDC required.\n\n```bash\n# Paper trade with $SIM (explicit)\npython copytrading_trader.py --venue sim --wallets 0x123... --live\n\n# Auto-detect: if your account has no linked wallet, $SIM is used automatically\npython copytrading_trader.py --wallets 0x123... --live\n```\n\nIn $SIM mode:\n- Trades execute on Simmer's LMSR at real Polymarket prices\n- Each market gets an independent $10K $SIM balance\n- Positions tracked in your Simmer portfolio (source: `sdk:copytrading`)\n- Whale signals still come from real Polymarket data\n\n## Running the Skill\n\n**Run a scan (dry run by default — no trades):**\n```bash\npython copytrading_trader.py\n```\n\n**Execute real trades:**\n```bash\npython copytrading_trader.py --live\n```\n\n**Check positions only:**\n```bash\npython copytrading_trader.py --positions\n```\n\n**View current config:**\n```bash\npython copytrading_trader.py --config\n```\n\n**Override wallets for one run:**\n```bash\npython copytrading_trader.py --wallets 0x123...,0x456...\n```\n\n**Full rebalance mode (includes sells):**\n```bash\npython copytrading_trader.py --rebalance\n```\n\n**Sell when whales exit positions:**\n```bash\npython copytrading_trader.py --whale-exits\n```\n\n## Reporting Results\n\nAfter each run, message the user with:\n- Current configuration (wallets, Top N, max position)\n- Number of wallets fetched and total positions found\n- Markets skipped due to conflicts\n- Trades executed (or skipped with reason)\n- Current portfolio positions\n\nExample output to share:\n```\n🐋 Copytrading Scan Complete\n\nConfiguration:\n• Following 2 wallets\n• Top 10 positions, max $50 each\n• Balance: $250.00 USDC\n\nFetched positions:\n• 0x1234...abcd: 15 positions\n• 0x5678...efgh: 22 positions\n• Combined: 28 unique markets\n• Conflicts skipped: 2\n\nTop 10 by allocation:\n1. \"Will BTC hit $100k?\" - 18.5% → BUY YES\n2. \"Trump pardons X?\" - 12.3% → BUY NO\n3. \"Fed rate cut Jan?\" - 9.8% → Already held\n...\n\nTrades executed: 4 buys ($180 total)\n• Bought 45 YES shares on \"Will BTC hit $100k?\" @ $0.82\n• Bought 120 NO shares on \"Trump pardons X?\" @ $0.15\n...\n\nNext scan in 4 hours.\n```\n\n## Example Conversations\n\n**User: \"Copytrade 0x1234...abcd\"**\n→ Run: `python copytrading_trader.py --wallets 0x1234...abcd`\n→ Report what positions that wallet has and what trades would execute\n\n**User: \"What is 0x5678...efgh holding?\"**\n→ Run: `python copytrading_trader.py --wallets 0x5678...efgh --dry-run`\n→ Show their positions without trading\n\n**User: \"Follow these wallets: 0xaaa..., 0xbbb..., 0xccc...\"**\n→ Run: `python copytrading_trader.py --wallets 0xaaa...,0xbbb...,0xccc...`\n→ Aggregate positions across all wallets, report results\n\n**User: \"Copytrade this whale but only top 5 positions\"**\n→ Run: `python copytrading_trader.py --wallets 0x... --top-n 5`\n\n**User: \"How are my positions doing?\"**\n→ Run: `python copytrading_trader.py --positions`\n→ Show current Polymarket positions with P&L\n\n**User: \"Show copytrading config\"**\n→ Run: `python copytrading_trader.py --config`\n→ Display current settings\n\n**User: \"Sell positions that whales have exited\"**\n→ Run: `python copytrading_trader.py --whale-exits`\n→ Compares your positions to whales, sells any they've closed\n\n**User: \"Do a full rebalance to match the whales\"**\n→ Run: `python copytrading_trader.py --rebalance`\n→ Includes both buys AND sells to match whale allocations\n\n## Finding Good Wallets to Follow\n\nCommon approaches:\n1. **Leaderboard tracking**: Check Polymarket leaderboards for consistent performers\n2. **Whale watchers**: Follow known profitable traders on social media\n3. **Specific strategies**: Follow wallets known for weather, politics, or crypto trades\n\nThe skill works best when:\n- Following 2-5 wallets with **overlapping strategies** (e.g. all politics-focused, or all crypto-focused)\n- Wallets have similar conviction — mixing very different traders means most positions only appear in one wallet and get reduced sizing (50%)\n- Wallets trade markets available on Polymarket\n\n### Conviction Tiers\n\nWhen following multiple wallets, positions are scored by conviction:\n\n- **High conviction** (held by 2+ wallets): full position sizing (`max_usd`)\n- **Low conviction** (held by 1 wallet): 50% position sizing\n\nHigh-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).\n\n## Troubleshooting\n\n**\"Order too small\" / \"below minimum (5)\"**\n- Polymarket requires minimum 5 shares per order\n- Increase `--max-usd` or reduce `--top-n` to concentrate into fewer positions\n\n**\"No wallets specified\"**\n- Provide wallet addresses in your message, e.g., \"copytrade 0x1234...\"\n- Or set SIMMER_COPYTRADING_WALLETS environment variable for recurring scans\n\n**\"Agent has no USDC balance\"**\n- Need USDC in your Polymarket wallet, or use `--venue sim` for $SIM paper trading\n- Check wallet is linked at simmer.markets/dashboard\n\n**\"Conflict skipped\"**\n- Wallets disagree on this market (one long YES, other long NO)\n- Markets with net position < 10% are skipped\n\n**\"All N positions filtered (X conflicts, Y drifted, Z stale)\"**\n- All whale positions were removed by safety filters\n- Try different target wallets, or reduce to 1 wallet to disable conviction scoring\n- Drift filter skips positions where price moved >30% from whale's entry\n- Stale filter skips near-resolved markets (price >90% or <10%)\n\n**\"Insufficient balance\"**\n- Not enough USDC for all trades\n- Reduce SIMMER_COPYTRADING_TOP_N or SIMMER_COPYTRADING_MAX_USD\n\n**\"Market could not be imported\"**\n- Some markets may not be importable (resolved, private, etc.)\n- These are skipped automatically\n\n**\"External wallet requires a pre-signed order\"**\n- `WALLET_PRIVATE_KEY` is not set in the environment\n- The SDK signs orders automatically when this env var is present — no manual signing code needed\n- Fix: `export WALLET_PRIVATE_KEY=0x<your-polymarket-wallet-private-key>`\n- Do NOT attempt to sign orders manually or modify the skill code — the SDK handles it\n\n**\"Balance shows $0 but I have funds on Polygon\"**\n- Polymarket V2 (live 2026-04-28) uses **pUSD** (PolyUSD, 1:1 backed by USDC.e). If your wallet holds USDC.e, migrate at [simmer.markets/dashboard](https://simmer.markets/dashboard?ref=sdk-skill&utm_campaign=sdk-skill) with one click (~30s)\n- If you bridged native USDC (Circle), swap to USDC.e first, then migrate to pUSD\n- Full migration guide: [docs.simmer.markets/v2-migration](https://docs.simmer.markets/v2-migration)\n\nFile v1.12.4:_meta.json\n\n{\n  \"ownerId\": \"kn7axnp7bzqsf5fkx0z8px7han7zyq1x\",\n  \"slug\": \"polymarket-copytrading\",\n  \"version\": \"1.12.4\",\n  \"publishedAt\": 1790133045894\n}\n\nFile v1.12.4:DISCLAIMER.md\n\n# Disclaimer\n\nThis skill is a **framework**, not a production trading system. Read this\nin full before connecting it to a wallet with real funds.\n\n## No financial advice\n\nNothing in this skill constitutes financial, investment, or trading\nadvice. The default strategy implemented here is a starting point, not a\ntested edge. Suitability for any account size or risk tolerance is your\nresponsibility to assess.\n\n## Default parameters are not validated\n\nDefault parameters are calibrated for testing the plumbing, not for live\nprofit. They have not been validated to produce positive returns under\ncurrent market conditions. Run paper mode for an extended period before\nscaling beyond default position sizes.\n\n## Automated trading carries irreversible risk\n\nWhen this skill runs with `--live`, it places real on-chain orders.\nOn-chain trades cannot be recalled. Strategy errors, signal lag, market\nregime shifts, and operator misconfiguration can produce losses\nexceeding any specific position size.\n\n## Risk monitoring may not apply to all market types\n\nStop-loss and take-profit monitors run on a fixed schedule. Markets that\nresolve faster than the monitor cycle cannot be exited automatically.\nPosition sizing is the only risk control on these markets — set it\nconservatively.\n\n## Use of this skill is at your own risk\n\nBy installing and running this skill you agree that the authors are not\nliable for any losses, direct or indirect, that arise from its use. This\napplies regardless of skill provenance — official Simmer skills,\ncommunity skills, and skills imported from external repositories all\ncarry this same disclaimer.\n\n## Where to learn more before going live\n\n- The skill's own `SKILL.md` documents the strategy and parameters\n- Your trading venue's documentation covers fee structure, order types,\n  and resolution rules\n- Simmer SDK documentation covers paper mode, dry-run flags, and\n  position monitoring\n\nFile v1.12.4:skill-card.md\n\n## Description:\n\nMirror 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.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[simmer](https://clawhub.ai/user/simmer)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and agents use this skill to inspect Polymarket trader positions, configure whale wallets to follow, run dry-run or paper copytrading checks, and optionally execute live mirrored trades with configured caps.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can place real-money trades when live mode and credentials are configured.\n\nMitigation: Use dry-run or $SIM paper mode first, keep per-position and per-run caps small, and review proposed trades before scaling to real USDC.\n\nRisk: Automatic venue routing can convert above-cap simulated Reactor signals to Polymarket orders.\n\nMitigation: Set COPYTRADING_FORCE_SIMMER_VENUE=true when simulated-only execution is required.\n\nRisk: Unattended live runs can continue acting on new whale signals without active review.\n\nMitigation: Avoid cron, loop, or nohup live execution until behavior, wallet setup, and caps have been reviewed.\n\nRisk: External-wallet trading depends on WALLET_PRIVATE_KEY, which is highly sensitive.\n\nMitigation: Store the private key only in a protected environment and avoid exposing it in logs, prompts, shell history, or shared configuration.\n\nRisk: Sell behavior and rebalance options can close positions as well as buy mirrored positions.\n\nMitigation: Review sell-related flags and defaults before live use, and confirm whether buy-only, whale-exit, or full-rebalance behavior is intended.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/simmer/skills/polymarket-copytrading)\n- [Simmer API](https://api.simmer.markets)\n- [Simmer dashboard](https://simmer.markets/dashboard)\n- [Simmer V2 migration guide](https://docs.simmer.markets/v2-migration)\n- [predicting.top](https://predicting.top)\n- [alphawhale.trade](https://alphawhale.trade)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown and terminal-oriented status summaries with inline shell commands and configuration values]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May run dry-run, paper, or live trading commands depending on user configuration; live trading requires Simmer credentials and, for external wallets, a wallet private key.]\n\n## Skill Version(s):\n\n1.12.4 (source: frontmatter and release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.12.4:clawhub.json\n\n{\n  \"emoji\": \"\\ud83d\\udc0b\",\n  \"primaryEnv\": \"SIMMER_API_KEY\",\n  \"requires\": {\n    \"env\": [\n      \"SIMMER_API_KEY\"\n    ],\n    \"pip\": [\n      \"simmer-sdk>=0.11.1\"\n    ]\n  },\n  \"envVars\": [\n    {\n      \"name\": \"SIMMER_API_KEY\",\n      \"required\": true,\n      \"description\": \"Your Simmer SDK API key \\u2014 get from simmer.markets/dashboard\"\n    },\n    {\n      \"name\": \"WALLET_PRIVATE_KEY\",\n      \"required\": false,\n      \"description\": \"Only needed for external-wallet self-custody trading. Not required when using managed wallets.\"\n    }\n  ],\n  \"cron\": null,\n  \"autostart\": false,\n  \"automaton\": {\n    \"managed\": true,\n    \"entrypoint\": \"copytrading_trader.py\"\n  },\n  \"tunables\": [\n    {\n      \"env\": \"SIMMER_COPYTRADING_WALLETS\",\n      \"type\": \"string\",\n      \"default\": \"\",\n      \"label\": \"Whale wallet addresses (comma-separated)\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_MAX_USD\",\n      \"type\": \"number\",\n      \"default\": 50,\n      \"range\": [\n        1,\n        200\n      ],\n      \"step\": 5,\n      \"label\": \"Max bet per trade\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_TOP_N\",\n      \"type\": \"number\",\n      \"default\": 5,\n      \"range\": [\n        1,\n        20\n      ],\n      \"step\": 1,\n      \"label\": \"Positions to track\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_MAX_TRADES\",\n      \"type\": \"number\",\n      \"default\": 5,\n      \"range\": [\n        1,\n        20\n      ],\n      \"step\": 1,\n      \"label\": \"Max trades per run\"\n    },\n    {\n      \"env\": \"COPYTRADING_CADENCE_MODE\",\n      \"type\": \"string\",\n      \"default\": \"polling\",\n      \"enum\": [\"polling\", \"balanced\", \"aggressive\"],\n      \"label\": \"Cadence mode — set higher for more active polling (polling=10 trades/run, balanced=50, aggressive=200)\"\n    },\n    {\n      \"env\": \"COPYTRADING_FORCE_SIMMER_VENUE\",\n      \"type\": \"string\",\n      \"default\": \"\",\n      \"label\": \"Force Simmer ($SIM) venue — set to 'true' to disable auto-routing above-cap trades to Polymarket\"\n    }\n  ]\n}\n\nFile v1.12.4:requirements.txt\n\nsimmer-sdk>=0.11.1\npackaging>=20\n\nArchive v1.12.3: 10 files, 35346 bytes\n\nFiles: clawhub.json (1951b), copytrading_trader.py (53265b), DISCLAIMER.md (1925b), requirements.txt (33b), scripts/status.py (5272b), skill-card.md (2777b), SKILL.md (22233b), tests/__init__.py (0b), tests/test_venue_routing.py (14531b), _meta.json (142b)\n\nFile v1.12.3:SKILL.md\n\n---\nname: polymarket-copytrading\ndescription: 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.\nmetadata:\n  author: Simmer (@simmer_markets)\n  version: \"1.12.3\"\n  displayName: Polymarket Copytrading\n  difficulty: beginner\n---\n# Polymarket Copytrading\n\nMirror positions from successful Polymarket traders using the Simmer SDK. Two modes share the same skill, use whichever fits your strategy.\n\n> 🚨 **Framework, not a production trading system.** Read [DISCLAIMER.md](./DISCLAIMER.md) before connecting to a wallet with real funds. Per-position cap defaults to $50; per-run cap defaults to 10 trades. Use `$SIM` paper-mode to validate any new whale selection before scaling to real USDC.\n\n> **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.\n\n| | **Polling mode** (free) | **Reactor mode** (Pro) |\n|---|---|---|\n| Entrypoint | `copytrading_trader.py` | `copytrading_trader.py --reactor` |\n| Cadence | Batch scan, runs on cron or manual | Polls every 2s for pre-resolved whale signals |\n| Latency | Minutes (Polymarket Data API polling) | Seconds (Simmer detects events in real-time, pre-confirmation) |\n| 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 |\n| Best for | Portfolio-aware, multi-whale, periodic scans | Real-time reaction to specific whales as they trade |\n| Requires | `SIMMER_API_KEY` | `SIMMER_API_KEY` + Simmer Pro plan |\n\n## Setup Flow\n\nWhen user asks to install or configure this skill:\n\n1. **Install the Simmer SDK** (version 0.9.19 or newer — reactor mode requires it)\n   ```bash\n   pip install -U 'simmer-sdk>=0.9.19'\n   ```\n\n2. **Ask for Simmer API key**\n   - They can get it from simmer.markets/dashboard → SDK tab\n   - Store in environment as `SIMMER_API_KEY`\n\n3. **Ask for wallet private key** (required for live trading on Polymarket)\n   - This is the private key for their Polymarket wallet (the wallet that holds USDC)\n   - Store in environment as `WALLET_PRIVATE_KEY`\n   - The SDK uses this to sign orders client-side automatically — no manual signing needed\n   - Not needed for $SIM paper trading\n\n4. **Ask about settings** (or confirm defaults)\n   - Target wallets: Whale addresses to copy\n   - Max per position: Amount per trade (default $50)\n   - Top N positions: How many positions to track (auto-calculated from balance)\n   - Max trades per run: Safety cap (default 10)\n\n## When to Use This Skill\n\nUse this skill when the user wants to:\n- Copytrade whale wallets on Polymarket\n- Paper trade (copytrade with $SIM) to test strategies without real money\n- Check what positions a wallet holds\n- Follow specific trader addresses\n- Check their copytrading positions\n\n## Quick Commands\n\n```bash\n# Check account balance and positions\npython scripts/status.py\n\n# Detailed position list\npython scripts/status.py --positions\n```\n\n**API Reference:**\n- Base URL: `https://api.simmer.markets`\n- Auth: `Authorization: Bearer $SIMMER_API_KEY`\n- Portfolio: `GET /api/sdk/portfolio`\n- Positions: `GET /api/sdk/positions`\n\n## Finding Whale Wallets\n\n- **[predicting.top](https://predicting.top)** — Leaderboard of top Polymarket traders with wallet addresses\n- **[alphawhale.trade](https://alphawhale.trade)** — Tools for copying and tracking top performers\n- **Polymarket Leaderboard** — Official rankings (requires account)\n\n## Quick Start (Ad-Hoc Usage)\n\n**User provides wallet(s) directly in chat:**\n```\nUser: \"Copytrade this wallet: 0x1234...abcd\"\nUser: \"What positions does 0x5678...efgh have?\"\nUser: \"Follow these whales: 0xaaa..., 0xbbb...\"\n```\n\n→ Run with `--wallets` flag:\n```bash\npython copytrading_trader.py --wallets 0x1234...abcd\npython copytrading_trader.py --wallets 0xaaa...,0xbbb... --dry-run\n```\n\nThis is the simplest way - no setup needed, just pass wallets directly.\n\n## Persistent Setup (Optional)\n\nFor automated recurring scans, wallets can be saved in environment:\n\n| Setting | Environment Variable | Default |\n|---------|---------------------|---------|\n| Target wallets | `SIMMER_COPYTRADING_WALLETS` | (none) |\n| Top N positions | `SIMMER_COPYTRADING_TOP_N` | auto |\n| Max per position | `SIMMER_COPYTRADING_MAX_USD` | 50 |\n| Max trades/run | `SIMMER_COPYTRADING_MAX_TRADES` | 10 |\n| Order type | `SIMMER_COPYTRADING_ORDER_TYPE` | GTC |\n| Cadence mode | `COPYTRADING_CADENCE_MODE` | `polling` |\n| Force Simmer venue | `COPYTRADING_FORCE_SIMMER_VENUE` | (unset) |\n\n### Cadence mode (v1.11+)\n\n`COPYTRADING_CADENCE_MODE` controls how many trades the skill attempts per polling run. Choose based on how frequently your setup runs:\n\n| Preset | Max trades/run | When to use |\n|--------|---------------|-------------|\n| `polling` | 10 | **Default.** Original polling-mode behavior — unchanged for existing installs |\n| `balanced` | 50 | More active polling, want a higher per-run budget |\n| `aggressive` | 200 | High-frequency polling setups |\n\n```bash\nexport COPYTRADING_CADENCE_MODE=balanced\n```\n\nExisting installs default to `polling` — **no behavior change** unless you explicitly set this variable.\n\n> **Reactor mode note:** `cadence_mode` controls polling-mode trade budget only. In Reactor mode, each whale signal is handled individually by `_process_reactor_signal` — the per-run cap doesn't apply. If you hit `Daily trade limit reached (10/day)` in Reactor mode, raise the server-side limit via:\n> ```bash\n> curl -X PATCH \"https://api.simmer.markets/api/sdk/user/settings\" \\\n>   -H \"Authorization: Bearer $SIMMER_API_KEY\" \\\n>   -H \"Content-Type: application/json\" \\\n>   -d '{\"max_trades_per_day\": 200}'\n> ```\n\n> **Position cap:** The per-market position cap is controlled by `SIMMER_COPYTRADING_MAX_USD` (default 50). Raise it to allow larger positions per market.\n\n**Top N auto-calculation (when not specified):**\n- Balance < $50: Top 5 positions\n- Balance $50-200: Top 10 positions\n- Balance $200-500: Top 25 positions\n- Balance $500+: Top 50 positions\n\n**Polymarket Constraints:**\n- Minimum 5 shares per order\n- SDK enforces $1.00 minimum position value (filters dust positions)\n\n> ⚠️ **Start Conservative:** Begin with small amounts (`--max-usd 5-10`) and `--dry-run` to understand how the skill behaves before scaling up.\n\n## How It Works\n\n> **By default, only buys execute.** Pass `--rebalance` to also sell positions the whales have exited, or `--whale-exits` to sell only on whale exits.\n\nEach cycle the script:\n1. Fetches positions from all target wallets via Simmer API\n2. Combines using size-weighted aggregation (larger wallets = more influence)\n3. Detects conflicts (one wallet long YES, another long NO) and skips those markets\n4. Scores by conviction: positions held by 2+ wallets get full sizing, single-wallet positions get 50% sizing\n5. Filters out drifted (>30% from entry) and stale (>90% or <10% price) positions\n6. Applies Top-N filtering to concentrate on highest-conviction positions\n7. Auto-imports missing markets from Polymarket\n8. Calculates rebalance trades to match target allocations\n9. Executes trades via Simmer SDK (respects spending limits)\n10. Reports results back to user\n\n## Reactor Mode (Pro) — event-driven real-time mirroring\n\n> **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.\n\nReactor 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.\n\n### How it's different from polling mode\n\n- **Event-driven, not batched.** Each whale settlement is evaluated and acted on independently.\n- **Fixed per-event sizing.** `mirror_fraction` × whale size, capped at `max_size`. No conviction tiering, no rebalance math.\n- **Server-side watchlist filter.** Your watchlist + `min_size` are stored in Simmer's reactor config and applied on the server before events reach your skill — you only see matches.\n- **Pre-resolved signals.** The server resolves Polymarket condition IDs to Simmer market UUIDs before writing the signal — the skill receives trade-ready payloads.\n- **Mirrors maker AND taker fills (v1.12.1+).** The reactor copies a whale's trade whether they took liquidity (market order) or posted it (a resting limit order). Earlier versions only saw market-order fills, so feeds for whales who mostly post limit orders were quiet — those pick up on v1.12.1+. Your `mirror_fraction` / `max_size` / `daily_cap` still bound exposure, so more complete copying never exceeds your configured caps.\n- **Two run modes.** Loop mode (default, polls every 2s) or `--once` for cron-style single poll and exit.\n- **Circuit breaker.** 5 consecutive trade failures → signals are skipped until the next success. Prevents runaway failures from draining your wallet.\n- **Server-side dedup.** Signals have a 60-second TTL in Redis and are deleted after successful execution. No local state files needed.\n- **Buys only (MVP).** Reactor currently mirrors whale **buys only** — sell signals are filtered out server-side by the relay. If a whale exits a position, reactor won't mirror the sell. Sell mirroring is planned for a future release.\n\n### Configure your reactor watchlist\n\nReactor uses Simmer-side config (not env vars), so dashboard edits take effect in seconds without restarting the skill.\n\n```bash\n# Set your watchlist via the Simmer API\ncurl -X PATCH \"https://api.simmer.markets/api/sdk/reactor/config\" \\\n  -H \"Authorization: Bearer $SIMMER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"wallets\": [\"0x1234...abcd\", \"0x5678...efgh\"],\n    \"min_size\": 1000,\n    \"max_size\": 50,\n    \"mirror_fraction\": 0.01,\n    \"daily_cap\": 100,\n    \"venue\": \"sim\",\n    \"enabled\": true\n  }'\n```\n\nFields:\n\n| Field | Meaning |\n|---|---|\n| `wallets` | Whale addresses to follow (EVM format, lowercased server-side) |\n| `min_size` | Minimum whale trade size to consider (shares) |\n| `max_size` | Cap on your mirror trade size (shares) |\n| `mirror_fraction` | Fraction of whale size to mirror (e.g. 0.01 = 1%) |\n| `daily_cap` | Max total spend per day in venue-native units. Enforced by this skill at execution time. The server additionally stops proposing new signals once a day's proposed total exceeds 3x this value (runaway guard) — capped feeds show `skipped_daily_cap` entries in reactor status rather than going silent. |\n| `venue` | `sim` / `polymarket` / `kalshi` |\n| `enabled` | Pause reactor by setting `false` — server will stop delivering events |\n| `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. |\n\n### Run reactor mode\n\n**Recommended: cron with `--once`** — polls for pending signals once and exits. Run on a 1-minute cron for reliable, persistent coverage:\n\n```bash\n# Linux crontab\n*/1 * * * * cd /path/to/skill && python copytrading_trader.py --reactor --once --live\n\n# OpenClaw cron\nopenclaw cron add --name \"reactor-poll\" --cron \"*/1 * * * *\" --tz UTC --session isolated \\\n  --message \"Run: cd /path/to/skill && python3 copytrading_trader.py --reactor --once\"\n\n# One-off check\npython copytrading_trader.py --reactor --once\n```\n\n> **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.\n\n**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.\n\n```bash\n# With a process manager (launchd, systemd, supervisor)\npython copytrading_trader.py --reactor\n\n# Plain shell (will not auto-restart)\nnohup python copytrading_trader.py --reactor > reactor.log 2>&1 &\n```\n\nSet `REACTOR_POLL_INTERVAL_SECONDS` to tune the polling cadence (default 2s).\n\n> **Note:** Reactor mode always executes live trades (venue is set in your reactor config). Use `venue: \"sim\"` in your config to paper trade.\n\n### What happens per signal\n\n1. Skill polls `GET /api/sdk/reactor/pending` for pre-resolved whale signals\n2. Circuit breaker check: if 5+ consecutive failures in recent reactions, skip this tick\n3. For each signal: compute mirror size (`taker_size × mirror_fraction`, capped by `max_size`, floored at 5-share Polymarket minimum)\n4. If below minimum → `skipped_filter` reaction, no trade\n5. `SimmerClient.trade()` with `skill_slug=\"polymarket-copytrading\"` and `source=\"sdk:copytrading:reactor\"`\n6. On success: DELETE the signal from `/api/sdk/reactor/pending/{tx_hash}` and POST a `mirrored` reaction\n7. On failure: POST a `failed` reaction, leave signal (60s TTL clears it)\n\n### Example output\n\n```\n[reactor] price_buffer=0.020 (from config)\n[reactor] --once: single poll against /api/sdk/reactor/pending\n[reactor] 0 pending signals\n```\n\nWhen a whale trade matches your watchlist:\n\n```\n[reactor] price_buffer=0.020 (from config)\n[reactor] loop mode: polling /api/sdk/reactor/pending every 2.0s\n[reactor] 1 pending signal(s)\n[reactor] 0xbaa2bc... BUY 7067 shares on \"Will Iran strike Iraq by April 30, 2026?\"\n[reactor] mirror: 70.67 shares @ $0.673 (buffer +2.0%) → GTC order placed\n[reactor] ✅ mirrored — trade_id=a23dc52a, signal deleted\n```\n\n### Reactor venue auto-routing (v1.11+)\n\nWhen Reactor signals arrive sized above Simmer's 500 $SIM per-trade cap, the skill automatically routes them to Polymarket instead of failing silently. This lets you follow whale sizing without hitting the LMSR hard cap:\n\n```\n[reactor] 0xbaa2bc... amount 800.00 $SIM > 500 $SIM cap → routing to polymarket\n[reactor] ✅ 0xbaa2bc... mirrored 800.00 USD trade_id=a23dc52a\n```\n\n**Edge cases:**\n- **No Polymarket wallet configured**: skill falls back to a 500 $SIM-capped trade and logs the routing decision. You won't miss the signal entirely.\n- **`COPYTRADING_FORCE_SIMMER_VENUE=true`**: disables auto-routing. Signals above 500 $SIM are capped at 500 and traded on Simmer venue.\n- **Signal already targets Polymarket**: no change — auto-routing only fires on `sim` venue signals.\n\n### External wallets just work\n\nReactor 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.\n\n### When to use polling vs reactor\n\n- **Use polling** when you want portfolio-style copying: aggregate across multiple whales, rebalance to target allocations, run periodically from cron, filter drifted/stale positions. Doesn't require Pro.\n- **Use reactor** when you want real-time reaction to individual whale trades, fixed per-event sizing, and pre-resolved signals. Requires Pro.\n- **Use both** if you want: polling for your steady-state portfolio alignment + reactor for opportunistic real-time mirroring. Different flags, same skill, same API key.\n\n---\n\n## $SIM Paper Trading\n\nCopytrading supports $SIM mode — mirror whale positions using simulated money on Simmer's LMSR markets. No wallet or USDC required.\n\n```bash\n# Paper trade with $SIM (explicit)\npython copytrading_trader.py --venue sim --wallets 0x123... --live\n\n# Auto-detect: if your account has no linked wallet, $SIM is used automatically\npython copytrading_trader.py --wallets 0x123... --live\n```\n\nIn $SIM mode:\n- Trades execute on Simmer's LMSR at real Polymarket prices\n- Each market gets an independent $10K $SIM balance\n- Positions tracked in your Simmer portfolio (source: `sdk:copytrading`)\n- Whale signals still come from real Polymarket data\n\n## Running the Skill\n\n**Run a scan (dry run by default — no trades):**\n```bash\npython copytrading_trader.py\n```\n\n**Execute real trades:**\n```bash\npython copytrading_trader.py --live\n```\n\n**Check positions only:**\n```bash\npython copytrading_trader.py --positions\n```\n\n**View current config:**\n```bash\npython copytrading_trader.py --config\n```\n\n**Override wallets for one run:**\n```bash\npython copytrading_trader.py --wallets 0x123...,0x456...\n```\n\n**Full rebalance mode (includes sells):**\n```bash\npython copytrading_trader.py --rebalance\n```\n\n**Sell when whales exit positions:**\n```bash\npython copytrading_trader.py --whale-exits\n```\n\n## Reporting Results\n\nAfter each run, message the user with:\n- Current configuration (wallets, Top N, max position)\n- Number of wallets fetched and total positions found\n- Markets skipped due to conflicts\n- Trades executed (or skipped with reason)\n- Current portfolio positions\n\nExample output to share:\n```\n🐋 Copytrading Scan Complete\n\nConfiguration:\n• Following 2 wallets\n• Top 10 positions, max $50 each\n• Balance: $250.00 USDC\n\nFetched positions:\n• 0x1234...abcd: 15 positions\n• 0x5678...efgh: 22 positions\n• Combined: 28 unique markets\n• Conflicts skipped: 2\n\nTop 10 by allocation:\n1. \"Will BTC hit $100k?\" - 18.5% → BUY YES\n2. \"Trump pardons X?\" - 12.3% → BUY NO\n3. \"Fed rate cut Jan?\" - 9.8% → Already held\n...\n\nTrades executed: 4 buys ($180 total)\n• Bought 45 YES shares on \"Will BTC hit $100k?\" @ $0.82\n• Bought 120 NO shares on \"Trump pardons X?\" @ $0.15\n...\n\nNext scan in 4 hours.\n```\n\n## Example Conversations\n\n**User: \"Copytrade 0x1234...abcd\"**\n→ Run: `python copytrading_trader.py --wallets 0x1234...abcd`\n→ Report what positions that wallet has and what trades would execute\n\n**User: \"What is 0x5678...efgh holding?\"**\n→ Run: `python copytrading_trader.py --wallets 0x5678...efgh --dry-run`\n→ Show their positions without trading\n\n**User: \"Follow these wallets: 0xaaa..., 0xbbb..., 0xccc...\"**\n→ Run: `python copytrading_trader.py --wallets 0xaaa...,0xbbb...,0xccc...`\n→ Aggregate positions across all wallets, report results\n\n**User: \"Copytrade this whale but only top 5 positions\"**\n→ Run: `python copytrading_trader.py --wallets 0x... --top-n 5`\n\n**User: \"How are my positions doing?\"**\n→ Run: `python copytrading_trader.py --positions`\n→ Show current Polymarket positions with P&L\n\n**User: \"Show copytrading config\"**\n→ Run: `python copytrading_trader.py --config`\n→ Display current settings\n\n**User: \"Sell positions that whales have exited\"**\n→ Run: `python copytrading_trader.py --whale-exits`\n→ Compares your positions to whales, sells any they've closed\n\n**User: \"Do a full rebalance to match the whales\"**\n→ Run: `python copytrading_trader.py --rebalance`\n→ Includes both buys AND sells to match whale allocations\n\n## Finding Good Wallets to Follow\n\nCommon approaches:\n1. **Leaderboard tracking**: Check Polymarket leaderboards for consistent performers\n2. **Whale watchers**: Follow known profitable traders on social media\n3. **Specific strategies**: Follow wallets known for weather, politics, or crypto trades\n\nThe skill works best when:\n- Following 2-5 wallets with **overlapping strategies** (e.g. all politics-focused, or all crypto-focused)\n- Wallets have similar conviction — mixing very different traders means most positions only appear in one wallet and get reduced sizing (50%)\n- Wallets trade markets available on Polymarket\n\n### Conviction Tiers\n\nWhen following multiple wallets, positions are scored by conviction:\n\n- **High conviction** (held by 2+ wallets): full position sizing (`max_usd`)\n- **Low conviction** (held by 1 wallet): 50% position sizing\n\nHigh-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).\n\n## Troubleshooting\n\n**\"Order too small\" / \"below minimum (5)\"**\n- Polymarket requires minimum 5 shares per order\n- Increase `--max-usd` or reduce `--top-n` to concentrate into fewer positions\n\n**\"No wallets specified\"**\n- Provide wallet addresses in your message, e.g., \"copytrade 0x1234...\"\n- Or set SIMMER_COPYTRADING_WALLETS environment variable for recurring scans\n\n**\"Agent has no USDC balance\"**\n- Need USDC in your Polymarket wallet, or use `--venue sim` for $SIM paper trading\n- Check wallet is linked at simmer.markets/dashboard\n\n**\"Conflict skipped\"**\n- Wallets disagree on this market (one long YES, other long NO)\n- Markets with net position < 10% are skipped\n\n**\"All N positions filtered (X conflicts, Y drifted, Z stale)\"**\n- All whale positions were removed by safety filters\n- Try different target wallets, or reduce to 1 wallet to disable conviction scoring\n- Drift filter skips positions where price moved >30% from whale's entry\n- Stale filter skips near-resolved markets (price >90% or <10%)\n\n**\"Insufficient balance\"**\n- Not enough USDC for all trades\n- Reduce SIMMER_COPYTRADING_TOP_N or SIMMER_COPYTRADING_MAX_USD\n\n**\"Market could not be imported\"**\n- Some markets may not be importable (resolved, private, etc.)\n- These are skipped automatically\n\n**\"External wallet requires a pre-signed order\"**\n- `WALLET_PRIVATE_KEY` is not set in the environment\n- The SDK signs orders automatically when this env var is present — no manual signing code needed\n- Fix: `export WALLET_PRIVATE_KEY=0x<your-polymarket-wallet-private-key>`\n- Do NOT attempt to sign orders manually or modify the skill code — the SDK handles it\n\n**\"Balance shows $0 but I have funds on Polygon\"**\n- Polymarket V2 (live 2026-04-28) uses **pUSD** (PolyUSD, 1:1 backed by USDC.e). If your wallet holds USDC.e, migrate at [simmer.markets/dashboard](https://simmer.markets/dashboard?ref=sdk-skill&utm_campaign=sdk-skill) with one click (~30s)\n- If you bridged native USDC (Circle), swap to USDC.e first, then migrate to pUSD\n- Full migration guide: [docs.simmer.markets/v2-migration](https://docs.simmer.markets/v2-migration)\n\nFile v1.12.3:_meta.json\n\n{\n  \"ownerId\": \"kn7axnp7bzqsf5fkx0z8px7han7zyq1x\",\n  \"slug\": \"polymarket-copytrading\",\n  \"version\": \"1.12.3\",\n  \"publishedAt\": 1788657077423\n}\n\nFile v1.12.3:DISCLAIMER.md\n\n# Disclaimer\n\nThis skill is a **framework**, not a production trading system. Read this\nin full before connecting it to a wallet with real funds.\n\n## No financial advice\n\nNothing in this skill constitutes financial, investment, or trading\nadvice. The default strategy implemented here is a starting point, not a\ntested edge. Suitability for any account size or risk tolerance is your\nresponsibility to assess.\n\n## Default parameters are not validated\n\nDefault parameters are calibrated for testing the plumbing, not for live\nprofit. They have not been validated to produce positive returns under\ncurrent market conditions. Run paper mode for an extended period before\nscaling beyond default position sizes.\n\n## Automated trading carries irreversible risk\n\nWhen this skill runs with `--live`, it places real on-chain orders.\nOn-chain trades cannot be recalled. Strategy errors, signal lag, market\nregime shifts, and operator misconfiguration can produce losses\nexceeding any specific position size.\n\n## Risk monitoring may not apply to all market types\n\nStop-loss and take-profit monitors run on a fixed schedule. Markets that\nresolve faster than the monitor cycle cannot be exited automatically.\nPosition sizing is the only risk control on these markets — set it\nconservatively.\n\n## Use of this skill is at your own risk\n\nBy installing and running this skill you agree that the authors are not\nliable for any losses, direct or indirect, that arise from its use. This\napplies regardless of skill provenance — official Simmer skills,\ncommunity skills, and skills imported from external repositories all\ncarry this same disclaimer.\n\n## Where to learn more before going live\n\n- The skill's own `SKILL.md` documents the strategy and parameters\n- Your trading venue's documentation covers fee structure, order types,\n  and resolution rules\n- Simmer SDK documentation covers paper mode, dry-run flags, and\n  position monitoring\n\nFile v1.12.3:skill-card.md\n\n## Description:\n\nMirror 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.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[simmer](https://clawhub.ai/user/simmer)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal traders and agents use this skill to inspect Polymarket whale positions, paper trade with Simmer, or execute capped copytrading runs. It supports portfolio-style polling and Pro Reactor mode for event-driven mirroring.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can automatically execute real-money trades and sells when run live.\n\nMitigation: Review carefully before installing, test with a dedicated low-balance wallet, and prefer --venue sim or COPYTRADING_FORCE_SIMMER_VENUE=true while validating behavior.\n\nRisk: Default polling should be treated as sell-capable unless whale-exit handling is disabled.\n\nMitigation: Use --no-whale-exits when buy-only behavior is required, and review rebalance and exit settings before running with live funds.\n\nRisk: Reactor cron can execute automatically and Reactor mode is documented as live execution.\n\nMitigation: Do not enable Reactor cron until the operator understands its automatic execution model, and use Simmer venue configuration for paper trading first.\n\nRisk: Trading behavior depends on installed dependencies and SDK behavior.\n\nMitigation: Pin and review dependencies before using live funds, including the required simmer-sdk package.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/simmer/skills/polymarket-copytrading)\n- [Simmer publisher profile](https://clawhub.ai/user/simmer)\n- [Simmer API](https://api.simmer.markets)\n- [Simmer dashboard](https://simmer.markets/dashboard)\n- [Polymarket V2 migration guide](https://docs.simmer.markets/v2-migration)\n- [predicting.top](https://predicting.top)\n- [alphawhale.trade](https://alphawhale.trade)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown status summaries with inline shell commands and configuration values]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May run dry-run simulations or live trading commands depending on user flags and venue configuration.]\n\n## Skill Version(s):\n\n1.12.3 (source: server release metadata and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.12.3:clawhub.json\n\n{\n  \"emoji\": \"\\ud83d\\udc0b\",\n  \"primaryEnv\": \"SIMMER_API_KEY\",\n  \"requires\": {\n    \"env\": [\n      \"SIMMER_API_KEY\"\n    ],\n    \"pip\": [\n      \"simmer-sdk>=0.11.1\"\n    ]\n  },\n  \"envVars\": [\n    {\n      \"name\": \"SIMMER_API_KEY\",\n      \"required\": true,\n      \"description\": \"Your Simmer SDK API key \\u2014 get from simmer.markets/dashboard\"\n    },\n    {\n      \"name\": \"WALLET_PRIVATE_KEY\",\n      \"required\": false,\n      \"description\": \"Only needed for external-wallet self-custody trading. Not required when using managed wallets.\"\n    }\n  ],\n  \"cron\": null,\n  \"autostart\": false,\n  \"automaton\": {\n    \"managed\": true,\n    \"entrypoint\": \"copytrading_trader.py\"\n  },\n  \"tunables\": [\n    {\n      \"env\": \"SIMMER_COPYTRADING_WALLETS\",\n      \"type\": \"string\",\n      \"default\": \"\",\n      \"label\": \"Whale wallet addresses (comma-separated)\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_MAX_USD\",\n      \"type\": \"number\",\n      \"default\": 50,\n      \"range\": [\n        1,\n        200\n      ],\n      \"step\": 5,\n      \"label\": \"Max bet per trade\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_TOP_N\",\n      \"type\": \"number\",\n      \"default\": 5,\n      \"range\": [\n        1,\n        20\n      ],\n      \"step\": 1,\n      \"label\": \"Positions to track\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_MAX_TRADES\",\n      \"type\": \"number\",\n      \"default\": 5,\n      \"range\": [\n        1,\n        20\n      ],\n      \"step\": 1,\n      \"label\": \"Max trades per run\"\n    },\n    {\n      \"env\": \"COPYTRADING_CADENCE_MODE\",\n      \"type\": \"string\",\n      \"default\": \"polling\",\n      \"enum\": [\"polling\", \"balanced\", \"aggressive\"],\n      \"label\": \"Cadence mode — set higher for more active polling (polling=10 trades/run, balanced=50, aggressive=200)\"\n    },\n    {\n      \"env\": \"COPYTRADING_FORCE_SIMMER_VENUE\",\n      \"type\": \"string\",\n      \"default\": \"\",\n      \"label\": \"Force Simmer ($SIM) venue — set to 'true' to disable auto-routing above-cap trades to Polymarket\"\n    }\n  ]\n}\n\nFile v1.12.3:requirements.txt\n\nsimmer-sdk>=0.11.1\npackaging>=20\n\nArchive v1.12.2: 10 files, 35136 bytes\n\nFiles: clawhub.json (1951b), copytrading_trader.py (53265b), DISCLAIMER.md (1925b), requirements.txt (33b), scripts/status.py (4939b), skill-card.md (2634b), SKILL.md (22233b), tests/__init__.py (0b), tests/test_venue_routing.py (14531b), _meta.json (142b)\n\nFile v1.12.2:SKILL.md\n\n---\nname: polymarket-copytrading\ndescription: 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.\nmetadata:\n  author: Simmer (@simmer_markets)\n  version: \"1.12.2\"\n  displayName: Polymarket Copytrading\n  difficulty: beginner\n---\n# Polymarket Copytrading\n\nMirror positions from successful Polymarket traders using the Simmer SDK. Two modes share the same skill, use whichever fits your strategy.\n\n> 🚨 **Framework, not a production trading system.** Read [DISCLAIMER.md](./DISCLAIMER.md) before connecting to a wallet with real funds. Per-position cap defaults to $50; per-run cap defaults to 10 trades. Use `$SIM` paper-mode to validate any new whale selection before scaling to real USDC.\n\n> **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.\n\n| | **Polling mode** (free) | **Reactor mode** (Pro) |\n|---|---|---|\n| Entrypoint | `copytrading_trader.py` | `copytrading_trader.py --reactor` |\n| Cadence | Batch scan, runs on cron or manual | Polls every 2s for pre-resolved whale signals |\n| Latency | Minutes (Polymarket Data API polling) | Seconds (Simmer detects events in real-time, pre-confirmation) |\n| 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 |\n| Best for | Portfolio-aware, multi-whale, periodic scans | Real-time reaction to specific whales as they trade |\n| Requires | `SIMMER_API_KEY` | `SIMMER_API_KEY` + Simmer Pro plan |\n\n## Setup Flow\n\nWhen user asks to install or configure this skill:\n\n1. **Install the Simmer SDK** (version 0.9.19 or newer — reactor mode requires it)\n   ```bash\n   pip install -U 'simmer-sdk>=0.9.19'\n   ```\n\n2. **Ask for Simmer API key**\n   - They can get it from simmer.markets/dashboard → SDK tab\n   - Store in environment as `SIMMER_API_KEY`\n\n3. **Ask for wallet private key** (required for live trading on Polymarket)\n   - This is the private key for their Polymarket wallet (the wallet that holds USDC)\n   - Store in environment as `WALLET_PRIVATE_KEY`\n   - The SDK uses this to sign orders client-side automatically — no manual signing needed\n   - Not needed for $SIM paper trading\n\n4. **Ask about settings** (or confirm defaults)\n   - Target wallets: Whale addresses to copy\n   - Max per position: Amount per trade (default $50)\n   - Top N positions: How many positions to track (auto-calculated from balance)\n   - Max trades per run: Safety cap (default 10)\n\n## When to Use This Skill\n\nUse this skill when the user wants to:\n- Copytrade whale wallets on Polymarket\n- Paper trade (copytrade with $SIM) to test strategies without real money\n- Check what positions a wallet holds\n- Follow specific trader addresses\n- Check their copytrading positions\n\n## Quick Commands\n\n```bash\n# Check account balance and positions\npython scripts/status.py\n\n# Detailed position list\npython scripts/status.py --positions\n```\n\n**API Reference:**\n- Base URL: `https://api.simmer.markets`\n- Auth: `Authorization: Bearer $SIMMER_API_KEY`\n- Portfolio: `GET /api/sdk/portfolio`\n- Positions: `GET /api/sdk/positions`\n\n## Finding Whale Wallets\n\n- **[predicting.top](https://predicting.top)** — Leaderboard of top Polymarket traders with wallet addresses\n- **[alphawhale.trade](https://alphawhale.trade)** — Tools for copying and tracking top performers\n- **Polymarket Leaderboard** — Official rankings (requires account)\n\n## Quick Start (Ad-Hoc Usage)\n\n**User provides wallet(s) directly in chat:**\n```\nUser: \"Copytrade this wallet: 0x1234...abcd\"\nUser: \"What positions does 0x5678...efgh have?\"\nUser: \"Follow these whales: 0xaaa..., 0xbbb...\"\n```\n\n→ Run with `--wallets` flag:\n```bash\npython copytrading_trader.py --wallets 0x1234...abcd\npython copytrading_trader.py --wallets 0xaaa...,0xbbb... --dry-run\n```\n\nThis is the simplest way - no setup needed, just pass wallets directly.\n\n## Persistent Setup (Optional)\n\nFor automated recurring scans, wallets can be saved in environment:\n\n| Setting | Environment Variable | Default |\n|---------|---------------------|---------|\n| Target wallets | `SIMMER_COPYTRADING_WALLETS` | (none) |\n| Top N positions | `SIMMER_COPYTRADING_TOP_N` | auto |\n| Max per position | `SIMMER_COPYTRADING_MAX_USD` | 50 |\n| Max trades/run | `SIMMER_COPYTRADING_MAX_TRADES` | 10 |\n| Order type | `SIMMER_COPYTRADING_ORDER_TYPE` | GTC |\n| Cadence mode | `COPYTRADING_CADENCE_MODE` | `polling` |\n| Force Simmer venue | `COPYTRADING_FORCE_SIMMER_VENUE` | (unset) |\n\n### Cadence mode (v1.11+)\n\n`COPYTRADING_CADENCE_MODE` controls how many trades the skill attempts per polling run. Choose based on how frequently your setup runs:\n\n| Preset | Max trades/run | When to use |\n|--------|---------------|-------------|\n| `polling` | 10 | **Default.** Original polling-mode behavior — unchanged for existing installs |\n| `balanced` | 50 | More active polling, want a higher per-run budget |\n| `aggressive` | 200 | High-frequency polling setups |\n\n```bash\nexport COPYTRADING_CADENCE_MODE=balanced\n```\n\nExisting installs default to `polling` — **no behavior change** unless you explicitly set this variable.\n\n> **Reactor mode note:** `cadence_mode` controls polling-mode trade budget only. In Reactor mode, each whale signal is handled individually by `_process_reactor_signal` — the per-run cap doesn't apply. If you hit `Daily trade limit reached (10/day)` in Reactor mode, raise the server-side limit via:\n> ```bash\n> curl -X PATCH \"https://api.simmer.markets/api/sdk/user/settings\" \\\n>   -H \"Authorization: Bearer $SIMMER_API_KEY\" \\\n>   -H \"Content-Type: application/json\" \\\n>   -d '{\"max_trades_per_day\": 200}'\n> ```\n\n> **Position cap:** The per-market position cap is controlled by `SIMMER_COPYTRADING_MAX_USD` (default 50). Raise it to allow larger positions per market.\n\n**Top N auto-calculation (when not specified):**\n- Balance < $50: Top 5 positions\n- Balance $50-200: Top 10 positions\n- Balance $200-500: Top 25 positions\n- Balance $500+: Top 50 positions\n\n**Polymarket Constraints:**\n- Minimum 5 shares per order\n- SDK enforces $1.00 minimum position value (filters dust positions)\n\n> ⚠️ **Start Conservative:** Begin with small amounts (`--max-usd 5-10`) and `--dry-run` to understand how the skill behaves before scaling up.\n\n## How It Works\n\n> **By default, only buys execute.** Pass `--rebalance` to also sell positions the whales have exited, or `--whale-exits` to sell only on whale exits.\n\nEach cycle the script:\n1. Fetches positions from all target wallets via Simmer API\n2. Combines using size-weighted aggregation (larger wallets = more influence)\n3. Detects conflicts (one wallet long YES, another long NO) and skips those markets\n4. Scores by conviction: positions held by 2+ wallets get full sizing, single-wallet positions get 50% sizing\n5. Filters out drifted (>30% from entry) and stale (>90% or <10% price) positions\n6. Applies Top-N filtering to concentrate on highest-conviction positions\n7. Auto-imports missing markets from Polymarket\n8. Calculates rebalance trades to match target allocations\n9. Executes trades via Simmer SDK (respects spending limits)\n10. Reports results back to user\n\n## Reactor Mode (Pro) — event-driven real-time mirroring\n\n> **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.\n\nReactor 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.\n\n### How it's different from polling mode\n\n- **Event-driven, not batched.** Each whale settlement is evaluated and acted on independently.\n- **Fixed per-event sizing.** `mirror_fraction` × whale size, capped at `max_size`. No conviction tiering, no rebalance math.\n- **Server-side watchlist filter.** Your watchlist + `min_size` are stored in Simmer's reactor config and applied on the server before events reach your skill — you only see matches.\n- **Pre-resolved signals.** The server resolves Polymarket condition IDs to Simmer market UUIDs before writing the signal — the skill receives trade-ready payloads.\n- **Mirrors maker AND taker fills (v1.12.1+).** The reactor copies a whale's trade whether they took liquidity (market order) or posted it (a resting limit order). Earlier versions only saw market-order fills, so feeds for whales who mostly post limit orders were quiet — those pick up on v1.12.1+. Your `mirror_fraction` / `max_size` / `daily_cap` still bound exposure, so more complete copying never exceeds your configured caps.\n- **Two run modes.** Loop mode (default, polls every 2s) or `--once` for cron-style single poll and exit.\n- **Circuit breaker.** 5 consecutive trade failures → signals are skipped until the next success. Prevents runaway failures from draining your wallet.\n- **Server-side dedup.** Signals have a 60-second TTL in Redis and are deleted after successful execution. No local state files needed.\n- **Buys only (MVP).** Reactor currently mirrors whale **buys only** — sell signals are filtered out server-side by the relay. If a whale exits a position, reactor won't mirror the sell. Sell mirroring is planned for a future release.\n\n### Configure your reactor watchlist\n\nReactor uses Simmer-side config (not env vars), so dashboard edits take effect in seconds without restarting the skill.\n\n```bash\n# Set your watchlist via the Simmer API\ncurl -X PATCH \"https://api.simmer.markets/api/sdk/reactor/config\" \\\n  -H \"Authorization: Bearer $SIMMER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"wallets\": [\"0x1234...abcd\", \"0x5678...efgh\"],\n    \"min_size\": 1000,\n    \"max_size\": 50,\n    \"mirror_fraction\": 0.01,\n    \"daily_cap\": 100,\n    \"venue\": \"sim\",\n    \"enabled\": true\n  }'\n```\n\nFields:\n\n| Field | Meaning |\n|---|---|\n| `wallets` | Whale addresses to follow (EVM format, lowercased server-side) |\n| `min_size` | Minimum whale trade size to consider (shares) |\n| `max_size` | Cap on your mirror trade size (shares) |\n| `mirror_fraction` | Fraction of whale size to mirror (e.g. 0.01 = 1%) |\n| `daily_cap` | Max total spend per day in venue-native units. Enforced by this skill at execution time. The server additionally stops proposing new signals once a day's proposed total exceeds 3x this value (runaway guard) — capped feeds show `skipped_daily_cap` entries in reactor status rather than going silent. |\n| `venue` | `sim` / `polymarket` / `kalshi` |\n| `enabled` | Pause reactor by setting `false` — server will stop delivering events |\n| `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. |\n\n### Run reactor mode\n\n**Recommended: cron with `--once`** — polls for pending signals once and exits. Run on a 1-minute cron for reliable, persistent coverage:\n\n```bash\n# Linux crontab\n*/1 * * * * cd /path/to/skill && python copytrading_trader.py --reactor --once --live\n\n# OpenClaw cron\nopenclaw cron add --name \"reactor-poll\" --cron \"*/1 * * * *\" --tz UTC --session isolated \\\n  --message \"Run: cd /path/to/skill && python3 copytrading_trader.py --reactor --once\"\n\n# One-off check\npython copytrading_trader.py --reactor --once\n```\n\n> **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.\n\n**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.\n\n```bash\n# With a process manager (launchd, systemd, supervisor)\npython copytrading_trader.py --reactor\n\n# Plain shell (will not auto-restart)\nnohup python copytrading_trader.py --reactor > reactor.log 2>&1 &\n```\n\nSet `REACTOR_POLL_INTERVAL_SECONDS` to tune the polling cadence (default 2s).\n\n> **Note:** Reactor mode always executes live trades (venue is set in your reactor config). Use `venue: \"sim\"` in your config to paper trade.\n\n### What happens per signal\n\n1. Skill polls `GET /api/sdk/reactor/pending` for pre-resolved whale signals\n2. Circuit breaker check: if 5+ consecutive failures in recent reactions, skip this tick\n3. For each signal: compute mirror size (`taker_size × mirror_fraction`, capped by `max_size`, floored at 5-share Polymarket minimum)\n4. If below minimum → `skipped_filter` reaction, no trade\n5. `SimmerClient.trade()` with `skill_slug=\"polymarket-copytrading\"` and `source=\"sdk:copytrading:reactor\"`\n6. On success: DELETE the signal from `/api/sdk/reactor/pending/{tx_hash}` and POST a `mirrored` reaction\n7. On failure: POST a `failed` reaction, leave signal (60s TTL clears it)\n\n### Example output\n\n```\n[reactor] price_buffer=0.020 (from config)\n[reactor] --once: single poll against /api/sdk/reactor/pending\n[reactor] 0 pending signals\n```\n\nWhen a whale trade matches your watchlist:\n\n```\n[reactor] price_buffer=0.020 (from config)\n[reactor] loop mode: polling /api/sdk/reactor/pending every 2.0s\n[reactor] 1 pending signal(s)\n[reactor] 0xbaa2bc... BUY 7067 shares on \"Will Iran strike Iraq by April 30, 2026?\"\n[reactor] mirror: 70.67 shares @ $0.673 (buffer +2.0%) → GTC order placed\n[reactor] ✅ mirrored — trade_id=a23dc52a, signal deleted\n```\n\n### Reactor venue auto-routing (v1.11+)\n\nWhen Reactor signals arrive sized above Simmer's 500 $SIM per-trade cap, the skill automatically routes them to Polymarket instead of failing silently. This lets you follow whale sizing without hitting the LMSR hard cap:\n\n```\n[reactor] 0xbaa2bc... amount 800.00 $SIM > 500 $SIM cap → routing to polymarket\n[reactor] ✅ 0xbaa2bc... mirrored 800.00 USD trade_id=a23dc52a\n```\n\n**Edge cases:**\n- **No Polymarket wallet configured**: skill falls back to a 500 $SIM-capped trade and logs the routing decision. You won't miss the signal entirely.\n- **`COPYTRADING_FORCE_SIMMER_VENUE=true`**: disables auto-routing. Signals above 500 $SIM are capped at 500 and traded on Simmer venue.\n- **Signal already targets Polymarket**: no change — auto-routing only fires on `sim` venue signals.\n\n### External wallets just work\n\nReactor 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.\n\n### When to use polling vs reactor\n\n- **Use polling** when you want portfolio-style copying: aggregate across multiple whales, rebalance to target allocations, run periodically from cron, filter drifted/stale positions. Doesn't require Pro.\n- **Use reactor** when you want real-time reaction to individual whale trades, fixed per-event sizing, and pre-resolved signals. Requires Pro.\n- **Use both** if you want: polling for your steady-state portfolio alignment + reactor for opportunistic real-time mirroring. Different flags, same skill, same API key.\n\n---\n\n## $SIM Paper Trading\n\nCopytrading supports $SIM mode — mirror whale positions using simulated money on Simmer's LMSR markets. No wallet or USDC required.\n\n```bash\n# Paper trade with $SIM (explicit)\npython copytrading_trader.py --venue sim --wallets 0x123... --live\n\n# Auto-detect: if your account has no linked wallet, $SIM is used automatically\npython copytrading_trader.py --wallets 0x123... --live\n```\n\nIn $SIM mode:\n- Trades execute on Simmer's LMSR at real Polymarket prices\n- Each market gets an independent $10K $SIM balance\n- Positions tracked in your Simmer portfolio (source: `sdk:copytrading`)\n- Whale signals still come from real Polymarket data\n\n## Running the Skill\n\n**Run a scan (dry run by default — no trades):**\n```bash\npython copytrading_trader.py\n```\n\n**Execute real trades:**\n```bash\npython copytrading_trader.py --live\n```\n\n**Check positions only:**\n```bash\npython copytrading_trader.py --positions\n```\n\n**View current config:**\n```bash\npython copytrading_trader.py --config\n```\n\n**Override wallets for one run:**\n```bash\npython copytrading_trader.py --wallets 0x123...,0x456...\n```\n\n**Full rebalance mode (includes sells):**\n```bash\npython copytrading_trader.py --rebalance\n```\n\n**Sell when whales exit positions:**\n```bash\npython copytrading_trader.py --whale-exits\n```\n\n## Reporting Results\n\nAfter each run, message the user with:\n- Current configuration (wallets, Top N, max position)\n- Number of wallets fetched and total positions found\n- Markets skipped due to conflicts\n- Trades executed (or skipped with reason)\n- Current portfolio positions\n\nExample output to share:\n```\n🐋 Copytrading Scan Complete\n\nConfiguration:\n• Following 2 wallets\n• Top 10 positions, max $50 each\n• Balance: $250.00 USDC\n\nFetched positions:\n• 0x1234...abcd: 15 positions\n• 0x5678...efgh: 22 positions\n• Combined: 28 unique markets\n• Conflicts skipped: 2\n\nTop 10 by allocation:\n1. \"Will BTC hit $100k?\" - 18.5% → BUY YES\n2. \"Trump pardons X?\" - 12.3% → BUY NO\n3. \"Fed rate cut Jan?\" - 9.8% → Already held\n...\n\nTrades executed: 4 buys ($180 total)\n• Bought 45 YES shares on \"Will BTC hit $100k?\" @ $0.82\n• Bought 120 NO shares on \"Trump pardons X?\" @ $0.15\n...\n\nNext scan in 4 hours.\n```\n\n## Example Conversations\n\n**User: \"Copytrade 0x1234...abcd\"**\n→ Run: `python copytrading_trader.py --wallets 0x1234...abcd`\n→ Report what positions that wallet has and what trades would execute\n\n**User: \"What is 0x5678...efgh holding?\"**\n→ Run: `python copytrading_trader.py --wallets 0x5678...efgh --dry-run`\n→ Show their positions without trading\n\n**User: \"Follow these wallets: 0xaaa..., 0xbbb..., 0xccc...\"**\n→ Run: `python copytrading_trader.py --wallets 0xaaa...,0xbbb...,0xccc...`\n→ Aggregate positions across all wallets, report results\n\n**User: \"Copytrade this whale but only top 5 positions\"**\n→ Run: `python copytrading_trader.py --wallets 0x... --top-n 5`\n\n**User: \"How are my positions doing?\"**\n→ Run: `python copytrading_trader.py --positions`\n→ Show current Polymarket positions with P&L\n\n**User: \"Show copytrading config\"**\n→ Run: `python copytrading_trader.py --config`\n→ Display current settings\n\n**User: \"Sell positions that whales have exited\"**\n→ Run: `python copytrading_trader.py --whale-exits`\n→ Compares your positions to whales, sells any they've closed\n\n**User: \"Do a full rebalance to match the whales\"**\n→ Run: `python copytrading_trader.py --rebalance`\n→ Includes both buys AND sells to match whale allocations\n\n## Finding Good Wallets to Follow\n\nCommon approaches:\n1. **Leaderboard tracking**: Check Polymarket leaderboards for consistent performers\n2. **Whale watchers**: Follow known profitable traders on social media\n3. **Specific strategies**: Follow wallets known for weather, politics, or crypto trades\n\nThe skill works best when:\n- Following 2-5 wallets with **overlapping strategies** (e.g. all politics-focused, or all crypto-focused)\n- Wallets have similar conviction — mixing very different traders means most positions only appear in one wallet and get reduced sizing (50%)\n- Wallets trade markets available on Polymarket\n\n### Conviction Tiers\n\nWhen following multiple wallets, positions are scored by conviction:\n\n- **High conviction** (held by 2+ wallets): full position sizing (`max_usd`)\n- **Low conviction** (held by 1 wallet): 50% position sizing\n\nHigh-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).\n\n## Troubleshooting\n\n**\"Order too small\" / \"below minimum (5)\"**\n- Polymarket requires minimum 5 shares per order\n- Increase `--max-usd` or reduce `--top-n` to concentrate into fewer positions\n\n**\"No wallets specified\"**\n- Provide wallet addresses in your message, e.g., \"copytrade 0x1234...\"\n- Or set SIMMER_COPYTRADING_WALLETS environment variable for recurring scans\n\n**\"Agent has no USDC balance\"**\n- Need USDC in your Polymarket wallet, or use `--venue sim` for $SIM paper trading\n- Check wallet is linked at simmer.markets/dashboard\n\n**\"Conflict skipped\"**\n- Wallets disagree on this market (one long YES, other long NO)\n- Markets with net position < 10% are skipped\n\n**\"All N positions filtered (X conflicts, Y drifted, Z stale)\"**\n- All whale positions were removed by safety filters\n- Try different target wallets, or reduce to 1 wallet to disable conviction scoring\n- Drift filter skips positions where price moved >30% from whale's entry\n- Stale filter skips near-resolved markets (price >90% or <10%)\n\n**\"Insufficient balance\"**\n- Not enough USDC for all trades\n- Reduce SIMMER_COPYTRADING_TOP_N or SIMMER_COPYTRADING_MAX_USD\n\n**\"Market could not be imported\"**\n- Some markets may not be importable (resolved, private, etc.)\n- These are skipped automatically\n\n**\"External wallet requires a pre-signed order\"**\n- `WALLET_PRIVATE_KEY` is not set in the environment\n- The SDK signs orders automatically when this env var is present — no manual signing code needed\n- Fix: `export WALLET_PRIVATE_KEY=0x<your-polymarket-wallet-private-key>`\n- Do NOT attempt to sign orders manually or modify the skill code — the SDK handles it\n\n**\"Balance shows $0 but I have funds on Polygon\"**\n- Polymarket V2 (live 2026-04-28) uses **pUSD** (PolyUSD, 1:1 backed by USDC.e). If your wallet holds USDC.e, migrate at [simmer.markets/dashboard](https://simmer.markets/dashboard?ref=sdk-skill&utm_campaign=sdk-skill) with one click (~30s)\n- If you bridged native USDC (Circle), swap to USDC.e first, then migrate to pUSD\n- Full migration guide: [docs.simmer.markets/v2-migration](https://docs.simmer.markets/v2-migration)\n\nFile v1.12.2:_meta.json\n\n{\n  \"ownerId\": \"kn7axnp7bzqsf5fkx0z8px7han7zyq1x\",\n  \"slug\": \"polymarket-copytrading\",\n  \"version\": \"1.12.2\",\n  \"publishedAt\": 1785892638628\n}\n\nFile v1.12.2:DISCLAIMER.md\n\n# Disclaimer\n\nThis skill is a **framework**, not a production trading system. Read this\nin full before connecting it to a wallet with real funds.\n\n## No financial advice\n\nNothing in this skill constitutes financial, investment, or trading\nadvice. The default strategy implemented here is a starting point, not a\ntested edge. Suitability for any account size or risk tolerance is your\nresponsibility to assess.\n\n## Default parameters are not validated\n\nDefault parameters are calibrated for testing the plumbing, not for live\nprofit. They have not been validated to produce positive returns under\ncurrent market conditions. Run paper mode for an extended period before\nscaling beyond default position sizes.\n\n## Automated trading carries irreversible risk\n\nWhen this skill runs with `--live`, it places real on-chain orders.\nOn-chain trades cannot be recalled. Strategy errors, signal lag, market\nregime shifts, and operator misconfiguration can produce losses\nexceeding any specific position size.\n\n## Risk monitoring may not apply to all market types\n\nStop-loss and take-profit monitors run on a fixed schedule. Markets that\nresolve faster than the monitor cycle cannot be exited automatically.\nPosition sizing is the only risk control on these markets — set it\nconservatively.\n\n## Use of this skill is at your own risk\n\nBy installing and running this skill you agree that the authors are not\nliable for any losses, direct or indirect, that arise from its use. This\napplies regardless of skill provenance — official Simmer skills,\ncommunity skills, and skills imported from external repositories all\ncarry this same disclaimer.\n\n## Where to learn more before going live\n\n- The skill's own `SKILL.md` documents the strategy and parameters\n- Your trading venue's documentation covers fee structure, order types,\n  and resolution rules\n- Simmer SDK documentation covers paper mode, dry-run flags, and\n  position monitoring\n\nFile v1.12.2:skill-card.md\n\n## Description:\n\nMirror 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.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[simmer](https://clawhub.ai/user/simmer)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and agents use this skill to inspect and mirror selected Polymarket trader wallets, either through dry-run or paper-trading workflows or through live automated trading with configured caps.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Reactor mode can place automated live trades, and polling dry-run behavior does not apply to reactor execution.\n\nMitigation: Use paper trading or polling dry-run before enabling reactor, and configure conservative max size and daily cap values before running reactor cron or loop mode.\n\nRisk: Live self-custody Polymarket trading may require a wallet private key in the environment.\n\nMitigation: Avoid setting WALLET_PRIVATE_KEY unless live self-custody trading is intended; prefer paper trading or managed-wallet workflows when validating the strategy.\n\nRisk: Copying selected wallets can create financial losses from signal lag, market movement, wallet-selection errors, or misconfiguration.\n\nMitigation: Validate wallet choices in paper mode, keep per-position and per-run caps low at first, and review reported skipped trades, conflicts, and positions after each run.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/simmer/skills/polymarket-copytrading)\n- [Skill disclaimer](DISCLAIMER.md)\n- [Simmer dashboard](https://simmer.markets/dashboard)\n- [Simmer v2 migration guide](https://docs.simmer.markets/v2-migration)\n- [predicting.top](https://predicting.top)\n- [alphawhale.trade](https://alphawhale.trade)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown and terminal-oriented text with inline shell commands and configuration values]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May trigger Simmer SDK/API calls and trading actions when the user runs the provided commands with live trading enabled.]\n\n## Skill Version(s):\n\n1.12.2 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.12.2:clawhub.json\n\n{\n  \"emoji\": \"\\ud83d\\udc0b\",\n  \"primaryEnv\": \"SIMMER_API_KEY\",\n  \"requires\": {\n    \"env\": [\n      \"SIMMER_API_KEY\"\n    ],\n    \"pip\": [\n      \"simmer-sdk>=0.11.1\"\n    ]\n  },\n  \"envVars\": [\n    {\n      \"name\": \"SIMMER_API_KEY\",\n      \"required\": true,\n      \"description\": \"Your Simmer SDK API key \\u2014 get from simmer.markets/dashboard\"\n    },\n    {\n      \"name\": \"WALLET_PRIVATE_KEY\",\n      \"required\": false,\n      \"description\": \"Only needed for external-wallet self-custody trading. Not required when using managed wallets.\"\n    }\n  ],\n  \"cron\": null,\n  \"autostart\": false,\n  \"automaton\": {\n    \"managed\": true,\n    \"entrypoint\": \"copytrading_trader.py\"\n  },\n  \"tunables\": [\n    {\n      \"env\": \"SIMMER_COPYTRADING_WALLETS\",\n      \"type\": \"string\",\n      \"default\": \"\",\n      \"label\": \"Whale wallet addresses (comma-separated)\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_MAX_USD\",\n      \"type\": \"number\",\n      \"default\": 50,\n      \"range\": [\n        1,\n        200\n      ],\n      \"step\": 5,\n      \"label\": \"Max bet per trade\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_TOP_N\",\n      \"type\": \"number\",\n      \"default\": 5,\n      \"range\": [\n        1,\n        20\n      ],\n      \"step\": 1,\n      \"label\": \"Positions to track\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_MAX_TRADES\",\n      \"type\": \"number\",\n      \"default\": 5,\n      \"range\": [\n        1,\n        20\n      ],\n      \"step\": 1,\n      \"label\": \"Max trades per run\"\n    },\n    {\n      \"env\": \"COPYTRADING_CADENCE_MODE\",\n      \"type\": \"string\",\n      \"default\": \"polling\",\n      \"enum\": [\"polling\", \"balanced\", \"aggressive\"],\n      \"label\": \"Cadence mode — set higher for more active polling (polling=10 trades/run, balanced=50, aggressive=200)\"\n    },\n    {\n      \"env\": \"COPYTRADING_FORCE_SIMMER_VENUE\",\n      \"type\": \"string\",\n      \"default\": \"\",\n      \"label\": \"Force Simmer ($SIM) venue — set to 'true' to disable auto-routing above-cap trades to Polymarket\"\n    }\n  ]\n}\n\nFile v1.12.2:requirements.txt\n\nsimmer-sdk>=0.11.1\npackaging>=20\n\nArchive v1.12.1: 10 files, 35083 bytes\n\nFiles: clawhub.json (1951b), copytrading_trader.py (53265b), DISCLAIMER.md (1925b), requirements.txt (33b), scripts/status.py (4930b), skill-card.md (2982b), SKILL.md (21941b), tests/__init__.py (0b), tests/test_venue_routing.py (14531b), _meta.json (142b)\n\nFile v1.12.1:SKILL.md\n\n---\nname: polymarket-copytrading\ndescription: 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.\nmetadata:\n  author: Simmer (@simmer_markets)\n  version: \"1.12.1\"\n  displayName: Polymarket Copytrading\n  difficulty: beginner\n---\n# Polymarket Copytrading\n\nMirror positions from successful Polymarket traders using the Simmer SDK. Two modes share the same skill, use whichever fits your strategy.\n\n> 🚨 **Framework, not a production trading system.** Read [DISCLAIMER.md](./DISCLAIMER.md) before connecting to a wallet with real funds. Per-position cap defaults to $50; per-run cap defaults to 10 trades. Use `$SIM` paper-mode to validate any new whale selection before scaling to real USDC.\n\n> **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.\n\n| | **Polling mode** (free) | **Reactor mode** (Pro) |\n|---|---|---|\n| Entrypoint | `copytrading_trader.py` | `copytrading_trader.py --reactor` |\n| Cadence | Batch scan, runs on cron or manual | Polls every 2s for pre-resolved whale signals |\n| Latency | Minutes (Polymarket Data API polling) | Seconds (Simmer detects events in real-time, pre-confirmation) |\n| 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 |\n| Best for | Portfolio-aware, multi-whale, periodic scans | Real-time reaction to specific whales as they trade |\n| Requires | `SIMMER_API_KEY` | `SIMMER_API_KEY` + Simmer Pro plan |\n\n## Setup Flow\n\nWhen user asks to install or configure this skill:\n\n1. **Install the Simmer SDK** (version 0.9.19 or newer — reactor mode requires it)\n   ```bash\n   pip install -U 'simmer-sdk>=0.9.19'\n   ```\n\n2. **Ask for Simmer API key**\n   - They can get it from simmer.markets/dashboard → SDK tab\n   - Store in environment as `SIMMER_API_KEY`\n\n3. **Ask for wallet private key** (required for live trading on Polymarket)\n   - This is the private key for their Polymarket wallet (the wallet that holds USDC)\n   - Store in environment as `WALLET_PRIVATE_KEY`\n   - The SDK uses this to sign orders client-side automatically — no manual signing needed\n   - Not needed for $SIM paper trading\n\n4. **Ask about settings** (or confirm defaults)\n   - Target wallets: Whale addresses to copy\n   - Max per position: Amount per trade (default $50)\n   - Top N positions: How many positions to track (auto-calculated from balance)\n   - Max trades per run: Safety cap (default 10)\n\n## When to Use This Skill\n\nUse this skill when the user wants to:\n- Copytrade whale wallets on Polymarket\n- Paper trade (copytrade with $SIM) to test strategies without real money\n- Check what positions a wallet holds\n- Follow specific trader addresses\n- Check their copytrading positions\n\n## Quick Commands\n\n```bash\n# Check account balance and positions\npython scripts/status.py\n\n# Detailed position list\npython scripts/status.py --positions\n```\n\n**API Reference:**\n- Base URL: `https://api.simmer.markets`\n- Auth: `Authorization: Bearer $SIMMER_API_KEY`\n- Portfolio: `GET /api/sdk/portfolio`\n- Positions: `GET /api/sdk/positions`\n\n## Finding Whale Wallets\n\n- **[predicting.top](https://predicting.top)** — Leaderboard of top Polymarket traders with wallet addresses\n- **[alphawhale.trade](https://alphawhale.trade)** — Tools for copying and tracking top performers\n- **Polymarket Leaderboard** — Official rankings (requires account)\n\n## Quick Start (Ad-Hoc Usage)\n\n**User provides wallet(s) directly in chat:**\n```\nUser: \"Copytrade this wallet: 0x1234...abcd\"\nUser: \"What positions does 0x5678...efgh have?\"\nUser: \"Follow these whales: 0xaaa..., 0xbbb...\"\n```\n\n→ Run with `--wallets` flag:\n```bash\npython copytrading_trader.py --wallets 0x1234...abcd\npython copytrading_trader.py --wallets 0xaaa...,0xbbb... --dry-run\n```\n\nThis is the simplest way - no setup needed, just pass wallets directly.\n\n## Persistent Setup (Optional)\n\nFor automated recurring scans, wallets can be saved in environment:\n\n| Setting | Environment Variable | Default |\n|---------|---------------------|---------|\n| Target wallets | `SIMMER_COPYTRADING_WALLETS` | (none) |\n| Top N positions | `SIMMER_COPYTRADING_TOP_N` | auto |\n| Max per position | `SIMMER_COPYTRADING_MAX_USD` | 50 |\n| Max trades/run | `SIMMER_COPYTRADING_MAX_TRADES` | 10 |\n| Order type | `SIMMER_COPYTRADING_ORDER_TYPE` | GTC |\n| Cadence mode | `COPYTRADING_CADENCE_MODE` | `polling` |\n| Force Simmer venue | `COPYTRADING_FORCE_SIMMER_VENUE` | (unset) |\n\n### Cadence mode (v1.11+)\n\n`COPYTRADING_CADENCE_MODE` controls how many trades the skill attempts per polling run. Choose based on how frequently your setup runs:\n\n| Preset | Max trades/run | When to use |\n|--------|---------------|-------------|\n| `polling` | 10 | **Default.** Original polling-mode behavior — unchanged for existing installs |\n| `balanced` | 50 | More active polling, want a higher per-run budget |\n| `aggressive` | 200 | High-frequency polling setups |\n\n```bash\nexport COPYTRADING_CADENCE_MODE=balanced\n```\n\nExisting installs default to `polling` — **no behavior change** unless you explicitly set this variable.\n\n> **Reactor mode note:** `cadence_mode` controls polling-mode trade budget only. In Reactor mode, each whale signal is handled individually by `_process_reactor_signal` — the per-run cap doesn't apply. If you hit `Daily trade limit reached (10/day)` in Reactor mode, raise the server-side limit via:\n> ```bash\n> curl -X PATCH \"https://api.simmer.markets/api/sdk/user/settings\" \\\n>   -H \"Authorization: Bearer $SIMMER_API_KEY\" \\\n>   -H \"Content-Type: application/json\" \\\n>   -d '{\"max_trades_per_day\": 200}'\n> ```\n\n> **Position cap:** The per-market position cap is controlled by `SIMMER_COPYTRADING_MAX_USD` (default 50). Raise it to allow larger positions per market.\n\n**Top N auto-calculation (when not specified):**\n- Balance < $50: Top 5 positions\n- Balance $50-200: Top 10 positions\n- Balance $200-500: Top 25 positions\n- Balance $500+: Top 50 positions\n\n**Polymarket Constraints:**\n- Minimum 5 shares per order\n- SDK enforces $1.00 minimum position value (filters dust positions)\n\n> ⚠️ **Start Conservative:** Begin with small amounts (`--max-usd 5-10`) and `--dry-run` to understand how the skill behaves before scaling up.\n\n## How It Works\n\n> **By default, only buys execute.** Pass `--rebalance` to also sell positions the whales have exited, or `--whale-exits` to sell only on whale exits.\n\nEach cycle the script:\n1. Fetches positions from all target wallets via Simmer API\n2. Combines using size-weighted aggregation (larger wallets = more influence)\n3. Detects conflicts (one wallet long YES, another long NO) and skips those markets\n4. Scores by conviction: positions held by 2+ wallets get full sizing, single-wallet positions get 50% sizing\n5. Filters out drifted (>30% from entry) and stale (>90% or <10% price) positions\n6. Applies Top-N filtering to concentrate on highest-conviction positions\n7. Auto-imports missing markets from Polymarket\n8. Calculates rebalance trades to match target allocations\n9. Executes trades via Simmer SDK (respects spending limits)\n10. Reports results back to user\n\n## Reactor Mode (Pro) — event-driven real-time mirroring\n\n> **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.\n\nReactor 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.\n\n### How it's different from polling mode\n\n- **Event-driven, not batched.** Each whale settlement is evaluated and acted on independently.\n- **Fixed per-event sizing.** `mirror_fraction` × whale size, capped at `max_size`. No conviction tiering, no rebalance math.\n- **Server-side watchlist filter.** Your watchlist + `min_size` are stored in Simmer's reactor config and applied on the server before events reach your skill — you only see matches.\n- **Pre-resolved signals.** The server resolves Polymarket condition IDs to Simmer market UUIDs before writing the signal — the skill receives trade-ready payloads.\n- **Mirrors maker AND taker fills (v1.12.1+).** The reactor copies a whale's trade whether they took liquidity (market order) or posted it (a resting limit order). Earlier versions only saw market-order fills, so feeds for whales who mostly post limit orders were quiet — those pick up on v1.12.1+. Your `mirror_fraction` / `max_size` / `daily_cap` still bound exposure, so more complete copying never exceeds your configured caps.\n- **Two run modes.** Loop mode (default, polls every 2s) or `--once` for cron-style single poll and exit.\n- **Circuit breaker.** 5 consecutive trade failures → signals are skipped until the next success. Prevents runaway failures from draining your wallet.\n- **Server-side dedup.** Signals have a 60-second TTL in Redis and are deleted after successful execution. No local state files needed.\n- **Buys only (MVP).** Reactor currently mirrors whale **buys only** — sell signals are filtered out server-side by the relay. If a whale exits a position, reactor won't mirror the sell. Sell mirroring is planned for a future release.\n\n### Configure your reactor watchlist\n\nReactor uses Simmer-side config (not env vars), so dashboard edits take effect in seconds without restarting the skill.\n\n```bash\n# Set your watchlist via the Simmer API\ncurl -X PATCH \"https://api.simmer.markets/api/sdk/reactor/config\" \\\n  -H \"Authorization: Bearer $SIMMER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"wallets\": [\"0x1234...abcd\", \"0x5678...efgh\"],\n    \"min_size\": 1000,\n    \"max_size\": 50,\n    \"mirror_fraction\": 0.01,\n    \"daily_cap\": 100,\n    \"venue\": \"sim\",\n    \"enabled\": true\n  }'\n```\n\nFields:\n\n| Field | Meaning |\n|---|---|\n| `wallets` | Whale addresses to follow (EVM format, lowercased server-side) |\n| `min_size` | Minimum whale trade size to consider (shares) |\n| `max_size` | Cap on your mirror trade size (shares) |\n| `mirror_fraction` | Fraction of whale size to mirror (e.g. 0.01 = 1%) |\n| `daily_cap` | Max total spend per day in venue-native units |\n| `venue` | `sim` / `polymarket` / `kalshi` |\n| `enabled` | Pause reactor by setting `false` — server will stop delivering events |\n| `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. |\n\n### Run reactor mode\n\n**Recommended: cron with `--once`** — polls for pending signals once and exits. Run on a 1-minute cron for reliable, persistent coverage:\n\n```bash\n# Linux crontab\n*/1 * * * * cd /path/to/skill && python copytrading_trader.py --reactor --once --live\n\n# OpenClaw cron\nopenclaw cron add --name \"reactor-poll\" --cron \"*/1 * * * *\" --tz UTC --session isolated \\\n  --message \"Run: cd /path/to/skill && python3 copytrading_trader.py --reactor --once\"\n\n# One-off check\npython copytrading_trader.py --reactor --once\n```\n\n> **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.\n\n**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.\n\n```bash\n# With a process manager (launchd, systemd, supervisor)\npython copytrading_trader.py --reactor\n\n# Plain shell (will not auto-restart)\nnohup python copytrading_trader.py --reactor > reactor.log 2>&1 &\n```\n\nSet `REACTOR_POLL_INTERVAL_SECONDS` to tune the polling cadence (default 2s).\n\n> **Note:** Reactor mode always executes live trades (venue is set in your reactor config). Use `venue: \"sim\"` in your config to paper trade.\n\n### What happens per signal\n\n1. Skill polls `GET /api/sdk/reactor/pending` for pre-resolved whale signals\n2. Circuit breaker check: if 5+ consecutive failures in recent reactions, skip this tick\n3. For each signal: compute mirror size (`taker_size × mirror_fraction`, capped by `max_size`, floored at 5-share Polymarket minimum)\n4. If below minimum → `skipped_filter` reaction, no trade\n5. `SimmerClient.trade()` with `skill_slug=\"polymarket-copytrading\"` and `source=\"sdk:copytrading:reactor\"`\n6. On success: DELETE the signal from `/api/sdk/reactor/pending/{tx_hash}` and POST a `mirrored` reaction\n7. On failure: POST a `failed` reaction, leave signal (60s TTL clears it)\n\n### Example output\n\n```\n[reactor] price_buffer=0.020 (from config)\n[reactor] --once: single poll against /api/sdk/reactor/pending\n[reactor] 0 pending signals\n```\n\nWhen a whale trade matches your watchlist:\n\n```\n[reactor] price_buffer=0.020 (from config)\n[reactor] loop mode: polling /api/sdk/reactor/pending every 2.0s\n[reactor] 1 pending signal(s)\n[reactor] 0xbaa2bc... BUY 7067 shares on \"Will Iran strike Iraq by April 30, 2026?\"\n[reactor] mirror: 70.67 shares @ $0.673 (buffer +2.0%) → GTC order placed\n[reactor] ✅ mirrored — trade_id=a23dc52a, signal deleted\n```\n\n### Reactor venue auto-routing (v1.11+)\n\nWhen Reactor signals arrive sized above Simmer's 500 $SIM per-trade cap, the skill automatically routes them to Polymarket instead of failing silently. This lets you follow whale sizing without hitting the LMSR hard cap:\n\n```\n[reactor] 0xbaa2bc... amount 800.00 $SIM > 500 $SIM cap → routing to polymarket\n[reactor] ✅ 0xbaa2bc... mirrored 800.00 USD trade_id=a23dc52a\n```\n\n**Edge cases:**\n- **No Polymarket wallet configured**: skill falls back to a 500 $SIM-capped trade and logs the routing decision. You won't miss the signal entirely.\n- **`COPYTRADING_FORCE_SIMMER_VENUE=true`**: disables auto-routing. Signals above 500 $SIM are capped at 500 and traded on Simmer venue.\n- **Signal already targets Polymarket**: no change — auto-routing only fires on `sim` venue signals.\n\n### External wallets just work\n\nReactor 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.\n\n### When to use polling vs reactor\n\n- **Use polling** when you want portfolio-style copying: aggregate across multiple whales, rebalance to target allocations, run periodically from cron, filter drifted/stale positions. Doesn't require Pro.\n- **Use reactor** when you want real-time reaction to individual whale trades, fixed per-event sizing, and pre-resolved signals. Requires Pro.\n- **Use both** if you want: polling for your steady-state portfolio alignment + reactor for opportunistic real-time mirroring. Different flags, same skill, same API key.\n\n---\n\n## $SIM Paper Trading\n\nCopytrading supports $SIM mode — mirror whale positions using simulated money on Simmer's LMSR markets. No wallet or USDC required.\n\n```bash\n# Paper trade with $SIM (explicit)\npython copytrading_trader.py --venue sim --wallets 0x123... --live\n\n# Auto-detect: if your account has no linked wallet, $SIM is used automatically\npython copytrading_trader.py --wallets 0x123... --live\n```\n\nIn $SIM mode:\n- Trades execute on Simmer's LMSR at real Polymarket prices\n- Each market gets an independent $10K $SIM balance\n- Positions tracked in your Simmer portfolio (source: `sdk:copytrading`)\n- Whale signals still come from real Polymarket data\n\n## Running the Skill\n\n**Run a scan (dry run by default — no trades):**\n```bash\npython copytrading_trader.py\n```\n\n**Execute real trades:**\n```bash\npython copytrading_trader.py --live\n```\n\n**Check positions only:**\n```bash\npython copytrading_trader.py --positions\n```\n\n**View current config:**\n```bash\npython copytrading_trader.py --config\n```\n\n**Override wallets for one run:**\n```bash\npython copytrading_trader.py --wallets 0x123...,0x456...\n```\n\n**Full rebalance mode (includes sells):**\n```bash\npython copytrading_trader.py --rebalance\n```\n\n**Sell when whales exit positions:**\n```bash\npython copytrading_trader.py --whale-exits\n```\n\n## Reporting Results\n\nAfter each run, message the user with:\n- Current configuration (wallets, Top N, max position)\n- Number of wallets fetched and total positions found\n- Markets skipped due to conflicts\n- Trades executed (or skipped with reason)\n- Current portfolio positions\n\nExample output to share:\n```\n🐋 Copytrading Scan Complete\n\nConfiguration:\n• Following 2 wallets\n• Top 10 positions, max $50 each\n• Balance: $250.00 USDC\n\nFetched positions:\n• 0x1234...abcd: 15 positions\n• 0x5678...efgh: 22 positions\n• Combined: 28 unique markets\n• Conflicts skipped: 2\n\nTop 10 by allocation:\n1. \"Will BTC hit $100k?\" - 18.5% → BUY YES\n2. \"Trump pardons X?\" - 12.3% → BUY NO\n3. \"Fed rate cut Jan?\" - 9.8% → Already held\n...\n\nTrades executed: 4 buys ($180 total)\n• Bought 45 YES shares on \"Will BTC hit $100k?\" @ $0.82\n• Bought 120 NO shares on \"Trump pardons X?\" @ $0.15\n...\n\nNext scan in 4 hours.\n```\n\n## Example Conversations\n\n**User: \"Copytrade 0x1234...abcd\"**\n→ Run: `python copytrading_trader.py --wallets 0x1234...abcd`\n→ Report what positions that wallet has and what trades would execute\n\n**User: \"What is 0x5678...efgh holding?\"**\n→ Run: `python copytrading_trader.py --wallets 0x5678...efgh --dry-run`\n→ Show their positions without trading\n\n**User: \"Follow these wallets: 0xaaa..., 0xbbb..., 0xccc...\"**\n→ Run: `python copytrading_trader.py --wallets 0xaaa...,0xbbb...,0xccc...`\n→ Aggregate positions across all wallets, report results\n\n**User: \"Copytrade this whale but only top 5 positions\"**\n→ Run: `python copytrading_trader.py --wallets 0x... --top-n 5`\n\n**User: \"How are my positions doing?\"**\n→ Run: `python copytrading_trader.py --positions`\n→ Show current Polymarket positions with P&L\n\n**User: \"Show copytrading config\"**\n→ Run: `python copytrading_trader.py --config`\n→ Display current settings\n\n**User: \"Sell positions that whales have exited\"**\n→ Run: `python copytrading_trader.py --whale-exits`\n→ Compares your positions to whales, sells any they've closed\n\n**User: \"Do a full rebalance to match the whales\"**\n→ Run: `python copytrading_trader.py --rebalance`\n→ Includes both buys AND sells to match whale allocations\n\n## Finding Good Wallets to Follow\n\nCommon approaches:\n1. **Leaderboard tracking**: Check Polymarket leaderboards for consistent performers\n2. **Whale watchers**: Follow known profitable traders on social media\n3. **Specific strategies**: Follow wallets known for weather, politics, or crypto trades\n\nThe skill works best when:\n- Following 2-5 wallets with **overlapping strategies** (e.g. all politics-focused, or all crypto-focused)\n- Wallets have similar conviction — mixing very different traders means most positions only appear in one wallet and get reduced sizing (50%)\n- Wallets trade markets available on Polymarket\n\n### Conviction Tiers\n\nWhen following multiple wallets, positions are scored by conviction:\n\n- **High conviction** (held by 2+ wallets): full position sizing (`max_usd`)\n- **Low conviction** (held by 1 wallet): 50% position sizing\n\nHigh-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).\n\n## Troubleshooting\n\n**\"Order too small\" / \"below minimum (5)\"**\n- Polymarket requires minimum 5 shares per order\n- Increase `--max-usd` or reduce `--top-n` to concentrate into fewer positions\n\n**\"No wallets specified\"**\n- Provide wallet addresses in your message, e.g., \"copytrade 0x1234...\"\n- Or set SIMMER_COPYTRADING_WALLETS environment variable for recurring scans\n\n**\"Agent has no USDC balance\"**\n- Need USDC in your Polymarket wallet, or use `--venue sim` for $SIM paper trading\n- Check wallet is linked at simmer.markets/dashboard\n\n**\"Conflict skipped\"**\n- Wallets disagree on this market (one long YES, other long NO)\n- Markets with net position < 10% are skipped\n\n**\"All N positions filtered (X conflicts, Y drifted, Z stale)\"**\n- All whale positions were removed by safety filters\n- Try different target wallets, or reduce to 1 wallet to disable conviction scoring\n- Drift filter skips positions where price moved >30% from whale's entry\n- Stale filter skips near-resolved markets (price >90% or <10%)\n\n**\"Insufficient balance\"**\n- Not enough USDC for all trades\n- Reduce SIMMER_COPYTRADING_TOP_N or SIMMER_COPYTRADING_MAX_USD\n\n**\"Market could not be imported\"**\n- Some markets may not be importable (resolved, private, etc.)\n- These are skipped automatically\n\n**\"External wallet requires a pre-signed order\"**\n- `WALLET_PRIVATE_KEY` is not set in the environment\n- The SDK signs orders automatically when this env var is present — no manual signing code needed\n- Fix: `export WALLET_PRIVATE_KEY=0x<your-polymarket-wallet-private-key>`\n- Do NOT attempt to sign orders manually or modify the skill code — the SDK handles it\n\n**\"Balance shows $0 but I have funds on Polygon\"**\n- Polymarket V2 (live 2026-04-28) uses **pUSD** (PolyUSD, 1:1 backed by USDC.e). If your wallet holds USDC.e, migrate at [simmer.markets/dashboard](https://simmer.markets/dashboard) with one click (~30s)\n- If you bridged native USDC (Circle), swap to USDC.e first, then migrate to pUSD\n- Full migration guide: [docs.simmer.markets/v2-migration](https://docs.simmer.markets/v2-migration)\n\nFile v1.12.1:_meta.json\n\n{\n  \"ownerId\": \"kn7axnp7bzqsf5fkx0z8px7han7zyq1x\",\n  \"slug\": \"polymarket-copytrading\",\n  \"version\": \"1.12.1\",\n  \"publishedAt\": 1782443990563\n}\n\nFile v1.12.1:DISCLAIMER.md\n\n# Disclaimer\n\nThis skill is a **framework**, not a production trading system. Read this\nin full before connecting it to a wallet with real funds.\n\n## No financial advice\n\nNothing in this skill constitutes financial, investment, or trading\nadvice. The default strategy implemented here is a starting point, not a\ntested edge. Suitability for any account size or risk tolerance is your\nresponsibility to assess.\n\n## Default parameters are not validated\n\nDefault parameters are calibrated for testing the plumbing, not for live\nprofit. They have not been validated to produce positive returns under\ncurrent market conditions. Run paper mode for an extended period before\nscaling beyond default position sizes.\n\n## Automated trading carries irreversible risk\n\nWhen this skill runs with `--live`, it places real on-chain orders.\nOn-chain trades cannot be recalled. Strategy errors, signal lag, market\nregime shifts, and operator misconfiguration can produce losses\nexceeding any specific position size.\n\n## Risk monitoring may not apply to all market types\n\nStop-loss and take-profit monitors run on a fixed schedule. Markets that\nresolve faster than the monitor cycle cannot be exited automatically.\nPosition sizing is the only risk control on these markets — set it\nconservatively.\n\n## Use of this skill is at your own risk\n\nBy installing and running this skill you agree that the authors are not\nliable for any losses, direct or indirect, that arise from its use. This\napplies regardless of skill provenance — official Simmer skills,\ncommunity skills, and skills imported from external repositories all\ncarry this same disclaimer.\n\n## Where to learn more before going live\n\n- The skill's own `SKILL.md` documents the strategy and parameters\n- Your trading venue's documentation covers fee structure, order types,\n  and resolution rules\n- Simmer SDK documentation covers paper mode, dry-run flags, and\n  position monitoring\n\nFile v1.12.1:skill-card.md\n\n## Description: <br>\nMirror positions from top Polymarket traders with polling mode for portfolio-style copying and Reactor mode for event-driven real-time mirroring via Simmer's on-chain signal infrastructure. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[simmer](https://clawhub.ai/user/simmer) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal users and their agents use this skill to configure and run Polymarket copytrading workflows, including dry-run checks, paper-mode trading, wallet-following scans, and Reactor-mode mirroring for eligible Simmer Pro users. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Automated copytrading can place live trades with real funds when configured for live trading or Reactor mode. <br>\nMitigation: Start in dry-run or $SIM mode, use conservative position caps, and review venue, max_size, daily_cap, and watchlist settings before enabling live execution. <br>\nRisk: A raw wallet private key used for external-wallet trading would expose funds if mishandled. <br>\nMitigation: Prefer managed wallets, or use a dedicated low-balance trading wallet when WALLET_PRIVATE_KEY is required. <br>\nRisk: Reactor mode can execute live trades even when the normal dry-run default would otherwise apply. <br>\nMitigation: Treat Reactor setup as live automation, verify server-side Reactor configuration, and use the sim venue for paper trading. <br>\nRisk: Strategy errors, market movement, signal lag, and misconfiguration can produce trading losses. <br>\nMitigation: Validate selected wallets and sizing in paper mode, keep per-position and daily caps low, and periodically review generated trade reports. <br>\n\n\n## Reference(s): <br>\n- [ClawHub Skill Page](https://clawhub.ai/simmer/skills/polymarket-copytrading) <br>\n- [Simmer API](https://api.simmer.markets) <br>\n- [Simmer Dashboard](https://simmer.markets/dashboard) <br>\n- [Polymarket V2 Migration Guide](https://docs.simmer.markets/v2-migration) <br>\n- [predicting.top](https://predicting.top) <br>\n- [alphawhale.trade](https://alphawhale.trade) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown guidance with inline shell commands, environment-variable configuration, API endpoints, and trade-status text.] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Can produce dry-run summaries, account status, copytrading configuration, and live or simulated trade execution reports.] <br>\n\n## Skill Version(s): <br>\n1.12.1 (source: release evidence and SKILL.md frontmatter) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.12.1:clawhub.json\n\n{\n  \"emoji\": \"\\ud83d\\udc0b\",\n  \"primaryEnv\": \"SIMMER_API_KEY\",\n  \"requires\": {\n    \"env\": [\n      \"SIMMER_API_KEY\"\n    ],\n    \"pip\": [\n      \"simmer-sdk>=0.11.1\"\n    ]\n  },\n  \"envVars\": [\n    {\n      \"name\": \"SIMMER_API_KEY\",\n      \"required\": true,\n      \"description\": \"Your Simmer SDK API key \\u2014 get from simmer.markets/dashboard\"\n    },\n    {\n      \"name\": \"WALLET_PRIVATE_KEY\",\n      \"required\": false,\n      \"description\": \"Only needed for external-wallet self-custody trading. Not required when using managed wallets.\"\n    }\n  ],\n  \"cron\": null,\n  \"autostart\": false,\n  \"automaton\": {\n    \"managed\": true,\n    \"entrypoint\": \"copytrading_trader.py\"\n  },\n  \"tunables\": [\n    {\n      \"env\": \"SIMMER_COPYTRADING_WALLETS\",\n      \"type\": \"string\",\n      \"default\": \"\",\n      \"label\": \"Whale wallet addresses (comma-separated)\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_MAX_USD\",\n      \"type\": \"number\",\n      \"default\": 50,\n      \"range\": [\n        1,\n        200\n      ],\n      \"step\": 5,\n      \"label\": \"Max bet per trade\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_TOP_N\",\n      \"type\": \"number\",\n      \"default\": 5,\n      \"range\": [\n        1,\n        20\n      ],\n      \"step\": 1,\n      \"label\": \"Positions to track\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_MAX_TRADES\",\n      \"type\": \"number\",\n      \"default\": 5,\n      \"range\": [\n        1,\n        20\n      ],\n      \"step\": 1,\n      \"label\": \"Max trades per run\"\n    },\n    {\n      \"env\": \"COPYTRADING_CADENCE_MODE\",\n      \"type\": \"string\",\n      \"default\": \"polling\",\n      \"enum\": [\"polling\", \"balanced\", \"aggressive\"],\n      \"label\": \"Cadence mode — set higher for more active polling (polling=10 trades/run, balanced=50, aggressive=200)\"\n    },\n    {\n      \"env\": \"COPYTRADING_FORCE_SIMMER_VENUE\",\n      \"type\": \"string\",\n      \"default\": \"\",\n      \"label\": \"Force Simmer ($SIM) venue — set to 'true' to disable auto-routing above-cap trades to Polymarket\"\n    }\n  ]\n}\n\nFile v1.12.1:requirements.txt\n\nsimmer-sdk>=0.11.1\npackaging>=20\n\nArchive v1.12.0: 10 files, 34928 bytes\n\nFiles: clawhub.json (1951b), copytrading_trader.py (52950b), DISCLAIMER.md (1925b), requirements.txt (33b), scripts/status.py (4930b), skill-card.md (3319b), SKILL.md (21507b), tests/__init__.py (0b), tests/test_venue_routing.py (14531b), _meta.json (142b)\n\nFile v1.12.0:SKILL.md\n\n---\nname: polymarket-copytrading\ndescription: 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.\nmetadata:\n  author: Simmer (@simmer_markets)\n  version: \"1.12.0\"\n  displayName: Polymarket Copytrading\n  difficulty: beginner\n---\n# Polymarket Copytrading\n\nMirror positions from successful Polymarket traders using the Simmer SDK. Two modes share the same skill, use whichever fits your strategy.\n\n> 🚨 **Framework, not a production trading system.** Read [DISCLAIMER.md](./DISCLAIMER.md) before connecting to a wallet with real funds. Per-position cap defaults to $50; per-run cap defaults to 10 trades. Use `$SIM` paper-mode to validate any new whale selection before scaling to real USDC.\n\n> **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.\n\n| | **Polling mode** (free) | **Reactor mode** (Pro) |\n|---|---|---|\n| Entrypoint | `copytrading_trader.py` | `copytrading_trader.py --reactor` |\n| Cadence | Batch scan, runs on cron or manual | Polls every 2s for pre-resolved whale signals |\n| Latency | Minutes (Polymarket Data API polling) | Seconds (Simmer detects events in real-time, pre-confirmation) |\n| 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 |\n| Best for | Portfolio-aware, multi-whale, periodic scans | Real-time reaction to specific whales as they trade |\n| Requires | `SIMMER_API_KEY` | `SIMMER_API_KEY` + Simmer Pro plan |\n\n## Setup Flow\n\nWhen user asks to install or configure this skill:\n\n1. **Install the Simmer SDK** (version 0.9.19 or newer — reactor mode requires it)\n   ```bash\n   pip install -U 'simmer-sdk>=0.9.19'\n   ```\n\n2. **Ask for Simmer API key**\n   - They can get it from simmer.markets/dashboard → SDK tab\n   - Store in environment as `SIMMER_API_KEY`\n\n3. **Ask for wallet private key** (required for live trading on Polymarket)\n   - This is the private key for their Polymarket wallet (the wallet that holds USDC)\n   - Store in environment as `WALLET_PRIVATE_KEY`\n   - The SDK uses this to sign orders client-side automatically — no manual signing needed\n   - Not needed for $SIM paper trading\n\n4. **Ask about settings** (or confirm defaults)\n   - Target wallets: Whale addresses to copy\n   - Max per position: Amount per trade (default $50)\n   - Top N positions: How many positions to track (auto-calculated from balance)\n   - Max trades per run: Safety cap (default 10)\n\n## When to Use This Skill\n\nUse this skill when the user wants to:\n- Copytrade whale wallets on Polymarket\n- Paper trade (copytrade with $SIM) to test strategies without real money\n- Check what positions a wallet holds\n- Follow specific trader addresses\n- Check their copytrading positions\n\n## Quick Commands\n\n```bash\n# Check account balance and positions\npython scripts/status.py\n\n# Detailed position list\npython scripts/status.py --positions\n```\n\n**API Reference:**\n- Base URL: `https://api.simmer.markets`\n- Auth: `Authorization: Bearer $SIMMER_API_KEY`\n- Portfolio: `GET /api/sdk/portfolio`\n- Positions: `GET /api/sdk/positions`\n\n## Finding Whale Wallets\n\n- **[predicting.top](https://predicting.top)** — Leaderboard of top Polymarket traders with wallet addresses\n- **[alphawhale.trade](https://alphawhale.trade)** — Tools for copying and tracking top performers\n- **Polymarket Leaderboard** — Official rankings (requires account)\n\n## Quick Start (Ad-Hoc Usage)\n\n**User provides wallet(s) directly in chat:**\n```\nUser: \"Copytrade this wallet: 0x1234...abcd\"\nUser: \"What positions does 0x5678...efgh have?\"\nUser: \"Follow these whales: 0xaaa..., 0xbbb...\"\n```\n\n→ Run with `--wallets` flag:\n```bash\npython copytrading_trader.py --wallets 0x1234...abcd\npython copytrading_trader.py --wallets 0xaaa...,0xbbb... --dry-run\n```\n\nThis is the simplest way - no setup needed, just pass wallets directly.\n\n## Persistent Setup (Optional)\n\nFor automated recurring scans, wallets can be saved in environment:\n\n| Setting | Environment Variable | Default |\n|---------|---------------------|---------|\n| Target wallets | `SIMMER_COPYTRADING_WALLETS` | (none) |\n| Top N positions | `SIMMER_COPYTRADING_TOP_N` | auto |\n| Max per position | `SIMMER_COPYTRADING_MAX_USD` | 50 |\n| Max trades/run | `SIMMER_COPYTRADING_MAX_TRADES` | 10 |\n| Order type | `SIMMER_COPYTRADING_ORDER_TYPE` | GTC |\n| Cadence mode | `COPYTRADING_CADENCE_MODE` | `polling` |\n| Force Simmer venue | `COPYTRADING_FORCE_SIMMER_VENUE` | (unset) |\n\n### Cadence mode (v1.11+)\n\n`COPYTRADING_CADENCE_MODE` controls how many trades the skill attempts per polling run. Choose based on how frequently your setup runs:\n\n| Preset | Max trades/run | When to use |\n|--------|---------------|-------------|\n| `polling` | 10 | **Default.** Original polling-mode behavior — unchanged for existing installs |\n| `balanced` | 50 | More active polling, want a higher per-run budget |\n| `aggressive` | 200 | High-frequency polling setups |\n\n```bash\nexport COPYTRADING_CADENCE_MODE=balanced\n```\n\nExisting installs default to `polling` — **no behavior change** unless you explicitly set this variable.\n\n> **Reactor mode note:** `cadence_mode` controls polling-mode trade budget only. In Reactor mode, each whale signal is handled individually by `_process_reactor_signal` — the per-run cap doesn't apply. If you hit `Daily trade limit reached (10/day)` in Reactor mode, raise the server-side limit via:\n> ```bash\n> curl -X PATCH \"https://api.simmer.markets/api/sdk/user/settings\" \\\n>   -H \"Authorization: Bearer $SIMMER_API_KEY\" \\\n>   -H \"Content-Type: application/json\" \\\n>   -d '{\"max_trades_per_day\": 200}'\n> ```\n\n> **Position cap:** The per-market position cap is controlled by `SIMMER_COPYTRADING_MAX_USD` (default 50). Raise it to allow larger positions per market.\n\n**Top N auto-calculation (when not specified):**\n- Balance < $50: Top 5 positions\n- Balance $50-200: Top 10 positions\n- Balance $200-500: Top 25 positions\n- Balance $500+: Top 50 positions\n\n**Polymarket Constraints:**\n- Minimum 5 shares per order\n- SDK enforces $1.00 minimum position value (filters dust positions)\n\n> ⚠️ **Start Conservative:** Begin with small amounts (`--max-usd 5-10`) and `--dry-run` to understand how the skill behaves before scaling up.\n\n## How It Works\n\n> **By default, only buys execute.** Pass `--rebalance` to also sell positions the whales have exited, or `--whale-exits` to sell only on whale exits.\n\nEach cycle the script:\n1. Fetches positions from all target wallets via Simmer API\n2. Combines using size-weighted aggregation (larger wallets = more influence)\n3. Detects conflicts (one wallet long YES, another long NO) and skips those markets\n4. Scores by conviction: positions held by 2+ wallets get full sizing, single-wallet positions get 50% sizing\n5. Filters out drifted (>30% from entry) and stale (>90% or <10% price) positions\n6. Applies Top-N filtering to concentrate on highest-conviction positions\n7. Auto-imports missing markets from Polymarket\n8. Calculates rebalance trades to match target allocations\n9. Executes trades via Simmer SDK (respects spending limits)\n10. Reports results back to user\n\n## Reactor Mode (Pro) — event-driven real-time mirroring\n\n> **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.\n\nReactor 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.\n\n### How it's different from polling mode\n\n- **Event-driven, not batched.** Each whale settlement is evaluated and acted on independently.\n- **Fixed per-event sizing.** `mirror_fraction` × whale size, capped at `max_size`. No conviction tiering, no rebalance math.\n- **Server-side watchlist filter.** Your watchlist + `min_size` are stored in Simmer's reactor config and applied on the server before events reach your skill — you only see matches.\n- **Pre-resolved signals.** The server resolves Polymarket condition IDs to Simmer market UUIDs before writing the signal — the skill receives trade-ready payloads.\n- **Two run modes.** Loop mode (default, polls every 2s) or `--once` for cron-style single poll and exit.\n- **Circuit breaker.** 5 consecutive trade failures → signals are skipped until the next success. Prevents runaway failures from draining your wallet.\n- **Server-side dedup.** Signals have a 60-second TTL in Redis and are deleted after successful execution. No local state files needed.\n- **Buys only (MVP).** Reactor currently mirrors whale **buys only** — sell signals are filtered out server-side by the relay. If a whale exits a position, reactor won't mirror the sell. Sell mirroring is planned for a future release.\n\n### Configure your reactor watchlist\n\nReactor uses Simmer-side config (not env vars), so dashboard edits take effect in seconds without restarting the skill.\n\n```bash\n# Set your watchlist via the Simmer API\ncurl -X PATCH \"https://api.simmer.markets/api/sdk/reactor/config\" \\\n  -H \"Authorization: Bearer $SIMMER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"wallets\": [\"0x1234...abcd\", \"0x5678...efgh\"],\n    \"min_size\": 1000,\n    \"max_size\": 50,\n    \"mirror_fraction\": 0.01,\n    \"daily_cap\": 100,\n    \"venue\": \"sim\",\n    \"enabled\": true\n  }'\n```\n\nFields:\n\n| Field | Meaning |\n|---|---|\n| `wallets` | Whale addresses to follow (EVM format, lowercased server-side) |\n| `min_size` | Minimum whale trade size to consider (shares) |\n| `max_size` | Cap on your mirror trade size (shares) |\n| `mirror_fraction` | Fraction of whale size to mirror (e.g. 0.01 = 1%) |\n| `daily_cap` | Max total spend per day in venue-native units |\n| `venue` | `sim` / `polymarket` / `kalshi` |\n| `enabled` | Pause reactor by setting `false` — server will stop delivering events |\n| `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. |\n\n### Run reactor mode\n\n**Recommended: cron with `--once`** — polls for pending signals once and exits. Run on a 1-minute cron for reliable, persistent coverage:\n\n```bash\n# Linux crontab\n*/1 * * * * cd /path/to/skill && python copytrading_trader.py --reactor --once --live\n\n# OpenClaw cron\nopenclaw cron add --name \"reactor-poll\" --cron \"*/1 * * * *\" --tz UTC --session isolated \\\n  --message \"Run: cd /path/to/skill && python3 copytrading_trader.py --reactor --once\"\n\n# One-off check\npython copytrading_trader.py --reactor --once\n```\n\n> **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.\n\n**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.\n\n```bash\n# With a process manager (launchd, systemd, supervisor)\npython copytrading_trader.py --reactor\n\n# Plain shell (will not auto-restart)\nnohup python copytrading_trader.py --reactor > reactor.log 2>&1 &\n```\n\nSet `REACTOR_POLL_INTERVAL_SECONDS` to tune the polling cadence (default 2s).\n\n> **Note:** Reactor mode always executes live trades (venue is set in your reactor config). Use `venue: \"sim\"` in your config to paper trade.\n\n### What happens per signal\n\n1. Skill polls `GET /api/sdk/reactor/pending` for pre-resolved whale signals\n2. Circuit breaker check: if 5+ consecutive failures in recent reactions, skip this tick\n3. For each signal: compute mirror size (`taker_size × mirror_fraction`, capped by `max_size`, floored at 5-share Polymarket minimum)\n4. If below minimum → `skipped_filter` reaction, no trade\n5. `SimmerClient.trade()` with `skill_slug=\"polymarket-copytrading\"` and `source=\"sdk:copytrading:reactor\"`\n6. On success: DELETE the signal from `/api/sdk/reactor/pending/{tx_hash}` and POST a `mirrored` reaction\n7. On failure: POST a `failed` reaction, leave signal (60s TTL clears it)\n\n### Example output\n\n```\n[reactor] price_buffer=0.020 (from config)\n[reactor] --once: single poll against /api/sdk/reactor/pending\n[reactor] 0 pending signals\n```\n\nWhen a whale trade matches your watchlist:\n\n```\n[reactor] price_buffer=0.020 (from config)\n[reactor] loop mode: polling /api/sdk/reactor/pending every 2.0s\n[reactor] 1 pending signal(s)\n[reactor] 0xbaa2bc... BUY 7067 shares on \"Will Iran strike Iraq by April 30, 2026?\"\n[reactor] mirror: 70.67 shares @ $0.673 (buffer +2.0%) → GTC order placed\n[reactor] ✅ mirrored — trade_id=a23dc52a, signal deleted\n```\n\n### Reactor venue auto-routing (v1.11+)\n\nWhen Reactor signals arrive sized above Simmer's 500 $SIM per-trade cap, the skill automatically routes them to Polymarket instead of failing silently. This lets you follow whale sizing without hitting the LMSR hard cap:\n\n```\n[reactor] 0xbaa2bc... amount 800.00 $SIM > 500 $SIM cap → routing to polymarket\n[reactor] ✅ 0xbaa2bc... mirrored 800.00 USD trade_id=a23dc52a\n```\n\n**Edge cases:**\n- **No Polymarket wallet configured**: skill falls back to a 500 $SIM-capped trade and logs the routing decision. You won't miss the signal entirely.\n- **`COPYTRADING_FORCE_SIMMER_VENUE=true`**: disables auto-routing. Signals above 500 $SIM are capped at 500 and traded on Simmer venue.\n- **Signal already targets Polymarket**: no change — auto-routing only fires on `sim` venue signals.\n\n### External wallets just work\n\nReactor 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.\n\n### When to use polling vs reactor\n\n- **Use polling** when you want portfolio-style copying: aggregate across multiple whales, rebalance to target allocations, run periodically from cron, filter drifted/stale positions. Doesn't require Pro.\n- **Use reactor** when you want real-time reaction to individual whale trades, fixed per-event sizing, and pre-resolved signals. Requires Pro.\n- **Use both** if you want: polling for your steady-state portfolio alignment + reactor for opportunistic real-time mirroring. Different flags, same skill, same API key.\n\n---\n\n## $SIM Paper Trading\n\nCopytrading supports $SIM mode — mirror whale positions using simulated money on Simmer's LMSR markets. No wallet or USDC required.\n\n```bash\n# Paper trade with $SIM (explicit)\npython copytrading_trader.py --venue sim --wallets 0x123... --live\n\n# Auto-detect: if your account has no linked wallet, $SIM is used automatically\npython copytrading_trader.py --wallets 0x123... --live\n```\n\nIn $SIM mode:\n- Trades execute on Simmer's LMSR at real Polymarket prices\n- Each market gets an independent $10K $SIM balance\n- Positions tracked in your Simmer portfolio (source: `sdk:copytrading`)\n- Whale signals still come from real Polymarket data\n\n## Running the Skill\n\n**Run a scan (dry run by default — no trades):**\n```bash\npython copytrading_trader.py\n```\n\n**Execute real trades:**\n```bash\npython copytrading_trader.py --live\n```\n\n**Check positions only:**\n```bash\npython copytrading_trader.py --positions\n```\n\n**View current config:**\n```bash\npython copytrading_trader.py --config\n```\n\n**Override wallets for one run:**\n```bash\npython copytrading_trader.py --wallets 0x123...,0x456...\n```\n\n**Full rebalance mode (includes sells):**\n```bash\npython copytrading_trader.py --rebalance\n```\n\n**Sell when whales exit positions:**\n```bash\npython copytrading_trader.py --whale-exits\n```\n\n## Reporting Results\n\nAfter each run, message the user with:\n- Current configuration (wallets, Top N, max position)\n- Number of wallets fetched and total positions found\n- Markets skipped due to conflicts\n- Trades executed (or skipped with reason)\n- Current portfolio positions\n\nExample output to share:\n```\n🐋 Copytrading Scan Complete\n\nConfiguration:\n• Following 2 wallets\n• Top 10 positions, max $50 each\n• Balance: $250.00 USDC\n\nFetched positions:\n• 0x1234...abcd: 15 positions\n• 0x5678...efgh: 22 positions\n• Combined: 28 unique markets\n• Conflicts skipped: 2\n\nTop 10 by allocation:\n1. \"Will BTC hit $100k?\" - 18.5% → BUY YES\n2. \"Trump pardons X?\" - 12.3% → BUY NO\n3. \"Fed rate cut Jan?\" - 9.8% → Already held\n...\n\nTrades executed: 4 buys ($180 total)\n• Bought 45 YES shares on \"Will BTC hit $100k?\" @ $0.82\n• Bought 120 NO shares on \"Trump pardons X?\" @ $0.15\n...\n\nNext scan in 4 hours.\n```\n\n## Example Conversations\n\n**User: \"Copytrade 0x1234...abcd\"**\n→ Run: `python copytrading_trader.py --wallets 0x1234...abcd`\n→ Report what positions that wallet has and what trades would execute\n\n**User: \"What is 0x5678...efgh holding?\"**\n→ Run: `python copytrading_trader.py --wallets 0x5678...efgh --dry-run`\n→ Show their positions without trading\n\n**User: \"Follow these wallets: 0xaaa..., 0xbbb..., 0xccc...\"**\n→ Run: `python copytrading_trader.py --wallets 0xaaa...,0xbbb...,0xccc...`\n→ Aggregate positions across all wallets, report results\n\n**User: \"Copytrade this whale but only top 5 positions\"**\n→ Run: `python copytrading_trader.py --wallets 0x... --top-n 5`\n\n**User: \"How are my positions doing?\"**\n→ Run: `python copytrading_trader.py --positions`\n→ Show current Polymarket positions with P&L\n\n**User: \"Show copytrading config\"**\n→ Run: `python copytrading_trader.py --config`\n→ Display current settings\n\n**User: \"Sell positions that whales have exited\"**\n→ Run: `python copytrading_trader.py --whale-exits`\n→ Compares your positions to whales, sells any they've closed\n\n**User: \"Do a full rebalance to match the whales\"**\n→ Run: `python copytrading_trader.py --rebalance`\n→ Includes both buys AND sells to match whale allocations\n\n## Finding Good Wallets to Follow\n\nCommon approaches:\n1. **Leaderboard tracking**: Check Polymarket leaderboards for consistent performers\n2. **Whale watchers**: Follow known profitable traders on social media\n3. **Specific strategies**: Follow wallets known for weather, politics, or crypto trades\n\nThe skill works best when:\n- Following 2-5 wallets with **overlapping strategies** (e.g. all politics-focused, or all crypto-focused)\n- Wallets have similar conviction — mixing very different traders means most positions only appear in one wallet and get reduced sizing (50%)\n- Wallets trade markets available on Polymarket\n\n### Conviction Tiers\n\nWhen following multiple wallets, positions are scored by conviction:\n\n- **High conviction** (held by 2+ wallets): full position sizing (`max_usd`)\n- **Low conviction** (held by 1 wallet): 50% position sizing\n\nHigh-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).\n\n## Troubleshooting\n\n**\"Order too small\" / \"below minimum (5)\"**\n- Polymarket requires minimum 5 shares per order\n- Increase `--max-usd` or reduce `--top-n` to concentrate into fewer positions\n\n**\"No wallets specified\"**\n- Provide wallet addresses in your message, e.g., \"copytrade 0x1234...\"\n- Or set SIMMER_COPYTRADING_WALLETS environment variable for recurring scans\n\n**\"Agent has no USDC balance\"**\n- Need USDC in your Polymarket wallet, or use `--venue sim` for $SIM paper trading\n- Check wallet is linked at simmer.markets/dashboard\n\n**\"Conflict skipped\"**\n- Wallets disagree on this market (one long YES, other long NO)\n- Markets with net position < 10% are skipped\n\n**\"All N positions filtered (X conflicts, Y drifted, Z stale)\"**\n- All whale positions were removed by safety filters\n- Try different target wallets, or reduce to 1 wallet to disable conviction scoring\n- Drift filter skips positions where price moved >30% from whale's entry\n- Stale filter skips near-resolved markets (price >90% or <10%)\n\n**\"Insufficient balance\"**\n- Not enough USDC for all trades\n- Reduce SIMMER_COPYTRADING_TOP_N or SIMMER_COPYTRADING_MAX_USD\n\n**\"Market could not be imported\"**\n- Some markets may not be importable (resolved, private, etc.)\n- These are skipped automatically\n\n**\"External wallet requires a pre-signed order\"**\n- `WALLET_PRIVATE_KEY` is not set in the environment\n- The SDK signs orders automatically when this env var is present — no manual signing code needed\n- Fix: `export WALLET_PRIVATE_KEY=0x<your-polymarket-wallet-private-key>`\n- Do NOT attempt to sign orders manually or modify the skill code — the SDK handles it\n\n**\"Balance shows $0 but I have funds on Polygon\"**\n- Polymarket V2 (live 2026-04-28) uses **pUSD** (PolyUSD, 1:1 backed by USDC.e). If your wallet holds USDC.e, migrate at [simmer.markets/dashboard](https://simmer.markets/dashboard) with one click (~30s)\n- If you bridged native USDC (Circle), swap to USDC.e first, then migrate to pUSD\n- Full migration guide: [docs.simmer.markets/v2-migration](https://docs.simmer.markets/v2-migration)\n\nFile v1.12.0:_meta.json\n\n{\n  \"ownerId\": \"kn7axnp7bzqsf5fkx0z8px7han7zyq1x\",\n  \"slug\": \"polymarket-copytrading\",\n  \"version\": \"1.12.0\",\n  \"publishedAt\": 1782439112753\n}\n\nFile v1.12.0:DISCLAIMER.md\n\n# Disclaimer\n\nThis skill is a **framework**, not a production trading system. Read this\nin full before connecting it to a wallet with real funds.\n\n## No financial advice\n\nNothing in this skill constitutes financial, investment, or trading\nadvice. The default strategy implemented here is a starting point, not a\ntested edge. Suitability for any account size or risk tolerance is your\nresponsibility to assess.\n\n## Default parameters are not validated\n\nDefault parameters are calibrated for testing the plumbing, not for live\nprofit. They have not been validated to produce positive returns under\ncurrent market conditions. Run paper mode for an extended period before\nscaling beyond default position sizes.\n\n## Automated trading carries irreversible risk\n\nWhen this skill runs with `--live`, it places real on-chain orders.\nOn-chain trades cannot be recalled. Strategy errors, signal lag, market\nregime shifts, and operator misconfiguration can produce losses\nexceeding any specific position size.\n\n## Risk monitoring may not apply to all market types\n\nStop-loss and take-profit monitors run on a fixed schedule. Markets that\nresolve faster than the monitor cycle cannot be exited automatically.\nPosition sizing is the only risk control on these markets — set it\nconservatively.\n\n## Use of this skill is at your own risk\n\nBy installing and running this skill you agree that the authors are not\nliable for any losses, direct or indirect, that arise from its use. This\napplies regardless of skill provenance — official Simmer skills,\ncommunity skills, and skills imported from external repositories all\ncarry this same disclaimer.\n\n## Where to learn more before going live\n\n- The skill's own `SKILL.md` documents the strategy and parameters\n- Your trading venue's documentation covers fee structure, order types,\n  and resolution rules\n- Simmer SDK documentation covers paper mode, dry-run flags, and\n  position monitoring\n\nFile v1.12.0:skill-card.md\n\n## Description: <br>\nMirror 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. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[simmer](https://clawhub.ai/user/simmer) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal users and developers use this skill to configure and run automated Polymarket copytrading workflows, including dry-run scans, paper trading with $SIM, account status checks, and optional live trade execution. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill can place automated real-money trades when live Polymarket execution is enabled. <br>\nMitigation: Start with dry-run or $SIM paper mode, keep position and per-run caps low, and enable live execution only after reviewing the s\n\nArchive v1.11.2: 10 files, 34463 bytes\n\nFiles: clawhub.json (1951b), copytrading_trader.py (52427b), DISCLAIMER.md (1925b), requirements.txt (33b), scripts/status.py (4930b), skill-card.md (2735b), SKILL.md (21507b), tests/__init__.py (0b), tests/test_venue_routing.py (14531b), _meta.json (142b)\n\nArchive v1.11.1: 8 files, 29762 bytes\n\nFiles: clawhub.json (1951b), copytrading_trader.py (50679b), DISCLAIMER.md (1925b), requirements.txt (33b), scripts/status.py (4930b), skill-card.md (2696b), SKILL.md (21507b), _meta.json (142b)\n\nArchive v1.10.2: 6 files, 24614 bytes\n\nFiles: clawhub.json (1449b), copytrading_trader.py (45012b), requirements.txt (33b), scripts/status.py (4930b), SKILL.md (18949b), _meta.json (142b)\n\nArchive v1.10.1: 6 files, 24256 bytes\n\nFiles: clawhub.json (1441b), copytrading_trader.py (43796b), requirements.txt (33b), scripts/status.py (4930b), SKILL.md (18949b), _meta.json (142b)\n\nArchive v1.9.3: 6 files, 24216 bytes\n\nFiles: clawhub.json (1441b), copytrading_trader.py (43796b), requirements.txt (33b), scripts/status.py (4930b), SKILL.md (18795b), _meta.json (141b)","readmeExcerpt":"Skill: polymarket-copytrading Owner: simmer Summary: 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. Tags: latest:1.12.4 Version history: v1.12.4 | 2026-09-23T03:10:45.894Z | auto - Bumped version to 1.12.4. - Minor documentation updates in SKILL.md. - Removed deprecated ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"pip install -U 'simmer-sdk>=0.9.19'"},{"language":"bash","snippet":"# Check account balance and positions\npython scripts/status.py\n\n# Detailed position list\npython scripts/status.py --positions"},{"language":"text","snippet":"User: \"Copytrade this wallet: 0x1234...abcd\"\nUser: \"What positions does 0x5678...efgh have?\"\nUser: \"Follow these whales: 0xaaa..., 0xbbb...\""},{"language":"bash","snippet":"python copytrading_trader.py --wallets 0x1234...abcd\npython copytrading_trader.py --wallets 0xaaa...,0xbbb... --dry-run"},{"language":"bash","snippet":"export COPYTRADING_CADENCE_MODE=balanced"},{"language":"bash","snippet":"> curl -X PATCH \"https://api.simmer.markets/api/sdk/user/settings\" \\\n>   -H \"Authorization: Bearer $SIMMER_API_KEY\" \\\n>   -H \"Content-Type: application/json\" \\\n>   -d '{\"max_trades_per_day\": 200}'\n>"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: polymarket-copytrading\ndescription: 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.\nmetadata:\n  author: Simmer (@simmer_markets)\n  version: \"1.12.4\"\n  displayName: Polymarket Copytrading\n  difficulty: beginner\n---\n# Polymarket Copytrading\n\nMirror positions from successful Polymarket traders using the Simmer SDK. Two modes share the same skill, use whichever fits your strategy.\n\n> 🚨 **Framework, not a production trading system.** Read [DISCLAIMER.md](./DISCLAIMER.md) before connecting to a wallet with real funds. Per-position cap defaults to $50; per-run cap defaults to 10 trades. Use `$SIM` paper-mode to validate any new whale selection before scaling to real USDC.\n\n> **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.\n\n| | **Polling mode** (free) | **Reactor mode** (Pro) |\n|---|---|---|\n| Entrypoint | `copytrading_trader.py` | `copytrading_trader.py --reactor` |\n| Cadence | Batch scan, runs on cron or manual | Polls every 2s for pre-resolved whale signals |\n| Latency | Minutes (Polymarket Data API polling) | Seconds (Simmer detects events in real-time, pre-confirmation) |\n| 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 |\n| Best for | Portfolio-aware, multi-whale, periodic scans | Real-time reaction to specific whales as they trade |\n| Requires | `SIMMER_API_KEY` | `SIMMER_API_KEY` + Simmer Pro plan |\n\n## Setup Flow\n\nWhen user asks to install or configure this skill:\n\n1. **Install the Simmer SDK** (version 0.9.19 or newer — reactor mode requires it)\n   ```bash\n   pip install -U 'simmer-sdk>=0.9.19'\n   ```\n\n2. **Ask for Simmer API key**\n   - They can get it from simmer.markets/dashboard → SDK tab\n   - Store in environment as `SIMMER_API_KEY`\n\n3. **Ask for wallet private key** (required for live trading on Polymarket)\n   - This is the private key for their Polymarket wallet (the wallet that holds USDC)\n   - Store in environment as `WALLET_PRIVATE_KEY`\n   - The SDK uses this to sign orders client-side automatically — no manual signing needed\n   - Not needed for $SIM paper trading\n\n4. **Ask about settings** (or confirm defaults)\n   - Target wallets: Whale addresses to copy\n   - Max per position: Amount per trade (default $50)\n   - Top N positions: How many positions to track (auto-calculated from balance)\n   - Max trades per run: Safety cap (default 10)\n\n## When to Use This Skill\n\nUse this skill when the user wants to:\n- Copytrade whale wallets on Polymarket\n- Paper trade (copytrade with $SIM) to test strategies without real money"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7axnp7bzqsf5fkx0z8px7han7zyq1x\",\n  \"slug\": \"polymarket-copytrading\",\n  \"version\": \"1.12.4\",\n  \"publishedAt\": 1790133045894\n}"},{"path":"DISCLAIMER.md","content":"# Disclaimer\n\nThis skill is a **framework**, not a production trading system. Read this\nin full before connecting it to a wallet with real funds.\n\n## No financial advice\n\nNothing in this skill constitutes financial, investment, or trading\nadvice. The default strategy implemented here is a starting point, not a\ntested edge. Suitability for any account size or risk tolerance is your\nresponsibility to assess.\n\n## Default parameters are not validated\n\nDefault parameters are calibrated for testing the plumbing, not for live\nprofit. They have not been validated to produce positive returns under\ncurrent market conditions. Run paper mode for an extended period before\nscaling beyond default position sizes.\n\n## Automated trading carries irreversible risk\n\nWhen this skill runs with `--live`, it places real on-chain orders.\nOn-chain trades cannot be recalled. Strategy errors, signal lag, market\nregime shifts, and operator misconfiguration can produce losses\nexceeding any specific position size.\n\n## Risk monitoring may not apply to all market types\n\nStop-loss and take-profit monitors run on a fixed schedule. Markets that\nresolve faster than the monitor cycle cannot be exited automatically.\nPosition sizing is the only risk control on these markets — set it\nconservatively.\n\n## Use of this skill is at your own risk\n\nBy installing and running this skill you agree that the authors are not\nliable for any losses, direct or indirect, that arise from its use. This\napplies regardless of skill provenance — official Simmer skills,\ncommunity skills, and skills imported from external repositories all\ncarry this same disclaimer.\n\n## Where to learn more before going live\n\n- The skill's own `SKILL.md` documents the strategy and parameters\n- Your trading venue's documentation covers fee structure, order types,\n  and resolution rules\n- Simmer SDK documentation covers paper mode, dry-run flags, and\n  position monitoring"},{"path":"skill-card.md","content":"## Description:\n\nMirror 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.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[simmer](https://clawhub.ai/user/simmer)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and agents use this skill to inspect Polymarket trader positions, configure whale wallets to follow, run dry-run or paper copytrading checks, and optionally execute live mirrored trades with configured caps.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can place real-money trades when live mode and credentials are configured.\n\nMitigation: Use dry-run or $SIM paper mode first, keep per-position and per-run caps small, and review proposed trades before scaling to real USDC.\n\nRisk: Automatic venue routing can convert above-cap simulated Reactor signals to Polymarket orders.\n\nMitigation: Set COPYTRADING_FORCE_SIMMER_VENUE=true when simulated-only execution is required.\n\nRisk: Unattended live runs can continue acting on new whale signals without active review.\n\nMitigation: Avoid cron, loop, or nohup live execution until behavior, wallet setup, and caps have been reviewed.\n\nRisk: External-wallet trading depends on WALLET_PRIVATE_KEY, which is highly sensitive.\n\nMitigation: Store the private key only in a protected environment and avoid exposing it in logs, prompts, shell history, or shared configuration.\n\nRisk: Sell behavior and rebalance options can close positions as well as buy mirrored positions.\n\nMitigation: Review sell-related flags and defaults before live use, and confirm whether buy-only, whale-exit, or full-rebalance behavior is intended.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/simmer/skills/polymarket-copytrading)\n- [Simmer API](https://api.simmer.markets)\n- [Simmer dashboard](https://simmer.markets/dashboard)\n- [Simmer V2 migration guide](https://docs.simmer.markets/v2-migration)\n- [predicting.top](https://predicting.top)\n- [alphawhale.trade](https://alphawhale.trade)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown and terminal-oriented status summaries with inline shell commands and configuration values]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May run dry-run, paper, or live trading commands depending on user configuration; live trading requires Simmer credentials and, for external wallets, a wallet private key.]\n\n## Skill Version(s):\n\n1.12.4 (source: frontmatter and release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."},{"path":"clawhub.json","content":"{\n  \"emoji\": \"\\ud83d\\udc0b\",\n  \"primaryEnv\": \"SIMMER_API_KEY\",\n  \"requires\": {\n    \"env\": [\n      \"SIMMER_API_KEY\"\n    ],\n    \"pip\": [\n      \"simmer-sdk>=0.11.1\"\n    ]\n  },\n  \"envVars\": [\n    {\n      \"name\": \"SIMMER_API_KEY\",\n      \"required\": true,\n      \"description\": \"Your Simmer SDK API key \\u2014 get from simmer.markets/dashboard\"\n    },\n    {\n      \"name\": \"WALLET_PRIVATE_KEY\",\n      \"required\": false,\n      \"description\": \"Only needed for external-wallet self-custody trading. Not required when using managed wallets.\"\n    }\n  ],\n  \"cron\": null,\n  \"autostart\": false,\n  \"automaton\": {\n    \"managed\": true,\n    \"entrypoint\": \"copytrading_trader.py\"\n  },\n  \"tunables\": [\n    {\n      \"env\": \"SIMMER_COPYTRADING_WALLETS\",\n      \"type\": \"string\",\n      \"default\": \"\",\n      \"label\": \"Whale wallet addresses (comma-separated)\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_MAX_USD\",\n      \"type\": \"number\",\n      \"default\": 50,\n      \"range\": [\n        1,\n        200\n      ],\n      \"step\": 5,\n      \"label\": \"Max bet per trade\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_TOP_N\",\n      \"type\": \"number\",\n      \"default\": 5,\n      \"range\": [\n        1,\n        20\n      ],\n      \"step\": 1,\n      \"label\": \"Positions to track\"\n    },\n    {\n      \"env\": \"SIMMER_COPYTRADING_MAX_TRADES\",\n      \"type\": \"number\",\n      \"default\": 5,\n      \"range\": [\n        1,\n        20\n      ],\n      \"step\": 1,\n      \"label\": \"Max trades per run\"\n    },\n    {\n      \"env\": \"COPYTRADING_CADENCE_MODE\",\n      \"type\": \"string\",\n      \"default\": \"polling\",\n      \"enum\": [\"polling\", \"balanced\", \"aggressive\"],\n      \"label\": \"Cadence mode — set higher for more active polling (polling=10 trades/run, balanced=50, aggressive=200)\"\n    },\n    {\n      \"env\": \"COPYTRADING_FORCE_SIMMER_VENUE\",\n      \"type\": \"string\",\n      \"default\": \"\",\n      \"label\": \"Force Simmer ($SIM) venue — set to 'true' to disable auto-routing above-cap trades to Polymarket\"\n    }\n  ]\n}"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1881,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T05:02:09.073Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T05:02:09.073Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:07:38.292Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}