Autonomous multi-strategy trading bot for Polymarket prediction markets. Scans ALL markets (crypto, politics, sports, economics, entertainment) for parity ar...
SKILL.md

---
name: polymarket-executor
description: Autonomous multi-strategy trading bot for Polymarket prediction markets. Scans ALL markets (crypto, politics, sports, economics, entertainment) for parity arbitrage, tail-end trading, and logical arbitrage opportunities. Features paper trading mode, Kelly Criterion position sizing, circuit breakers, and full optimizer integration via learned_config.json.
version: 2.0.0
metadata:
  openclaw:
    emoji: "🎯"
    requires:
      bins: ["python3"]
      env:
        required: []
        optional:
          - POLYMARKET_API_KEY
          - POLYMARKET_SECRET
          - POLYMARKET_PASSPHRASE
          - POLYMARKET_WALLET_ADDRESS
          - POLYMARKET_CAPITAL
          - TELEGRAM_BOT_TOKEN
          - TELEGRAM_CHAT_ID
          - PAPER_MODE
          - WORKSPACE
    network_behavior:
      makes_requests: true
      endpoints_allowed:
        - "https://clob.polymarket.com/*"
        - "https://gamma-api.polymarket.com/*"
        - "https://api.telegram.org/bot*"
      requires_credentials: false   # Paper mode works without credentials
      uses_websocket: false
    security_level: "L3 - Financial Execution (Real Money in live mode)"
    author: "Georges Andronescu (Wesley Armando)"
    license: "MIT"
    homepage: "https://github.com/georges91560/polymarket-executor"
    repository: "https://github.com/georges91560/polymarket-executor"
---

# Polymarket Executor — Multi-Strategy Trading Bot

## 🎯 WHAT IT DOES

Autonomous trading bot for Polymarket prediction markets.

Starts in **paper mode** (simulated capital, zero risk) to validate strategy performance before deploying real money. Reads configuration from `learned_config.json` (adjusted automatically by `polymarket-optimizer` every 6 hours).

**Markets covered:**
- ✅ Crypto (BTC, ETH, altcoins — price targets, daily/weekly)
- ✅ Politics (elections, policy, polls, government decisions)
- ✅ Sports (NBA, NFL, MLB, NHL, Soccer, UFC, Tennis, Golf)
- ✅ Economics (Fed rates, CPI, jobs reports, GDP)
- ✅ Technology (Apple, Tesla, Google, IPOs, launches)
- ✅ Entertainment (Oscars, Emmys, box office)
- ✅ Weather (hurricanes, temperature records, climate events)
- ✅ Miscellaneous (all binary outcome markets)

**Total markets scanned:** 500–5000+ per cycle

---

## ⚡ QUICK START

### Paper Mode (Default — No credentials needed)

```bash
cd /data/.openclaw/workspace/skills/polymarket-executor
python3 polymarket_executor.py
```

Expected output:
```
============================================================
POLYMARKET EXECUTOR v2.0.0
============================================================
[MODE] 📄 PAPER TRADING (simulated capital: $100.00)
[CONFIG] Loaded learned_config.json
[GAMMA] Fetched 2,341 markets
[SCAN] Scanning 500 markets with 50 workers...
[SCAN] Found 8 opportunities
[TRADE] PAPER: parity_arbitrage | YES+NO = $0.94 | Edge: 6.3%
[PORTFOLIO] Capital: $100.00 | Open: 2 | P&L: +$0.00
```

### Live Mode (After paper validation)

```bash
export PAPER_MODE=false
export POLYMARKET_API_KEY="your_key"
export POLYMARKET_SECRET="your_secret"
export POLYMARKET_PASSPHRASE="your_passphrase"
export POLYMARKET_CAPITAL=50.0
python3 polymarket_executor.py
```

---

## 🔥 STRATEGIES

### 1. Parity Arbitrage — Risk: ZERO ✅
**YES + NO prices don't sum to $1.00 → buy both → guaranteed profit**

