Snapshot de Odds

Obtenha um snapshot das odds atuais das casas de apostas.

GET /api/v1/odds

AutenticaçãoPermalink for this section

Requer API key. Disponível para todos os tiers.

Parâmetros de QueryPermalink for this section

Aliases de Categoria de MercadoPermalink for this section

Em vez de listar tipos de mercado individuais, você pode usar um alias de categoria para corresponder a um grupo de mercados relacionados. Aliases e tipos exatos podem ser misturados livremente em uma lista separada por vírgulas.

# Buscar todos os mercados "main" (moneyline + spreads + totals)
curl "https://api.sharpapi.io/api/v1/odds?league=nba&market=main" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Misturar um alias com um tipo exato
curl "https://api.sharpapi.io/api/v1/odds?league=nfl&market=spread,moneyline" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Todos os mercados de player props
curl "https://api.sharpapi.io/api/v1/odds?league=nba&market=props" \
  -H "X-API-Key: YOUR_API_KEY"

Exemplos de RequisiçãoPermalink for this section

curl -X GET "https://api.sharpapi.io/api/v1/odds?league=nba&sportsbook=draftkings&market=moneyline" \
  -H "X-API-Key: YOUR_API_KEY"

// Buscar todas as odds de moneyline da NBA usando paginação baseada em cursor (recomendado)
async function fetchAllOdds() {
  const results = [];
  let cursor = null;
 
  do {
    const url = new URL('https://api.sharpapi.io/api/v1/odds');
    url.searchParams.set('league', 'nba');
    url.searchParams.set('sportsbook', 'draftkings');
    url.searchParams.set('market', 'moneyline');
    url.searchParams.set('limit', '200');
    if (cursor) url.searchParams.set('cursor', cursor);
 
    const { data, pagination } = await fetch(url, {
      headers: { 'X-API-Key': 'YOUR_API_KEY' }
    }).then(r => r.json());
 
    results.push(...data);
    cursor = pagination.has_more ? pagination.next_cursor : null;
  } while (cursor);
 
  return results;
}

import requests
 
# Buscar todas as odds de moneyline da NBA usando paginação baseada em cursor (recomendado)
def fetch_all_odds():
    results = []
    params = {'league': 'nba', 'sportsbook': 'draftkings', 'market': 'moneyline', 'limit': 200}
    cursor = None
 
    while True:
        if cursor:
            params['cursor'] = cursor
        resp = requests.get(
            'https://api.sharpapi.io/api/v1/odds',
            params=params,
            headers={'X-API-Key': 'YOUR_API_KEY'}
        ).json()
 
        results.extend(resp['data'])
        pagination = resp['pagination']
        if not pagination['has_more']:
            break
        cursor = pagination['next_cursor']
 
    return results

PaginaçãoPermalink for this section

Cada resposta inclui tanto next_cursor (estável) quanto next_offset (legado) no objeto pagination. Para varreduras sequenciais do conjunto completo de dados, sempre use next_cursor.

# Primeira página — sem necessidade de cursor
curl "https://api.sharpapi.io/api/v1/odds?league=nfl&limit=200" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Páginas subsequentes — passe next_cursor da resposta anterior
curl "https://api.sharpapi.io/api/v1/odds?league=nfl&limit=200&cursor=eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0" \
  -H "X-API-Key: YOUR_API_KEY"

Ordem dos resultadosPermalink for this section

Os resultados são retornados em ordem cronológica por hora de início do evento — primeiro os eventos já em andamento e os que começam mais cedo, depois os posteriores. Eventos sem hora de início no feed são ordenados por último.

Uma única página é, portanto, uma fatia da programação, não uma amostra de todo o conjunto de resultados. Uma casa de apostas sem jogos começando dentro do trecho da programação que aquela página cobre não aparecerá nela, mesmo que tenha muitas linhas correspondentes mais tarde no mesmo dia — esse é o comportamento esperado, não uma falha de cobertura. Para verificar se uma casa oferece um mercado, filtre com ?sportsbook= ou restrinja com ?league= em vez de ler uma primeira página sem filtro.

Em uma página com linhas, é isso que meta.books informa: uma casa listada em in_scope sem entrada em in_page não retornou linhas naquela página — geralmente porque seus jogos ficam fora do trecho da programação que aquela página cobre, e não porque ela não oferece o mercado.

Cursores são opacos — não os analise nem os construa. Eles codificam a posição de ordenação do último item na página atual e só são válidos para os mesmos parâmetros de filtro.

