# API do Bac Bo Live

No Bac Bo Live, Player e Banker jogam dois dados cada. Resultados, dados e multiplicadores de empate. Esta página mostra como a API do Bac Bo Live responde, com os campos explicados um a um.

Base URL: `https://api.lynxmetrics.com/v1/bacbo-live`

Source: https://lynxmetrics.com/docs/bacbo-live · Ver o Bac Bo Live ao vivo: https://lynxmetrics.com/apis/bacbo-live

## Autenticação

Envie no cabeçalho `x-api-key` uma chave criada no painel para o Bac Bo Live, já que a chave de outra API recebe `key_wrong_api`.

```bash
curl https://api.lynxmetrics.com/v1/bacbo-live/latest \
  -H "x-api-key: SUA_CHAVE"
```

Chaves, teste e assinaturas (você pode assinar a mesma API várias vezes, cada uma com as suas chaves) funcionam igual em todas as APIs e estão explicados na [documentação geral](https://lynxmetrics.com/docs#autenticacao). (https://lynxmetrics.com/docs.md)

## Exemplos de código

Exemplos prontos para copiar, em Python, Node.js e PHP. Troque `SUA_CHAVE` pela chave do painel e rode: cada um chama a função `on_round` (`onRound` no Node.js) a cada rodada nova do Bac Bo Live, e é nela que entra o seu código.

### Tempo real pelo stream (recomendado)

Uma conexão aberta que recebe cada rodada no instante em que ela fecha. Só a abertura da conexão gasta requisição, então você não esbarra no limite por minuto, e é o caminho que entrega mais rápido. O exemplo reconecta sozinho, manda o `last-event-id` para receber em `missed` o que fechou enquanto esteve fora, e para quando chega `closed`.

Python

```python
import json
import time
import requests

API = "https://api.lynxmetrics.com/v1/bacbo-live"
KEY = "SUA_CHAVE"


def on_round(r):
    print(r["id"], r["outcome"], r["data"])


def listen():
    last_id = None
    while True:
        headers = {"x-api-key": KEY, "accept": "text/event-stream"}
        if last_id:
            headers["last-event-id"] = last_id
        try:
            with requests.get(API + "/stream", headers=headers, stream=True, timeout=(10, 60)) as res:
                if res.status_code != 200:
                    print("HTTP", res.status_code, res.text)
                    time.sleep(int(res.headers.get("retry-after", 10)))
                    continue
                res.encoding = "utf-8"
                event, data = None, []
                for line in res.iter_lines(chunk_size=1, decode_unicode=True):
                    if line.startswith("event:"):
                        event = line[6:].strip()
                    elif line.startswith("data:"):
                        data.append(line[5:].strip())
                    elif line == "":
                        if event and data:
                            body = json.loads("\n".join(data))
                            if event == "ready":
                                for r in body.get("missed") or []:
                                    on_round(r)
                                if body.get("data"):
                                    last_id = body["data"]["id"]
                            elif event == "round":
                                on_round(body["data"])
                                last_id = body["data"]["id"]
                            elif event == "closed":
                                return
                        event, data = None, []
        except requests.RequestException as error:
            print("reconnecting:", error)
        time.sleep(3)


listen()
```

Node.js

```js
const API = "https://api.lynxmetrics.com/v1/bacbo-live";
const KEY = "SUA_CHAVE";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function onRound(r) {
  console.log(r.id, r.outcome, r.data);
}

async function listen() {
  let lastId = null;
  for (;;) {
    try {
      const headers = { "x-api-key": KEY, accept: "text/event-stream" };
      if (lastId) headers["last-event-id"] = lastId;
      const res = await fetch(API + "/stream", { headers });
      if (!res.ok) {
        console.error("HTTP", res.status, await res.text());
        await sleep(Number(res.headers.get("retry-after") ?? 10) * 1000);
        continue;
      }
      const decoder = new TextDecoder();
      let buffer = "";
      for await (const chunk of res.body) {
        buffer += decoder.decode(chunk, { stream: true });
        let end;
        while ((end = buffer.indexOf("\n\n")) >= 0) {
          const block = buffer.slice(0, end);
          buffer = buffer.slice(end + 2);
          const event = /^event: (.+)$/m.exec(block)?.[1];
          const data = block
            .split("\n")
            .filter((line) => line.startsWith("data:"))
            .map((line) => line.slice(5).trim())
            .join("\n");
          if (!event || !data) continue;
          const body = JSON.parse(data);
          if (event === "ready") {
            for (const r of body.missed ?? []) onRound(r);
            if (body.data) lastId = body.data.id;
          } else if (event === "round") {
            onRound(body.data);
            lastId = body.data.id;
          } else if (event === "closed") {
            return;
          }
        }
      }
    } catch (error) {
      console.error("reconnecting:", error.message);
    }
    await sleep(3000);
  }
}

listen();
```

PHP

```php
<?php
$api = "https://api.lynxmetrics.com/v1/bacbo-live";
$key = "SUA_CHAVE";

function on_round(array $r): void
{
    echo $r["id"], " ", $r["outcome"], " ", json_encode($r["data"]), PHP_EOL;
}

$lastId = null;
while (true) {
    $headers = ["x-api-key: $key", "accept: text/event-stream"];
    if ($lastId) $headers[] = "last-event-id: $lastId";
    $buffer = "";
    $closed = false;

    $ch = curl_init("$api/stream");
    curl_setopt_array($ch, [
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_WRITEFUNCTION => function ($ch, $chunk) use (&$buffer, &$lastId, &$closed) {
            $buffer .= $chunk;
            while (($end = strpos($buffer, "\n\n")) !== false) {
                $block = substr($buffer, 0, $end);
                $buffer = substr($buffer, $end + 2);
                if (!preg_match('/^event: (.+)$/m', $block, $event)) continue;
                preg_match_all('/^data: ?(.*)$/m', $block, $data);
                $body = json_decode(implode("\n", $data[1]), true);
                if (!is_array($body)) continue;
                if ($event[1] === "ready") {
                    foreach ($body["missed"] ?? [] as $r) on_round($r);
                    if (!empty($body["data"])) $lastId = $body["data"]["id"];
                } elseif ($event[1] === "round") {
                    on_round($body["data"]);
                    $lastId = $body["data"]["id"];
                } elseif ($event[1] === "closed") {
                    $closed = true;
                    return 0;
                }
            }
            return strlen($chunk);
        },
    ]);
    curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($closed) break;
    if ($status !== 200) fwrite(STDERR, "HTTP $status" . PHP_EOL);
    sleep($status === 200 ? 3 : 10);
}
```

### Latest com espera (sem conexão aberta)

Para quem prefere pedir em vez de manter uma conexão aberta. O `?wait=20` segura a resposta até a próxima rodada do Bac Bo Live fechar, por no máximo 20 segundos, então a rodada chega no instante em que fecha e o exemplo faz poucas requisições por minuto em vez de perguntar a toda hora. Ele manda o `ETag` da última resposta em `if-none-match`: enquanto nada muda, a espera termina em `304` sem corpo, e no `429` ele espera o tempo do cabeçalho `retry-after` em vez de insistir.

Python

```python
import time
import requests

API = "https://api.lynxmetrics.com/v1/bacbo-live"

session = requests.Session()
session.headers["x-api-key"] = "SUA_CHAVE"


def on_round(r):
    print(r["id"], r["outcome"], r["data"])


etag = None
last_id = None
while True:
    try:
        res = session.get(
            API + "/latest",
            params={"wait": 20},
            headers={"if-none-match": etag} if etag else {},
            timeout=30,
        )
    except requests.RequestException as error:
        print("retrying:", error)
        time.sleep(5)
        continue

    if res.status_code == 200:
        etag = res.headers.get("etag")
        r = res.json()["data"]
        if r and r["id"] != last_id:
            if last_id:
                on_round(r)
            last_id = r["id"]
    elif res.status_code == 429:
        time.sleep(int(res.headers.get("retry-after", 5)))
        continue
    elif res.status_code != 304:
        print("HTTP", res.status_code, res.text)
        time.sleep(10)
        continue
    time.sleep(2)
```

Node.js

```js
const API = "https://api.lynxmetrics.com/v1/bacbo-live";
const KEY = "SUA_CHAVE";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function onRound(r) {
  console.log(r.id, r.outcome, r.data);
}

async function poll() {
  let etag = null;
  let lastId = null;
  for (;;) {
    let res;
    try {
      const headers = { "x-api-key": KEY };
      if (etag) headers["if-none-match"] = etag;
      res = await fetch(API + "/latest?wait=20", { headers, signal: AbortSignal.timeout(30_000) });
    } catch (error) {
      console.error("retrying:", error.message);
      await sleep(5000);
      continue;
    }

    if (res.status === 200) {
      etag = res.headers.get("etag");
      const { data } = await res.json();
      if (data && data.id !== lastId) {
        if (lastId) onRound(data);
        lastId = data.id;
      }
    } else if (res.status === 429) {
      await sleep(Number(res.headers.get("retry-after") ?? 5) * 1000);
      continue;
    } else if (res.status !== 304) {
      console.error("HTTP", res.status, await res.text());
      await sleep(10_000);
      continue;
    }
    await sleep(2000);
  }
}

poll();
```

PHP

```php
<?php
$api = "https://api.lynxmetrics.com/v1/bacbo-live";
$key = "SUA_CHAVE";

function on_round(array $r): void
{
    echo $r["id"], " ", $r["outcome"], " ", json_encode($r["data"]), PHP_EOL;
}

$etag = null;
$lastId = null;
while (true) {
    $headers = ["x-api-key: $key"];
    if ($etag) $headers[] = "if-none-match: $etag";
    $received = [];

    $ch = curl_init("$api/latest?wait=20");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$received) {
            $parts = explode(":", $line, 2);
            if (count($parts) === 2) $received[strtolower(trim($parts[0]))] = trim($parts[1]);
            return strlen($line);
        },
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status === 200) {
        $etag = $received["etag"] ?? null;
        $round = json_decode($body, true)["data"] ?? null;
        if ($round && $round["id"] !== $lastId) {
            if ($lastId) on_round($round);
            $lastId = $round["id"];
        }
    } elseif ($status === 429) {
        sleep((int) ($received["retry-after"] ?? 5));
        continue;
    } elseif ($status !== 304) {
        fwrite(STDERR, "HTTP $status $body" . PHP_EOL);
        sleep(10);
        continue;
    }
    sleep(2);
}
```

### Mandar cada rodada para o Telegram

Troque a função `on_round` de qualquer um dos exemplos acima por esta, com o token do seu bot (o que o @BotFather entrega) e o id do chat ou do canal. O `outcome` e tudo o que vem em `data` estão explicados mais abaixo, em Campos de cada rodada.

Python

```python
BOT_TOKEN = "123456:ABC..."
CHAT_ID = "-1001234567890"


def on_round(r):
    text = f"{r['outcome'].upper()} · {r['id']}"
    requests.post(
        f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage",
        json={"chat_id": CHAT_ID, "text": text},
        timeout=10,
    )
```

Node.js

```js
const BOT_TOKEN = "123456:ABC...";
const CHAT_ID = "-1001234567890";

function onRound(r) {
  fetch(`https://api.telegram.org/bot${BOT_TOKEN}/sendMessage`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ chat_id: CHAT_ID, text: `${r.outcome.toUpperCase()} · ${r.id}` }),
    signal: AbortSignal.timeout(10_000),
  }).catch((error) => console.error("telegram:", error.message));
}
```

PHP

```php
$botToken = "123456:ABC...";
$chatId = "-1001234567890";

