Notas de Engenharia da Naly: Polymarket Gamma como uma camada reprodutível de snapshots de mercado

TL;DRA ingestão do Polymarket Gamma dá à Naly uma visão pública e estruturada de eventos, mercados, resultados, preços, tags e metadados de resolução de mercados de previsão. A Naly usa essa camada para escolher candidatos a artigos, ancorar resumos de distorções de preço, apoiar histórias de previsão da KBO, preservar citações de fontes e criar snapshots duráveis de mercado para verificação posterior. A afirmação de engenharia é simples: a confiança editorial começa com insumos de mercado reproduzíveis, não com prosa gerada.

Resumo

A API Polymarket Gamma deve ser tratada como a fonte de descoberta de mercados e metadados da Naly, não como uma interface de negociação. A documentação oficial da Polymarket separa Gamma das APIs Data e CLOB: Gamma cobre eventos, mercados, tags, séries, metadados esportivos, busca, comentários e perfis públicos, enquanto CLOB lida com livros de ordens, preços, spreads e operações de negociação autenticadas. Para artigos da Naly, essa fronteira é útil. A maioria dos fluxos editoriais precisa do texto da pergunta, da identidade do mercado, dos rótulos de resultado, das probabilidades exibidas, das tags de categoria, dos prazos e do contexto de resolução antes de precisar de detalhes de livro de ordens em nível de tick.

A tese desta nota é que a Naly deve ingerir o Gamma em uma camada versionada de snapshots de mercado. Um snapshot não é a verdade; é o estado público observado do mercado em um momento específico, vinculado a URLs de origem e a payloads brutos preservados. Isso permite que a Naly publique o que outros escondem: o contexto do mercado, os limites do sinal e a evidência exata usada quando um artigo foi gerado.

Onde isso se encaixa na Naly

A ingestão do Gamma fica antes da geração de artigos e depois da descoberta de fontes externas. No caminho de publicação da Naly, ela fornece o lado de mercado de previsão do pacote de evidências para quatro usos posteriores:

Resumos de distorções de preço precisam de candidatos atuais de eventos e mercados, com metadados suficientes para comparar probabilidades implícitas pelo mercado com raciocínio respaldado por fontes.
Artigos de previsão da KBO precisam de mercados esportivos, tags de equipes ou eventos, prazos de eventos e rótulos de resultado que possam ser renderizados sem contexto de mercado inserido manualmente.
Citações de fontes precisam de URLs estáveis de mercado, slugs de eventos e identificadores de mercado para que o leitor possa auditar por que o artigo discutiu um contrato específico.
A verificação de previsões precisa de snapshots históricos para que a resolução posterior possa ser pontuada em relação à probabilidade que a Naly realmente viu no momento da publicação.

Os fatos do runtime local importam principalmente para o formato, não para a novidade. TypeScript 5.9 e tsx são uma opção razoável para scripts de ingestão; drizzle-orm com @neondatabase/serverless pode persistir registros normalizados e JSON bruto; Next.js 16 e React 19 podem renderizar as páginas de artigo resultantes; os pacotes ai e Claude SDK podem consumir o pacote de evidências preparado somente depois que a ingestão tornar explícito o estado do mercado.

Mecanismo técnico

Um loop robusto de ingestão do Gamma tem seis etapas.

