DEV Community: Ryan

Pinnacle WebSocket API in 2026: Build a Live Odds Client in Python and Node.js

Ryan — Sun, 30 Aug 2026 22:21:17 +0000

Pinnacle's public API closed on 23 July 2025, and the modern way to hold its live odds in your own process is a WebSocket feed: a connection that pushes every change the moment it happens, into state you control. This post builds a working live-odds client against pinnapi's WS protocol, start to finish: connect, subscribe, seed, merge, survive disconnects. Roughly 60 lines of Python by the end, with the same client in Node.js at the bottom for the JS side of the room. The payoff for those 60 lines is a full local mirror of the book, the substrate for anything that needs complete market state rather than isolated pings: odds screens, derivative pricing, or strategy code that asks "what does the whole board look like right now" a thousand times a second without a network call.

Disclosure first: I run pinnapi, the feed used below. The handling patterns here (snapshot seeding, delta merging, keepalive, reconnect) transfer to any WebSocket odds feed, so the post should be useful even if you never touch mine.

The protocol in one minute

Endpoint: wss://pinnapi.com/ws/feed?key=YOUR_KEY. Query-param auth is the documented form for the WebSocket. Commercially: the raw WS is a +$99/mo add-on on any pinnapi plan (plans run $99–$229/mo, and the free tier of 100 requests a day with no card covers the REST and SSE side).

You subscribe by sending one message:

{"type": "subscribe", "streams": ["live", "prematch"], "sport_ids": [1, 2], "event_ids": []}

Scope it by stream, by sport, or down to individual events. The server then sends:

snapshot first: a stream's current events, which seeds your local state
live: incremental frames carrying rec (a record) and op (what to do with it)
prematch_matchups: sport_id plus data
prematch_markets: matchup_id plus data
error: code and message

Keepalive is a contract, not a suggestion: the server sends {"type": "ping"} and your client must reply {"type": "pong"}. The op values on live frames: "add" means a new event or new markets appeared, insert; "upd" is an incremental delta, merge it by its composite key and never replace the whole list; "del" means the event was kicked off, settled, or voided, drop your copy. Upstream, Pinnacle pushes incremental updates over MQTT and the feed forwards frames, so the rhythm you handle is the book's own. The field reference per frame type is in the docs.

Step 1: connect and subscribe

The websockets library, the key from an env var, one subscribe message on open. One design note before the code: subscribe as narrowly as your product allows. The subscription is scoped by stream, sport, or event precisely so the connection carries only what your model consumes, and every frame you do not receive is parse work, memory, and merge risk you do not pay for. A client that subscribes to everything "to be safe" is usually a client that has not decided what it is for.

import asyncio, json, os
import websockets

KEY = os.environ["PINNAPI_KEY"]
URL = f"wss://pinnapi.com/ws/feed?key={KEY}"

SUBSCRIBE = {
    "type": "subscribe",
    "streams": ["live", "prematch"],
    "sport_ids": [1, 2],
    "event_ids": [],
}

Step 2: local state and the snapshot

The whole point of a raw WebSocket over filtered alerts is that you hold the book yourself. That is a dict, a key function, and a seeding hook for the snapshot frame.

The key function deserves a moment, because it is the contract that makes the whole protocol coherent. The snapshot and every later delta must agree on what identifies one market row; if they do not, an upd lands beside the row it should have modified instead of on top of it, and your book silently forks into stale and fresh copies of the same market. Whatever fields you build the key from, build it in exactly one place and use it on both the seeding path and the delta path:

book = {}

def composite_key(rec):
    """One market row's identity. Replace with the real key fields
    from the docs' field reference for your subscribed streams."""
    return json.dumps(rec, sort_keys=True)  # placeholder key

def seed(frame):
    # index the snapshot's events by composite_key here;
    # the exact payload layout is in the docs' field reference
    pass

Step 3: the dispatch loop

Every frame is one of five types, and live frames switch on op:

def apply_live(rec, op):
    k = composite_key(rec)
    if op == "add":          # new event, or new markets on one
        book[k] = rec
    elif op == "upd":        # delta: merge, never replace the list
        book.setdefault(k, {}).update(rec)
    elif op == "del":        # kicked off, settled, or voided
        book.pop(k, None)

async def run():
    async with websockets.connect(URL) as ws:
        await ws.send(json.dumps(SUBSCRIBE))
        async for raw in ws:
            msg = json.loads(raw)
            t = msg.get("type")
            if t == "ping":
                await ws.send(json.dumps({"type": "pong"}))
            elif t == "snapshot":
                seed(msg)
            elif t == "live":
                apply_live(msg["rec"], msg["op"])
            elif t == "prematch_matchups":
                print("matchups for sport", msg["sport_id"])
            elif t == "prematch_markets":
                print("markets for matchup", msg["matchup_id"])
            elif t == "error":
                print("error:", msg["code"], msg["message"])