?offset=N continua funcionando para paginação rasa (até offset 500) e é apropriado para requisições de página única ou acesso direto por posição. Além de 500, a API retorna 400 offset_too_large — caso contrário, o servidor teria que ordenar todo o conjunto filtrado de resultados a cada página, o que é muito mais barato evitar do que otimizar por requisição. Use cursor para qualquer coisa mais profunda.

{
  "error": {
    "code": "offset_too_large",
    "message": "offset must be <= 500; use `cursor=` from the previous response for deeper pagination",
    "max_offset": 500
  }
}

RespostaPermalink for this section

Sucesso (200)Permalink for this section

{
  "success": true,
  "data": [
    {
      "id": "draftkings_33483153_moneyline_PHO",
      "sportsbook": "draftkings",
      "event_id": "33483153",
      "sport": "basketball",
      "league": "nba",
      "home_team": "PHI 76ers",
      "away_team": "PHO Suns",
      "market_type": "moneyline",
      "selection": "PHO Suns",
      "selection_type": "away",
      "odds_american": -150,
      "odds_decimal": 1.667,
      "odds_probability": 0.60,
      "line": null,
      "event_start_time": "2026-01-26T19:00:00Z",
      "timestamp": "2026-01-26T02:10:24.125Z",
      "is_live": false
    },
    {
      "id": "draftkings_33483153_moneyline_PHI",
      "sportsbook": "draftkings",
      "event_id": "33483153",
      "sport": "basketball",
      "league": "nba",
      "home_team": "PHI 76ers",
      "away_team": "PHO Suns",
      "market_type": "moneyline",
      "selection": "PHI 76ers",
      "selection_type": "home",
      "odds_american": 130,
      "odds_decimal": 2.30,
      "odds_probability": 0.4348,
      "line": null,
      "event_start_time": "2026-01-26T19:00:00Z",
      "timestamp": "2026-01-26T02:10:24.125Z",
      "is_live": false
    }
  ],
  "meta": {
    "count": 2,
    "total": 3095,
    "books_available": ["draftkings", "fanduel", "betmgm", "caesars", "pinnacle"],
    "books_returned": ["draftkings"],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "has_more": true,
      "next_offset": 50,
      "next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
    },
    "updated_at": "2026-01-26T02:10:37.846Z",
    "filters": {
      "league": "nba",
      "sportsbook": "draftkings",
      "market": "moneyline"
    }
  }
}

Resultados vazios (200): meta.storePermalink for this section

Uma página vazia — 200 com "data": [] e "count": 0 — pode significar duas coisas diferentes: seus filtros não corresponderam a nada, ou a instância que respondeu não tinha nada carregado naquele momento (por exemplo, durante uma troca de store). Desde setembro de 2026 a resposta diz qual é o caso. Sempre que /odds retorna zero linhas, um bloco meta.store é adicionado, e reason é o campo no qual você deve se basear:

{
  "data": [],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 0,
    "has_more": false,
    "next_offset": null
  },
  "updated_at": "2026-09-07T02:41:18.552Z",
  "meta": {
    "store": {
      "generation": 5019,
      "ready": true,
      "books": 39,
      "rows": 810137,
      "reason": "no_match"
    }
  }
}

• Presente apenas em resultados vazios. Uma resposta com linhas é idêntica byte a byte à anterior e não carrega meta.store; parsers que leem data + pagination + updated_at continuam funcionando.
• books e rows descrevem o snapshot inteiro, não a sua consulta — rows: 810137 é evidência de que o store estava populado, não uma contagem do que você teria obtido.
• Consultas que se resolvem para duas ou mais casas de apostas também carregam meta.books (o escopo de casas resolvido: in_scope e as contagens in_page por casa); meta.store é adicionado ao lado dele. O mesmo vale para a página vazia de uma seleção de casas do dashboard que não se resolveu para nenhuma casa — veja Seleção de casas vazia abaixo.
• Um valor desconhecido de league ou sportsbook é rejeitado com 400 invalid_filter em vez de respondido com uma página vazia. Os demais filtros não são validados contra o catálogo: um market_type ou event_id que não existe em lugar nenhum retorna uma página vazia comum com reason: "no_match".

Eventos finalizados: event_status e completed_atPermalink for this section

