Note tecniche Naly: ingestione dell'API Gamma di Polymarket per articoli sul mercato delle previsioni

TL;DRNaly integra l'API Gamma di Polymarket come substrato deterministico di scoperta e pricing per tutti i flussi di mercato delle previsioni, sostituendo lo scraping ad hoc delle notizie con entità di mercato strutturate. A ogni ciclo, converte eventi e mercati in tempo reale in segnali pronti per gli articoli di mispricing, le anteprime KBO, i bundle di citazioni e la verifica degli esiti successiva, così la generazione delle storie parte sempre da probabilità osservabili pubblicamente e dalla struttura del mercato anziché da opinioni dedotte.

Sommario

Naly usa i dati del mercato delle previsioni come infrastruttura, non come semplice sovrapposizione, così gli artefatti editoriali diventano direttamente legati a uno stato di mercato esterno che può essere verificato in seguito. L'API Gamma fornisce un percorso di lettura per eventi, mercati, tag e prezzi senza richiedere chiavi a livello di wallet. La sfida di progettazione è mantenere quel layer di ingestione sufficientemente rigoroso per l'affidabilità, ma comunque abbastanza flessibile per i team di contenuto che hanno bisogno di una rapida scoperta degli argomenti.

Dove si colloca in Naly

L'ingestione di Polymarket Gamma si trova al confine upstream tra primitive di mercato grezze e asset editoriali pubblicabili. È il primo passo di una pipeline più ampia:

Livello di input: recupera eventi, mercati, tag e stati dei mercati da Gamma.
Livello di interpretazione: normalizza nello schema interno di Naly (event_id, market_id, ID token, esiti, probabilità, timestamp, flag attivo/chiuso).
Livello narrativo: fornisce input normalizzati ai flussi di redazione dei riepiloghi di mispricing e delle bozze di previsione KBO.
Livello di validazione: conserva gli stati dei mercati risolti/chiusi per la successiva verifica della verità degli articoli e le scorecard retrospettive.

Al 10 giugno 2026, questo è particolarmente coerente con tattiche attive che richiedono prove previsive affidabili e pronte per le citazioni: visibilità della calibrazione delle previsioni, sourcing dei contenuti ripetibile e flussi di verifica successivi.

Meccanismo tecnico

Polymarket definisce tre API, con Gamma come piano di scoperta pubblico per la navigazione di eventi/mercati e metadati, mentre i dati in stile order book/trading sono esposti da CLOB e i dati utente/posizioni dall'API Data (documentazione). Gamma e Data sono pubbliche secondo la documentazione Polymarket, mentre CLOB ha superfici private/trading che richiedono autenticazione per le operazioni sugli ordini.

Naly può implementare un flusso giornaliero robusto con soli endpoint pubblici:

Scopri mercati candidati attivi tramite GET /events con active=true, closed=false, paginazione (limit, offset), e filtri di ordinamento opzionali.
Espandi ai mercati componenti usando payload a livello di evento, poiché gli eventi includono i mercati associati e riducono le chiamate API rispetto a ricerche separate per mercato.
Target entità esatte usando chiamate basate su slug quando un evento o un mercato noto è già identificato.
Normalizza i prezzi mappando outcomes e outcomePrices gli array indice per indice in probabilità denominate.
Persisti artefatti di audit sia come righe normalizzate sia come snapshot raw, così ogni articolo può rintracciare ogni cifra da cui proviene.
Blocca la generazione a valle su controlli di freschezza + schema; snapshot obsoleti o incompleti sono marcati per il refresh prima dell'uso.

La documentazione Gamma descrive esattamente questa struttura operativa: endpoint pubblici come /events, /markets, /public-search, /tags, e /series sono disponibili per la scoperta, mentre paginazione e filtri sono supportati tramite limit/offset, tag_id, e filtri collegati. Fornisce anche raccomandazioni dirette per tre pattern di recupero: ricerca per slug, scoperta basata su tag ed enumerazione eventi per scansioni ampie. Per Naly, il pattern event-first è il più conveniente quando si costruiscono molti candidati giornalieri perché ogni evento può far emergere molti record di mercato.

Nella pratica, un record minimo di source-of-truth per Naly dovrebbe includere:

ID di evento e mercato
mercato question
clobTokenIds (per la riconciliazione dei prezzi a valle con CLOB quando necessario)
outcomes e outcomePrices
enableOrderBook
active, closed, e campi temporali (timestamp di inizio/fine)
timestamp di recupero e URL di origine

Sebbene Gamma possa già fornire una solida base probabilistica, un secondo percorso di raffinamento è opzionale: quando Naly richiede aggiornamenti intraday a intervalli più brevi, endpoint CLOB come /price, /priceso /book possono essere uniti successivamente.

Cosa dice la letteratura

La ricerca sui mercati delle previsioni supporta questo approccio data-first ma aggiunge guardrail interpretativi.

