Patterns de Conception d'API de Polymarket : Le Leader Mondial des Marchés de Prédiction

Les marchés de prédiction comptent parmi les domaines les plus exigeants pour concevoir une API : instruments financiers à expiration, probabilités en temps réel, événements à plusieurs issues, relations de capital complexes, utilisateurs humains et bots d’arbitrage. Polymarket, actuellement la plus grande plateforme de marchés de prédiction au monde en termes de volume, propose une architecture utile à étudier : elle sépare explicitement découverte, trading, données historiques et flux temps réel. Voici huit modèles concrets à reprendre dans vos propres API. Essayez Apidog dès aujourd’hui Modèle 1 : séparer les API par domaine Polymarket expose trois API avec des responsabilités distinctes : API Gamma (gamma-api.polymarket.com) : découverte de marchés, événements, balises et recherche. API CLOB (clob.polymarket.com) : carnet d’ordres, prix et placement d’ordres. API de données (data-api.polymarket.com) : positions, transactions, analyses et classements. Cette séparation ne relève pas seulement du nommage. Chaque domaine a ses propres contraintes : Domaine Consommateurs principaux Latence attendue Authentification Découverte UI, recherche, indexeurs Modérée Publique Trading Bots, traders, teneurs de marché Faible Lecture publique, écriture authentifiée Données Dashboards, reporting, analytics Variable Publique, requêtes par portefeuille Au lieu de regrouper toutes les ressources sous une seule API : /markets /orders /users définissez d’abord le but de chaque surface d’API : Découvrir → Gamma Trader → CLOB Analyser → Data API Cette découpe permet de faire évoluer indépendamment : les mécanismes d’authentification ; les politiques de cache ; les limites de débit ; les SLA de latence ; les modèles de pagination et de streaming. À appliquer : découpez vos API selon les flux métier et les profils de consommation, pas uniquement selon vos tables ou entités de base de données. Les données de marché — prix, carnets d’ordres, métadonnées d’événements et transactions historiques — sont accessibles publiquement : curl "https://gamma-api.polymarket.com/events?limit=5" Aucune clé API ni flux OAuth n’est nécessaire pour lire ces données. Cette approche réduit fortement la friction pour : les développeurs qui explorent la plateforme ; les interfaces publiques ; les outils d’analyse ; les bots qui surveillent les marchés ; les intégrations tierces. Le principe est simple : séparez explicitement les autorisations de lecture et d’écriture. GET /markets → public GET /order-book/:id → public POST /orders → authentifié DELETE /orders/:id → authentifié Pour une plateforme où la lecture dépasse largement l’écriture, demander une authentification pour chaque endpoint public ajoute surtout de la complexité inutile. À appliquer : Listez les endpoints qui exposent des données non sensibles. Rendez-les accessibles sans inscription si possible. Réservez les contrôles forts aux actions qui modifient un état, déplacent des fonds ou créent un engagement. Les endpoints de trading nécessitent une authentification en deux étapes. L’authentification L1 utilise une signature EIP-712 avec la clé privée de l’utilisateur. Elle sert à dériver des identifiants API : // L1 : dériver des identifiants API depuis la clé privée const credentials = await client.createOrDeriveApiKey(); // → { key: "...", secret: "...", passphrase: "..." } Cette opération est sensible : elle prouve le contrôle du portefeuille. Une fois les identifiants dérivés, les requêtes utilisent HMAC-SHA256 : { "POLY_ADDRESS": "0x...", "POLY_SIGNATURE": "<hmac-sha256>", "POLY_TIMESTAMP": "1716000000", "POLY_API_KEY": "550e8400-...", "POLY_PASSPHRASE": "..." } Le modèle général est le suivant : L1 : « Je prouve mon identité avec un identifiant fort » L2 : « Je prouve que cette requête est autorisée » Il évite de demander une signature de clé privée pour chaque appel à faible latence, tout en conservant un lien cryptographique avec l’identité initiale. À appliquer : utilisez un facteur fort et rare pour créer une session ou des identifiants ; utilisez ensuite des credentials plus légers pour les appels fréquents ; définissez clairement la durée de vie, la révocation et la rotation des secrets L2. Sur Polymarket, un ordre n’est pas une simple requête métier envoyée à un serveur. C’est un message signé qui constitue un engagement financier. const response = await client.createAndPostOrder( { tokenID: "71321045679...", price: 0.65, size: 100, side: Side.BUY, }, { tickSize: "0.01", negRisk: false, }, OrderType.GTC ); Le SDK : construit une structure EIP-712 typée ; la signe avec la clé privée ; soumet l’ordre signé ; permet au moteur de correspondance hors chaîne de traiter l’ordre ; utilise la signature lors du règlement sur Polygon. La différence de sémantique est importante : API classique : « Veuillez effectuer cette opération pour moi. » Message signé : « Voici une autorisation cryptographique pour cette opération. » Le message transporte lui-même une partie de l’autorisation. Ce modèle apporte des propriétés utiles : non-répudiation ; vérifiabilité ; limitation du pouvoir de l’opérateur ; séparation entre transport réseau et autorisation métier. À appliquer : envisagez des payloads signés pour les opérations à fort enjeu : transactions financières, validation de documents, approbations irréversibles ou instructions réglementées. Polymarket structure ses données autour de deux concepts : Événement : la question globale ; Marché : une issue binaire négociable de cet événement. Exemple : une course électorale peut être un événement, et chaque candidat peut correspondre à un marché distinct. { "id": "501", "title": "2026 Pennsylvania Senate Race", "negRisk": true, "markets": [ { "id": "2301", "question": "Will Bob Casey win?", "outcomePrices": "[\"0.42\", \"0.58\"]" }, { "id": "2302", "question": "Will Dave McCormick win?", "outcomePrices": "[\"0.35\", \"0.65\"]" }, { "id": "2303", "question": "Will a third candidate win?", "outcomePrices": "[\"0.23\", \"0.77\"]" } ] } L’API encode ainsi des relations métier importantes : un événement contient plusieurs marchés ; les résultats et leurs prix sont liés par index ; outcomes[0] correspond à outcomePrices[0] ; negRisk modifie les relations de capital entre les marchés. Ne masquez pas ces relations derrière une structure plate si elles influencent les calculs métier. À appliquer : Identifiez les invariants de votre domaine. Ajoutez-les au modèle de réponse. Utilisez des types ou champs explicites plutôt que de les laisser uniquement dans la documentation. Faites échouer les requêtes invalides plutôt que de laisser le client interpréter des données ambiguës. negRisk Le champ negRisk indique qu’un événement comporte une relation financière particulière entre ses marchés : exactement un seul résultat peut gagner. Dans ce contexte : 1 jeton « Non » sur le résultat A ≡ 1 jeton « Oui » sur tous les autres résultats Exemple de conversion : Avant Après 1× Non (Autre) 1× Oui (Casey) + 1× Oui (McCormick) Cette contrainte est visible dans l’API : { "negRisk": true } Elle doit aussi être fournie lors de la construction d’un ordre : { tickSize: "0.01", negRisk: true, } Le point important n’est pas seulement le champ lui-même. C’est le fait que l’invariant métier soit représenté dans le contrat d’API. Sans cette information, un bot peut calculer une exposition erronée. Le champ empêche donc une erreur de modélisation silencieuse. À appliquer : lorsqu’une règle métier modifie les calculs, les transitions d’état ou les autorisations, encodez-la directement dans les schémas d’entrée et de sortie. La taille de tick n’est pas toujours fixe. Sur Polymarket, elle change selon le prix du marché. Quand le prix dépasse 0.96 ou descend sous 0.04, le tick minimum passe de 0.01 à 0.001 : { "event_type": "tick_size_change", "asset_id": "65818619657...", "old_tick_size": "0.01", "new_tick_size": "0.001", "timestamp": "100000000" } Cette granularité est nécessaire près des extrêmes. Entre 0.04 et 0.03, un mouvement de 0.01 représente 25 % de la probabilité initiale. Un tick de 0.001 permet une découverte de prix plus précise. Le client doit donc traiter la taille de tick comme un état mutable : let tickSize = "0.01"; socket.on("tick_size_change", (event) => { if (event.asset_id === assetId) { tickSize = event.new_tick_size; } }); Puis utiliser la valeur à jour lors de la création d’ordres : const orderOptions = { tickSize, negRisk: true, }; Ne codez pas ces paramètres en dur. Si le client ignore une transition d’état, ses ordres peuvent être rejetés. À appliquer : distinguez les configurations statiques des paramètres dynamiques ; diffusez les changements de règles par événements ; permettez aux clients de reconstruire leur état après reconnexion ; documentez les actions attendues après chaque événement. Polymarket utilise deux couches WebSocket pour des besoins différents. Le canal de marché est destiné au trading : wss://ws-subscriptions-clob.polymarket.com/ws/market Les abonnements utilisent des IDs d’actifs : { "assets_ids": [ "65818619657568813474341868652308942079804919287380422192892211131408793125422" ], "type": "market" } Les clients reçoivent notamment : snapshots de carnet d’ordres ; changements de prix ; exécutions ; changements de taille de tick. Le second socket cible des usages plus larges : wss://ws-live-data.polymarket.com Il peut diffuser des commentaires, prix crypto, prix d’actions et événements sociaux. { "action": "subscribe", "subscriptions": [ { "topic": "crypto_prices", "type": "update", "filters": "btcusdt,ethusd" } ] } Ces flux ont des contraintes différentes : Besoin Flux de trading Flux de données générales Latence Très faible Variable Volume Carnets et exécutions Activité, commentaires, prix externes Identifiant Asset ID Sujet Consommateur Bot, teneur de marché UI, dashboard, application sociale Un endpoint unique obligerait à faire des compromis sur les performances, la fiabilité et la complexité du protocole. À appliquer : créez des flux distincts dès que les audiences ont des exigences réellement incompatibles en matière de latence, de volume ou de tolérance aux pertes. Les choix de conception de Polymarket suivent un principe cohérent : l’API expose la structure réelle du domaine au lieu de la masquer. Pour rendre une API financière ou temps réel plus robuste : Séparez les surfaces d’API par usage métier. Rendez les données de lecture accessibles lorsque le risque le permet. Distinguez preuve d’identité et autorisation de requête. Utilisez des messages signés pour les actions irréversibles ou à fort enjeu. Exposez les relations métier importantes dans les schémas. Encodez les invariants comme champs typés et validations. Diffusez les changements d’état au lieu de laisser les clients les découvrir par erreur. Segmentez les infrastructures temps réel selon les besoins des consommateurs. Une API ergonomique est utile. Une API fidèle au domaine l’est davantage : elle aide les clients à construire des intégrations correctes, notamment lorsque les erreurs de modélisation ont un coût financier direct.