The comment on upd deserves its own sentence, because it is the bug I see most. An upd frame carries the fields that changed, not the record's full current form. Replace your local row wholesale and you erase every field the delta did not mention; merge by the composite key and your local row converges on the truth with each frame. That is the entire discipline of running a local mirror, in one dict.update call.

Step 4: surviving disconnects

Connections drop. The protocol makes recovery cheap: reconnect, resubscribe, and the server's fresh snapshot frame reseeds your state from scratch.

async def main():
    while True:
        try:
            await run()
        except (websockets.ConnectionClosed, OSError) as err:
            print("disconnected:", err, "- reconnecting")
            book.clear()          # snapshot on reconnect reseeds state
            await asyncio.sleep(2)

asyncio.run(main())

One sentence on why this pattern matters: a dropped connection costs you the gap while you were away, but never your correctness, because you throw away the possibly stale book and rebuild present-tense state from the new snapshot instead of guessing what changed in the dark.

The whole client

Assembled, about sixty lines, runnable as-is once you adapt composite_key and seed to the streams you subscribe to. From here the natural next steps are the ones your product defines: expose book to your strategy code behind a read interface, log every del (a vanished market is information, not just cleanup), and stamp receive time on each frame the moment it arrives so you can watch your own end-to-end latency instead of assuming it.

import asyncio, json, os
import websockets

KEY = os.environ["PINNAPI_KEY"]
URL = f"wss://pinnapi.com/ws/feed?key={KEY}"

SUBSCRIBE = {
    "type": "subscribe",
    "streams": ["live", "prematch"],
    "sport_ids": [1, 2],
    "event_ids": [],
}

book = {}

def composite_key(rec):
    """One market row's identity. Replace with the real key fields
    from the docs' field reference for your subscribed streams."""
    return json.dumps(rec, sort_keys=True)  # placeholder key

def seed(frame):
    # index the snapshot's events by composite_key here
    pass

def apply_live(rec, op):
    k = composite_key(rec)
    if op == "add":
        book[k] = rec
    elif op == "upd":
        book.setdefault(k, {}).update(rec)
    elif op == "del":
        book.pop(k, None)

async def run():
    async with websockets.connect(URL) as ws:
        await ws.send(json.dumps(SUBSCRIBE))
        async for raw in ws:
            msg = json.loads(raw)
            t = msg.get("type")
            if t == "ping":
                await ws.send(json.dumps({"type": "pong"}))
            elif t == "snapshot":
                seed(msg)
            elif t == "live":
                apply_live(msg["rec"], msg["op"])
            elif t == "prematch_matchups":
                print("matchups for sport", msg["sport_id"])
            elif t == "prematch_markets":
                print("markets for matchup", msg["matchup_id"])
            elif t == "error":
                print("error:", msg["code"], msg["message"])

async def main():
    while True:
        try:
            await run()
        except (websockets.ConnectionClosed, OSError) as err:
            print("disconnected:", err, "- reconnecting")
            book.clear()
            await asyncio.sleep(2)

asyncio.run(main())

The same client in Node.js

Identical protocol, identical discipline, the ws package instead of websockets. The browser note first: query-param auth exists precisely because browser WebSocket clients cannot set headers, so this same URL works with the native WebSocket in a browser tab too.

// npm i ws
const WebSocket = require("ws");

const KEY = process.env.PINNAPI_KEY;
const URL = `wss://pinnapi.com/ws/feed?key=${KEY}`;

const book = new Map();
// same caveat as the Python version: replace with the real key
// fields from the docs' field reference for your streams
const keyOf = (rec) => JSON.stringify(rec); // placeholder key

function connect() {
  const ws = new WebSocket(URL);

  ws.on("open", () =>
    ws.send(JSON.stringify({
      type: "subscribe",
      streams: ["live", "prematch"],
      sport_ids: [1, 2],
      event_ids: [],
    }))
  );

  ws.on("message", (raw) => {
    const msg = JSON.parse(raw);
    switch (msg.type) {
      case "ping":                    // liveness contract
        ws.send(JSON.stringify({ type: "pong" }));
        break;
      case "snapshot":                // seed the book here
        break;
      case "live": {
        const k = keyOf(msg.rec);
        if (msg.op === "add") book.set(k, msg.rec);
        else if (msg.op === "upd")    // delta: merge, never replace
          book.set(k, { ...(book.get(k) || {}), ...msg.rec });
        else if (msg.op === "del") book.delete(k);
        break;
      }
      case "error":
        console.error(msg.code, msg.message);
        break;
    }
  });

  ws.on("close", () => {              // snapshot on reconnect reseeds
    book.clear();
    setTimeout(connect, 2000);
  });
}

