Odds ao vivo e liquidação de bilhetes. Uma única API.

Do zero às odds em tempo real

API REST

https://api.bestoddsapi.com/api/v1

Token OAuth2

https://api.bestoddsapi.com/oauth/token

WebSocket

wss://ws.bestoddsapi.com (endereço exato vem no ticket)

Portal

https://api.bestoddsapi.com/portal

1Credenciais

OAuth2 Client Credentials (máquina a máquina): client_id público e client_secret sigiloso, exibido só na criação ou rotação. Emitidas no portal do cliente após a contratação.

2Access token

curl -s -X POST "https://api.bestoddsapi.com/oauth/token" \
  -d grant_type=client_credentials \
  -d client_id="$BESTSODDSAPI_CLIENT_ID" \
  -d client_secret="$BESTSODDSAPI_CLIENT_SECRET" \
  -d scope="events:read odds:read results:read usage:read ws:connect"

# { "token_type": "Bearer", "expires_in": 3600, "access_token": "eyJ..." }

Envie Authorization: Bearer <access_token> em todas as chamadas e reutilize o token até perto de expires_in.

3Eventos ao vivo

curl -s "https://api.bestoddsapi.com/api/v1/events/live?sport=soccer&per_page=20" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

Use sempre o id interno (UUID). IDs do fornecedor de origem não são expostos.

4Odds de um evento

curl -s "https://api.bestoddsapi.com/api/v1/events/$EVENT_ID/odds?market=match_winner,over_under&bookmaker=bet365" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

price e line são strings decimais: use tipo decimal (bcmath, decimal.js, BigDecimal), nunca float. meta.sequence serve para reconciliar com o WebSocket.

5Streaming

Peça um ticket em POST /ws/authorize e conecte (protocolo Pusher 7). Detalhes na aba WebSocket. Exemplos executáveis em cURL, PHP e Node.js na documentação oficial.

Endpoints (/api/v1)

Além do scope, o plano precisa habilitar a funcionalidade (events, odds, results, websocket) e, quando configurado, o esporte.

Filtros

Paginação

Cursor opaco: per_page (1–100, padrão 50) e cursor. Continue enquanto meta.pagination.next_cursor não for null.

WebSocket: uma conexão por esporte

Protocolo Pusher 7 atrás de um gateway de admissão. A conexão só é aceita com um ticket de uso único (TTL ~45 s) emitido pela API.

curl -s -X POST "https://api.bestoddsapi.com/api/v1/ws/authorize" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sport":"soccer"}'

# data.connection:
#   url: wss://ws.bestoddsapi.com/app/APP_KEY?protocol=7&…&ticket=wst_…
#   channel_template:      private-customer.{id}.event.{eventId}.odds
#   live_channel_template: private-customer.{id}.live.{sport}
#   max_subscriptions: 100

Mensagens

• odds.snapshot: estado atual do evento logo após assinar o canal.
• odds.updated: delta com o estado completo do mercado e sequence crescente. Aplique só os de sequence maior que o snapshot.
• live.snapshot / live.updated: lista ao vivo do esporte, só com eventos cujo status, placar ou tempo mudou, e removed[].
• result.updated: resultado final com markets liquidados, no canal do evento e no canal ao vivo do esporte.

Limites e reconexão

max_ws_connections vale por esporte; cada conexão aceita até max_subscriptions canais (padrão 100). Entrega best effort: se a sequence pular, refaça o snapshot. Reconecte com backoff exponencial e jitter, sempre com ticket novo.

delay = min(30s, 1s * 2^tentativa); sleep(random(0, delay))

Erros

{ "error": { "code": "rate_limited", "message": "Too many requests.", "details": {} },
  "request_id": "01J9..." }

Limites e cabeçalhos

Cotas por minuto, hora, dia e mês (janelas fixas UTC), por cliente, somando todas as credenciais. Requisições rejeitadas (429) não consomem cota.

X-RateLimit-Limit

Limite da janela mais restritiva

X-RateLimit-Remaining

Requisições restantes na janela

X-RateLimit-Reset

Unix epoch (s) em que a janela reinicia

Retry-After

Segundos a aguardar (429 e 503)

X-Request-Id

ID de correlação (você pode enviar o seu)

Versão

Versão maior no caminho (/api/v1). Dentro da v1 só entram mudanças compatíveis: novos campos, endpoints e valores de enum. Ignore campos que não conhece.