oddspush
Python client for the OddsPush API: real-time Pinnacle odds over one WebSocket, plus a REST API, with no-vig and fair prices and the closing line for your CLV.
- All 13 sports, live and pre-match.
- A local price book, kept up to date for you: merged by version, closed markets and periods removed.
- Reconnects on its own with backoff, subscribes again and catches up with a snapshot.
- Sync and asyncio REST clients.
- Pure Python, two dependencies (
websockets,httpx), Python 3.10+.
You need an API key (opk_...). Start a free 7-day trial to get
one. Full API reference: oddspush.com/docs.
pip install oddspush
Stream live odds
import asyncio
from oddspush import Stream
async def main():
async with Stream("opk_...", sports=[1], channels=["ld", "both"]) as stream:
async for msg in stream:
if msg["type"] == "odds" and msg["data"].get("type") == "live":
rec = msg["data"]["rec"]
for key, market in stream.book.markets(rec["id"]).items():
print(rec["id"], key, [(p["designation"], p["price"]) for p in market["prices"]])
asyncio.run(main())
stream.book always holds the current open markets of every event you follow:
stream.book.event_ids() # events in the book
stream.book.event(event_id) # league, participants, state, startTime...
stream.book.markets(event_id) # {"s;0;m": {...}, "s;0;ou;2.5": {...}}
stream.book.market(event_id, "s;0;m")
Prices are in American odds; oddspush.american_to_decimal(-155) gives 1.645.
Sports: 1 Soccer, 2 Tennis, 3 Basketball, 4 Hockey, 5 American football, 6 Baseball,
7 Rugby, 8 MMA, 9 Boxing, 10 Other (volleyball and handball), 11 Esports, 12 Golf,
13 Cricket (oddspush.SPORTS).
Channels: ld and both are the prices (ask for both). Add pre for pre-match prices.
dz carries volatile moments: the book leaves it out, and with dz in your channels the
stream asks for snapshots of the book's channels only. Without channels, live updates come
on every channel; the book still takes only ld and both.
No-vig and fair prices
async with Stream("opk_...", sports=[1], channels=["ld", "both"], fair=True) as stream:
async for msg in stream:
if msg["type"] == "fair":
for m in msg["data"]["markets"]:
print(m["key"], m["margin"], [(p["designation"], p["fair_decimal"]) for p in m["prices"]])
Each fair message follows its odds update with the same markets priced without the
bookmaker's margin, two ways: no_vig (multiplicative) and fair (power method, which
corrects the favourite-longshot bias). The book keeps them too:
stream.book.fair(event_id, "s;0;m") # {"version", "margin", "prices"} or None
It only returns the fair price of the very market version the book holds.
Closing line and CLV
from oddspush import Client, clv
with Client("opk_...") as api:
line = api.closing(1639824805) # pre-match or live event id
ml = next(m for m in line["markets"] if m["key"] == "s;0;m")
home = next(p for p in ml["prices"] if p["designation"] == "home")
print(clv(2.10, home["fair_decimal"])) # your price vs the fair closing price
Or get them as they happen with Stream(..., closing=True) (closing messages).
Player props and specials
Specials (player, game and team props) are events of their own (rec.type == "special",
parentId is the match). With specials=True your snapshots include them with their current
prices, so the book recovers them after a reconnect:
async with Stream("opk_...", sports=[3, 5], channels=["ld", "both", "pre"],
specials=True) as stream:
async for msg in stream:
for event_id in stream.book:
ev = stream.book.event(event_id)
if ev.get("type") != "special":
continue
for key, m in stream.book.markets(event_id).items():
names = {p["id"]: p.get("name") for p in ev.get("participants") or []}
legs = [(names.get(p["participantId"]), p["price"]) for p in m["prices"]]
print(ev["special"]["description"], legs,
"suspended" if stream.book.is_suspended(event_id, key) else "open")
Their markets have no status: a closed period suspends them (the book keeps them and
is_suspended says so) and settled removes them.
REST
from oddspush import Client
with Client("opk_...") as api:
api.events(sport_id=1) # every event, markets per channel
api.event(1638807209, fair=True) # one event, ld + both merged
api.event(1639824805, channel="pre", fair=True) # a pre-match event
api.membership(sport_id=1) # pre-match events about to go live
for row in api.iter_closings(sport_id=1): # matches with a closing line
print(row["event_id"], row["start_ms"])
AsyncClient has the same methods, awaitable. A 429 is retried after retry-after
(max_retries=2), then raised as RateLimited. Limits: 120 requests at once, then 300 a
minute per account.
What the stream does for you
- Logs in and subscribes. After a drop it reconnects with exponential backoff (1 s, 2 s, 4 s... up to 30 s), restores your filter and asks for a snapshot.
- Asks for a snapshot after
missed(you fell behind) and afterfeed: up(the source came back), and again later if the snapshot rate limit says so. - Yields
{"type": "disconnected", "reason": ..., "retry_in_s": ...}each time the connection drops, so you can log it. - Snapshots count against your plan's
snapshots_per_hour. Passresync=Falseto stop the automatic ones. - Stops and raises on what retrying cannot fix:
Unauthorized,SubscriptionExpired,NotInPlan(a REST-only plan) andTokenReplaced.
Change the subscription at any time:
await stream.subscribe(sports=[2, 3])
await stream.unsubscribe(sports=[3])
await stream.subscribe(fair=True) # turn fair prices on, filter unchanged, no snapshot
await stream.request_snapshot()
In a bot that runs for days, stream.book.prune(3600) drops events that have had no update
for an hour and have no open market left.
One machine per connection
A token works from as many IPs at a time as the connections in your plan: one included,
plus any extra connections you add (90 USD each for 30 days, from your account page). Using it from
a new IP beyond that (a stream login or a REST request) takes over from the oldest IP and
closes the stream there (TokenReplaced). With one connection, run your stream and your
REST calls from the same machine.
Keep up
Read fast and do heavy work in another task: if you fall more than 15 seconds behind, the
server closes the connection and the stream reconnects. Host your bot close to Ireland (AWS
eu-west-1) for the lowest latency.
Examples
See examples/: a live
printer, a fair-price watcher, a pre-match tracker and a CLV report.
Links
- Website and pricing: oddspush.com
- API reference: oddspush.com/docs
- Source and issues: github.com/oddspush/oddspush-python
- Support: support@oddspush.com
OddsPush is not affiliated with, endorsed by or sponsored by Pinnacle. MIT licensed.
Metadata
Release files for oddspush 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| oddspush-0.2.0.tar.gz | 31.1 kB | With provenance | Details for oddspush-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| oddspush-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for oddspush-0.2.0-py3-none-any.whl |
Total release size: 54.9 kB
Release files / oddspush-0.2.0.tar.gz
| Download URL | oddspush-0.2.0.tar.gz |
|---|---|
| Size | 31.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
21a5ea044bdf3219994999fb08a182560d552b6057ad5bdb43675fb2ddf2f44b
|
|
BLAKE2b-256 checksum How to use checksums |
0af9214b62e3b7e3c944a055dc9387e498f6650ad5dec5d83af5f584f9b63f66
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / oddspush-0.2.0-py3-none-any.whl
| Download URL | oddspush-0.2.0-py3-none-any.whl |
|---|---|
| Size | 23.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b1b0e46583fcbf9f1bb131bd14247cc34d874f306c9f7bc7d33138c34ded2091
|
|
BLAKE2b-256 checksum How to use checksums |
5b72e788330abdd3ce2115f9d2fb1ece1a967c2a057ce5043fd964f0c8aa29da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for oddspush 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for oddspush-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.