Les marchés de prédiction comptent parmi les domaines les plus exigeants techniquement pour la création d'API. Vous y gérez des instruments financiers qui expirent, des probabilités qui s'évaluent en temps réel, des événements à plusieurs issues avec des relations de capital complexes, et une base d'utilisateurs qui inclut à la fois des humains cliquant sur une interface utilisateur et des bots de trading automatisés exécutant des stratégies d'arbitrage. Chaque décision de conception est immédiatement mise à l'épreuve. Polymarket, actuellement la plus grande plateforme de marchés de prédiction au monde en termes de volume, a construit un écosystème d'API qui mérite d'être étudié précisément pour cette raison. Ce n'est pas juste une API CRUD sur une base de données. C'est une architecture soigneusement stratifiée qui gère la tension fondamentale entre ouverture et sécurité, entre données en temps réel et historiques, et entre modèles de finance traditionnels et primitives natives de la crypto. Voici huit modèles de conception à extraire de leur approche.
Modèle 1 : Couches d'API séparées par domaine
Polymarket expose trois API distinctes, chacune avec un domaine clair :
- API Gamma (
gamma-api.polymarket.com) — découverte de marchés, événements, balises, recherche - API CLOB (
clob.polymarket.com) — données du carnet d'ordres, tarification, placement d'ordres - API de données (
data-api.polymarket.com) — positions utilisateur, transactions, analyses, classements
Il ne s'agit pas seulement d'une convention de nommage — chaque API a des exigences d'authentification différentes, des fréquences de mise à jour différentes et des profils de consommateurs différents. L'API Gamma est entièrement publique, optimisée pour la navigation et la découverte. L'API CLOB a à la fois des points de terminaison publics (tout le monde peut lire le carnet d'ordres) et des points de terminaison authentifiés (le trading nécessite des identifiants). L'API de données est publique mais adressée par portefeuille — vous interrogez les positions par adresse utilisateur. La leçon de conception ici est que la séparation par domaine plutôt que par entité produit des API plus cohérentes. Une approche naïve vous donnerait /markets, /orders, /users tout sous un même toit. Polymarket demande plutôt : « À quoi sert cette API ? » et construit ensuite autour de cette question. La découverte a des modèles d'accès différents du trading. Le trading a des exigences de latence différentes de l'analyse. Donner à chacun sa propre URL de base signifie que chacun peut évoluer, s'adapter et s'authentifier indépendamment.
Modèle 2 : Accès aux données Public-First
Tout ce qui concerne les données de marché — prix, carnets d'ordres, métadonnées d'événements, transactions historiques — est entièrement public :
curl "https://gamma-api.polymarket.com/events?limit=5"
Pas de clé API. Pas d'OAuth. Pas de limites de débit sur les points de terminaison de lecture. Vous obtenez les données. C'est un choix délibéré que la plupart des plateformes financières ne font pas. Les bourses traditionnelles protègent les données de marché comme source de revenus. Polymarket les traite comme une infrastructure — plus les gens peuvent lire et construire sur ces données, plus le marché devient liquide et utile. C'est la logique des biens publics appliquée à une API. La conséquence pratique pour les concepteurs d'API mérite d'être notée : séparer l'accès en lecture de l'accès en écriture comme une préoccupation de premier ordre, plutôt que d'appliquer l'authentification uniformément, est presque toujours la bonne approche pour les plateformes où la consommation de données dépasse largement la production de données. Si un utilisateur peut lire les prix du marché sans identifiants, vous avez supprimé les frictions pour 95 % de votre audience potentielle. Vous n'ajoutez des frictions qu'au moment où cela compte vraiment — lorsqu'ils veulent passer un ordre réel.
Modèle 3 : Authentification à deux niveaux reflétant une confiance réelle
Les points de terminaison de trading nécessitent une authentification, mais le modèle d'authentification de Polymarket a une structure que la plupart des concepteurs d'API n'ont jamais vue : deux niveaux avec des objectifs distincts. L'Authentification L1 utilise une signature EIP-712 de la clé privée de l'utilisateur. Elle prouve la propriété du portefeuille. Vous l'utilisez exactement une fois (ou rarement) pour dériver les identifiants API :
// L1 : Utilisez votre clé privée pour dériver les identifiants API
const credentials = await client.createOrDeriveApiKey();
// → { key: "...", secret: "...", passphrase: "..." }
L'Authentification L2 utilise HMAC-SHA256 avec ces identifiants dérivés. C'est ce que vous joignez à chaque requête de trading :
// En-têtes L2 sur chaque requête de trading
{
"POLY_ADDRESS": "0x...",
"POLY_SIGNATURE": "<hmac-sha256>",
"POLY_TIMESTAMP": "1716000000",
"POLY_API_KEY": "550e8400-...",
"POLY_PASSPHRASE": "..."
}
L'idée est que différentes opérations méritent différentes cérémonies de sécurité. La création de clés API nécessite de prouver le contrôle du portefeuille — c'est une action à enjeux élevés qui devrait exiger une signature cryptographique de la clé privée. Mais une fois que vous avez établi cette confiance, les requêtes de trading de routine ne devraient pas nécessiter de re-signature avec votre clé privée à chaque appel. Les identifiants L2 sont suffisamment légers pour une utilisation à haute fréquence tout en étant liés à l'identité L1. Ce modèle s'applique bien au-delà de la crypto : considérez-le comme la différence entre « prouver que vous êtes cette personne » (L1, effectué rarement avec l'identifiant le plus fort disponible) et « prouver que cette requête provient de vous » (L2, effectué constamment avec un identifiant de session). La plupart des applications web combinent ces éléments en un seul flux d'authentification et perdent la nuance de sécurité.
Modèle 4 : Les ordres comme messages signés, pas comme appels API
C'est là que les marchés de prédiction divergent le plus nettement de la conception API conventionnelle. Lorsque vous placez un ordre sur Polymarket, vous n'envoyez pas seulement des données à un serveur — vous créez un message cryptographiquement signé qui est un engagement financier exécutoire :
const response = await client.createAndPostOrder(
{
tokenID: "71321045679...",
price: 0.65,
size: 100,
side: Side.BUY,
},
{
tickSize: "0.01",
negRisk: false,
},
OrderType.GTC
);
En arrière-plan, le SDK construit une structure de données typée EIP-712, la signe avec votre clé privée et soumet la signature avec l'ordre. Le moteur de correspondance fonctionne hors-chaîne (offchain), mais lorsque les transactions sont appariées, elles se règlent sur la chaîne (on-chain) via Polygon en utilisant ces signatures. L'opérateur ne peut pas fabriquer de transactions ni déplacer de fonds — le message signé est l'autorisation. Cela modifie la sémantique de ce qu'un « appel API » signifie. Normalement, soumettre à un point de terminaison signifie « veuillez faire ceci en mon nom. » Ici, soumettre un ordre signifie « voici un instrument signé autorisant cette transaction. » L'API n'est pas un intermédiaire prenant des décisions — c'est un relais pour des messages cryptographiquement auto-autorisants. Pour les concepteurs d'API en dehors de l'espace crypto, la leçon à retenir est la suivante : lorsque la charge utile elle-même peut porter l'autorisation plutôt que de dépendre entièrement des identifiants de la couche de transport, vous obtenez gratuitement la non-répudiation et la vérifiabilité. Les systèmes financiers, les documents juridiques et les opérations à enjeux élevés sont tous des candidats pour ce modèle.
Modèle 5 : Ontologie explicite dans le modèle de données
Polymarket structure ses données autour de deux objets : les Événements et les Marchés. La distinction est importante. Un événement est une question : « Qui gagnera la course au Sénat américain de Pennsylvanie en 2026 ? » Il a un titre, une catégorie, une date de résolution. Un marché est un résultat binaire spécifique et négociable au sein de cet événement : « Bob Casey va-t-il gagner ? » Un événement peut contenir de nombreux marchés.
{
"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\"]" }
]
}
C'est une ontologie explicite — l'API ne se contente pas de stocker des données, elle encode les relations conceptuelles entre les entités. Les prix sont représentés comme des tableaux parallèles où la position de l'index est la convention de liaison : outcomes[0] correspond à outcomePrices[0]. Le drapeau negRisk au niveau de l'événement signale que les marchés qu'il contient ont des relations de capital qui n'existent pas dans les marchés indépendants. La plupart des API aplatissent ces relations. Polymarket les fait apparaître parce qu'elles sont cruciales pour le fonctionnement du système. Si vous construisez un trader automatisé et que vous ignorez negRisk: true, vous construirez un modèle de position incorrect et risquez de perdre de l'argent. La conception de l'API rend la structure conceptuelle visible afin que l'omission de celle-ci soit un choix conscient, et non un défaut silencieux.
Modèle 6 : NegRisk — Les relations de capital comme préoccupation de premier ordre
Le drapeau negRisk sur les événements met en évidence l'un des modèles de conception d'API les plus intéressants de Polymarket : rendre les équivalences financières programmables. Dans un événement multi-résultats standard, chaque marché est indépendant. Mais dans un événement NegRisk, où exactement un seul résultat peut l'emporter, une relation mathématique existe entre les positions :
1 jeton « Non » sur le résultat A ≡ 1 jeton « Oui » sur tous les autres résultats
Ce n'est pas seulement des mathématiques — c'est implémenté dans des contrats intelligents et révélé via l'API. Lorsque vous détenez une position « Non » sur « Autre » dans la course au Sénat de Pennsylvanie, vous pouvez la convertir :
| Avant | Après |
|---|---|
| 1× Non (Autre) | 1× Oui (Casey) + 1× Oui (McCormick) |
L'API le rend explicite : negRisk: true dans l'objet marché, et negRisk: true requis dans vos options d'ordre lors du trading sur ces marchés. Si vous vous trompez, votre ordre sera rejeté ou réglé incorrectement. Le modèle de conception ici est d'encoder les invariants du domaine comme des champs API typés plutôt que de les laisser comme des notes de bas de page dans la documentation. Le drapeau NegRisk n'existe pas parce qu'il est pratique de l'avoir — il existe parce que son omission entraîne un comportement incorrect. Lorsque votre domaine a des contraintes strictes (un seul résultat peut l'emporter, les positions ont des équivalences de conversion), ces contraintes doivent apparaître dans l'interface de l'API, pas seulement dans les documents.
Modèle 7 : Taille de tick dynamique comme état du marché
La plupart des API financières traitent la taille de tick comme une configuration statique. Celle de Polymarket fait quelque chose de plus intéressant : la taille de tick change dynamiquement en fonction du prix du marché, et l'API l'expose comme un flux d'événements en temps réel. Lorsque le prix d'un marché approche les extrêmes (au-dessus de 0,96 ou en dessous de 0,04), la taille minimale du tick se réduit 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"
}
Le raisonnement est intuitif : à des probabilités extrêmes, un tick d'un cent représente un mouvement de 25 % (passant de 0,04 à 0,03). C'est trop grossier pour une découverte de prix significative. Des ticks plus fins près des extrêmes permettent au marché d'exprimer des probabilités comme 97,3 % plutôt que d'arrondir à 97 %. Ce qui rend cela notable comme choix de conception d'API, c'est que la taille du tick n'est pas un paramètre que vous récupérez une fois — c'est un état qui change et doit être suivi. Le WebSocket expose précisément les événements tick_size_change afin que les clients puissent maintenir leur logique de construction d'ordres cohérente avec l'état actuel du marché. Si vous codez en dur la taille du tick et manquez cet événement, vos ordres seront rejetés. Cela reflète un principe plus large : la conception d'API pour les systèmes financiers doit adopter l'état comme un concept de premier ordre. Les paramètres du marché ne sont pas statiques. Les règles de résolution changent. Les résultats sont clarifiés. L'API doit communiquer ces transitions d'état explicitement, et non laisser les clients les découvrir par des requêtes rejetées.
Modèle 8 : Deux couches WebSocket pour différents profils de consommateurs
Polymarket utilise deux systèmes WebSocket distincts, et comprendre pourquoi révèle un modèle de segmentation d'audience. Le Canal de Marché (wss://ws-subscriptions-clob.polymarket.com/ws/market) est conçu pour les consommateurs de trading. Abonnez-vous par ID de jeton, recevez des instantanés du carnet d'ordres, des changements de prix, des exécutions de transactions et des changements de taille de tick. Tout est indexé par ID d'actifs et optimisé pour une construction d'ordres à faible latence :
{
"assets_ids": ["65818619657568813474341868652308942079804919287380422192892211131408793125422"],
"type": "market"
}
Le Socket de Données en Temps Réel (wss://ws-live-data.polymarket.com) est construit pour un profil complètement différent. Il diffuse des commentaires, les prix crypto de Binance et Chainlink, les prix des actions et les événements d'interaction sociale. Abonnez-vous par sujet :
{
"action": "subscribe",
"subscriptions": [
{ "topic": "crypto_prices", "type": "update", "filters": "btcusdt,ethusd" }
]
}
Ces deux systèmes servent des audiences ayant des besoins fondamentalement différents. Un teneur de marché a besoin de deltas de carnet d'ordres pertinents à la microseconde. Une interface utilisateur montrant « ce qui se passe sur Polymarket en ce moment » a besoin de flux de commentaires et d'activité sociale. Les combiner signifierait soit une sur-ingénierie du flux social avec des exigences de latence de niveau trading, soit une sous-ingénierie du flux du carnet d'ordres avec des hypothèses de fiabilité de niveau social. La leçon est simple mais souvent ignorée : lorsque vos consommateurs en temps réel ont des tolérances à la latence, des volumes de données et des modes de défaillance significativement différents, donnez-leur une infrastructure séparée. Les points de terminaison WebSocket partagés qui tentent de servir plusieurs objectifs tendent à s'effondrer vers le plus haut dénominateur commun en matière de complexité et vers le plus bas dénominateur commun en matière de performances.
Ce que ces modèles ont en commun
La conception de l'API de Polymarket reflète une philosophie particulière : l'API doit rendre visible la structure réelle du domaine, et non l'abstraire. L'architecture à trois couches correspond aux limites réelles du domaine. L'accès public-first reflète le fonctionnement de la valeur des marchés de prédiction. L'authentification à deux niveaux reflète la différence réelle entre prouver une identité et autoriser une action. Les ordres en tant que messages signés encodent la garantie non-custodial. La hiérarchie Événement/Marché et le drapeau NegRisk exposent des relations qui seraient autrement invisibles. Les tailles de tick dynamiques maintiennent l'état du client cohérent avec l'état du marché. Des couches WebSocket séparées servent des publics distincts. La plupart des conseils de conception d'API se concentrent sur l'ergonomie : la rendre facile à appeler, cohérente dans la nomination, prévisible dans la gestion des erreurs. L'API de Polymarket fait tout cela — mais les choix les plus intéressants concernent la fidélité au domaine. Lorsque le domaine a une distinction significative, l'API la révèle. Lorsque le domaine a une contrainte, l'API la fait respecter. Lorsque le domaine a un état qui change, l'API le diffuse. Le résultat est une API qui exige plus de ses consommateurs, mais une API où réussir signifie que vous comprenez réellement le système sur lequel vous tradez. Ce n'est pas une coïncidence — pour un marché de prédiction, où le but est que les prix reflètent l'information, une API qui vous force à comprendre la structure du marché fait exactement ce qu'elle devrait faire.