Markets

Markets Orchestration

Bridges ESPN live schedules (NBA, NFL, MLB, NHL, WNBA, CFB, CBB) with Kalshi and Polymarket prediction markets. Before writing queries, consult references/api-reference.md for supported sport codes, command parameters, and price normalization formats.

Quick Start

sports-skills markets get_todays_markets --sport=nba
sports-skills markets search_entity --query="Lakers" --sport=nba
sports-skills markets compare_odds --sport=nba --event_id=401234567
sports-skills markets get_sport_markets --sport=nfl
sports-skills markets get_sport_schedule --sport=nba
sports-skills markets normalize_price --price=0.65 --source=polymarket
sports-skills markets evaluate_market --sport=nba --event_id=401234567
sports-skills markets match_markets --sport=mlb --date=2026-06-06
sports-skills markets get_market_price --venue=kalshi --ticker=KXMENWORLDCUP-26-FR
sports-skills markets get_price_history --venue=kalshi --ticker=KXMENWORLDCUP-26-FR --interval=1d

Python SDK:

from sports_skills import markets

markets.get_todays_markets(sport="nba")
markets.search_entity(query="Lakers", sport="nba")
markets.compare_odds(sport="nba", event_id="401234567")
markets.get_sport_markets(sport="nfl")
markets.get_sport_schedule(sport="nba", date="2025-02-26")
markets.normalize_price(price=0.65, source="polymarket")
markets.evaluate_market(sport="nba", event_id="401234567")
markets.match_markets(sport="mlb", date="2026-06-06")
markets.get_market_price(venue="kalshi", ticker="KXMENWORLDCUP-26-FR", at_time="2026-05-01T12:00:00+00:00")
markets.get_price_history(venue="polymarket", token_id="<token_id>", interval="1h")

CRITICAL: Before Any Query

CRITICAL: Before calling any orchestration command, verify:

• A sport code is provided for sport-aware commands (get_todays_markets, compare_odds, get_sport_markets, evaluate_market).
• Price sources are identified correctly before normalization: espn = American odds, polymarket = 0-1 probability, kalshi = 0-100 integer.

Important Notes

• Sport context is passed through. --sport=nba maps automatically to the correct Polymarket sport code and Kalshi series ticker.
• Both platforms use sport-aware search. Polymarket uses sport → series_id; Kalshi uses KXNBA, KXNFL, etc.
• Prices are normalized. Everything is converted to implied probability for comparison.

Workflows

Today's NBA Dashboard

sports-skills markets get_todays_markets --sport=nba

Returns each game with ESPN info, DraftKings odds, matching Kalshi markets, and matching Polymarket markets.

Find Arb on a Specific Game

1. Get the ESPN event ID: get_sport_schedule --sport=nba 2. Compare odds: compare_odds --sport=nba --event_id=<id> 3. If arbitrage detected, response includes allocation percentages and guaranteed ROI.

Full Bet Evaluation

1. evaluate_market --sport=nba --event_id=<id> 2. Fetches ESPN odds and matching prediction market price 3. Pipes through betting.evaluate_bet: devig → edge → Kelly 4. Returns fair probability, edge, EV, Kelly fraction, and recommendation

Same Game on Both Venues

1. match_markets --sport=mlb --date=2026-06-06 2. Each match pairs the Kalshi event (with market tickers) and the Polymarket event (with moneyline token IDs) for the same game — joined deterministically on date + team codes, fuzzy title match as fallback. 3. Feed kalshi.market_tickers[i] and polymarket.markets[i].token_ids[j] straight into get_market_price to compare prices.

Price Movement Over Time

1. get_market_price --venue=kalshi --ticker=<ticker> --at_time=2026-05-01 for a single point-in-time price (both yes/no sides, 0-1). 2. get_price_history --venue=kalshi --ticker=<ticker> --interval=1d for the full series — same {timestamp, price} shape on either venue.

Examples

Example 1: Today's games with prediction market odds User says: "What NBA games are on today and what are the prediction market odds?" Actions: 1. Call get_todays_markets(sport="nba") Result: Unified dashboard with each game's ESPN info and Kalshi/Polymarket prices

Example 2: Cross-platform team search User says: "Find me Lakers markets on Kalshi and Polymarket" Actions: 1. Call search_entity(query="Lakers", sport="nba") Result: All Lakers markets across both exchanges with prices and volume

