Introduction

SmatchONE Odds est un fournisseur de données sportives : cotes pregame et live, résultats et scores en direct, issus de notre back office d'agrégation. L'API expose un schéma stable versionné v1. Chaque ressource est normalisée et accompagnée d'une enveloppe de traçabilité _provenance.

Format : JSON UTF-8. Cotes en format décimal. Dates en ISO 8601. Les horodatages de match (startsAt) sont exprimés dans le fuseau configuré pour votre compte (par défaut heure du Cameroun, UTC+1) ; les horodatages techniques (_provenance.fetchedAt) restent en UTC. Voir la section Fuseaux horaires.

Base URL & Authentification

Base URL : https://real-odds-api-production.up.railway.app

Toutes les routes /agd/v1/* exigent un header :
  Authorization: Bearer <token-fourni-à-l-onboarding>

La route /health est ouverte (pas de token).

Le token est remis lors de l'onboarding. Ne le partagez pas côté client.

curl -H "Authorization: Bearer <token-fourni-à-l-onboarding>" \
  "https://real-odds-api-production.up.railway.app/agd/v1/fixtures?status=LIVE&limit=50"

Fuseaux horaires

Les horodatages de match (champ startsAt des fixtures) sont émis en ISO 8601 avec offset de fuseau — le fuseau configuré pour votre compte, par défaut l'heure du Cameroun (Africa/Douala, UTC+1).

"startsAt": "2026-06-26T18:55:00+01:00"   // 18h55 heure du Cameroun
// = exactement le même instant que "2026-06-26T17:55:00Z" (UTC)

C'est le même instantqu'en UTC, simplement exprimé dans le fuseau de votre compte. Un parseur ISO 8601 standard (datetime()) accepte indifféremment le suffixe Z ou l'offset ±HH:MM : aucun changement de code requis côté intégration.

À retenir : seuls les horodatages de match sont exprimés dans votre fuseau. Les horodatages techniques — notamment _provenance.fetchedAt — restent toujours en UTC (suffixe Z).

Enveloppe _provenance

Chaque objet renvoyé porte un champ _provenance décrivant l'origine de la donnée, sa fraîcheur et ses éventuelles lacunes.

"_provenance": {
  "source": "the-odds-api",          // fournisseur d'origine
  "fetchedAt": "2026-06-26T19:31:21Z", // horodatage de récupération (UTC)
  "rawId": "3",                       // identifiant brut côté source
  "missing": ["logoUrl"],             // champs absents dans la source
  "warnings": [],                     // alertes de normalisation
  "schemaVersion": "v1"               // version du schéma
}

Sports

GET https://real-odds-api-production.up.railway.app/agd/v1/sports

[
  {
    "id": "football",
    "key": "football",
    "name": "Football",
    "isActive": true,
    "_provenance": { "source": "the-odds-api", "fetchedAt": "2026-06-26T19:31:21Z",
                     "rawId": "3", "missing": [], "warnings": [], "schemaVersion": "v1" }
  }
]

Ligues

GET https://real-odds-api-production.up.railway.app/agd/v1/leagues?limit=1000

[
  {
    "id": "4033",
    "sportId": "football",
    "countryId": null,
    "name": "Kategoria Superiore",
    "season": "2026",
    "type": "league",
    "logoUrl": null,
    "_provenance": { "source": "the-odds-api", "rawId": "4033", "missing": ["countryId","logoUrl"],
                     "warnings": [], "schemaVersion": "v1" }
  }
]

Équipes

GET https://real-odds-api-production.up.railway.app/agd/v1/teams?limit=1000

[
  {
    "id": "aj-deem",
    "name": "AJ Deem",
    "countryId": null,
    "logoUrl": null,
    "founded": null,
    "venue": null,
    "_provenance": { "source": "the-odds-api", "rawId": "aj-deem", "schemaVersion": "v1" }
  }
]

Matchs & Résultats

Les matchs sont filtrables par statut. Un résultat est simplement un match au statut FINISHED avec ses scores (homeScore / awayScore).

Coup d'envoi. startsAt est un ISO 8601 avec offset de fuseau (ex. 2026-06-26T18:55:00+01:00), correspondant au fuseau configuré pour votre compte (par défaut heure du Cameroun, UTC+1). C'est le même instant qu'en UTC — voir Fuseaux horaires.

Statut fiable. Le champ status n'est pas le statut brut du bookmaker (qui reste figé sur « live »). Il est recalculé à partir de plusieurs signaux réels, par ordre de fiabilité :

• SCHEDULED— le coup d'envoi (startsAt) n'a pas encore eu lieu.
• FINISHED— dès qu'un de ces signaux est vrai : résultat final reçu (score FT), ou tous les marchés du match sont fermés (plus aucun pari possible), ou match commencé depuis plus de 4 h (garde-fou). Un match terminé est immédiatement settlable.
• LIVE — match commencé, dans la fenêtre de jeu, avec au moins un marché encore ouvert. Un matchLIVE est réellement en cours (il ne reste jamais « live » des heures après la fin).
• CANCELLED / POSTPONED / PAUSED — match annulé/abandonné, reporté, ou interrompu temporairement. Émis dès que le bookmaker le signale, pour que tu puisses annuler/suspendre les tickets concernés.

Scores mi-temps. homeHalftimeScore / awayHalftimeScore sont renseignés quand la donnée mi-temps est disponible. Sinon ils valent null et apparaissent dans _provenance.missing.

GET https://real-odds-api-production.up.railway.app/agd/v1/fixtures?status=LIVE|SCHEDULED|FINISHED&limit=100
GET https://real-odds-api-production.up.railway.app/agd/v1/fixtures/{id}

{
  "id": "5541815",
  "leagueId": "43221",
  "homeTeamId": "aj-deem",
  "awayTeamId": "boland-brendan",
  "startsAt": "2026-06-26T18:55:00+01:00",  // fuseau du compte (déf. UTC+1) = 17:55:00Z
  "status": "FINISHED",
  "season": "2026",
  "homeTeamName": "AJ Deem",
  "awayTeamName": "Boland, Brendan",
  "leagueName": "UTR PTT Waco Men 01",
  "homeScore": 2,
  "awayScore": 1,
  "homeHalftimeScore": 1,        // renseigné si la mi-temps est connue, sinon null
  "awayHalftimeScore": 0,
  "_provenance": { "source": "the-odds-api", "rawId": "5541815",
                   "missing": [], "schemaVersion": "v1" }
}

Exemple sans mi-temps disponible : homeHalftimeScore / awayHalftimeScore à null, listés dans _provenance.missing :

{
  "id": "5541900",
  "status": "FINISHED",
  "homeScore": 3,
  "awayScore": 2,
  "homeHalftimeScore": null,
  "awayHalftimeScore": null,
  "_provenance": { "source": "the-odds-api", "rawId": "5541900",
                   "missing": ["homeHalftimeScore", "awayHalftimeScore"],
                   "schemaVersion": "v1" }
}

Cotes (pregame + live)

Les cotes sont regroupées par marché (clés canoniques) puis par sélection. Clés canoniques courantes : match-winner, over-under-X, both-teams-score, double-chance, asian-handicap.

GET https://real-odds-api-production.up.railway.app/agd/v1/odds/{id}

{
  "fixtureId": "5541815",
  "bookmakerId": "betconstruct",
  "markets": [
    {
      "key": "winner-of-the-match",
      "name": "Winner of the match",
      "status": "OPEN",
      "description": { "fr": "Résultat final : 1 = domicile · X = nul · 2 = extérieur.", "en": "Final result: 1 = home · X = draw · 2 = away." },
      "margin": 15.0,
      "selections": [
        { "key": "home", "label": "AJ Deem",        "decimalOdds": 2.1275, "line": null, "status": "ACTIVE" },
        { "key": "away", "label": "Boland, Brendan", "decimalOdds": 2.2425, "line": null, "status": "ACTIVE" }
      ]
    }
  ],
  "_provenance": { "source": "the-odds-api", "schemaVersion": "v1" }
}

Livescore

GET https://real-odds-api-production.up.railway.app/agd/v1/livescore/{id}

Renvoie le score en direct quand disponible, sinon { "detail": "no livescore for fixture" }.

Scores par période. periodScores est rempli quand l'information de période existe : un tableau de { period, home, away } où home / away sont les points marqués dans cette période (non cumulés). Valeurs possibles de period : 1H, 2H, HT (foot), Q1…Q4 (basket), S1…S5 (tennis). Le champ period(période courante) est renseigné s'il est connu.

{
  "fixtureId": "5541815",
  "homeScore": 1,
  "awayScore": 0,
  "minute": 34,
  "period": "2H",                 // période courante si connue, sinon null
  "periodScores": [               // rempli si l'info de période existe, sinon []
    { "period": "1H", "home": 1, "away": 0 },
    { "period": "2H", "home": 0, "away": 0 }
  ],
  "_provenance": { "source": "the-odds-api", "schemaVersion": "v1" }
}

WebSocket temps réel — /agd/v1/ws

UNE seule connexion WebSocket pousse tout en temps réel — cotes, livescore, minute, statut. Aucun GET REST nécessaire pour le temps réel. Le SSE /stream et les GET REST restent disponibles en parallèle (migration).

wss://real-odds-api-production.up.railway.app/agd/v1/ws

Auth : le même token Bearer, au choix — header Authorization: Bearer <token>sur l'upgrade, OU sous-protocole agd.v1.bearer.<token>. Une seule connexion par instance suffit (pas de connexion par match).

1) Abonnement (client → serveur)

{ "type": "subscribe",
  "channels": ["odds", "livescore", "fixture"],
  "filter": { "sport": "football" } }

channels : omettez pour tout recevoir. filter.sport : optionnel.

2) Snapshot puis flux (serveur → client)

Juste après l'ack, on burst l'état completde tous les matchs de l'abonnement, puis on passe au flux live. 0 appel REST pour être cohérent au démarrage (idem à la reconnexion).

{ "type": "subscribed", "channels": [...], "snapshotStart": true }
… odds.update / livescore.update / fixture.update (état courant) …
{ "type": "snapshotEnd" }
… flux live …

3) Règles de continuité

• On ne retire JAMAIS une entrée (marché / sélection / match) avant que le match soit FINISHED. Un marché qui cesse d'être coté passe à status: "NO_QUOTE" (les dernières cotes restent). OPEN = on price activement.
• État COMPLET à chaque event (pas de delta) : écrasez votre cache pour ce fixtureId.

4) Payloads

{ "type": "odds.update", "at": "2026-07-02T13:04:12.245Z",
  "fixtureId": "5546570", "bookmakerId": "betconstruct",
  "markets": [ { "key": "match-winner", "name": "FT 1X2", "status": "OPEN",
    "selections": [
      { "key": "home", "label": "1", "decimalOdds": 3.12, "line": null, "status": "ACTIVE" },
      { "key": "draw", "label": "X", "decimalOdds": 4.46, "line": null, "status": "ACTIVE" },
      { "key": "away", "label": "2", "decimalOdds": 2.20, "line": null, "status": "ACTIVE" } ] } ] }

{ "type": "livescore.update", "at": "2026-07-02T13:47:03.500Z",
  "fixtureId": "5546570", "scoreHome": 1, "scoreAway": 0,
  "elapsed": 47, "period": "2H", "status": "LIVE" }

{ "type": "fixture.update", "at": "2026-07-02T15:32:00.000Z",
  "fixtureId": "5546570", "status": "FINISHED",
  "homeScore": 2, "awayScore": 1, "startsAt": "2026-07-02T13:00:00.000Z" }

Livescore : poussé à chaque changement de minute + heartbeat ~15 s en live (on continue de pousser pendant la mi-temps HT/BT avec la période figée, sans incrémenter elapsed). Pas d'event > 30 s = flux mort. On s'arrête à FINISHED. Périodes CANONIQUES : 1H HT 2H BT ET AET AP PEN FT FINISHED (foot ; non-foot inchangé).

5) Keep-alive, erreurs, reconnexion

Le serveur envoie { "type": "ping" } (~20 s) si pas d'autre trafic. Erreurs : { "type": "error", "code": "…", "message": "…" } (AUTH_EXPIRED, AUTH_INVALID, RATE_LIMITED, INTERNAL). À la reconnexion (backoff exponentiel), le snapshotre-livre l'état complet — vous ne perdez aucun match. Le rejeu par sincepourra être ajouté ultérieurement (le snapshot le couvre pour l'instant).

Limites & honnêteté des données

Pour éviter toute mauvaise surprise côté intégration, voici ce que la source (le BO BetConstruct de ce compte) n'expose pas, et que nous ne fournissons donc pas :

• Pas d'events détaillés : buts, cartons, remplacements, VAR. (Aucune route match-events.)
• Pas de compositions (lineups) ni de statistiques de match.
• Pas de settlement par sélection fourni par notre API.

Le settlement côté AGDTech se base donc sur : les scores finaux (FT), les scores mi-temps (HT, si disponibles) et les scores par période (periodScores, si disponibles).

Cadence de polling recommandée

Doc interactive auto-générée : https://real-odds-api-production.up.railway.app/redoc

Historique des mises à jour

Chaque modification de l'API est consignée ici. La dernière version est en tête. La date la plus récente apparaît en rouge en haut de page.