Note di ingegneria Naly: Polymarket Gamma come livello riproducibile di snapshot di mercato

TL;DRL'ingestione di Polymarket Gamma offre a Naly una visione pubblica e strutturata di eventi, mercati, esiti, prezzi, tag e metadati di risoluzione dei prediction market. Naly usa questo livello per scegliere candidati per gli articoli, ancorare i riepiloghi sulle mispricing, supportare le storie di previsione KBO, preservare le citazioni delle fonti e creare snapshot di mercato durevoli per la verifica successiva. L'affermazione ingegneristica è semplice: la fiducia editoriale parte da input di mercato riproducibili, non dalla prosa generata.

Abstract

L'API Polymarket Gamma dovrebbe essere trattata come fonte Naly per la scoperta dei mercati e i metadati, non come interfaccia di trading. La documentazione ufficiale di Polymarket separa Gamma dalle API Data e CLOB: Gamma copre eventi, mercati, tag, serie, metadati sportivi, ricerca, commenti e profili pubblici, mentre CLOB gestisce book ordini, prezzi, spread e operazioni di trading autenticate. Per gli articoli Naly, questo confine è utile. La maggior parte dei workflow editoriali ha bisogno di testo della domanda, identità del mercato, etichette degli esiti, probabilità visualizzate, tag di categoria, scadenze e contesto di risoluzione prima di avere bisogno di dettagli tick-level sul book ordini.

La tesi di questa nota è che Naly dovrebbe acquisire Gamma in un livello versionato di snapshot di mercato. Uno snapshot non è la verità; è lo stato pubblico di mercato osservato in un momento specifico, legato agli URL delle fonti e preservato nei payload grezzi. Questo consente a Naly di pubblicare ciò che altri nascondono: il contesto di mercato, i limiti del segnale e l'evidenza esatta usata quando un articolo è stato generato.

Dove si colloca in Naly

L'ingestione di Gamma si colloca prima della generazione degli articoli e dopo la scoperta di fonti esterne. Nel percorso di pubblicazione di Naly, fornisce il lato prediction-market del pacchetto di evidenze per quattro usi downstream:

I riepiloghi sulle mispricing hanno bisogno di candidati evento e mercato correnti, con metadati sufficienti per confrontare le probabilità implicite del mercato con ragionamenti supportati da fonti.
Gli articoli di previsione KBO hanno bisogno di mercati sportivi, tag di squadra o evento, scadenze degli eventi ed etichette degli esiti che possano essere renderizzati senza contesto di mercato inserito manualmente.
Le citazioni delle fonti hanno bisogno di URL di mercato stabili, slug degli eventi e identificatori di mercato, così un lettore può verificare perché l'articolo ha discusso uno specifico contratto.
La verifica delle previsioni ha bisogno di snapshot storici, così la risoluzione successiva può essere valutata rispetto alla probabilità che Naly ha effettivamente visto al momento della pubblicazione.

I fatti sul runtime locale contano soprattutto per la forma, non per la novità. TypeScript 5.9 e tsx sono adatti agli script di ingestione; drizzle-orm con @neondatabase/serverless può conservare record normalizzati e JSON grezzo; Next.js 16 e React 19 possono renderizzare le pagine degli articoli risultanti; i pacchetti ai e Claude SDK possono consumare il pacchetto di evidenze preparato solo dopo che l'ingestione ha reso esplicito lo stato di mercato.

Meccanismo tecnico

Un solido ciclo di ingestione Gamma ha sei fasi.

