Polymarket — Sports Prediction Markets

Setup

which sports-skills || pip install sports-skills

pip install

python3 --version  # check version
# If < 3.10, try: python3.12 -m pip install sports-skills
# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills

Quick Start

sports-skills polymarket get_sports_markets --limit=20
sports-skills polymarket search_markets --query="NBA Finals"

from sports_skills import polymarket

markets = polymarket.get_sports_markets(limit=20)
prices = polymarket.get_market_prices(token_id="abc123")

Commands

get_sports_markets

• limit

  (int, optional): Max results (default: 50, max: 100)

• offset

  (int, optional): Pagination offset

• sports_market_types

  (str, optional): Filter by type ("moneyline", "spreads", "totals")

• game_id

  (str, optional): Filter by game

• active

  (bool, optional): Only active markets (default: true)

• closed

  (bool, optional): Include closed markets (default: false)

• order

  (str, optional): Sort field (default: "volume")

• ascending

  (bool, optional): Sort ascending (default: false)

get_sports_events

• limit

  ,

  offset

  ,

  active

  ,

  closed

  ,

  order

  ,

  ascending

  (same as above)

• series_id

  (str, optional): Filter by series (league) ID

get_series

• limit

  (int, optional): Max results (default: 100)

• offset

  (int, optional): Pagination offset

get_market_details

• market_id

  (str): Market ID

• slug

  (str): Market slug (alternative to ID)

get_event_details

• event_id

  (str): Event ID

• slug

  (str): Event slug (alternative to ID)

get_market_prices

• token_id

  (str): Single CLOB token ID

• token_ids

  (list): Multiple CLOB token IDs (batch)

get_order_book

• token_id

  (str, required): CLOB token ID

get_sports_market_types

search_markets

• query

  (str, optional): Keyword to search — use league names (e.g., "Premier League", "Champions League", "La Liga", "NBA Finals")

• sports_market_types

  (str, optional): Filter by type

• tag_id

  (int, optional): Tag ID (default: 1 = Sports)

• limit

  (int, optional): Max results (default: 20)

get_price_history

• token_id

  (str, required): CLOB token ID

• interval

  (str, optional): Time range ("1d", "1w", "1m", "max"). Default: "max"

• fidelity

  (int, optional): Seconds between data points. Default: 120

get_last_trade_price

• token_id

  (str, required): CLOB token ID

Examples

1. Call

   search_markets(query="NBA Finals", sports_market_types="moneyline")

2. Get

   token_id

   from the market details
3. Call

   get_market_prices(token_id="...")

   for current odds
4. Present teams with implied probabilities (price = probability)

1. Call

   search_markets(query="English Premier League")

   — use full league name
2. Sort results by Yes outcome price descending
3. Present teams with implied probabilities (price = probability)

1. Call

   search_markets(query="Champions League")

2. Present top contenders with prices, volume, and liquidity

1. Call

   get_order_book(token_id="...")

   for full book
2. Present bids, asks, spread, and implied probabilities

Troubleshooting

• sports-skills

  command not found: Package not installed. Run

  pip install sports-skills

  . If pip fails with a Python version error, you need Python 3.10+ — see Setup section.

• ModuleNotFoundError: No module named 'sports_skills'

  : Same as above — install the package. Prefer the CLI over Python imports to avoid path issues.
• token_id vs market_id: Price/orderbook endpoints need the CLOB

  token_id

  (found in market details under

  clobTokenIds

  ), not the Gamma

  market_id

  . Always fetch market details first to get the token_id.
• Search returns 0 results:

  search_markets

  matches event titles, not sport categories. Don't search "soccer" or "football" — search by league name: "Premier League", "Champions League", "La Liga", "Bundesliga", "Serie A", "NBA Finals", etc.
• Market not found by ID: Use

  search_markets(query="...")

  with keywords instead of guessing IDs. Or use

  get_market_details(slug="...")

  with the URL slug.
• Stale or wide prices: Low-liquidity markets may have wide bid-ask spreads. The

  mid

  price from

  get_market_prices

  is the midpoint — check

  spread

  to assess reliability.
• Pagination: Use

  offset

  parameter for paging. Default

  limit

  varies by endpoint (20-100). Increment offset by limit for each page.

APIs

• Gamma API (gamma-api.polymarket.com): Market metadata, events, series. Public, no auth.
• CLOB API (clob.polymarket.com): Prices, order books, trades. Public reads, no auth.