Construire un bot Polymarket : scanner, sizing, exécution, monitoring

Ce guide montre comment construire un bot Polymarket qui scanne en continu les marchés, calcule les tailles de position, exécute via le CLOB et surveille la performance. Il se concentre sur l'architecture et les patrons développeur que vous pouvez implémenter en utilisant les API publiques de Polymarket et le modèle Relayer.

Points clés

• Architecturer le bot en quatre services indépendants : scanner, sizer, exécuteur et monitor.
• Utiliser les APIs Gamma et CLOB de Polymarket pour les listings et la passation d'ordres ; WebSocket pour les mises à jour de carnet en temps réel.
• Préférer les ordres marché FAK pour une exécution à vitesse arbitraire, mais toujours prendre en compte le slippage et les frais.
• Instrumenter le monitoring et des kill-switches rapides pour les disputes d'oracle, les retards de settlement ou des fills inattendus.

Pourquoi cette structure

Les systèmes de trading sont plus faciles à analyser quand les responsabilités sont séparées. Un scanner trouve des edges candidats, un sizer convertit l'edge en position, un exécuteur place les ordres via le CLOB, et un monitor garantit la sécurité et la correction. Cette séparation vous permet de scaler, tester et raisonner indépendamment sur la latence et le risque.

H2: Sources de données et APIs

Commencez par connecter ces endpoints Polymarket à vos services :

• Gamma (métadonnées marché) : https://gamma-api.polymarket.com — markets, events, tags, series. Utilisez la pagination avec after_cursor ; évitez offset.
• CLOB (order book & trading) : https://clob.polymarket.com — les lectures d'orderbook sont publiques ; le trading nécessite API key + HMAC. Les SDK CLOB gèrent la passation d'ordres.
• Market WebSocket (carnet en temps réel) : wss://ws-subscriptions-clob.polymarket.com/ws/market — abonnez-vous aux flux book, price_change, best_bid_ask et tick_size_change. PING toutes les 10s.
• Data API (positions, open interest) : https://data-api.polymarket.com pour l'analytics post-trade.

Note de conception : combinez les listings Gamma avec le flux WebSocket pour un scanning live efficace. Respectez les limites de taux de Gamma (par ex. le cap sur /markets) et les exigences de clé CLOB pour la passation d'ordres.

H2: Scanner — trouver des opportunités candidates

Fonction

Le scanner découvre les opportunités correspondant à votre stratégie : spreads intra-market binaires, sommes multi-issue, ou patterns endgame. Il doit être sans état (stateless), scalable horizontalement et concentré sur le calcul d'edges bruts.

Entrées et cadence

• Abonnez-vous au Market WebSocket avec custom_feature_enabled: true pour recevoir best_bid_ask et les changements de tick.
• Backfillez via Gamma /markets lorsque vous rencontrez un nouvel instrument pour obtenir les métadonnées et les issues.
• Maintenez une petite vue en mémoire des meilleurs asks/bids pour chaque issue.

Calcul de l'edge

• Binaire intra-market : calculez edge = 1.00 - (bestAsk(YES) + bestAsk(NO)). Un edge positif est un candidat.
• Multi-issue : edge = 1.00 - sum(bestAsk(outcomes)).

Seuils et filtres

• Seuil minimum d'edge (par ex. > un certain nombre de cents configuré) pour couvrir les frais taker et le risque d'exécution.
• Vérifications minimales de liquidité : la profondeur au meilleur ask doit satisfaire la taille minimale de fill.
• Sensibilité au tick-size : prenez en compte les événements tick_size_change — la granularité des prix peut passer à $0.001 près des extrêmes.

H2: Sizing — risque et allocation de capital

Objectifs

Le sizing convertit un edge brut en un plan d'ordre : combien de parts acheter par issue, et comment splitter en plusieurs ordres pour limiter le slippage.

Composants

