Polymarket Trading Skill

Trade prediction markets on Polymarket through the official polymarket CLI. Browse markets, place limit and market orders, manage positions, check rewards, and interact with conditional tokens — all from the terminal.

Installation

macOS / Linux (Homebrew)

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

Shell script

curl -sSL https://raw.githubusercontent.com/Polymarket/polymarket-cli/main/install.sh | sh

Build from source (Rust)

git clone https://github.com/Polymarket/polymarket-cli
cd polymarket-cli
cargo install --path .

Wallet Setup

# Guided first-time setup
polymarket setup

# Or manually:
polymarket wallet create
polymarket approve set  # needs MATIC for gas on Polygon

Configuration

Private key is resolved in order:

CLI flag: --private-key 0xabc...
Environment variable: POLYMARKET_PRIVATE_KEY=0xabc...
Config file: ~/.config/polymarket/config.json

Signature types: proxy (default), eoa, gnosis-safe. Override with --signature-type.

Overview

You are an expert in using the polymarket CLI for prediction market trading. Your goal is to help users trade on Polymarket efficiently while emphasizing safety, position management, and risk awareness.

How to Use This Skill

Safety First: Start with small positions. Polymarket trades are real money on Polygon mainnet.
Verify Before Trading: Always show the exact command and confirm with the user before executing trades.
Check Prerequisites: Confirm wallet is set up, approvals are granted, and sufficient USDC balance exists.
Use JSON Output: For scripting and automation, use -o json for machine-readable output.
Understand Token IDs: Each market outcome (YES/NO) has a unique token ID. Get it from market details or order book commands.

When to Use This Skill

Use this skill when the user wants to:

Browse or search prediction markets
Place bets (limit orders, market orders)
Check market prices, spreads, and order books
View or manage open orders
Check portfolio positions and P/L
Cancel orders
Redeem winnings from resolved markets
Check liquidity rewards and earnings
Monitor market activity and leaderboards
Hedge positions across markets

Common trigger phrases:

"What prediction markets are trending?"
"Buy YES on Bitcoin above 100k"
"Show me the order book"
"What's the spread on this market?"
"Cancel all my orders"
"Check my positions"
"How much have I earned in rewards?"
"Place a limit order at 0.45"
"Hedge my position"

When NOT to use this skill:

User wants to trade stocks/ETFs/options (use Alpaca trading skill)
User wants financial advice (provide tools, not recommendations)
User wants to use the Polymarket web UI

Core Commands

Market Discovery (No wallet needed)

List markets:

polymarket markets list --limit 10
polymarket markets list --active true --order volume_num
polymarket markets list --closed false --limit 50 --offset 25

Get market details:

polymarket markets get 12345
polymarket markets get will-trump-win  # by slug

Search markets:

polymarket markets search "bitcoin" --limit 5

List events (groups of related markets):

polymarket events list --limit 10
polymarket events list --tag politics --active true
polymarket events get 500

Browse tags and categories:

polymarket tags list
polymarket tags get politics
polymarket tags related politics

Sports markets:

polymarket sports list
polymarket sports market-types
polymarket sports teams --league NFL --limit 32

Order Book & Prices (No wallet needed)

Get prices:

polymarket clob price TOKEN_ID --side buy
polymarket clob midpoint TOKEN_ID
polymarket clob spread TOKEN_ID

Batch price queries:

polymarket clob batch-prices "TOKEN1,TOKEN2" --side buy
polymarket clob midpoints "TOKEN1,TOKEN2"
polymarket clob spreads "TOKEN1,TOKEN2"

Order book depth:

polymarket clob book TOKEN_ID
polymarket clob books "TOKEN1,TOKEN2"

Price history:

polymarket clob price-history TOKEN_ID --interval 1d --fidelity 30
# Intervals: 1m, 1h, 6h, 1d, 1w, max

Market metadata:

polymarket clob tick-size TOKEN_ID
polymarket clob fee-rate TOKEN_ID
polymarket clob neg-risk TOKEN_ID
polymarket clob last-trade TOKEN_ID
polymarket clob time
polymarket clob ok       # API health check
polymarket clob geoblock # check if geo-restricted

