API de Esportes (v1)

Introdução

Ligas, campeonatos, jogos ao vivo, placares e odds em tempo real. Os dados são atualizados em segundos durante os jogos, e as odds mostram oddsSuspended: true quando estão bloqueadas para atualização. Todas as respostas são JSON no formato { ok, data } ou { ok: false, error }.

Autenticação

Envie sua chave no cabeçalho x-api-key. Pegue a chave no seu painel, em API Keys. Nunca exponha a chave em código público.

Proteção por domínio: se você cadastrar domínios no painel, só as requisições vindas desses domínios (cabeçalho Origin/Referer) serão aceitas. Chamadas de servidor sem Origin funcionam normalmente enquanto nenhum domínio estiver cadastrado.

Endpoints

• GET/accountDados da sua conta e consumo do dia
• GET/leaguesLigas e campeonatos liberados no seu plano
• GET/upcomingPróximos jogos das ligas do seu plano, ordenados do mais próximo ao mais distante dentro das próximas 24 horas
• GET/eventsJogos da liga com odds (pré-jogo e ao vivo)
• GET/events/{eventId}Um jogo específico com todos os mercados
• GET/marketsCatálogo de mercados disponíveis por esporte
• GET/liveTodos os jogos ao vivo agora (só das suas ligas). A categoria "live" também aparece em /leagues e funciona em /events?league=live
• GET/scoresPlacares: ao vivo, encerrados e próximos
• GET/standingsTabela de classificação da liga (pontos, jogos, vitórias, gols). Escudos servidos pelo seu domínio. Ligas com grupos devolvem uma tabela por grupo
• POST/betsRegistrar uma aposta para liquidação automática
• GET/early-payoutVer sua configuração de pagamento antecipado (modo, jogos principais da API e jogos escolhidos manualmente)
• POST/early-payoutEscolher como sua conta usa o pagamento antecipado
• GET/webhooksWebhook enviado para o seu webhook_url quando uma aposta termina
• GET/betsHistórico de apostas (win / loss / void / open)
• GET/odds-rulesBasquete e tênis: lista as suas regras de odds
• POST/odds-rulesBasquete e tênis: cria uma regra de odds (PUT /odds-rules/{id} edita, DELETE remove)
• GET/odds-history/{eventId}Basquete e tênis: histórico de odds médias gravadas do jogo
• GET/courts-streamBasquete e tênis: stream SSE com placar, odds e liquidação em tempo real
• GET/field/footballCampo gráfico ao vivo: lista os jogos de futebol, basquete (/field/basketball) ou tênis (/field/tennis) e avisa quais têm campo disponível agora. O campo é gerado automaticamente a partir do SportScore, você não precisa montar nada. Só planos com campo gráfico liberado no painel
• GET/field/football/{matchId}Campo gráfico de um jogo (futebol, basquete ou tênis): devolve o embedUrl para exibir o campo ao vivo no seu site, mais o estado do jogo em JSON (placar, lance atual, estatísticas, lances). Cada consulta conta 1 requisição; o embed em si não gasta o limite

Parâmetros — GET /events

Acréscimos (addedTime)

Em /events e /live, o campo addedTime vem null enquanto o acréscimo não foi anunciado. Quando o 4º árbitro mostra a placa, o campo passa a trazer os minutos exatos de cada tempo. Basta checar addedTime.announced a cada atualização. Se o acréscimo não for publicado, o campo continua null e o jogo segue normalmente pelo clock (ex.: 90'+3').

"clock": "90'+2'",
"addedTime": {
  "firstHalf": 2,     // minutos de acréscimo do 1º tempo (null se não anunciado)
  "secondHalf": 5,    // minutos de acréscimo do 2º tempo (null se não anunciado)
  "announced": true
}

Apostas e liquidação automática

Registre a aposta do seu usuário com POST /bets. Nós acompanhamos o placar e marcamos win assim que a condição for cumprida (mesmo com o jogo em andamento) ou loss quando ela não puder mais acontecer ou o jogo terminar. Linhas exatas (ex.: 2.0 com 2 gols) ficam void. Consulte o resultado em GET /bets.

• Pênaltis (penalty_awarded, penalty_awarded_h1, penalty_awarded_h2, first_penalty_goal): contam pênaltis marcados (convertidos ou perdidos). Se a fonte do jogo não informar pênaltis, a aposta é anulada (void).
• Primeiro a N escanteios no 1º tempo (corners_race_h1): aberto antes do jogo e até os 20 minutos do 1º tempo. Cartões no 1º tempo: cards_totals_h1 (amarelo = 1, vermelho = 2).
• Jogo suspenso: suspended: true e oddsSuspended: true; o status continua live até o jogo voltar ou ser encerrado.
• Ligas pelo LiveScore: Copa do Brasil, Copa do Brasil Feminina, LigaPro (Equador) e Liga FUTVE (Venezuela), com odds próprias (CloudFut). Placar, tempo, lances e estatísticas também usam o LiveScore quando a ESPN não reconhece o jogo.

Mercados disponíveis

A lista de jogos (/events, /live) traz os mercados principais que estiverem disponíveis. Os mercados adicionais — escanteios, cartões, períodos e jogadores — vêm em /events/{eventId}, no campo markets, já agrupados por category e com a melhor odd de cada opção. Cada casa oferece mercados diferentes; mostre apenas os que vierem na resposta. Nos mercados por time, a API substitui `home` e `away` pelo nome real do jogo: por exemplo, `Flamengo|over` ou `Palmeiras|over`. O campo `name` também vem como `Escanteios do time — Flamengo`, nunca como um time genérico.

O catálogo abaixo detalha os mercados liquidados automaticamente pela plataforma. Todos os esportes usam o mesmo formato de bookmaker/market/outcomes.

Cartão vermelho: não existe o mercado "vai ter vermelho no jogo (sim/não)". Use player_to_receive_red_card (odds por jogador) e os contadores ao vivo em stats.home.redCards / stats.away.redCards. Apostas de escanteios e cartões são liquidadas pelas estatísticas oficiais da partida; se o jogo não tiver estatísticas, a aposta fica void.

Pagamentos e webhooks

Limites

Cada plano tem um limite de requisições por dia. Ao atingir o limite, a API responde 429 até o próximo dia. Acompanhe pelos cabeçalhos:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-Plan

Erros