Skip to content
Back to search

polymarket-skills

Composable Agent Skills for Polymarket prediction market trading. Paper-trading-first, security-audited. Works with Claude Code, OpenClaw, NanoClaw, Codex, Cursor.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mjunaidca--polymarket-skills/badge.svg)](/listings/mjunaidca--polymarket-skills)

HTML

<a href="/listings/mjunaidca--polymarket-skills"><img src="/api/listings/mjunaidca--polymarket-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

One Command (All Skills)

npx skills add mjunaidca/polymarket-skills

Individual Skills

npx skills add mjunaidca/polymarket-skills --skill polymarket-scanner
npx skills add mjunaidca/polymarket-skills --skill polymarket-analyzer
npx skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader
# etc.

Manual

Copy any skill folder to `~/.claude/skills/` (Claude Code) or `~/.agents/skills/` (other agents).

Dependencies

pip install py-clob-client requests

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 289 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Polymarket AI Trading Skills
  2. Composable [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.
  3. ## Skills
  4. | Skill | What It Does | Auth | Risk |
  5. |-------|-------------|------|------|
  6. | **polymarket-scanner** | Browse, search, and explore live markets | None | Zero |
  7. | **polymarket-analyzer** | Detect edges: arbitrage, momentum, correlation analysis | None | Zero |
  8. | **polymarket-monitor** | Price alerts and position monitoring | None | Zero |
  9. | **polymarket-paper-trader** | Simulate trades against live prices, portfolio health checks | None | Zero |
  10. | **polymarket-strategy-advisor** | Trading methodology, recommendations, backtesting | None | Low |
  11. | **polymarket-live-executor** | Execute real trades (wallet + explicit human opt-in) | L2 Wallet | Medium |
  12. ## Install
  13. ### One Command (All Skills)
  14. ```bash
  15. npx skills add mjunaidca/polymarket-skills
  16. ```
  17. ### Individual Skills
  18. ```bash
  19. npx skills add mjunaidca/polymarket-skills --skill polymarket-scanner
  20. npx skills add mjunaidca/polymarket-skills --skill polymarket-analyzer
  21. npx skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader
  22. # etc.
  23. ```
  24. ### Manual
  25. Copy any skill folder to `~/.claude/skills/` (Claude Code) or `~/.agents/skills/` (other agents).
  26. ### Dependencies
  27. ```bash
  28. pip install py-clob-client requests
  29. ```
  30. ## Quick Start
  31. Once installed, talk to your agent naturally:
  32. - *"Scan Polymarket for interesting markets"* -- triggers polymarket-scanner
  33. - *"Find trading opportunities"* -- triggers polymarket-analyzer
  34. - *"Set up a paper trading portfolio with $1000"* -- triggers polymarket-paper-trader
  35. - *"What should I trade?"* -- triggers polymarket-strategy-advisor
  36. - *"Check my portfolio health"* -- triggers polymarket-paper-trader (health_check)
  37. - *"Am I ready to go live?"* -- triggers polymarket-strategy-advisor (backtest --live-check)
  38. - *"Check correlation risk"* -- triggers polymarket-analyzer (correlation_tracker)
  39. ### Full Pipeline
  40. ```bash
  41. source ~/.venv/bin/activate
  42. # 1. Initialize portfolio
  43. python polymarket-paper-trader/scripts/paper_engine.py --action init --balance 1000
  44. # 2. Scan markets
  45. python polymarket-scanner/scripts/scan_markets.py --limit 50 --min-volume 10000
  46. # 3. Find edges
  47. python polymarket-analyzer/scripts/find_edges.py --min-edge 0.02 --limit 500
  48. # 4. Scan momentum
  49. python polymarket-analyzer/scripts/momentum_scanner.py --min-volume 10000
  50. # 5. Get trade recommendations
  51. python polymarket-strategy-advisor/scripts/advisor.py --top 5 \
  52. --portfolio-db ~/.polymarket-paper/portfolio.db
  53. # 6. Paper trade
  54. python polymarket-paper-trader/scripts/paper_engine.py \
  55. --action buy --token TOKEN_ID --side YES --size 50 --reason "Momentum signal"
  56. # 7. Check portfolio health (one command)
  57. python polymarket-paper-trader/scripts/health_check.py
  58. # 8. Check correlation risk
  59. python polymarket-analyzer/scripts/correlation_tracker.py
  60. # 9. Review performance
  61. python polymarket-strategy-advisor/scripts/backtest.py
  62. # 10. Daily review
  63. python polymarket-strategy-advisor/scripts/daily_review.py --days 7
  64. ```
  65. ## Architecture
  66. ```
  67. Scanner --> Analyzer --> Strategy Advisor --> Paper Trader --> Live Executor
  68. (find) (evaluate) (recommend) (simulate) (execute)
  69. ```
  70. ### polymarket-scanner/ -- Market Data (Read-Only)
  71. | Script | Purpose | Key Args |
  72. |--------|---------|----------|
  73. | `scan_markets.py` | Browse/search active markets from Gamma API | `--limit 100 --min-volume 10000 --category TEXT --search TEXT` |
  74. | `get_orderbook.py` | Full order book for a specific token | `--token-id ID --depth 10` |
  75. | `get_prices.py` | Current midpoint, spread, last trade | `--token-id ID (repeatable) --market-slug SLUG` |
  76. ### polymarket-analyzer/ -- Edge Detection
  77. | Script | Purpose | Key Args |
  78. |--------|---------|----------|
  79. | `find_edges.py` | Arbitrage (YES+NO < $1), wide spread, overpriced detection | `--min-edge 0.02 --limit 500` |
  80. | `momentum_scanner.py` | Volume surges, price momentum, liquidity changes | `--min-volume 10000 --limit 300` |
  81. | `analyze_orderbook.py` | Depth analysis, bid-ask imbalance, liquidity concentration | `--token-id ID --depth 10` |
  82. | `correlation_tracker.py` | Detects hidden correlated exposure in portfolio | `--threshold 0.15 --json` |
  83. ### polymarket-monitor/ -- Price Monitoring
  84. | Script | Purpose | Key Args |
  85. |--------|---------|----------|
  86. | `monitor_prices.py` | Multi-token polling with threshold alerts (JSON) | `--token-id ID --interval 30 --threshold 5.0` |
  87. | `watch_market.py` | Continuous single-market snapshots | `--token-id ID --interval 15` |
  88. ### polymarket-paper-trader/ -- Simulation Engine
  89. | Script | Purpose | Key Args |
  90. |--------|---------|----------|
  91. | `paper_engine.py` | Core engine: init, buy, close, portfolio, trades | `--action init/buy/close/portfolio/trades` |
  92. | `execute_paper.py` | Execute structured strategy recommendations | `--recommendation '{"token_id":...}' --dry-run` |
  93. | `portfolio_report.py` | Full analytics: Sharpe, Sortino, drawdown | `--json` |
  94. | `health_check.py` | One-command session start: live prices, stops, drawdown, risk | `--json` (exit codes: 0=GREEN, 1=YELLOW, 2=RED) |
  95. ### polymarket-strategy-advisor/ -- Trading Methodology
  96. | Script | Purpose | Key Args |
  97. |--------|---------|----------|
  98. | `advisor.py` | Scan, score, size trade recommendations | `--top 5 --portfolio-db PATH` |
  99. | `backtest.py` | Performance analysis + live-readiness assessment | `--live-check --days 30 --json` |
  100. | `daily_review.py` | Win/loss breakdown, strategy analysis, suggestions | `--days 7` |
  101. ### polymarket-live-executor/ -- Real Trading (4 Safety Layers)
  102. | Script | Purpose | Key Args |
  103. |--------|---------|----------|
  104. | `execute_live.py` | Place real orders (requires env vars + human "yes") | `--token-id ID --side BUY --size 5 --price 0.60` |
  105. | `check_positions.py` | Wallet balance, open orders, trade history | `--balance --orders --trades` |
  106. | `setup_wallet.py` | Create burner wallet, verify config, check balance | `--create / --verify / --check-balance` |
  107. ## CLAUDE.md Constitution
  108. The repo includes a [CLAUDE.md](CLAUDE.md) that serves as the agent's trading constitution:
  109. - **9 non-negotiable rules** (edge required, paper default, risk is law, human confirms live trades, etc.)
  110. - **Authoritative risk limits** resolving all cross-file conflicts (graduated drawdown at 10/15/20%)
  111. - **Daily workflow** (14-step session start -> scan -> evaluate -> execute -> review)
  112. - **Paper-to-live prerequisites** (20+ trades, >55% win rate, Sharpe >0.5, drawdown <15%)
  113. - **Experience tiers** for live capital progression ($25 -> $100 -> $500 -> $2,000+)
  114. When CLAUDE.md conflicts with any SKILL.md, CLAUDE.md wins.
  115. ## Risk Management
  116. ### Risk Limits (from CLAUDE.md)
  117. | Parameter | Limit |
  118. |-----------|-------|
  119. | Max position size | 10% of portfolio (5% if confidence < 0.7, 2% for news, 1% for new strategy) |
  120. | Max concurrent positions | 5 |
  121. | Max single market exposure | 20% of portfolio |
  122. | Daily loss halt | 5% of portfolio |
  123. | Weekly loss halt | 10% of portfolio |
  124. | Graduated drawdown | 10% -> reduce 50%, 15% -> reduce 75%, 20% -> halt all |
  125. ### Correlation Detection
  126. The `correlation_tracker.py` groups positions by topic and detects hidden correlation:
  127. ```
  128. $ python polymarket-analyzer/scripts/correlation_tracker.py
  129. > Cluster: Insider Trading (3 positions) Exposure: $90.50 (9.4%)
  130. Correlation reason: shared qualifier: insider trading
  131. - YES $48.74 Will Axiom be accused of insider trading?
  132. - YES $23.90 Will MEXC be accused of insider trading?
  133. - YES $17.86 Will Robinhood be accused of insider trading?
  134. Diversification Score: 65/100 GOOD
  135. ```
  136. ### Portfolio Health Check
  137. The `health_check.py` runs the full session-start workflow in one command:
  138. ```
  139. $ python polymarket-paper-trader/scripts/health_check.py
  140. Status: [RED] Action required
  141. Total Value: $966.43 Drawdown: 3.36%
  142. Stops Triggered: 2
  143. [HIGH] Stop-loss triggered for MEXC insider trading
  144. [HIGH] Stop-loss triggered for Robinhood insider trading
  145. ```
  146. ### Live-Readiness Assessment
  147. The `backtest.py --live-check` tells you when you're ready for real money:
  148. ```
  149. $ python polymarket-strategy-advisor/scripts/backtest.py --live-check
  150. Live-Readiness Assessment: NOT READY (1/4 criteria met)
  151. [FAIL] Closed trades >= 20 actual: 0
  152. [FAIL] Win rate > 55% actual: 0.0%
  153. [FAIL] Sharpe ratio > 0.5 actual: 0.0
  154. [PASS] Max drawdown < 15% actual: 0.0%
  155. ```
  156. ## Going Live
  157. ### Prerequisites
  158. 1. 20+ closed paper trades with >55% win rate, Sharpe >0.5, drawdown <15%
  159. 2. A burner wallet (never your main wallet) funded with USDC on Polygon
  160. 3. Environment variables configured
  161. ### Setup
  162. ```bash
  163. cd polymarket-live-executor
  164. # Create a burner wallet
  165. python scripts/setup_wallet.py --create
  166. # Fund it: send $25 USDC + 0.1 MATIC on Polygon
  167. # Configure
  168. cp .env.example .env && chmod 600 .env
  169. # Edit .env with your private key
  170. # Verify
  171. source .env
  172. python scripts/setup_wallet.py --verify
  173. python scripts/setup_wallet.py --check-balance
  174. ```
  175. ### Experience Tiers
  176. | Level | Max Wallet | Max Per Trade | Daily Loss Limit |
  177. |-------|-----------|---------------|------------------|
  178. | First time | $25 | $5 | $10 |
  179. | Learning | $100 | $10 | $25 |
  180. | Experienced | $500 | $50 | $100 |
  181. | Advanced | $2,000+ | $200 | $500 |
  182. ### Safety Layers
  183. 1. **Paper-first**: Must prove edge in simulation before going live
  184. 2. **Env var gate**: `POLYMARKET_CONFIRM=true` required for any execution
  185. 3. **Human-in-the-loop**: Every trade shows full details, waits for "yes"
  186. 4. **Position caps**: Hard limits on size, daily loss, and concentration
  187. ## APIs Used
  188. | API | Endpoint | Auth | Usage |
  189. |-----|----------|------|-------|
  190. | Gamma API | `gamma-api.polymarket.com` | None | Market metadata, search |
  191. | CLOB API | `clob.polymarket.com` | None (read) / L2 (trade) | Prices, orderbooks, trading |
  192. No official Polymarket testnet exists. The paper trading engine simulates execution against real live prices.
  193. ## Data Storage
  194. | Location | Contents |
  195. |----------|----------|
  196. | `~/.polymarket-paper/portfolio.db` | Paper trading portfolio (SQLite) |
  197. | `~/.polymarket-live/trades.log` | Live trade log |
  198. | `~/.polymarket-paper/` | All paper trading data |
  199. ## Security
  200. - Full security audit: [SECURITY-AUDIT.md](SECURITY-AUDIT.md) (14 findings, all HIGH/MEDIUM fixed)
  201. - All DB queries use parameterized statements (no SQL injection)
  202. - Market data treated as untrusted (prompt injection defense)
  203. - Private keys never logged, displayed, or echoed
  204. - `.env` files gitignored; `.env.example` provided as template
  205. ## Disclaimer
  206. - These skills provide analytical tools and a paper trading simulator
  207. - Not financial advice. Past performance does not predict future results
  208. - Prediction market trading involves risk of total loss
  209. - Always paper trade new strategies before risking real capital
  210. - The authors are not responsible for any trading losses

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.