API de Esportes (v1)

URL base:

https://sportdataapi.cyou/api/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

Parâmetros — GET /events

league*

string

ID da liga (de /leagues)

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.

Mercados para Vôlei

A disponibilidade varia por liga e momento do jogo. Em partidas futuras, alguns mercados só aparecem quando as linhas são abertas. O endpoint /events/{eventId} devolve somente os mercados abertos daquele evento.

Mercado	selection	Aposta
h2hMoneyline / vencedor · Resultado	home \| away \| draw (quando aplicável)	Sim
spreadsHandicap / spread · Handicap	home \| away (+ point)	Sim
totalsTotal (mais/menos) · Totais	over \| under (+ point)	Sim
alternate_spreadsHandicaps alternativos · Handicap	home \| away (+ point)	Só odds
alternate_totalsTotais alternativos · Totais	over \| under (+ point)	Só odds
team_totalsTotais por equipe · Totais	team\|over \| team\|under (+ point)	Só odds

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

Pagamentos de assinatura via Pix são gerados pelo gateway configurado no painel Bank. 1. POST /api/me/action com action=purchase gera uma cobrança. 2. O sistema recebe QR Code e copia-e-cola. 3. O gateway chama /api/webhooks/vibepay com x-signature. 4. Ao receber PAID/APPROVED/CONFIRMED, o pagamento vira approved e a assinatura é liberada automaticamente. 5. O endpoint /api/me/action com action=getPaymentStatus também consulta o status para o painel. No seu cliente/API de apostas, o fluxo é separado: POST /bets cria o bilhete e o webhook cadastrado em webhook_url recebe bet.settled com WIN, LOSS ou VOID.

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

401	missing_api_key / invalid_api_key	Chave ausente, inválida ou revogada
403	domain_not_allowed	A requisição veio de um domínio diferente do cadastrado
403	league_not_in_plan	A liga não está incluída no seu plano
403	sport_not_in_plan	O esporte não está incluído no seu plano
409	odds_suspended	Odds bloqueadas (atualizando) — tente de novo em instantes
409	odds_changed	A odd mudou; o erro retorna a odd máxima atual
409	market_decided / event_finished	Mercado já decidido ou jogo encerrado
429	daily_limit_reached	Limite diário do plano atingido (zera 00:00 UTC)
429	rate_limited	Muitas requisições por minuto

Criar conta grátis

Exemplo — GET /events

curl --request GET \
  --url 'https://sportdataapi.cyou/api/v1/events?league=soccer_brazil_campeonato' \
  --header 'x-api-key: SUA_API_KEY'

Resposta

{
  "ok": true,
  "data": [
    {
      "id": "a1b2c3d4e5f6",
      "league": "soccer_brazil_campeonato",
      "homeTeam": "Flamengo",
      "awayTeam": "Palmeiras",
      "homeLogo": "https://sua-api.com/api/img/team/819",
      "awayLogo": "https://sua-api.com/api/img/team/2029",
      "commenceTime": "2026-10-02T22:00:00Z",
      "status": "live",
      "minute": 67,
      "period": 2,
      "halftime": false,
      "clock": "67'",
      "addedTime": null, // vira { "firstHalf": 2, "secondHalf": 5, "announced": true } quando anunciado
      "score": { "home": 1, "away": 0 },
      "halftimeScore": { "home": 1, "away": 0 },
      "incidents": [
        { "type": "goal", "team": "home", "minute": "23'", "player": "Pedro" },
        { "type": "yellow_card", "team": "away", "minute": "41'", "player": "Gómez" }
      ],
      "stats": {
        "home": { "possession": 58, "shots": 11, "shotsOnTarget": 5, "corners": 6, "yellowCards": 1, "redCards": 0, "fouls": 9, "offsides": 2 },
        "away": { "possession": 42, "shots": 7, "shotsOnTarget": 2, "corners": 3, "yellowCards": 2, "redCards": 0, "fouls": 12, "offsides": 1 }
      },
      "updatedAt": "2026-10-02T23:14:05Z",
      "statusDetail": "67'", // texto da fonte: "HT", "FT", "Susp", "Int."...
      "suspended": false, // true com o jogo suspenso/interrompido: status segue "live" e oddsSuspended vira true
      "oddsSuspended": false,
      "bookmakers": [
        {
          "key": "pinnacle",
          "markets": [
            {
              "key": "h2h",
              "outcomes": [
                { "name": "Flamengo", "price": 1.85 },
                { "name": "Draw", "price": 3.4 },
                { "name": "Palmeiras", "price": 4.2 }
              ]
            },
            {
              "key": "totals",
              "outcomes": [
                { "name": "Over", "price": 1.7, "point": 2.5 },
                { "name": "Under", "price": 2.1, "point": 2.5 }
              ]
            }
          ]
        }
      ]
    }
  ]
}