Blog · Geral

Resultados em tempo real: o stream SSE, evento por evento

Como receber cada rodada no instante em que ela é salva: os eventos do /stream, a reconexão com Last-Event-ID e por que SSE em vez de webhook ou WebSocket.

Publicado em 30 de outubro de 2026 · atualizado em 14 de novembro de 2026 · 11 min de leitura

O /stream passo a passo: eventos, horários e reconexão · no YouTube

Toda API de resultados ao vivo responde a mesma pergunta — "qual foi a última rodada?" — de dois jeitos. Você pergunta de tempo em tempo, ou a API te avisa. O GET /v1/{api}/stream da LynxMetrics é o segundo jeito: uma conexão HTTP que fica aberta e entrega cada rodada no instante em que ela é salva, sem intervalo de consulta no meio.

Este artigo é a referência do stream, igual para todas as APIs do catálogo. Os artigos de cada jogo mostram o mesmo mecanismo com os números daquela mesa: o Bac Bo Live, o Lightning Baccarat e a Baccarat 1.

Por que SSE, e não webhook nem WebSocket

Stream (SSE)Consultar o /latestWebhookWebSocket
Atraso além do da APInenhummetade do seu intervalo, em médianenhumnenhum
Gasto do limite por minuto1 na abertura1 por consulta——
Precisa de endereço públiconãonãosimnão
Atravessa proxy e CDNsim, é HTTP comumsimsimàs vezes não
Existe na LynxMetricssimsimnãonão

Webhook não existe, e não é esquecimento. Ele exigiria que você publicasse um endereço na internet, e do nosso lado uma tabela de destinos, assinatura de requisição e fila de reentrega — peças que podem falhar sozinhas. Para quem já tem um processo rodando, o stream entrega a mesma coisa com menos peças e sem expor nada.

WebSocket foi descartado porque traz um canal de volta que não usamos: você nunca precisa mandar nada para nós depois de abrir a conexão. SSE é HTTP comum, com um cabeçalho e uma resposta que não termina, então ele passa onde o WebSocket às vezes tromba e funciona em qualquer cliente que leia uma resposta aos poucos.

Sem conexão aberta: o ?wait= do /latest

Se o seu ambiente não deixa manter uma conexão aberta (um script que roda e sai, uma função sem servidor, um laço simples em PHP), existe um meio-termo desde 14/11/2026: peça o /latest com ?wait=20 e diga qual rodada você já tem. A resposta fica em aberto até a próxima rodada fechar e chega com ela, no mesmo instante em que o stream entregaria. Se nada fechar em 20 segundos, vem 304 e você pede de novo.

curl "https://api.lynxmetrics.com/v1/bacbo-live/latest?wait=20" \
  -H "x-api-key: SUA_CHAVE" \
  -H 'if-none-match: "ETAG_DA_ULTIMA_RESPOSTA"'

Quem não guarda o ETag manda &after= com o id da última rodada que tem. É uma requisição por rodada, em vez de uma a cada poucos segundos, e o tempo limite do seu cliente precisa ser maior que o wait. O código pronto em Python, Node.js e PHP, tanto do stream quanto desta espera, está na documentação de cada API.

Abrir a conexão

curl -N https://api.lynxmetrics.com/v1/bacbo-live/stream \
  -H "x-api-key: SUA_CHAVE" \
  -H "accept: text/event-stream"

O -N desliga o buffer do curl, senão o terminal só mostraria tudo no fim. Troque bacbo-live pelo slug da API que você assinou — a chave abre uma API só.

Os eventos

O fluxo padrão tem três eventos — ready, round e closed — e um quarto, o phase, que só chega se você pedir com ?phases=1.

No fio, cada evento é um nome, às vezes um id, e uma linha data: com o JSON compacto:

event: phase
data: {"roundId":"v1793371825421","game":"bacbo-live","phase":"resolving","at":"2026-10-30T18:10:49.903Z","sentAt":"2026-10-30T18:10:53.903Z"}

