Polymarket CLI

The Polymarket Trading Bot CLI is an AI-native research and trading interface for Polymarket. It pairs live Polymarket market data with the Octagon Research API so you can discover markets, investigate events, generate independent probability estimates, find pricing discrepancies, size positions against your bankroll, and place orders — all from the terminal.

Instead of stitching together market discovery, research, probability modeling, position sizing, and order execution by hand, the CLI brings those workflows behind one interface that works two ways at once:

• an interactive terminal application for traders and researchers
• a structured JSON command-line API for scripts, automations, and AI agents

Repository: Polymarket Trading Bot CLI on GitHub

How you use it

Issue direct commands:

polymarket search crypto --min-volume 10000
polymarket analyze will-bitcoin-hit-100k-by-december-31-2027
polymarket events when-will-bitcoin-hit-100k

Or ask natural-language questions inside the interactive terminal:

Find the most liquid crypto markets with at least five points of model edge.
Compare the outcomes priced in the 2028 presidential election event.
What catalysts could move this market before it resolves?
How does the model's probability compare with the order book here?

The agent runs multiple tool-use iterations across Polymarket and Octagon — gathering market data, inspecting related contracts, retrieving research, and comparing prices — before it answers. Bring your own LLM key (OpenAI, Anthropic, Google, xAI, OpenRouter, or local Ollama).

What the CLI unlocks

Discover across Polymarket

Search by keyword, category, theme, liquidity constraint, or resolution window to reduce thousands of contracts into a researchable opportunity set.

# Keyword + structured filters
polymarket search "bitcoin" --category crypto --min-volume 10000 --limit 20

# Rank live opportunities by model edge
polymarket search edge --min-edge 5 --sort-by total_volume --limit 10

Edge results sort by model edge, expected return, trading volume, or model probability. Beyond flat search:

• similar — related markets, walking event, then series, then category (-q "free text" ranks by keyword relevance instead).
• events — Octagon event rollups, and the full outcome ladder for one event (polymarket events when-will-bitcoin-hit-100k).
• catalysts upcoming --days 30 — markets approaching resolution, grouped by week.
• search --aggregate-by series — roll results up to the series level.

Research a market

analyze fuses live market state with Octagon research into an independent assessment — model probability, market-implied probability, edge, confidence, ranked price drivers, catalysts, suggested size, and risk-gate results.

polymarket analyze will-bitcoin-hit-100k-by-december-31-2027

For longer-form due diligence, report pulls the full Octagon markdown report for an event, a market, or a polymarket.com URL, with --refresh to force a fresh run:

polymarket report when-will-bitcoin-hit-100k --refresh

trust adds a Trader Trust scorecard so you can judge whether a contract is clearly defined and interpretable before relying on its displayed probability:

polymarket trust when-will-bitcoin-hit-100k
polymarket trust when-will-bitcoin-hit-100k --market will-bitcoin-hit-100k-by-december-31-2027

Edge, sizing, and the five-gate risk engine

The CLI defines edge as the gap between Octagon's independent probability estimate and the probability implied by the live order book:

Model probability: 72%
Market price:      58%
Edge:             +14 percentage points

This separates the research question (what is the probability?) from the trading question (is the price attractive relative to that probability?). No estimate becomes a trade automatically — signals pass through fractional-Kelly sizing and a five-gate risk engine first:

1. Kelly — is the position size justified by the estimated edge?
2. Liquidity — is there enough activity to enter and exit responsibly?
3. Correlation — does the trade duplicate exposure already in the book?
4. Concentration — would it over-weight one market, event, or category?
5. Drawdown — has the account crossed a configured drawdown or daily-loss limit?

Sizing and limits are configurable. The runtime default is half-Kelly:

polymarket config risk.kelly_multiplier 0.25
polymarket config risk.max_drawdown 0.20
polymarket config risk.max_positions 10
polymarket config risk.daily_loss_limit 200

Sizing runs against your wallet balance. Set risk.bankroll_usdc to cap how much of it the CLI will deploy:

