API Documentation

Live and prematch odds from the Betfair exchange — back and lay prices with the size available at each, per runner, per market — normalised into one event map and served over REST and WebSocket.

Base URL https://betfair-odds.com/betfair/v1/. One API key authenticates every endpoint on this page: x-portal-apikey, x-api-key, or ?key= (see Authentication).

Plans

Per-second rates for each tier are in Plans & rate limits.

Every plan allows one concurrent WebSocket connection. Open one socket and fan out inside your own process; a second connection on the same key is rejected rather than replacing the first.

Feeds

Every endpoint takes ?feed=, which selects the data set:

Full current snapshot of a feed. Returns { meta, liveMap }.

Query parameters

curl -H "x-portal-apikey: $KEY" \
  "https://betfair-odds.com/betfair/v1/livemap?feed=live&sports=soccer,tennis"

const res = await fetch(
  "https://betfair-odds.com/betfair/v1/livemap?feed=live&sports=soccer",
  { headers: { "x-portal-apikey": process.env.KEY } }
);
const { meta, liveMap } = await res.json();
// meta.stale tells you if the feed has gone quiet
console.log(meta.event_count, meta.stale);

import os, requests

r = requests.get(
    "https://betfair-odds.com/betfair/v1/livemap",
    params={"feed": "live", "sports": "soccer"},
    headers={"x-portal-apikey": os.environ["KEY"]},
    timeout=30,
)
r.raise_for_status()
data = r.json()
print(data["meta"]["event_count"], data["meta"]["stale"])

req, _ := http.NewRequest("GET",
    "https://betfair-odds.com/betfair/v1/livemap?feed=live", nil)
