Guide de l'API Polymarket - Créez votre premier bot de trading en 2026

Chapitre 27 sur 33

La version courte

Polymarket expose trois API publiques : CLOB (trading), Gamma (découverte de marchés) et Data (analytique). Le SDK Python officiel est py-clob-client 0.34.6. L'authentification utilise une clé d'API + signature ECDSA, les ordres étant signés via EIP-712 à travers un portefeuille proxy sur Polygon. Les limites de débit vous restreignent à environ 60 ordres/minute par clé. Le plus gros écueil pour les nouveaux développeurs est le problème de mappage condition_id → token_id entre Gamma et CLOB - réglez-le en premier, et tout le reste se met en place. Chaque mois, on gagne sur Polymarket environ 40 millions $ en récompenses de liquidité et en spread capturé par les bots, presque entièrement par des utilisateurs de l'API.

Partie 1 : Les trois API

Polymarket sépare proprement les responsabilités entre trois services distincts. Utiliser la bonne API pour chaque tâche garde votre bot rapide, simple et dans les limites de débit.

Une boucle de bot typique utilise Gamma pour trouver des marchés, CLOB pour récupérer les carnets d'ordres et passer des transactions, et Data pour back-tester la performance de la stratégie hors ligne. Pensez à Gamma comme au « catalogue », à CLOB comme à la « bourse » et à Data comme à l'« entrepôt ».

Partie 2 : Authentification et le modèle de portefeuille proxy

Polymarket ne signe pas les transactions avec la clé privée de votre portefeuille principal. À la place, il utilise un portefeuille proxy de style Gnosis Safe : votre portefeuille principal autorise un proxy, et le proxy exécute toutes les transactions sur Polygon. Votre bot d'API parle à ce proxy.

Ce dont vous avez besoin

• Clé d'API - générez-la dans Settings → Developer de Polymarket
• Clé privée - la clé de votre portefeuille de trading (PAS la phrase de récupération de votre MetaMask principal)
• Adresse funder - l'adresse de votre portefeuille proxy (affichée dans Settings → Wallet)
• Chain ID - 137 (Polygon mainnet)
• Type de signature - 1 (POLY_PROXY, standard pour les particuliers)

Partie 3 : Installer py-clob-client

Le SDK Python officiel est le moyen le plus rapide de passer de zéro à votre premier ordre. Nous utiliserons la version 0.34.6, qui est l'actuelle en avril 2026.

# Create a virtual environment first
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# Install the SDK
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

Configuration de base du client

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON

load_dotenv()

client = ClobClient(
 host="https://clob.polymarket.com",
 key=os.environ["POLY_PRIVATE_KEY"],
 chain_id=POLYGON, # 137
 signature_type=1, # POLY_PROXY
 funder=os.environ["POLY_FUNDER"],
)

# One-time: derive and cache API credentials
client.set_api_creds(client.create_or_derive_api_creds())

L'appel à create_or_derive_api_creds() signe un message avec votre clé privée et l'échange contre une clé d'API, un secret et une passphrase. Mettez-les en cache dans votre .env après la première exécution pour ne pas appeler l'endpoint de dérivation à chaque démarrage.

Partie 4 : Découvrir des marchés via Gamma

Avant de pouvoir trader, vous devez trouver des marchés qui en valent la peine. Gamma renvoie du JSON avec tout ce que l'interface de Polymarket affiche : question, résultats, prix, volume 24h, échéance, tags et images.

import requests

resp = requests.get(
 "https://gamma-api.polymarket.com/markets",
 params={
 "active": "true",
 "closed": "false",
 "tag_slug": "politics",
 "limit": 20,
 "order": "volume24hr",
 "ascending": "false",
 },
 timeout=10,
)
resp.raise_for_status()
markets = resp.json()

for m in markets:
 print(f"{m['slug']:50} Yes ${float(m['outcomePrices'][0]):.3f} Vol24h ${m.get('volume24hr', 0):,.0f}")

Paramètres utiles de requête Gamma

Partie 5 : Le mappage condition_id → token_id

C'est le point de douleur numéro 1 dans le développement de bots Polymarket. Gamma renvoie un condition_id (un par marché). Les transactions CLOB utilisent un token_id (un par résultat). Vous avez toujours besoin des deux.

# Each Gamma market object contains 'clobTokenIds' - a JSON string array
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # First outcome
no_token = token_ids[1] # Second outcome

# Alternative: ask CLOB directly using condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

Le piège de l'ordre des résultats

Le tableau outcomes et le tableau clobTokenIds de Gamma sont indexés ensemble. Lisez toujours l'étiquette du résultat plutôt que de supposer que l'index 0 est « Yes ». Dans les marchés à résultats multiples (NegRisk, Oscars, élections), l'index 0 pourrait être « Kamala Harris » ou « Taylor Swift » - l'ordre est déterministe mais propre au marché.

Partie 6 : Lire les carnets d'ordres

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

Les carnets d'ordres sont renvoyés sous forme de tableaux triés (bids décroissants, asks croissants). Chaque niveau a un price et une size. Pour estimer le slippage d'un ordre plus important, parcourez le carnet et accumulez le notionnel jusqu'à avoir consommé votre taille cible.