Example 3: Odds comparison for a specific game User says: "Compare the odds for this Celtics game across ESPN and Polymarket" Actions: 1. Get event_id from get_sport_schedule(sport="nba") 2. Call compare_odds(sport="nba", event_id="<id>") Result: Normalized side-by-side comparison with automatic arbitrage check

Example 4: Full market evaluation User says: "Is there edge on the Chiefs game?" Actions: 1. Get event_id from get_sport_schedule(sport="nfl") 2. Call evaluate_market(sport="nfl", event_id="<id>") Result: Fair probability, edge percentage, EV, Kelly fraction, and bet recommendation

Example 5: Browse all markets for a sport User says: "Show me all NFL prediction markets" Actions: 1. Call get_sport_markets(sport="nfl") Result: All open NFL markets across Kalshi and Polymarket

Example 6: Price conversion User says: "Convert a Polymarket price of 65 cents to American odds" Actions: 1. Call normalize_price(price=0.65, source="polymarket") Result: Common structure with implied probability (0.65), American odds (-185.7), and decimal (1.54)

Example 7: Pair a game across venues User says: "Find the Mets game on both Kalshi and Polymarket" Actions: 1. Call match_markets(sport="mlb", date="<game date>") Result: The game paired across venues — Kalshi market tickers and Polymarket moneyline token IDs side by side

Example 8: Historical price User says: "What was France's World Cup price a month ago?" Actions: 1. Call get_market_price(venue="kalshi", ticker="KXMENWORLDCUP-26-FR", at_time="2026-05-03T12:00:00+00:00") Result: Yes/no prices (0-1) as of that moment; use get_price_history for the full curve

Commands that DO NOT exist — never call these

• ~~get_odds~~ — does not exist. Use compare_odds to see odds across sources.
• ~~search_markets~~ — does not exist on the markets module. Use search_entity instead.
• ~~get_schedule~~ — does not exist. Use get_sport_schedule instead.

If a command is not listed in references/api-reference.md, it does not exist.

Troubleshooting

Error: No markets returned for a sport Cause: Sport code may be missing or incorrect Solution: Check references/api-reference.md for valid sport codes. Use the exact code (e.g., nba, epl, laliga)

Error: compare_odds returns no data for an event Cause: The event_id is incorrect or the game has not been indexed yet Solution: Call get_sport_schedule(sport=...) to retrieve the correct event_id first

Error: One source shows warnings in the response Cause: Kalshi or Polymarket is temporarily unavailable Solution: The module returns partial results — use what is available. Retry the unavailable source separately using the kalshi or polymarket skill directly

Error: normalize_price returns unexpected American odds value Cause: Wrong source parameter — Kalshi uses 0-100 integers, Polymarket uses 0-1 decimals Solution: Verify the source. Kalshi price of 65 requires source="kalshi", Polymarket price of 0.65 requires source="polymarket"

Markets Orchestration — API Reference

Commands

match_markets notes

• sport must exist on both venues: mlb, nfl, nba, nhl, wnba, cfb, cbb, epl, ucl, laliga, bundesliga, seriea, ligue1, mls, worldcup.
• Each match returns kalshi.market_tickers and polymarket.markets[] (moneyline markets with token_ids and outcomes). US-league games have one moneyline market with team-named outcomes; soccer games have several binary ones (home/away/draw).
• match_method is code (deterministic identifier join) or title (fuzzy fallback — used when the venues' team codes differ, e.g. World Cup ISO vs FIFA country codes).
• unmatched lists games seen on only one venue (listing windows differ).

get_market_price / get_price_history notes

• at_time, start_time, end_time accept Unix timestamps or ISO 8601 datetimes.
• Historical Kalshi prices come from candlesticks (hourly within 7 days of at_time, daily within 31); Polymarket from CLOB price history.
• All prices are 0-1 probabilities for the YES side regardless of venue — no unit conversion needed downstream.

Supported Sports

US Sports (with ESPN schedules)

Football (prediction markets only — no ESPN schedule)

Price Normalization

Different sources use different formats. normalize_price converts any format to a common structure.

Normalized output shape:

{
  "implied_probability": 0.65,
  "american": -185.7,
  "decimal": 1.5385,
  "source": "polymarket"
}

Partial Results Behavior

If one source is unavailable, the module returns what it has with warnings:

{
  "status": true,
  "data": {
    "games": [],
    "warnings": ["Kalshi search failed: connection timeout"]
  }
}