# Polymarket Quant Trading

> Build automated Polymarket trading bots with Kelly criterion, Bayesian probability, liquidity filtering, and real-time data feeds. Covers CLOB API integration, signal generation, position sizing, risk management, DRY RUN validation, and VPS deployment. Use when the user mentions Polymarket, prediction markets, event contracts, or quantitative trading strategies.

- **Type:** Skill
- **Install:** `agentstack add skill-jrcomet-polymarket-quant-skills-polymarket-quant-trading`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JRcomet](https://agentstack.voostack.com/s/jrcomet)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JRcomet](https://github.com/JRcomet)
- **Source:** https://github.com/JRcomet/polymarket-quant-skills/tree/main/polymarket-quant-trading

## Install

```sh
agentstack add skill-jrcomet-polymarket-quant-skills-polymarket-quant-trading
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Polymarket Quantitative Trading Bot Builder

A battle-tested skill for building automated trading bots on Polymarket's prediction market platform. Based on a real system that processed 211,000+ on-chain signals, executed 2,500+ simulated trades, and runs 24/7 on a Tokyo VPS.

## When to Use This Skill

Use this skill when the user wants to:
- Build a Polymarket trading bot from scratch
- Add quantitative strategies (Kelly, Bayesian, etc.) to an existing bot
- Connect external data sources (Binance, weather APIs) to Polymarket
- Implement proper risk management for prediction market trading
- Deploy a trading bot to production (VPS + systemd)
- Analyze Polymarket market data or orderbook dynamics
- Understand prediction market mechanics and edge detection

## Architecture Overview

A complete Polymarket quant system has three layers:

```
Signal Layer → Decision Layer → Execution Layer
(data sources)   (quant models)   (CLOB API)
```

**Signal Layer**: External data feeds that provide information edge
- Crypto prices (Binance WebSocket for real-time BTC/ETH)
- Weather data (Open-Meteo + WeatherAPI ensemble)
- On-chain wallet activity (Polymarket contract events)

**Decision Layer**: Quantitative models that convert signals to trades
- Bayesian probability updating (rolling posterior estimation)
- Kelly criterion (optimal position sizing)
- Liquidity filtering (reject thin markets)
- Signal fusion (weighted multi-source combination)

**Execution Layer**: Trade placement and management
- Polymarket CLOB API (py_clob_client)
- Order type selection (limit vs market)
- Position tracking and P&L logging

## Core Quantitative Components

### 1. Kelly Criterion — Dynamic Position Sizing

The Kelly criterion determines optimal bet size based on edge magnitude:

```
f* = (b * p - q) / b

where:
  f* = fraction of bankroll to bet
  b  = decimal odds - 1 (net payout)
  p  = estimated true probability
  q  = 1 - p
```

**Implementation guidance:**
- Use fractional Kelly (25% of full Kelly) for conservative growth
- Set hard limits: MIN_BET = $0.50, MAX_BET = $10-20
- Scale with bankroll: recalculate after each trade
- Never bet on negative edge (f*  0:
            likelihood_up = 0.5 + min(price_move_pct / 2, 0.4)
        else:
            likelihood_up = 0.5 + max(price_move_pct / 2, -0.4)

        # Bayesian update
        posterior = (likelihood_up * self.prior) / (
            likelihood_up * self.prior +
            (1 - likelihood_up) * (1 - self.prior)
        )

        self.prior = posterior
        self.observations.append({
            'timestamp': timestamp,
            'move': price_move_pct,
            'posterior': posterior
        })

        # Trim old observations
        self._trim_window(timestamp)
        return posterior

    def get_confidence(self):
        """How far from 0.5 (neutral) is our estimate."""
        return abs(self.prior - 0.5) * 2  # 0 = no info, 1 = certain
```

**Key insight**: 5 consecutive bullish signals in a 30-second window push the posterior from 0.50 to ~0.83. A sudden reversal drops it back quickly. This is much more robust than acting on a single price snapshot.

### 3. Liquidity Filter — The Most Important Feature

**This is the #1 lesson from DRY RUN testing.** In simulation, 70% of profitable trades occurred in markets with  MAX_SPREAD:
        return False, f"Spread too wide: {spread:.3f}"

    if best_bid  MAX_MARKET_PRICE:
        return False, f"Price outside range: {best_bid:.3f}-{best_ask:.3f}"

    # Check depth at best price
    depth = market_data.get('depth_at_best', 0)
    if depth  0.5 else "DOWN"
    bayesian_direction = "UP" if bayesian_prob > 0.5 else "DOWN"

    if sigmoid_direction != bayesian_direction:
        # Signals disagree — reduce confidence
        return 0.5, "CONFLICT"

    # Weighted fusion
    fused = sigmoid_prob * sigmoid_weight + bayesian_prob * bayesian_weight
    return fused, "ALIGNED"
```

## Polymarket API Integration

### Required Setup

```bash
pip install py-clob-client python-dotenv requests websocket-client
```

### API Endpoints

| API | Purpose | Base URL |
|-----|---------|----------|
| CLOB API | Order placement & management | `https://clob.polymarket.com` |
| Gamma API | Market discovery & metadata | `https://gamma-api.polymarket.com` |
| Data API | Historical prices & orderbooks | `https://data-api.polymarket.com` |

### Authentication

Polymarket uses API key + secret + passphrase authentication:

```python
from py_clob_client.client import ClobClient

client = ClobClient(
    host="https://clob.polymarket.com",
    key=os.environ["POLYMARKET_API_KEY"],
    chain_id=137,  # Polygon
    signature_type=2,
    funder=os.environ["POLYMARKET_FUNDER_ADDRESS"]
)
# Derive API credentials from private key
client.set_api_creds(client.create_or_derive_api_creds())
```

**Security**: NEVER hardcode private keys. Always use environment variables or `.env` files excluded from version control.

### Market Discovery

```python
def find_active_markets(keyword=None, category=None):
    """Find markets that are actively trading."""
    params = {"active": True, "closed": False}
    if keyword:
        params["tag_slug"] = keyword

    resp = requests.get(
        "https://gamma-api.polymarket.com/events",
        params=params
    )
    events = resp.json()

    # Filter for markets with adequate liquidity
    tradeable = []
    for event in events:
        for market in event.get('markets', []):
            if float(market.get('volume', 0)) > 1000:
                tradeable.append(market)
    return tradeable
```

## Bot Architecture Template

Read `references/bot-template.md` for the complete bot template with:
- Main scanning loop with configurable intervals
- WebSocket integration for real-time price feeds
- CSV logging for trades, signals, and calibration data
- systemd service configuration for 24/7 operation
- DRY RUN mode for zero-cost strategy validation

## Strategy Tracks

### Track 1: Crypto Price Prediction (Structural)
- **Edge source**: Binance real-time prices vs Polymarket odds lag
- **Time horizon**: 5-minute windows before market close
- **Key challenge**: Latency — 70% of arbitrage profits go to  .env  /etc/systemd/system/polymarket-bot.service << 'EOF'
[Unit]
Description=Polymarket Trading Bot
After=network.target

[Service]
Type=simple
WorkingDirectory=/root/polymarket-bot
ExecStart=/usr/bin/python3 /root/polymarket-bot/bot.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 6. Enable and start
systemctl daemon-reload
systemctl enable polymarket-bot
systemctl start polymarket-bot

# 7. Check logs
journalctl -u polymarket-bot -f
```

### DRY RUN First

**Always** start with `DRY_RUN = True`. This mode:
- Executes full signal pipeline
- Logs all would-be trades to CSV
- Tracks theoretical P&L
- Costs zero money

Run DRY RUN for at least 48 hours before considering live trading. Check:
1. Are signals generating at expected frequency?
2. What's the theoretical win rate?
3. How many trades pass the liquidity filter?
4. Is the Kelly sizing reasonable?

## Common Pitfalls

1. **Ignoring liquidity** — Simulated profits in thin markets are fake
2. **Over-betting** — Full Kelly = eventual ruin. Use fractional (25%)
3. **Single data source** — Always cross-reference when possible
4. **No DRY RUN** — Going live without validation is gambling, not trading
5. **Hardcoded private keys** — Use env vars, never commit keys to code
6. **Ignoring settlement** — Markets resolve on schedule; factor this into entry timing
7. **Technical indicator cargo cult** — MACD/RSI/VWAP are stock indicators; most don't apply to binary event markets

## Reference Files

- `references/bot-template.md` — Complete bot code template with all components
- `references/api-reference.md` — Polymarket API endpoint documentation
- `scripts/liquidity_checker.py` — Standalone market liquidity scanner
- `scripts/backtest.py` — Simple backtesting framework for strategy validation

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JRcomet](https://github.com/JRcomet)
- **Source:** [JRcomet/polymarket-quant-skills](https://github.com/JRcomet/polymarket-quant-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jrcomet-polymarket-quant-skills-polymarket-quant-trading
- Seller: https://agentstack.voostack.com/s/jrcomet
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.