Le quote dei bookmaker italiani,
in un'unica API

GET /api/v1/mock/odds senza chiave

Ogni endpoint ha un gemello sotto /api/v1/mock/ che risponde subito, senza registrarti e senza consumare quota: stessa forma della risposta, stessi parametri, stessa validazione stretta del feed vero. I prezzi sono sintetici — mock: true, header X-Odss-Mock: 1, id con prefisso mock_ — servono a scrivere e collaudare il codice, non a giocarci.

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

Disponibili: /mock/odds · /mock/odds/history · /mock/sports · /mock/bookmakers · /mock/leagues · /mock/status · /mock/stream (SSE). Il parametro seed rende la risposta riproducibile: usalo nella CI invece di bruciare quota a ogni run.

Sul feed VERO sono pubblici senza chiave anche /api/v1/leagues, /api/v1/coverage e /api/v1/status.

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 (codice ISO 3166-1 alpha-2 del paese di licenza — IT, GB, US, SE… — oppure world quando non è attribuito), playable_it (true solo per i book con concessione ADM, cioè giocabili dall'Italia: false per tutti gli altri book del feed, dalle sharp di riferimento come Pinnacle ai marchi esteri), is_exchange (commissione sulla vincita) e source (direct se leggiamo noi il book, partner_feed se il listino ci arriva da un fornitore di dati terzo).

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 Pro ed 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 via un fornitore di dati terzo su licenza contrattuale): 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/odds/history

Storico delle variazioni di quota per un evento: una riga ogni volta che un bookmaker cambia prezzo su un gruppo. Filtri event_id (obbligatorio), book, market, from/to (ISO), limit. Ordine dal più recente: la prima riga di un evento iniziato è la sua chiusura. Rispetta l'ambito della chiave.

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

GET /api/v1/middles

Middle Over/Under calcolati dal feed corrente: OVER su una linea bassa da un book, UNDER su una linea alta da un altro. Se il totale cade nella finestra vincono entrambe le giocate. Campi middle_window, hit_return_pct, miss_return_pct, safe (nessuna perdita nemmeno a vuoto). Filtri: sport, min_return, safe, limit.

Regola di freschezza: una quota ferma da più di stale_after_seconds (900s di default) resta nelle risposte di /odds col suo last_update, ma non viene accoppiata in un middle: una gamba vecchia probabilmente non esiste più sul sito del bookmaker. La soglia applicata e il numero di gambe scartate sono nella risposta.

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

GET /api/v1/coverage pubblico, senza chiave

Quanti marchi di bookmaker hanno una quota valida nel feed di questo momento, per regione (Italia, USA, UK, mondo). Non coincide con il numero di voci di /api/v1/bookmakers: là sono elencate le chiavi interrogabili e le corsie di mercato dedicate (es. <marchio>-corners) contano a sé, qui vengono accorpate sotto il marchio.

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. Una consegna può arrivare in più POST consecutivi, ognuno firmato per conto suo e numerato dall'header X-Odss-Page: pagina/totale: ogni corpo porta page, pages, changed_total e removed_total, così dalla prima pagina sai già quanto sta arrivando. Non limitare la frequenza dell'endpoint: una pagina rifiutata ferma le successive.

Limiti, header ed errori

Ogni risposta autenticata include X-RateLimit-Limit (quota mensile del piano), X-RateLimit-Remaining e X-RateLimit-Reset (unix time in secondi in cui la finestra si riapre; sul 429 da quota la stessa data è nel corpo come retry_at). La quota è una finestra mobile di 30 giorni.

Parametri: nessun silenzio

Su tutti gli endpoint /api/v1 un parametro che non riconosciamo non viene mai ignorato: se scrivi bookmaker invece di bookmakers ricevi 400 con il nome sbagliato, l'elenco di quelli ammessi su quell'endpoint e, se è un refuso, il suggerimento del nome giusto. Il confronto è esatto: anche Sport con la maiuscola viene rifiutato. Gli endpoint di catalogo (/sports, /bookmakers, /leagues, /coverage, /status) non accettano alcun parametro. Preferiamo un errore subito a una risposta 200 con dati non filtrati che sembrano corretti: il 400 è deterministico, va corretto e non ritentato, e non consuma quota.

La stessa regola vale per gli argomenti dei tool del server MCP (POST /api/mcp): un nome che non esiste, o un tipo sbagliato come una lista al posto della stringa CSV, riceve un errore JSON-RPC -32602 invece di essere ignorato. Il campo error.data porta i nomi ammessi, così l'agente si corregge da 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 · 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 la licenza di Redistribuzione Display (add-on Enterprise, +€120/mese), che copre la sola visualizzazione. Creare, alimentare o commercializzare servizi di surebet/arbitraggio, di value betting o equivalenti richiede invece la Surebet API, il piano che include la licenza per rivendere le surebet calcolate: 950 €/mese + IVA, dal sito. Ridistribuire le API o i dati grezzi resta fuori da ogni piano: per quello scrivici a [email protected].