polymarket-paper-trader

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: polymarket-paper-trader
description: Use this skill whenever the user wants to paper trade, simulate trades, virtual trading, demo mode, practice trading, backtest strategies, test strategy performance, use paper money, manage a virtual portfolio, track simulated P&L, or do risk-free trading on Polymarket prediction markets. Also use when the user asks about their portfolio, positions, trade history, or performance report for paper trading. This is the core trading engine — it executes simulated trades against real live Polymarket prices with zero financial risk.
---

# Polymarket Paper Trading Engine

Simulate trades against **live Polymarket prices** with zero financial risk. No wallet, no keys, no money at stake. Portfolio persists across sessions in SQLite.

## Quick Start

### Initialize a Portfolio
```bash
python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action init --balance 1000
```

### Buy Shares (Market Order)
```bash
# Buy $50 of YES shares using live order book prices
python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
  --action buy --token TOKEN_ID --side YES --size 50 \
  --reason "High confidence based on news analysis"
```

### Buy Shares (Limit Order)
```bash
python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
  --action buy --token TOKEN_ID --side YES --size 50 --price 0.45 \
  --reason "Value buy below fair price estimate"
```

### Check Portfolio
```bash
python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action portfolio
python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action portfolio --json
```

### Close a Position
```bash
python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
  --action close --token TOKEN_ID --reason "Taking profit"
```

### View Trade History
```bash
python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action trades
```

### Performance Report
```bash
python ~/.agents/skills/polymarket-paper-trader/scripts/portfolio_report.py
python ~/.agents/skills/polymarket-paper-trader/scripts/portfolio_report.py --json
```

### Portfolio Health Check (Session Start)
```bash
python ~/.agents/skills/polymarket-paper-trader/scripts/health_check.py
python ~/.agents/skills/polymarket-paper-trader/scripts/health_check.py --json
```
Runs the full session-start workflow in one command: loads portfolio, fetches live prices, updates DB, calculates drawdown, checks stop losses, evaluates all risk limits. Returns GREEN/YELLOW/RED status.

## Finding Token IDs

Token IDs come from the Polymarket Gamma API. To find them for a market:

```bash
# Search for markets
curl -s 'https://gamma-api.polymarket.com/markets?limit=5&active=true&closed=false&order=volume24hr&ascending=false' | python3 -c "
import sys, json
for m in json.load(sys.stdin):
    tokens = json.loads(m['clobTokenIds'])
    prices = json.loads(m['outcomePrices'])
    print(f\"{m['question'][:60]}\")
    print(f\"  YES token: {tokens[0]}  price: {prices[0]}\")
    print(f\"  NO  token: {tokens[1]}  price: {prices[1]}\")
    print()
"
```

Or use the **polymarket-scanner** skill to discover markets first.

## Execute Strategy Recommendations

The executor takes structured recommendations from strategy advisors:

```bash
python ~/.agents/skills/polymarket-paper-trader/scripts/execute_paper.py \
  --recommendation '{
    "token_id": "TOKEN_ID",
    "side": "YES",
    "action": "BUY",
    "size_usd": 50,
    "confidence": 0.75,
    "reasoning": "Momentum signal detected",
    "strategy": "momentum"
  }'
```

Dry run (validates without executing):
```bash
python ~/.agents/skills/polymarket-paper-trader/scripts/execute_paper.py \
  --recommendation '{"token_id":"TOKEN","side":"YES","size_usd":50}' --dry-run
```

## Risk Rules (Built In)

| Rule | Default | Purpose |
|------|---------|---------|
| Max position size | 10% of portfolio | No single bet too large |
| Max drawdown | 30% | Stop t