function on_round(array $r): void
{
    global $botToken, $chatId;
    $ch = curl_init("https://api.telegram.org/bot$botToken/sendMessage");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_POSTFIELDS => ["chat_id" => $chatId, "text" => strtoupper($r["outcome"]) . " · " . $r["id"]],
    ]);
    curl_exec($ch);
    curl_close($ch);
}
```

### O que mais dá problema em bot

- Não consulte mais rápido do que a mesa joga. Com menos de 1 segundo entre as consultas você só gasta o limite e recebe `429`: a rodada nova não chega antes por isso. Se precisa do resultado no mesmo segundo, use o `/stream`.
- No `429`, leia o cabeçalho `retry-after` e espere esse tempo, porque repetir na hora não adianta. Toda resposta traz `x-ratelimit-remaining` e `x-ratelimit-reset`, que dizem quanto ainda cabe no minuto.
- `401` em toda chamada quer dizer chave errada, revogada ou trocada no painel: copie a chave de novo. Muitas tentativas seguidas com chave inválida fazem o seu IP receber `429` por um tempo, mesmo depois de corrigir.
- `trial_expired` quer dizer que as horas do teste acabaram. Assinando um plano no painel, a mesma chave volta a funcionar, sem mexer no código.
- Se o seu bot ficou parado, não tente adivinhar o que perdeu: peça `/results?after=` com o `id` da última rodada que você tem e receba, em ordem, todas as que fecharam depois.
- Cada chave tem um número de conexões de stream, na tabela de limites. Passou disso, a conexão mais antiga é encerrada com `closed`. Para rodar vários bots, crie uma chave para cada um no painel.

## GET /v1/bacbo-live/latest

A rodada mais recente do Bac Bo Live, ou null se ainda não houver nenhuma.

| Field | Type |  |
| --- | --- | --- |
| `wait` | `number` | Segundos que a resposta pode esperar pela próxima rodada, até 20. Só espera quem já tem a última: mande o `ETag` dela em `if-none-match` ou o `id` dela em `after`. Quando uma rodada fecha, a resposta sai na hora com ela; se o tempo acabar antes, vem `304` (com ETag) ou a mesma rodada (com `after`). Conta como uma requisição só, e o tempo limite do seu cliente tem de ser maior que o `wait`. |
| `after` | `id` | O `id` da última rodada que você tem. Só serve junto com `wait`, para quem não guarda o `ETag`. |

```json
{
  "data": {
    "id": "v1794669483249",
    "game": "bacbo-live",
    "tableId": "BacBo00000000001",
    "startedAt": "2026-11-14T15:17:48.079Z",
    "settledAt": "2026-11-14T15:18:12.409Z",
    "outcome": "tie",
    "data": {
      "player": { "dice": [4, 1], "score": 5 },
      "banker": { "dice": [1, 4], "score": 5 },
      "multiplier": 6
    }
  }
}
```

## GET /v1/bacbo-live/results

Rodadas do Bac Bo Live da mais nova para a mais antiga. Para buscar a página seguinte, passe o `nextCursor` da resposta em `before`, e quando ele vier `null` não há mais resultados.

| Field | Type |  |
| --- | --- | --- |
| `limit` | `number` | Quantas rodadas trazer, com padrão 50 e máximo 250 a 1000. |
| `before` | `ISO 8601` | Traz só rodadas encerradas antes desta data, como o `nextCursor` da página anterior, e até onde dá para voltar depende do plano. |
| `after` | `ISO 8601 \| id` | Para sincronizar sem repetir nem pular rodadas: passe o `settledAt` ou o `id` da última rodada que você já tem, e a resposta traz só as encerradas depois dela, da mais antiga para a mais nova, até o `limit`. Se a página vier cheia, o `nextCursor` vai no próximo `after`, e quando ele vier `null` você está em dia. Também respeita o histórico do plano e pode ser usado junto com `before`. |

```json
GET /v1/bacbo-live/results?limit=1

