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
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 /latest | Webhook | WebSocket | |
|---|---|---|---|---|
| Atraso além do da API | nenhum | metade do seu intervalo, em média | nenhum | nenhum |
| Gasto do limite por minuto | 1 na abertura | 1 por consulta | — | — |
| Precisa de endereço público | não | não | sim | não |
| Atravessa proxy e CDN | sim, é HTTP comum | sim | sim | às vezes não |
| Existe na LynxMetrics | sim | sim | não | nã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"}}| Evento | Quando chega | O que fazer com ele |
|---|---|---|
ready | Uma vez, ao abrir | Traz 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 |
phase | Opcional (?phases=1), quando a mesa entra na resolução da rodada | Traz o roundId que a rodada vai ter, segundos antes do resultado |
round | Uma por rodada nova | A rodada em data e os horários da entrega em timing. É o único evento com id: |
closed | Outra conexão abriu com a mesma chave | Fim 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:
| Campo | Relógio | O que ele marca |
|---|---|---|
data.startedAt | mesa | Início da rodada, quando as apostas abriram |
data.settledAt | mesa | Fim da rodada: o resultado ficou definido na origem |
timing.receivedAt | nossa API | O resultado ficou pronto do nosso lado |
timing.sentAt | nossa API | Este 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", "...": "..." }
]
}missedtraz as rodadas que fecharam enquanto você estava fora, da mais antiga para a mais nova, até 50.datacontinua sendo a última rodada encerrada, que normalmente é o último item demissed— então trate peloidpara não contar duas vezes.- Como o
id:só vai no eventoround, o cursor que você guarda é sempre uma rodada que existe de verdade. É por isso que ophasenão temid:: 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):
resyncError | O que aconteceu | O que fazer |
|---|---|---|
bad_cursor | O valor não é um id de rodada nem uma data ISO 8601 | Corrigir o que você está guardando |
unknown_round | O id não é de nenhuma rodada desta API | Pode ser id de outra API, ou de uma rodada descartada depois de um phase |
plan_limit | A rodada é mais antiga que o histórico do seu plano | Seguir do que o plano cobre |
too_many_missed | Mais de 50 rodadas fecharam na sua ausência | Paginar 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:
- O cursor sai do
idda rodada, não de um contador seu. Ele é fixo e nunca muda. - O
trataré idempotente. Oreadyrepete 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. - O
closedpara o laço. Reconectar depois de umclosedderruba 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
closede 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-IDisso é 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
/latesta 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
- O que é uma API e como se conectar a uma pela primeira vez
API explicada sem complicação: o que é, como funcionam REST, JSON e chaves, e como fazer a primeira chamada no navegador, no terminal, em Python e em JavaScript.
- Onde hospedar um bot 24 horas: hospedagem, VPS ou serverless
O que um bot que roda sem parar realmente precisa, quanto custa cada opção de hospedagem, e por que serverless não combina com conexão aberta.
- Erros e limites de API: 429, backoff e o que fazer
Guia prático dos erros de uma API de dados: o que significa cada status HTTP, como tratar o 429 com Retry-After e backoff, e o código que resolve isso.