Polymarket

Polymarket — Sports Prediction Markets

Quick Start

Prefer the CLI — it avoids Python import path issues:

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

Python SDK (alternative):

from sports_skills import polymarket

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

Prerequisites

Core commands (11 commands) work out of the box — no dependencies, no API keys.

CLI commands (30+ commands) require the Polymarket CLI binary:

pip install sports-skills[polymarket]

Or via Homebrew:

brew tap Polymarket/polymarket-cli https://github.com/Polymarket/polymarket-cli
brew install polymarket

Trading commands additionally require a configured wallet. Three options:

# Option 1 — environment variable
export POLYMARKET_PRIVATE_KEY=0x...

# Option 2 — Python SDK (per-session)
from sports_skills import polymarket
polymarket.configure(private_key="0x...")

# Option 3 — CLI config file (persists across sessions)
polymarket wallet import <private-key>
polymarket approve set

If a CLI command returns "polymarket CLI not installed", install with pip install sports-skills[polymarket].

Important Notes

• Prices are probabilities. A price of 0.65 means 65% implied probability. No conversion needed.
• `token_id` vs `market_id`: Price and orderbook endpoints require the CLOB token_id, not the Gamma market_id. Always call get_market_details first to get clobTokenIds.
• `search_markets` matches event titles, not sport categories. Use specific league names ("Premier League", "Champions League"), not generic terms ("soccer", "football").
• `cli_search_markets` is a more powerful full-text search via the CLI binary. Use it when search_markets returns no results.
• Before complex fetches, run the parameter validator: bash scripts/validate_params.sh <command> [args]

For detailed reference data, see the files in the `references/` directory.

Workflows

Workflow: Live Odds Check

1. search_markets --query="<league/event name>" 2. get_market_details --market_id=<id> to get CLOB token IDs. 3. get_market_prices --token_id=<id> 4. Present probabilities.

Workflow: Event Overview

1. get_sports_events --active=true 2. Pick event, then get_event_details --event_id=<id>. 3. For each market, get prices.

Workflow: Price Trend Analysis

1. Find market via search_markets. 2. get_market_details for token_id. 3. get_price_history --token_id=<id> --interval=1w 4. Present price movement.

Workflow: Portfolio Analysis (requires CLI)

1. get_positions --address=<wallet> — open positions 2. get_portfolio_value --address=<wallet> — total value 3. get_trade_history --address=<wallet> --limit=20 — recent trades 4. get_activity --address=<wallet> — full activity feed

Workflow: Market Analytics (requires CLI)

1. get_holders --condition_id=<id> — who holds positions 2. get_open_interest --condition_id=<id> — total interest 3. get_volume --event_id=<id> — volume data

Workflow: Leaderboard (requires CLI)

1. get_leaderboard --period=week --order_by=pnl --limit=20 2. get_profile --address=<top_trader_address> — inspect top traders

Workflow: Trading (requires CLI + wallet)

1. get_balance --asset_type=collateral — check USDC balance 2. cli_search_markets --query="NBA" — find markets 3. get_market_details --market_id=<id> — get token_id 4. create_order --token_id=<id> --side=buy --price=0.55 --size=10 5. get_orders — verify order placed 6. cancel_order --order_id=<id> — cancel if needed

Commands Reference

Core Commands (no CLI needed)

CLI Commands: Data & Analytics

CLI Commands: Search, Tags & Discovery

CLI Commands: Comments & Profiles

CLI Commands: Sports Metadata

CLI Commands: CLOB Extras

CLI Commands: Trading (requires wallet)

CLI Commands: On-Chain (requires wallet)

Examples

User: "Who's favored to win the NBA Finals?" 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)

User: "Who will win the Premier League?" 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)

User: "Show me Champions League odds" 1. Call search_markets(query="Champions League") 2. Present top contenders with prices, volume, and liquidity

User: "Show me the Polymarket leaderboard" 1. Call get_leaderboard(period="week", order_by="pnl", limit=20) 2. Present traders with rank, username, PnL, and volume

User: "What positions does this wallet hold?" 1. Call get_positions(address="0x...") 2. Present positions with outcome, size, avg price, current value, PnL

User: "Buy 10 shares of YES on this market" 1. Call get_market_details(market_id="...") to get token_id 2. Call create_order(token_id="...", side="buy", price="0.55", size="10") 3. Call get_orders() to confirm

Error Handling & Fallbacks

• If search returns 0 results, try full league names ("English Premier League" not "EPL", "Champions League" not "CL"). search_markets matches event titles.
• If get_market_prices fails, you likely used market_id instead of token_id. Always call get_market_details first to get CLOB token_id.
• If prices seem stale, check get_last_trade_price for the most recent trade. Low-liquidity markets may have wide spreads.
• If a CLI command returns "polymarket CLI not installed", the command requires the Rust binary. The original 11 commands work without the CLI.
• If a trading command fails with an auth error, ensure a wallet is configured: polymarket wallet create && polymarket approve set.
• Never fabricate odds or probabilities. If no market exists, state so.

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.
• Polymarket CLI (polymarket binary): Full platform access via subprocess. Requires separate installation (brew install polymarket). Supports all Gamma, CLOB, Data, CTF, and trading operations via -o json output. Used for: leaderboard, positions, portfolio, trading, on-chain ops, comments, profiles, full-text search, tags, sports metadata.

Valid Commands & Common Mistakes

Core Commands (no CLI needed)

These work out of the box with no external dependencies:

• get_sports_markets
• get_sports_events
• get_series
• get_market_details
• get_event_details
• get_market_prices
• get_order_book
• get_sports_market_types
• search_markets
• get_price_history
• get_last_trade_price

CLI Commands: Data & Analytics (requires polymarket binary)

• get_leaderboard — trader leaderboard (period, order_by, limit)
• get_positions — open positions by wallet address
• get_closed_positions — closed positions by wallet address
• get_portfolio_value — portfolio value by wallet address
• get_trade_history — trade history by wallet address
• get_activity — activity feed by wallet address
• get_holders — market position holders by condition_id
• get_open_interest — open interest by condition_id
• get_volume — volume by event_id
• get_traded — markets traded by wallet address

CLI Commands: Search & Tags (requires polymarket binary)

• cli_search_markets — full-text search (more powerful than search_markets)
• get_tags — list all tags
• get_tag — tag details
• get_related_tags — related tags

CLI Commands: Comments & Profiles (requires polymarket binary)

• get_comments — comments on an entity (entity_type + entity_id)
• get_comment — single comment by ID
• get_user_comments — comments by user address
• get_profile — public user profile by address

CLI Commands: Sports Metadata (requires polymarket binary)

• cli_sports_list — list all sports
• cli_sports_teams — teams by league

CLI Commands: CLOB Extras (requires polymarket binary)

• get_tick_size — minimum tick size by token_id
• get_fee_rate — fee rate by token_id

CLI Commands: Trading (requires polymarket binary + wallet)

• 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_balance — check wallet balance
• get_orders — view open orders
• get_user_trades — view your trades

CLI Commands: On-Chain (requires polymarket binary + wallet)

• ctf_split — split USDC into YES/NO tokens (condition_id, amount)
• ctf_merge — merge YES/NO tokens back to USDC (condition_id, amount)
• ctf_redeem — redeem winning tokens (condition_id)
• approve_check — check contract approvals
• approve_set — approve all contracts for trading

Commands that DO NOT exist (commonly hallucinated)

• ~~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).

Other common mistakes

• 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 "soccer" or "football" -- search_markets matches event titles. Use specific league names: "Premier League", "Champions League", "La Liga", etc.
• 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.