{
  "data": [
    {
      "id": "v1794669483249",
      "game": "bacbo-live",
      "tableId": "BacBo00000000001",
      "startedAt": "2026-11-14T15:17:48.079Z",
      "settledAt": "2026-11-14T15:18:12.409Z",
      "outcome": "tie",
      "data": {
        "player": { "dice": [4, 1], "score": 5 },
        "banker": { "dice": [1, 4], "score": 5 },
        "multiplier": 6
      }
    }
  ],
  "nextCursor": "2026-11-14T15:18:12.409Z"
}
```

## GET /v1/bacbo-live/stream

Rodadas do Bac Bo Live ao vivo, numa conexão que fica aberta (SSE, Server-Sent Events): cada rodada chega no instante em que é salva, sem você ficar perguntando. É o caminho mais rápido, porque tira o intervalo entre as suas consultas. É HTTP comum, então atravessa proxy e CDN e funciona com qualquer cliente que aceite cabeçalho e leitura contínua.

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

```text
event: round
data: {
data:   "data": {
data:     "id": "v1794669483249",
data:     "game": "bacbo-live",
data:     "tableId": "BacBo00000000001",
data:     "startedAt": "2026-11-14T15:17:48.079Z",
data:     "settledAt": "2026-11-14T15:18:12.409Z",
data:     "outcome": "tie",
data:     "data": {
data:       "player": { "dice": [4, 1], "score": 5 },
data:       "banker": { "dice": [1, 4], "score": 5 },
data:       "multiplier": 6
data:     }
data:   },
data:   "timing": {
data:     "receivedAt": "2026-11-14T15:18:16.309Z",
data:     "sentAt": "2026-11-14T15:18:16.359Z"
data:   }
data: }

