Instantánea de Cuotas

Obtén una instantánea de las cuotas actuales de las casas de apuestas.

GET /api/v1/odds

AutenticaciónPermalink for this section

Requiere API key. Disponible para todos los planes.

Parámetros de ConsultaPermalink for this section

Alias de Categoría de MercadoPermalink for this section

En lugar de listar tipos de mercado individuales, puedes usar un alias de categoría para coincidir con un grupo de mercados relacionados. Los alias y los tipos exactos pueden mezclarse libremente en una lista separada por comas.

# Obtener todos los mercados "main" (moneyline + spreads + totales)
curl "https://api.sharpapi.io/api/v1/odds?league=nba&market=main" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Mezclar un alias con un tipo exacto
curl "https://api.sharpapi.io/api/v1/odds?league=nfl&market=spread,moneyline" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Todos los mercados de player props
curl "https://api.sharpapi.io/api/v1/odds?league=nba&market=props" \
  -H "X-API-Key: YOUR_API_KEY"

Ejemplos de SolicitudesPermalink 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"

// Obtener todas las cuotas moneyline de la NBA usando paginación basada en 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
 
# Obtener todas las cuotas moneyline de la NBA usando paginación basada en 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

PaginaciónPermalink for this section

Cada respuesta incluye tanto next_cursor (estable) como next_offset (legacy) en el objeto pagination. Para escaneos secuenciales de un conjunto de datos completo, usa siempre next_cursor.

# Primera página — no se necesita cursor
curl "https://api.sharpapi.io/api/v1/odds?league=nfl&limit=200" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Páginas siguientes — pasa next_cursor de la respuesta anterior
curl "https://api.sharpapi.io/api/v1/odds?league=nfl&limit=200&cursor=eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0" \
  -H "X-API-Key: YOUR_API_KEY"

Orden de los resultadosPermalink for this section

Los resultados se devuelven en orden cronológico por hora de inicio del evento: primero los eventos que ya están en curso y los que empiezan antes, después los posteriores. Los eventos sin hora de inicio en el feed se ordenan al final.

Por tanto, una sola página es una porción del calendario, no una muestra del conjunto completo de resultados. Una casa de apuestas sin partidos que empiecen dentro del tramo del calendario que esa página cubre no aparecerá en ella, aunque tenga muchas filas coincidentes más tarde ese mismo día: es el comportamiento esperado, no una falta de cobertura. Para comprobar si una casa ofrece un mercado, filtra con ?sportsbook= o acota con ?league= en lugar de leer una primera página sin filtrar.

En una página con filas, eso es lo que indica meta.books: una casa que aparece en in_scope sin entrada en in_page no devolvió filas en esa página, normalmente porque sus partidos quedan fuera del tramo del calendario que esa página cubre y no porque no ofrezca el mercado.

Los cursores son opacos — no los analices ni los construyas. Codifican la posición de ordenación del último elemento de la página actual y solo son válidos para los mismos parámetros de filtro.

?offset=N sigue funcionando para paginación superficial (hasta el offset 500) y es apropiado para solicitudes de una sola página o acceso directo por posición. Más allá de 500, la API devuelve 400 offset_too_large — de lo contrario, el servidor tendría que ordenar el conjunto de resultados filtrado completo en cada página, lo que es mucho más barato evitar que optimizar por solicitud. Usa cursor para cualquier cosa más profunda.

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

RespuestaPermalink for this section

