Aller au contenu principal

Glossaire

Un référentiel complet des termes clés et concepts utilisés dans l'ensemble de l'API de marché de prédiction.

Concepts fondamentaux​

Marché​

Un marché de prédiction représente une question portant sur un événement futur avec un ensemble défini de résultats possibles. Les marchés traversent un cycle de vie allant de la création au règlement. Exemples : "Pleuvra-t-il demain ?", "Quelle équipe gagne la finale ?"

Résultat​

Un résultat est l'une des issues possibles d'un marché. Chaque marché comporte deux résultats ou plus. Pour un marché binaire comme "Le Bitcoin atteindra-t-il 100 000 $ ?", les résultats seraient "Oui" et "Non". Les parts sont achetées et vendues par résultat.

Opérateur​

Un opérateur est une entité commerciale enregistrée qui s'intègre à la plateforme de marché de prédiction. Les opérateurs gèrent leurs propres joueurs, sessions et portefeuilles. Chaque opérateur dispose d'une clé API unique pour l'authentification. Toutes les données (marchés, ordres, positions) sont limitées à l'opérateur.

Joueur​

Un joueur est un utilisateur final de la plateforme d'un opérateur. Les joueurs sont identifiés par une chaîne playerId que l'opérateur fournit lors du passage des ordres. Le moteur de prédiction stocke cet identifiant sur les ordres, mais ne gère pas les comptes des joueurs — c'est la responsabilité de l'opérateur.

Concepts de trading​

Ordre​

Une instruction d'achat ou de vente de parts d'un résultat spécifique. Un ordre précise le résultat, la direction (achat/vente), la quantité (parts) et optionnellement une limite de prix. Les ordres sont soumis par les opérateurs pour le compte de leurs joueurs.

Sens de l'ordre​

La direction d'un ordre :

  • BUY — Acquérir des parts d'un résultat. Vous réalisez un bénéfice si le résultat gagne.
  • SELL — Céder des parts que vous détenez déjà. Vous cristallisez votre profit ou perte actuel.

Type d'ordre​

La façon dont l'ordre doit être exécuté :

  • LIMIT — Exécuter uniquement au prix spécifié ou mieux. Si aucun ordre correspondant n'existe à votre prix, l'ordre reste dans le carnet d'ordres jusqu'à ce qu'il soit apparié ou annulé.
  • MARKET — Exécuter immédiatement au meilleur prix disponible. Les ordres au marché sont exécutés contre les ordres à cours limité existants dans le carnet. En cas de liquidité insuffisante, l'ordre peut être partiellement exécuté ou rejeté.

Parts​

L'unité de trading dans un marché de prédiction. Chaque part représente une créance sur une unité de paiement si le résultat associé gagne. Par exemple, acheter 100 parts de "Oui" à 0,60 $ signifie payer 60 $ et recevoir 100 $ si "Oui" gagne, ou 0 $ en cas de perte.

Prix​

Le coût par part, exprimé en valeur comprise entre 0.01 et 0.99. Le prix reflète la probabilité implicite du marché que le résultat se produise. Un prix de 0.65 implique une probabilité de 65 %. Les prix sont requis pour les ordres à cours limité.

Écart​

La différence entre la meilleure offre de vente (prix de vente le plus bas) et la meilleure offre d'achat (prix d'achat le plus élevé). Un écart plus faible indique un marché plus liquide. Par exemple, si la meilleure offre d'achat est 0.63 et la meilleure offre de vente est 0.67, l'écart est de 0.04.

Transaction​

Une transaction est créée lorsqu'un ordre d'achat est apparié avec un ordre de vente. Chaque transaction enregistre le prix d'exécution, le nombre de parts échangées et les frais facturés aux deux parties. Les transactions sont des enregistrements immuables des opérations exécutées.

Frais​

Un pourcentage prélevé sur chaque transaction à la fois à l'acheteur et au vendeur. Les frais de trading par défaut sont de 2 % de la valeur de la transaction (parts * prix). Les frais sont enregistrés sur chaque transaction sous les champs buyerFee et sellerFee.

Identifiant de transaction​

Une chaîne optionnelle fournie par l'opérateur et attachée à un ordre. Peut être utilisée comme clé d'idempotence ou comme référence au système de transactions interne de l'opérateur. Le moteur de prédiction stocke cette valeur sans en imposer l'unicité.

Concepts du carnet d'ordres​

Carnet d'ordres​

L'ensemble de tous les ordres d'achat et de vente ouverts (non appariés) pour un résultat spécifique. Le carnet d'ordres est organisé par niveau de prix et détermine la façon dont les nouveaux ordres sont appariés.

Offre d'achat​