Descoberta. Use eventos do Gamma quando a Naly precisar de descoberta ampla de mercados ativos e use slugs de mercado ou evento quando um artigo estiver ancorado a uma URL conhecida da Polymarket. O guia de dados de mercado da Polymarket recomenda eventos para uma descoberta ativa completa porque eventos incluem mercados associados, reduzindo chamadas de API. Para trabalho por categoria, como esportes, tags e metadados esportivos devem restringir o rastreamento antes de ranquear candidatos.
Paginação. O Gamma oferece suporte tanto a endpoints no estilo offset quanto a endpoints keyset. Para rastreamento grande ou repetido, a paginação keyset é mais segura porque next_cursor se torna o token de continuação e offset é explicitamente rejeitado no endpoint keyset de mercados. Para tarefas menores de artigos direcionados, a paginação por offset ainda pode ser aceitável quando a janela de consulta é estreita e a saída recebe snapshot imediatamente.
Normalização. A regra principal de normalização é que os rótulos de resultado e os preços de resultado devem ser mapeados por posição. A visão geral de dados de mercado da Polymarket documenta arrays outcomes e outcomePrices como arrays um para um, portanto a disciplina de índice importa. Um array trocado não é um bug cosmético; ele inverte a interpretação de mercado do artigo.
Snapshotting. Armazene tanto colunas normalizadas quanto JSON bruto. As colunas normalizadas devem incluir provedor, carimbo de data/hora de coleta, id ou slug do evento, id ou slug do mercado, texto da pergunta, condition id quando presente, identificadores de token quando presentes, rótulos de resultado, preços de resultado, flags de ativo e fechado, horário de término, tags, URL de origem e hash do payload. O JSON bruto protege a Naly contra drift de schema e permite que a verificação reproduza o artefato exato de ingestão.
Pontuação de candidatos. Tarefas de artigo devem ranquear mercados usando critérios editoriais, não critérios de execução de negociação: atualidade, volume ou liquidez quando disponíveis, proximidade da resolução, disponibilidade de fontes, adequação à categoria e se o mercado consegue produzir um contraste claro para o leitor. A pontuação de candidatos nunca deve sugerir que um preço de mercado está automaticamente errado; deve marcar um mercado como digno de pesquisa.
Vinculação de publicação. Quando um artigo gerado cita um mercado, o artigo deve vincular ao id do snapshot armazenado, à URL de origem da Polymarket e ao conjunto de evidências externas usado pelo redator. Essa é a diferença entre uma página que diz que o mercado estava em 62 por cento e uma página que consegue provar quando, onde e de qual payload esse valor veio.

Limites de taxa fazem parte do mecanismo. A Polymarket documenta throttling aplicado pelo Cloudflare e limites específicos do Gamma para /events, /markets, /tags, e /public-search. A Naly não precisa se aproximar desses limites para publicação diária, então a postura correta é conservadora: concorrência limitada, retry com jitter, hashes de payload para idempotência e alertas quando uma tarefa recebe respostas com throttling, vazias ou estruturalmente inesperadas.

O que diz a literatura

Trabalhos recentes no arXiv apoiam o design snapshot-first. Jia et al. descrevem dados de mercados de previsão descentralizados como fragmentados entre metadados off-chain, registros de negociação em nível de execução e eventos de resolução por oráculo, e então defendem um sistema relacional unificado com resolução de identificadores, atualizações incrementais e mecanismos de consistência. O sistema de publicação menor da Naly tem a mesma classe de problema: metadados de mercado sozinhos não bastam, a menos que possam ser posteriormente conectados a preços, afirmações de artigos e resultados de resolução.

O estudo de calibração de Le é diretamente relevante para a linguagem dos artigos. Usando grandes datasets da Kalshi e da Polymarket, o paper argumenta que a calibração depende de domínio, horizonte e efeitos de tamanho de negociação; consumidores que tratam preços como probabilidades ao valor de face podem interpretá-los sistematicamente de forma equivocada. Para a Naly, isso significa que um artigo deve dizer probabilidade implícita pelo mercado, preço observado ou sinal público de mercado, não verdade. O artigo pode discutir uma possível distorção de preço somente depois de separar a observação bruta do mercado do modelo da Naly ou do raciocínio respaldado por fontes.

O paper de Dubach sobre microestrutura da Polymarket trata principalmente de dados de livro de ordens, mas traz um alerta útil para o design de ingestão: evidências de mercado de alta frequência têm modos de erro específicos da fonte, atrasos de ingestão e joins que importam. O Gamma é menos granular do que feeds de livro de ordens, mas o mesmo princípio se aplica. A fonte de um número deve estar visível. Um snapshot do Gamma, um midpoint do CLOB e um registro de negociação on-chain são relacionados, mas não intercambiáveis.

Madrigal-Cianci, Monsalve Maya e Breakey enquadram mercados de previsão como problemas inversos bayesianos em que histórias observadas de probabilidade e volume são ruidosas, endógenas e moldadas por tipos heterogêneos de traders. Isso reforça a postura editorial da Naly. O estado de mercado ingerido é evidência, não veredito. Boa engenharia torna essa incerteza inspecionável em vez de apagá-la durante a geração.

Trade-offs de design

Gamma versus CLOB é o primeiro trade-off. Gamma dá à Naly capacidade de descoberta, contexto de artigo e metadados. CLOB dá precificação mais precisa e mecânica de livro de ordens. Para artigos diários de engenharia e resumos de mercados de previsão, Gamma deve ser o input padrão porque responde sobre o que é o mercado. CLOB pode ser adicionado quando o artigo precisar de spread, midpoint ou precisão de histórico de preços.

