Delta de Odds

Obtenha apenas as odds que mudaram desde um timestamp específico. Este endpoint retorna o mesmo formato de odds que /odds, mas filtrado para itens atualizados após o seu valor since, tornando-o ideal para clientes de polling que desejam atualizações incrementais sem buscar novamente o snapshot completo.

GET /api/v1/odds/delta

AutenticaçãoPermalink for this section

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

Parâmetros de QueryPermalink for this section

Exemplos de RequisiçõesPermalink for this section

# Get all odds changes in the last 30 seconds
curl -X GET "https://api.sharpapi.io/api/v1/odds/delta?since=2026-02-11T12:00:00Z&league=nba" \
  -H "X-API-Key: YOUR_API_KEY"

let since = new Date(Date.now() - 30000).toISOString();
 
async function pollDelta() {
  let offset = 0;
  while (true) {
    const response = await fetch(
      `https://api.sharpapi.io/api/v1/odds/delta?since=${since}&league=nba&limit=500&offset=${offset}`,
      { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
    );
    const { data, removed, pagination, meta, overflow } = await response.json();
 
    console.log(`${pagination.count} odds changed, ${removed.length} removed`);
 
    if (!pagination.has_more) {
      if (overflow) {
        // Página terminal, mas a varredura limitada do servidor (nível Free) não cobriu toda a janela: as linhas que ficaram de fora são inalcançáveis em qualquer offset e esta marca d'água as pularia. Refaça o bootstrap em vez de avançar — veja "Quando uma janela não pode ser drenada".
        throw new Error(
          'delta window not fully scanned: re-baseline from /odds (cursor=), ' +
          "then resume with the FIRST baseline page's updated_at as since"
        );
      }
      // Página terminal: server_time é a marca d'água real — use-a como próximo since.
      since = meta.server_time;
      break;
    }
    if (pagination.next_offset === null) {
      // Janela grande demais para paginar por offset — um since novo deve vir de uma base /odds nova, nunca desta resposta. Veja Padrão de Polling.
      throw new Error(
        'delta window exceeds offset paging: re-baseline from /odds (cursor=), ' +
        "then resume with the FIRST baseline page's updated_at as since"
      );
    }
    // since permanece inalterado enquanto a janela é drenada.
    offset = pagination.next_offset;
  }
}
 
// Poll every 5 seconds
setInterval(pollDelta, 5000);

import requests
import time
from datetime import datetime, timezone, timedelta
 
since = (datetime.now(timezone.utc) - timedelta(seconds=30)).isoformat()
 
while True:
    offset = 0
    while True:
        response = requests.get(
            'https://api.sharpapi.io/api/v1/odds/delta',
            params={'since': since, 'league': 'nba', 'limit': 500, 'offset': offset},
            headers={'X-API-Key': 'YOUR_API_KEY'}
        )
        result = response.json()
        pagination = result['pagination']
 
        print(f"{pagination['count']} odds changed, {len(result['removed'])} removed")
 
        if not pagination['has_more']:
            if result.get('overflow'):
                # Página terminal, mas a varredura limitada do servidor (nível Free) não cobriu toda a janela: as linhas que ficaram de fora são inalcançáveis em qualquer offset e esta marca d'água as pularia. Refaça o bootstrap em vez de avançar — veja "Quando uma janela não pode ser drenada".
                raise RuntimeError(
                    'delta window not fully scanned: re-baseline from /odds '
                    "(cursor=), then resume with the FIRST baseline page's "
                    'updated_at as since'
                )
            # Página terminal: server_time é a marca d'água real — use-a como próximo since.
            since = result['meta']['server_time']
            break
        if pagination['next_offset'] is None:
            # Janela grande demais para paginar por offset — um since novo deve vir de uma base /odds nova, nunca desta resposta. Veja Padrão de Polling.
            raise RuntimeError(
                'delta window exceeds offset paging: re-baseline from /odds '
                "(cursor=), then resume with the FIRST baseline page's "
                'updated_at as since'
            )
        # since permanece inalterado enquanto a janela é drenada.
        offset = pagination['next_offset']
 
    time.sleep(5)

RespostaPermalink for this section

Sucesso (200)Permalink for this section

{
  "data": [
    {
      "id": "199954867251468",
      "sportsbook": "draftkings",
      "event_id": "nba_celtics_lakers_2026-02-08_b3",
      "sport": "basketball",
      "league": "nba",
      "home_team": "Los Angeles Lakers",
      "away_team": "Boston Celtics",
      "market_type": "moneyline",
      "selection": "Boston Celtics",
      "selection_type": "away",
      "odds_american": -150,
      "odds_decimal": 1.667,
      "odds_probability": 0.60,
      "line": null,
      "event_start_time": "2026-02-08T19:00:00Z",
      "timestamp": "2026-02-08T12:00:15.125Z",
      "is_live": false,
      "is_main_line": true
    }
  ],
  "removed": [
    {
      "id": "102044417046441",
      "sportsbook": "pinnacle",
      "removed_at": "2026-02-08T12:00:07Z",
      "event_start": "2026-02-08T12:00:00Z",
      "was_live": false,
      "boundary": true
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 1,
    "total": 1,
    "has_more": false,
    "next_offset": null
  },
  "updated_at": "2026-02-08T12:00:20Z",
  "meta": {
    "server_time": "2026-02-08T12:00:20Z"
  }
}

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_delta_abc123

Respostas de ErroPermalink for this section

400 Parâmetro since ausente

{
  "error": {
    "code": "validation_error",
    "message": "The 'since' parameter is required for the delta endpoint",
    "docs": "https://docs.sharpapi.io/en/api-reference/odds-delta"
  }
}

400 Offset muito grande

{
  "error": {
    "code": "offset_too_large",
    "message": "offset must be <= 500; page with `next_offset` until `has_more` is false, then advance `since` to the response's top-level `updated_at` (mirrored as `meta.server_time`; a response field, not a row field) — it holds at your current `since` while `has_more` is true; keep paging while `next_offset` is non-null even if `overflow` is true (that only means `total` is capped); when `next_offset` is null while `has_more` or `overflow` is true, re-bootstrap from paged `/odds` (`cursor=`) and resume delta with a fresh `since`",
    "max_offset": 500
  }
}

401 Não autorizado

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"
  }
}

