{"id":50492606,"url":"https://github.com/mjunaidca/polymarket-skills","last_synced_at":"2026-06-02T04:02:40.972Z","repository":{"id":340743309,"uuid":"1167337539","full_name":"mjunaidca/polymarket-skills","owner":"mjunaidca","description":"Composable Agent Skills for Polymarket prediction market trading. Paper-trading-first, security-audited. Works with Claude Code, OpenClaw, NanoClaw, Codex, Cursor.","archived":false,"fork":false,"pushed_at":"2026-02-26T09:20:49.000Z","size":137,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-26T14:44:15.891Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mjunaidca.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY-AUDIT.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-26T07:25:15.000Z","updated_at":"2026-02-26T09:20:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mjunaidca/polymarket-skills","commit_stats":null,"previous_names":["mjunaidca/polymarket-skills"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mjunaidca/polymarket-skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjunaidca%2Fpolymarket-skills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjunaidca%2Fpolymarket-skills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjunaidca%2Fpolymarket-skills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjunaidca%2Fpolymarket-skills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mjunaidca","download_url":"https://codeload.github.com/mjunaidca/polymarket-skills/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjunaidca%2Fpolymarket-skills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33805345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T04:02:40.413Z","updated_at":"2026-06-02T04:02:40.967Z","avatar_url":"https://github.com/mjunaidca.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Polymarket AI Trading Skills\n\nComposable [Agent Skills](https://agentskills.io/specification) for Polymarket prediction market trading. Paper-trading-first, security-audited, works with Claude Code, OpenClaw, NanoClaw, Codex, Cursor, and any SKILL.md-compatible agent.\n\n## Skills\n\n| Skill | What It Does | Auth | Risk |\n|-------|-------------|------|------|\n| **polymarket-scanner** | Browse, search, and explore live markets | None | Zero |\n| **polymarket-analyzer** | Detect edges: arbitrage, momentum, correlation analysis | None | Zero |\n| **polymarket-monitor** | Price alerts and position monitoring | None | Zero |\n| **polymarket-paper-trader** | Simulate trades against live prices, portfolio health checks | None | Zero |\n| **polymarket-strategy-advisor** | Trading methodology, recommendations, backtesting | None | Low |\n| **polymarket-live-executor** | Execute real trades (wallet + explicit human opt-in) | L2 Wallet | Medium |\n\n## Install\n\n### One Command (All Skills)\n```bash\nnpx skills add mjunaidca/polymarket-skills\n```\n\n### Individual Skills\n```bash\nnpx skills add mjunaidca/polymarket-skills --skill polymarket-scanner\nnpx skills add mjunaidca/polymarket-skills --skill polymarket-analyzer\nnpx skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader\n# etc.\n```\n\n### Manual\nCopy any skill folder to `~/.claude/skills/` (Claude Code) or `~/.agents/skills/` (other agents).\n\n### Dependencies\n```bash\npip install py-clob-client requests\n```\n\n## Quick Start\n\nOnce installed, talk to your agent naturally:\n\n- *\"Scan Polymarket for interesting markets\"* -- triggers polymarket-scanner\n- *\"Find trading opportunities\"* -- triggers polymarket-analyzer\n- *\"Set up a paper trading portfolio with $1000\"* -- triggers polymarket-paper-trader\n- *\"What should I trade?\"* -- triggers polymarket-strategy-advisor\n- *\"Check my portfolio health\"* -- triggers polymarket-paper-trader (health_check)\n- *\"Am I ready to go live?\"* -- triggers polymarket-strategy-advisor (backtest --live-check)\n- *\"Check correlation risk\"* -- triggers polymarket-analyzer (correlation_tracker)\n\n### Full Pipeline\n\n```bash\nsource ~/.venv/bin/activate\n\n# 1. Initialize portfolio\npython polymarket-paper-trader/scripts/paper_engine.py --action init --balance 1000\n\n# 2. Scan markets\npython polymarket-scanner/scripts/scan_markets.py --limit 50 --min-volume 10000\n\n# 3. Find edges\npython polymarket-analyzer/scripts/find_edges.py --min-edge 0.02 --limit 500\n\n# 4. Scan momentum\npython polymarket-analyzer/scripts/momentum_scanner.py --min-volume 10000\n\n# 5. Get trade recommendations\npython polymarket-strategy-advisor/scripts/advisor.py --top 5 \\\n  --portfolio-db ~/.polymarket-paper/portfolio.db\n\n# 6. Paper trade\npython polymarket-paper-trader/scripts/paper_engine.py \\\n  --action buy --token TOKEN_ID --side YES --size 50 --reason \"Momentum signal\"\n\n# 7. Check portfolio health (one command)\npython polymarket-paper-trader/scripts/health_check.py\n\n# 8. Check correlation risk\npython polymarket-analyzer/scripts/correlation_tracker.py\n\n# 9. Review performance\npython polymarket-strategy-advisor/scripts/backtest.py\n\n# 10. Daily review\npython polymarket-strategy-advisor/scripts/daily_review.py --days 7\n```\n\n## Architecture\n\n```\nScanner --\u003e Analyzer --\u003e Strategy Advisor --\u003e Paper Trader --\u003e Live Executor\n(find)      (evaluate)    (recommend)          (simulate)       (execute)\n```\n\n### polymarket-scanner/ -- Market Data (Read-Only)\n\n| Script | Purpose | Key Args |\n|--------|---------|----------|\n| `scan_markets.py` | Browse/search active markets from Gamma API | `--limit 100 --min-volume 10000 --category TEXT --search TEXT` |\n| `get_orderbook.py` | Full order book for a specific token | `--token-id ID --depth 10` |\n| `get_prices.py` | Current midpoint, spread, last trade | `--token-id ID (repeatable) --market-slug SLUG` |\n\n### polymarket-analyzer/ -- Edge Detection\n\n| Script | Purpose | Key Args |\n|--------|---------|----------|\n| `find_edges.py` | Arbitrage (YES+NO \u003c $1), wide spread, overpriced detection | `--min-edge 0.02 --limit 500` |\n| `momentum_scanner.py` | Volume surges, price momentum, liquidity changes | `--min-volume 10000 --limit 300` |\n| `analyze_orderbook.py` | Depth analysis, bid-ask imbalance, liquidity concentration | `--token-id ID --depth 10` |\n| `correlation_tracker.py` | Detects hidden correlated exposure in portfolio | `--threshold 0.15 --json` |\n\n### polymarket-monitor/ -- Price Monitoring\n\n| Script | Purpose | Key Args |\n|--------|---------|----------|\n| `monitor_prices.py` | Multi-token polling with threshold alerts (JSON) | `--token-id ID --interval 30 --threshold 5.0` |\n| `watch_market.py` | Continuous single-market snapshots | `--token-id ID --interval 15` |\n\n### polymarket-paper-trader/ -- Simulation Engine\n\n| Script | Purpose | Key Args |\n|--------|---------|----------|\n| `paper_engine.py` | Core engine: init, buy, close, portfolio, trades | `--action init/buy/close/portfolio/trades` |\n| `execute_paper.py` | Execute structured strategy recommendations | `--recommendation '{\"token_id\":...}' --dry-run` |\n| `portfolio_report.py` | Full analytics: Sharpe, Sortino, drawdown | `--json` |\n| `health_check.py` | One-command session start: live prices, stops, drawdown, risk | `--json` (exit codes: 0=GREEN, 1=YELLOW, 2=RED) |\n\n### polymarket-strategy-advisor/ -- Trading Methodology\n\n| Script | Purpose | Key Args |\n|--------|---------|----------|\n| `advisor.py` | Scan, score, size trade recommendations | `--top 5 --portfolio-db PATH` |\n| `backtest.py` | Performance analysis + live-readiness assessment | `--live-check --days 30 --json` |\n| `daily_review.py` | Win/loss breakdown, strategy analysis, suggestions | `--days 7` |\n\n### polymarket-live-executor/ -- Real Trading (4 Safety Layers)\n\n| Script | Purpose | Key Args |\n|--------|---------|----------|\n| `execute_live.py` | Place real orders (requires env vars + human \"yes\") | `--token-id ID --side BUY --size 5 --price 0.60` |\n| `check_positions.py` | Wallet balance, open orders, trade history | `--balance --orders --trades` |\n| `setup_wallet.py` | Create burner wallet, verify config, check balance | `--create / --verify / --check-balance` |\n\n## CLAUDE.md Constitution\n\nThe repo includes a [CLAUDE.md](CLAUDE.md) that serves as the agent's trading constitution:\n\n- **9 non-negotiable rules** (edge required, paper default, risk is law, human confirms live trades, etc.)\n- **Authoritative risk limits** resolving all cross-file conflicts (graduated drawdown at 10/15/20%)\n- **Daily workflow** (14-step session start -\u003e scan -\u003e evaluate -\u003e execute -\u003e review)\n- **Paper-to-live prerequisites** (20+ trades, \u003e55% win rate, Sharpe \u003e0.5, drawdown \u003c15%)\n- **Experience tiers** for live capital progression ($25 -\u003e $100 -\u003e $500 -\u003e $2,000+)\n\nWhen CLAUDE.md conflicts with any SKILL.md, CLAUDE.md wins.\n\n## Risk Management\n\n### Risk Limits (from CLAUDE.md)\n\n| Parameter | Limit |\n|-----------|-------|\n| Max position size | 10% of portfolio (5% if confidence \u003c 0.7, 2% for news, 1% for new strategy) |\n| Max concurrent positions | 5 |\n| Max single market exposure | 20% of portfolio |\n| Daily loss halt | 5% of portfolio |\n| Weekly loss halt | 10% of portfolio |\n| Graduated drawdown | 10% -\u003e reduce 50%, 15% -\u003e reduce 75%, 20% -\u003e halt all |\n\n### Correlation Detection\n\nThe `correlation_tracker.py` groups positions by topic and detects hidden correlation:\n\n```\n$ python polymarket-analyzer/scripts/correlation_tracker.py\n\n  \u003e Cluster: Insider Trading  (3 positions)  Exposure: $90.50 (9.4%)\n    Correlation reason: shared qualifier: insider trading\n    - YES $48.74  Will Axiom be accused of insider trading?\n    - YES $23.90  Will MEXC be accused of insider trading?\n    - YES $17.86  Will Robinhood be accused of insider trading?\n\n  Diversification Score:  65/100  GOOD\n```\n\n### Portfolio Health Check\n\nThe `health_check.py` runs the full session-start workflow in one command:\n\n```\n$ python polymarket-paper-trader/scripts/health_check.py\n\n  Status: [RED]    Action required\n  Total Value:  $966.43    Drawdown: 3.36%\n  Stops Triggered: 2\n  [HIGH] Stop-loss triggered for MEXC insider trading\n  [HIGH] Stop-loss triggered for Robinhood insider trading\n```\n\n### Live-Readiness Assessment\n\nThe `backtest.py --live-check` tells you when you're ready for real money:\n\n```\n$ python polymarket-strategy-advisor/scripts/backtest.py --live-check\n\n  Live-Readiness Assessment: NOT READY (1/4 criteria met)\n  [FAIL] Closed trades \u003e= 20        actual: 0\n  [FAIL] Win rate \u003e 55%             actual: 0.0%\n  [FAIL] Sharpe ratio \u003e 0.5         actual: 0.0\n  [PASS] Max drawdown \u003c 15%         actual: 0.0%\n```\n\n## Going Live\n\n### Prerequisites\n\n1. 20+ closed paper trades with \u003e55% win rate, Sharpe \u003e0.5, drawdown \u003c15%\n2. A burner wallet (never your main wallet) funded with USDC on Polygon\n3. Environment variables configured\n\n### Setup\n\n```bash\ncd polymarket-live-executor\n\n# Create a burner wallet\npython scripts/setup_wallet.py --create\n\n# Fund it: send $25 USDC + 0.1 MATIC on Polygon\n\n# Configure\ncp .env.example .env \u0026\u0026 chmod 600 .env\n# Edit .env with your private key\n\n# Verify\nsource .env\npython scripts/setup_wallet.py --verify\npython scripts/setup_wallet.py --check-balance\n```\n\n### Experience Tiers\n\n| Level | Max Wallet | Max Per Trade | Daily Loss Limit |\n|-------|-----------|---------------|------------------|\n| First time | $25 | $5 | $10 |\n| Learning | $100 | $10 | $25 |\n| Experienced | $500 | $50 | $100 |\n| Advanced | $2,000+ | $200 | $500 |\n\n### Safety Layers\n\n1. **Paper-first**: Must prove edge in simulation before going live\n2. **Env var gate**: `POLYMARKET_CONFIRM=true` required for any execution\n3. **Human-in-the-loop**: Every trade shows full details, waits for \"yes\"\n4. **Position caps**: Hard limits on size, daily loss, and concentration\n\n## APIs Used\n\n| API | Endpoint | Auth | Usage |\n|-----|----------|------|-------|\n| Gamma API | `gamma-api.polymarket.com` | None | Market metadata, search |\n| CLOB API | `clob.polymarket.com` | None (read) / L2 (trade) | Prices, orderbooks, trading |\n\nNo official Polymarket testnet exists. The paper trading engine simulates execution against real live prices.\n\n## Data Storage\n\n| Location | Contents |\n|----------|----------|\n| `~/.polymarket-paper/portfolio.db` | Paper trading portfolio (SQLite) |\n| `~/.polymarket-live/trades.log` | Live trade log |\n| `~/.polymarket-paper/` | All paper trading data |\n\n## Security\n\n- Full security audit: [SECURITY-AUDIT.md](SECURITY-AUDIT.md) (14 findings, all HIGH/MEDIUM fixed)\n- All DB queries use parameterized statements (no SQL injection)\n- Market data treated as untrusted (prompt injection defense)\n- Private keys never logged, displayed, or echoed\n- `.env` files gitignored; `.env.example` provided as template\n\n## Disclaimer\n\n- These skills provide analytical tools and a paper trading simulator\n- Not financial advice. Past performance does not predict future results\n- Prediction market trading involves risk of total loss\n- Always paper trade new strategies before risking real capital\n- The authors are not responsible for any trading losses\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjunaidca%2Fpolymarket-skills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmjunaidca%2Fpolymarket-skills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjunaidca%2Fpolymarket-skills/lists"}