Python SDK Reference

The Python client is auto-generated from the OpenAPI spec and published as predictorsdk on PyPI.

Client surfaces

The SDK provides both synchronous (PredictorSDK) and asynchronous (AsyncPredictorSDK) clients.

Four surfaces are paginated with a cursor: get_sports_matching_markets, get_markets, get_binance_crypto_prices and list_polymarket_wallet_positions. Each returns a pager that walks the cursor for you; see Pagination. The other surfaces return the parsed response.

Sync client

from predictorsdk import PredictorSDK

client = PredictorSDK(token="YOUR_API_KEY")

# A paginated call returns a pager: pager.items holds this page's events.
pager = client.get_sports_matching_markets(league="nfl")
for event in pager.items:
    print(event.event_id, event.scheduled_date, event.scheduled_start, event.title)

# A lookup finds events by identifier and answers one unpaginated response.
found = client.lookup_sports_matching_markets(source_id="kalshi:KXNBAGAME-26OCT20OKCSAS")

categories = client.get_categories()
plans = client.get_plans()  # Public: works without an API key.

Async client

import asyncio
from predictorsdk import AsyncPredictorSDK

client = AsyncPredictorSDK(token="YOUR_API_KEY")

async def main():
    pager = await client.get_sports_matching_markets(league="nfl")
    async for event in pager:  # every event on every page
        print(event.event_id, event.title)

asyncio.run(main())

Pagination

A call to get_sports_matching_markets, get_markets, get_binance_crypto_prices or list_polymarket_wallet_positions returns a pager. Iterate it to visit every item on every page; the client sends each next cursor and repeats the filters that issued it. On the async client, await the call, then use async for.

# Every event on every page.
for event in client.get_sports_matching_markets(league="nfl", limit=50):
    print(event.event_id, event.title)

# One provider's markets, a page at a time. The whole catalog is about
# 470,000 markets, thousands of pages, so filter by provider or category first.
pager = client.get_markets(provider="prophetx", limit=100)
for page in pager.iter_pages():
    print(len(page.items), page.response.pagination.total)

A pager is immutable: next_page() and iter_pages() return new pagers. Iterating the pager itself walks every page, so use pager.items when you want only the first. pagination.total is an integer on get_markets and get_sports_matching_markets, and None on get_binance_crypto_prices and list_polymarket_wallet_positions, whose upstreams cannot count; follow has_next rather than total. See the Pagination guide for the cursor rules.

Configuration

Key types

These tables describe what the API promises. A response that leaves a field out still parses, and the field reads None; see Responses that leave a field out.

SportsMatchingListResponse

The pager.response of get_sports_matching_markets. Contains the matched events in data, the pagination block, and a snapshot freshness block.

SportsMatchingLookupResponse

The response from lookup_sports_matching_markets: one unpaginated response, with no pagination block.

SportsMatchingLookupResult

CanonicalSportsEvent

One matched game, as the list and the lookup both return it.

PaginationBlock

CanonicalSportsSourceMarket

One venue market matched to a canonical submarket, with the same fields on every venue. event_id is the venue's parent event, for get_event; market_id is the market itself, for get_market. Pass provider to either call as its provider, or use the composite f"{provider}:{id}". Any of event_id, market_id or market_slug, prefixed with provider, finds the event again as source_id. See Which identifier goes where.

get_sports_matching_markets parameters

All keyword arguments, all optional. The filters narrow the list, and total, has_more and the cursors describe the filtered set.

from datetime import date

# Tonight's NFL games: filters compose, and every page keeps them.
for event in client.get_sports_matching_markets(league="nfl", scheduled_date=date(2026, 10, 15)):
    print(event.event_id, event.scheduled_start)

lookup_sports_matching_markets parameters

Send at least one identifier; with both, at most 100 unique values in all.