Um cliente que continua consultando /odds?event_id=<id> depois que o jogo termina recebe uma página vazia definitiva — reason: "no_match" é verdadeiro, mas não diz por que nada correspondeu. Quando a página está vazia porque o único evento pelo qual você filtrou terminou, meta.store também diz isso. Esta é a resposta real para um jogo da MLB que havia terminado na mesma noite (uma consulta de uma única casa, para que o corpo fique curto — uma consulta com várias casas carrega meta.books ao lado, como acima):

GET /api/v1/odds?event_id=mlb_twins_whitesox_2026-09-06_b3&sportsbook=pinnacle&limit=1

{
  "data": [],
  "pagination": {
    "limit": 1,
    "offset": 0,
    "count": 0,
    "has_more": false,
    "next_offset": null
  },
  "updated_at": "2026-09-07T10:04:34.951684418Z",
  "meta": {
    "store": {
      "generation": 13456,
      "ready": true,
      "books": 39,
      "rows": 947879,
      "reason": "no_match",
      "event_status": "final",
      "completed_at": "2026-09-07T02:09:37Z"
    }
  }
}

/events/mlb_twins_whitesox_2026-09-06_b3 retornou status: "final" com o mesmo completed_at no mesmo instante — os dois endpoints leem o mesmo registro, portanto não podem discordar.

O sinal só é anexado quando todas as condições a seguir são satisfeitas — caso contrário o bloco mantém sua forma comum e nenhuma das duas chaves está presente:

• a requisição filtrou por exatamente um event_id (uma lista separada por vírgulas não recebe sinal — o campo é singular);
• a página está vazia com reason: "no_match" (uma página warming ou store_empty nunca o carrega — o vazio é do store, e reason já diz para tentar novamente);
• sabe-se que o evento terminou. Um evento ainda ao vivo ou futuro, ou um id que não existe em lugar nenhum, recebe um no_match comum sem event_status — portanto uma consulta de um único id respondida sem ele significa um id errado ou um evento que não terminou.

Um evento finalizado cujas odds ainda estão em cache retorna essas linhas normalmente; o sinal aparece quando a página se esvazia. completed_at é o momento em que a conclusão foi detectada — normalmente alguns minutos depois de o evento sair do feed ao vivo — e não o apito final; a mesma ressalva de completed_at em /events. O código de status nunca muda: um cliente que consulta um evento ao longo de toda a sua vida continua recebendo 200.

Seleção de casas vazia: meta.books.reasonPermalink for this section

Se a seleção de casas de apostas salva no seu dashboard não se resolve para nada — todas as casas selecionadas estão ausentes do snapshot atual ou não estão incluídas no seu tier —, uma requisição a /odds sem filtros é respondida com uma página vazia. O store está bem; a seleção é o motivo, e a resposta o nomeia. meta.books — normalmente presente apenas em consultas que se resolvem para duas ou mais casas — é emitido com um escopo vazio, reason: "selection_disjoint" e selected, a seleção que não se resolveu para nada (IDs canônicos de casa, ordenados):

{
  "data": [],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 0,
    "has_more": false,
    "next_offset": null
  },
  "updated_at": "2026-09-07T10:04:34.951684418Z",
  "meta": {
    "books": {
      "in_scope": [],
      "in_page": {},
      "reason": "selection_disjoint",
      "selected": ["betano", "bwin"]
    },
    "store": {
      "generation": 13454,
      "ready": true,
      "books": 39,
      "rows": 947919,
      "reason": "no_match"
    }
  }
}

• meta.books.reason tem precedência. meta.store continua aparecendo ao lado com reason: "no_match" — correto para o store (ele está populado), mas não é a causa. Quando meta.books.reason está presente, esse é o motivo da página vazia; tentar novamente não mudará a resposta. Corrija a seleção no seu dashboard, ou faça upgrade se as casas que você selecionou exigirem um tier superior.
• in_scope e in_page estão presentes e vazios ([] / {}, nunca null). O único valor de reason hoje é selection_disjoint.
• Emitido apenas quando a seleção é de fato a causa: a requisição não trazia um filtro sportsbook= explícito, você tem uma seleção no dashboard e seu tier sozinho teria se resolvido para pelo menos uma casa. Nunca aparece no tier Free (que sempre serve DraftKings e FanDuel, independentemente da seleção) nem com um store vazio ou em aquecimento — essas páginas são explicadas por meta.store.
• Com um filtro sportsbook= explícito, a mesma divergência é rejeitada em vez de respondida com uma página vazia: 403 tier_restricted, 403 book_not_selected ou 503 book_unavailable.
• Páginas que se resolvem para uma ou mais casas não mudam: o bloco de duas ou mais casas não carrega reason nem selected, e um escopo de uma única casa não carrega meta.books de forma alguma.

