Notes d'ingénierie Naly : Polymarket Gamma comme couche de snapshots de marché reproductibles

TL;DRL'ingestion de Polymarket Gamma donne à Naly une vue publique et structurée des événements de marchés de prédiction, des marchés, des résultats, des prix, des tags et des métadonnées de résolution. Naly utilise cette couche pour choisir des candidats d'articles, ancrer des synthèses de mauvaises valorisations, soutenir les articles de prédiction KBO, préserver les citations de sources et créer des snapshots de marché durables pour vérification ultérieure. L'affirmation d'ingénierie est simple : la confiance éditoriale commence par un intrant de marché reproductible, pas par une prose générée.

Résumé

L'API Polymarket Gamma doit être traitée comme la source de découverte de marchés et de métadonnées de Naly, et non comme une interface de trading. La documentation officielle de Polymarket distingue Gamma des API Data et CLOB : Gamma couvre les événements, les marchés, les tags, les séries, les métadonnées sportives, la recherche, les commentaires et les profils publics, tandis que CLOB gère les carnets d'ordres, les prix, les spreads et les opérations de trading authentifiées. Pour les articles de Naly, cette frontière est utile. La plupart des workflows éditoriaux ont besoin du texte de la question, de l'identité du marché, des libellés de résultats, des probabilités affichées, des tags de catégorie, des échéances et du contexte de résolution avant d'avoir besoin de détails de carnet d'ordres au tick près.

La thèse de cette note est que Naly devrait ingérer Gamma dans une couche de snapshots de marché versionnée. Un snapshot n'est pas la vérité ; c'est l'état public observé du marché à un moment précis, lié aux URL sources et préservé avec les charges utiles brutes. Cela permet à Naly de publier ce que les autres cachent : le contexte de marché, les limites du signal et les preuves exactes utilisées lorsqu'un article a été généré.

Sa place dans Naly

L'ingestion Gamma se situe avant la génération d'articles et après la découverte de sources externes. Dans le chemin de publication de Naly, elle fournit le volet marché de prédiction du paquet de preuves pour quatre usages en aval :

Les synthèses de mauvaises valorisations ont besoin de candidats d'événements et de marchés actuels, avec assez de métadonnées pour comparer les probabilités implicites du marché au raisonnement appuyé par des sources.
Les articles de prédiction KBO ont besoin de marchés sportifs, de tags d'équipes ou d'événements, d'échéances d'événements et de libellés de résultats pouvant être rendus sans contexte de marché saisi manuellement.
Les citations de sources ont besoin d'URL de marché stables, de slugs d'événements et d'identifiants de marchés afin qu'un lecteur puisse auditer pourquoi l'article a discuté d'un contrat précis.
La vérification des prédictions a besoin de snapshots historiques afin que la résolution ultérieure puisse être notée par rapport à la probabilité que Naly a réellement vue au moment de la publication.

Les faits d'exécution locaux comptent surtout pour la forme, pas pour la nouveauté. TypeScript 5.9 et tsx conviennent raisonnablement aux scripts d'ingestion ; drizzle-orm avec @neondatabase/serverless peut persister des enregistrements normalisés et du JSON brut ; Next.js 16 et React 19 peuvent rendre les pages d'articles résultantes ; les packages ai et Claude SDK peuvent consommer le paquet de preuves préparé seulement après que l'ingestion a rendu explicite l'état du marché.

Mécanisme technique

Une boucle d'ingestion Gamma robuste comporte six étapes.

