# Polymarket Scanner API

Real-time arbitrage and mispricing detection across 10,000+ prediction markets on [Polymarket](https://polymarket.com).

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/vesper-astrena/polymarket-scanner-api)

## What It Detects

- **Exclusive outcome mispricings** — When yes prices don't sum to 1.0
- **Ladder contradictions** — When higher thresholds are priced above lower ones
- **Cross-market conflicts** — Contradictions between related markets

## Quick Start

```bash
# Try the hosted API (free, 3 requests/day)
curl https://polymarket-scanner-api.onrender.com/api/scan

# Filter by minimum profit and liquidity
curl "https://polymarket-scanner-api.onrender.com/api/scan?min_profit=5&min_liquidity=1000"
```

## Self-Host

```bash
git clone https://github.com/vesper-astrena/polymarket-scanner-api.git
cd polymarket-scanner-api
pip install -r requirements.txt
python main.py
# → http://localhost:8000
```

## API Reference

### `GET /api/scan`

Returns current arbitrage opportunities.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `min_profit` | float | 0 | Minimum estimated profit % |
| `min_liquidity` | float | 0 | Minimum liquidity in USD |
| `limit` | int | 50 | Max opportunities to return |

**Response:**

```json
{
  "scan_time": "2026-03-12T00:22:58Z",
  "events_scanned": 750,
  "markets_scanned": 11330,
  "opportunities_found": 110,
  "opportunities": [
    {
      "type": "exclusive_mispricing",
      "description": "Counter-Strike: Team Nemesis vs ARCRED",
      "deviation_pct": 473.8,
      "estimated_profit_pct": 145.25,
      "min_liquidity_usd": 451.0,
      "strategy": "BUY_ALL_NO",
      "confidence": "high"
    }
  ]
}
```

### `GET /api/health`

Health check endpoint.

## Pricing

| | Free | Pro ($29/mo) |
|---|---|---|
| API calls | 3/day | Unlimited |
| Opportunities | Top 10 | All (50+) |
| Cache | 5 min | Real-time |
| Webhooks | — | Coming soon |

**[Get Pro Access →](https://vesperfinch.gumroad.com/l/polymarket-api)**

## How It Works

The scanner fetches all active events from Polymarket's public Gamma API, parses market data, and runs three detection algorithms:

1. **Exclusive outcomes**: Checks if yes prices for mutually exclusive outcomes sum to 1.0
2. **Ladder contradictions**: Verifies that higher thresholds have lower probabilities
3. **Cross-market**: Finds contradictions between semantically related markets

Data source: [Polymarket Gamma API](https://gamma-api.polymarket.com) (public, read-only, no authentication required).

## License

MIT