Notes d’ingénierie Naly : ingestion de l’API Gamma de Polymarket pour les articles sur les marchés prédictifs

TL;DRNaly ingère l’API Gamma de Polymarket comme un substrat déterministe de découverte et de tarification pour l’ensemble des flux liés aux marchés prédictifs, remplaçant les extractions ad hoc d’actualités par des entités de marché structurées. À chaque cycle, il transforme les événements et marchés en direct en signaux prêts à être utilisés dans des synthèses de décalage de prix, des aperçus KBO, des lots de citations et des vérifications de résultats ultérieures, afin que la génération des contenus parte toujours de probabilités observables publiquement et de la structure du marché plutôt que d’opinions inférées.

Résumé

Naly utilise les données de marché prédictif comme infrastructure, pas comme simple surcouche, afin que les artefacts éditoriaux soient directement liés à un état de marché externe pouvant être audité ultérieurement. L’API Gamma fournit un accès en lecture aux événements, marchés, tags et prix sans nécessiter de clés au niveau du portefeuille. Le défi de conception est de maintenir cette couche d’ingestion suffisamment stricte pour la fiabilité tout en restant suffisamment souple pour les équipes de contenu qui ont besoin d’une découverte rapide des sujets.

Positionnement dans Naly

L’ingestion de Gamma de Polymarket se situe à la frontière amont entre les primitives de marché brutes et les actifs éditoriaux publiables. C’est la première étape d’un pipeline plus large :

Couche d’entrée : récupérer les événements, marchés, tags et statuts de marché depuis Gamma.
Couche d’interprétation : normaliser dans le schéma interne de Naly (event_id, market_id, identifiants de jetons, issues, probabilités, horodatages, indicateurs actif/clos).
Couche narrative : injecter les entrées normalisées dans les flux de synthèse de sous-valorisation et de rédaction des prévisions KBO.
Couche de validation : conserver les états de marché résolus/clos pour la vérification ultérieure de la vérité des articles et les scorecards rétrospectives.

Au 10 juin 2026, ce point est particulièrement aligné avec les tactiques actives qui exigent des preuves de prévision fiables et prêtes à être citées : visibilité de la calibration des prévisions, sourcing éditorial répétable et workflows de vérification ultérieurs.

Mécanisme technique

Polymarket définit trois API, avec Gamma comme couche de découverte publique pour la consultation des événements/marchés et des métadonnées, tandis que le carnet d’ordres et les données de trading sont exposés par la CLOB et les données utilisateur/positions par la Data API (docs). Selon la documentation Polymarket, Gamma et Data sont publiques, tandis que la CLOB dispose de surfaces privées/trading qui requièrent une authentification pour les opérations d’ordre.

Naly peut implémenter un flux quotidien robuste avec uniquement des endpoints publics :

Découvrir les marchés candidats actifs via GET /events avec active=true, closed=false, la pagination (limit, offset), et des filtres de tri optionnels.
Étendre aux marchés constitutifs en utilisant les charges utiles au niveau de l’événement, car les événements portent les marchés associés et réduisent les appels API par rapport aux recherches de marché séparées.
Cibler les entités exactes grâce aux appels basés sur les slugs lorsqu’un événement ou marché connu est déjà identifié.
Normaliser les prix en mappant outcomes et outcomePrices les tableaux index par index en probabilités nommées.
Persister les artefacts d’audit sous forme de lignes normalisées et de snapshots bruts afin que chaque article puisse tracer chaque valeur sourcée.
Conditionner la génération en aval à la fraîcheur + aux vérifications de schéma ; les snapshots périmés ou incomplets sont marqués pour rafraîchissement avant utilisation.

La documentation Gamma décrit exactement cette forme opérationnelle : des endpoints publics tels que /events, /markets, /public-search, /tags, et /series sont disponibles pour la découverte, tandis que la pagination et le filtrage sont pris en charge via limit/offset, tag_id, et les filtres associés. Elle fournit également des recommandations directes pour trois patterns de récupération : recherche par slug, découverte basée sur les tags et énumération d’événements pour les scans larges. Pour Naly, le pattern centré événement est le plus rentable en coûts lors de la construction d’un grand nombre de candidats quotidiens, car chaque événement peut remonter de nombreux enregistrements de marché.

En pratique, un enregistrement de vérité source minimal pour Naly devrait inclure :

les identifiants d’événement et de marché
marché question
clobTokenIds (pour la réconciliation de prix en aval avec la CLOB si nécessaire)
outcomes et outcomePrices
enableOrderBook
active, closed, ainsi que les champs temporels (horodatages de début/fin)
l’horodatage de récupération et l’URL source

Bien que Gamma puisse déjà fournir une bonne base probabiliste, un second chemin d’affinage est optionnel : quand Naly a besoin de mises à jour intrajournalières à plus faible intervalle, des endpoints CLOB comme /price, /prices, /book peuvent être intégrés ultérieurement.

Ce que dit la littérature

La recherche sur les marchés prédictifs soutient cette approche axée sur la donnée, mais ajoute des garde-fous autour de l’interprétation.