```

### O que chega na conexão

| Field | Type |  |
| --- | --- | --- |
| `ready` | `event` | Vem uma só vez, assim que a conexão abre, com a última rodada já encerrada, para você começar em dia. Não é rodada nova: compare o `id` com o da última que você tem e não conte duas vezes. O `data` vem `null` enquanto não houver nenhuma rodada. Numa reconexão ele traz também, em `missed`, as rodadas que fecharam enquanto você estava fora. |
| `phase` | `opcional` | Opcional: só chega se você pedir com `?phases=1`. São dois avisos por rodada, ambos com `ref`, `game`, `phase`, `at` e `sentAt`: `betting`, quando a mesa volta ao plano aberto e as apostas da próxima rodada abrem, e `resolving`, quando ela entra na resolução e as apostas já fecharam — este leva também o `roundId`, o id que a rodada vai ter no `round`, vários segundos antes do resultado. Para saber a que rodada um resultado pertence você NÃO precisa disto: bastam o `id` do `round`, a ordem garantida e o `last-event-id`. A fase serve para amarrar mais cedo, e 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, e aí nenhum `round` vem com aquele `ref`. |
| `round` | `event` | Uma por rodada nova, com o mesmo objeto que o `/latest` devolve em `data`, os horários da entrega em `timing` e, quando a rodada teve fase, o `ref` dela. O `id` do evento é o id da rodada, e só o `round` tem `id`, porque é ele que serve de ponto de retomada na reconexão. |
| `correction` | `opcional` | Opcional: só chega se você pedir com `?corrections=1`. Avisa que uma rodada que já tinha saído no `round` mudou: no Bac Bo, cerca de uma vez a cada 2.000 rodadas a mesa repete a jogada de um copinho depois de os dados terem parado, e o dado que saiu deixa de valer. Vem com `data`, a rodada como ela fica (o mesmo `id` e os mesmos horários), `previous`, com o `outcome` e o `data` que tinham sido entregues, e `sentAt`. Não leva `id` de evento, então o `last-event-id` não muda. Chega quando aquela rodada termina na mesa, de 30 segundos a 3 minutos depois do `round`. Mesmo sem pedir, o `/latest`, o `/results` e o `/stats` passam a devolver a rodada corrigida. |
| `gap` | `event` | A fila desta conexão estourou e rodadas foram descartadas: o seu cliente não estava dando conta do ritmo. Vem com `resyncError: too_many_missed`, o mesmo código da reconexão que ficou longa. A conexão continua aberta, e é este o único caso em que falta rodada no meio de um stream — sempre anunciado, porque os ids não são sequenciais e você não teria como notar. Para fechar o buraco, peça `/results?after=` com o id da última rodada que você recebeu. |
| `closed` | `event` | A sua conexão foi encerrada porque outra mais nova foi aberta com a mesma chave. Vem com `reason: "replaced"`. Não é queda de rede, então não reconecte automaticamente: reconectar aqui só derrubaria a conexão nova, que então reconectaria e derrubaria a sua, sem fim. |
| `: ping` | `comentário` | A cada 20 segundos sem rodada vai uma linha começando com dois-pontos. Não é evento e pode ser ignorada; ela só impede que algum proxy no meio feche a conexão parada. |

### Amarrar um palpite antes do fecho

O id de uma rodada é o próprio instante em que as apostas fecharam, ao milissegundo: ele não existe enquanto elas estão abertas, e não há como adivinhá-lo. Para quem publica um palpite antes do fecho existe o `ref`, uma referência nossa, criada na abertura das apostas e repetida na resolução e no resultado. Carimbe o palpite com o `ref` do `betting` e case com o `round` que trouxer o mesmo `ref`, sem depender da ordem de chegada e sem esperar o id. Peça as fases com `?phases=1`; quem conecta no meio já recebe a fase em que a mesa está.

```text
event: phase
data: {
data:   "ref": "r1761939000000-7",
data:   "game": "bacbo-live",
data:   "phase": "betting",
data:   "at": "2026-11-14T15:17:46.409Z",
data:   "sentAt": "2026-11-14T15:17:46.509Z"
data: }