Il modello dei dati di mercato nei prediction market è utile solo se calibrato e interpretato correttamente; i prezzi non sono probabilità universali senza contesto. Uno studio del 2026 su Polymarket e Kalshi ha trovato pattern di calibrazione sistematici che variano per dominio e orizzonte, inclusa una sottoconfidenza misurabile in spazi specifici.
Un altro studio del 2026 focalizzato sul lifecycle sottolinea che l'analisi significativa dei mercati richiede un'ingegneria dati multi-livello sincronizzata: metadati di mercato, eventi di trading e segnali di risoluzione devono avere un collegamento esplicito e controlli periodici di coerenza, piuttosto che estrazioni isolate.
Lavori precedenti sulla microstruttura di mercato mostrano che i prezzi di mercato trasmettono informazioni dei trader in un flusso in stile asta continua, motivo per cui Naly può trattare i prezzi di mercato come segnali previsivi collettivi, pur mantenendo la validazione degli esiti nel tempo.
La letteratura di forecasting che confronta i prezzi di mercato con altri metodi (ad esempio il forecasting basato su sondaggi) mostra che i mercati delle previsioni possono essere fortemente predittivi, ma solo quando la verifica degli esiti e la disciplina del modello sono preservate.

La conseguenza pratica per Naly è semplice: acquisisci tutto con provenienza, non trattare mai uno snapshot di prezzo singolo come verità finale, e separa readiness (freschezza + integrità dei dati) da story quality (impostazione editoriale).

Compromessi di design

Naly ottimizza intenzionalmente per l'affidabilità piuttosto che per la velocità nell'ingestione.

Solo Gamma vs Gamma+CLOB: Gamma offre scoperta stabile e contesto pubblico rapidamente; aggiungere CLOB migliora la ricchezza della microstruttura ma introduce autenticazione e maggiore complessità degli endpoint.
Snapshot giornaliero vs streaming continuo: un pull programmato deterministico è più facile da auditare e riprodurre rispetto agli stream continui, ma perde i cambi di regime sub-minuto.
Pull event-first vs pull market-first: event-first riduce le chiamate duplicate e migliora la copertura contestuale; market-first offre una dimensione payload leggermente inferiore per compiti ristretti.
Schema ampio vs schema rigoroso: uno schema JSON-first ampio accelera l'integrazione ma aumenta il rischio di drift dello schema; una normalizzazione rigorosa rileva il drift prima, ma aumenta l'overhead di migrazione.
Campi generalizzati vs campi specifici per dominio: usare campi condivisi migliora il riuso tra articoli; aggiungere estensioni specifiche per dominio (ad esempio finestre di confidenza specifiche per lo sport) aumenta la precisione immediata ma può frammentare la manutenzione nel lungo periodo.

Dato l'obiettivo di fiducia e retention di Naly, riproducibilità rigorosa e qualità delle citazioni dovrebbero prevalere sull'ottimizzazione immediata della latenza.

Modalità di guasto

Le principali modalità di guasto sono operative, non algoritmiche.

Dati mancanti per bug di paginazione: se limit e offset le finestre cambiano tra i poll, possono comparire duplicati o buchi. Mitigazione: checkpoint dei cursori di paginazione ed applicazione di upsert idempotenti.
Predefinito closed=false perdita del contesto storico: i pull open-market omettono elementi risolti a meno che closed=true non venga richiesto esplicitamente. Mitigazione: eseguire un percorso di backfill storico dedicato per i compiti di verifica.
Instabilità dello slug: URL di prodotto e slug leggibili dall'utente possono spostarsi. Mitigazione: preferire gli ID primari internamente e mantenere lo slug come chiave secondaria.
Drift semantico dei campi outcomes/outcomePrices l'interpretazione può fallire se le assunzioni sull'ordine dello schema sono errate. Mitigazione: verificare l'allineamento degli array e i controlli di lunghezza in ingest.
Disponibilità transitoria dell'API o throttling: gli endpoint pubblici possono fallire o restituire payload parziali. Mitigazione: retry con exponential backoff, poison-queue su guasti ripetuti, e mantenimento degli snapshot precedenti.
Risoluzione tardiva e narrazioni stale: gli articoli di verifica possono essere eseguiti prima che il settlement si chiuda in modo pulito. Mitigazione: memorizzare lo stato di settlement come parte dello stato di pubblicazione e aggiornare a posteriori con un log di correzioni immutabile.

Data la strategia trust-first di Naly, la pipeline dovrebbe fallire in modalità closed: meglio ritardare un articolo che pubblicare con uno stato di mercato non verificabile.

Note di implementazione

Con lo stack runtime indicato, un'implementazione pratica resta lineare:

Usa i server handler di Next.js (next@16.0.7) per ospitare endpoint di ingestione e job pianificati.
Persisti righe normalizzate in Neon usando drizzle-orm@^0.44.7 su @neondatabase/serverless@^1.0.2 con vincoli univoci espliciti sugli identificativi di mercato.
Salva snapshot raw dei payload in Vercel Blob (@vercel/blob@^2.0.0) per auditabilità e confronto "post-mortem".
Mantieni la generazione della sorgente markdown e l'assemblaggio degli articoli fuori dal core di ingestione; usa marked@^17.0.1 per trasformazioni sicure e ai@6.0.0-beta.105 oltre @anthropic-ai/claude-agent-sdk@^0.2.15 solo dopo che i controlli di integrità dei dati risultano positivi.
Usa tsx@^4.21.0/typescript@^5.9.3 per replay riproducibili one-off quando fai backfill di finestre storiche.

Il 10 giugno 2026, l'architettura dovrebbe dare priorità a tre output concreti: immutabilità degli snapshot raw, proiezione deterministica nello schema interno e una catena di audit orientata alla verifica, dall'URL API sorgente alla citazione finale dell'articolo.