Notas de Engenharia da Naly: Ingestão da API Gamma da Polymarket para artigos de mercados de previsão

TL;DRA Naly ingere a API Gamma da Polymarket como um substrato determinístico de descoberta e precificação para todos os fluxos de mercado de previsão, substituindo raspagens de notícias ad hoc por entidades de mercado estruturadas. Em cada ciclo, converte eventos e mercados ao vivo em sinais prontos para artigos de resumos de mispricing, prévias de KBO, pacotes de citações e verificação posterior de desfecho, para que a geração de histórias comece sempre a partir de probabilidades observáveis publicamente e da estrutura de mercado em vez de opiniões inferidas.

Resumo

A Naly está usando dados de mercado de previsão como infraestrutura, não como uma sobreposição, de modo que artefatos editoriais ficam diretamente ligados a um estado de mercado externo que pode ser auditado depois. A API Gamma oferece um caminho de leitura para eventos, mercados, tags e preços sem exigir chaves em nível de carteira. O desafio de design é manter essa camada de ingestão rígida o suficiente para confiabilidade e ainda flexível para equipes de conteúdo que precisam de descoberta rápida de tópicos.

Onde ela se encaixa na Naly

A ingestão da Polymarket Gamma fica na fronteira a montante entre primitivas brutas de mercado e ativos editoriais publicáveis. É o primeiro passo de um pipeline mais amplo:

Camada de entrada: buscar eventos, mercados, tags e estados de mercado no Gamma.
Camada de interpretação: normalizar no esquema interno da Naly (event_id, market_id, IDs de token, resultados, probabilidades, timestamps, flags ativo/encerrado).
Camada narrativa: alimentar entradas normalizadas para os fluxos de redação de mispricing e prévias de KBO.
Camada de validação: manter estados de mercado resolvidos/encerrados para checagem posterior da veracidade do artigo e scorecards retrospectivos.

Em 10 de junho de 2026, isso está particularmente alinhado com táticas ativas que exigem evidência de previsão confiável pronta para citação: visibilidade de calibração de previsão, sourcing de conteúdo repetível e fluxos de verificação posteriores.

Mecanismo técnico

A Polymarket define três APIs, com a Gamma como plano de descoberta público para navegação e metadados de evento/mercado, enquanto dados de livro de ofertas e estilo de negociação são expostos pelo CLOB e dados de usuário/posições pela Data API (docs). Gamma e Data são públicas conforme a documentação da Polymarket, enquanto o CLOB possui superfícies privadas de negociação que exigem autenticação para operações de ordem.

A Naly pode implementar um fluxo diário robusto com apenas endpoints públicos:

Descobrir mercados candidatos ativos via GET /events com active=true, closed=false, paginação (limit, offset), e filtros de ordenação opcionais.
Expandir para mercados componentes usando payloads em nível de evento, já que os eventos trazem mercados associados e reduzem chamadas de API em comparação com consultas de mercado separadas.
Alvo de entidades exatas usando chamadas baseadas em slug quando um evento ou mercado conhecido já foi identificado.
Normalizar preços mapeando outcomes e outcomePrices arrays índice a índice em probabilidades nomeadas.
Persistir artefatos de auditoria como linhas normalizadas e snapshots brutos para que cada artigo possa rastrear cada figura de origem.
Travar geração downstream em verificações de atualidade + esquema; snapshots obsoletos ou incompletos são marcados para atualização antes do uso.

A documentação da Gamma descreve exatamente essa forma operacional: endpoints públicos como /events, /markets, /public-search, /tags, e /series estão disponíveis para descoberta, enquanto paginação e filtragem são suportadas via limit/offset, tag_id, e filtros relacionados. Ela também fornece recomendações diretas para três padrões de recuperação: busca por slug, descoberta baseada em tag e enumeração de eventos para varreduras amplas. Para a Naly, o padrão event-first é o mais custo-efetivo ao construir grandes candidatas diárias porque cada evento pode revelar muitos registros de mercado.

Na prática, um registro mínimo de verdade-fonte para a Naly deve incluir:

IDs de evento e mercado
mercado question
clobTokenIds (para reconciliação de preço downstream com o CLOB quando necessário)
outcomes e outcomePrices
enableOrderBook
active, closed, e campos temporais (timestamps de início/fim)
timestamp de busca e URL de origem

Embora a Gamma já possa fornecer uma base probabilística forte, um caminho de refinamento secundário é opcional: quando a Naly precisa de atualizações intradiárias com intervalo menor, endpoints do CLOB como /price, /prices, ou /book podem ser mesclados depois.

O que diz a literatura

Pesquisas sobre mercados de previsão apoiam essa abordagem orientada por dados, mas adicionam guardrails em torno da interpretação.

