Le quote sportive
in un'unica API

GET /api/v1/odds esempio

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

Le quote cross-book correnti, raggruppate per evento, mercato e linea. Ogni record elenca i bookmaker con i loro esiti e il timestamp dell'ultimo aggiornamento.

Parametri

Campi della risposta

Paginazione

Ripeti la chiamata aumentando offset di returned, finché offset + returned < count. Il palinsesto è vivo: count può variare leggermente tra le pagine.

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

Gli sport disponibili in questo momento nel feed (i valori del parametro sport).

GET /api/v1/bookmakers

I bookmaker attivi nel feed, con country, playable_it (false per le sharp di riferimento come Pinnacle) e is_exchange (commissione sulla vincita).

GET /api/v1/leagues pubblico, senza chiave

Il palinsesto corrente aggregato: per ogni sport le leghe quotate, con numero di eventi e di bookmaker. Utile per scoprire i valori del filtro league.

GET /api/v1/stream Enterprise

Server-Sent Events: alla connessione un evento hello, poi eventi odds con i record CAMBIATI (stesso schema di /odds) e i rimossi, entro ~10 secondi da quando il motore li rileva — niente polling. Parametro opzionale sport; snapshot iniziale via GET /odds. La cadenza dei dati resta quella del motore (freschezza per book misurata sulla status page; bet365/Betfair via feed partner): lo stream elimina la latenza di polling, fa fede last_update. Max 3 stream concorrenti; la connessione conta 1 richiesta di quota.

GET /api/v1/coverage pubblico, senza chiave

Conteggio dei bookmaker coperti per regione (Italia, USA, UK, mondo).

POST /api/mcp MCP

Server MCP (JSON-RPC 2.0) per agenti AI e connettori (Claude, ChatGPT…). Autenticazione con la stessa chiave (Authorization: Bearer odss_live_… o x-api-key). Tool: get_odds (con state=live), list_sports, list_bookmakers, list_leagues. Solo tools/call consuma quota; l'handshake (initialize/tools/list) è gratis. Stateless: nessuna sessione, ogni richiesta è autosufficiente.

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) dalla dashboard o via API — POST /api/account/webhooks con la sessione account (body {url, sport?, state?}; il secret è mostrato una volta, max 20 per account) — e ricevi le variazioni di quota via POST: stesso payload {changed, removed} dello stream. Ogni consegna è firmata: header X-Odss-Signature: t=<unix>,v1=<hex> = HMAC-SHA256 di "{timestamp}.{body}" col secret del webhook (verifica la firma e rifiuta timestamp vecchi). Solo https, niente redirect seguiti; endpoint che falliscono a ripetizione si auto-disabilitano. Rispondi 2xx per confermare.

Limiti, header ed errori

Ogni risposta autenticata include X-RateLimit-Limit (quota mensile del piano) e X-RateLimit-Remaining. La quota è una finestra mobile di 30 giorni.

Machine-readable · contratto & agenti

Per generare client, SDK o usare l'API da un agente AI: il contratto OpenAPI 3.1 e una guida sintetica per LLM sono pubblici e sempre allineati.

Licenza d'uso

L'uso interno (modelli, bot, analisi, backtest) è incluso in tutti i piani. La ridistribuzione dei dati — ad esempio mostrarli agli utenti finali di un tuo prodotto — richiede un'autorizzazione scritta: scrivici a [email protected] e definiamo una licenza adatta al tuo caso.