Partie 7 : Passer des ordres

Ordre à cours limité (GTC - par défaut)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # Shares, not dollars. 100 shares @ $0.45 = $45 max cost.
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

L'appel à create_order signe un message structuré EIP-712 avec votre clé privée. post_order le soumet à CLOB. Vous n'envoyez jamais de clés privées brutes sur le réseau - seulement des ordres signés.

Types d'ordre

Annuler

# Single order
client.cancel(order_id="0xabc...")

# Cancel all orders on a specific market
client.cancel_market_orders(market=market['conditionId'])

# Nuclear option: cancel everything
client.cancel_all()

Partie 8 : Streaming WebSocket

Interroger Gamma chaque seconde est du gaspillage et vous atteindrez vite les limites de débit. Le flux WebSocket diffuse les mises à jour de carnet d'ordres et de transactions en temps réel, avec une latence inférieure à la seconde.

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

Deux flux existent : le flux /market (carnet d'ordres et transactions publics) et le flux /user (vos propres événements d'ordre et d'exécution, authentifié). Les bots de production se connectent généralement aux deux, se reconnectent automatiquement à la déconnexion, et traitent le WebSocket comme la source de vérité de l'état actuel du carnet.

Partie 9 : Limites de débit et backoff

Lorsque vous recevez un HTTP 429, le serveur renvoie un en-tête Retry-After. Implémentez un backoff exponentiel avec jitter :

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Too many retries")

Partie 10 : Une architecture de bot de référence

Tout bot Polymarket robuste a les mêmes six composants. Construisez chacun comme son propre module ; gardez-les faiblement couplés.

Partie 11 : Modes de défaillance courants

• Données WebSocket obsolètes - Suivez l'heure du dernier message par actif ; s'il n'y a pas de mise à jour pendant >30s sur un marché actif, forcez un rafraîchissement REST.
• Collisions de nonce - py-clob-client gère les nonce des ordres pour vous, mais si vous écrivez votre propre signataire, incrémentez le nonce à chaque ordre.
• Solde insuffisant - Vérifiez toujours le solde pUSD avant de passer ; le carnet pourrait afficher votre ordre mais l'appariement le rejettera.
• Marché en pause ou en résolution - Vérifiez market.active && !market.closed avant de trader. Les mises à jour de Gamma sont en retard sur CLOB de quelques secondes autour de la résolution.
• Désaccord de l'adaptateur NegRisk - Les marchés à résultats multiples passent par un adaptateur NegRisk distinct. Le SDK le gère, mais confirmez que votre ordre est allé au bon venue.

Partie 12 : Récompenses de liquidité via l'API

Polymarket fait tourner environ 5 millions $/mois en récompenses de liquidité générales plus 5 millions $+/mois en récompenses spécifiques au sport (voir Récompenses de liquidité). La grande majorité va aux market makers pilotés par API qui peuvent maintenir des cotations bilatérales serrées sur des milliers de marchés.

La formule de récompense récompense les ordres proches du point médian, la taille et le temps au carnet. Une boucle de market making minimale :

1. Lisez le carnet d'ordres du marché cible
2. Calculez un point médian juste (p. ex. VWAP des 3 meilleurs niveaux de chaque côté)
3. Postez un bid à mid − spread_target/2 et un ask à mid + spread_target/2
4. À chaque mise à jour WebSocket, ré-évaluez le prix si votre cotation dérive de plus d'un tick par rapport à la cible
5. Annulez et sortez si le carnet s'amincit ou si des nouvelles tombent

Partie 13 : Passer en production

• Hébergement : un VPS à 6 $/mois (Hetzner, DigitalOcean) en Europe ou US-East suffit pour la plupart des bots. Co-localisez avec un Polygon RPC si vous avez besoin d'une latence inférieure à 10ms.
• RPC : utilisez Alchemy, Infura ou QuickNode pour un Polygon RPC fiable. Les paliers gratuits suffisent jusqu'à ce que vous passiez des centaines d'ordres par minute.
• Surveillance : Prometheus + Grafana pour les métriques ; un bot Telegram pour les alertes. Journalisez chaque ID d'ordre que vous envoyez et chaque exécution que vous recevez.
• Sauvegardes : persistez l'état chaque minute. Si le VPS meurt en pleine exécution, vous voulez reprendre en quelques secondes, pas réconcilier à la main.
• Impôts : votre journal est aussi votre piste d'audit - voir Guide fiscal.

Partie 14 - Conseils de pro validés pour l'API Polymarket

Aide-mémoire : situation → action

Et ensuite ?

• Outils et ressources - tableaux de bord, analytique et flux de données tiers qui complètent l'API
• Stratégies avancées - arbitrage à pattes multiples et constructions de type options adaptées aux bots
• Récompenses de liquidité - formules exactes pour gagner des rebates de market-making
• Guide du carnet d'ordres - une intuition plus profonde pour lire le carnet avant de coder contre lui
• Glossaire - définitions en langage clair de chaque terme de ce guide