Owls Insight Python SDK

Official Python SDK for the Owls Insight real-time sports betting odds API. Sync and async clients, fully typed with Pydantic v2, plus a Socket.io WebSocket client for live streams.

pip install owls-insight

Requires Python 3.9+. Get an API key at owlsinsight.com.

Quick start (sync)

from owls_insight import OwlsInsight

client = OwlsInsight(api_key="owlsinsight_...")

# REST: current NBA odds. `data` is keyed by sportsbook -> list of events.
odds = client.rest.get_odds("nba", books=["pinnacle", "fanduel"])
for book, events in odds.data.items():
    for event in events:
        print(book, event.home_team, "vs", event.away_team)

# WebSocket: stream live updates
client.ws.connect()
client.ws.subscribe(sports=["nba"], books=["pinnacle"])
client.ws.on("odds-update", lambda data: print("live:", data))

# or block for the next event
update = client.ws.wait_for("odds-update", timeout=15)

client.destroy()

Quick start (async)

import asyncio
from owls_insight import AsyncOwlsInsight

async def main():
    async with AsyncOwlsInsight(api_key="owlsinsight_...") as client:
        odds = await client.rest.get_odds("nba", books=["pinnacle"])
        print(sum(len(events) for events in odds.data.values()), "games")

        await client.ws.connect()
        await client.ws.subscribe(sports=["nba"], books=["pinnacle"])
        update = await client.ws.wait_for("pinnacle-realtime", timeout=30)
        print("realtime:", update)

asyncio.run(main())

Authentication

Pass your API key to the constructor. REST uses the Authorization: Bearer header; the WebSocket uses the ?apiKey= query string. Both are handled for you.

import os
client = OwlsInsight(api_key=os.environ["OWLS_INSIGHT_API_KEY"])

REST

Method names are snake_case (the JS SDK's getOdds is get_odds here). Every method returns a typed Pydantic model; unknown fields from the evolving API are preserved (model_extra), never dropped.

Full parity with the TypeScript SDK — every endpoint is available on both client.rest (sync) and the async client.

Methods whose response shape isn't individually modelled yet return a permissive ApiResponse envelope (success/data/meta, all fields preserved). Deep per-endpoint Pydantic typing is the remaining follow-on; the method surface is complete.

ProphetX order book

Each ProphetX markets entry (keyed "{market_id}:{line}") parses as models.ProphetXMarket. The book is a list of sides in outcomes order, each side its price levels best-first or None when nothing is resting. On spread and total deltas the book sits under marketLines[0] rather than the top level, so use the helpers:

from owls_insight import OwlsInsight, prophetx_book, prophetx_outcomes, prophetx_best

px = OwlsInsight(api_key="...").rest.get_prophetx_odds("baseball")
for event in px.data.sports["Baseball"]:
    for key, market in event.markets.items():
        outcomes = prophetx_outcomes(market)        # labels, one per side
        for i, side in enumerate(prophetx_book(market)):
            best = prophetx_best(market, i)
            if best is None:                        # None side = nothing resting
                continue
            # best.value = amount you can bet now; best.odds = American; payout from those two, not from stake
            label = outcomes[i].name if i < len(outcomes) else None
            print(key, label, best.odds, best.value)

Hard Rock odds decoding

Hard Rock v2 selections carry a rootIdx, not inline odds. Decode it client-side:

from owls_insight import root_idx_to_american_odds
root_idx_to_american_odds(42)  # -325
root_idx_to_american_odds(72)  #  100  (even)

WebSocket events

odds-update, props-update (and per-book {book}-props-update), pinnacle-realtime, ps3838-realtime, esports-update, prophetx-update, and the v2 {book}-v2-update deltas.

client.ws.connect()
client.ws.subscribe(sports=["nba", "nhl"], books=["pinnacle", "fanduel"])
client.ws.subscribe_props(book="fanduel")           # props stream
client.ws.update_subscription(prophetx=True)        # merge, don't replace
client.ws.on("props-update", handle_props)

Errors

from owls_insight import AuthenticationError, RateLimitError, ServiceBusyError, OwlsInsightError

try:
    client.rest.get_odds("nba")
except AuthenticationError:
    ...  # 401
except RateLimitError as e:
    # e.code is "HISTORY_CONCURRENCY" when too many history requests were in flight
    print("retry after", e.retry_after_ms, "ms", e.code)
except ServiceBusyError as e:
    # 503: too expensive to serve in one request, or a transient outage
    print("busy, retry after", e.retry_after_ms, "ms or narrow the request")
except OwlsInsightError as e:
    print(e.status, e.message)

Retries are opt-in for direct calls: OwlsInsight(api_key, max_retries=3) retries 429 and 503 honouring Retry-After (else exponential backoff). iter_history_odds / iter_history_props retry by default. history_concurrency (default 3, the MVP plan's per-key history allowance; Hall of Fame allows 4) caps the history requests a client keeps in flight; requests beyond it wait client-side instead of being refused.

License

MIT