Le quote dei bookmaker ADM, esteri ed exchange 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) · /mock/ticker (un frame di quote 1X2 d'esempio ogni 5 s, senza parametri). 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, /api/v1/status e /api/v1/pulse.

Prima chiamata in 3 passi

1. Crea la chiave Registrati e genera una chiave nella dashboard. Il piano Free è per sempre.
2. Elenca gli sport Verifica la chiave con una chiamata a /sports.
3. Chiedi le quote Chiama /odds con sport e mercato: ricevi le quote cross-book.

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, ognuno con questi campi.

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: arrivano solo i record cambiati e quelli rimossi, niente polling. Con state=live il live arriva di solito in 10-30 secondi (mediana misurata circa 15 s). Limite di oggi, misurato l'8 ottobre 2026: con state=all un giro pre-partita completo pesa centinaia di MB e la connessione cade prima di riceverlo; lo stream è rimasto senza variazioni il 79% del tempo, con un resync ogni 12 minuti circa. Il pre-partita arriva solo con filtri stretti (sport, mercato, lega), a ondate, quando si rinnova lo snapshot servito. Stiamo riscrivendo la consegna a pagine piccole con contropressione; fino ad allora, per tutto il pre-partita usa lo snapshot paginato di /odds.

GET /api/v1/odds/history

Non ancora attivo. Oggi la cattura è spenta: ogni chiamata risponde 200 con count: 0 e history_enabled: false, e conta nella quota. Quando sarà attivo: 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.

Limiti di safe, oggi: alcune famiglie di mercato non sono ancora separate per unità (nel tennis e nel volley un totale di set può finire accanto a un totale di game o di punti), alcuni pseudo-eventi «Home - Away» di una piattaforma sono serviti come partite, e due partite omonime possono condividere un event_id. In questi casi safe: true non è un middle vero: prima di agire controlla che le due gambe siano la stessa partita, la stessa unità e lo stesso orario. La risposta lo ricorda nel campo safe_note.

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). Coincide con le voci di /api/v1/bookmakers: entrambi contano un operatore una volta sola, con le corsie di mercato dedicate (es. <marchio>-corners) sotto il marchio; in /bookmakers le chiavi con cui le sue quote escono stanno in feed_keys.

GET /api/v1/coverage/matrix pubblico, senza chiave

Per ogni bookmaker, sport per sport: i mercati normalizzati che quota adesso, con le linee viste. Serve a distinguere tre cose che un elenco piatto confonde.

Un mercato non elencato sotto un operatore attivo è un'assenza strutturale: non lo quota, e domani sarà uguale. Gli operatori in live_only_bookmakers hanno righe ma non nel prematch, quindi sui loro mercati prematch la risposta non dice nulla; se una corsia del feed non ha risposto, incomplete_lanes la nomina e la copertura è parziale, non assente.

E un mercato che il motore non sa mappare con certezza non viene indovinato: esce come other:<etichetta> e qui viene solo contato (other_markets), perché due book lo chiamano in modi diversi e confrontare quelle etichette sarebbe sbagliato — quelle che molti book scrivono uguale stanno in other_markets_common. Ambito prematch, ricalcolata al massimo ogni 10 minuti (generated_at).

GET /api/v1/pulse pubblico, senza chiave

Il battito del feed, solo numeri aggregati (niente prezzi, niente nomi di book): è ciò che interrogano da sole le pagine di questo sito. Nessun parametro, Cache-Control: public, max-age=5, limite per IP a sé (60 al minuto).

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 è gratis. Stateless: 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 e ricevi le variazioni di quota via POST, con lo stesso payload {changed, removed} dello stream.

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 vale per una finestra di 30 giorni che parte dalla prima richiesta del periodo: alla scadenza il contatore si azzera e riparte con la richiesta successiva.

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: after, bookmakers, changed_since, commence_from, commence_to, content, country, event_id, format, league, limit, market, offset, playable_it, player, sport, state"
}

Risorse per macchine e 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. Ridistribuire le API o i dati grezzi resta fuori da ogni piano: per quello scrivici a [email protected].