connect();

Same shape as the Python client: the spread on upd is the merge-never-replace rule, the close handler is the reconnect-and-reseed pattern, and the pong reply keeps liveness provable.

How fast does a frame arrive?

Own figures only, with the span named, because a latency number without its two endpoints is noise: from pinnapi's ingestion edge to a nearby European client, frames arrive in roughly 15–40 ms, median 22 ms, p99 41 ms. The methodology is public at the latency benchmark, and the standing rule applies to my numbers before anyone else's: every latency figure is a hypothesis until you measure it from your own box, in the region you will actually run in. I quote nothing for other feeds here.

One honest caveat before you copy any of this. If all you need is "tell me when a price drops X percent," you do not need this build: the SSE drop stream does the watching server-side with ?min_drop in about ten lines, no state and no merge logic, and the drop alerts guide walks it end to end. The WebSocket earns its keep when the product is a full local mirror of the book. For alert-shaped work it is over-engineering, and I say that as the person selling it.

Questions I keep getting

Is there a WebSocket API for Pinnacle odds? Yes, from independent feeds; Pinnacle itself has had no public API since July 2025. pinnapi's WebSocket runs at wss://pinnapi.com/ws/feed, sold as a +$99/mo add-on on any plan.

What messages does a Pinnacle WebSocket send? On pinnapi's feed: a snapshot frame first to seed local state, then live frames carrying a record and an op (add, upd, del), prematch_matchups and prematch_markets frames for the prematch side, error frames with a code and message, and ping frames your client must answer with pong.

How do I keep the connection alive? Two habits: reply {"type": "pong"} to every server {"type": "ping"}, and wrap the connection in a reconnect loop that resubscribes on drop and lets the fresh snapshot reseed your state. A dropped connection then costs you the gap, not your correctness.

Can I place bets through it? No. It is a data feed, not a sportsbook: prices flow to your code and nothing flows back toward a betting market. pinnapi is independent and not affiliated with Pinnacle.

I run pinnapi, an independent Pinnacle-only odds feed. pinnapi is not affiliated with or endorsed by Pinnacle.

Pinnacle Killed Its Public API. Here's How to Get Pinnacle Odds in 2026 (With Code)

Ryan — Mon, 06 Jul 2026 20:36:38 +0000

If you build betting models, you already know the bad news: Pinnacle shut down public access to its API in July 2025. A decade of tutorials, GitHub repos, and Stack Overflow answers now point at endpoints that return nothing unless you're a commercial partner.

This post is the writeup I wish I'd found the week that happened. It covers the three realistic ways to get Pinnacle odds into your code today, and more importantly the architectural difference between them that most comparison posts skip entirely: polling vs push.

Why this one bookmaker matters

Skip this if you know it: Pinnacle is the sharpest major book, and its line is the closest public proxy for true probability. Arbitrage and value betting strategies are, mechanically, "react to a Pinnacle move before a soft bookmaker adjusts." Which means your entire edge lives inside a window of a few seconds and your data architecture decides whether you're inside or outside that window.

That's the lens for everything below.

The polling trap

Most odds APIs are REST-only. Your integration inevitably looks like this:

import time
import requests

while True:
    resp = requests.get(
        "https://api.example-odds-provider.com/v4/odds",
        params={"bookmakers": "pinnacle", "markets": "h2h"},
    )
    process(resp.json())
    time.sleep(10)  # rate limits say hi

Count the delays stacked in that loop:

