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.

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, OwlsInsightError

try:
    client.rest.get_odds("nba")
except AuthenticationError:
    ...  # 401
except RateLimitError as e:
    print("retry after", e.retry_after_ms, "ms")
except OwlsInsightError as e:
    print(e.status, e.message)

License

MIT