Skill: antonelli182/sports-skills-polymarket (version 1.0.0)

--- name: polymarket description: | Polymarket sports prediction markets — live odds, prices, order books, events, series, and market search. No auth required. Covers NFL, NBA, MLB, football (EPL, UCL, La Liga), tennis, cricket, MMA, esports. Supports moneyline, spreads, totals, and player props. Use when: user asks about sports betting odds, prediction markets, win probabilities, market sentiment, or "who is favored to win" questions. Don't use when: user asks about actual match results, scores, or statistics — use the sport-specific skill: football-data (soccer), nfl-data (NFL), nba-data (NBA), wnba-data (WNBA), nhl-data (NHL), mlb-data (MLB), tennis-data (tennis), golf-data (golf), cfb-data (college football), cbb-data (college basketball), or fastf1 (F1). Don't use for historical match data. Don't use for news — use sports-news instead. Don't confuse with Kalshi — Polymarket focuses on crypto-native prediction markets with deeper sports coverage; Kalshi is a US-regulated exchange with different market structure. license: MIT metadata: author: machina-sports version: "0.3.0" --- # 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: ```bash 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): ```python 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`: ```bash pip install sports-skills[polymarket] ``` Additionally requires a configured wallet: ```bash 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 | Command | Description | |---|---| | `get_sports_config` | Available sport codes | | `get_todays_events` | Today's events for a league | | `search_markets` | Find markets by sport, keyword, and type | | `get_sports_markets` | Browse all sports markets | | `get_sports_events` | Browse sports events | | `get_series` | List series (leagues) | | `get_market_details` | Single market details | | `get_event_details` | Single event details | | `get_market_prices` | Current CLOB prices | | `get_order_book` | Full order book | | `get_price_history` | Historical prices | | `get_last_trade_price` | Most recent trade | 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` is not installed or wallet is not configured Solution: Run `pip install sports-skills[polymarket]` and set `POLYMARKET_PRIVATE_KEY` environment variable


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)