event: phase
data: {
data:   "ref": "r1761939000000-7",
data:   "roundId": "v1794669483249",
data:   "game": "bacbo-live",
data:   "phase": "resolving",
data:   "at": "2026-11-14T15:18:03.249Z",
data:   "sentAt": "2026-11-14T15:18:05.409Z"
data: }

event: round
data: {
data:   "data": {
data:     "id": "v1794669483249",
data:     "game": "bacbo-live",
data:     "tableId": "BacBo00000000001",
data:     "startedAt": "2026-11-14T15:17:48.079Z",
data:     "settledAt": "2026-11-14T15:18:12.409Z",
data:     "outcome": "tie",
data:     "data": {
data:       "player": { "dice": [4, 1], "score": 5 },
data:       "banker": { "dice": [1, 4], "score": 5 },
data:       "multiplier": 6
data:     }
data:   },
data:   "ref": "r1761939000000-7",
data:   "timing": {
data:     "receivedAt": "2026-11-14T15:18:16.309Z",
data:     "sentAt": "2026-11-14T15:18:16.359Z"
data:   }
data: }

```

| Field | Type |  |
| --- | --- | --- |
| `ref` | `string` | A referência da rodada, igual nos três eventos. É uma cadeia opaca: não tente interpretá-la nem derivar dela a próxima. Um `ref` pode ficar sem resultado — se a rodada for descartada, nenhum `round` chega com ele, e o `betting` seguinte abre outra. |
| `roundId` | `string` | O id definitivo da rodada. Só aparece a partir do `resolving`, porque é ancorado no instante do fecho das apostas. É ele que vem no `id` do evento `round` e serve de `last-event-id` na reconexão. |
| `phase` | `betting \| resolving` | `betting`: as apostas da próxima rodada abriram. `resolving`: a mesa entrou na resolução e as apostas fecharam. Teste sempre este campo em vez de supor, porque fases novas podem ser acrescentadas. |
| `at` | `ISO 8601` | Instante da fase no relógio da mesa, o mesmo de `startedAt` e `settledAt`. O `sentAt`, ao lado, é quando o aviso saiu na sua conexão. |

### Horários e atraso

Os eventos carregam os horários de cada pedaço do caminho, para você medir o atraso real em vez de estimar. Os horários da rodada estão no relógio da mesa; os da entrega, no relógio da nossa API. O atraso do Bac Bo Live é medido contra a mesa e aparece nos próprios carimbos de cada evento, rodada por rodada.

| Field | Type |  |
| --- | --- | --- |
| `data.startedAt` | `ISO 8601` | Início da rodada no relógio da mesa, que é quando as apostas abriram. |
| `data.settledAt` | `ISO 8601` | Fim da rodada no relógio da mesa: o instante em que o resultado ficou definido na origem. É também a data usada na ordenação, no `before` e no `after`. |
| `timing.receivedAt` | `ISO 8601` | Quando o resultado ficou pronto aqui, do nosso lado. A diferença entre ele e o `settledAt` é o atraso da origem até nós, que é a parte que está nas nossas mãos. |
| `timing.sentAt` | `ISO 8601` | Quando este evento foi escrito na sua conexão. A diferença entre ele e o `receivedAt` é o tempo que a rodada esperou na fila desta conexão, normalmente alguns milissegundos; o resto do atraso até o seu código é rede. |

### Reconectar sem perder rodada

Ao reconectar, mande no cabeçalho `last-event-id` o id da última rodada que você recebeu — um cliente de SSE que reconecta sozinho já manda esse cabeçalho, e quem controla a reconexão manda o cabeçalho ou `?last_event_id=`, tanto faz. O `ready` volta com `missed`: as rodadas que fecharam enquanto você estava fora, da mais antiga para a mais nova. O stream resolve ausências de até 50 rodadas; se mais que isso fecharam, ele não devolve as mais recentes e nem tenta — `missed` vem `null` com `too_many_missed`, e você fecha o buraco pelo `/results?after=`. O `data` continua sendo a última rodada encerrada, que normalmente é o último item de `missed`. Quando não dá para recuperar, `missed` vem `null` e `resyncError` diz por quê; a conexão abre de qualquer forma, porque uma reconexão não pode falhar por causa de um cursor velho.

```bash
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: v1794669483249"
```

| Field | Type |  |
| --- | --- | --- |
| `bad_cursor` | `resyncError` | O valor enviado não é um id de rodada nem uma data ISO 8601. |
| `unknown_round` | `resyncError` | Esse id não é de nenhuma rodada nossa nesta API. Pode ser de outra API, ou de uma rodada que acabou descartada: um `phase` não garante que a rodada vai existir. |
| `plan_limit` | `resyncError` | A rodada é mais antiga que o histórico do seu plano. |
| `too_many_missed` | `resyncError` | Mais de 50 rodadas fecharam na sua ausência, ou seja, você ficou fora tempo demais para o stream resolver sozinho. Peça `/results?after=` com o id que você tem e pagine até ficar em dia. |

### Como manter a conexão

- Dentro de uma conexão os eventos saem um por vez e em ordem cronológica: as fases de uma rodada sempre antes do resultado dela — `betting`, `resolving` e `round`, com o mesmo `ref` —, e cada `round` com `settledAt` maior que o do anterior. O `betting` de uma rodada pode chegar pouco antes do `round` da anterior, porque um vem da mesa e o outro do banco; o que vale é a ordem dentro de cada rodada. Nenhuma rodada chega duas vezes na mesma conexão. Se a sua conexão ficar lenta e a fila dela estourar, as rodadas mais antigas são descartadas e vai um `event: gap` avisando.
- Cada plano tem um número de conexões simultâneas por chave, na tabela de limites abaixo. Passar desse número não dá erro: a conexão mais antiga daquela chave é encerrada com um `event: closed` e a nova entra no lugar. Assim um processo que caiu sem o sistema avisar nunca tranca você para fora da sua própria vaga.
- Toda conexão é encerrada depois de 6 horas, mesmo saudável, e cabe ao cliente reconectar. Esse fim não manda evento nenhum: a conexão simplesmente fecha, e o `closed` é só da substituição, então uma leitura que termina sem motivo depois de horas abertas é este prazo. É de propósito: conexão que morre sem avisar existe, e esse prazo é o que impede que ela ocupe lugar para sempre. Quem roda o dia inteiro reconecta cerca de quatro vezes por dia.
- Se o seu cliente tem tempo limite de leitura, deixe-o acima de 20 segundos, senão ele corta a conexão no silêncio entre uma rodada e outra.
- Abrir a conexão gasta uma requisição do seu limite por minuto. As rodadas que chegam depois não gastam nada, então acompanhar pelo stream pesa menos no limite do que ficar consultando o `/latest`.
- A chave só é aceita no cabeçalho `x-api-key`, nunca na URL, que ficaria em log de proxy e em histórico. Por isso o `EventSource` do navegador não serve: ele não envia cabeçalhos. No navegador, o caminho é um `fetch` lendo o corpo aos poucos; melhor ainda é o seu servidor ouvir o stream e repassar, porque uma chave no navegador ficaria à vista de qualquer visitante.

## GET /v1/bacbo-live/stats

Estatísticas do Bac Bo Live calculadas na hora sobre as últimas rodadas.

| Field | Type |  |
| --- | --- | --- |
| `sample` | `number` | Sobre quantas rodadas recentes calcular, com padrão 100 e máximo 250 a 1000. |

```json
GET /v1/bacbo-live/stats

