Prediction Markets

Prediction Markets (Kalshi + Polymarket) — read-only market data

Everything here is read-only public data. No auth, no keys, no trading. All scripts: Python 3.10+ stdlib only, run as python3 scripts/.py … or directly (executable).

Script routing

| You need | Run | Notes | |---|---|---| | Find Kalshi markets (by text, event, series, status) | scripts/kalshi_markets.py --query "cpi" --series KXCPI | --ticker T for one market. Kalshi has NO server-side text search: bare --query scans up to --max-pages×1000 markets (~5s/page) and reports truncation in the output's scan object — narrow with --series/--event whenever you can | | Kalshi orderbook, spread, depth | scripts/kalshi_orderbook.py TICKER --depth 10 | asks derived from opposite bids (see gotchas) | | Kalshi price history (OHLC) | scripts/kalshi_candles.py TICKER --period 60 --start 2026-07-01 | --period ∈ {1,60,1440} min; auto-resolves series (2 extra GETs) | | Find Polymarket markets | scripts/poly_markets.py --query "fed" --active | --slug S for one market; full-text via Gamma /public-search | | Polymarket orderbook, spread, midpoint | scripts/poly_orderbook.py --slug market-slug | or --token-id N; --outcome no for the NO token | | Polymarket price history | scripts/poly_history.py --slug market-slug --interval 1w | or --start/--end; points are {t, iso, p} | | Same event on both venues + spread | scripts/match_markets.py --query "fed december" | v0 heuristic matcher — verify pairs manually |

Every script: --help has 3+ runnable examples; --timeout (default 15s); retries 429/5xx with 1s/2s/4s backoff; paginates to exhaustion or --limit.

Output contract (all scripts)

stdout = single JSON: {"venue", "endpoint", "params", "fetched_at", "count", "data"}. Errors: one JSON line on stderr {"error": {"category", "message", "hint"}} + exit code: 2 usage · 3 network · 4 rate-limited · 5 geo-blocked · 6 not found · 7 schema surprise. Exit 0 with count: 0 = valid empty result (e.g. no matches), not an error.

Workflows

"What's the probability of X?"

1. kalshi_markets.py --query "X" --status open and/or poly_markets.py --query "X" --active.
2. Each row already carries implied_probability (float 0–1, from bid/ask midpoint or last).
3. Quote it as a percentage; name the market title and venue. If several markets match

(different thresholds/dates), list them — don't silently pick one.

"How liquid is it / what's the real cost to trade?"

1. Get the market: discovery scripts above → ticker (Kalshi) or slug/token_id (Polymarket).
2. kalshi_orderbook.py TICKER / poly_orderbook.py --slug S → summary has best bid/ask,

spread, midpoint, implied_probability, depth totals.

1. Wide spread or thin depth = the midpoint probability is soft. Say so.

"Compare venues / is there a price gap?"

1. match_markets.py --query "topic" --top 5.
2. Each pair reports confidence (0–1, components: title/date/entities) and prob_spread.

The matcher canonicalizes common aliases (Fed=FOMC, NYC=New York=KNYC, BTC=Bitcoin, Cavs=Cleveland, $60k=60000) before scoring, but it is still a v0 heuristic.

1. Treat confidence (e.g. KXHIGHNY = NYC daily

high, KXHIGHLAX, KXHIGHCHI). There is no text search, and scanning all markets for "temperature" is slow — go through the series instead:

1. kalshi_markets.py --series KXHIGHNY --status open → today's/tomorrow's temperature buckets.
2. A day's high is split into mutually-exclusive buckets (e.g. -B98.5, -B100.5, -T105).

To answer "P(high > 99°)", kalshi_markets.py --event KXHIGHNY-26JUL04 returns ALL buckets of that event — sum the implied_probability of the buckets above the threshold.

1. Don't pick one bucket and call it the answer; the buckets partition the outcome space.

Multi-contract events (sports, ranges) — use --event, not --query

One game or event is many contracts (moneyline, spread, totals; or temperature buckets), each its own ticker. To get them all: find the event_ticker from any one market, then kalshi_markets.py --event returns every market in that event. --query alone scans the whole universe slowly and may miss them — the event listing is exact and fast.

References — read before deviating from the scripts

• references/kalshi-api.md — read when writing ANY custom Kalshi call: base URLs, no-auth

endpoints, cursor pagination, dollar-string units (*_dollars, *_fp), rate limits.

• references/polymarket-api.md — read when writing ANY custom Polymarket call: Gamma vs

CLOB vs data-api split, question→tokenId resolution, pagination differences.

• references/market-mechanics.md — read before doing probability/fee/settlement math or

interpreting negRisk multi-outcome events.

• references/gotchas.md — read FIRST when an API call fails or numbers look wrong.

Known traps: prices are strings, cents-era fields are gone, tokenId ≠ slug, wordless Kalshi geo-403, /midpoint returns mid not mid_price.

Known constraints

• Kalshi production hosts geo-block some non-US regions with an unlabeled 403 (exit 5 from

the scripts). Demo hosts (external-api.demo.kalshi.co) usually remain reachable for smoke tests; data there is not production data. Polymarket public data has shown no geo-blocking.

• Endpoints came from live docs snapshotted in docs-raw/ (2026-07-01). If a script starts

returning schema errors (exit 7), the API changed: re-fetch docs before "fixing" code.

• Educational/research tooling. Not financial advice. No order execution exists here.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: azazelitto21
• Source: azazelitto21/prediction-markets-skill
• License: MIT

Install and usage instructions live in the source repository linked above.