DEV Community

Cover image for Patterns de Conception d'API de Polymarket : Le Leader Mondial des Marchés de Prédiction
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

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

#api #architecture #systemdesign #web3

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
Enter fullscreen mode Exit fullscreen mode

définissez d’abord le but de chaque surface d’API :

Découvrir → Gamma
Trader → CLOB
Analyser → Data API
Enter fullscreen mode Exit fullscreen mode

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.

Modèle 2 : privilégier un accès public aux données de lecture

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"
Enter fullscreen mode Exit fullscreen mode

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é
Enter fullscreen mode Exit fullscreen mode

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 :

  1. Listez les endpoints qui exposent des données non sensibles.
  2. Rendez-les accessibles sans inscription si possible.
  3. Réservez les contrôles forts aux actions qui modifient un état, déplacent des fonds ou créent un engagement.

Modèle 3 : utiliser deux niveaux d’authentification

Les endpoints de trading nécessitent une authentification en deux étapes.

Niveau L1 : prouver le contrôle du portefeuille

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: "..." }
Enter fullscreen mode Exit fullscreen mode

Cette opération est sensible : elle prouve le contrôle du portefeuille.

Niveau L2 : signer les requêtes de trading

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": "..."
}
Enter fullscreen mode Exit fullscreen mode

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 »
Enter fullscreen mode Exit fullscreen mode

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.

Modèle 4 : traiter les ordres comme des messages signés

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
);
Enter fullscreen mode Exit fullscreen mode

Le SDK :

  1. construit une structure EIP-712 typée ;
  2. la signe avec la clé privée ;
  3. soumet l’ordre signé ;
  4. permet au moteur de correspondance hors chaîne de traiter l’ordre ;
  5. 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. »
Enter fullscreen mode Exit fullscreen mode

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.

Modèle 5 : rendre l’ontologie du domaine explicite

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\"]"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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 :

  1. Identifiez les invariants de votre domaine.
  2. Ajoutez-les au modèle de réponse.
  3. Utilisez des types ou champs explicites plutôt que de les laisser uniquement dans la documentation.
  4. Faites échouer les requêtes invalides plutôt que de laisser le client interpréter des données ambiguës.

Modèle 6 : exposer les relations de capital avec 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
}
Enter fullscreen mode Exit fullscreen mode

Elle doit aussi être fournie lors de la construction d’un ordre :

{
  tickSize: "0.01",
  negRisk: true,
}
Enter fullscreen mode Exit fullscreen mode

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.

Modèle 7 : diffuser les paramètres dynamiques comme état temps réel

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"
}
Enter fullscreen mode Exit fullscreen mode

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;
  }
});
Enter fullscreen mode Exit fullscreen mode

Puis utiliser la valeur à jour lors de la création d’ordres :

const orderOptions = {
  tickSize,
  negRisk: true,
};
Enter fullscreen mode Exit fullscreen mode

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.

Modèle 8 : séparer les WebSockets selon les consommateurs

Polymarket utilise deux couches WebSocket pour des besoins différents.

Canal de marché

Le canal de marché est destiné au trading :

wss://ws-subscriptions-clob.polymarket.com/ws/market
Enter fullscreen mode Exit fullscreen mode

Les abonnements utilisent des IDs d’actifs :

{
  "assets_ids": [
    "65818619657568813474341868652308942079804919287380422192892211131408793125422"
  ],
  "type": "market"
}
Enter fullscreen mode Exit fullscreen mode

Les clients reçoivent notamment :

  • snapshots de carnet d’ordres ;
  • changements de prix ;
  • exécutions ;
  • changements de taille de tick.

Socket de données temps réel

Le second socket cible des usages plus larges :

wss://ws-live-data.polymarket.com
Enter fullscreen mode Exit fullscreen mode

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"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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.

Ce qu’il faut retenir

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 :

  1. Séparez les surfaces d’API par usage métier.
  2. Rendez les données de lecture accessibles lorsque le risque le permet.
  3. Distinguez preuve d’identité et autorisation de requête.
  4. Utilisez des messages signés pour les actions irréversibles ou à fort enjeu.
  5. Exposez les relations métier importantes dans les schémas.
  6. Encodez les invariants comme champs typés et validations.
  7. Diffusez les changements d’état au lieu de laisser les clients les découvrir par erreur.
  8. 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.

Top comments (0)