Éxito (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 vacíos (200): meta.storePermalink for this section

Una página vacía —200 con "data": [] y "count": 0— puede significar dos cosas distintas: que tus filtros no coincidieron con nada, o que la instancia que respondió no tenía nada cargado en ese momento (por ejemplo, durante un cambio de store). Desde septiembre de 2026 la respuesta indica cuál de las dos es. Siempre que /odds devuelve cero filas añade un bloque meta.store, y reason es el campo sobre el que debes decidir:

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

• Solo está presente en resultados vacíos. Una respuesta con filas es idéntica byte a byte a la anterior y no incluye meta.store; los parsers que leen data + pagination + updated_at siguen funcionando.
• books y rows describen el snapshot completo, no tu consulta: rows: 810137 demuestra que el store tenía datos, no cuenta lo que habrías obtenido.
• Las consultas que se resuelven a dos o más casas de apuestas también incluyen meta.books (el conjunto de casas resuelto: in_scope y los recuentos in_page por casa); meta.store se añade junto a él. Lo mismo ocurre con la página vacía de una selección de casas del dashboard que no se resolvió a ninguna casa; ver Selección de casas vacía más abajo.
• Un valor desconocido de league o sportsbook se rechaza con 400 invalid_filter en lugar de responderse con una página vacía. Los demás filtros no se validan contra el catálogo: un market_type o un event_id que no existe en ningún sitio devuelve una página vacía normal con reason: "no_match".

Eventos finalizados: event_status y completed_atPermalink for this section

Un cliente que sigue consultando /odds?event_id=<id> después de que el partido termine recibe una página vacía definitiva: reason: "no_match" es cierto, pero no dice por qué nada coincidió. Cuando la página está vacía porque el único evento por el que filtraste ha terminado, meta.store también lo indica. Esta es la respuesta real para un partido de la MLB que había terminado esa misma noche (una consulta de una sola casa, para que el cuerpo sea corto; una consulta de varias casas incluye además meta.books, como arriba):

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 devolvió en ese mismo instante status: "final" con el mismo completed_at: ambos endpoints leen el mismo registro, así que no pueden discrepar.

La señal solo se añade cuando se cumplen todas las condiciones siguientes; en caso contrario el bloque conserva su forma habitual y ninguna de las dos claves está presente:

• la petición filtró por exactamente un event_id (una lista separada por comas no recibe señal; el campo es singular);
• la página está vacía con reason: "no_match" (una página warming o store_empty nunca la incluye: el vacío es del store, y reason ya indica que reintentes);
• se sabe que el evento ha terminado. Un evento todavía en vivo o próximo, o un id que no existe en ningún sitio, recibe un no_match normal sin event_status; así que una consulta de un solo id respondida sin él significa un id incorrecto o un evento que no ha terminado.

Un evento finalizado cuyas cuotas siguen en caché devuelve esas filas con normalidad; la señal aparece cuando la página se vacía. completed_at es el momento en que se detectó la finalización —normalmente unos minutos después de que el evento saliera del feed en vivo—, no el pitido final; la misma salvedad que completed_at en /events. El código de estado nunca cambia: un cliente que consulta un evento durante toda su vida sigue recibiendo 200.

Selección de casas vacía: meta.books.reasonPermalink for this section

Si la selección de casas de apuestas guardada en tu dashboard no se resuelve a nada —todas las casas seleccionadas están ausentes del snapshot actual o no están incluidas en tu plan—, una petición a /odds sin filtros se responde con una página vacía. El store está bien; la selección es el motivo, y la respuesta lo nombra. meta.books —normalmente presente solo en consultas que se resuelven a dos o más casas— se emite con un conjunto vacío, reason: "selection_disjoint" y selected, la selección que no se resolvió a 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 tiene prioridad. meta.store sigue apareciendo junto a él con reason: "no_match": correcto para el store (tiene datos), pero no es la causa. Cuando meta.books.reason está presente, ese es el motivo de la página vacía; reintentar no cambiará la respuesta. Corrige la selección en tu dashboard, o mejora tu plan si las casas que seleccionaste requieren uno superior.
• in_scope e in_page están presentes y vacíos ([] / {}, nunca null). El único valor de reason hoy es selection_disjoint.
• Se emite solo cuando la selección es realmente la causa: la petición no llevaba un filtro sportsbook= explícito, tienes una selección en el dashboard y tu plan por sí solo se habría resuelto al menos a una casa. Nunca aparece en el plan Free (que siempre sirve DraftKings y FanDuel, sea cual sea la selección) ni con un store vacío o en calentamiento: esas páginas las explica meta.store.
• Con un filtro sportsbook= explícito, la misma discrepancia se rechaza en lugar de responderse con una página vacía: 403 tier_restricted, 403 book_not_selected o 503 book_unavailable.
• Las páginas que se resuelven a una o más casas no cambian: el bloque de dos o más casas no lleva reason ni selected, y un conjunto de una sola casa no lleva meta.books en absoluto.

Cabeceras de RespuestaPermalink for this section

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

Respuestas de ErrorPermalink for this section

401 No Autorizado

Si no se envía ninguna clave se devuelve missing_api_key; una clave inválida devuelve 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 Plan Restringido

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

429 Límite de Tasa Superado

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

Esquema del Objeto OddsPermalink for this section

Tipos de selecciónPermalink for this section

selection_type lleva el identificador canónico de lado para cada selection. La mayoría de mercados son a dos vías (p. ej. moneyline, point spread, total) y emiten uno de los valores simples siguientes. Un pequeño conjunto de mercados multieje (doble oportunidad de fútbol, BTTS combinado, resultado × O/U, round betting de MMA, set betting de tenis, marcador exacto, etc.) codifica dos resultados por selección y emite valores compuestos unidos por _.

Filtrado por Rango de CuotasPermalink for this section

Usa min_odds y max_odds para filtrar por valor de cuotas americanas.

# Devolver solo cuotas en positivo (+100 y superiores)
curl "https://api.sharpapi.io/api/v1/odds?league=nba&min_odds=100" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Devolver solo cuotas entre -200 y +200
curl "https://api.sharpapi.io/api/v1/odds?league=nba&min_odds=-200&max_odds=200" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta Agrupada por EventoPermalink for this section

Usa group_by=event para agrupar las cuotas por evento en lugar de una lista plana. Esto es útil para construir interfaces centradas en 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"
  }
}

Acceso a Casas por PlanPermalink for this section

Las casas de apuestas incluidas en tus resultados de cuotas dependen de tu plan de suscripción:

Ejemplos de FiltradoPermalink for this section

# Obtener cuotas en directo de la NBA de todas tus casas disponibles
curl "https://api.sharpapi.io/api/v1/odds?league=nba&is_live=true" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Obtener cuotas moneyline y spread para un 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 las cuotas de spread de la NFL (usa next_cursor de cada respuesta)
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 - Obtén solo las cuotas que cambiaron desde una marca de tiempo dada
• Best Odds - Obtén las mejores cuotas de todas las casas para cada selección
• Odds Comparison - Compara cuotas entre casas lado a lado
• Batch Odds - Obtén cuotas para varios eventos en una sola solicitud
• Markets - Lista los tipos de mercado disponibles
• Sportsbooks - Lista las casas de apuestas disponibles y su estado