Guia · Python · Node

Odds da Pinnacle em tempo real via WebSocket com Python e Node

Atualizado em 9 de novembro de 2026 · PinnFeed · 5 min de leitura

Neste guia você monta um cliente que mantém em memória uma cópia viva dos preços da Pinnacle: ele conecta, assina, carrega o snapshot, aplica cada delta, responde aos heartbeats e reconecta sozinho. Os outros guias (alertas de steam, value bet, o bot de Telegram) partem dele.

Você precisa de uma chave da PinnFeed no plano Builder (o plano WebSocket, €99/mês, 3 dias grátis). Com uma chave Free ou Hobby dá para acompanhar os exemplos REST da documentação (em inglês).

Passo 1 — Pegue uma chave e coloque no ambiente#

Crie uma chave no painel e exporte, para ela nunca ir parar no seu código:

export PINNFEED_KEY="pf_live_..."

Passo 2 — Entenda os frames#

Depois de conectar e enviar subscribe, o servidor manda:

subscribed e depois um snapshot em partes (part, parts, final) com todos os eventos e mercados que batem com seus filtros;
frames delta, cada um com uma lista de changes: upsert traz o objeto novo completo e remove só o id;
um ping a cada 20 segundos. Responda com {"type":"pong"} ou o servidor fecha o socket depois de 60 segundos de silêncio.

Os mercados são identificados por id (eventId:key), então um dicionário é todo o estado de que você precisa. Cada resultado traz decimal, american, fair (odd justa sem margem) e fairProb. A referência do WebSocket (em inglês) lista todos os campos.

Passo 3 — O cliente em Python#

Instale a única dependência com pip install websockets (Python 3.9+). Salve como pinnfeed_stream.py; os guias de steam e de Telegram importam esse arquivo.

# pinnfeed_stream.py: mantém uma cópia ao vivo do book da Pinnacle a partir do WebSocket da PinnFeed.
# pip install websockets   (Python 3.9+)
import asyncio, json, os, random
import websockets

WS_URL = os.environ.get("PINNFEED_WS", "wss://pinnfeed.io/v1/stream")
KEY = os.environ["PINNFEED_KEY"]
SIDES = {"home", "away", "draw", "over", "under"}


class Book:
    """Eventos e mercados por id, atualizados pelos frames snapshot + delta."""

    def __init__(self):
        self.events, self.markets = {}, {}

    def apply(self, msg, on_market=None):
        if msg["type"] == "snapshot":
            for e in msg["events"]:
                self.events[e["id"]] = e
            for m in msg["markets"]:
                self.markets[m["id"]] = m
        elif msg["type"] == "delta":
            for c in msg["changes"]:
                if c["kind"] == "event" and c["op"] == "upsert":
                    self.events[c["event"]["id"]] = c["event"]
                elif c["kind"] == "event" and c["op"] == "remove":
                    self.events.pop(c["id"], None)
                    for mid in [k for k, m in self.markets.items() if m["eventId"] == c["id"]]:
                        del self.markets[mid]
                elif c["kind"] == "market" and c["op"] == "upsert":
                    old = self.markets.get(c["market"]["id"])
                    self.markets[c["market"]["id"]] = c["market"]
                    if on_market:
                        on_market(old, c["market"], self.events.get(c["market"]["eventId"]))
                elif c["kind"] == "market" and c["op"] == "remove":
                    self.markets.pop(c["id"], None)


async def stream(subscription, on_market=None, on_ready=None):
    """Conecta, assina e mantém o book atualizado; reconecta com backoff para sempre."""
    delay = 1
    while True:
        book = Book()
        try:
            async with websockets.connect(WS_URL, additional_headers={"x-api-key": KEY}, max_size=None) as ws:
                await ws.send(json.dumps({"type": "subscribe", **subscription}))
                async for raw in ws:
                    msg = json.loads(raw)
                    if msg["type"] == "ping":
                        await ws.send('{"type":"pong"}')
                    elif msg["type"] == "error":
                        print("server error:", msg["code"], msg["message"])
                    elif msg["type"] in ("snapshot", "delta"):
                        book.apply(msg, on_market if msg["type"] == "delta" else None)
                        if msg["type"] == "snapshot" and msg.get("final") and on_ready:
                            on_ready(book)
                        delay = 1
        except (OSError, websockets.ConnectionClosed) as e:
            print(f"disconnected ({e}); reconnecting in {delay}s")
        await asyncio.sleep(delay + random.random())
        delay = min(delay * 2, 30)


if __name__ == "__main__":
    def ready(book):
        print(f"book ready: {len(book.events)} events, {len(book.markets)} markets")

    def moved(old, new, event):
        if old and event:
            for o_old, o_new in zip(old["outcomes"], new["outcomes"]):
                if o_new["name"] in SIDES and o_old["decimal"] != o_new["decimal"]:
                    print(f'{event["home"]} v {event["away"]} {new["type"]} {o_new["name"]}: '
                          f'{o_old["decimal"]} -> {o_new["decimal"]} (fair {o_new["fair"]})')

    asyncio.run(stream({"sports": ["soccer"], "markets": ["moneyline"], "main": True, "specials": False}, moved, ready))