# `lookups` reports what each identifier found; there is no pagination block.
response = client.lookup_sports_matching_markets(
    source_id=["kalshi:KXNBAGAME-26OCT20OKCSAS", "sxbet:L19766755"]
)
for identifier, found in response.lookups.items():
    print(identifier, found.event_ids)

MarketsListResponse

The pager.response of get_markets. Contains data, catalog snapshot freshness, and pagination.

UnifiedMarket

A market from any supported prediction market provider.

get_markets parameters

get_market and get_event parameters

get_market(market_id, ...) and get_event(event_id, ...) take the ID as their first argument, either platform-native or the composite {provider}:{id}. Both take an optional provider keyword (GetMarketRequestProvider and GetEventRequestProvider) to say which venue an ID belongs to. A bare ID that more than one venue holds raises ConflictError with the candidates; retry with provider set to one of them, or with the composite form. The retired platform is not accepted.

market = client.get_market("KXNBAGAME-26OCT20OKCSAS-OKC", provider="kalshi")
event = client.get_event("KXNBAGAME-26OCT20OKCSAS", provider="kalshi")
print(event.provider)  # "kalshi": pass it back as `provider` for the nested markets

EventResponse

The response from get_event.

get_binance_crypto_prices parameters

CryptoPricesResponse

The pager.response of get_binance_crypto_prices: newest prices first, one per second.

Raw responses

Use with_raw_response on a surface that is not paginated to access HTTP metadata alongside the parsed body:

raw = client.with_raw_response.lookup_sports_matching_markets(
    source_id="kalshi:KXNBAGAME-26OCT20OKCSAS"
)
print(raw.status_code)
print(raw.headers)
print(len(raw.data.data))

A paginated surface returns its pager from with_raw_response too, and a pager carries no status or headers; for those, send the request through your own httpx_client and read its responses there.

Responses that leave a field out

The client reads a response without validating it against the spec, as the TypeScript and Go clients do. A field the spec marks required that a response does not carry reads None instead of raising an error, so a call against an API that is a release ahead of or behind your SDK still returns everything the response did carry. Older SDK releases raised a ParsingError in this case.

• A value of an unexpected type is passed through as the API sent it.
• A field the SDK does not know is kept as an attribute on its model.
• Dates and datetimes are still parsed to date and datetime, and nested objects are still the generated models, so isinstance checks and attribute access work as before.

Because the types above describe what the API promises, check the fields you depend on. pager.response.snapshot can be None, and so can pager.items when a page carries no data:

pager = client.get_sports_matching_markets()
snapshot = pager.response.snapshot
if snapshot is not None and snapshot.observed_at is not None:
    print(snapshot.observed_at)
for event in pager.items or []:
    print(event.event_id)

An error response whose body does not match ErrorResponse still raises the typed error for its status, with e.body.code and e.body.message reading None for whatever the body did not carry.

Error handling

The SDK raises typed exceptions for known HTTP error codes:

The client retries a 408, 429 or 5xx response twice by default (max_retries, on the client or in request_options). A 429 waits for Retry-After, or else until the second-based X-RateLimit-Reset. Any other retried status honours Retry-After and otherwise backs off exponentially from one second. No wait exceeds 60 seconds. A 409 is never retried: send the request again with a provider from its candidates.

A request that gets no response because the connection was refused, reset or closed by the server is retried the same way, with the same backoff and the same limit. A timeout is never retried, and cancelling an async call ends a wait at once. Every call is a read, so repeating one is safe. The Go and TypeScript SDKs follow the same policy, and every response and error carries the same request id.

from predictorsdk import PredictorSDK, BadRequestError

client = PredictorSDK(token="YOUR_API_KEY")

try:
    # A venue ID needs its provider prefix: "kalshi:KXNBAGAME-26OCT20OKCSAS".
    client.lookup_sports_matching_markets(source_id="KXNBAGAME-26OCT20OKCSAS")
except BadRequestError as e:
    print(f"Bad request: {e.body.code}: {e.body.message}")