Skip to main content
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

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.
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
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
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

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).
The chart script prints the HTML file path. Open it manually:
open /path/to/chart.html  # macOS
xdg-open /path/to/chart.html  # Linux
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

Build docs developers (and LLMs) love

Get started for freeTalk to us