Las cuotas de las casas italianas,
en una sola API

GET /api/v1/mock/odds sin clave

Cada endpoint tiene un gemelo bajo /api/v1/mock/ que responde ya, sin registrarte y sin consumir cuota: misma forma de respuesta, mismos parámetros, misma validación estricta que el feed real. Los precios son sintéticos — mock: true, cabecera X-Odss-Mock: 1, ids con prefijo mock_ — sirven para escribir y probar tu código, no para apostar.

curl "https://odss-api.com/api/v1/mock/odds?sport=calcio&limit=3"

Disponibles: /mock/odds · /mock/odds/history · /mock/sports · /mock/bookmakers · /mock/leagues · /mock/status · /mock/stream (SSE). El parámetro seed hace la respuesta reproducible: úsalo en CI en vez de gastar cuota en cada ejecución.

En el feed REAL también son públicos sin clave /api/v1/leagues, /api/v1/coverage y /api/v1/status.

GET /api/v1/odds ejemplo

curl "https://odss-api.com/api/v1/odds?sport=calcio&league=serie%20a&limit=5" \
  -H "x-api-key: odss_live_..."

const r = await fetch(
  "https://odss-api.com/api/v1/odds?sport=calcio&league=serie%20a&limit=5",
  { headers: { "x-api-key": "odss_live_..." } }
);
const { count, odds } = await r.json();

import requests
r = requests.get(
    "https://odss-api.com/api/v1/odds",
    params={"sport": "calcio", "league": "serie a", "limit": 5},
    headers={"x-api-key": "odss_live_..."},
)
data = r.json()  # { count, offset, returned, state, odds: [...] }

GET /api/v1/odds

Las cuotas cross-book actuales, agrupadas por evento, mercado y línea. Cada registro lista las casas con sus resultados y el timestamp de su última actualización.

Parámetros

Campos de la respuesta

Paginación

Repite la llamada aumentando offset en returned, mientras offset + returned < count. El tablero está vivo: count puede variar ligeramente entre páginas.

GET /api/v1/odds?sport=calcio&limit=1000&offset=0
GET /api/v1/odds?sport=calcio&limit=1000&offset=1000
# … finché offset + returned < count

GET /api/v1/sports

Los deportes disponibles ahora mismo en el feed (los valores del parámetro sport).

GET /api/v1/bookmakers

Las casas activas en el feed, con country (código ISO 3166-1 alpha-2 del país de licencia — IT, GB, US, SE… — o world cuando no está atribuido), playable_it (true solo para las casas con licencia ADM italiana, es decir jugables desde Italia: false para todas las demás del feed, desde referencias sharp como Pinnacle hasta las marcas extranjeras), is_exchange (comisión sobre la ganancia) y source (direct si leemos la casa nosotros, partner_feed si su listado nos llega de un proveedor de datos externo).

GET /api/v1/leagues público, sin clave

El calendario actual agregado: para cada deporte las ligas cotizadas, con número de eventos y de casas. Útil para descubrir valores del filtro league.

GET /api/v1/stream Pro y Enterprise

Server-Sent Events: un evento hello al conectar, luego eventos odds con los registros CAMBIADOS (mismo esquema que /odds, cada uno con su state) y los eliminados, en un máximo de ~10 segundos desde que el motor los detecta — sin polling. Parámetros opcionales sport y state (prematch|live|all); snapshot inicial vía GET /odds?state=…. La cadencia de los datos sigue siendo la del motor (frescura por casa medida en la status page; bet365 vía un proveedor de datos externo con licencia contractual): el stream elimina la latencia de polling, manda last_update. Máx. 3 streams concurrentes; la conexión cuenta como 1 petición de cuota.

GET /api/v1/odds/history

Histórico de cambios de cuota de un evento: una fila cada vez que una casa mueve un precio en un grupo. Filtros event_id (obligatorio), book, market, from/to (ISO), limit. Del más reciente: en un evento ya empezado la primera fila es su cierre. Respeta el ámbito de la clave.

curl "https://odss-api.com/api/v1/odds/history?event_id=a3f9c1e07b2d4865&book=snai" \
  -H "x-api-key: odss_live_..."

GET /api/v1/middles

Middles Over/Under calculados del feed actual: OVER en una línea baja en una casa, UNDER en una línea alta en otra. Si el total cae en la ventana ganan ambas apuestas. Campos middle_window, hit_return_pct, miss_return_pct, safe (sin pérdida ni fallando). Filtros: sport, min_return, safe, limit.

Regla de frescura: una cuota parada más de stale_after_seconds (900s por defecto) sigue en las respuestas de /odds con su last_update, pero no se empareja en un middle: una pata vieja probablemente ya no existe en la web de la casa. El umbral aplicado y las patas descartadas están en la respuesta.