Un ordre d'achat dans le carnet d'ordres. Les offres d'achat sont triées du prix le plus élevé au plus bas. L'offre d'achat la plus élevée représente le montant maximum qu'un acheteur est prêt à payer.

Offre de vente​

Un ordre de vente dans le carnet d'ordres. Les offres de vente sont triées du prix le plus bas au plus élevé. L'offre de vente la plus basse représente le montant minimum qu'un vendeur est prêt à accepter.

Meilleure offre d'achat​

Le prix le plus élevé qu'un acheteur est actuellement prêt à payer. Il s'agit du sommet du côté acheteur du carnet d'ordres.

Meilleure offre de vente​

Le prix le plus bas qu'un vendeur est actuellement prêt à accepter. Il s'agit du sommet du côté vendeur du carnet d'ordres.

Prix médian​

Le point médian entre la meilleure offre d'achat et la meilleure offre de vente : (bestBid + bestAsk) / 2. Souvent utilisé comme le "prix actuel" d'un résultat.

Niveau de prix​

Une ligne dans le carnet d'ordres indiquant le nombre total de parts et le nombre d'ordres à un prix spécifique. Par exemple, un niveau de prix peut afficher 500 parts réparties sur 8 ordres à un prix de 0.65.

Profondeur​

Le nombre de niveaux de prix visibles dans le carnet d'ordres. Demander une profondeur de 10 retourne les 10 meilleurs niveaux d'achat et les 10 meilleurs niveaux de vente.

Liquidité​

La disponibilité des ordres dans le carnet. Un marché avec de nombreux ordres à des écarts serrés est considéré comme liquide. Une faible liquidité signifie que les ordres au marché peuvent ne pas être entièrement exécutés ou peuvent s'exécuter à des prix défavorables.

Concepts de position et de règlement​

Position​

Un enregistrement agrégé des parts détenues par un opérateur pour un résultat spécifique dans un marché spécifique. Les positions sont automatiquement créées et mises à jour à mesure que les transactions s'exécutent. Une position suit : le total des parts détenues, le prix d'acquisition moyen, le coût total et le profit/perte réalisé.

Prix moyen (avgPrice)​

Le prix moyen pondéré par le volume auquel les parts d'une position ont été acquises. Mis à jour chaque fois qu'une transaction BUY ajoute des parts à la position.

Coût total​

Le montant total dépensé pour acquérir les parts d'une position : parts * avgPrice.

PnL réalisé (Profit et Perte)​

Le profit ou la perte cumulé provenant des parts qui ont été vendues. Lorsque vous vendez des parts, la différence entre le prix de vente et le prix d'acquisition moyen est enregistrée comme PnL réalisé. Le PnL non réalisé (des parts encore détenues) n'est pas suivi directement — calculez-le comme parts * (prixActuel - avgPrice).

Règlement​

Le processus de calcul et d'enregistrement des paiements après la résolution d'un marché. Chaque position reçoit un enregistrement de règlement indiquant le montant du paiement. Les positions gagnantes sont payées à 1,00 $ par part ; les positions perdantes reçoivent 0,00 $.

Paiement​

Le montant dû au détenteur d'une position après règlement. Calculé comme parts * payoutPerShare. Pour un résultat gagnant, payoutPerShare = 1.00. Pour un résultat perdant, payoutPerShare = 0.00.

Cycle de vie d'un marché​

Brouillon​

Le statut initial d'un marché nouvellement créé. Le marché n'est pas visible pour les traders et ne peut pas accepter d'ordres.

À venir​

Un marché qui a été ouvert mais dont l'heure tradingStartsAt n'est pas encore arrivée. Le marché est visible mais pas encore tradable.

Ouvert​

Le marché accepte activement des ordres. Il s'agit du seul statut où le trading peut avoir lieu.

Suspendu​

Le trading est temporairement suspendu (par exemple, en raison d'un litige ou d'une activité irrégulière). Le marché peut être repris pour retourner au statut OPEN.

Fermé​

Le trading a définitivement pris fin. Le marché est en attente de résolution (déclaration du résultat gagnant).

Résolu​

Le résultat gagnant a été déclaré. Le marché est prêt pour le règlement.

Réglé​

Toutes les positions ont été réglées et les montants des paiements enregistrés. Il s'agit de l'état terminal d'un marché complété avec succès.

Annulé​

Le marché a été annulé. Tous les ordres ouverts sont automatiquement annulés. Il s'agit d'un état terminal.

Statuts des ordres​

En attente​

L'ordre a été placé dans le carnet d'ordres et attend d'être apparié. Aucune part n'a encore été exécutée.

Partiel (Partiellement exécuté)​