O modelo de dados de mercado em mercados de previsão só é útil se estiver calibrado e interpretado corretamente; preços não são probabilidades universais sem contexto. Um estudo de 2026 sobre Polymarket e Kalshi encontrou padrões de calibração sistemáticos que variam por domínio e horizonte, incluindo subestimação mensurável em espaços específicos.
Outro estudo de 2026 focado no ciclo de vida enfatiza que uma análise de mercado significativa exige engenharia de dados em camadas sincronizadas: metadados de mercado, eventos de negociação e sinais de resolução precisam de ligação explícita e checagens periódicas de consistência, em vez de coletas isoladas.
Trabalhos anteriores sobre microestrutura mostram que os preços de mercado transmitem informação de traders sob um fluxo estilo leilão contínuo, razão pela qual a Naly pode tratar preços de mercado como sinais de previsão coletivos enquanto ainda valida desfechos ao longo do tempo.
A literatura de previsão que compara preços de mercado com outros métodos (por exemplo, previsão baseada em pesquisa) mostra que os mercados de previsão podem ser fortemente preditivos, mas apenas quando a verificação de desfecho e a disciplina de modelo são preservadas.

A consequência prática para a Naly é direta: ingira tudo com proveniência, nunca trate um único snapshot de preço como verdade final, e separe readiness (frescor de dados + integridade) de story quality (enquadramento editorial).

Compromissos de design

A Naly otimiza intencionalmente a confiabilidade sobre a velocidade na ingestão.

Gamma-only versus Gamma+CLOB: A Gamma oferece descoberta estável e contexto público rapidamente; adicionar o CLOB melhora a riqueza da microestrutura, mas aumenta a complexidade de autenticação e de endpoints.
Snapshot diário versus streaming contínuo: uma extração agendada determinística é mais fácil de auditar e reproduzir do que streams contínuos, mas perde mudanças de regime em poucos segundos.
Event-first pull versus market-first pull: event-first reduz chamadas duplicadas e melhora a cobertura contextual; market-first oferece tamanho de payload ligeiramente menor para tarefas mais estreitas.
Wide schema versus strict schema: um esquema amplo JSON-first acelera integração, mas aumenta o risco de drift de esquema; normalização rígida detecta drift mais cedo, mas aumenta a sobrecarga de migração.
Campos generalizados versus campos específicos de domínio: usar campos compartilhados melhora reutilização entre artigos; adicionar extensões específicas de domínio (por exemplo, janelas de confiança específicas de esporte) aumenta precisão imediata, mas pode fragmentar a manutenção de longo prazo.

Dado o objetivo de confiança e retenção da Naly, reprodutibilidade estrita e qualidade de citação devem predominar sobre a otimização de latência imediata.

Modos de falha

Os maiores modos de falha são operacionais, não algorítmicos.

Dados ausentes por bugs de paginação: se limit e offset as janelas mudam entre os polls, podem aparecer duplicatas ou lacunas. Mitigação: fazer checkpoint dos cursores de paginação e impor upserts idempotentes.
Padrão closed=false descartar contexto histórico: as coletas de open-market omitem itens resolvidos, a menos que closed=true seja explicitamente solicitado. Mitigação: executar um caminho dedicado de backfill histórico para tarefas de verificação.
Instabilidade de slug: URLs de produto e slugs legíveis por humanos podem derivar. Mitigação: preferir IDs principais internamente e manter o slug como chave secundária.
Deriva de campo semântico: outcomes/outcomePrices interpretação pode falhar se suposições de ordem de esquema estiverem erradas. Mitigação: afirmar alinhamento de arrays e checagens de tamanho na ingestão.
Disponibilidade transitória da API ou throttling: os endpoints públicos podem falhar ou retornar payloads parciais. Mitigação: retry com backoff exponencial, poison-queue em falhas repetidas e manter snapshots anteriores.
Resolução tardia e narrativas desatualizadas: artigos de verificação podem rodar antes de a liquidação se resolver limpo. Mitigação: armazenar o status de liquidação como parte do estado de publicação e atualizar posteriormente com um log de correção imutável.

Dada a estratégia trust-first da Naly, o pipeline deve falhar em modo fechado: é melhor atrasar um artigo do que publicar com estado de mercado não verificável.

Notas de implementação

Usando a stack de runtime informada, uma implementação prática continua direta:

Usar handlers de servidor do Next.js (next@16.0.7) para hospedar endpoints de ingestão e jobs agendados.
Persistir linhas normalizadas no Neon usando drizzle-orm@^0.44.7 over @neondatabase/serverless@^1.0.2 com restrições únicas explícitas em identificadores de mercado.
Armazenar snapshots de payload brutos no Vercel Blob (@vercel/blob@^2.0.0) para auditabilidade e diff pós-mortem.
Manter a geração de origem em Markdown e montagem de artigo fora do núcleo de ingestão; usar marked@^17.0.1 para transformação segura e ai@6.0.0-beta.105 além @anthropic-ai/claude-agent-sdk@^0.2.15 somente após as checagens de integridade de dados passarem.
Usar tsx@^4.21.0/typescript@^5.9.3 para reexecuções reprodutíveis de uma só vez ao fazer backfill de janelas históricas.

Em 10 de junho de 2026, a arquitetura deve priorizar três saídas duras: imutabilidade do snapshot bruto, projeção determinística para o esquema interno e uma trilha de auditoria orientada à verificação desde a URL da API de origem até a citação final do artigo.