event: round
id: v1793371825421
data: {"data":{"id":"v1793371825421","outcome":"banker","settledAt":"2026-10-30T18:10:58.903Z","...":"..."},"timing":{"receivedAt":"2026-10-30T18:11:02.803Z","sentAt":"2026-10-30T18:11:02.853Z"}}
EventoQuando chegaO que fazer com ele
readyUma vez, ao abrirTraz em data a última rodada já encerrada, para você começar em dia, e numa reconexão traz também o que você perdeu. Não é rodada nova
phaseOpcional (?phases=1), quando a mesa entra na resolução da rodadaTraz o roundId que a rodada vai ter, segundos antes do resultado
roundUma por rodada novaA rodada em data e os horários da entrega em timing. É o único evento com id:
closedOutra conexão abriu com a mesma chaveFim de vida deste processo: reconectar aqui derrubaria a conexão nova

Além disso, a cada 20 segundos de silêncio vai uma linha começando com dois-pontos. É o batimento que impede um proxy no meio de fechar uma conexão parada; não é evento e pode ser ignorada.

O que o phase é, e o que ele não é

O phase existe porque a nossa fonte é a própria mesa, e o leitor sabe o momento em que ela entra na resolução da rodada — o close-up dos dados no copinho, as cartas na mesa. Nesse instante as apostas já fecharam, o resultado ainda não existe, e o id da rodada já está definido. No Bac Bo esse aviso chega cerca de 8 segundos antes do resultado.

Ele é opcional de propósito: abra a conexão com ?phases=1 para recebê-lo. E vale ser direto sobre o que ele não resolve: para saber a que rodada um resultado pertence, você não precisa do phase. O id do round, a ordem garantida dentro da conexão e o last-event-id já respondem isso sem ambiguidade. A fase só adianta essa amarração em alguns segundos — útil para quem registra algo antes do resultado, e peso inútil para quem só quer o resultado certo.

O que ele não é: promessa de resultado. Um close-up cortado, uma falha na transmissão ou uma leitura insegura fazem a rodada ser descartada de propósito — é melhor faltar do que chutar —, e aí nenhum round chega com aquele roundId. Quem guarda estado por fase precisa saber expirar uma fase que não virou rodada.

Um detalhe que poupa 35 segundos de espera: se você pediu as fases e abre a conexão no meio de uma rodada em resolução, a fase aberta chega logo depois do ready, em vez de você esperar a próxima.

Os horários, para medir o atraso em vez de estimar

O round traz quatro carimbos, de dois relógios diferentes:

CampoRelógioO que ele marca
data.startedAtmesaInício da rodada, quando as apostas abriram
data.settledAtmesaFim da rodada: o resultado ficou definido na origem
timing.receivedAtnossa APIO resultado ficou pronto do nosso lado
timing.sentAtnossa APIEste evento foi escrito na sua conexão

Com eles, cada pedaço do caminho se mede separado, e dá para saber de quem é o atraso:

  • receivedAt − settledAt é mesa até nós: a parte que está nas nossas mãos. Hoje fica em torno de 4 segundos.
  • sentAt − receivedAt é a fila desta conexão, normalmente alguns milissegundos.
  • O que sobra até o seu código rodar é rede sua.
from datetime import datetime

def atrasos(evento):
    t = lambda iso: datetime.fromisoformat(iso.replace("Z", "+00:00"))
    rodada, timing = evento["data"], evento["timing"]
    return {
        "mesa_ate_nos": (t(timing["receivedAt"]) - t(rodada["settledAt"])).total_seconds(),
        "fila": (t(timing["sentAt"]) - t(timing["receivedAt"])).total_seconds(),
        "ate_voce": (datetime.now(tz=t(timing["sentAt"]).tzinfo) - t(timing["sentAt"])).total_seconds(),
    }

O timing fica fora do data de propósito: assim o objeto da rodada continua idêntico, byte a byte, ao que o /latest e o /results devolvem, e o mesmo código trata rodada que veio do stream e rodada que veio do histórico.

Reconectar sem perder rodada