polymarket config risk.bankroll_usdc 500

Trade, monitor, and validate

With a wallet configured, the CLI places and manages orders and tracks the portfolio. Prices are decimal dollars between 0 and 1, where 0.56 is 56 cents a share and a 56% implied probability:

polymarket buy  will-bitcoin-hit-100k-by-december-31-2027 10 0.56   # 10 shares, limit $0.56, YES outcome
polymarket sell will-bitcoin-hit-100k-by-december-31-2027 10 0.62 --side no
polymarket sell will-bitcoin-hit-100k-by-december-31-2027 max       # close the whole position
polymarket orders                                                    # resting orders on the CLOB
polymarket portfolio                                                 # positions, P&L, risk snapshot
polymarket watch will-bitcoin-hit-100k-by-december-31-2027           # live price + order-book feed

Omit the price for a market order. buy and sell confirm before they send; --yes skips the prompt. For a multi-outcome event such as presidential-election-winner-2028, pass the outcome name where yes or no would go.

Cancelling takes a full order id or any unique prefix of one, several ids at once, or every resting order:

polymarket orders cancel 0x3f2a
polymarket orders cancel 0x3f2a 0x91bd
polymarket orders cancel --all

backtest answers the question that matters most — does the model find real edge? It compares historical Octagon predictions against final settlement (resolved markets) or current pricing (unresolved), reporting Brier score, market Brier, skill score with confidence intervals, hit rate, and capital-weighted flat-bet P&L.

polymarket backtest --days 30 --min-volume 10 --min-price 5 --max-price 95
polymarket backtest --export results.csv

Installation

The fastest path needs no clone or install:

bunx polymarket-trading-bot-cli@latest

The CLI requires Bun 1.1 or newer (it uses bun:sqlite and runs TypeScript directly):

curl -fsSL https://bun.com/install | bash

On first launch the setup wizard collects your Octagon key, LLM provider, wallet, and bankroll. Configuration, cache, and the SQLite database live under ~/.polymarket-bot/.

Recommended install for agents and scripts

For repeated, parallel, or automated use, install globally and call the polymarket binary directly:

bun add -g polymarket-trading-bot-cli
polymarket search crypto --json

This is preferable to repeated bunx calls because it keeps Bun install messages out of JSON output, prevents concurrent processes racing on the temporary package cache, lowers startup overhead, and gives agents and scheduled jobs a stable executable.

Connect a wallet

Research works without a wallet. Trading and portfolio reads need one.

Create and fund your account on polymarket.com, then import it:

polymarket wallet import <private-key>   # trading, balances, and positions
polymarket wallet import <address>       # read-only: balances and positions
polymarket wallet show                   # what is currently configured

The CLI supports Polymarket deposit wallets, which is what polymarket.com creates for accounts opened on or after May 4, 2026.

Your key is written to ~/.polymarket-bot/wallet.json with owner-only permissions and stays on your machine — orders are signed locally, and only the signature is sent. Import an address instead of a key to read balances and positions without granting the ability to place orders.

Polymarket runs a single environment, so every order the CLI places is real money.

Connect the Octagon Research API

Set OCTAGON_API_KEY to enable Octagon-powered functionality:

export OCTAGON_API_KEY=your_octagon_api_key

An Octagon key unlocks deep research, independent probability estimates, edge scanning, related-market discovery, event outcome ladders, Trader Trust scorecards, model-driven Kelly sizing, and full market reports. Get a key from the Octagon application. Without it, basic search falls back to the local SQLite cache, but analyze, similar, events, trust, and report require Octagon access.

LLM provider configuration

The natural-language agent needs at least one model provider. Supported providers: OpenAI, Anthropic, Google, xAI, OpenRouter, and Ollama.

export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export GOOGLE_API_KEY=...
export XAI_API_KEY=...
export OPENROUTER_API_KEY=...

The CLI defaults to an OpenAI model (GPT-5.4). When using another provider, switch the configured model accordingly.