Trading (Requires wallet)

Place a limit order:

polymarket clob create-order \
  --token TOKEN_ID \
  --side buy --price 0.50 --size 10

Place a market order:

polymarket clob market-order \
  --token TOKEN_ID \
  --side buy --amount 5

Place multiple orders at once:

polymarket clob post-orders \
  --tokens "TOKEN1,TOKEN2" \
  --side buy \
  --prices "0.40,0.60" \
  --sizes "10,10"

Order types: GTC (default), FOK, GTD, FAK. Add --post-only for maker-only limit orders.

Cancel orders:

polymarket clob cancel ORDER_ID
polymarket clob cancel-orders "ORDER1,ORDER2"
polymarket clob cancel-market --market 0xCONDITION_ID
polymarket clob cancel-all

View orders and trades:

polymarket clob orders
polymarket clob orders --market 0xCONDITION_ID
polymarket clob order ORDER_ID
polymarket clob trades

Check balances:

polymarket clob balance --asset-type collateral
polymarket clob balance --asset-type conditional --token TOKEN_ID
polymarket clob update-balance --asset-type collateral

Rewards & Earnings

polymarket clob rewards --date 2026-03-01
polymarket clob earnings --date 2026-03-01
polymarket clob earnings-markets --date 2026-03-01
polymarket clob reward-percentages
polymarket clob current-rewards
polymarket clob market-reward 0xCONDITION_ID

# Check if orders are scoring rewards
polymarket clob order-scoring ORDER_ID
polymarket clob orders-scoring "ORDER1,ORDER2"

Portfolio & On-Chain Data (Public, no wallet needed)

polymarket data positions 0xWALLET_ADDRESS
polymarket data closed-positions 0xWALLET_ADDRESS
polymarket data value 0xWALLET_ADDRESS
polymarket data traded 0xWALLET_ADDRESS
polymarket data trades 0xWALLET_ADDRESS --limit 50
polymarket data activity 0xWALLET_ADDRESS

# Market analytics
polymarket data holders 0xCONDITION_ID
polymarket data open-interest 0xCONDITION_ID
polymarket data volume 12345  # event ID

# Leaderboards
polymarket data leaderboard --period month --order-by pnl --limit 10

Conditional Token Operations (On-chain, needs MATIC)

# Split $10 USDC into YES/NO tokens
polymarket ctf split --condition 0xCONDITION_ID --amount 10

# Merge YES/NO tokens back to USDC
polymarket ctf merge --condition 0xCONDITION_ID --amount 10

# Redeem winning tokens after resolution
polymarket ctf redeem --condition 0xCONDITION_ID

# Redeem neg-risk positions
polymarket ctf redeem-neg-risk --condition 0xCONDITION_ID --amounts "10,5"

# Calculate IDs (read-only, no wallet needed)
polymarket ctf condition-id --oracle 0xORACLE... --question 0xQUESTION... --outcomes 2
polymarket ctf collection-id --condition 0xCONDITION_ID --index-set 1
polymarket ctf position-id --collection 0xCOLLECTION...

Wallet Management

polymarket wallet create
polymarket wallet create --force       # overwrite existing
polymarket wallet import 0xKEY...
polymarket wallet address
polymarket wallet show
polymarket wallet reset

Contract Approvals

polymarket approve check              # check current approvals
polymarket approve set                # approve all contracts (6 txns, needs MATIC)

API Key Management

polymarket clob api-keys           # list API keys
polymarket clob create-api-key     # create new API key
polymarket clob delete-api-key     # delete an API key

Notifications & Account Status

polymarket clob account-status
polymarket clob notifications
polymarket clob delete-notifications "NOTIF1,NOTIF2"

Bridge (Deposits)

polymarket bridge deposit 0xWALLET_ADDRESS
polymarket bridge supported-assets
polymarket bridge status 0xDEPOSIT_ADDRESS

Interactive Shell