Conexão aberta cai: rede, deploy, reinício, e o fim de vida de 6 horas que toda conexão tem. O que resolve isso é o Last-Event-ID, o mecanismo padrão do SSE: você diz qual foi a última rodada que recebeu, e a API devolve o que fechou na sua ausência.

curl -N https://api.lynxmetrics.com/v1/bacbo-live/stream \
  -H "x-api-key: SUA_CHAVE" \
  -H "accept: text/event-stream" \
  -H "last-event-id: v1793371825421"

O ready então volta assim:

{
  "data": { "id": "v1793372118404", "outcome": "player", "...": "..." },
  "missed": [
    { "id": "v1793371962117", "...": "..." },
    { "id": "v1793372118404", "...": "..." }
  ]
}
  • missed traz as rodadas que fecharam enquanto você estava fora, da mais antiga para a mais nova, até 50.
  • data continua sendo a última rodada encerrada, que normalmente é o último item de missed — então trate pelo id para não contar duas vezes.
  • Como o id: só vai no evento round, o cursor que você guarda é sempre uma rodada que existe de verdade. É por isso que o phase não tem id:: ele apontaria para uma rodada que talvez nunca exista.

No navegador, o EventSource manda o Last-Event-ID sozinho ao reconectar — mas ele não manda cabeçalhos, então a chave não passa por ali e o lugar do stream é no servidor. Fora do navegador, você manda o cabeçalho ou ?last_event_id=.

Quando não dá para recuperar

A conexão abre de qualquer forma — uma reconexão não pode falhar por causa de um cursor velho. O missed vem null e aparece um resyncError dizendo o motivo (ele só existe quando algo deu errado):

resyncErrorO que aconteceuO que fazer
bad_cursorO valor não é um id de rodada nem uma data ISO 8601Corrigir o que você está guardando
unknown_roundO id não é de nenhuma rodada desta APIPode ser id de outra API, ou de uma rodada descartada depois de um phase
plan_limitA rodada é mais antiga que o histórico do seu planoSeguir do que o plano cobre
too_many_missedMais de 50 rodadas fecharam na sua ausênciaPaginar o /results?after= até ficar em dia

Ou seja: o stream resolve a ausência curta sozinho, e a ausência longa continua sendo trabalho do /results, que pagina. Os dois tetos — as 50 rodadas da recuperação e o da fila de uma conexão lenta — existem pela mesma razão: não guardar rodada indefinidamente para um cliente que não está mais lá.

Um cliente que aguenta o dia inteiro

Juntando tudo: ler os eventos, guardar o cursor, reconectar e não repetir rodada.

stream.py

import json
import time

import httpx

API = "bacbo-live"
URL = "https://api.lynxmetrics.com/v1/" + API + "/stream?phases=1"   # sem o ?phases=1 não vem event: phase
CHAVE = "SUA_CHAVE"

ultimo_id = None   # cursor: a última rodada que tratamos


def tratar(rodada):
    global ultimo_id
    if rodada["id"] == ultimo_id:
        return                      # o ready repete a última de propósito
    ultimo_id = rodada["id"]
    print(rodada["settledAt"], rodada["outcome"])


def acompanhar():
    cabecalhos = {"x-api-key": CHAVE, "accept": "text/event-stream"}
    if ultimo_id:
        cabecalhos["last-event-id"] = ultimo_id
    with httpx.stream("GET", URL, headers=cabecalhos, timeout=None) as resposta:
        resposta.raise_for_status()
        evento = None
        for linha in resposta.iter_lines():
            if linha.startswith("event:"):
                evento = linha.split(":", 1)[1].strip()
            elif linha.startswith("data:"):
                corpo = json.loads(linha.split(":", 1)[1])
                if evento == "ready":
                    if corpo.get("resyncError"):
                        print("não recuperou:", corpo["resyncError"])   # trate o too_many_missed com /results
                    for rodada in corpo.get("missed") or []:
                        tratar(rodada)
                    if corpo["data"]:
                        tratar(corpo["data"])
                elif evento == "round":
                    tratar(corpo["data"])
                elif evento == "phase":
                    print("resolvendo", corpo["roundId"])
                elif evento == "closed":
                    return "closed"