Command overview

# Discovery
polymarket search [query]
polymarket search edge
polymarket similar <market-slug>

# Research
polymarket analyze <market-slug>
polymarket report <event-slug>
polymarket trust <event-slug>
polymarket catalysts upcoming

# Events
polymarket events
polymarket events <event-slug>

# Trading & account
polymarket wallet import | show | address
polymarket buy | sell | orders | portfolio | watch

# Evaluation
polymarket backtest

Run polymarket help <command> for detailed usage, or see the User Guide.

Agent and JSON usage

Every command supports --json and returns a consistent envelope:

polymarket analyze will-bitcoin-hit-100k-by-december-31-2027 --json

{
  "ok": true,
  "command": "analyze",
  "data": {
    "ticker": "will-bitcoin-hit-100k-by-december-31-2027",
    "modelProb": 0.72,
    "marketProb": 0.58,
    "edge": 0.14,
    "confidence": "very_high",
    "drivers": [{ "claim": "Bitcoin ETF inflows accelerating", "impact": "high" }]
  },
  "meta": { "octagon_credits_used": 3, "octagon_cache_hits": 0 },
  "timestamp": "2026-03-30T10:00:00.000Z"
}

This consistent envelope makes the CLI a clean tool layer for shell scripts, scheduled jobs, AI-agent tool calls, monitoring, and data pipelines.

Example orchestration

MARKET=will-bitcoin-hit-100k-by-december-31-2027
ANALYSIS=$(polymarket analyze "$MARKET" --json)
EDGE=$(echo "$ANALYSIS" | jq '.data.edge')

# Trade only when the edge clears five percentage points
if (( $(echo "$EDGE > 0.05" | bc -l) )); then
  polymarket buy "$MARKET" 10 0.56 --yes --json
fi

polymarket portfolio --json

A more advanced agent can search the universe, rank by edge and liquidity, pull reports, Kelly-size each candidate, place orders, and re-evaluate edge as prices move.

Parallel research and streaming

After a global install, fan out analyses concurrently:

parallel -j 30 'polymarket analyze {} --json > {}.json' ::: <market-slug-a> <market-slug-b> <market-slug-c>

watch --theme emits newline-delimited JSON (one object per scan cycle), suitable for log processors, alerting services, message queues, and serverless workflows:

polymarket watch --theme crypto --json

Octagon credit controls

Octagon reports consume credits and are cached with market-aware expiration — markets closer to settlement get shorter cache lifetimes. Force a fresh report with --refresh, and cap daily usage to balance freshness against spend:

polymarket analyze will-bitcoin-hit-100k-by-december-31-2027 --refresh
polymarket config octagon.daily_credit_ceiling 100

Common use cases

• Individual trader — discover markets, generate research, compare model probability with live price, size trades, and monitor portfolio risk.
• Quantitative researcher — use JSON output and backtests to test whether signals persist across time and category.
• AI trading agent — expose commands as tools to research, size, and execute strategies through one structured interface.
• News and event analyst — use reports, outcome ladders, catalysts, and related-market discovery to see how events are being priced.
• Developer — treat the JSON envelope as a local integration layer for discovery, research, probability comparison, and execution.
• Scheduled monitor — run recurring searches or watch to detect new markets, edge changes, and upcoming catalysts.

Telemetry

The CLI collects anonymous operational telemetry — command names, tool usage, timing, and success/failure status — to improve reliability. It never collects API keys, trade details, natural-language prompts, or personal information. Disable it any time:

export TELEMETRY_ENABLED=false

Get started

# Interactive
bunx polymarket-trading-bot-cli@latest

# Agents, scripts, and parallel workflows
bun add -g polymarket-trading-bot-cli
polymarket search edge --min-edge 5 --json

Connect OCTAGON_API_KEY to unlock deep research, model probabilities, edge scanning, related-market discovery, and Trader Trust scorecards.

Next steps

• Kalshi CLI
• MCP Server
• Claude Plugin