Certaines parts de l'ordre ont été appariées et tradées, mais les parts restantes sont toujours dans le carnet d'ordres en attente d'autres appariements.

Exécuté​

Toutes les parts de l'ordre ont été appariées. L'ordre est complet.

Annulé​

L'ordre a été annulé par l'opérateur avant d'être entièrement exécuté. Toutes les parts non appariées restantes sont retirées du carnet d'ordres.

Expiré​

L'ordre a dépassé son heure expiresAt sans être entièrement exécuté. Les parts restantes sont retirées du carnet d'ordres.

Rejeté​

L'ordre a été rejeté par le système, généralement parce qu'un ordre au marché n'a pas pu trouver de liquidité correspondante.

Concepts d'authentification​

Clé API​

Une chaîne secrète unique attribuée à chaque opérateur. Utilisée pour authentifier tous les appels API via l'en-tête HTTP X-Api-Key. Gardez cette valeur sécurisée — en cas de compromission, contactez un administrateur de la plateforme pour la régénérer.

Concepts d'infrastructure​

Catégorie​

Un mécanisme de regroupement pour les marchés. Les catégories ont un nom, un slug et une icône optionnelle. Les marchés peuvent être assignés à une catégorie à des fins d'organisation et de filtrage. Les catégories peuvent être spécifiques à un opérateur ou globales (partagées entre opérateurs).

Pagination par curseur​

Une stratégie de pagination utilisée dans l'ensemble de l'API. Au lieu de numéros de page, l'API retourne une valeur nextCursor que vous transmettez dans les requêtes suivantes pour récupérer la page suivante. Cette approche est plus efficace pour les grands ensembles de données et gère les insertions/suppressions entre les pages.

Volume​

Le nombre total de parts échangées sur un marché pour tous les résultats. Les marchés suivent à la fois le volume total historique (totalVolume) et le volume glissant sur 24 heures (volume24h).

Journal d'audit​

Un enregistrement interne de toutes les actions significatives effectuées sur les marchés (création, ouverture, résolution, etc.). Chaque entrée du journal enregistre le type d'action, l'acteur et l'état avant/après.

Concepts de livraison d'événements​

Webhook​

Une notification HTTP POST envoyée depuis le moteur de prédiction vers une URL enregistrée par l'opérateur lorsqu'un événement se produit. Les webhooks sont signés avec HMAC-SHA256 pour garantir leur authenticité. Il s'agit de l'approche recommandée pour la livraison d'événements de backend à backend. Les opérateurs peuvent filtrer les types d'événements qu'ils reçoivent.

Secret de webhook​

Une chaîne hexadécimale de 64 caractères générée lors de la création d'un webhook. Utilisée pour calculer la signature HMAC-SHA256 de chaque charge utile de livraison. Le secret n'est affiché en intégralité qu'une seule fois — au moment de la création. Stockez-le de manière sécurisée.

Signature de webhook​

Un hachage HMAC-SHA256 du corps de la charge utile du webhook, envoyé dans l'en-tête X-Webhook-Signature sous la forme sha256=<hex>. Les opérateurs doivent vérifier cette signature avant de traiter les livraisons de webhooks pour s'assurer que la charge utile n'a pas été altérée.

Journal d'événements​

Un journal soutenu par Postgres de tous les événements avec des numéros de séquence croissants de façon monotone. Les événements sont limités à chaque opérateur et conservés pendant 24 heures. Le journal d'événements alimente l'API de relecture d'événements.

Numéro de séquence​

Un entier auto-incrémenté attribué à chaque événement dans le journal d'événements. Les numéros de séquence sont uniques et strictement croissants, permettant aux opérateurs de suivre leur position de lecture et de rejouer les événements manqués en demandant events where sequence > lastProcessedSequence.

Relecture d'événements​

La capacité de récupérer des événements historiques via l'API REST (GET /api/v1/events). Utilisée pour se remettre d'une interruption de webhook, d'une déconnexion WebSocket ou de tout événement manqué. Les événements peuvent être filtrés par type, marché et numéro de séquence.

Type d'événement​

Une classification des événements émis par le moteur de prédiction. Les types incluent : MARKET_CREATED, MARKET_STATUS_CHANGED, MARKET_RESOLVED, ORDER_BOOK_UPDATE, PRICE_UPDATED, ORDER_PLACED, ORDER_MATCHED, ORDER_CANCELLED, POSITION_UPDATED, SETTLEMENT_COMPLETED.

Rétention des événements​

La durée pendant laquelle les événements sont stockés dans le journal d'événements. La période de rétention par défaut est de 24 heures. Après expiration, les événements sont automatiquement supprimés et ne peuvent plus être rejoués.