Ingestão event-first versus market-first é o segundo trade-off. Event-first é mais barata para varreduras amplas porque um evento pode conter múltiplos mercados e metadados compartilhados. Market-first é mais limpa para verificação porque a pontuação eventual se vincula a um resultado binário específico. A Naly deve ingerir os dois formatos, mas fazer os links dos artigos apontarem para a afirmação em nível de mercado sempre que um único resultado estiver sendo avaliado.

JSON bruto versus schema tipado é o terceiro trade-off. JSON bruto sozinho é fácil de armazenar, mas difícil de consultar com segurança. Colunas tipadas sozinhas são fáceis de consultar, mas frágeis quando campos do provedor evoluem. O padrão durável é ambos: campos tipados para ranking, renderização e joins; payloads brutos para auditoria, replay e migração.

Renderização ao vivo versus renderização congelada é o quarto trade-off. Um widget de mercado ao vivo pode ser útil, mas as afirmações do artigo devem se vincular ao snapshot do momento da publicação. Caso contrário, um artigo antigo pode mudar silenciosamente de significado quando a Polymarket move, fecha ou resolve um mercado. Para a estratégia de confiança da Naly, evidência congelada supera atualidade quando uma página faz uma afirmação datada.

Modos de falha

A falha mais perigosa é o desalinhamento entre resultado e preço. Se Yes e No rótulos forem analisados separadamente dos preços, o artigo pode inverter o sinal e ainda parecer plausível.

A segunda falha é a reutilização de mercado obsoleto. Um mercado pode estar ativo durante a descoberta e fechado no momento da publicação. Cada tarefa de artigo deve revalidar campos de ativo, fechado, arquivado e horário de término imediatamente antes de vincular o snapshot.

A terceira falha é ambiguidade multimercado. Um evento da Polymarket pode conter vários mercados negociáveis. Um resumo pode citar o evento, mas um registro de verificação deve citar o mercado e o resultado específicos que a Naly avaliou.

A quarta falha é drift de schema. APIs públicas mudam nomes de campos, padrões e relações aninhadas. O armazenamento de snapshots deve incluir hashes de payload, versão do parser, URL do provedor e erros de validação para que o drift seja observável.

A quinta falha é exagerar a calibração. Um preço de mercado é um sinal público útil, mas a literatura alerta contra tratá-lo como uma probabilidade limpa em todos os domínios e horizontes. O texto da Naly deve preservar a diferença entre probabilidade implícita pelo mercado, estimativa da Naly e resultado realizado.

A sexta falha é perda de citação. Se um artigo armazena apenas markdown renderizado, a verificação posterior não consegue provar qual página de mercado e qual payload sustentaram a afirmação. Joins entre artigo e mercado devem ser registros de primeira classe, não prosa embutida.

Notas de implementação

Uma implementação prática da Naly pode manter pequeno o contrato de ingestão:

provider: polymarket-gamma.
provider_url: o endpoint exato do Gamma ou a URL pública de mercado usada para descoberta.
fetched_at: carimbo de data/hora do servidor em UTC.
event_key e market_key: identificadores ou slugs estáveis do provedor.
question: texto canônico da pergunta do mercado.
outcomes: rótulos ordenados.
outcome_prices: strings decimais ordenadas, normalizadas para valores numéricos somente após validação.
status: flags de ativo, fechado, arquivado e publicabilidade.
raw_payload: resposta completa do provedor.
payload_hash: hash determinístico para idempotência e replay.
parser_version: o contrato de código que interpretou o payload.

O gerador de artigos deve receber isso como evidência estruturada, não como texto solto de prompt. Ele pode então produzir markdown por meio da stack de IA existente, renderizar com o pipeline do site e manter citações anexadas aos registros de origem. Um worker de verificação pode posteriormente conectar o snapshot de mercado do artigo aos dados de resolução e pontuar se a afirmação publicada envelheceu bem.

O princípio de engenharia é deliberadamente conservador: ingerir, normalizar, tirar snapshot, citar e então escrever. Essa ordem é mais lenta do que pedir a um modelo para navegar e resumir uma página de mercado, mas cria o artefato de que a Naly realmente precisa para aquisição e retenção: um artigo público cuja evidência de mercado pode ser reproduzida depois que o resultado é conhecido.