oddssea
Get API key

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.

Get a free API key

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

OddsDecimal by default, three decimals. oddsFormat: Decimal, American, HongKong, Indonesian, Malay (case doesn't matter). /ps3838 defaults to American, as PS3838 does.
LimitsUSD. 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.
TimesISO 8601 UTC (2026-10-03T19:30:00Z). Cursors (last, since) are Unix milliseconds.
Periods0 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").
Marketsmoneyline (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

GET /v1/sports
{"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.

GET /v1/leagues?sport=soccer
{"sport": "soccer", "leagues": [{"id": 1980, "name": "England - Premier League", "events": 20}, ...]}

Events

GET /v1/events?sport=
sportrequired: id or name
live1 in-play only, 0 prematch only; default both
league, event, matchids, comma-separated or repeated, up to 200
sincea previous response's last: only what changed since (see below)
oddsFormatsee Formats
devigadds 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.

GET /v1/events/{eventId}

One event: the event object itself, not wrapped in events. Takes oddsFormat and devig.

Matches

GET /v1/matches/{matchId}

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.

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}
multiplicativeEvery probability scaled by the same factor. The usual choice.
additiveThe same amount off each outcome. fair is empty ({}) where that would make a probability negative.
powerProbabilities raised to a common power: shades long shots more (the favourite–long-shot bias).
shinShin'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

GET /v1/history?event=&period=&market=&line=

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.

eventthe prematch or in-play event id
period, marketas in events: moneyline or 1x2 (whichever the event has), handicap, total
linethe 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.

unavailable: when the line couldn't be bet, [from, to, reason] in ms (to exclusive, null while it still can't be). The reason is one of:

suspendedlisted, but its market was closed (the event suspended or its period closed); the point at to is the reopening price
unlistednot offered: taken off, replaced when the line moved, or its period or event gone
GET /v1/history?event=

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, scoreas /v1/events showed them
phase, clockthe state split: the period, and whole minutes (soccer counts up; basketball, hockey and football count down; null where there's no clock)
tennisscore is sets, plus games, points and server
suspendedwhen 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

GET /v1/history/events?sport=&from=&to=

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.

sportid or name; required
from, toUnix 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
leagueleague ids, or part of a league's name (case doesn't matter); repeat for several
home, away, qteam or player names, matched as in search; each match gets a score, and below 0.6 it isn't returned
limit, cursorrows 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"}
idthe prematch event: use it with /v1/history and /v1/opening-closing. null if the match was only listed in-play
liveIdthe in-play event (null if it never went in-play). Live and Scale keys only: left out for a Prematch key
kickoffwhen the prematch prices stopped (ms), normally the kick-off; null if they stopped long before the start (taken off) or haven't stopped yet
closingfalse when the match was taken off before its start: no closing prices
historyUntiluntil when /v1/history has its price moves (ms, 7 days after the start); opening and closing prices stay a year
linkedits linked events (Sets, Games, Kills, Points): id, unit, live, result
resultthe 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}
statusfinal, or void when the match was cancelled or abandoned (no score)
winnerhome, away or draw, for the whole match; null when void
periodsevery 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, updatedAtwhen 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

GET /v1/opening-closing?event=

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.

eventevent ids, comma-separated or repeated
devigadds 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

GET /v1/drops?window=900

The biggest price moves right now: one row per line side, sorted by size.

window300, 900, 3600 seconds, or open (since opening; in-play: since kick-off)
directiondrop (default), rise, both, or limit: lines whose limit moved instead
minDropminimum move in percent (default 3)
minOdds, maxOddscurrent price range (default 1.01 – 1000)
minMaxminimum max stake on the selection, USD
sport, live, marketfilters; market: moneyline (1X2 included), 1x2, handicap, total, comma-separated or repeated
main1 (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

WS wss://api.oddssea.dev/v1/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}
sportsids or names; omit for all
events, matchesids: only those (with their linked events)
livetrue: in-play only
oddsFormat, devigas on REST
openedtrue: an opened message whenever a line appears for the first time
limitstrue: 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
readythe 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/streamthe 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

FreePrematchLiveScale
USD / month$0$59$149$299
Prematch eventsdelayedreal timereal timereal time
In-play eventsneverneveryesyes
Stream connections–1110
Full snapshot (no since), per endpoint and sport1 / 60 s1 / 60 s1 / 60 s1 / 10 s
Delta (since), per endpoint and sport–1 / 10 s1 / 5 s1 / s
REST requests, all together10 / min, 100 / day60 / min120 / min600 / 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"}

400INVALID_REQUEST_DATA: a parameter is missing or wrong; the message says which
401UNAUTHORIZED: no key, or an unknown one
403FORBIDDEN: not in your plan (for example in-play history with a Prematch key)
403PLAN_REQUIRED: your plan doesn't include this (the Free plan's limits above); the message says what it has
404NOT_FOUND: no such sport, event, match or endpoint
405METHOD_NOT_ALLOWED: every endpoint is a GET (the streams are WebSocket)
429TOO_MANY_REQUESTS: over a limit; wait Retry-After seconds
streamTOO_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
503SERVICE_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 2026A 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 2026Streams 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 2026The 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 2026Results: 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.