API reference
Pinnacle prematch and live odds over REST and WebSocket. Two formats with one key: /v1, one object per match with one flat list of markets, and /ps3838, the shapes of PS3838's own API, so an existing client only changes its base URL.
Getting started
Base URL: https://api.oddssea.dev. Every request carries your key in the X-API-Key header.
# the sports, with how many matches each has now curl -H "X-API-Key: $KEY" https://api.oddssea.dev/v1/sports # every soccer match on offer, in decimal odds curl -H "X-API-Key: $KEY" "https://api.oddssea.dev/v1/events?sport=soccer"
For prices as they change, keep a WebSocket open instead of polling: Stream. REST is for snapshots, lookups and history; it's rate-limited per plan so that the stream is always the faster path.
Responses are JSON, gzip-compressed when you send Accept-Encoding: gzip (recommended: a full sport is a few hundred kilobytes compressed).
From Python, the client does the requests and keeps the stream connected: pip install oddssea. Its README has the examples; the source is on GitHub.
Authentication
Create an account and keys at https://app.oddssea.dev/account: no email, no password, your account number is the login. An account has up to 5 keys, for different bots or machines; a key that leaks is revoked there without touching the account. Limits belong to the account, shared by its keys.
Send the key as a header, never in a URL (URLs end up in logs and browser history):
X-API-Key: your-key
The WebSocket takes the same header. Browsers can't set WebSocket headers: there, send the key in the first message, {"op": "auth", "key": "your-key"}, before anything else.
What a key can see is its plan's, on every endpoint: a Prematch key never gets an in-play event, from REST or the stream. See Plans and limits.
Every response says the plan: X-Plan (free, prematch, live, scale) and, on a paid plan, X-Plan-Expires (ISO time). When paid time runs out the account is on Free: keys keep working with the Free plan's data, the stream refuses new connections and closes open ones with PLAN_CHANGED. In the 3 days before, a new stream connection first gets {"type": "notice", "seq", "code": "PLAN_EXPIRES", "expiresAt", "next", "message"}; next is the plan whose paid time starts then, or null (Free).
Formats and units
| Odds | Decimal by default, three decimals. oddsFormat: Decimal, American, HongKong, Indonesian, Malay (case doesn't matter). /ps3838 defaults to American, as PS3838 does. |
|---|---|
| Limits | USD. maxVolume is Pinnacle's limit for the market: from a price of 2.00 it's the maximum stake, below 2.00 the maximum win. maxStake applies that rule per side: volume at 2.00 and up, volume / (price − 1) below. |
| Times | ISO 8601 UTC (2026-10-03T19:30:00Z). Cursors (last, since) are Unix milliseconds. |
| Periods | 0 is the whole match; 1, 2… are halves, sets, quarters or periods as the sport has them. Every market carries its periodName ("1st Half", "Set 2"). |
| Markets | moneyline (two-way), 1x2 (with a draw), handicap (line = the home handicap), total (line = the total). Every alternative line is its own market entry; main: true marks the main line. Not included: team totals, props and specials, corners and bookings. |
Ids and lines
Event (id): one listing. A match's in-play listing has an id of its own, different from its prematch one, and some markets come as linked events with a unit other than Regular (Kills for e-sports, Points for volleyball). A tennis match is listed as two events, Sets and Games, with no Regular one.
Match (matchId): one id for the whole match, the same before and after kick-off and on its linked events. Key your data on matchId and nothing needs re-keying at kick-off.
Line key: "<period>|<market>|<line>", the line without trailing zeros and empty for moneylines: "0|1x2|", "0|handicap|-0.25", "1|total|2.5". Used by history and opening / closing prices.
Sports and leagues
{"sports": [{"id": 29, "sport": "soccer", "name": "Soccer", "events": 1575, "live": 58}, ...]}
Wherever a sport is a parameter, use its id or its name (sport): 29 and soccer are the same.
{"sport": "soccer", "leagues": [{"id": 1980, "name": "England - Premier League", "events": 20}, ...]}
Events
sport | required: id or name |
live | 1 in-play only, 0 prematch only; default both |
league, event, match | ids, comma-separated or repeated, up to 200 |
since | a previous response's last: only what changed since (see below) |
oddsFormat | see Formats |
devig | adds fair prices: Fair prices |
{
"sport": "soccer", "last": 1790999123456,
"events": [{
"id": 1637600069, "matchId": 1637370516,
"sport": "soccer", "sportId": 29, "league": "Japan - J2 League", "leagueId": 2157,
"home": "Tochigi City", "away": "Imabari", "starts": "2026-10-03T05:00:00Z",
"live": true, "state": "2H 61'", "score": [1, 0], "suspended": false,
"parentId": 1637370516, "unit": "Regular",
"markets": [
{"market": "1x2", "period": 0, "periodName": "Match", "status": "open", "line": null, "main": true,
"prices": {"home": 1.645, "draw": 3.89, "away": 6.27},
"maxVolume": 775.0, "maxStake": {"home": 1198, "draw": 775, "away": 775},
"updatedAt": "2026-10-03T06:41:07.123Z"},
{"market": "handicap", "period": 0, "periodName": "Match", "status": "open", "line": -0.5, "main": true,
"prices": {"home": 1.645, "away": 2.35}, "maxVolume": 1575.0, "maxStake": {"home": 2433, "away": 1575},
"updatedAt": "2026-10-03T06:41:07.123Z"},
{"market": "total", "period": 0, "periodName": "Match", "status": "open", "line": 2.5, "main": true,
"prices": {"over": 2.02, "under": 1.84}, "maxVolume": 1575.0, "maxStake": {"over": 1575, "under": 1875},
"updatedAt": "2026-10-03T06:41:05.981Z"}
]
}]
}
status is open or suspended; suspended on the event means all its prices are off for now (in-play, often for seconds). Events with no prices yet have markets: [].
In-play events carry state (the period and clock, e.g. "2H 61'", "Q3 7'", "Set 2") and score ([home, away]; for tennis it's sets, and its Games event has the games). score is null when there's no live score: always for e-sports, volleyball and MMA (where state often is null too), and now and then for a match of another sport.
Deltas. Pass the last of your previous response as since to get only the events changed since then, each whole; an event that's gone comes as {"id": …, "removed": true}. A since older than an hour gets a full snapshot.
One event: the event object itself, not wrapped in events. Takes oddsFormat and devig.
Matches
Every event of a match: its in-play listing, its prematch listing while that still exists, and its linked events. In-play first. Takes oddsFormat and devig.
{"matchId": 1637370516, "sport": "tennis", "events": [{...in-play event...}, {...Games...}]}
Or filter any events request or stream subscription by match / matches.
Search
Finds matches by team or player names. Accents, punctuation, "FC"-style words and the order of home and away don't matter, so names from another bookmaker work as they are.
home, away | one or both; or q for free text |
sport | id or name |
starts, window | an ISO time or Unix ms, and hours either side (default 36) |
live, limit | 1 / 0; results, up to 50 (default 10) |
curl -H "X-API-Key: $KEY" "https://api.oddssea.dev/v1/search?home=Banik%20Ostrava&away=Hradec&sport=soccer"
{"matches": [{"score": 0.981, "id": 1637412345, "matchId": 1637412345, "sport": "soccer", "sportId": 29,
"league": "Czech Republic - 1. Liga", "home": "Banik Ostrava", "away": "Hradec Kralove",
"starts": "2026-10-04T14:00:00Z", "live": false, "unit": "Regular"}]}
score runs 0 to 1; results below 0.5 aren't returned. Search covers the matches listed now; for finished ones, use matches by date.
Fair prices
Add devig= and a method below (devig=multiplicative) to an events, event or match request, or "devig" to a stream subscription, and every market gets fair: its prices with the margin taken off.
"prices": {"home": 2.78, "draw": 3.90, "away": 2.02},
"fair": {"home": 3.112, "draw": 4.532, "away": 2.183}
multiplicative | Every probability scaled by the same factor. The usual choice. |
|---|---|
additive | The same amount off each outcome. fair is empty ({}) where that would make a probability negative. |
power | Probabilities raised to a common power: shades long shots more (the favourite–long-shot bias). |
shin | Shin's model of a book protecting itself from insiders; also shades long shots. Equal to additive on two-way markets. |
Fair prices are in the requested oddsFormat.
History
Every change of one line: prices, limit and when it couldn't be bet. For an in-play event the series starts with its prematch listing, so one request covers the whole match; liveAt is the kick-off.
event | the prematch or in-play event id |
period, market | as in events: moneyline or 1x2 (whichever the event has), handicap, total |
line | the home handicap or the total; leave it out for moneyline and 1x2 |
{"sides": ["home", "away", "draw"],
"points": [[1794990000123, 2.15, 3.40, 3.30, 400], [1795003320000, 2.40, 3.10, 3.20, 400],
[1795003386000, 3.60, 3.30, 2.05, 250], ...],
"unavailable": [[1795003320000, 1795003386000, "suspended"], [1795008600000, null, "unlisted"]],
"opening": {"home": 2.15, "draw": 3.30, "away": 3.40},
"closing": {"home": 1.96, "draw": 3.55, "away": 3.70},
"liveAt": 1795001800000, "prematchEvent": 1637370516}
Each point: [ms, price per side in "sides" order, maxVolume]. prematchEvent is the prematch event's id when you ask for an in-play one, else null. A line the event never had answers with no points and null prices. History is kept for 7 days after a match's start; opening and closing prices for a year. Recording started on 3 October 2026: nothing goes back further, and for matches already listed that day, the opening price is the first one recorded. A Prematch key gets prematch events only, up to their kick-off. To find the ids of finished matches, use matches by date.
suspended | listed, but its market was closed (the event suspended or its period closed); the point at to is the reopening price |
|---|---|
unlisted | not offered: taken off, replaced when the line moved, or its period or event gone |
Without period, market and line: the match's in-play timeline, a row each time its state, clock or score changed. Live and Scale. event is the prematch or the in-play id; the answer's event is the in-play one. A match that never went in-play has event, timeline and suspended null.
{"event": 1637600069, "matchId": 1637370516, "liveAt": 1795001800000,
"timeline": [
{"t": 1795001800000, "state": "1H 0'", "phase": "1H", "clock": 0, "score": [0, 0]},
{"t": 1795003386000, "state": "1H 26'", "phase": "1H", "clock": 26, "score": [1, 0]},
{"t": 1795004500000, "state": "HT", "phase": "HT", "clock": null, "score": [1, 0]}],
"suspended": [[1795003320000, 1795003386000]]}
state, score | as /v1/events showed them |
|---|---|
phase, clock | the state split: the period, and whole minutes (soccer counts up; basketball, hockey and football count down; null where there's no clock) |
| tennis | score is sets, plus games, points and server |
suspended | when the event was suspended, [from, to] |
In-play betting often closes before the end, so the final score is result in matches by date.
Matches by date
Matches by start time, finished ones included, up to a year back (recording started on 3 October 2026): the ids for history and opening and closing. One row per match, in start order.
sport | id or name; required |
from, to | Unix ms, an ISO time or a date (2026-10-05: to includes that day). Default: the last 7 days. At most 31 days per request |
league | league ids, or part of a league's name (case doesn't matter); repeat for several |
home, away, q | team or player names, matched as in search; each match gets a score, and below 0.6 it isn't returned |
limit, cursor | rows per page, up to 500 (default 100); for the next page, pass next from the previous one as cursor |
curl -H "X-API-Key: $KEY" "https://api.oddssea.dev/v1/history/events?sport=baseball&league=Korea%20Professional&from=2026-10-05&to=2026-10-11"
{"matches": [{"matchId": 1637707569, "id": 1637707569, "liveId": 1638159492,
"league": "Korea Professional Baseball", "leagueId": 6227, "home": "Samsung Lions", "away": "KT Wiz",
"starts": "2026-10-11T05:00:00Z", "kickoff": 1791694841895, "closing": true,
"historyUntil": 1792299600000, "linked": [],
"result": {"status": "final", "winner": "away",
"periods": [{"period": 0, "periodName": "Match", "home": 4, "away": 6}, ...],
"settledAt": 1791712800000, "updatedAt": 1791712800000}}],
"next": "1791694800000.1637707569"}
id | the prematch event: use it with /v1/history and /v1/opening-closing. null if the match was only listed in-play |
|---|---|
liveId | the in-play event (null if it never went in-play). Live and Scale keys only: left out for a Prematch key |
kickoff | when the prematch prices stopped (ms), normally the kick-off; null if they stopped long before the start (taken off) or haven't stopped yet |
closing | false when the match was taken off before its start: no closing prices |
historyUntil | until when /v1/history has its price moves (ms, 7 days after the start); opening and closing prices stay a year |
linked | its linked events (Sets, Games, Kills, Points): id, unit, live, result |
result | the final score per period (results); null until the match is settled, and after historyUntil |
leagueId can be null for matches before 12 October 2026. With a Prematch key, matches only ever listed in-play are left out. next is null on the last page.
Results
Each row of matches by date has the match's final score per period in result, as the bookmaker settles it, for matches that started in the last 7 days (until historyUntil, like the price history). null until the match is settled.
curl -H "X-API-Key: $KEY" "https://api.oddssea.dev/v1/history/events?sport=soccer&from=2026-10-10&to=2026-10-11"
"result": {"status": "final", "winner": "home",
"periods": [{"period": 0, "periodName": "Match", "home": 2, "away": 1},
{"period": 1, "periodName": "1st Half", "home": 1, "away": 1}],
"settledAt": 1791907569795, "updatedAt": 1791907569795}
status | final, or void when the match was cancelled or abandoned (no score) |
|---|---|
winner | home, away or draw, for the whole match; null when void |
periods | every period settled, with the same period numbers and periodNames as the markets in events: soccer's match and 1st half, basketball's halves and quarters, hockey's periods and regulation time, baseball's innings, e-sports' maps, volleyball's sets. A tennis match's Sets event has the sets, its Games event the games. A cancelled period: {"period": 1, "periodName": "1st Half", "status": "void"} |
settledAt, updatedAt | when the result was first settled, and its last correction (ms); the same unless corrected |
A result is added once the match is settled, usually by 12:00 UTC the next day, and a correction can follow within a day: to keep your own records current, ask for yesterday and today once a day and compare updatedAt. Linked events (a tennis match's sets and games, e-sports kills) have results of their own, in their linked entries. The score settles any line: a handicap of −1.5 on the home side wins when home − away is 2 or more, a total of 2.5 goes over at 3 goals or more. For PS3838 clients: /ps3838/v3/fixtures/settled.
Opening and closing
Per event and line key: the first prices seen and the last prematch prices (closing), for closing line value and model calibration. Up to 200 events; an id we have nothing for is left out of events.
event | event ids, comma-separated or repeated |
devig | adds fair: every line's fair prices, by multiplicative, additive, power or shin (the same as /v1/events) |
{"events": [{"id": 1637370516,
"opening": {"0|1x2|": {"home": 2.15, "draw": 3.30, "away": 3.40},
"0|total|2.5": {"over": 1.92, "under": 1.94}, "0|total|2.75": {"over": 2.20, "under": 1.70}},
"closing": {"0|1x2|": {"home": 1.96, "draw": 3.55, "away": 3.70},
"0|total|2.5": {"over": 1.72, "under": 2.17}, "0|total|2.75": {"over": 1.95, "under": 1.91}},
"main": {"opening": ["0|1x2|", "0|total|2.5"], "closing": ["0|1x2|", "0|total|2.75"]},
"fair": {"opening": {"0|total|2.5": {"over": 1.989, "under": 2.011}, ...},
"closing": {"0|total|2.75": {"over": 2.022, "under": 1.979}, ...}},
"kickoff": 1791001812345, "final": true}]}
closing is null before the start. Between the scheduled start and kick-off it follows the market with final: false; at kick-off it's frozen (final: true).
main lists the main line of each period and market: in opening the main line when that market first appeared, in closing the main line at closing (it moves as the market moves: 2.5 to 2.75 above). Moneylines and 1X2 are always listed. To get the closing price of the main full-time total, take the key in main.closing that starts with 0|total|. A period and market with no key there has no known main line. fair is only there with devig.
Drops and limits
The biggest price moves right now: one row per line side, sorted by size.
window | 300, 900, 3600 seconds, or open (since opening; in-play: since kick-off) |
direction | drop (default), rise, both, or limit: lines whose limit moved instead |
minDrop | minimum move in percent (default 3) |
minOdds, maxOdds | current price range (default 1.01 – 1000) |
minMax | minimum max stake on the selection, USD |
sport, live, market | filters; market: moneyline (1X2 included), 1x2, handicap, total, comma-separated or repeated |
main | 1 (default) main lines only, 0 alternative lines too |
{"drops": [{"eventId": 1637466250, "sport": "hockey", "sportId": 19, "league": "Norway - Eliteserien",
"home": "Stjernen Hockey Fredrikstad", "away": "Frisk Asker", "starts": "2026-10-03T17:00:00Z", "live": false,
"period": 6, "periodName": "Regulation Time", "market": "1x2", "line": null, "side": "home",
"from": 3.13, "to": 2.65, "dropPct": 15.34, "fair": 2.929, "max": 50, "maxFrom": 50, "maxStake": 50,
"at": 1790990421555, "points": [[1790989900000, 3.13], [1790990421555, 2.65]]}], "now": 1790990433000}
from is the price at the window's start, to the price now, dropPct = (from − to) / from in percent, so negative for a rise. fair is the side's fair price now (multiplicative), max / maxFrom the market's limit now and at the window's start, points the side's last 40 price moves.
With direction=limit a row is a whole line (side: null): from / to are the limit in USD (a negative dropPct: the limit went up), prices the line's prices now and maxStake is per side.
Stream
Subscribe once; you get a snapshot of every event you asked for, then every change as it happens, each event whole: a new score or clock sends an update too, prices changed or not.
{"op": "subscribe",
"sports": ["soccer", 33],
"live": true,
"oddsFormat": "Decimal",
"devig": "power",
"opened": true,
"limits": true}
sports | ids or names; omit for all |
events, matches | ids: only those (with their linked events) |
live | true: in-play only |
oddsFormat, devig | as on REST |
opened | true: an opened message whenever a line appears for the first time |
limits | true: a limit message whenever a market's limit changes |
A new subscribe replaces the previous one (at most one per 5 seconds) and starts with a fresh snapshot. Your key's plan decides what's included, whatever you subscribe to.
const ws = new WebSocket("wss://api.oddssea.dev/v1/stream", { headers: { "X-API-Key": KEY } }); // Node, the "ws" package
ws.onopen = () => ws.send(JSON.stringify({ op: "subscribe", sports: ["soccer"], live: true }));
ws.onmessage = m => {
const msg = JSON.parse(m.data);
if (msg.type === "snapshot" || msg.type === "update") store(msg.event);
if (msg.type === "remove") drop(msg.eventId);
};
Keep reading: a client that falls 10,000 messages behind is disconnected (close code 4008). The connection is compressed (permessage-deflate) when your client supports it.
Reconnecting. After any close, connect again and subscribe as before; the snapshot brings you back in sync. Wait a short random time first, longer after each failed attempt (about 0.5 s up to 30 s).
Before we close a connection, for example when we update the service, it gets a reconnect message about 10 seconds ahead (closesAt, Unix ms). To switch without a gap: open a new connection, subscribe the same way, keep using the old one until the new one sends ready, then close the old one. The second connection is accepted during the switch, also on a plan with one stream connection. If you ignore the message, the connection closes with code 1012 and you reconnect as usual.
import asyncio, json, random, websockets # pip install websockets (14 or newer)
URL, SUB = "wss://api.oddssea.dev/v1/stream", {"op": "subscribe", "sports": ["soccer"], "live": True}
async def open_stream():
"""A new connection, subscribed and read up to its "ready": (connection, its snapshot)."""
ws = await websockets.connect(URL, additional_headers={"X-API-Key": KEY})
await ws.send(json.dumps(SUB))
events = {}
async for raw in ws:
m = json.loads(raw)
if m["type"] == "snapshot": events[m["event"]["id"]] = m["event"]
if m["type"] == "ready": return ws, events
raise ConnectionError("closed before ready")
async def main():
wait = 0.5
while True:
try:
ws, events = await open_stream()
wait, new = 0.5, None
while True:
recv = asyncio.ensure_future(ws.recv())
done, _ = await asyncio.wait({recv, new} - {None}, return_when=asyncio.FIRST_COMPLETED)
if recv in done and recv.exception() and new: # the old one closed first: wait for the new one
await asyncio.wait({new})
elif recv in done:
m = json.loads(recv.result())
if m["type"] == "update": events[m["event"]["id"]] = m["event"]
if m["type"] == "remove": events.pop(m["eventId"], None)
if m["type"] == "reconnect" and not new: new = asyncio.create_task(open_stream())
else:
recv.cancel()
if new and new.done(): # the new one is ready (or failed: keep the old)
if not new.exception():
old, (ws, events) = ws, new.result()
await old.close()
new = None
except (OSError, websockets.WebSocketException):
await asyncio.sleep(wait * random.uniform(0.5, 1)) # after any close: a random wait that grows
wait = min(wait * 2, 30)
asyncio.run(main())
Messages
Every message has a type and, except errors, a seq that counts up by one per connection (a gap means you missed something: resubscribe) and sentAt, the Unix time in ms our server sent it. New message types and fields can be added: ignore the ones you don't know.
snapshot | {"type", "seq", "sport", "event"}, one per event the subscription covers |
|---|---|
ready | the snapshot is complete; updates follow |
update | {"type", "seq", "sport", "event"}: the whole event, every time anything in it changes |
notice | {"type", "seq", "code", "message", ...}: about your account, e.g. PLAN_EXPIRES with expiresAt |
remove | {"type", "seq", "sportId", "eventId"}: off the board (ended, or, for a Prematch key, gone in-play) |
opened | {"type", "seq", "sport", "sportId", "eventId", "matchId", "newEvent", "markets"}: lines seen for the first time on this event, with their first prices, right after the update that carries them; newEvent: the event itself is new |
limit | {"type", "seq", "sport", "sportId", "eventId", "matchId", "changes": [{"period", "periodName", "market", "line", "from", "to", "maxStake"}]} |
reconnect | {"type", "seq", "closesAt", "message"}: this connection will be closed at about closesAt (Unix ms): open a new one, switch to it at its ready, then close this one (Reconnecting) |
error | {"type", "code", "message"}: a bad or too frequent request; the connection stays open |
Measuring your latency. sentAt lets you see the network part yourself. With a synchronised clock (NTP), the time from our send to your receipt is:
import json, time, statistics, websocket # pip install websocket-client
ws = websocket.create_connection("wss://api.oddssea.dev/v1/stream", header=["X-API-Key: " + KEY])
ws.send(json.dumps({"op": "subscribe", "live": True}))
ms = []
while len(ms) < 500:
m = json.loads(ws.recv())
if m["type"] == "update":
ms.append(time.time() * 1000 - m["sentAt"])
print(f"median {statistics.median(ms):.1f} ms, p95 {sorted(ms)[int(len(ms) * .95)]:.1f} ms")
Add our own processing time, published on the latency page, for the time from a price change reaching us to it reaching you.
PS3838-compatible API
The same data in PS3838's shapes. A client written for PS3838 changes its base URL to https://api.oddssea.dev/ps3838 and its credentials to the X-API-Key header, and otherwise reads our responses unchanged.
GET /ps3838/v3/sports | |
GET /ps3838/v3/leagues?sportId= | |
GET /ps3838/v1/periods?sportId= | |
GET /ps3838/v3/fixtures?sportId= | leagueIds, eventIds, isLive, since |
GET /ps3838/v4/odds?sportId= | leagueIds, eventIds, isLive, since, oddsFormat (default American), toCurrencyCode (USD only) |
WS /ps3838/stream | the stream protocol above; each event as a PS3838 odds event plus its fixture |
GET /ps3838/v3/fixtures/settled?sportId= | leagueIds, since: settled periods (number, status 1 settled, 2 re-settled, 3 cancelled, 4 re-settled as cancelled, settlementId, settledAt, team1Score, team2Score); also as /ps3838/v1/fixtures/settled |
since works as on PS3838: pass the previous last; a fixture or odds event that's gone comes with "removed": true. Limits (maxMoneyline, maxSpread, maxTotal, a line's max) are volumes, as on PS3838. Betting endpoints aren't part of this API. Settled fixtures cover the matches that started in the last 7 days; without since, the last 24 hours, as on PS3838; cancellationReason isn't given. With a Live or Scale key a match's in-play event is settled too, with the same periods.
Plans and limits
| Free | Prematch | Live | Scale | |
|---|---|---|---|---|
| USD / month | $0 | $59 | $149 | $299 |
| Prematch events | delayed | real time | real time | real time |
| In-play events | never | never | yes | yes |
| Stream connections | – | 1 | 1 | 10 |
Full snapshot (no since), per endpoint and sport | 1 / 60 s | 1 / 60 s | 1 / 60 s | 1 / 10 s |
Delta (since), per endpoint and sport | – | 1 / 10 s | 1 / 5 s | 1 / s |
| REST requests, all together | 10 / min, 100 / day | 60 / min | 120 / min | 600 / min |
The per-sport limits are for /v1/events and PS3838's /fixtures, /odds and /fixtures/settled; a request without since counts as a full snapshot, filtered or not. Sports, leagues and periods: once per 10 seconds per endpoint. Every other endpoint counts toward the per-minute total only. Up to 200 ids per request. Over a limit the API answers 429 with Retry-After. The stream has no request limits: it's the real-time path.
With a Prematch key an event leaves every response at kick-off: REST deltas report it removed once, the stream sends remove.
Free is for trying the data out, in both formats: /v1/sports, /v1/leagues and /v1/events (prematch, every market, decimal odds, with "delayed": true and no timestamps; the league, event and match filters work; since, devig and other odds formats answer 403 PLAN_REQUIRED), and PS3838's /v3/sports, /v3/leagues, /v1/periods, /v3/fixtures and /v4/odds (the same delayed prematch events, every odds format, no *UpdatedAt times; since is accepted and answered with every event, and isLive=1 with none). Every other endpoint and the stream answer 403 PLAN_REQUIRED.
Paying for 3 months save 10%, 6 months 15%, 12 months 20%. Every plan is for your own use, company or individual. Showing the data to others or reselling it needs a redistribution licence: contact us.
Errors
Errors are JSON: {"code": "INVALID_REQUEST_DATA", "message": "oddsFormat: one of Decimal, American, HongKong, Indonesian, Malay"}
| 400 | INVALID_REQUEST_DATA: a parameter is missing or wrong; the message says which |
|---|---|
| 401 | UNAUTHORIZED: no key, or an unknown one |
| 403 | FORBIDDEN: not in your plan (for example in-play history with a Prematch key) |
| 403 | PLAN_REQUIRED: your plan doesn't include this (the Free plan's limits above); the message says what it has |
| 404 | NOT_FOUND: no such sport, event, match or endpoint |
| 405 | METHOD_NOT_ALLOWED: every endpoint is a GET (the streams are WebSocket) |
| 429 | TOO_MANY_REQUESTS: over a limit; wait Retry-After seconds |
| stream | TOO_MANY_CONNECTIONS: your plan's stream connections are all in use; not permanent: close another connection, or wait a few seconds, and try again · PLAN_CHANGED: the account's plan changed (time ran out, or a new plan): connect again |
| 503 | SERVICE_UNAVAILABLE: starting up or briefly unavailable; retry shortly |
Stream close codes: 4008 too slow (the queue filled), 1013 unavailable, 1012 closed by us, for example at the closesAt of a reconnect message: connect again (Reconnecting), 4003 not allowed for this key; the error sent before it says why, and after TOO_MANY_CONNECTIONS you can try again (above).
Changes
Within /v1 fields are only ever added: ignore keys you don't know. Anything breaking gets a new version path.
| November 2026 | A Python client: pip install oddssea (GitHub). |
|---|---|
| November 2026 | /v1/history: unavailable (when a line couldn't be bet) and a match's in-play timeline. |
| November 2026 | Streams send a reconnect message before we close a connection for an update, so your client can open a new one and switch to it without a gap. |
| October 2026 | The Free plan also answers in PS3838's shapes: sports, leagues, periods, fixtures and odds, delayed and prematch, so an existing PS3838 client can be tried before paying. |
| October 2026 | Results: final scores per period in /v1/history/events (result), and PS3838's /v3/fixtures/settled. |
| October 2026 | /v1/history/events: finished matches by date, league or team. /v1/history now returns opening and closing for matches older than two days too. |