Mercados de previsão estão entre os domínios tecnicamente mais exigentes para a construção de APIs. Você está lidando com instrumentos financeiros que expiram, probabilidades que precificam em tempo real, eventos de múltiplos resultados com relações complexas de capital e uma base de usuários que inclui tanto humanos clicando em uma interface quanto robôs de negociação automatizados executando estratégias de arbitragem. Cada decisão de design é imediatamente testada sob estresse.
Polymarket, atualmente a maior plataforma de mercado de previsão do mundo em volume, construiu um ecossistema de API que vale a pena estudar exatamente por essa razão. Não é apenas uma API CRUD sobre um banco de dados. É uma arquitetura cuidadosamente em camadas que lida com a tensão fundamental entre abertura e segurança, entre dados em tempo real e históricos, e entre padrões financeiros tradicionais e primitivos nativos de cripto.
Aqui estão oito padrões de design que valem a pena extrair de como eles fizeram.
Padrão 1: Camadas de API Separadas por Domínio
A Polymarket expõe três APIs distintas, cada uma com um domínio claro:
- API Gamma (
gamma-api.polymarket.com) — descoberta de mercado, eventos, tags, busca - API CLOB (
clob.polymarket.com) — dados de livro de ordens, precificação, colocação de ordens - API de Dados (
data-api.polymarket.com) — posições de usuários, negociações, análises, classificações
Isso não é apenas uma convenção de nomenclatura — cada API tem requisitos de autenticação diferentes, cadências de atualização distintas e perfis de consumidor variados. A API Gamma é totalmente pública, otimizada para navegação e descoberta. A API CLOB tem endpoints públicos (qualquer um pode ler o livro de ordens) e endpoints autenticados (a negociação exige credenciais). A API de Dados é pública, mas endereçada por carteira — você consulta posições pelo endereço do usuário.
A lição de design aqui é que separar por domínio em vez de por entidade produz APIs mais coerentes. Uma abordagem ingênua daria /markets, /orders, /users tudo sob o mesmo teto. A Polymarket, em vez disso, pergunta: "Para que serve esta API for?" e então constrói em torno dessa pergunta. A descoberta tem padrões de acesso diferentes da negociação. A negociação tem requisitos de latência diferentes da análise. Dar a cada uma sua própria URL base significa que cada uma pode evoluir, escalar e autenticar independentemente.
Padrão 2: Acesso a Dados Primeiro-Público
Tudo sobre os dados do mercado — preços, livros de ordens, metadados de eventos, negociações históricas — é totalmente público:
curl "https://gamma-api.polymarket.com/events?limit=5"
Sem chave de API. Sem OAuth. Sem barreiras de limite de taxa em endpoints de leitura. Você obtém os dados.
Esta é uma escolha deliberada que a maioria das plataformas financeiras não faz. As bolsas tradicionais guardam os dados de mercado como uma fonte de receita. A Polymarket os trata como infraestrutura — quanto mais pessoas puderem ler e construir sobre os dados, mais líquido e útil o mercado se torna. É a lógica de bens públicos aplicada a uma API.
A consequência prática para os designers de API vale a pena notar: separar o acesso de leitura do acesso de escrita como uma preocupação de primeira classe, em vez de aplicar a autenticação uniformemente, é quase sempre a decisão certa para plataformas onde o consumo de dados supera vastamente a produção de dados. Se um usuário pode ler os preços de mercado sem credenciais, você removeu o atrito de 95% do seu público potencial. Você só adiciona atrito no ponto onde realmente importa — quando eles querem fazer uma ordem real.
Padrão 3: Autenticação de Dois Níveis Que Reflete Confiança Real
Endpoints de negociação exigem autenticação, mas o modelo de autenticação da Polymarket tem uma estrutura que a maioria dos designers de API não viu antes: dois níveis com propósitos distintos.
A Autenticação L1 usa uma assinatura EIP-712 da chave privada do usuário. Ela prova a propriedade da carteira. Você a usa exatamente uma vez (ou com pouca frequência) para derivar credenciais de API:
// L1: Use your private key to derive API credentials
const credentials = await client.createOrDeriveApiKey();
// → { key: "...", secret: "...", passphrase: "..." }
A Autenticação L2 usa HMAC-SHA256 com essas credenciais derivadas. É o que você anexa a cada solicitação de negociação:
// L2 headers on every trading request
{
"POLY_ADDRESS": "0x...",
"POLY_SIGNATURE": "<hmac-sha256>",
"POLY_TIMESTAMP": "1716000000",
"POLY_API_KEY": "550e8400-...",
"POLY_PASSPHRASE": "..."
}
A percepção é que operações diferentes merecem cerimônias de segurança diferentes. Criar chaves de API exige provar o controle da carteira — essa é uma ação de alto risco que deve exigir uma assinatura criptográfica da chave privada. Mas, uma vez estabelecida essa confiança, as solicitações de negociação rotineiras não devem exigir a re-assinatura com sua chave privada em cada chamada. As credenciais L2 são leves o suficiente para uso de alta frequência, ao mesmo tempo em que permanecem vinculadas à identidade L1.
Este padrão se estende bem além da cripto: pense nisso como a diferença entre "prove que você é essa pessoa" (L1, feito infrequentemente com a credencial mais forte disponível) e "prove que esta solicitação veio de você" (L2, feito constantemente com uma credencial de sessão). A maioria dos aplicativos web colapsa esses em um único fluxo de autenticação e perde a nuance de segurança.
Padrão 4: Ordens Como Mensagens Assinadas, Não Chamadas de API
É aqui que os mercados de previsão divergem mais acentuadamente do design convencional de API. Quando você faz uma ordem na Polymarket, você não está apenas enviando dados para um servidor — você está criando uma mensagem criptograficamente assinada que é um compromisso financeiro executável:
const response = await client.createAndPostOrder(
{
tokenID: "71321045679...",
price: 0.65,
size: 100,
side: Side.BUY,
},
{
tickSize: "0.01",
negRisk: false,
},
OrderType.GTC
);
Por baixo do capô, o SDK constrói uma estrutura de dados tipada EIP-712, assina-a com sua chave privada e submete a assinatura junto com a ordem. O motor de casamento de ordens opera fora da cadeia (offchain), mas quando as negociações são correspondidas, elas são liquidadas na cadeia (on-chain) via Polygon usando essas assinaturas. O operador não pode fabricar negociações ou mover fundos — a mensagem assinada é a autorização.
Isso muda a semântica do que significa uma "chamada de API". Normalmente, enviar algo para um endpoint significa "por favor, faça isso em meu nome". Aqui, enviar uma ordem significa "aqui está um instrumento assinado autorizando esta negociação". A API não é um intermediário tomando decisões — é um retransmissor para mensagens criptograficamente auto-autorizadas.
Para designers de API fora do espaço cripto, a lição é esta: quando o payload em si pode carregar autorização, em vez de depender inteiramente de credenciais da camada de transporte, você obtém não-repúdio e verificabilidade gratuitamente. Sistemas financeiros, documentos legais e operações de alto risco são todos candidatos para este padrão.
Padrão 5: Ontologia Explícita no Modelo de Dados
A Polymarket estrutura seus dados em torno de dois objetos: Eventos e Mercados. A distinção importa.
Um Evento é uma pergunta: "Quem vencerá a corrida para o Senado dos EUA na Pensilvânia em 2026?" Ele tem um título, uma categoria, uma data de resolução. Um Mercado é um resultado binário negociável específico dentro desse evento: "Bob Casey vencerá?" Um evento pode conter muitos mercados.
{
"id": "501",
"title": "2026 Pennsylvania Senate Race",
"negRisk": true,
"markets": [
{ "id": "2301", "question": "Will Bob Casey win?", "outcomePrices": "[\"0.42\", \"0.58\"]" },
{ "id": "2302", "question": "Will Dave McCormick win?", "outcomePrices": "[\"0.35\", \"0.65\"]" },
{ "id": "2303", "question": "Will a third candidate win?", "outcomePrices": "[\"0.23\", \"0.77\"]" }
]
}
Isso é ontologia explícita — a API não apenas armazena dados, ela codifica as relações conceituais entre entidades. Os preços são representados como arrays paralelos onde a posição do índice é a convenção de ligação: outcomes[0] corresponde a outcomePrices[0]. O flag negRisk no nível do evento sinaliza que os mercados dentro dele têm relações de capital que não existem em mercados independentes.
A maioria das APIs achata essas relações. A Polymarket as expõe porque são cruciais para o funcionamento do sistema. Se você estiver construindo um trader automatizado e perder negRisk: true, você construirá o modelo de posição errado e poderá perder dinheiro. O design da API torna a estrutura conceitual visível para que omiti-la seja uma escolha consciente, e não um padrão silencioso.
Padrão 6: NegRisk — Relações de Capital Como uma Preocupação de Primeira Classe
O flag negRisk em eventos aponta para um dos padrões de design de API mais interessantes da Polymarket: tornar as equivalências financeiras programáveis.
Em um evento multi-resultado padrão, cada mercado é independente. Mas em um evento NegRisk, onde exatamente um resultado pode vencer, existe uma relação matemática entre as posições:
1 token Não no resultado A ≡ 1 token Sim em todos os outros resultados
Isso não é apenas matemática — é implementado em contratos inteligentes e exposto através da API. Quando você detém uma posição "Não" em "Outro" na corrida para o Senado da Pensilvânia, você pode convertê-la:
| Antes | Depois |
|---|---|
| 1× Não (Outro) | 1× Sim (Casey) + 1× Sim (McCormick) |
A API torna isso explícito: negRisk: true no objeto de mercado, e negRisk: true exigido nas suas opções de ordem ao negociar esses mercados. Se você errar, sua ordem será rejeitada ou liquidada incorretamente.
O padrão de design aqui é codificar invariantes de domínio como campos de API tipados, em vez de deixá-los como notas de rodapé da documentação. O flag NegRisk não existe porque é conveniente tê-lo — ele existe porque omiti-lo causa um comportamento incorreto. Quando seu domínio tem restrições rígidas (apenas um resultado pode vencer, posições têm equivalências de conversão), essas restrições devem aparecer na superfície da API, não apenas na documentação.
Padrão 7: Tamanho do Tick Dinâmico Como Estado do Mercado
A maioria das APIs financeiras trata o tamanho do tick como uma configuração estática. A da Polymarket faz algo mais interessante: o tamanho do tick muda dinamicamente com base no preço de mercado, e a API expõe isso como um fluxo de eventos em tempo real.
Quando o preço de um mercado se aproxima dos extremos (acima de 0.96 ou abaixo de 0.04), o tamanho mínimo do tick se reduz de 0.01 para 0.001:
{
"event_type": "tick_size_change",
"asset_id": "65818619657...",
"old_tick_size": "0.01",
"new_tick_size": "0.001",
"timestamp": "100000000"
}
O raciocínio é intuitivo: em probabilidades extremas, um tick de 1 centavo representa um movimento de 25% (indo de 0.04 para 0.03). Isso é muito grosseiro para uma descoberta de preço significativa. Ticks mais finos perto dos extremos permitem que o mercado expresse probabilidades como 97.3% em vez de arredondar para 97%.
O que torna isso notável como uma escolha de design de API é que o tamanho do tick não é um parâmetro que você busca uma vez — é um estado que muda e deve ser rastreado. O WebSocket expõe eventos de tick_size_change precisamente para que os clientes possam manter sua lógica de construção de ordens consistente com o estado atual do mercado. Se você codificar o tamanho do tick e perder este evento, suas ordens serão rejeitadas.
Isso reflete um princípio mais amplo: o design de API para sistemas financeiros deve abraçar o estado como um conceito de primeira classe. Os parâmetros de mercado não são estáticos. As regras de resolução mudam. Os resultados são esclarecidos. A API precisa comunicar essas transições de estado explicitamente, não deixar que os clientes as descubram através de solicitações rejeitadas.
Padrão 8: Duas Camadas de WebSocket Para Diferentes Perfis de Consumidor
A Polymarket executa dois sistemas WebSocket separados, e entender o porquê revela um padrão sobre a segmentação de público.
O Canal de Mercado (wss://ws-subscriptions-clob.polymarket.com/ws/market) é construído para consumidores de negociação. Assine por ID de token, receba snapshots do livro de ordens, mudanças de preço, execuções de negociações e mudanças no tamanho do tick. Tudo é chaveado para IDs de ativos e otimizado para construção de ordens de baixa latência:
{
"assets_ids": ["65818619657568813474341868652308942079804919287380422192892211131408793125422"],
"type": "market"
}
O Socket de Dados em Tempo Real (wss://ws-live-data.polymarket.com) é construído para um perfil completamente diferente. Ele transmite comentários, preços de criptomoedas da Binance e Chainlink, preços de ações e eventos de interação social. Assine por tópico:
{
"action": "subscribe",
"subscriptions": [
{ "topic": "crypto_prices", "type": "update", "filters": "btcusdt,ethusd" }
]
}
Esses dois sistemas atendem a públicos com necessidades fundamentalmente diferentes. Um formador de mercado precisa de deltas de livro de ordens relevantes em microssegundos. Uma interface de usuário mostrando "o que está acontecendo na Polymarket agora" precisa de feeds de comentários e atividade social. Combiná-los significaria ou superdimensionar o feed social com requisitos de latência de nível de negociação, ou subdimensionar o feed do livro de ordens com suposições de confiabilidade de nível social.
A lição é simples, mas muitas vezes ignorada: quando seus consumidores em tempo real têm tolerância à latência, volumes de dados e modos de falha significativamente diferentes, forneça-lhes infraestrutura separada. Endpoints WebSocket compartilhados que tentam servir a múltiplos propósitos tendem a colapsar para o maior denominador comum em complexidade e para o menor denominador comum em desempenho.
O Que Esses Padrões Têm em Comum
O design da API da Polymarket reflete uma filosofia particular: a API deve tornar a estrutura real do domínio visível, não abstraí-la.
A arquitetura de três camadas mapeia para fronteiras de domínio reais. O acesso primeiro-público reflete como funciona o valor do mercado de previsão. A autenticação de dois níveis espelha a diferença real entre provar identidade e autorizar uma ação. Ordens como mensagens assinadas codificam a garantia não custodial. A hierarquia Evento/Mercado e o flag NegRisk expõem relações que de outra forma seriam invisíveis. Tamanhos de tick dinâmicos mantêm o estado do cliente consistente com o estado do mercado. Camadas WebSocket separadas servem a públicos separados.
A maioria dos conselhos de design de API foca na ergonomia: torná-la fácil de chamar, consistente na nomenclatura, previsível no tratamento de erros. A API da Polymarket faz tudo isso — mas as escolhas mais interessantes são sobre a fidelidade ao domínio. Quando o domínio tem uma distinção significativa, a API a expõe. Quando o domínio tem uma restrição, a API a impõe. Quando o domínio tem um estado que muda, a API o transmite.
O resultado é uma API que exige mais de seus consumidores, mas uma em que acertar significa que você realmente entende o sistema em que está negociando. Isso não é uma coincidência — para um mercado de previsão, onde o objetivo é que os preços reflitam informações, uma API que o força a entender a estrutura do mercado está fazendo exatamente o que deveria.