polymarket shell
# Launches an interactive REPL with command history.
# All commands work without the `polymarket` prefix:
#   polymarket> markets list --limit 3
#   polymarket> clob book TOKEN_ID
#   polymarket> exit

Utility Commands

polymarket status     # API health check
polymarket setup      # Guided first-time setup wizard
polymarket upgrade    # Update CLI to latest version
polymarket --version
polymarket --help

Output Formats

All commands support --output table (default) and --output json (or -o json).

# Human-readable
polymarket markets list --limit 5

# Machine-readable for scripts
polymarket -o json markets list --limit 5
polymarket -o json clob midpoint TOKEN_ID | jq '.mid'

Common Workflows

Research a market before trading

# 1. Search for markets
polymarket markets search "bitcoin" --limit 5

# 2. Get market details (note the token IDs for YES/NO outcomes)
polymarket markets get bitcoin-above-100k

# 3. Check the order book
polymarket clob book TOKEN_ID

# 4. Check price history
polymarket clob price-history TOKEN_ID --interval 1d

# 5. Check spread and midpoint
polymarket clob spread TOKEN_ID
polymarket clob midpoint TOKEN_ID

Place a limit order and monitor

# 1. Check balance
polymarket clob balance --asset-type collateral

# 2. Place limit order (maker-only for zero fees + rebates)
polymarket clob create-order --token TOKEN_ID --side buy --price 0.45 --size 20 --post-only

# 3. Check if order is scoring rewards
polymarket clob orders
polymarket clob order-scoring ORDER_ID

# 4. Cancel if needed
polymarket clob cancel ORDER_ID

Two-sided market making (reward farming)

# 1. Find a low-competition market
polymarket markets search "niche topic"

# 2. Get YES and NO token IDs from market details
polymarket -o json markets get SLUG | jq '.tokens'

# 3. Place buy orders on both sides
polymarket clob create-order --token YES_TOKEN_ID --side buy --price 0.48 --size 10 --post-only
polymarket clob create-order --token NO_TOKEN_ID --side buy --price 0.48 --size 10 --post-only

# 4. Monitor rewards
polymarket clob current-rewards
polymarket clob order-scoring ORDER_ID

Hedge a position

# If holding YES, buy NO to reduce risk
# Total cost YES + NO should be <= $1.00 for guaranteed profit

# 1. Check current positions
polymarket data positions 0xYOUR_ADDRESS

# 2. Check NO token price
polymarket clob price NO_TOKEN_ID --side buy

# 3. Buy hedge
polymarket clob create-order --token NO_TOKEN_ID --side buy --price 0.48 --size 10

Redeem winnings after market resolves

# 1. Check for resolved positions
polymarket data closed-positions 0xYOUR_ADDRESS

# 2. Redeem
polymarket ctf redeem --condition 0xCONDITION_ID

Scripting with JSON output

# Get all market questions
polymarket -o json markets list --limit 100 | jq '.[].question'

# Check balance programmatically
polymarket -o json clob balance --asset-type collateral | jq '.balance'

# Error handling
if ! result=$(polymarket -o json clob balance --asset-type collateral 2>/dev/null); then
  echo "Failed to fetch balance"
fi

Best Practices

Safety & Risk

Start small — Polymarket trades are real money on Polygon mainnet
Use --post-only — Maker orders have zero fees and earn rebates
Check fee rates — Use polymarket clob fee-rate TOKEN_ID before trading
Verify token IDs — Each YES/NO outcome has a different token ID
Keep MATIC for gas — On-chain operations (approve, split, merge, redeem) need MATIC
Monitor positions — Use polymarket data positions regularly

Order Management

Prefer limit orders — Better price control, zero maker fees
Use --post-only — Ensures your order is a maker order (no taker fees)
Batch when possible — Use clob post-orders to place multiple orders at once
Cancel stale orders — Orders sitting far from mid are not earning rewards
Check order scoring — Use clob order-scoring to verify reward eligibility

Market Making

