Quick start

Run your first commands and generate an interactive price chart

This guide walks you through the essential commands to get started with the Polymarket CLI Research Tool.

Look up an event

Events contain multiple outcome markets. To look up an event, use the slug from the event URL.

1. Find the event slug

   From a Polymarket event URL like:

   https://polymarket.com/event/democratic-presidential-nominee-2028
   

   The slug is the last path segment: democratic-presidential-nominee-2028

2. Run the events command

   Look up the event using JSON output format:

   polymarket -o json events get democratic-presidential-nominee-2028
   

   This returns event metadata including:

   • All outcome markets in the markets array
   • Condition IDs for each outcome
   • Current prices (in the outcomePrices field as a JSON string)
   • Volume and liquidity data

The outcomePrices field is a JSON string that must be parsed separately. If you’re processing the output programmatically, use json.loads() on this field.

Look up a market

Individual binary YES/NO markets use a different command.

1. Identify a market URL

   Market URLs contain /market/ in the path:

   https://polymarket.com/market/will-bitcoin-hit-100k-by-year-end
   

   The slug is: will-bitcoin-hit-100k-by-year-end

2. Run the markets command

   Look up the market:

   polymarket -o json markets get will-bitcoin-hit-100k-by-year-end
   

   This returns a single market object with:

   • Current YES/NO prices
   • Volume and liquidity metrics
   • The condition_id (required for further analysis)

Using events get on a market slug (or vice versa) will return a 404 error. Always match the command to the URL path: /event/ → events get, /market/ → markets get.

Generate a price chart

Create an interactive HTML price chart with multiple time-window tabs.

1. Get the condition ID

   From your event or market lookup, note the condition_id value. It looks like:

   0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75
   
2. Convert to decimal token ID

   The chart script requires a decimal token ID, not the hex condition ID. Get it using:

   polymarket -o json clob market 0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75
   

   The output contains a tokens array:

   {
     "tokens": [
       {
         "token_id": "71321045679065602346747843609838734172500046701793441554156264871781491144591",
         "outcome": "Yes"
       },
       {
         "token_id": "39847950530539906082798520801973142091201919117568609687493690497182515012810",
         "outcome": "No"
       }
     ]
   }
   

   Copy the token_id for the outcome you want to chart (YES or NO).

3. Generate the chart

   Run the chart script with your decimal token ID:

   python3 scripts/chart.py 71321045679065602346747843609838734172500046701793441554156264871781491144591 --title "Bitcoin $100k YES"
   

   The script will:

   1. Fetch recent high-resolution price history
   2. Fetch full historical data with --fidelity 5000
   3. Merge the data into a single timeline
   4. Generate an HTML file
   5. Open it automatically in your browser

If you installed this as a Codex skill, use the full path to the script:

python3 ~/.codex/skills/polymarket/scripts/chart.py <TOKEN_ID> --title "Market Name YES"

Chart features

The generated chart includes:

• 8 time-window tabs: 1H, 6H, 1D, 1W, 1M, 3M, 6M, All
• Interactive tooltips: Hover to see exact price and timestamp
• Zoom and pan: Click and drag to zoom, double-click to reset
• Default view: Opens to the 1W (one week) view

Common workflows

Search for high-volume markets

Find trending markets sorted by volume:

polymarket markets search "" --order volumeNum --limit 20

Use markets search instead of markets list because list always sorts ascending (least useful markets first). The --order parameter requires camelCase: volumeNum, not volume_num.

Find top holders

View the largest position holders for a market:

polymarket -o json data holders 0x0f49db97f71c68b1e42a6d16e3de93d85dbf7d4148e3f018eb79e88554be9f75

The output includes:

• outcome_index: 0 = YES holders
• outcome_index: 1 = NO holders
• Wallet addresses and position sizes

Analyze a wallet's trades

Get trading history for cost-basis analysis:

polymarket -o json data trades 0xYOUR_WALLET_ADDRESS --limit 500

Filter the results by condition_id to analyze positions in a specific market. Calculate:

• Total cost: Sum of (size × price) for all BUY trades
• Total shares: Sum of size for all BUY trades
• Average price: total_cost / total_shares
• Current value: shares_held × current_price
• Win payout: shares_held × $1.00
• ROI if wins: ((payout - cost) / cost) × 100

Get current price history

Fetch recent price data at maximum resolution:

polymarket -o json clob price-history --interval max <DECIMAL_TOKEN_ID>

For full historical data with lower resolution:

polymarket -o json clob price-history --interval max --fidelity 5000 <DECIMAL_TOKEN_ID>

Key gotchas

Avoid these common mistakes:

• Wrong command → 404: Match the command to the URL path (/event/ vs /market/)
• Token IDs must be decimal: Never use hex 0x... format for CLOB commands
• outcomePrices is a string: Parse it with json.loads() when processing event data
• Ordering is camelCase: Use volumeNum, not volume_num (causes 422 error)
• Sum of YES prices ≈ 1.01: Normal 1% house edge, not an error

Troubleshooting

No price history returned

Confirm you’re using a decimal CLOB token ID, not hex. Get it via:

polymarket -o json clob market <CONDITION_ID>

Read the token_id field from the tokens array (not the hex condition ID).

Browser doesn't open automatically

The chart script prints the HTML file path. Open it manually:

open /path/to/chart.html  # macOS
xdg-open /path/to/chart.html  # Linux

422 error when searching markets

The --order parameter requires camelCase:

# ✓ Correct
polymarket markets search "crypto" --order volumeNum

# ✗ Wrong
polymarket markets search "crypto" --order volume_num

Next steps

Now that you’ve run your first commands:

• Explore different markets and generate charts for price analysis
• Use holder analysis to understand market positioning
• Analyze wallet trades to calculate cost basis and ROI
• Search for trending markets using volume sorting

View full command reference

See all available commands and options