Cabeçalhos de RespostaPermalink for this section

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1737853200
X-Data-Delay: 0
X-Request-Id: req_abc123def456

Respostas de ErroPermalink for this section

401 Unauthorized

Se nenhuma chave for enviada, retorna missing_api_key; uma chave inválida retorna invalid_api_key.

{
  "error": {
    "code": "missing_api_key",
    "message": "API key required. Pass via X-API-Key header, api_key query parameter, or Bearer token.",
    "docs": "https://docs.sharpapi.io/en/authentication"
  }
}

403 Tier Restricted

{
  "error": {
    "code": "tier_restricted",
    "message": "Sportsbook 'pinnacle' requires Sharp tier or higher",
    "docs": "https://docs.sharpapi.io/en/pricing"
  }
}

429 Rate Limited

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "docs": "https://docs.sharpapi.io/en/authentication#rate-limits"
  }
}

Schema do Objeto OddsPermalink for this section

Tipos de seleçãoPermalink for this section

selection_type carrega o identificador canônico de lado para cada selection. A maioria dos mercados é de duas vias (ex.: moneyline, point spread, total) e emite um dos valores simples abaixo. Um pequeno conjunto de mercados multieixo (dupla chance no futebol, BTTS combinado, resultado × O/U, round betting de MMA, set betting de tênis, placar exato, etc.) codifica dois resultados por seleção e emite valores compostos unidos por _.

Filtragem por Faixa de OddsPermalink for this section

Use min_odds e max_odds para filtrar pelo valor das odds americanas.

# Retornar apenas odds positivas (+100 e acima)
curl "https://api.sharpapi.io/api/v1/odds?league=nba&min_odds=100" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Retornar apenas odds entre -200 e +200
curl "https://api.sharpapi.io/api/v1/odds?league=nba&min_odds=-200&max_odds=200" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta Agrupada por EventoPermalink for this section

Use group_by=event para agrupar odds por evento em vez de uma lista plana. Isso é útil para construir UIs centradas em eventos.

curl "https://api.sharpapi.io/api/v1/odds?league=nba&group_by=event" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "data": [
    {
      "event_id": "33483153",
      "event_name": "PHI 76ers vs PHO Suns",
      "sport": "basketball",
      "league": "nba",
      "start_time": "2026-01-26T19:00:00Z",
      "is_live": false,
      "odds": [
        {
          "id": "draftkings_33483153_moneyline_PHO",
          "sportsbook": "draftkings",
          "market_type": "moneyline",
          "selection": "PHO Suns",
          "selection_type": "away",
          "odds_american": -150,
          "odds_decimal": 1.667,
          "odds_probability": 0.60,
          "line": null,
          "timestamp": "2026-01-26T02:10:24.125Z"
        }
      ]
    }
  ],
  "meta": {
    "group_by": "event",
    "books_available": 5,
    "filters": { "league": "nba" },
    "updated_at": "2026-01-26T02:10:37.846Z"
  }
}

Acesso a Casas por TierPermalink for this section

As casas de apostas incluídas em seus resultados de odds dependem do seu tier de assinatura:

Exemplos de FiltragemPermalink for this section

# Obter odds ao vivo da NBA de todas as casas disponíveis
curl "https://api.sharpapi.io/api/v1/odds?league=nba&is_live=true" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Obter odds de moneyline e spread para um evento específico
curl "https://api.sharpapi.io/api/v1/odds?event_id=nba_76ers_suns_2026-01-26_b3&market=moneyline,spread" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Paginar por todas as odds de spread da NFL (use next_cursor de cada resposta)
curl "https://api.sharpapi.io/api/v1/odds?league=nfl&market=spread&limit=200" \
  -H "X-API-Key: YOUR_API_KEY"

Endpoints RelacionadosPermalink for this section

• Odds Delta - Obtenha apenas odds que mudaram desde um determinado timestamp
• Best Odds - Obtenha as melhores odds em todas as casas para cada seleção
• Odds Comparison - Compare odds entre casas lado a lado
• Batch Odds - Busque odds para múltiplos eventos em uma única requisição
• Markets - Liste tipos de mercado disponíveis
• Sportsbooks - Liste casas de apostas disponíveis e seus status