req.Header.Set("x-portal-apikey", os.Getenv("KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

$ch = curl_init("https://betfair-odds.com/betfair/v1/livemap?feed=live");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-portal-apikey: " . getenv("KEY")]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);

Response

{
  "meta": {
    "feed": "live",
    "receivedAt": "2026-07-28T12:00:00.000Z",
    "seq": 1234,
    "stale": false,
    "age_ms": 850,
    "event_count": 512
  },
  "liveMap": { /* eventId -> event */ }
}

gzip is pre-computed once per update and served when Accept-Encoding includes gzip and no sports filter is set — a filtered response is built per request and cannot reuse the cached compressed copy. Before the first data arrives this returns 503 no_data_yet.

A cheap index of what is on the feed — poll this instead of pulling the whole snapshot when you only need to know what changed. Returns { meta, events }.

Takes the same feed and sports parameters as /livemap.

Rows carry no prices — that is what makes it cheap. marketCount tells you how many markets an event has; fetch them from /events/{eventId} or take the whole book from /livemap. See the Event object for the full shape.

Response

{
  "meta": { /* as above */ },
  "events": [
    {
      "eventId": "1.234567890",
      "team1": "Arsenal",
      "team2": "Chelsea",
      "sport": "soccer",
      "tournament": "Premier League",
      "openTimestamp": 1789000000000,
      "marketCount": 42
    }
  ]
}

One event, byte-identical to what we ingested. Returns { meta, event }.

curl -H "x-portal-apikey: $KEY" \
  "https://betfair-odds.com/betfair/v1/events/1.234567890?feed=prematch"

An id that is not on the feed returns 404 unknown_event. That body still carries meta, so a miss tells you how fresh the feed was when it missed.

What your key is entitled to on the Betfair product.

{
  "tier": "scale",
  "active": true,
  "expires_at": 1789000000000,
  "ws_active": true,
  "ws_until": 1789000000000,
  "is_admin": false,
  "capabilities": ["rest_live", "rest_prematch", "ws_live", "ws_prematch"],
  "limits": { "perSec": 30 },
  "max_connections": 1
}

Feed freshness and service state. No key required. The same handler answers /ping.

{
  "ok": true,
  "service": "betfair",
  "feeds": { "live": { "stale": false, "age_ms": 850, /* ...meta */ } },
  "senders": { }, "clients": 3, "ingest": { }, "ws": { }
}

GET /betfair/v1/status returns the same information as a human-readable HTML page.

Staleness thresholds

Each feed has its own threshold:

Transitions are detected by a 5-second polling loop, so the WebSocket stale frame can lag the threshold by up to 5 s. meta.age_ms is the exact measure.

wss://betfair-odds.com/betfair/v1/stream — push instead of polling. Included in Pro + WS and Scale; available on plain Pro as a $99/mo add-on.

1. Authenticate — within 10 seconds

{ "action": "authenticate", "apiKey": "YOUR_KEY" }

The server replies:

{ "type": "authenticated", "tier": "scale", "is_admin": false,
  "ws_addon": true, "capabilities": ["rest_live", "ws_live"] }

Miss the 10-second deadline and you receive {"type":"error","code":"auth_timeout"} followed by close 1008.

2. Subscribe

{ "action": "subscribe", "feeds": ["live"], "sports": ["soccer"] }

The key is action (not type) and feeds (not streams). Omitting feeds defaults to ["live"].

You get an acknowledgement first, then the snapshot:

{ "type": "subscribed", "feed": "live", "sports": [] }

A feed you are not entitled to does not close the socket — you receive {"type":"error","code":"...","feed":"...","required_capability":"..."} and the other feeds in the same request still subscribe.

Unsubscribe with {"action":"unsubscribe","feeds":["live"]}, acknowledged as {"type":"unsubscribed","feeds":[...]}.

3. Data frames

{ "type": "snapshot", "feed": "live", "meta": {…}, "liveMap": {…} }
{ "type": "update",   "feed": "live", "meta": {…}, "changed": {…}, "removed": […] }
{ "type": "stale",    "feed": "live", "stale": true }

The snapshot payload lives under liveMap.

4. Heartbeat

{ "type": "ping", "ts": 1789000000000, "buffered_max_bytes": 0 }   // every 30s
{ "action": "pong" }                                        // your reply

5. One connection per key

Example clients

npx wscat -c wss://betfair-odds.com/betfair/v1/stream
> {"action":"authenticate","apiKey":"YOUR_KEY"}
> {"action":"subscribe","feeds":["live"]}
# reply to each ping with: {"action":"pong"}

import WebSocket from "ws";

const ws = new WebSocket("wss://betfair-odds.com/betfair/v1/stream");
const book = new Map();

ws.on("open", () =>
  ws.send(JSON.stringify({ action: "authenticate", apiKey: process.env.KEY })));

ws.on("message", (buf) => {
  const m = JSON.parse(buf);
  switch (m.type) {
    case "authenticated":
      // ws_addon:false means the tier is active but the add-on is not
      if (!m.ws_addon) throw new Error("WebSocket add-on inactive");
      ws.send(JSON.stringify({ action: "subscribe", feeds: ["live"] }));
      break;
    case "snapshot":
      // single-chunk snapshots have NO seq/final — never wait for final
      for (const [id, ev] of Object.entries(m.liveMap ?? {})) book.set(id, ev);
      break;
    case "update":
      for (const [id, ev] of Object.entries(m.changed ?? {})) book.set(id, ev);
      for (const id of m.removed ?? []) book.delete(id);
      break;
    case "ping":
      ws.send(JSON.stringify({ action: "pong" }));   // action, not type
      break;
    case "error":
      console.error(m.code, m.message);   // WS uses `code`, REST uses `error`
      break;
  }
});

import asyncio, json, os, websockets

async def main():
    url = "wss://betfair-odds.com/betfair/v1/stream"
    async with websockets.connect(url) as ws:
        await ws.send(json.dumps({"action": "authenticate",
                                 "apiKey": os.environ["KEY"]}))
        book = {}
        async for raw in ws:
            m = json.loads(raw)
            t = m.get("type")
            if t == "authenticated":
                if not m.get("ws_addon"):
                    raise RuntimeError("WebSocket add-on inactive")
                await ws.send(json.dumps({"action": "subscribe",
                                         "feeds": ["live"]}))
            elif t == "snapshot":
                book.update(m.get("liveMap") or {})
            elif t == "update":
                book.update(m.get("changed") or {})
                for i in m.get("removed") or []: book.pop(i, None)
            elif t == "ping":
                await ws.send(json.dumps({"action": "pong"}))

asyncio.run(main())

Close codes

Backpressure eviction fires on a sustained backlog above 1 MB for 60 s, or above 128 MB instantly. The buffered_max_bytes field on each ping is the high-water mark since the previous ping, so it measures your headroom rather than only reporting breaches. Compression (permessage-deflate) is always enabled server-side above 1 KB — there is nothing to configure on your side.

Error envelopes & WebSocket codes

The status codes themselves are listed under Errors. What follows is the part that bites: the two transports do not shape an error the same way.

// REST
{ "error": "no_betfair_plan", "message": "…",
  "required_capability": "rest_live", "current_tier": null }

// WebSocket
{ "type": "error", "code": "unknown_feed", "message": "…" }

Every 403 body also carries required_capability and current_tier. Call /betfair/v1/me to see exactly what you hold.

WebSocket-only codes, none of which close the socket — handle an error frame on a still-open connection: invalid_json, invalid_message, not_authenticated, unknown_action, unknown_feed (the WebSocket equivalent of REST's bad_feed), and ws_addon_inactive when you subscribe without the add-on.

Ready to start? Claim the free 3-day Scale trial — WebSocket included — in one click from your dashboard, or pick a plan there. Questions? Telegram @ArbitrageXpro.