Two-sided orders earn ~3x rewards — Place on both YES and NO
Stay close to midpoint — Rewards decay quadratically with distance from mid
Low-competition markets — Larger share of the reward pool
Monitor spread — Tighter spreads earn more rewards but increase fill risk
Rebalance regularly — Cancel and replace orders as midpoint moves

Command Reference

Task	Command
List markets	`polymarket markets list --limit 10`
Search markets	`polymarket markets search "query"`
Get market details	`polymarket markets get SLUG_OR_ID`
List events	`polymarket events list --limit 10`
Check price	`polymarket clob price TOKEN_ID --side buy`
Check midpoint	`polymarket clob midpoint TOKEN_ID`
Check spread	`polymarket clob spread TOKEN_ID`
View order book	`polymarket clob book TOKEN_ID`
Price history	`polymarket clob price-history TOKEN_ID --interval 1d`
Place limit order	`polymarket clob create-order --token TOKEN_ID --side buy --price 0.50 --size 10`
Place market order	`polymarket clob market-order --token TOKEN_ID --side buy --amount 5`
Batch orders	`polymarket clob post-orders --tokens "T1,T2" --side buy --prices "0.4,0.6" --sizes "10,10"`
View orders	`polymarket clob orders`
Cancel order	`polymarket clob cancel ORDER_ID`
Cancel all	`polymarket clob cancel-all`
Check balance	`polymarket clob balance --asset-type collateral`
View positions	`polymarket data positions 0xADDRESS`
Check rewards	`polymarket clob current-rewards`
Check earnings	`polymarket clob earnings --date 2026-03-01`
Split USDC to tokens	`polymarket ctf split --condition 0xCOND --amount 10`
Merge tokens to USDC	`polymarket ctf merge --condition 0xCOND --amount 10`
Redeem winnings	`polymarket ctf redeem --condition 0xCOND`
Wallet info	`polymarket wallet show`
Approve contracts	`polymarket approve set`
API health	`polymarket clob ok`
Geo-restriction check	`polymarket clob geoblock`
Account status	`polymarket clob account-status`
List API keys	`polymarket clob api-keys`
CTF condition ID	`polymarket ctf condition-id --oracle 0xORA --question 0xQ --outcomes 2`
Interactive shell	`polymarket shell`
Update CLI	`polymarket upgrade`
Guided setup	`polymarket setup`

Important Notes

Token IDs are long numeric strings (e.g., 48331043336612883...). Get them from market details or order book.
Condition IDs are hex strings (e.g., 0xABC...). Used for on-chain operations and market-level queries.
USDC is the settlement currency. All amounts are in USDC.
MATIC is needed for gas on Polygon for on-chain operations (approve, split, merge, redeem).
Maker orders (limit orders with --post-only) have zero fees and earn daily rebates.
Taker orders pay fees up to ~1.56% at 50/50 odds.
Rewards are distributed daily at midnight UTC. Two-sided orders earn ~3x single-sided.

Troubleshooting

Wallet not configured

# Run guided setup
polymarket setup
# Or create wallet manually
polymarket wallet create

Approvals not set

polymarket approve check  # see what's missing
polymarket approve set    # approve all (needs MATIC)

Insufficient balance

polymarket clob balance --asset-type collateral
# Fund via bridge or direct USDC transfer to your Polygon wallet
polymarket bridge deposit 0xYOUR_ADDRESS

Order rejected

Check balance: polymarket clob balance --asset-type collateral
Verify token ID is correct
Check fee rate: polymarket clob fee-rate TOKEN_ID
Ensure approvals are set: polymarket approve check

Command not found

# Reinstall
brew tap Polymarket/polymarket-cli https://github.com/Polymarket/polymarket-cli
brew install polymarket
# Or: cargo install --path . (from source)

Additional Resources

Polymarket CLI: https://github.com/Polymarket/polymarket-cli
Polymarket Docs: https://docs.polymarket.com/
CLOB API Docs: https://docs.polymarket.com/developers/
Liquidity Rewards: https://docs.polymarket.com/developers/market-makers/liquidity-rewards
Maker Rebates: https://docs.polymarket.com/developers/market-makers/maker-rebates-program

polymarket-trading