Schema da Resposta de DeltaPermalink for this section

O array data contém os mesmos objetos de odds que o endpoint /odds. Apenas odds atualizadas após o timestamp since são incluídas.

O Array removedPermalink for this section

O array removed de nível superior nomeia cada linha de odds que saiu do quadro desde o seu timestamp since — mercados que uma casa retirou (suspensão, um limiar de handicap/total retirado por um movimento de linha, evento liquidado). Delete esses ids do seu estado local; este é o sinal de fechamento explícito, então você nunca precisa comparar snapshots por conta própria. Presente apenas quando ao menos uma remoção correspondeu aos seus filtros. Veja Ciclo de Vida do Mercado para o mapa completo de sinais de fechamento/suspensão.

A resposta de delta inclui campos adicionais:

Flags de Truncamento e ClampingPermalink for this section

Duas flags booleanas opcionais de nível superior aparecem apenas quando o servidor teve que aplicar um limite de segurança à resposta. Clientes bem comportados que fazem polling na cadência recomendada nunca as veem.

Padrão de PollingPermalink for this section

O padrão de polling recomendado drena cada janela e então encadeia since a partir da página terminal:

1. Faça uma requisição inicial com since definido para um timestamp recente
2. Aplique data como upserts e removed como exclusões
3. Enquanto pagination.has_more for true e pagination.next_offset não for null, solicite a próxima página com offset igual a next_offset, mantendo since inalterado
4. Na página terminal (has_more: false), leia meta.server_time e use-o como o valor since na sua próxima requisição — a menos que overflow ainda seja true nessa página (varredura limitada do nível Free): então refaça o bootstrap em vez de avançar (veja abaixo)
5. Repita no intervalo desejado (ex.: a cada 5 segundos)

Isso garante:

• Sem lacunas - server_time é o relógio do servidor e só avança quando você já tem todas as linhas da janela, então você não perderá atualizações por desvio de relógio nem por uma leitura parcial
• Sem duplicatas - cada janela de delta é não sobreposta
• Payload mínimo - apenas odds alteradas são retornadas

Quando uma janela não pode ser drenadaPermalink for this section

offset é limitado a 500, então uma janela com mais mudanças correspondentes do que a paginação por offset alcança termina com next_offset: null enquanto has_more ainda é true. No nível Free, a varredura limitada do servidor também pode deixar overflow: true na própria página terminal (has_more: false) — linhas além do orçamento de varredura são inalcançáveis em qualquer offset, e avançar since ali as pularia. Os dois estados são o mesmo sinal — refaça o bootstrap sempre que next_offset for null enquanto has_more ou overflow for true:

1. Busque uma base completa em /odds com paginação cursor=
2. Retome o polling de delta com since definido para o updated_at da primeira página da base — páginas posteriores são lidas mais tarde; usar o valor da última página deixaria lacunas com as mudanças que chegaram a páginas anteriores durante a varredura

Fazendo polling na cadência recomendada com limit=500, as janelas ficam pequenas o bastante para que esse caminho raramente seja necessário.

Endpoints RelacionadosPermalink for this section

• Snapshot de Odds - Obtenha o snapshot completo atual de odds
• Stream SSE - Atualizações push em tempo real via Server-Sent Events
• Stream WebSocket - Atualizações push em tempo real via WebSocket