Découverte. Utilisez les événements Gamma lorsque Naly a besoin d'une découverte large de marchés actifs, et utilisez les slugs de marché ou d'événement lorsqu'un article est ancré à une URL Polymarket connue. Le guide des données de marché de Polymarket recommande les événements pour une découverte active complète, car les événements incluent les marchés associés, ce qui réduit les appels API. Pour un travail par catégorie, comme le sport, les tags et les métadonnées sportives devraient restreindre l'exploration avant le classement des candidats.
Pagination. Gamma prend en charge à la fois des endpoints de style offset et des endpoints keyset. Pour une exploration volumineuse ou répétée, la pagination keyset est plus sûre car next_cursor devient le jeton de continuation et offset est explicitement rejeté sur l'endpoint keyset des marchés. Pour des travaux d'articles plus petits et ciblés, la pagination offset peut encore être acceptable lorsque la fenêtre de requête est étroite et que la sortie est immédiatement snapshottée.
Normalisation. La règle clé de normalisation est que les libellés de résultats et les prix de résultats doivent être mappés par position. La vue d'ensemble des données de marché de Polymarket documente outcomes et outcomePrices comme des tableaux en correspondance un-à-un, donc la discipline des index compte. Un tableau permuté n'est pas un bogue cosmétique ; il inverse l'interprétation du marché dans l'article.
Snapshotting. Stockez à la fois des colonnes normalisées et le JSON brut. Les colonnes normalisées devraient inclure le fournisseur, l'horodatage de récupération, l'id ou le slug de l'événement, l'id ou le slug du marché, le texte de la question, l'id de condition lorsqu'il est présent, les identifiants de jetons lorsqu'ils sont présents, les libellés de résultats, les prix de résultats, les indicateurs actif et fermé, l'heure de fin, les tags, l'URL source et le hash de la charge utile. Le JSON brut protège Naly contre la dérive de schéma et permet à la vérification de rejouer l'artéfact exact d'ingestion.
Notation des candidats. Les travaux d'articles devraient classer les marchés selon des critères éditoriaux, et non des critères d'exécution de trading : fraîcheur, volume ou liquidité lorsque disponible, proximité de la résolution, disponibilité des sources, adéquation à la catégorie et capacité du marché à produire un contraste clair pour le lecteur. La notation des candidats ne devrait jamais impliquer qu'un prix de marché est automatiquement faux ; elle devrait signaler qu'un marché mérite une recherche.
Liaison à la publication. Lorsqu'un article généré cite un marché, l'article devrait lier l'id du snapshot stocké, l'URL source Polymarket et l'ensemble de preuves externes utilisé par le rédacteur. C'est la différence entre une page qui dit que le marché était à 62 % et une page capable de prouver quand, où et à partir de quelle charge utile cette valeur provenait.

Les limites de débit font partie du mécanisme. Polymarket documente un throttling imposé par Cloudflare et des limites Gamma spécifiques pour /events, /markets, /tags, et /public-search. Naly n'a pas besoin d'approcher ces limites pour la publication quotidienne, donc la bonne posture est conservatrice : concurrence bornée, relance avec jitter, hashes de charges utiles pour l'idempotence et alertes lorsqu'un travail reçoit des réponses ralenties, vides ou structurellement inattendues.

Ce que dit la littérature

Des travaux récents sur arXiv soutiennent la conception snapshot-first. Jia et al. décrivent les données des marchés de prédiction décentralisés comme fragmentées entre métadonnées off-chain, enregistrements de trading au niveau des exécutions et événements de résolution par oracle, puis plaident pour un système relationnel unifié avec résolution d'identifiants, mises à jour incrémentales et mécanismes de cohérence. Le système de publication plus restreint de Naly rencontre la même classe de problème : les métadonnées de marché seules ne suffisent pas, sauf si elles peuvent ensuite être jointes aux prix, aux affirmations d'articles et aux résultats de résolution.

L'étude de calibration de Le est directement pertinente pour le langage des articles. À partir de grands jeux de données Kalshi et Polymarket, l'article soutient que la calibration dépend du domaine, de l'horizon et des effets de taille de transaction ; les consommateurs qui traitent les prix comme des probabilités nominales peuvent les interpréter systématiquement de travers. Pour Naly, cela signifie qu'un article devrait dire probabilité implicite du marché, prix observé ou signal de marché public, et non vérité. L'article peut discuter d'une possible mauvaise valorisation seulement après avoir séparé l'observation brute du marché du modèle de Naly ou du raisonnement appuyé par des sources.

L'article de Dubach sur la microstructure de Polymarket porte surtout sur les données de carnet d'ordres, mais il donne un avertissement utile pour la conception de l'ingestion : les preuves de marché à haute fréquence ont des modes d'erreur propres à la source, des délais d'ingestion et des jointures qui comptent. Gamma est moins granulaire que les flux de carnet d'ordres, mais le même principe s'applique. La source d'un nombre doit être visible. Un snapshot Gamma, un midpoint CLOB et un enregistrement de transaction on-chain sont liés, mais pas interchangeables.

Madrigal-Cianci, Monsalve Maya et Breakey présentent les marchés de prédiction comme des problèmes inverses bayésiens où les historiques de probabilités observées et de volumes sont bruités, endogènes et façonnés par des types de traders hétérogènes. Cela renforce la position éditoriale de Naly. L'état de marché ingéré est une preuve, pas un verdict. Une bonne ingénierie rend cette incertitude inspectable au lieu de l'effacer pendant la génération.

Compromis de conception

Gamma contre CLOB est le premier compromis. Gamma donne à Naly la découvrabilité, le contexte d'article et les métadonnées. CLOB donne une tarification plus précise et les mécaniques de carnet d'ordres. Pour les articles d'ingénierie quotidiens et les synthèses de marchés de prédiction, Gamma devrait être l'intrant par défaut, car il répond à la question de ce dont parle le marché. CLOB peut être ajouté lorsque l'article a besoin de précision sur le spread, le midpoint ou l'historique des prix.