{
  "data": {
    "total": 100,
    "counts": { "player": 46, "banker": 45, "tie": 9 },
    "percentages": { "player": 46, "banker": 45, "tie": 9 },
    "currentStreak": { "outcome": "banker", "length": 3 },
    "outcomes": {
      "player": {
        "count": 46,
        "percent": 46,
        "longestStreak": 5,
        "sinceLast": 3
      },
      "banker": {
        "count": 45,
        "percent": 45,
        "longestStreak": 6,
        "sinceLast": 0
      },
      "tie": {
        "count": 9,
        "percent": 9,
        "longestStreak": 1,
        "sinceLast": 11
      }
    },
    "sample": {
      "from": "2026-11-14T14:27:05.112Z",
      "to": "2026-11-14T15:18:12.409Z"
    },
    "tieMultipliers": { "4": 5, "6": 3, "88": 1 }
  }
}
```

## Campos de cada rodada

Formato de cada rodada do Bac Bo Live em latest e results.

| Field | Type |  |
| --- | --- | --- |
| `id` | `string` | Id da rodada, único e estável. É gerado por nós, não pelo provedor, então use-o só para comparar e como cursor (em after e last-event-id), sem interpretar o conteúdo. |
| `game` | `string` | Slug da API, que aqui é sempre "bacbo-live". |
| `tableId` | `string \| null` | Id da mesa no provedor, ou null quando a fonte não informa. |
| `startedAt` | `string \| null` | Início da rodada em UTC, ou null quando a fonte não informa. |
| `settledAt` | `string` | Fim da rodada em UTC, que é a data usada na ordenação e em before. |
| `outcome` | `"player" \| "banker" \| "tie"` | Quem ganhou a rodada: player, banker ou tie, que é o empate. |
| `data.player.dice` | `[number, number]` | Os dois dados do Player, de 1 a 6. |
| `data.player.score` | `number` | Soma dos dados do Player, de 2 a 12. |
| `data.banker.dice` | `[number, number]` | Os dois dados do Banker, de 1 a 6. |
| `data.banker.score` | `number` | Soma dos dados do Banker, de 2 a 12. |
| `data.multiplier` | `number \| null` | Multiplicador pago no empate, como 4, 6 ou 88, e null quando a rodada não termina empatada. |

## Campos das estatísticas

| Field | Type |  |
| --- | --- | --- |
| `total` | `number` | Quantas rodadas entraram na conta, igual ao sample ou menos se ainda houver poucas. |
| `counts` | `{ player, banker, tie }` | Vitórias de Player, de Banker e empates na amostra. |
| `percentages` | `{ player, banker, tie }` | As mesmas contagens em porcentagem, com uma casa decimal. |
| `currentStreak` | `{ outcome, length } \| null` | Resultado que está se repetindo agora e há quantas rodadas, ou null sem rodadas. |
| `outcomes` | `{ player, banker, tie }` | Um bloco por resultado: count (quantas vezes saiu), percent, longestStreak (a maior sequência seguida na amostra) e sinceLast (rodadas desde a última vez, com 0 para a rodada mais recente e null se não saiu na amostra). Tem a mesma forma em todas as APIs. |
| `sample` | `{ from, to } \| null` | Período da amostra: o settledAt da rodada mais antiga (from) e da mais nova (to), ou null sem rodadas. |
| `tieMultipliers` | `{ [multiplier]: number }` | Quantos empates da amostra pagaram cada multiplicador, com o multiplicador como chave. |

## Planos e limites

Limites da API do Bac Bo Live em cada plano. Um parâmetro acima do máximo é reduzido ao máximo, e um before mais antigo que o histórico do plano responde plan_limit. A coluna por minuto é o limite de requisições por minuto de cada assinatura, somando todas as chaves dela, e a coluna de conexões é quantas conexões do /stream a mesma chave pode ter abertas ao mesmo tempo.

| Plano | Preço | Por minuto | Conexões | limit | sample | before |
| --- | --- | --- | --- | --- | --- | --- |
| Teste | 2 horas, sem cartão | 60 | 1 | 250 | 250 | 7 dias |
| Pro | R$ 21,90/mês | 60 | 1 | 250 | 250 | 7 dias |
| Business | R$ 49,90/mês | 400 | 5 | 1000 | 1000 | completo |

Os erros têm o mesmo formato em todas as APIs e estão listados na [documentação geral](https://lynxmetrics.com/docs#erros).
