Polymarket

Polymarket — Sports Prediction Markets

Before writing queries, consult references/api-reference.md for sport codes, command parameters, and price format.

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 parameter:

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-v2:

pip install sports-skills[polymarket]

Additionally requires a configured wallet:

export POLYMARKET_PRIVATE_KEY=0x...
# Only for proxy / email (Magic) wallets, where the signer differs from the
# funds holder. EOA wallets don't need it.
export POLYMARKET_FUNDER_ADDRESS=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

See references/api-reference.md for full parameter lists and return shapes.

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, it does not exist.

Troubleshooting

Error: search_markets returns 0 results Cause: The sport parameter is missing — without it, search only checks high-volume markets and misses single-game events Solution: Always pass sport='<code>' to search_markets. Check references/api-reference.md for valid sport codes

Error: get_market_prices fails or returns wrong data Cause: market_id (Gamma) was used instead of token_id (CLOB) Solution: Call get_market_details(market_id=<id>) first to get the CLOB clobTokenIds, then use those with 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>) for the most recent actual trade price

Error: Trading commands fail Cause: py-clob-client-v2 is not installed or wallet is not configured Solution: Run pip install sports-skills[polymarket] and set POLYMARKET_PRIVATE_KEY environment variable

Polymarket — API Reference

Core Commands (no dependencies needed)

Trading Commands (requires py-clob-client-v2 + wallet)

Sport Codes (Common)

Run get_sports_config() for the full list of 120+ sport codes.

Price Format

Prices on Polymarket are probabilities on a 0-1 scale:

• Price of 0.65 = 65% implied probability
• No conversion needed
• token_id (CLOB) is required for price/orderbook endpoints — use get_market_details to get clobTokenIds from a market_id

See references/api.md and references/commands.md for extended documentation.

Polymarket APIs

• Gamma API (gamma-api.polymarket.com): Market metadata, events, series. Public, no auth. Used by core commands.
• CLOB API (clob.polymarket.com): Prices, order books, trades. Public reads, no auth. Used by core commands.
• py-clob-client-v2 (Python SDK): Trading operations (create/cancel orders, view trades). Requires pip install sports-skills[polymarket] and a wallet private key. No CLI binary needed.

Valid Commands & Common Mistakes

CRITICAL: Always use the sport parameter

For single-game markets, ALWAYS pass sport='<code>' to search_markets and get_todays_events.

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

Core Commands (no dependencies needed)

These work out of the box:

• get_sports_config — list all available sport codes (nba, epl, nfl, bun, etc.)
• get_todays_events — today's events for a specific sport (requires sport param)
• search_markets — find markets by sport, keyword, and type (use sport param for single-game markets)
• get_sports_markets — browse all sports markets (sorted by volume)
• get_sports_events — browse sports events (sorted by volume)
• get_series — list series (leagues)
• get_market_details — single market details (by market_id or slug)
• get_event_details — single event details with nested markets
• get_market_prices — current CLOB prices (requires token_id)
• get_order_book — full order book (requires token_id)
• get_sports_market_types — valid market types
• get_price_history — historical prices (requires token_id)
• get_last_trade_price — most recent trade (requires token_id)

Trading Commands (requires py-clob-client-v2 + wallet)

• configure — set wallet private key
• create_order — place a limit order (token_id, side, price, size)
• market_order — place a market order (token_id, side, amount)
• cancel_order — cancel an order by ID
• cancel_all_orders — cancel all open orders
• get_orders — view open orders
• get_user_trades — view your trades

Key Usage Patterns

Finding single-game markets (MOST COMMON)

# Use the sport parameter — this is the key to finding single-game markets
sports-skills polymarket search_markets --sport=nba --sports_market_types=moneyline
sports-skills polymarket search_markets --sport=epl --query="Leeds"
sports-skills polymarket get_todays_events --sport=nba

Discovering sport codes

sports-skills polymarket get_sports_config
# Returns: nba, epl, nfl, bun, fl1, ucl, mls, atp, wta, and 110+ more

Commands that DO NOT exist (commonly hallucinated)

• ~~cli_search_markets~~ — does not exist. Use search_markets instead.
• ~~cli_sports_list~~ / ~~cli_sports_teams~~ — do not exist. Use get_sports_config and search_markets(sport=...).
• ~~get_market_odds~~ / ~~get_odds~~ — market prices ARE the implied probability. Use get_market_prices(token_id="...") where price = probability.
• ~~get_implied_probability~~ — the price IS the implied probability. No conversion needed.
• ~~get_current_odds~~ — use get_last_trade_price(token_id="...") for the most recent price.
• ~~get_markets~~ — the correct command is get_sports_markets (for browsing) or search_markets (for searching by keyword/sport).
• ~~get_leaderboard~~ / ~~get_positions~~ / ~~get_holders~~ / ~~get_balance~~ — not available.
• ~~get_team_schedule~~ — this is a football-data command, not polymarket.

Other common mistakes

• Not using the `sport` parameter — without it, search_markets only checks high-volume markets and misses single-game events. Always pass sport='nba' (or epl, nfl, etc.) when looking for specific game markets.
• Using market_id where token_id is needed — price and orderbook endpoints require the CLOB token_id, not the Gamma market_id. Always call get_market_details first to get clobTokenIds.
• Searching generic terms like "football" or "Premier League" without sport — use the sport code parameter instead (e.g. sport='epl').
• Forgetting to get the token_id before calling price/orderbook endpoints — always fetch market details first.

If you're unsure whether a command exists, check this list. Do not try commands that aren't listed above.