curl "https://odss-api.com/api/v1/middles?sport=calcio&safe=true" \
  -H "x-api-key: odss_live_..."

GET /api/v1/coverage público, sin clave

Cuántas marcas de casas tienen una cuota válida en el feed de este momento, por región (Italia, USA, UK, mundo). No coincide con el número de entradas de /api/v1/bookmakers: allí se listan las claves consultables y las líneas de mercado dedicadas (p. ej. <marca>-corners) cuentan por separado, mientras que aquí se agrupan bajo la marca.

POST /api/mcp MCP

Servidor MCP (JSON-RPC 2.0) para agentes IA y conectores (Claude, ChatGPT…). Autenticación con la misma clave (Authorization: Bearer odss_live_… o x-api-key). Herramientas: get_odds (con state=live), list_sports, list_bookmakers, list_leagues. Solo tools/call consume cuota; el handshake es gratis. Stateless.

curl -X POST https://odss-api.com/api/mcp \
  -H "Authorization: Bearer odss_live_..." -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_odds","arguments":{"sport":"calcio","state":"live","limit":5}}}'

Webhook Enterprise

Registra una URL (https) desde el panel o vía API — POST /api/account/webhooks con la sesión de cuenta (body {url, sport?, state?}; el secret se muestra una vez, máx. 20 por cuenta) — y recibe los cambios de cuota por POST — mismo payload {changed, removed} que el stream. Cada entrega va firmada: X-Odss-Signature: t=<unix>,v1=<hex> = HMAC-SHA256 de «{timestamp}.{body}» con el secreto (verifícala, rechaza timestamps viejos). Solo https, sin redirecciones; los endpoints que fallan se autodesactivan. Responde 2xx. Una entrega puede llegar en varios POST consecutivos, cada uno firmado por separado y numerado por la cabecera X-Odss-Page: página/total: cada cuerpo lleva page, pages, changed_total y removed_total, así desde la primera página ya sabes cuánto está llegando. No limites la frecuencia del endpoint: una página rechazada detiene las siguientes.

Límites, cabeceras y errores

Cada respuesta autenticada incluye X-RateLimit-Limit (cuota mensual del plan), X-RateLimit-Remaining y X-RateLimit-Reset (unix time en segundos en que la ventana se reabre; en el 429 por cuota la misma fecha está en el cuerpo como retry_at). La cuota es una ventana móvil de 30 días.

Parámetros: sin silencios

En todos los endpoints /api/v1, un parámetro que no reconocemos no se ignora nunca: si escribes bookmaker en lugar de bookmakers recibes 400 con el nombre equivocado, la lista de los admitidos en ese endpoint y, si es una errata, la sugerencia del nombre correcto. La comparación es exacta: incluso Sport con mayúscula inicial se rechaza. Los endpoints de catálogo (/sports, /bookmakers, /leagues, /coverage, /status) no aceptan ningún parámetro. Preferimos un error inmediato a una respuesta 200 con datos sin filtrar que parecen correctos: el 400 es determinista, hay que corregirlo y no reintentarlo, y no consume cuota.

La misma regla vale para los argumentos de las herramientas del servidor MCP (POST /api/mcp): un nombre que no existe, o un tipo equivocado como una lista en lugar de la cadena CSV, recibe un error JSON-RPC -32602 en vez de ignorarse. El campo error.data incluye los nombres admitidos, así el agente se corrige solo.

curl "https://odss-api.com/api/v1/odds?bookmaker=snai" -H "x-api-key: odss_live_..."

HTTP/1.1 400 Bad Request
{
  "error": "Parametro sconosciuto: \"bookmaker\" (forse intendevi \"bookmakers\"?). Ammessi su questo endpoint: bookmakers, content, event_id, league, limit, market, offset, player, sport, state"
}

Machine-readable · contrato y agentes

Para generar clientes, SDKs o usar la API desde un agente IA: el contrato OpenAPI 3.1 y una guía breve para LLM son públicos y siempre sincronizados.

Licencia de uso

El uso interno (modelos, bots, análisis, backtests) está incluido en todos los planes. Redistribuir los datos — p. ej. mostrarlos a los usuarios finales de tu producto — requiere la licencia de Redistribución Display (complemento Enterprise, +120 €/mes), que cubre solo la visualización. Crear, alimentar o comercializar servicios de surebet/arbitraje, de value betting o equivalentes exige en cambio la Surebet API, el plan que incluye la licencia para revender las surebets calculadas: 950 €/mes + IVA, desde la web. Redistribuir la API o los datos brutos queda fuera de todos los planes: para eso, escribe a [email protected].