Polymarket Arbitrage

Monitor and execute arbitrage opportunities on Polymarket prediction markets. Detects math arbitrage (multi-outcome probability mismatches), cross-market arbitrage (same event different prices), and orderbook inefficiencies. Use when user wants to find or trade Polymarket arbitrage, monitor prediction markets for opportunities, or implement automated trading strategies. Includes risk management, P&L tracking, and alerting.

Security Scan

The skill's code, instructions, and requirements are coherent with its stated purpose (finding Polymarket arbitrage); no unexplained creds, installs, or hidden endpoints were found — but it relies on fragile web-scraping, subprocess shell calls, and future automation would require private keys, so exercise standard caution.

Purpose & Capability

Name/description (Polymarket arbitrage) align with the included scripts (fetch_markets.py, detect_arbitrage.py, monitor.py) and documentation. The files only perform scraping, local analysis, state persistence in ./polymarket_data, and optional alerting — all expected for this purpose. No unrelated credentials, cloud APIs, or system services are requested.

Instruction Scope

SKILL.md instructs the agent/user to install requests and beautifulsoup4 and run the Python scripts; scripts only read/write files under the skill directory and fetch polymarket.com for data. A minor runtime concern: monitor.py invokes other scripts via subprocess.run(..., shell=True) to run python3 commands; in the present code those commands are constructed from local paths and CLI args, so immediate injection risk is low, but shell usage increases attack surface if untrusted inputs are later introduced (e.g., returning crafted filenames or providing malicious CLI args). The skill does not currently access environment variables or other system configs outside its data directory. The README and code correctly call out that homepage percentages may be stale and that execution requires wallet integration (not implemented).

Install Mechanism

There is no formal install spec (instruction-only + included scripts). The SKILL.md tells users to pip install requests and beautifulsoup4 — a normal, low-risk dependency installation. No external archives, shorteners, or arbitrary downloads are used.

Credentials

The skill declares no required environment variables or credentials and the code does not read secrets. The README warns that Phase 4 automation would require wallet integration and private keys; that functionality is not implemented in the included scripts. If you extend this skill to automate trades, you will need to manage private keys securely. Currently there is no disproportionate credential request.

Persistence & Privilege

always is false and the skill does not modify global agent config or other skills. It persists only to a local ./polymarket_data directory and a small alert_state.json file. It runs as a user-level process and does not request elevated privileges.

Assessment

This skill appears internally consistent and does what it claims: scrape the Polymarket homepage, detect math arbs, and optionally alert. Recommendations before installing or running: 1) Run it in a controlled environment (local VM or isolated project) and paper-trade first — the code and docs repeatedly warn that homepage odds are often stale and that real execution is fast and competitive. 2) Inspect or pin Python dependencies you install with pip. 3) Do NOT supply private keys, wallet JSONs, or long-lived secrets to this skill unless you (a) implement secure key management and (b) audit any added execution logic — automation that holds keys is a major additional risk. 4) Be aware of webhook URLs: they often embed tokens (e.g., Telegram bot tokens); treat them as secrets and avoid pasting them into public logs. 5) Note the use of subprocess.run(..., shell=True): currently commands are generated from local paths and user CLI args, but if you modify the code to include user-supplied strings in those commands, validate/avoid shell=True to prevent command injection. 6) Expect functional fragility (HTML scraping heuristics can produce wrong probabilities); validate outputs against the live site before risking funds.

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:

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:

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.

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.

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.

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:

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