• Caps d'exposition : limites d'exposition en pUSD par marché et globales.
• Sizing limité par profondeur : calculez le volume cumulatif disponible aux niveaux de prix successifs côté ask ; ne dimensionnez que jusqu'au volume qui garde le slippage attendu dans la tolérance.
• Provision pour frais : soustrayez la fee taker attendue (variable, jusqu'à 1.8% dans certaines catégories) de l'edge brut avant de décider d'entrer en position.

Patron pratique

• Commencez par des fills conservateurs : préférez plusieurs petits ordres marché FAK plutôt qu'un gros ordre unique, sauf si vous contrôlez le carnet.
• Si vous achetez un ensemble complet via les flows CTF split/merge, incluez le coût des split/merge (pris en charge par le Relayer) et les arrondis potentiels dus au tick size.

H2: Exécuteur — passer les ordres et gérer les fills

Types d'ordres et contraintes

• Utilisez l'endpoint trading du CLOB pour la passation des ordres : https://clob.polymarket.com. Le SDK CLOB et le Relayer gèrent le déploiement de wallet, les approvals et la signature des ordres.
• Pour la vitesse, utilisez FAK (Fill-And-Kill) market orders quand approprié. Les FAK exécutent immédiatement ou annulent ; ils évitent une exposition qui traîne mais peuvent être partiellement fillés.

Flux d'exécution

1. Préparez l'intention de trade : liste des token ids d'issue et quantités cibles retournées par le sizer.
2. Si vous exécutez un ensemble multi-issue complet, vous pouvez à la place effectuer un CTF split (mint d'un ensemble complet) puis vendre les legs ; le Relayer et le SDK abstraient les ops CTF.
3. Soumettez les ordres via l'API trading CLOB avec des en-têtes d'attribution appropriés si vous faites partie du Builder Program.
4. Observez les fills via le WebSocket last_trade_price et les mises à jour best_bid_ask ou via les réponses de trading CLOB.

Sécurité et réconciliation

• Suivez les fills partiels et annulez le reste ou re-prixez immédiatement.
• Réconciliez les soldes CTF on-chain (via Data API) après les fills pour vous assurer que vous détenez bien les tokens d'issue attendus.
• Implémentez des clés d'idempotence et la gestion de nonce pour les retries d'ordre.

H2: Monitoring et sécurité opérationnelle

Ce qu'il faut monitorer

• Taux de fill, slippage moyen versus attendu, edge réalisé après frais.
• Latence entre les mises à jour WebSocket et la soumission d'ordre.
• Événements inhabituels : disputes UMA, tick_size_change, pannes générales de la marketplace.

Alertes et kill-switches

• Soft kill automatisé : mettre en pause la passation de nouveaux ordres lorsque le P&L réalisé net descend sous un seuil ou lorsque le slippage de fill dépasse des limites.
• Hard kill : arrêter immédiatement tout le trafic si UMA signale une dispute pour un marché où vous avez des positions, ou si le Relayer signale des problèmes de settlement.

Logs d'audit et observabilité

• Stockez toutes les intentions d'ordre, snapshots bruts du marché et fills exécutés. Utilisez ces logs pour post-mortem et backtesting.
• Étiquetez les logs avec market id, condition_ids et request ids pour faire correspondre les enregistrements Gamma et CLOB.

H2: Builder Program, identifiants et limites de taux

Si vous prévoyez de router des ordres avec attribution, rejoignez le Builder Program et gérez les clés via les settings Polymarket. Les tiers Builder contrôlent les limites quotidiennes du Relayer et les récompenses. Pour trader via le CLOB vous aurez besoin d'API key + HMAC et devrez respecter les limites de taux et quotas du Relayer.

H2: Risques courants et mitigations

Ne supposez jamais que l'edge mathématique est garanti. Risques à prendre en compte :

• Risque de résolution : les disputes UMA peuvent mettre en pause ou modifier les paiements.
• Slippage et fills partiels : les FAK peuvent être partiellement remplis ; prévoyez l'exposition résiduelle.
• Frais : les taker fees varient par catégorie et peuvent grignoter de petits edges (Geopolitics est sans frais).
• Délai de settlement : le timing de redeem/merge et les retards d'oracle peuvent immobiliser du capital.
• Défaillances smart-contract ou Relayer : prévoir des solutions de secours et une alerte humaine.

Comment cela affecte votre trading

Concevez votre bot pour que chaque unité de trade soit petite, observable et réversible dans vos limites de risque. Un sizing conservateur, un monitoring rapide et des conditions d'arrêt claires réduisent le risque de queue. Utilisez les endpoints Gamma et CLOB pour un état de marché déterministe et préférez les ordres FAK pour une exécution rapide, mais mesurez toujours le slippage réalisé par rapport aux attentes.

Conclusion

L'architecture ci-dessus fournit une feuille de route pragmatique pour construire un bot de trading Polymarket : un scanner haute-débit, un sizer conservateur, un exécuteur robuste utilisant le CLOB et le Relayer, et un monitoring en couches. Commencez petit, instrumentez massivement et itérez sur le sizing et les filtres à mesure que vous accumulez des données live.

Questions fréquemment posées

Quelles APIs dois-je utiliser pour obtenir les listings de marché et les données de carnet en direct ?

Utilisez https://gamma-api.polymarket.com pour les métadonnées marché (/markets) et wss://ws-subscriptions-clob.polymarket.com/ws/market pour le carnet d'ordres temps réel et les événements best_bid_ask. Utilisez https://clob.polymarket.com pour les lectures d'order-book et le trading ; les lectures sont publiques mais le trading nécessite API key + HMAC.

Dois-je utiliser des limit orders ou des market (FAK) orders pour l'arbitrage ?

Les FAK (Fill-And-Kill) market orders sont couramment utilisés pour la vitesse et pour éviter une exposition qui traîne. Ils peuvent être partiellement fillés, donc concevez le sizing et la réconciliation en conséquence. Le SDK CLOB expose des helpers pour créer des FAK market orders.

Comment prendre en compte les frais lors du sizing des trades ?

Soustrayez les taker fees attendues de votre edge brut avant de trader. Les taker fees varient par catégorie (0% à 1.8% actuellement). Utilisez un seuil d'edge net qui couvre les frais plus le slippage attendu et des marges pour le monitoring.

Quel monitoring est essentiel pour un bot live ?

Surveillez les taux de fill, le slippage réalisé, la latence, les avis de dispute UMA, les événements tick_size_change et la santé du Relayer. Implémentez des kill-switches soft et hard pour un slippage important, des drawdowns P&L ou des disputes d'oracle.

Puis-je router des ordres via le Builder Program ?

Oui. Le Builder Program permet à des tiers de router des ordres avec attribution et de gagner des builder fees. Les tiers contrôlent les limites quotidiennes du Relayer et les récompenses ; les identifiants s'obtiennent sur polymarket.com/settings.