while True:
    if acompanhar() == "closed":
        print("outra conexão tomou a vaga desta chave")
        break
    time.sleep(2)

Três detalhes desse código que não são enfeite:

  1. O cursor sai do id da rodada, não de um contador seu. Ele é fixo e nunca muda.
  2. O tratar é idempotente. O ready repete a última rodada de propósito, e um cliente que não checa o id publica a mesma mão duas vezes a cada reconexão.
  3. O closed para o laço. Reconectar depois de um closed derruba a conexão que tomou o seu lugar, e as duas cópias ficam se expulsando para sempre.

Limites e cuidados

  • Conexões por chave: 1 no plano Pro e 3 no Business. Passar disso não dá erro: a conexão mais antiga daquela chave é encerrada com closed e a nova entra no lugar — assim um processo que morreu sem avisar nunca tranca você fora da sua própria vaga.
  • Fim de vida de 6 horas, mesmo numa conexão saudável. Quem roda o dia inteiro reconecta cerca de quatro vezes por dia, e com o Last-Event-ID isso é invisível no resultado final.
  • Tempo limite de leitura acima de 20 segundos no seu cliente, senão ele corta a conexão no silêncio entre uma rodada e outra. Em Python, timeout=None.
  • Custo: abrir a conexão gasta 1 requisição do seu limite por minuto; as rodadas que chegam depois não gastam nada. Acompanhar pelo stream pesa muito menos que consultar o /latest a cada 3 segundos.
  • A chave fica no servidor. No navegador ela ficaria à vista de qualquer visitante — veja segurança da API.

Onde ver isso funcionando

A documentação de cada API traz a tabela de eventos, os campos e os limites do seu plano, e cada jogo tem o seu artigo com os números da mesa: Bac Bo Live, Lightning Baccarat e Baccarat 1. Para montar algo em cima disso, o bot de Telegram é o caminho mais curto do stream até uma mensagem no grupo.

Perguntas frequentes

O que é o endpoint /stream da LynxMetrics?

É uma conexão HTTP que fica aberta (Server-Sent Events) e entrega cada rodada no instante em que ela é salva, em vez de você consultar a API de tempo em tempo. Abrir a conexão gasta uma requisição do seu limite por minuto, e as rodadas que chegam depois não gastam nada.

A LynxMetrics tem webhook?

Não. Um webhook exigiria um endereço público seu e, do nosso lado, assinatura de requisição e fila de reentrega. O /stream cobre o mesmo caso com menos peças e sem expor nada, então é o caminho recomendado para receber rodadas em tempo real.

Como reconectar ao stream sem perder rodadas?

Mande no cabeçalho last-event-id o id da última rodada recebida. O evento ready volta com missed, as rodadas que fecharam na sua ausência, da mais antiga para a mais nova, até 50. Acima disso vem resyncError too_many_missed e você pagina o /results?after= para ficar em dia.

O que é o evento phase e como recebê-lo?

É o aviso de que a mesa entrou na resolução de uma rodada, quando as apostas já fecharam e o resultado ainda não existe, e ele é opcional: só chega se você abrir a conexão com ?phases=1. Traz o roundId que a rodada vai ter, no Bac Bo cerca de 8 segundos antes do resultado. Para saber a que rodada um resultado pertence você não precisa dele: o id do round, a ordem garantida e o last-event-id bastam.

Para que servem os campos de timing?

Para medir o atraso em vez de estimar. O settledAt é o fim da rodada no relógio da mesa, o receivedAt é quando o resultado ficou pronto do nosso lado e o sentAt é quando o evento foi escrito na sua conexão. A diferença entre receivedAt e settledAt é o trecho que está nas nossas mãos, hoje em torno de 4 segundos.

Por que a conexão do stream é encerrada a cada 6 horas?

É de propósito: conexão que morre sem avisar existe, e esse prazo impede que ela ocupe uma vaga para sempre. Com o Last-Event-ID a reconexão não custa nenhuma rodada, então quem roda o dia inteiro reconecta cerca de quatro vezes por dia sem perder nada.

Leia também