Polymarket — Sports Prediction Markets

Before writing queries, consult

references/api-reference.md

Quick Start

Prefer the CLI — it avoids Python import path issues:

sports-skills polymarket search_markets --sport=nba --sports_market_types=moneyline
sports-skills polymarket get_todays_events --sport=epl
sports-skills polymarket search_markets --sport=epl --query="Leeds" --sports_market_types=moneyline
sports-skills polymarket get_sports_config

Python SDK (alternative):

from sports_skills import polymarket

polymarket.search_markets(sport='nba', sports_market_types='moneyline')
polymarket.get_todays_events(sport='epl')
polymarket.search_markets(sport='epl', query='Leeds')
polymarket.get_sports_config()

CRITICAL: Before Any Query

CRITICAL: Before calling any market endpoint, verify:

• The

  sport

  parameter is always passed to

  search_markets

  and

  get_todays_events

  for single-game markets.
• Prices are probabilities on a 0-1 scale (0.65 = 65%) — no conversion needed.
• For price/orderbook endpoints, use

  token_id

  (CLOB), not

  market_id

  (Gamma). Call

  get_market_details

  first to get

  clobTokenIds

  .

Without the

sport

WRONG: search_markets(query="Leeds")           → 0 results
RIGHT: search_markets(sport='epl', query='Leeds') → returns all Leeds markets

Prerequisites

Core commands (no dependencies, no API keys): All read commands work out of the box.

Trading commands require

py_clob_client

pip install sports-skills[polymarket]

Additionally requires a configured wallet:

export POLYMARKET_PRIVATE_KEY=0x...

Workflows

Find Single-Game Markets for a Sport

1. search_markets --sport=nba

   (or epl, nfl, bun, etc.)
2. Each market includes outcomes with prices (price = probability).
3. For detailed prices, use

   get_market_prices --token_id=<clob_token_id>

   .

Today's Events for a League

1. get_todays_events --sport=epl

   — returns events sorted by start date.
2. Each event includes nested markets (moneyline, spreads, totals, props).
3. Pick a market, get

   clob_token_id

   from outcomes, then

   get_market_prices

   .

Live Odds Check

1. search_markets --sport=nba --query="Lakers" --sports_market_types=moneyline

2. get_market_prices --token_id=<id>

   for live CLOB prices.
3. Present probabilities.

Price Trend Analysis

1. Find market via

   search_markets --sport=nba

   .
2. Get

   clob_token_id

   from the outcomes.

3. get_price_history --token_id=<id> --interval=1w

4. Present price movement.

Commands

get_sports_config

get_todays_events

search_markets

get_sports_markets

get_sports_events

get_series

get_market_details

get_event_details

get_market_prices

get_order_book

get_price_history

get_last_trade_price

See

references/api-reference.md

Examples

Example 1: Tonight's NBA favorites User says: "Who's favored in tonight's NBA games?" Actions:

1. Call

   search_markets(sport='nba', sports_market_types='moneyline')

   Result: Each matchup with implied win probabilities (price = probability)

Example 2: Team-specific odds User says: "Show me Leeds vs Man City odds" Actions:

1. Call

   search_markets(sport='epl', query='Leeds', sports_market_types='moneyline')

   Result: Leeds moneyline market with outcome prices

Example 3: Today's EPL events User says: "What EPL matches are on today?" Actions:

1. Call

   get_todays_events(sport='epl')

   Result: Today's EPL events with nested markets (moneyline, spreads, totals, props)

Example 4: League winner futures User says: "Who will win the Premier League?" Actions:

1. Call

   search_markets(query='Premier League')

   — returns futures
2. Sort results by Yes outcome price descending Result: Top contenders ranked by win probability

Example 5: Bundesliga odds User says: "Show me Bundesliga odds for Dortmund vs Bayern" Actions:

1. Call

   search_markets(sport='bun', query='Dortmund', sports_market_types='moneyline')

   Result: Dortmund/Bayern moneyline market with outcome prices

Commands that DO NOT exist — never call these

• cli_search_markets

  — does not exist. Use

  search_markets

  instead.

• cli_sports_list

  — does not exist. Use

  get_sports_config

  instead.

• get_market_odds

  /

  get_odds

  /

  get_current_odds

  — prices ARE probabilities. Use

  get_market_prices(token_id=...)

  .

• get_implied_probability

  — the price IS the implied probability.

• get_markets

  — use

  get_sports_markets

  (browse) or

  search_markets

  (search).

• get_team_schedule

  — this is a football-data command, not polymarket.

If a command is not listed in

references/api-reference.md

Troubleshooting

Error:

search_markets

sport

sport='<code>'

search_markets

references/api-reference.md

Error:

get_market_prices

market_id

token_id

get_market_details(market_id=<id>)

clobTokenIds

get_market_prices

Error: Prices seem stale or unchanged Cause: Low-liquidity market — may have wide spreads and infrequent trades Solution: Check

get_last_trade_price(token_id=<id>)

Error: Trading commands fail Cause:

py_clob_client

pip install sports-skills[polymarket]

POLYMARKET_PRIVATE_KEY