```
YES: $0.45 + NO: $0.49 = $0.94 total
Buy both → payout: $1.00 → profit: 6.4%
Risk: NONE (guaranteed regardless of outcome)
```

Frequency: 5–20/day | Win rate: 100%

---

### 2. Tail-End Trading — Risk: Very Low ✅
**Buy >95% certainty outcomes, wait for $1.00 resolution**

```
Fed keeps rates → 98% certain → price: $0.97
Buy at $0.97 → resolution: $1.00 → profit: 3.1%
Risk: Very low (event almost certain)
```

Frequency: 10–30/day | Win rate: 95–98%

---

### 3. Logical Arbitrage — Risk: Low ✅
**Finds impossible price combinations between related markets**

```
"BTC > 100k by March" = 40%
"BTC > 90k by March"  = 35%   ← IMPOSSIBLE (90k < 100k)

Buy "BTC > 90k" at 35% — must resolve ≥ "BTC > 100k"
```

Frequency: 2–10/day | Win rate: 90–95%

---

## 📊 RISK MANAGEMENT

| Protection | Value | Description |
|---|---|---|
| Kelly Criterion | 25% fraction | Conservative position sizing |
| Max position | 10% of capital | Per-market limit |
| Max concurrent | 3 trades | Open positions cap |
| Circuit breaker | -15% daily | Halts all trading |
| Stop-loss | -50% per position | Auto-close losing trades |
| Max daily trades | 20 | Hard cap per day |

---

## 🧠 ADAPTIVE LEARNING

The executor reads `learned_config.json` at startup. The optimizer updates this file every 6 hours.

**What adapts automatically:**
- `min_parity_profit` — raised if false positives, lowered if win rate excellent
- `min_tail_end_certainty` — adjusted based on tail-end win rate
- `min_logical_edge` — tightened if logical arb underperforms
- `kelly_fraction` — reduced if portfolio in drawdown
- `strategy_allocation` — capital shifted toward best-performing strategies
- `scan_interval_seconds` — faster scans when performing well

---

## 📁 FILES CREATED

| File | Description |
|---|---|
| `paper_trades.json` | All simulated trade records |
| `portfolio.json` | Capital, positions, daily P&L |
| `performance_metrics.json` | Per-strategy stats for optimizer |
| `live_trades.jsonl` | Real trade log (live mode only) |
| `learned_config.json` | Optimizer-adjusted parameters |

---

## 📱 TELEGRAM ALERTS

```
🎯 POLYMARKET SCAN COMPLETE

📊 Markets scanned: 500
🔍 Opportunities: 8

💼 PORTFOLIO
💰 Capital: $100.00
📈 Daily P&L: +$2.34
🎯 Win Rate: 75.0%
📊 Open positions: 2

📋 OPPORTUNITIES
• parity_arbitrage: 6.3% edge
  Fed Rate Decision — Keeps...
• tail_end: 3.1% edge
  Chiefs win Super Bowl...
```

---

## ✅ LIVE READINESS CHECKLIST

Before switching `PAPER_MODE=false`:

- [ ] 30+ resolved paper trades
- [ ] Win rate ≥ 55%
- [ ] Positive total P&L
- [ ] No circuit breaker triggered
- [ ] Polymarket API credentials configured
- [ ] USDC on Polygon wallet
- [ ] Residential proxy configured (VPS blocks CLOB POST)

The `polymarket-optimizer` will report readiness automatically.

---

## ⚠️ VPS / PROXY NOTE

Polymarket CLOB API blocks datacenter IPs (including Hostinger VPS) for POST /order.

**Reading markets:** works fine on VPS (no proxy needed)
**Placing orders:** requires residential proxy in live mode

Recommended: IPRoyal, BrightData rotating residential proxy.
Paper mode works 100% without proxy.

---

**Version:** 2.0.0 | **License:** MIT | **Author:** Georges Andronescu (Wesley Armando)
Polymarket Executor

SKILL.md

related skills
