market-selector

name	market-selector
description	Polymarket market discovery, filtering, and scoring engine — scan trending/new/closing markets, filter by volume/liquidity/expiry/category, and score on a 0-100 composite scale.

market-selector

Scan Polymarket for trading opportunities. An agent can use this to discover, filter, and rank prediction markets before making trading decisions.

GitHub: https://github.com/joyehuang/market-selector

Installation

pip install git+https://github.com/joyehuang/market-selector.git

Or with pip from git:

pip install market-selector

CLI Usage

# Scan trending markets (sorted by volume)
market-selector scan --scanner trending

# Scan all scanners at once (trending + new-markets + closing-soon)
market-selector scan --scanner all

# JSON output for programmatic consumption by the agent
market-selector scan --scanner trending --output json

# Custom result limit
market-selector scan --scanner new-markets --limit 10

# Continuous watch mode
market-selector watch --scanner trending

# List available scanners
market-selector scanners

# View scan history (requires Postgres persistence)
market-selector history

# Disable persistence for one-off runs
market-selector scan --scanner trending --no-save

Agent Integration

1. Install once (setup)

The agent should install the package once:

import subprocess
subprocess.run(["pip", "install", "market-selector"], check=True)

2. Run a scan

import subprocess, json

result = subprocess.run(
    ["market-selector", "scan", "--scanner", "all", "--output", "json"],
    capture_output=True, text=True, timeout=120
)

# Parse JSON output
scans = json.loads(result.stdout)

The JSON output contains three scanner results. Each has a selected_markets array with ranked, scored markets:

{
  "scanner": "trending",
  "scanned_at": "2026-05-20T12:00:00+00:00",
  "total_markets_scanned": 500,
  "passed_filters": 23,
  "selected_markets": [
    {
      "token_id": "tok_yes_123",
      "token_ids": ["tok_yes_123", "tok_no_456"],
      "condition_id": "0xabc123",
      "question": "Will BTC reach $150K by June?",
      "probability": 0.35,
      "score": 88.4,
      "score_breakdown": {"volume": 85.0, "liquidity"       
       
       
       
       
       
       
        
        
       
        
    
  

3. Agent reasoning loop

For each top-N market, the agent should assess:

• Score ≥ 80 → market qualifies on fundamentals
• Spread < 3% → liquid enough to trade
• Probability assessment → does the current price seem mispriced given my knowledge?
• Time to expiry → enough time for thesis to play out?
• Check existing positions → don't double up

4. Example agent prompt

Scan Polymarket for trading opportunities using market-selector.

1. Run: `market-selector scan --scanner all --output json`
2. Parse the JSON for top-10 merged markets by score
3. For each market, assess:
   - Score ≥ 80 ✓
   - Spread < 3% ✓
   - Is the probability mispriced?
   - Time to expiry sufficient?
4. Return your analysis in this format:

### Scan Summary
trending: 500 scanned → 23 passed filters
new-markets: 300 scanned → 15 passed filters
closing-soon: 80 scanned → 8 passed filters

### Top Markets
1. [88.4] Will BTC reach $150K? — prob 35% — spread 1% → BUY YES
2. [86.2] Iran regime change? — prob 2% — spread 0.5% → SKIP (too risky)
3. [85.0] Trump wins 2026? — prob 60% — spread 2% → SKIP (expiry too far)

5. Run scan only (no trade)

If the agent only needs to see what's available (no trading):

market-selector scan --scanner trending --output json

Pass --no-save to avoid polluting the DB with one-off scans.

Configuration (env vars)

Variable	Default	Description
GAMMA_API_BASE_URL	https://gamma-api.polymarket.com	Polymarket events API
CLOB_API_URL	https://clob.polymarket.com	Polymarket order-book API
MARKET_SELECTOR_MIN_VOLUME_USD	10000	Min volume filter
MARKET_SELECTOR_MAX_SPREAD	0.05	Max spread filter (5%)
MARKET_SELECTOR_MIN_LIQUIDITY_USD	5000	Min liquidity filter
MARKET_SELECTOR_MIN_HOURS_TO_EXPIRY	24	Min hours to expiry
MARKET_SELECTOR_MAX_HOURS_TO_EXPIRY	8760	Max hours to expiry
MARKET_SELECTOR_ALLOWED_CATEGORIES	crypto,politics,tech,sports,finance	Category allow-list
DATABASE_URL	See README	Postgres connection (optional)

Persistence (optional)

If Postgres is available, set DATABASE_URL and run:

alembic upgrade head

Scans are then persisted for historical querying and diffing. The history command shows past scan results.

Scoring Formula

Five dimensions → composite 0-100 score:

Dimension	Weight	Notes
Volume	30%	Log scale, $1M → 100
Liquidity	25%	Log scale, $500k → 100
Spread	20%	Linear: 0% → 100, 10% → 0
Timing	15%	Triangular: 7d optimal
Category	10%	Crypto 100, Politics 90, ...

Important Notes

• The CLI returns JSON when --output json is set; the default is a human-readable Rich table
• No authentication is needed — Gamma API and CLOB API are public read-only endpoints
• The package has no trading functionality — it only discovers and scores markets
• For best results, run all three scanners (--scanner all) and merge by score