Scoperta. Usa gli eventi Gamma quando Naly ha bisogno di una scoperta ampia dei mercati attivi, e usa slug di mercato o evento quando un articolo è ancorato a un URL Polymarket noto. La guida ai dati di mercato di Polymarket raccomanda gli eventi per una scoperta attiva completa perché gli eventi includono i mercati associati, riducendo le chiamate API. Per lavori di categoria come lo sport, tag e metadati sportivi dovrebbero restringere il crawl prima del ranking dei candidati.
Paginazione. Gamma supporta sia endpoint in stile offset sia endpoint keyset. Per crawl ampi o ripetuti, la paginazione keyset è più sicura perché next_cursor diventa il token di continuazione e offset viene esplicitamente rifiutato sull'endpoint keyset dei mercati. Per lavori di articoli più piccoli e mirati, la paginazione offset può essere ancora accettabile quando la finestra della query è stretta e l'output viene immediatamente snapshottato.
Normalizzazione. La regola chiave di normalizzazione è che le etichette degli esiti e i prezzi degli esiti devono essere mappati per posizione. La panoramica dei dati di mercato di Polymarket documenta gli array outcomes e outcomePrices come array uno-a-uno, quindi la disciplina degli indici conta. Un array scambiato non è un bug cosmetico; rovescia l'interpretazione del mercato dell'articolo.
Snapshotting. Conserva sia colonne normalizzate sia JSON grezzo. Le colonne normalizzate dovrebbero includere provider, timestamp di acquisizione, id o slug dell'evento, id o slug del mercato, testo della domanda, condition id quando presente, identificatori dei token quando presenti, etichette degli esiti, prezzi degli esiti, flag active e closed, end time, tag, URL della fonte e hash del payload. Il JSON grezzo protegge Naly dallo schema drift e consente alla verifica di riprodurre l'esatto artefatto di ingestione.
Punteggio dei candidati. I job degli articoli dovrebbero classificare i mercati usando criteri editoriali, non criteri di esecuzione del trading: freschezza, volume o liquidità dove disponibili, prossimità alla risoluzione, disponibilità di fonti, aderenza alla categoria e capacità del mercato di produrre un contrasto chiaro per il lettore. Il punteggio dei candidati non dovrebbe mai implicare che un prezzo di mercato sia automaticamente sbagliato; dovrebbe segnalare un mercato come degno di ricerca.
Vincolo di pubblicazione. Quando un articolo generato cita un mercato, l'articolo dovrebbe collegarsi all'id dello snapshot conservato, all'URL fonte di Polymarket e al set di evidenze esterne usato dall'autore. Questa è la differenza tra una pagina che dice che il mercato era al 62 percento e una pagina che può dimostrare quando, dove e da quale payload proveniva quel valore.

I rate limit fanno parte del meccanismo. Polymarket documenta throttling imposto da Cloudflare e limiti Gamma specifici per /events, /markets, /tags, e /public-search. Naly non ha bisogno di avvicinarsi a quei limiti per la pubblicazione quotidiana, quindi la postura corretta è conservativa: concorrenza limitata, retry con jitter, hash dei payload per idempotenza e alerting quando un job riceve risposte throttled, vuote o strutturalmente inattese.

Cosa dice la letteratura

Recenti lavori arXiv supportano il design snapshot-first. Jia et al. descrivono i dati dei prediction market decentralizzati come frammentati tra metadati off-chain, record di trading a livello di fill ed eventi di risoluzione oracle, poi argomentano a favore di un sistema relazionale unificato con risoluzione degli identificatori, aggiornamenti incrementali e meccanismi di coerenza. Il sistema di pubblicazione più piccolo di Naly ha la stessa classe di problema: i soli metadati di mercato non bastano se in seguito non possono essere uniti a prezzi, affermazioni degli articoli ed esiti di risoluzione.

Lo studio di calibrazione di Le è direttamente rilevante per il linguaggio degli articoli. Usando ampi dataset Kalshi e Polymarket, il paper sostiene che la calibrazione dipende da dominio, orizzonte ed effetti della dimensione delle operazioni; i consumatori che trattano i prezzi come probabilità a valore nominale possono interpretarli sistematicamente in modo errato. Per Naly, questo significa che un articolo dovrebbe dire probabilità implicita del mercato, prezzo osservato o segnale di mercato pubblico, non verità. L'articolo può discutere una possibile mispricing solo dopo aver separato l'osservazione grezza del mercato dal modello di Naly o dal ragionamento supportato da fonti.

Il paper di Dubach sulla microstruttura di Polymarket riguarda soprattutto i dati del book ordini, ma offre un avvertimento utile per il design dell'ingestione: l'evidenza di mercato ad alta frequenza ha modalità di errore specifiche della fonte, ritardi di ingestione e join che contano. Gamma è meno granulare dei feed del book ordini, ma si applica lo stesso principio. La fonte di un numero deve essere visibile. Uno snapshot Gamma, un midpoint CLOB e un record di trade on-chain sono correlati ma non intercambiabili.

Madrigal-Cianci, Monsalve Maya e Breakey inquadrano i prediction market come problemi inversi bayesiani in cui le storie di probabilità e volume osservate sono rumorose, endogene e modellate da tipi di trader eterogenei. Questo rafforza la postura editoriale di Naly. Lo stato di mercato acquisito è evidenza, non verdetto. Una buona ingegneria rende quell'incertezza ispezionabile invece di eliminarla durante la generazione.

Trade-off di design

Gamma rispetto a CLOB è il primo trade-off. Gamma offre a Naly scopribilità, contesto degli articoli e metadati. CLOB offre pricing più preciso e meccaniche del book ordini. Per articoli tecnici quotidiani e riepiloghi sui prediction market, Gamma dovrebbe essere l'input predefinito perché risponde a cosa riguarda il mercato. CLOB può essere aggiunto quando l'articolo ha bisogno di spread, midpoint o precisione della storia dei prezzi.

