Les cotes des bookmakers italiens,
en une seule API

GET /api/v1/mock/odds sans clé

Chaque endpoint a un jumeau sous /api/v1/mock/ qui répond tout de suite, sans inscription et sans consommer de quota : même forme de réponse, mêmes paramètres, même validation stricte que le flux réel. Les cotes sont synthétiques — mock: true, en-tête X-Odss-Mock: 1, ids préfixés mock_ — elles servent à écrire et tester votre code, pas à parier.

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). Le paramètre seed rend la réponse reproductible : utilisez-le en CI plutôt que de brûler du quota à chaque exécution.

Sur le flux RÉEL, sont aussi publics sans clé /api/v1/leagues, /api/v1/coverage et /api/v1/status.

GET /api/v1/odds exemple

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

Les cotes cross-book actuelles, regroupées par événement, marché et ligne. Chaque enregistrement liste les bookmakers avec leurs issues et l'horodatage de leur dernière mise à jour.

Paramètres

Champs de la réponse

Pagination

Répétez l'appel en augmentant offset de returned, tant que offset + returned < count. Le programme est vivant : count peut varier légèrement entre les pages.

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

Les sports disponibles en ce moment dans le flux (les valeurs du paramètre sport).

GET /api/v1/bookmakers

Les bookmakers actifs dans le flux, avec country (code ISO 3166-1 alpha-2 du pays de licence — IT, GB, US, SE… — ou world lorsqu'il n'est pas attribué), playable_it (true uniquement pour les books titulaires d'une licence ADM italienne, donc jouables depuis l'Italie : false pour tous les autres books du flux, des références sharp comme Pinnacle aux marques étrangères), is_exchange (commission sur les gains) et source (direct si nous lisons le book nous-mêmes, partner_feed si sa cote nous parvient via un fournisseur de données tiers).

GET /api/v1/leagues public, sans clé

Le programme actuel agrégé : pour chaque sport, les ligues cotées, avec nombre d'événements et de bookmakers. Utile pour découvrir les valeurs du filtre league.

GET /api/v1/stream Pro et Enterprise

Server-Sent Events : un événement hello à la connexion, puis des événements odds avec les enregistrements MODIFIÉS (même schéma que /odds, chacun avec son state) et les supprimés, sous ~10 secondes après leur détection par le moteur — pas de polling. Paramètres optionnels sport et state (prematch|live|all) ; snapshot initial via GET /odds?state=…. La cadence des données reste celle du moteur (fraîcheur par book mesurée sur la status page ; bet365 via un fournisseur de données tiers sous licence contractuelle) : le stream supprime la latence de polling, last_update fait foi. Max 3 streams concurrents ; la connexion compte pour 1 requête de quota.

GET /api/v1/odds/history

Historique des variations de cote d'un événement : une ligne à chaque fois qu'un bookmaker bouge un prix sur un groupe. Filtres event_id (obligatoire), book, market, from/to (ISO), limit. Du plus récent : pour un événement commencé, la première ligne est sa clôture. Respecte la portée de la clé.

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 calculés sur le flux courant : OVER sur une ligne basse chez un book, UNDER sur une ligne haute chez un autre. Si le total tombe dans la fenêtre, les deux paris gagnent. Champs middle_window, hit_return_pct, miss_return_pct, safe (aucune perte même à côté). Filtres : sport, min_return, safe, limit.

Règle de fraîcheur : une cote figée depuis plus de stale_after_seconds (900s par défaut) reste dans les réponses de /odds avec son last_update, mais n'est jamais appariée dans un middle : une jambe périmée n'existe probablement plus chez le bookmaker. Le seuil appliqué et les jambes écartées figurent dans la réponse.

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

GET /api/v1/coverage public, sans clé

Combien de marques de bookmakers ont une cote valide dans le flux actuel, par région (Italie, USA, UK, monde). Ne correspond pas au nombre d'entrées de /api/v1/bookmakers : cet endpoint liste les clés interrogeables, où les lignes de marché dédiées (ex. <marque>-corners) comptent à part, alors qu'ici elles sont regroupées sous la marque.

POST /api/mcp MCP

Serveur MCP (JSON-RPC 2.0) pour agents IA et connecteurs (Claude, ChatGPT…). Auth avec la même clé (Authorization: Bearer odss_live_… ou x-api-key). Outils : get_odds (avec state=live), list_sports, list_bookmakers, list_leagues. Seul tools/call consomme du quota ; le handshake est gratuit. 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

Enregistrez une URL (https) depuis le tableau de bord ou via l'API — POST /api/account/webhooks avec la session compte (body {url, sport?, state?} ; le secret n'est montré qu'une fois, max 20 par compte) — et recevez les changements de cotes par POST — même payload {changed, removed} que le flux. Chaque livraison est signée : X-Odss-Signature: t=<unix>,v1=<hex> = HMAC-SHA256 de «{timestamp}.{body}» avec le secret (vérifiez-la, rejetez les vieux timestamps). https uniquement, pas de redirections ; les endpoints en échec se désactivent. Répondez 2xx. Une livraison peut arriver en plusieurs POST consécutifs, chacun signé séparément et numéroté par l'en-tête X-Odss-Page: page/total : chaque corps porte page, pages, changed_total et removed_total, la première page vous dit donc déjà combien arrive. Ne limitez pas la fréquence de l'endpoint : une page refusée arrête les suivantes.

Limites, en-têtes et erreurs

Chaque réponse authentifiée inclut X-RateLimit-Limit (quota mensuel du plan), X-RateLimit-Remaining et X-RateLimit-Reset (temps unix en secondes où la fenêtre se rouvre ; sur le 429 de quota la même date est dans le corps comme retry_at). Le quota est une fenêtre glissante de 30 jours.

Paramètres : aucun silence

Sur tous les endpoints /api/v1, un paramètre que nous ne reconnaissons pas n'est jamais ignoré : si vous écrivez bookmaker au lieu de bookmakers, vous recevez 400 avec le nom erroné, la liste de ceux admis sur cet endpoint et, s'il s'agit d'une faute de frappe, la suggestion du nom correct. La comparaison est exacte : même Sport avec une majuscule est rejeté. Les endpoints de catalogue (/sports, /bookmakers, /leagues, /coverage, /status) n'acceptent aucun paramètre. Nous préférons une erreur immédiate à une réponse 200 avec des données non filtrées qui semblent correctes : le 400 est déterministe, il doit être corrigé et non réessayé, et il ne consomme pas de quota.

La même règle s'applique aux arguments des outils du serveur MCP (POST /api/mcp) : un nom qui n'existe pas, ou un type erroné comme une liste au lieu de la chaîne CSV, reçoit une erreur JSON-RPC -32602 plutôt que d'être ignoré. Le champ error.data contient les noms admis, de sorte que l'agent se corrige tout seul.

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 · contrat & agents

Pour générer des clients, SDK ou utiliser l'API depuis un agent IA : le contrat OpenAPI 3.1 et un guide concis pour LLM sont publics et toujours synchronisés.

Licence d'utilisation

L'usage interne (modèles, bots, analyses, backtests) est inclus dans tous les plans. Redistribuer les données — p. ex. les afficher aux utilisateurs finaux de votre produit — exige la licence de Redistribution Display (option Enterprise, +120 €/mois), qui ne couvre que l'affichage. Créer, alimenter ou commercialiser des services de surebet/arbitrage, de value betting ou équivalents exige en revanche la Surebet API, le plan qui comprend la licence pour revendre les surebets calculées : 950 €/mois + TVA, depuis le site. Redistribuer l'API ou les données brutes reste hors de tout plan : pour cela, écrivez à [email protected].