Your polling interval (10s here — and on most providers' affordable tiers, rate limits or credit costs force it higher)
The provider's own update cycle — how often they refresh from Pinnacle (often tens of seconds on cheaper plans)
How they get the data — some providers scrape Pinnacle's public website rather than ingesting a feed. The Odds API, to its credit, says this in its own docs: Pinnacle "odds are from public website which may incur a delay."

Worst case, a price moved 40+ seconds before your bot sees it. For closing-line research, irrelevant. For arbitrage, that's not "slower" it's a different product. The opportunity was found, bet, and closed by faster actors while your time.sleep() was still counting down.

The push alternative

The fix is architectural, not a faster loop: the provider holds a connection open and pushes every change the moment it happens. The examples below use pinnapi, which is built around this model and exposes it two ways SSE for drop alerts, WebSocket for the full odds feed.

Option A: SSE drop stream

The simplest integration is the server-sent-events drop stream: you tell the server your threshold with min_drop, and it watches every Pinnacle price for you. One GET request, then drops arrive as they happen:

import json
import requests
from sseclient import SSEClient

resp = requests.get(
    "https://pinnapi.com/odds-drop?min_drop=3",
    headers={"x-portal-apikey": API_KEY},
    stream=True,
)

for event in SSEClient(resp).events():
    payload = json.loads(event.data)
    if isinstance(payload, list):          # first message is a "connected" handshake
        for drop in payload:
            print(f'{drop["home"]}: {drop["from_price"]} -> {drop["to_price"]}')
            evaluate_opportunity(drop)     # fires when Pinnacle moves, not when a loop wakes up

There's a /odds-drop-prematch variant of the same stream (with an optional recheck parameter that confirms a drop is stable before alerting), so you can run live and prematch strategies off separate connections.

Notice what disappeared versus the polling version: the interval, the credit math, and the entire client-side diffing layer. Server-side drop detection is something polling structurally can't give you — you can't diff snapshots you haven't fetched yet.

Option B: WebSocket for the full feed

Drops are the signal; sometimes you want the whole market state. The WebSocket feed at wss://pinnapi.com/ws/feed gives you a snapshot on subscribe, then streams every add/update/delete as it happens:

import asyncio
import json
import websockets

async def main():
    async with websockets.connect(f"wss://pinnapi.com/ws/feed?key={API_KEY}") as ws:
        await ws.send(json.dumps({
            "type": "subscribe",
            "streams": ["live"],
            "sport_ids": [1, 2],           # 1 = soccer, 2 = tennis
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg["type"] == "ping":      # heartbeat reply or get disconnected
                await ws.send(json.dumps({"type": "pong"}))
            elif msg["type"] == "snapshot":
                seed_order_book(msg["events"])
            elif msg["type"] == "live":
                apply_update(msg["rec"])   # a raw Pinnacle record, add/upd/del

asyncio.run(main())

You subscribe by stream (live, prematch), by sport, or down to individual event_ids, so the connection carries only what your model actually consumes.

Either way, the latency budget collapses to network transit plus the provider's ingestion time pinnapi quotes 15–40 ms from a Pinnacle price change to your handler, and my own measurements land in that range. Against a 10-second polling loop, that's two-to-three orders of magnitude, on the exact metric the strategy lives on.

Your three options in 2026

OpticOdds — the enterprise answer. 200+ books including Pinnacle, excellent infrastructure, real push feeds. No public pricing; you talk to sales, and quotes generally start in the high hundreds per month and climb. If you're a funded operation, it's the best product in the space. If you're an individual, you're not the customer.

pinnapi — the specialist. Pinnacle-only by design: push delivery (SSE/WebSocket/REST), drop alerts, and no-vig fair prices built in, across 10+ sports live and prematch. Published pricing from $99 to $229/month, and a free tier (100 REST requests/day, no card) that's enough to benchmark the latency claims yourself before paying — which is how it should work. The tradeoff is the point: one book, done properly, at a price an individual can justify.

The Odds API — the generalist. Dozens of books in one normalized schema, genuinely free tier (500 credits/month), great docs, and the whole internet recommends it. But it's polling-only REST, credits burn as markets × regions per call, and its Pinnacle data specifically is website-scraped with a documented delay. Perfect for backtesting and multi-book dashboards; the wrong architecture for anything latency-sensitive.

	OpticOdds	pinnapi	The Odds API
Delivery	Push (enterprise)	Push — SSE/WS, 15–40 ms	Polling REST only
Pinnacle source	Direct	Direct, purpose-built	Public-site scrape, documented delay
Drop alerts / no-vig	Platform tooling	Built in	No
Pricing	Custom quote	$99–$229/mo published	Cheapest, credit-based
Free tier	No	100 req/day	500 credits/mo

Picking by use case, not by feature list

Backtesting or CLV research? The Odds API. Latency doesn't matter for historical analysis, and the free tier is real.
Live arbitrage or steam chasing as an individual or small team? pinnapi. It's the only push-based option priced for you, and drop alerts remove a whole component from your stack.
Building a sportsbook or trading desk? OpticOdds, and budget accordingly.

The one mistake I keep seeing in betting-dev communities: building a latency-sensitive strategy on a polling API because it was the first result, then blaming the strategy when it bleeds. Audit the delivery mechanism before you write the model. It's the highest-leverage architecture decision in the whole system.

I build betting models and infrastructure. No affiliate links here pricing and latency figures are from provider docs and my own testing as of mid-2026; check current docs before you commit.