L'ingestione event-first rispetto a market-first è il secondo trade-off. Event-first è più economica per scansioni ampie perché un evento può contenere più mercati e metadati condivisi. Market-first è più pulita per la verifica perché il punteggio finale si collega a uno specifico esito binario. Naly dovrebbe acquisire entrambe le forme, ma fare in modo che i link degli articoli puntino alla claim a livello di mercato ogni volta che viene valutato un singolo esito.

JSON grezzo rispetto a schema tipizzato è il terzo trade-off. Il solo JSON grezzo è facile da conservare ma difficile da interrogare in sicurezza. Le sole colonne tipizzate sono facili da interrogare ma fragili quando i campi del provider evolvono. Il pattern durevole è entrambi: campi tipizzati per ranking, rendering e join; payload grezzi per audit, replay e migrazione.

Render live rispetto a render congelato è il quarto trade-off. Un widget di mercato live può essere utile, ma le affermazioni dell'articolo devono vincolarsi allo snapshot al momento della pubblicazione. Altrimenti, un vecchio articolo può cambiare significato silenziosamente quando Polymarket muove, chiude o risolve un mercato. Per la strategia di fiducia di Naly, l'evidenza congelata batte la freschezza quando una pagina fa un'affermazione datata.

Modalità di fallimento

Il fallimento più pericoloso è il disallineamento tra esito e prezzo. Se le etichette Yes e No vengono parsate separatamente dai prezzi, l'articolo può invertire il segnale pur continuando a sembrare plausibile.

Il secondo fallimento è il riuso di mercati stantii. Un mercato può essere active durante la scoperta e closed al momento della pubblicazione. Ogni job di articolo dovrebbe rivalidare i campi active, closed, archived ed end-time immediatamente prima di vincolare lo snapshot.

Il terzo fallimento è l'ambiguità multi-mercato. Un evento Polymarket può contenere diversi mercati negoziabili. Un riepilogo può citare l'evento, ma un record di verifica deve citare lo specifico mercato ed esito che Naly ha valutato.

Il quarto fallimento è lo schema drift. Le API pubbliche cambiano nomi dei campi, default e relazioni annidate. L'archiviazione degli snapshot dovrebbe includere hash dei payload, versione del parser, URL del provider ed errori di validazione, così il drift è osservabile.

Il quinto fallimento è sovrastimare la calibrazione. Un prezzo di mercato è un segnale pubblico utile, ma la letteratura avverte di non trattarlo come una probabilità pulita su tutti i domini e orizzonti. Il copy di Naly dovrebbe preservare la differenza tra probabilità implicita del mercato, stima Naly ed esito realizzato.

Il sesto fallimento è la perdita delle citazioni. Se un articolo conserva solo markdown renderizzato, la verifica successiva non può dimostrare quale pagina di mercato e quale payload supportavano l'affermazione. Le join articolo-mercato dovrebbero essere record di prima classe, non prosa incorporata.

Note di implementazione

Un'implementazione pratica di Naly può mantenere piccolo il contratto di ingestione:

provider: polymarket-gamma.
provider_url: l'esatto endpoint Gamma o URL pubblico di mercato usato per la scoperta.
fetched_at: timestamp del server in UTC.
event_key e market_key: identificatori o slug stabili del provider.
question: testo canonico della domanda di mercato.
outcomes: etichette ordinate.
outcome_prices: stringhe decimali ordinate normalizzate a valori numerici solo dopo la validazione.
status: flag active, closed, archived e publishability.
raw_payload: risposta completa del provider.
payload_hash: hash deterministico per idempotenza e replay.
parser_version: il contratto di codice che ha interpretato il payload.

Il generatore di articoli dovrebbe riceverlo come evidenza strutturata, non come testo prompt libero. Può quindi produrre markdown tramite lo stack AI esistente, renderizzare con la pipeline del sito e mantenere le citazioni collegate ai record fonte. Un worker di verifica può in seguito unire lo snapshot di mercato dell'articolo ai dati di risoluzione e valutare se l'affermazione pubblicata è invecchiata bene.

Il principio ingegneristico è deliberatamente conservativo: acquisisci, normalizza, crea snapshot, cita, poi scrivi. Questo ordine è più lento che chiedere a un modello di navigare e riassumere una pagina di mercato, ma crea l'artefatto di cui Naly ha davvero bisogno per acquisizione e retention: un articolo pubblico la cui evidenza di mercato può essere riprodotta dopo che il risultato è noto.