Skip to main content

Python CLI Reference

Installation​

Option A: From PyPI (Recommended)

pip install polymarket-ai-market-suggestor

Option B: From Source

cd polymarket-ai-market-suggestor
pip install -r requirements.txt

See the PyPI package for more details.

Core Commands​

suggest​

Generate market suggestions from a trend or topic.

polysuggest suggest "Bitcoin will hit $100k"
polysuggest suggest "Will Trump win in 2028?" --confidence 0.8
polysuggest suggest "AI will become sentient" --save-to-db

Options:

  • --confidence <value> – Suggestion confidence threshold 0-1 (default: auto)
  • --save-to-db – Store suggestion in database for calibration tracking
  • --output json|table – Output format (default: table)

Output:

Trend: "Bitcoin will hit $100k"
Suggested Outcome: YES
Confidence: 0.75
Reasoning: Recent price trends and Fed policy changes suggest bullish sentiment
Markets:
  - BTC-2025-EOY-100K (Polymarket ID: 0x...)
  - BTC Price EOY (Manifold: https://manifold.markets/...)

data​

Manage real-time market data.

fetch​

Fetch live data for a specific market.

polysuggest data fetch --market 0x123abc... --output ohlcv
polysuggest data fetch --market BTC-2025 --duration 1h --interval 5m

Options:

  • --market <id> – Market ID (required)
  • --duration <str> – Time window (default: 1h, examples: 5m, 1h, 24h)
  • --interval <str> – Candle interval (default: 1m, examples: 1m, 5m, 1h)
  • --output ohlcv|raw|json – Output format

Output:

Time                 Open    High    Low     Close   Volume
2025-12-16 14:00    $45.2   $45.8   $44.9   $45.5   125000
2025-12-16 14:05    $45.5   $46.1   $45.4   $46.0   98000
...

stream​

Stream real-time prices to a WebSocket.

polysuggest data stream --market BTC-2025 --timeout 60s

edges​

Detect and monitor edges (probability mismatches).

list​

Show detected edges across all markets.

polysuggest edges list --top 10
polysuggest edges list --min-edge 0.15 --min-liquidity 5000
polysuggest edges list --output json

Options:

  • --top <n> – Show top N edges by EV (default: 10)
  • --min-edge <float> – Minimum edge % (default: 0.05)
  • --min-liquidity <float> – Minimum liquidity (default: 1000)
  • --output json|table – Output format

Output:

Market ID           Fair Prob  Market Prob  Edge %   Liquidity  Confidence  Decay
BTC-100K-2025       0.72       0.55         +31%     15000      0.92        0.95
ETH-50K-EOY         0.64       0.48         +33%     8000       0.88        0.87
...

watch​

Monitor edges in real-time, with alerts on new ones.

polysuggest edges watch --threshold 0.20 --interval 5s
polysuggest edges watch --webhook https://hooks.slack.com/...

Options:

  • --threshold <float> – Alert on edges > threshold (default: 0.15)
  • --interval <str> – Check interval (default: 5s)
  • --webhook <url> – Post alerts to webhook

Output:

[14:23:45] NEW EDGE DETECTED
Market: BTC-2025-EOY-100K
Fair Probability: 0.72
Market Probability: 0.55
Edge: +31%
Liquidity: $15,000
Confidence: 0.92
→ Place trade? (y/n): _

calibrate​

Track historical accuracy of suggestions and edges.

show​

Display calibration metrics.

polysuggest calibrate show
polysuggest calibrate show --by-confidence  # Group by confidence bucket
polysuggest calibrate show --since "2025-11-01"

Options:

  • --by-confidence – Break down by confidence buckets (0-0.25, 0.25-0.5, etc.)
  • --by-category – Break down by market category (crypto, sports, etc.)
  • --since <date> – Filter from date forward
  • --output json|table|csv

Output:

Confidence  Count  Accuracy  Brier Score  Avg Confidence
0.60-0.70    42     0.67      0.18         0.65
0.70-0.80    35     0.80      0.12         0.75
0.80-0.90    28     0.89      0.08         0.85
0.90+        12     0.92      0.06         0.93

Overall: 117 suggestions, 78% accuracy, Brier score 0.12

update​

Backfill historical suggestions with resolutions.

polysuggest calibrate update --auto  # Auto-fetch resolutions from Gamma API
polysuggest calibrate update --manual  # Interactive mode

positions​

Manage your portfolio and P&L.

summary​

Show portfolio overview.

polysuggest positions summary
polysuggest positions summary --currency usd

Output:

Total Exposure:         $12,500
Realized P&L:          +$1,245 (+9.9%)
Unrealized P&L:        +$340 (+2.7%)
Total P&L:             +$1,585 (+12.6%)

Win Rate:              62% (18/29 closed positions)
Avg Win:               +$85
Avg Loss:              -$42
Profit Factor:         2.1x

Portfolio Heat:        32% (max loss in worst case)
Liquidation Risk:      Low

list​

List all open positions.

polysuggest positions list
polysuggest positions list --market BTC-2025
polysuggest positions list --outcome YES

Output:

Position ID  Market              Outcome  Qty   Entry Price  Current Price  Unrealized P&L  Status
POS-001      BTC-2025-EOY-100K   YES      50    $0.45        $0.52         +$350 (+7.8%)   Open
POS-002      ETH-50K-EOY         NO       100   $0.35        $0.38         -$300 (-8.6%)    Open

add​

Manually add a position (for record-keeping).

polysuggest positions add --market BTC-2025 --outcome YES --qty 100 --entry-price 0.45

close​

Close a position.

polysuggest positions close --position-id POS-001 --exit-price 0.52

orders​

Manage limit orders and execution.

place​

Place a new order.

polysuggest orders place --market BTC-2025 --outcome YES --size 100 --limit 0.45
polysuggest orders place --market BTC-2025 --outcome YES --size 100 --limit 0.45 --ladder 5 --window 30m

Options:

  • --market <id> – Market ID (required)
  • --outcome <YES|NO> – Outcome (required)
  • --size <int> – Order size (required)
  • --limit <float> – Limit price (required)
  • --ladder <n> – Split into N tranches (default: 1, no laddering)
  • --window <str> – Time window for laddering (default: 5m, examples: 5m, 1h)
  • --auto-cancel-on-spread – Cancel if spread widens >5%

Output:

Order ID: ORD-12345
Status: PENDING
Market: BTC-2025-EOY-100K
Outcome: YES
Size: 100
Limit Price: $0.45
Estimated Slippage: -0.8%
Expected Fill Price: $0.446
Liquidity Available: 15,000

Order laddered into 5 tranches:
  Tranche 1: 20 @ $0.45 (starts now)
  Tranche 2: 20 @ $0.45 (in 7.5m)
  Tranche 3: 20 @ $0.45 (in 15m)
  Tranche 4: 20 @ $0.45 (in 22.5m)
  Tranche 5: 20 @ $0.45 (in 30m)

→ Confirm? (y/n): y

status​

Check order status and execution.

polysuggest orders status --order-id ORD-12345

Output:

Order ID: ORD-12345
Status: PARTIALLY_FILLED
Created: 2025-12-16 14:00:00
Fills:
  Tranche 1: 20 @ $0.449 (filled at 14:00:30)
  Tranche 2: 20 @ $0.450 (filled at 14:08:15)
  Tranche 3: PENDING
  ...

Total Filled: 40 / 100
Avg Fill Price: $0.4495
Realized Slippage: -0.55%

cancel​

Cancel a pending order.

polysuggest orders cancel --order-id ORD-12345

backtest​

Run historical simulations.

run​

Run a backtest.

polysuggest backtest run --start "2025-11-01" --end "2025-12-15" --strategy edges
polysuggest backtest run --market BTC-2025 --strategy manual --input-file trades.csv

Options:

  • --start <date> – Start date (required)
  • --end <date> – End date (required)
  • --strategy <str> – Strategy (edges, random, buy-hold, manual)
  • --input-file <path> – CSV for manual strategy (columns: date, market, outcome, size, price)
  • --initial-capital <float> – Starting capital (default: 10000)
  • --output json|html – Output format

Output:

Backtest Results: edges strategy (2025-11-01 to 2025-12-15)

Initial Capital:       $10,000
Final Capital:         $11,586
Realized P&L:          +$1,586 (+15.9%)

Total Trades:          28
Winning Trades:        20 (71.4%)
Losing Trades:         8 (28.6%)
Avg Win:               +$125
Avg Loss:              -$64

Sharpe Ratio:          1.42
Max Drawdown:          -8.2%
Return / Drawdown:     1.93x

Edge Accuracy:         72% (20/28 trades with +EV)
Avg Edge Detected:     +0.18 (18% EV advantage)

results​

Show backtest results (with visualizations).

polysuggest backtest results --id BACKTEST-12345 --plot equity,drawdown,distribution

ai​

AI model and inference commands.

estimate-probability​

Get fair probability estimate for a market.

polysuggest ai estimate-probability --market BTC-2025 --show-intervals
polysuggest ai estimate-probability --market BTC-2025 --model bayesian,ensemble

Options:

  • --market <id> – Market ID (required)
  • --model <str> – Model selection (default: ensemble)
  • --show-intervals – Show credible intervals

Output:

Market: BTC-2025-EOY-100K
Fair Probability Estimate (Ensemble):

Bayesian Model:       0.72 (credible interval: 0.68-0.76)
  └─ Based on: base rates, sentiment, order flow
  └─ Confidence: 0.88

SVM Classifier:       0.68 (historical pattern match)
  └─ Similar to 14 past markets
  └─ Accuracy on similar: 76%

LSTM Time Series:     0.75 (momentum + trend)
  └─ Recent momentum: bullish
  └─ Volatility: moderate

Ensemble Average:     0.72

research​

Research and semantic search.

Find similar historical markets.

polysuggest research search "What markets were created after China banned crypto?"
polysuggest research search "bull market rallies" --limit 20

Output:

Similar Markets (RAG):
1. "Will Bitcoin rally >30% after China regulatory action?" (created 2023-10-15)
   Resolution: YES (in 3 weeks)
   Final Price: $0.78
   
2. "Crypto recovery in bear market phase" (created 2023-11-01)
   Resolution: YES
   Final Price: $0.65

...

report​

Generate daily research report.

polysuggest research report
polysuggest research report --email your@email.com

Output:

PolySuggest Daily Research Report
Date: 2025-12-16

TOP 5 EDGE OPPORTUNITIES
1. BTC-100K-EOY: +31% edge, $15k liquidity, confidence 0.92
2. ETH-50K-EOY: +33% edge, $8k liquidity, confidence 0.88
...

EMERGING TRENDS
- "Trump and crypto" sentiment surge (+45% in last 24h)
- "AI regulation" now trending (5 new markets created)

MARKET CALENDAR
- BTC-2025 resolves in 15 days
- ETH-May resolves in 3 days (close-to-resolution warning)

PORTFOLIO REBALANCE SUGGESTIONS
- Current correlation: 0.78 (too high)
- Consider exiting ETH-NO to diversify

DAILY P&L
- Realized: +$45
- Unrealized: -$12
- Total: +$33

config​

Manage configuration.

polysuggest config set --key api-key --value sk_...
polysuggest config set --key gamma-api-url --value https://api.gamma.polymarket.com
polysuggest config set --key bankroll --value 50000
polysuggest config set --key alert-webhook --value https://hooks.slack.com/...

polysuggest config show
polysuggest config show --key bankroll

Global Options​

All commands support:

  • --verbose – Verbose logging
  • --output json|table|csv – Output format
  • --config <path> – Config file path
  • --help – Show help

Examples​

Quick Start Workflow​

# 1. Check for new edges
polysuggest edges list --top 5

# 2. Get fair probability for top edge
polysuggest ai estimate-probability --market BTC-2025-EOY-100K --show-intervals

# 3. Check portfolio impact
polysuggest positions summary

# 4. Place order with laddering
polysuggest orders place \
  --market BTC-2025-EOY-100K \
  --outcome YES \
  --size 100 \
  --limit 0.45 \
  --ladder 5 \
  --window 30m

# 5. Watch edge in real-time
polysuggest edges watch --threshold 0.20

Research & Backtesting​

# Find similar markets
polysuggest research search "BTC price rally"

# Run a backtest
polysuggest backtest run \
  --start "2025-11-01" \
  --end "2025-12-15" \
  --strategy edges

# Check calibration
polysuggest calibrate show --by-confidence

Portfolio Management​

# Overview
polysuggest positions summary

# List specific positions
polysuggest positions list --market BTC-2025

# Close a position
polysuggest positions close --position-id POS-001 --exit-price 0.52

Configuration Files​

Create a .polysuggest.yaml in your home directory:

api:
  gamma-api-url: https://api.gamma.polymarket.com
  gamma-api-key: sk_...

trading:
  bankroll: 50000
  max-position-size: 0.05  # 5% of bankroll per position
  max-portfolio-heat: 0.50  # 50% max loss tolerance

alerts:
  slack-webhook: https://hooks.slack.com/...
  email: your@email.com
  min-edge-threshold: 0.15

database:
  postgres-url: postgresql://user:pass@localhost/polysuggest
  timescaledb-url: postgresql://user:pass@localhost/timescale

inference:
  model: ensemble  # or "bayesian", "svm", "lstm"
  confidence-interval: 0.90