Le modèle de données de marché dans les marchés prédictifs n’est utile que s’il est calibré et correctement interprété ; les prix ne sont pas des probabilités universelles sans contexte. Une étude de 2026 sur Polymarket et Kalshi a mis en évidence des motifs de calibration systématiques qui varient selon le domaine et l’horizon, notamment une sous-confiance mesurable dans certains espaces.
Une autre étude de 2026 centrée sur le cycle de vie souligne qu’une analyse de marché significative nécessite une ingénierie de données multi-couches synchronisée : les métadonnées de marché, les événements de trading et les signaux de règlement doivent être explicitement liés et soumis à des contrôles de cohérence périodiques, plutôt qu’à des requêtes isolées.
Des travaux antérieurs sur la microstructure des marchés montrent que les prix de marché transmettent l’information des traders dans un flux de type enchères continues, ce qui explique pourquoi Naly peut traiter les prix de marché comme des signaux de prévision collectifs tout en validant les résultats dans le temps.
La littérature de prévision qui compare les prix de marché à d’autres méthodes (par exemple la prévision basée sur les enquêtes) montre que les marchés prédictifs peuvent être fortement prédictifs, mais seulement lorsque la vérification des résultats et la discipline de modélisation sont préservées.

La conséquence pratique pour Naly est simple : ingérer chaque donnée avec sa provenance, ne jamais considérer un instantané de prix isolé comme une vérité finale, et séparer readiness (fraîcheur + intégrité des données) de story quality (la narration éditoriale).

Compromis de conception

Naly optimise intentionnellement la fiabilité au détriment de la vitesse lors de l’ingestion.

Gamma seul vs Gamma + CLOB : Gamma fournit rapidement une découverte stable et un contexte public ; ajouter la CLOB améliore la richesse de la microstructure mais ajoute de la complexité d’authentification et d’endpoints.
Snapshot quotidien vs streaming continu : une extraction planifiée déterministe est plus facile à auditer et à reproduire que des flux continus, mais elle ne capte pas les changements de régime au sous-minute.
Extraction événement d’abord vs extraction marché d’abord : événement d’abord réduit les appels dupliqués et améliore la couverture contextuelle ; marché d’abord offre une taille de payload légèrement plus faible pour des tâches ciblées.
Schéma large vs schéma strict : un schéma large orienté JSON accélère l’intégration mais augmente le risque de dérive de schéma ; une normalisation stricte détecte plus tôt les dérives mais augmente la charge de migration.
Champs généralisés vs champs spécifiques au domaine : l’usage de champs partagés améliore la réutilisation entre articles ; ajouter des extensions spécifiques au domaine (par ex. fenêtres de confiance propres au sport) augmente la précision immédiate mais peut fragmenter la maintenance à long terme.

Compte tenu de l’objectif de Naly de confiance et de rétention, la reproductibilité stricte et la qualité de citation doivent primer sur l’optimisation immédiate de la latence.

Modes de défaillance

Les plus grands modes de défaillance sont opérationnels, pas algorithmiques.

Données manquantes dues à des bugs de pagination : si limit et offset les fenêtres changent entre les sondages, des doublons ou des trous peuvent apparaître. Mitigation : checkpoint des curseurs de pagination et application d’upserts idempotents.
Par défaut closed=false perte du contexte historique : les pulls de marché ouvert omettent les éléments résolus sauf si closed=true la demande est explicite. Mitigation : exécuter un chemin dédié de backfill historique pour les tâches de vérification.
Instabilité des slugs : les URLs produit et slugs lisibles par l’homme peuvent dériver. Mitigation : privilégier en interne les identifiants primaires et conserver le slug comme clé secondaire.
Dérive sémantique des champs : outcomes/outcomePrices l’interprétation peut se casser si les hypothèses d’ordre du schéma sont erronées. Mitigation : valider l’alignement des tableaux et les contrôles de longueur lors de l’ingestion.
Disponibilité transitoire de l’API ou throttling : les endpoints publics peuvent échouer ou renvoyer des payloads partiels. Mitigation : retry avec backoff exponentiel, queue de poison en cas d’échecs répétés, et conservation des snapshots précédents.
Règlement tardif et narratifs obsolètes : les articles de vérification peuvent s’exécuter avant que la liquidation ne soit nette. Mitigation : stocker le statut de règlement dans l’état de publication et effectuer des mises à jour postérieures via un journal de correction immuable.

Compte tenu de la stratégie trust-first de Naly, le pipeline doit fonctionner en mode échec sécurisé : mieux vaut retarder un article que publier avec un état de marché non vérifiable.

Notes d’implémentation

Avec la stack d’exécution indiquée, une implémentation pratique reste simple :

Utiliser les gestionnaires de serveur Next.js (next@16.0.7) pour héberger les endpoints d’ingestion et les jobs planifiés.
Persister les lignes normalisées dans Neon via drizzle-orm@^0.44.7 sur @neondatabase/serverless@^1.0.2 avec des contraintes d’unicité explicites sur les identifiants du marché.
Conserver les snapshots de payload bruts dans Vercel Blob (@vercel/blob@^2.0.0) pour l’auditabilité et les diff post-mortem.
Conserver la génération de la source markdown et l’assemblage des articles hors du cœur de l’ingestion ; utiliser marked@^17.0.1 pour des transformations sûres et ai@6.0.0-beta.105 plus @anthropic-ai/claude-agent-sdk@^0.2.15 uniquement après la validation des contrôles d’intégrité des données.
Utiliser tsx@^4.21.0/typescript@^5.9.3 pour des relectures ponctuelles reproductibles lors du backfill de fenêtres historiques.

Le 10 juin 2026, l’architecture doit prioriser trois livrables clés : l’immutabilité du snapshot brut, la projection déterministe dans le schéma interne, et une trace d’audit orientée vérification, de l’URL de l’API source jusqu’à la citation finale de l’article.