Polymarket CLI

Use the polymarket binary directly. Prefer read-only commands by default, use -o json for structured output, and treat any trading or on-chain action as sensitive.

Safety rules

Never read ~/.config/polymarket/config.json or any file that may contain private keys.

Never run wallet-management commands yourself. The user must run these directly:

• polymarket wallet create
• polymarket wallet import
• polymarket wallet show
• polymarket wallet reset
• polymarket wallet address
• polymarket setup

Ask before running any command that can:

• place, modify, or cancel orders
• approve contracts
• split, merge, redeem, or bridge assets
• create/delete API keys or notifications
• write private keys or config

Safe to run without extra confirmation:

• markets, events, tags, series, comments, profiles, sports
• read-only clob commands like book, price, midpoint, spread, price-history, market
• public data commands for wallets, markets, holders, volume, leaderboards
• health/version/help commands

Read-only authenticated commands are allowed only when they do not reveal secrets and do not modify state.

Quick start

Check availability first:

polymarket --help
polymarket --version

Use JSON for agent work:

polymarket -o json markets list --limit 5
polymarket -o json markets search "bitcoin" --limit 5
polymarket -o json clob midpoint TOKEN_ID

Opinionated workflows

Research a market

Use this when the user wants a quick market read without trading.

1. Search likely candidates:

polymarket -o json markets search "QUERY" --limit 10

1. Pick the most relevant slug or tokenized market.
2. If needed, inspect details:

polymarket -o json markets get MARKET_ID_OR_SLUG

1. If token IDs are available, inspect price/action:

polymarket -o json clob midpoint TOKEN_ID
polymarket -o json clob spread TOKEN_ID
polymarket -o json clob book TOKEN_ID
polymarket -o json clob price-history TOKEN_ID --interval 1d --fidelity 30

Summarize with: question, current odds, spread/liquidity hints, recent price context, and any obvious caveats.

Check a wallet safely

Use this when the user wants exposure, PnL-ish status, or activity without changing anything.

polymarket -o json data positions 0xWALLET
polymarket -o json data value 0xWALLET
polymarket -o json data trades 0xWALLET --limit 50

If the local configured wallet is relevant and the user wants account state, use read-only authenticated checks that do not expose secrets:

polymarket -o json clob balance --asset-type collateral
polymarket -o json clob orders
polymarket -o json clob trades
polymarket approve check

Do not run wallet show; tell the user to run wallet-management commands themselves.

Place a limit order safely

Do not run until the user confirms all of:

• market or token
• side (buy/sell)
• price
• size or amount
• whether post-only is desired

Recommended sequence:

# 1) Verify market context first
polymarket -o json clob midpoint TOKEN_ID
polymarket -o json clob spread TOKEN_ID
polymarket -o json clob book TOKEN_ID

# 2) Then place only after confirmation
polymarket clob create-order --token TOKEN_ID --side buy --price 0.50 --size 10

Repeat the full order back to the user before execution.

Common tasks

Browse markets and events

polymarket markets list --limit 10
polymarket markets search "election" --limit 5
polymarket markets get MARKET_ID_OR_SLUG
polymarket events list --limit 10
polymarket events get EVENT_ID

Inspect price/action on the CLOB

polymarket clob ok
polymarket clob book TOKEN_ID
polymarket clob midpoint TOKEN_ID
polymarket clob spread TOKEN_ID
polymarket clob price-history TOKEN_ID --interval 1d --fidelity 30

Inspect public wallet/market data

polymarket data positions 0xWALLET
polymarket data value 0xWALLET
polymarket data trades 0xWALLET --limit 50
polymarket data holders 0xCONDITION_ID
polymarket data open-interest 0xCONDITION_ID
polymarket data leaderboard --period month --order-by pnl --limit 10

Wallet and setup

Wallet-management commands are user-only. Do not run them yourself. If the user wants setup help, tell them which command to run locally.

# user-only
polymarket setup
polymarket wallet create
polymarket wallet import 0xPRIVATE_KEY
polymarket wallet show

# agent may run read-only approval checks
polymarket approve check

# agent must ask before any on-chain approval write
polymarket approve set

Trading

Only run after confirmation.

polymarket clob create-order --token TOKEN_ID --side buy --price 0.50 --size 10
polymarket clob market-order --token TOKEN_ID --side buy --amount 5
polymarket clob orders
polymarket clob cancel ORDER_ID
polymarket clob cancel-all

Working style

1. Prefer read-only discovery first.
2. If the user wants trading, verify the exact token/market, side, size/amount, and price before running anything.
3. For scripts and summaries, use -o json and parse the result.
4. If a command fails, rerun with --help on the relevant subcommand to inspect flags.
5. If the CLI is missing, tell the user how to install it:

brew tap Polymarket/polymarket-cli https://github.com/Polymarket/polymarket-cli
brew install polymarket

Reference

Read references/command-map.md when you need a fuller command inventory or a reminder of which areas are read-only vs sensitive.