L'ingestion event-first contre market-first est le deuxième compromis. L'event-first est moins coûteux pour les scans larges, car un événement peut contenir plusieurs marchés et des métadonnées partagées. Le market-first est plus propre pour la vérification, car la note finale s'attache à un résultat binaire précis. Naly devrait ingérer les deux formes, mais faire pointer les liens d'article vers l'affirmation au niveau du marché lorsqu'un seul résultat est évalué.

Le JSON brut contre le schéma typé est le troisième compromis. Le JSON brut seul est facile à stocker mais difficile à interroger sans risque. Les colonnes typées seules sont faciles à interroger mais fragiles lorsque les champs du fournisseur évoluent. Le modèle durable consiste à garder les deux : champs typés pour le classement, le rendu et les jointures ; charges utiles brutes pour l'audit, le rejeu et la migration.

Le rendu en direct contre le rendu figé est le quatrième compromis. Un widget de marché en direct peut être utile, mais les affirmations de l'article doivent se lier au snapshot au moment de la publication. Sinon, un ancien article peut changer silencieusement de sens lorsque Polymarket fait bouger, ferme ou résout un marché. Pour la stratégie de confiance de Naly, une preuve figée vaut mieux que la fraîcheur lorsqu'une page avance une affirmation datée.

Modes de défaillance

La défaillance la plus dangereuse est le désalignement entre résultat et prix. Si les libellés Yes et No sont analysés séparément des prix, l'article peut inverser le signal tout en restant plausible.

La deuxième défaillance est la réutilisation de marchés périmés. Un marché peut être actif lors de la découverte et fermé au moment de la publication. Chaque travail d'article devrait revalider les champs actif, fermé, archivé et heure de fin immédiatement avant de lier le snapshot.

La troisième défaillance est l'ambiguïté multi-marchés. Un événement Polymarket peut contenir plusieurs marchés négociables. Une synthèse peut citer l'événement, mais un enregistrement de vérification doit citer le marché et le résultat précis que Naly a évalués.

La quatrième défaillance est la dérive de schéma. Les API publiques changent les noms de champs, les valeurs par défaut et les relations imbriquées. Le stockage des snapshots devrait inclure les hashes de charges utiles, la version du parseur, l'URL du fournisseur et les erreurs de validation afin que la dérive soit observable.

La cinquième défaillance est de suraffirmer la calibration. Un prix de marché est un signal public utile, mais la littérature met en garde contre le fait de le traiter comme une probabilité propre à travers tous les domaines et horizons. La copie de Naly devrait préserver la différence entre probabilité implicite du marché, estimation de Naly et résultat réalisé.

La sixième défaillance est la perte de citation. Si un article ne stocke que le markdown rendu, la vérification ultérieure ne peut pas prouver quelle page de marché et quelle charge utile soutenaient l'affirmation. Les jointures article-marché devraient être des enregistrements de première classe, pas de la prose intégrée.

Notes d'implémentation

Une implémentation Naly pratique peut garder le contrat d'ingestion restreint :

provider: polymarket-gamma.
provider_url: l'endpoint Gamma exact ou l'URL de marché publique utilisé pour la découverte.
fetched_at: horodatage serveur en UTC.
event_key et market_key: identifiants ou slugs stables du fournisseur.
question: texte canonique de la question du marché.
outcomes: libellés ordonnés.
outcome_prices: chaînes décimales ordonnées normalisées en valeurs numériques seulement après validation.
status: indicateurs actif, fermé, archivé et publiable.
raw_payload: réponse complète du fournisseur.
payload_hash: hash déterministe pour l'idempotence et le rejeu.
parser_version: le contrat de code qui a interprété la charge utile.

Le générateur d'articles devrait recevoir cela comme preuve structurée, et non comme texte de prompt lâche. Il peut ensuite produire du markdown via la pile d'IA existante, effectuer le rendu avec le pipeline du site et garder les citations attachées aux enregistrements sources. Un worker de vérification peut ensuite joindre le snapshot de marché de l'article aux données de résolution et noter si l'affirmation publiée a bien résisté au temps.

Le principe d'ingénierie est délibérément conservateur : ingérer, normaliser, snapshotter, citer, puis écrire. Cet ordre est plus lent que de demander à un modèle de parcourir et résumer une page de marché, mais il crée l'artéfact dont Naly a réellement besoin pour l'acquisition et la rétention : un article public dont les preuves de marché peuvent être rejouées après que le résultat est connu.