diff --git a/README.md b/README.md index 367d2d1..302ca5f 100644 --- a/README.md +++ b/README.md @@ -4,104 +4,256 @@ Composable [Agent Skills](https://agentskills.io/specification) for Polymarket p ## Skills -| Skill | What It Does | Auth Required | Risk | -|-------|-------------|---------------|------| +| Skill | What It Does | Auth | Risk | +|-------|-------------|------|------| | **polymarket-scanner** | Browse, search, and explore live markets | None | Zero | -| **polymarket-analyzer** | Detect edges: arbitrage, momentum, wide spreads | None | Zero | +| **polymarket-analyzer** | Detect edges: arbitrage, momentum, correlation analysis | None | Zero | | **polymarket-monitor** | Price alerts and position monitoring | None | Zero | -| **polymarket-paper-trader** | Simulate trades against live prices (zero risk) | None | Zero | -| **polymarket-strategy-advisor** | Trading methodology, recommendations, daily review | None | Low | -| **polymarket-live-executor** | Execute real trades (requires wallet + explicit opt-in) | L2 Wallet | Medium | +| **polymarket-paper-trader** | Simulate trades against live prices, portfolio health checks | None | Zero | +| **polymarket-strategy-advisor** | Trading methodology, recommendations, backtesting | None | Low | +| **polymarket-live-executor** | Execute real trades (wallet + explicit human opt-in) | L2 Wallet | Medium | ## Install -### Claude Code / Compatible Agents +### One Command (All Skills) ```bash -npx skills add https://github.com/verticalclaw/polymarket-skills --skill polymarket-scanner -npx skills add https://github.com/verticalclaw/polymarket-skills --skill polymarket-analyzer -npx skills add https://github.com/verticalclaw/polymarket-skills --skill polymarket-monitor -npx skills add https://github.com/verticalclaw/polymarket-skills --skill polymarket-paper-trader -npx skills add https://github.com/verticalclaw/polymarket-skills --skill polymarket-strategy-advisor -npx skills add https://github.com/verticalclaw/polymarket-skills --skill polymarket-live-executor +npx skills add mjunaidca/polymarket-skills +``` + +### Individual Skills +```bash +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/` (or your agent's skill directory). +Copy any skill folder to `~/.claude/skills/` (Claude Code) or `~/.agents/skills/` (other agents). ### Dependencies ```bash -pip install py-clob-client +pip install py-clob-client requests ``` ## Quick Start -Once installed, just talk to your agent naturally: +Once installed, talk to your agent naturally: -- *"Scan Polymarket for interesting markets"* — triggers polymarket-scanner -- *"Find trading opportunities"* — triggers polymarket-analyzer -- *"Set up a paper trading portfolio with $1000"* — triggers polymarket-paper-trader -- *"What should I trade?"* — triggers polymarket-strategy-advisor -- *"Check my portfolio"* — triggers polymarket-paper-trader +- *"Scan Polymarket for interesting markets"* -- triggers polymarket-scanner +- *"Find trading opportunities"* -- triggers polymarket-analyzer +- *"Set up a paper trading portfolio with $1000"* -- triggers polymarket-paper-trader +- *"What should I trade?"* -- triggers polymarket-strategy-advisor +- *"Check my portfolio health"* -- triggers polymarket-paper-trader (health_check) +- *"Am I ready to go live?"* -- triggers polymarket-strategy-advisor (backtest --live-check) +- *"Check correlation risk"* -- triggers polymarket-analyzer (correlation_tracker) -### Full Pipeline Example +### Full Pipeline ```bash -# 1. Scan markets -python polymarket-scanner/scripts/scan_markets.py --limit 20 --min-volume 50000 +source ~/.venv/bin/activate -# 2. Find edges -python polymarket-analyzer/scripts/find_edges.py --limit 30 +# 1. Initialize portfolio +python polymarket-paper-trader/scripts/paper_engine.py --action init --balance 1000 -# 3. Get recommendations -python polymarket-strategy-advisor/scripts/advisor.py --top 5 --portfolio-db ~/.polymarket-paper/portfolio.db +# 2. Scan markets +python polymarket-scanner/scripts/scan_markets.py --limit 50 --min-volume 10000 -# 4. Paper trade -python polymarket-paper-trader/scripts/paper_engine.py --action buy --token TOKEN_ID --side YES --size 50 --reason "Momentum signal" +# 3. Find edges +python polymarket-analyzer/scripts/find_edges.py --min-edge 0.02 --limit 500 -# 5. Review performance -python polymarket-strategy-advisor/scripts/daily_review.py --portfolio-db ~/.polymarket-paper/portfolio.db +# 4. Scan momentum +python polymarket-analyzer/scripts/momentum_scanner.py --min-volume 10000 + +# 5. Get trade recommendations +python polymarket-strategy-advisor/scripts/advisor.py --top 5 \ + --portfolio-db ~/.polymarket-paper/portfolio.db + +# 6. Paper trade +python polymarket-paper-trader/scripts/paper_engine.py \ + --action buy --token TOKEN_ID --side YES --size 50 --reason "Momentum signal" + +# 7. Check portfolio health (one command) +python polymarket-paper-trader/scripts/health_check.py + +# 8. Check correlation risk +python polymarket-analyzer/scripts/correlation_tracker.py + +# 9. Review performance +python polymarket-strategy-advisor/scripts/backtest.py + +# 10. Daily review +python polymarket-strategy-advisor/scripts/daily_review.py --days 7 ``` ## Architecture ``` -polymarket-scanner/ # Read-only market data (Gamma + CLOB APIs) - scripts/scan_markets.py # Browse/search markets - scripts/get_orderbook.py # Full order book depth - scripts/get_prices.py # Current prices/spreads - -polymarket-analyzer/ # Edge detection - scripts/find_edges.py # Arbitrage, overpriced, wide spread detection - scripts/momentum_scanner.py # Volume surge + orderbook imbalance signals - scripts/analyze_orderbook.py # Depth analysis - -polymarket-paper-trader/ # Zero-risk simulation engine - scripts/paper_engine.py # Core engine (SQLite portfolio) - scripts/execute_paper.py # Execute strategy recommendations - scripts/portfolio_report.py # Sharpe, Sortino, drawdown analytics - -polymarket-strategy-advisor/ # Trading methodology - scripts/advisor.py # Scan + score + size recommendations - scripts/daily_review.py # Performance review + suggestions - -polymarket-monitor/ # Position monitoring - scripts/monitor_prices.py # Multi-token price polling with alerts - scripts/watch_market.py # Continuous single-market snapshots - -polymarket-live-executor/ # Real trading (4 safety layers) - scripts/execute_live.py # Requires wallet + POLYMARKET_CONFIRM=true - scripts/check_positions.py # Balance, orders, trade history +Scanner --> Analyzer --> Strategy Advisor --> Paper Trader --> Live Executor +(find) (evaluate) (recommend) (simulate) (execute) ``` -## Safety Design +### polymarket-scanner/ -- Market Data (Read-Only) -- **Paper trading first**: Every strategy runs in simulation before real capital -- **No wallet by default**: Scanner, analyzer, monitor, paper trader, and advisor need zero authentication -- **Live executor locked**: Requires `POLYMARKET_PRIVATE_KEY` + `POLYMARKET_CONFIRM=true` + per-trade "yes" confirmation -- **Risk engine**: Position limits, drawdown stops, daily loss limits, concentration caps -- **Prompt injection protection**: All market data sanitized before display (market names are user-generated content) -- **SQL injection prevention**: All queries use parameterized statements -- **Security audited**: See [SECURITY-AUDIT.md](SECURITY-AUDIT.md) +| Script | Purpose | Key Args | +|--------|---------|----------| +| `scan_markets.py` | Browse/search active markets from Gamma API | `--limit 100 --min-volume 10000 --category TEXT --search TEXT` | +| `get_orderbook.py` | Full order book for a specific token | `--token-id ID --depth 10` | +| `get_prices.py` | Current midpoint, spread, last trade | `--token-id ID (repeatable) --market-slug SLUG` | + +### polymarket-analyzer/ -- Edge Detection + +| Script | Purpose | Key Args | +|--------|---------|----------| +| `find_edges.py` | Arbitrage (YES+NO < $1), wide spread, overpriced detection | `--min-edge 0.02 --limit 500` | +| `momentum_scanner.py` | Volume surges, price momentum, liquidity changes | `--min-volume 10000 --limit 300` | +| `analyze_orderbook.py` | Depth analysis, bid-ask imbalance, liquidity concentration | `--token-id ID --depth 10` | +| `correlation_tracker.py` | Detects hidden correlated exposure in portfolio | `--threshold 0.15 --json` | + +### polymarket-monitor/ -- Price Monitoring + +| Script | Purpose | Key Args | +|--------|---------|----------| +| `monitor_prices.py` | Multi-token polling with threshold alerts (JSON) | `--token-id ID --interval 30 --threshold 5.0` | +| `watch_market.py` | Continuous single-market snapshots | `--token-id ID --interval 15` | + +### polymarket-paper-trader/ -- Simulation Engine + +| Script | Purpose | Key Args | +|--------|---------|----------| +| `paper_engine.py` | Core engine: init, buy, close, portfolio, trades | `--action init/buy/close/portfolio/trades` | +| `execute_paper.py` | Execute structured strategy recommendations | `--recommendation '{"token_id":...}' --dry-run` | +| `portfolio_report.py` | Full analytics: Sharpe, Sortino, drawdown | `--json` | +| `health_check.py` | One-command session start: live prices, stops, drawdown, risk | `--json` (exit codes: 0=GREEN, 1=YELLOW, 2=RED) | + +### polymarket-strategy-advisor/ -- Trading Methodology + +| Script | Purpose | Key Args | +|--------|---------|----------| +| `advisor.py` | Scan, score, size trade recommendations | `--top 5 --portfolio-db PATH` | +| `backtest.py` | Performance analysis + live-readiness assessment | `--live-check --days 30 --json` | +| `daily_review.py` | Win/loss breakdown, strategy analysis, suggestions | `--days 7` | + +### polymarket-live-executor/ -- Real Trading (4 Safety Layers) + +| Script | Purpose | Key Args | +|--------|---------|----------| +| `execute_live.py` | Place real orders (requires env vars + human "yes") | `--token-id ID --side BUY --size 5 --price 0.60` | +| `check_positions.py` | Wallet balance, open orders, trade history | `--balance --orders --trades` | +| `setup_wallet.py` | Create burner wallet, verify config, check balance | `--create / --verify / --check-balance` | + +## CLAUDE.md Constitution + +The repo includes a [CLAUDE.md](CLAUDE.md) that serves as the agent's trading constitution: + +- **9 non-negotiable rules** (edge required, paper default, risk is law, human confirms live trades, etc.) +- **Authoritative risk limits** resolving all cross-file conflicts (graduated drawdown at 10/15/20%) +- **Daily workflow** (14-step session start -> scan -> evaluate -> execute -> review) +- **Paper-to-live prerequisites** (20+ trades, >55% win rate, Sharpe >0.5, drawdown <15%) +- **Experience tiers** for live capital progression ($25 -> $100 -> $500 -> $2,000+) + +When CLAUDE.md conflicts with any SKILL.md, CLAUDE.md wins. + +## Risk Management + +### Risk Limits (from CLAUDE.md) + +| Parameter | Limit | +|-----------|-------| +| Max position size | 10% of portfolio (5% if confidence < 0.7, 2% for news, 1% for new strategy) | +| Max concurrent positions | 5 | +| Max single market exposure | 20% of portfolio | +| Daily loss halt | 5% of portfolio | +| Weekly loss halt | 10% of portfolio | +| Graduated drawdown | 10% -> reduce 50%, 15% -> reduce 75%, 20% -> halt all | + +### Correlation Detection + +The `correlation_tracker.py` groups positions by topic and detects hidden correlation: + +``` +$ python polymarket-analyzer/scripts/correlation_tracker.py + + > Cluster: Insider Trading (3 positions) Exposure: $90.50 (9.4%) + Correlation reason: shared qualifier: insider trading + - YES $48.74 Will Axiom be accused of insider trading? + - YES $23.90 Will MEXC be accused of insider trading? + - YES $17.86 Will Robinhood be accused of insider trading? + + Diversification Score: 65/100 GOOD +``` + +### Portfolio Health Check + +The `health_check.py` runs the full session-start workflow in one command: + +``` +$ python polymarket-paper-trader/scripts/health_check.py + + Status: [RED] Action required + Total Value: $966.43 Drawdown: 3.36% + Stops Triggered: 2 + [HIGH] Stop-loss triggered for MEXC insider trading + [HIGH] Stop-loss triggered for Robinhood insider trading +``` + +### Live-Readiness Assessment + +The `backtest.py --live-check` tells you when you're ready for real money: + +``` +$ python polymarket-strategy-advisor/scripts/backtest.py --live-check + + Live-Readiness Assessment: NOT READY (1/4 criteria met) + [FAIL] Closed trades >= 20 actual: 0 + [FAIL] Win rate > 55% actual: 0.0% + [FAIL] Sharpe ratio > 0.5 actual: 0.0 + [PASS] Max drawdown < 15% actual: 0.0% +``` + +## Going Live + +### Prerequisites + +1. 20+ closed paper trades with >55% win rate, Sharpe >0.5, drawdown <15% +2. A burner wallet (never your main wallet) funded with USDC on Polygon +3. Environment variables configured + +### Setup + +```bash +cd polymarket-live-executor + +# Create a burner wallet +python scripts/setup_wallet.py --create + +# Fund it: send $25 USDC + 0.1 MATIC on Polygon + +# Configure +cp .env.example .env && chmod 600 .env +# Edit .env with your private key + +# Verify +source .env +python scripts/setup_wallet.py --verify +python scripts/setup_wallet.py --check-balance +``` + +### Experience Tiers + +| Level | Max Wallet | Max Per Trade | Daily Loss Limit | +|-------|-----------|---------------|------------------| +| First time | $25 | $5 | $10 | +| Learning | $100 | $10 | $25 | +| Experienced | $500 | $50 | $100 | +| Advanced | $2,000+ | $200 | $500 | + +### Safety Layers + +1. **Paper-first**: Must prove edge in simulation before going live +2. **Env var gate**: `POLYMARKET_CONFIRM=true` required for any execution +3. **Human-in-the-loop**: Every trade shows full details, waits for "yes" +4. **Position caps**: Hard limits on size, daily loss, and concentration ## APIs Used @@ -110,6 +262,24 @@ polymarket-live-executor/ # Real trading (4 safety layers) | Gamma API | `gamma-api.polymarket.com` | None | Market metadata, search | | CLOB API | `clob.polymarket.com` | None (read) / L2 (trade) | Prices, orderbooks, trading | +No official Polymarket testnet exists. The paper trading engine simulates execution against real live prices. + +## Data Storage + +| Location | Contents | +|----------|----------| +| `~/.polymarket-paper/portfolio.db` | Paper trading portfolio (SQLite) | +| `~/.polymarket-live/trades.log` | Live trade log | +| `~/.polymarket-paper/` | All paper trading data | + +## Security + +- Full security audit: [SECURITY-AUDIT.md](SECURITY-AUDIT.md) (14 findings, all HIGH/MEDIUM fixed) +- All DB queries use parameterized statements (no SQL injection) +- Market data treated as untrusted (prompt injection defense) +- Private keys never logged, displayed, or echoed +- `.env` files gitignored; `.env.example` provided as template + ## Disclaimer - These skills provide analytical tools and a paper trading simulator