# Polymarket Edge Scanner

Read-only CLI that scans every active Polymarket market (~8,000 events /
~20,000 markets, via the public Gamma + CLOB APIs, no key needed) and writes a
ranked markdown report of opportunities. It never places trades.

## Run

```bash
python3 scanner.py --bankroll 100            # full scan, ~2-3 min
python3 scanner.py --fast                    # skip live order-book verification
python3 scanner.py --min-liquidity 2000      # stricter liquidity filter
```

Output: `report-YYYYMMDD-HHMM.md` (or `--out path`).

## What it finds, in order of trustworthiness

| Signal | What it is | Risk |
|---|---|---|
| **Arbitrage** | Sum of YES asks over an exhaustive mutually-exclusive event < $1 (or all-NO < n−1). Verified against live order books, fee-adjusted. | ~Risk-free **if** filled at quoted prices and outcome list truly exhaustive. Capital may be locked until resolution — check the end date. |
| **Settlement bonds** | Near-certain side (≥95¢) resolving within 45 days, ≥20% annualized. | The 2–5¢ tail is priced for a reason. Only buy when YOU can verify the outcome is locked. |
| **Deadline decay** | "by \<date\>" markets near deadline still priced 5–60¢. | Judgment call. Check the news first; the market may know something. |
| **Big movers** | ≥15¢ moves in 24h. | Informational only. |

## Sizing rules baked in ($100 bankroll defaults)

- Fractional Kelly (¼) for probabilistic bets: stake = ¼ · B · (p − price)/(1 − price)
- Arbitrage capped at 30% of bankroll per event; bonds at 10% each, diversified.
- Order min size on Polymarket is usually 5 shares; depth is checked top-of-book.

## Known limitations / honesty notes

- Single-market YES/NO "arbitrage" is impossible by construction (Polymarket's
  book is mirrored: YES ask + NO ask = 1 + spread). Only cross-outcome arbs exist.
- Exhaustiveness check: an event qualifies for arb only if every one of its
  markets is either tradeable now or already resolved NO. Still eyeball the
  outcome list before trading.
- Gamma `bestBid/bestAsk` can be seconds-to-minutes stale; arb finalists are
  re-verified on the CLOB, everything else is screening-grade.
- Fees: applied as `takerBaseFee/1e4 × min(p, 1−p)` when `feesEnabled` (mostly
  sports). 
- No tool guarantees profit. Expect most long-term PnL from discipline
  (sizing, selectivity) rather than any single signal.