A API da Polymarket mapeada: Gamma vs CLOB vs Data API
Quem está começando perde um dia com o mesmo problema: a Polymarket não tem uma API, tem quatro, e o endpoint que você quer raramente está na primeira que você tentou. Este é o mapa completo.
A primeira coisa a entender sobre a API da Polymarket é que ela não existe. Existem quatro APIs REST e quatro streams WebSocket, cada uma servindo uma parte distinta de uma integração, cada uma em seu próprio hostname, com seus próprios limites de requisições e suas próprias exigências de autenticação.
Quase toda pergunta do tipo “a API da Polymarket não tem X” acaba sendo “X está em outro host”. Aqui está a superfície inteira em um só lugar.
As quatro APIs REST
| API | URL base | Para que serve | Autenticação |
|---|---|---|---|
| Gamma | gamma-api.polymarket.com | Descobrir eventos e mercados; metadados | Nenhuma |
| CLOB | clob.polymarket.com | Preços, livros de ofertas, envio e gerenciamento de ordens | Nenhuma para ler, L1/L2 para operar |
| Data | data-api.polymarket.com | Posições, atividade, participação nos mercados | Nenhuma |
| Relayer | relayer-v2.polymarket.com | Enviar transações da carteira sem ter POL para o gás | Assinada |
A regra de roteamento de 30 segundos
Quais mercados existem? → Gamma. Qual é o preço / quero operar → CLOB. O que esta carteira tem? → Data API. Preciso movimentar fundos sem gás → Relayer. Se você está procurando um endpoint de eventos no CLOB, ou um livro de ofertas na Gamma, o erro é esse.
API Gamma — descoberta e metadados
A Gamma é por onde você começa. Ela responde o que existe: eventos, os mercados dentro deles, tags, busca e os metadados de que você precisa para trabalhar com todo o resto — principalmente os IDs de tokens que todo endpoint do CLOB exige.
/events— lista eventos, com paginação por chave disponível/markets— lista mercados; tambémby id,by slug,by token/public-search— busca em eventos e mercados/tags,/comments— taxonomia e discussão- Contratos em aberto, volume ao vivo, maiores detentores
/markets tem o limite mais apertado da plataforma
300 req / 10s — 13× mais apertado do que o limite geral da própria Gamma, de 4,000 req / 10s. Se você está paginando a lista completa de mercados em um loop, é isso que quebra primeiro. Guarde os metadados dos mercados em cache; eles quase não mudam durante a vida de um mercado. Os números completos estão na referência de limites de requisições.
API CLOB — preços, livros e ordens
O livro de ofertas em si, e o único lugar onde você pode operar. A leitura é pública; operar exige credenciais.
| Grupo | Endpoints | Autenticação |
|---|---|---|
| Livro de ofertas | /book, /books, /midpoint, /midpoints, /spread, /spreads | Pública |
| Preços | /price, /prices, /prices-history, preço da última negociação, /tick-size, taxa de fee | Pública |
| Ordens | POST /order, POST /orders, DELETE /order, /orders, /cancel-all, /cancel-market-orders | L2 + assinatura da carteira |
| Registro | /trades, /data/orders, /data/trades, /notifications | L2 |
| Autenticação | /auth/api-key, /auth/api-keys, /auth/derive-api-key | L1 |
| Conta | allowance de saldo (consultar / atualizar) | L2 |
Singular vs plural é uma distinção real
Quase todo endpoint de dados de mercado do CLOB tem um gêmeo em lote: /book e /books, /price e /prices. Os endpoints no singular têm 1,500 req / 10s e os no plural têm 500 req / 10s — mas uma chamada no plural cobre muitos tokens, então o lote dá muito mais dados por unidade de orçamento de limite. Prefira /books a um loop de /book praticamente sempre.
Data API — posições e atividade
Perguntas sobre portfólio: /positions, /closed-positions, /trades, além da API de PNL do usuário. Note que esta é a mais apertada das três APIs principais — um limite geral de 1,000 req / 10s, com /positions e /closed-positions em apenas 150 req / 10s cada. Ela foi feita para painéis, não para loops de polling.
Os quatro streams WebSocket
Se você está fazendo polling de /book com um timer, pare — é para isso que os streams existem. O polling é a forma mais comum de queimar o orçamento de limite de requisições sem ganhar nada.
| Stream | URL | Transmite |
|---|---|---|
| CLOB Market | wss://ws-subscriptions-clob.polymarket.com/ws/market | Atualizações públicas do livro de ofertas, de preço e de ciclo de vida do mercado |
| CLOB User | wss://ws-subscriptions-clob.polymarket.com/ws/user | Atualizações autenticadas de ordens e negociações da sua conta |
| RTDS | wss://ws-live-data.polymarket.com | Preços de referência públicos, comentários, atividade de negociação |
| Sports | wss://sports-api.polymarket.com/ws | Status e placares de jogos ao vivo |
O canal User é o que as pessoas esquecem. Se o seu bot faz polling de /data/orders para descobrir se a ordem foi executada, você está pagando com orçamento de limite por uma informação que o canal User teria enviado no momento em que aconteceu — e com menor latência.
Autenticação: L1 e L2
Os dados públicos de mercado não exigem credenciais — você pode chamar a Gamma, os endpoints de leitura do CLOB e a Data API com um curl simples. Operar exige duas camadas, e entender qual é qual resolve a maioria dos erros de autenticação.
| Camada | Como funciona | Finalidade |
|---|---|---|
| L1 | A carteira assina uma mensagem EIP-712 | Provar o controle da carteira; criar ou derivar credenciais de API |
| L2 | Requisições assinadas com as credenciais de API usando HMAC-SHA256 | Autenticar requisições privadas ao CLOB |
O envio de ordens usa as duas: a L2 autentica a requisição, e uma assinatura da carteira autoriza a ordem. Os dados tipados da L1 são um payload ClobAuth em chainId: 137 (Polygon), com o endereço do seu signer, um timestamp Unix em segundos, um nonce (use 0, a menos que você gerencie vários conjuntos de credenciais) e a string de mensagem fixa.
Obtendo uma chave de API
- Assine o payload EIP-712
ClobAuthcom a chave privada da sua carteira Polygon. - Chame
POST /auth/api-keycom os headers L1 para criar as credenciais. Você recebe uma chave, um secret e uma passphrase — os três são necessários para a L2. - Nas execuções seguintes, chame
GET /auth/derive-api-keypara recuperar as credenciais existentes em vez de criar novas.
As duas falhas de autenticação responsáveis pela maioria das dúvidas de suporte
Credenciais incompletas — a L2 precisa da chave, do secret e da passphrase; ter duas das três produz uma requisição bem formada com uma assinatura impossível de verificar. Desvio de relógio — a assinatura inclui um timestamp, então um contêiner com o relógio alguns segundos errado produz assinaturas que o servidor rejeita como inválidas. As duas aparecem como Unauthorized/Invalid api key, e é por isso que essa mensagem é tão pesquisada. Veja a referência de erros.
SDKs
A Polymarket mantém SDKs unificados em TypeScript e Python que encapsulam tudo isso com uma interface tipada e cuidam da paginação, dos formatos de erro e da configuração da carteira. Se você está começando do zero em uma dessas linguagens, use-os — implementar à mão a assinatura EIP-712 e a assinatura HMAC das requisições é um jeito bem propenso a erros de gastar um fim de semana.
Use REST diretamente quando o seu runtime não for coberto por um SDK, quando você precisar de controle exato sobre assinatura, headers, novas tentativas ou transporte, ou quando precisar de um endpoint que o SDK ainda não expôs. Note que estes são os SDKs unificados — se você está em um cliente mais antigo, há um caminho de migração documentado, e os clientes antigos são a origem de muitos bugs de credenciais desatualizadas.
Quanto custa a API da Polymarket?
Nada. Não há plano pago, página de preços da API nem assinatura — as APIs da Polymarket são gratuitas, com o acesso regulado por limites de requisições e não por cobrança. Os dados públicos de mercado nem exigem chave.
A única coisa que cresce com dinheiro são os limites de trading por signer, divididos em níveis conforme o volume de 30 dias da sua carteira maker — de Standard, com 40 tokens de ordem/s, até Elite, com 600 —, mas isso é uma alocação de vazão, não uma taxa.
A única coisa que nenhuma dessas APIs vai dar a você
Depois de mapear a superfície inteira, o útil é saber o que não está nela: profundidade histórica do livro de ofertas.
Todos os endpoints acima servem o estado atual. /book retorna o livro agora. /prices-history dá preços, mas não profundidade, então não consegue dizer qual teria sido a sua execução. E quando um mercado é resolvido, /book retorna 404. O que sobrevive é uma série de preços esparsa, de cerca de um ponto por minuto, que você pode buscar com um início e um fim explícitos. Nenhum plano ou nível de limite de requisições muda isso.
| Pergunta | Dá para responder com a API da Polymarket? |
|---|---|
| Como está o livro agora? | Sim — /book |
| Qual era o preço ontem? | Sim, cerca de um ponto por minuto, via /prices-history com início e fim |
| Qual era a profundidade às 14:03:17 de ontem? | Não |
| A que preço minha ordem de 500 cotas teria sido executada? | Não |
| Mostre um mercado resolvido na semana passada | O registro e o resultado, sim (closed=true). O livro, não. |
Essa lacuna é o motivo pelo qual fazer backtest de uma estratégia na Polymarket exige uma fonte de dados separada, que gravou o livro enquanto os mercados estavam ativos. A PolyTest faz exatamente isso para os mercados cripto Up/Down — mais de 240M de snapshots pontuais com 8 níveis de profundidade por lado, timestamps abaixo de um segundo e mercados resolvidos mantidos em vez de descartados. Um header, JSON limpo e um teste grátis de 3 dias:
curl -H "X-API-Key: $POLYTEST_KEY" \
"https://api.polytest.io/api/v1/markets?coin=btc&market_type=5m&limit=20"A referência completa de endpoints está na documentação da PolyTest, ou comece um teste grátis.
Perguntas frequentes
- Quais são os endpoints da API da Polymarket?
- A Polymarket mantém quatro APIs REST: Gamma (gamma-api.polymarket.com) para eventos, mercados e metadados; CLOB (clob.polymarket.com) para preços, livros de ofertas e trading; Data API (data-api.polymarket.com) para posições e atividade; e Relayer (relayer-v2.polymarket.com) para transações sem gás. Há também quatro streams WebSocket, que cobrem o canal público de mercado, o canal autenticado do usuário, dados em tempo real e esportes.
- A API da Polymarket é gratuita?
- Sim. Não há plano pago, assinatura nem página de preços da API — o acesso é regulado por limites de requisições e não por cobrança, e os dados públicos de mercado não exigem chave de API. A única coisa que escala é o nível de vazão de trading por signer, baseado no volume de trading de 30 dias da sua carteira, e não em pagamento.
- Como obtenho uma chave de API da Polymarket?
- Assine o payload de dados tipados EIP-712 ClobAuth com a chave privada da sua carteira Polygon e depois chame POST /auth/api-key com os headers L1 para criar as credenciais. Você recebe uma chave, um secret e uma passphrase — os três são necessários para assinar as requisições L2. Nas execuções seguintes, use GET /auth/derive-api-key para recuperar as credenciais existentes em vez de criar novas. Os dados públicos de mercado não precisam de chave.
- Qual é a diferença entre a API Gamma e a API CLOB?
- A Gamma é para descoberta: quais eventos e mercados existem, seus metadados e os IDs de tokens de que os outros endpoints precisam. O CLOB é para o livro de ofertas: preços atuais, profundidade do livro e envio ou cancelamento de ordens. Se você precisa encontrar um mercado, use a Gamma; se precisa precificar ou operar um, use o CLOB.
- A Polymarket tem um SDK Python?
- Sim. A Polymarket mantém SDKs unificados em TypeScript e Python que cobrem as quatro APIs REST com uma interface tipada e cuidam da paginação, dos formatos de erro e da configuração da carteira. Há um caminho de migração documentado a partir dos clientes antigos. Usar REST diretamente faz sentido quando o seu runtime não é suportado, quando você precisa de controle exato sobre assinatura e novas tentativas ou quando precisa de um endpoint que o SDK ainda não expôs.
- Consigo profundidade histórica do livro de ofertas pela API da Polymarket?
- Não. Todos os endpoints da Polymarket servem o estado atual. O endpoint /prices-history retorna uma série de preços de cerca de um ponto por minuto sem a profundidade por trás dela, então não consegue dizer a que preço uma ordem de determinado tamanho teria sido executada, e o livro de ofertas de um mercado resolvido retorna 404. O backtesting exige snapshots pontuais gravados enquanto os mercados estavam ativos, como o arquivo de mais de 240M de snapshots dos mercados cripto Up/Down da PolyTest.
Tenha os dados históricos que a Polymarket não guarda
A PolyTest registra os mercados cripto Up/Down da Polymarket enquanto estão ativos — mais de 240M de snapshots com 8 níveis de profundidade do livro de ofertas, timestamps abaixo de um segundo e mercados resolvidos preservados. Comece com um teste grátis de 3 dias.
Continue lendo
O SDK Python da Polymarket em 2026 (e como sair do py-clob-client)
Se o seu código ainda importa ClobClient de py_clob_client, ele está construído sobre um pacote substituído — assim como a maior parte do código da Polymarket que um assistente de IA vai escrever para você. Veja o SDK atual e como migrar.
WebSockets da Polymarket: dados em tempo real que não caem
Fazer polling do livro de ofertas é a forma mais comum de queimar o orçamento de limite de requisições sem ganhar nada. Veja os quatro streams, as opções de assinatura que ninguém documenta e o modo de falha em que seu bot recebe silêncio e acha que é calmaria.
Limites de requisições da API da Polymarket: a referência completa
A Polymarket publica seus limites de requisições em várias páginas, em dois sistemas completamente diferentes, usando uma janela de 10 segundos que quase ninguém espera. Aqui está tudo em um só conjunto de tabelas — mais o que realmente acontece quando você passa de um limite.