Rode com python pinnfeed_stream.py. Você verá book ready: N events, M markets e depois uma linha por movimento de preço.

Passo 4 — O cliente em Node#

A mesma lógica em Node 18+ com npm install ws. Salve como stream.mjs e rode node stream.mjs.

// stream.mjs: book da Pinnacle ao vivo a partir do WebSocket da PinnFeed (Node 18+).
// npm install ws
import WebSocket from 'ws';

const WS_URL = process.env.PINNFEED_WS || 'wss://pinnfeed.io/v1/stream';
const KEY = process.env.PINNFEED_KEY;
const SIDES = new Set(['home', 'away', 'draw', 'over', 'under']);
const events = new Map();
const markets = new Map();

function connect(delay = 1000) {
  const ws = new WebSocket(WS_URL, { headers: { 'x-api-key': KEY }, perMessageDeflate: true });
  ws.on('open', () => {
    delay = 1000;
    ws.send(JSON.stringify({ type: 'subscribe', sports: ['soccer', 'tennis'], markets: ['moneyline'], main: true, specials: false }));
  });
  ws.on('message', (raw) => {
    const msg = JSON.parse(raw);
    if (msg.type === 'ping') return ws.send('{"type":"pong"}');
    if (msg.type === 'error') return console.error('server error:', msg.code, msg.message);
    if (msg.type === 'snapshot') {
      if (msg.part === 1) { events.clear(); markets.clear(); }
      msg.events.forEach((e) => events.set(e.id, e));
      msg.markets.forEach((m) => markets.set(m.id, m));
      if (msg.final) console.log(`book ready: ${events.size} events, ${markets.size} markets`);
    }
    if (msg.type === 'delta') {
      for (const c of msg.changes) {
        if (c.kind === 'event') c.op === 'upsert' ? events.set(c.event.id, c.event) : events.delete(c.id);
        if (c.kind === 'market' && c.op === 'remove') markets.delete(c.id);
        if (c.kind === 'market' && c.op === 'upsert') {
          const old = markets.get(c.market.id);
          markets.set(c.market.id, c.market);
          const ev = events.get(c.market.eventId);
          if (!old || !ev) continue;
          c.market.outcomes.forEach((o, i) => {
            const prev = old.outcomes[i];
            if (prev && SIDES.has(o.name) && prev.decimal !== o.decimal) console.log(`${ev.home} v ${ev.away} ${o.name}: ${prev.decimal} -> ${o.decimal} (fair ${o.fair})`);
          });
        }
      }
    }
  });
  ws.on('close', (code) => {
    const wait = Math.min(delay * 2, 30000);
    console.log(`closed (${code}); reconnecting in ${wait / 1000}s`);
    setTimeout(() => connect(wait), wait + Math.random() * 1000);
  });
  ws.on('error', (e) => console.error('ws error:', e.message));
}
connect();

Passo 5 — Restrinja a assinatura#

Os filtros rodam no servidor, então você só recebe e processa o que pediu:

{ "type": "subscribe", "sports": ["tennis"], "live": true, "markets": ["moneyline", "total"], "main": true }

sports: slugs ou ids; leagues e events: listas de ids.
live: true só ao vivo, false só pré-jogo; omita para os dois.
main: true mantém só o moneyline, o handicap e o total principais de cada evento.
Enviar subscribe de novo substitui a assinatura e manda um snapshot novo.

Checklist de produção#

Reconecte com backoff e jitter (os dois clientes fazem isso: 1 s, 2 s, 4 s, até 30 s) e reconstrua a partir do novo snapshot.
Ative a compressão: o websockets do Python negocia permessage-deflate por padrão; no Node passe perMessageDeflate: true. Os snapshots ficam de 5 a 10 vezes menores.
Leia rápido. Se mais de 16 MB se acumularem para um cliente lento, o servidor fecha com o código 4008. Faça o trabalho pesado fora do loop do socket.
Use seq para log, não para detectar buracos: os filtros pulam lotes que você não assinou.

Perguntas frequentes#

Qual plano preciso para o WebSocket?#

Builder (€99/mês) ou superior. Chaves Free e Hobby recebem 403 plan_lacks_ws no WebSocket e podem usar REST.

Quantas conexões posso abrir?#

O Builder permite 3 conexões WebSocket por conta e o Pro, 10.

Por que alguns resultados têm ids de participante em vez de home ou away?#

Especiais e alguns futuros listam participantes em vez de mandante e visitante. Assine com "specials": false e filtre por home, away, draw, over e under se quiser só linhas de partida, como fazem os exemplos.