Introduction
# Polymarket Arbitrage
Find and execute arbitrage opportunities on Polymarket prediction markets.
## Quick Start
### 1. Paper Trading (Recommended First Step)
Run a single scan to see current opportunities:
```bash cd skills/polymarket-arbitrage pip install requests beautifulsoup4 python scripts/monitor.py --once --min-edge 3.0 ```
View results in `polymarket_data/arbs.json`
### 2. Continuous Monitoring
Monitor every 5 minutes and alert on new opportunities:
```bash python scripts/monitor.py --interval 300 --min-edge 3.0 ```
Stop with `Ctrl+C`
### 3. Understanding Results
Each detected arbitrage includes: - **net_profit_pct**: Edge after 2% fees - **risk_score**: 0-100, lower is better - **volume**: Market liquidity - **action**: What to do (buy/sell all outcomes)
Good opportunities: - Net profit: 3-5%+ - Risk score: <50 - Volume: $1M+ - Type: `math_arb_buy` (safer)
## Arbitrage Types Detected
### Math Arbitrage (Primary Focus)
**Type A: Buy All Outcomes** (prob sum < 100%) - Safest type - Guaranteed profit if executable - Example: 48% + 45% = 93% → 7% edge, ~5% net after fees
**Type B: Sell All Outcomes** (prob sum > 100%) - Riskier (requires liquidity) - Need capital to collateralize - Avoid until experienced
See `references/arbitrage_types.md` for detailed examples and strategies.
### Cross-Market Arbitrage
Same event priced differently across markets (not yet implemented - requires semantic matching).
### Orderbook Arbitrage
Requires real-time orderbook data (homepage shows midpoints, not executable prices).
## Scripts
### fetch_markets.py
Scrape Polymarket homepage for active markets.
```bash python scripts/fetch_markets.py --output markets.json --min-volume 50000 ```
Returns JSON with market probabilities, volumes, and metadata.
### detect_arbitrage.py
Analyze markets for arbitrage opportunities.
```bash python scripts/detect_arbitrage.py markets.json --min-edge 3.0 --output arbs.json ```
Accounts for: - 2% taker fees (per leg) - Multi-outcome fee multiplication - Risk scoring
### monitor.py
Continuous monitoring with alerting.
```bash python scripts/monitor.py --interval 300 --min-edge 3.0 [--alert-webhook URL] ```
Features: - Fetches markets every interval - Detects arbitrage - Alerts on NEW opportunities only (deduplicates) - Saves state to `polymarket_data/`
## Workflow Phases
### Phase 1: Paper Trading (1-2 weeks)
**Goal:** Understand opportunity frequency and quality
1. Run monitor 2-3x per day 2. Log opportunities in spreadsheet 3. Check if they're still available when you look 4. Calculate what profit would have been
**Decision point:** If seeing 3-5 good opportunities per week, proceed to Phase 2.
### Phase 2: Micro Testing ($50-100 CAD)
**Goal:** Learn platform mechanics
1. Create Polymarket account 2. Deposit $50-100 in USDC 3. Manual trades only (no automation) 4. Max $5-10 per opportunity 5. Track every trade in spreadsheet
**Decision point:** If profitable after 20+ trades, proceed to Phase 3.
### Phase 3: Scale Up ($500 CAD)
**Goal:** Increase position sizes
1. Increase bankroll to $500 2. Max 5% per trade ($25) 3. Still manual execution 4. Implement strict risk management
### Phase 4: Automation (Future)
Requires: - Wallet integration (private key management) - Polymarket API or browser automation - Execution logic - Monitoring infrastructure
**Only consider after consistently profitable manual trading.**
See `references/getting_started.md` for detailed setup instructions.
## Risk Management
### Critical Rules
1. **Maximum position size:** 5% of bankroll per opportunity 2. **Minimum edge:** 3% net (after fees) 3. **Daily loss limit:** 10% of bankroll 4. **Focus on buy arbs:** Avoid sell-side until experienced
### Red Flags
- Edge >10% (likely stale data) - Volume <$100k (liquidity risk) - Probabilities recently updated (arb might close) - Sell-side arbs (capital + liquidity requirements)
## Fee Structure
Polymarket charges: - **Maker fee:** 0% - **Taker fee:** 2%
**Conservative assumption:** 2% per leg (assume taker)
**Breakeven calculation:** - 2-outcome market: 2% × 2 = 4% gross edge needed - 3-outcome market: 2% × 3 = 6% gross edge needed - N-outcome market: 2% × N gross edge needed
**Target:** 3-5% NET profit (after fees)
## Common Issues
### "High edge but disappeared"
Homepage probabilities are stale or represent midpoints, not executable prices. This is normal. Real arbs disappear in seconds.
### "Can't execute at displayed price"
Liquidity issue. Low-volume markets show misleading probabilities. Stick to $1M+ volume markets.
### "Edge is too small after fees"
Increase `--min-edge` threshold. Try 4-5% for more conservative filtering.
## Files and Data
All monitoring data stored in `./polymarket_data/`: - `markets.json` - Latest market scan - `arbs.json` - Detected opportunities - `alert_state.json` - Deduplication state (which arbs already alerted)
## Advanced Topics
### Telegram Integration (Future)
Pass webhook URL to monitor script for alerts:
```bash python scripts/monitor.py --alert-webhook "https://api.telegram.org/bot<token>/sendMessage?chat_id=<id>" ```
### Position Sizing
For a 2-outcome math arb with probabilities p₁ and p₂ where p₁ + p₂ < 100%:
**Optimal allocation:** - Bet on outcome 1: (100% / p₁) / [(100%/p₁) + (100%/p₂)] of capital - Bet on outcome 2: (100% / p₂) / [(100%/p₁) + (100%/p₂)] of capital
This ensures equal profit regardless of which outcome wins.
**Simplified rule:** For small edges, split capital evenly across outcomes.
### Execution Speed
Arbs disappear fast. If planning automation: - Use websocket connections (not polling) - Place limit orders simultaneously - Have capital pre-deposited - Monitor gas fees on Polygon
## Resources
- **Polymarket:** https://polymarket.com - **Documentation:** https://docs.polymarket.com - **API (if available):** Check Polymarket docs - **Community:** Polymarket Discord
## Support
For skill issues: - Check `references/arbitrage_types.md` for strategy details - Check `references/getting_started.md` for setup help - Review output files in `polymarket_data/` - Ensure dependencies installed: `pip install requests beautifulsoup4`