A API da Polymarket em linguagem simples

A Polymarket mantém três APIs HTTP públicas. A Gamma, em gamma-api.polymarket.com, lista eventos e mercados. A CLOB, em clob.polymarket.com, fornece livros de ordens, preços e histórico. A Data, em data-api.polymarket.com, mostra negociações e posições. Todos os endpoints de leitura funcionam sem autenticação. Apenas as operações de negociação exigem credenciais e uma wallet com saldo.

De qual API da Polymarket eu preciso?

Escolha conforme a pergunta. Para saber quais mercados existem e do que tratam, use a Gamma. Para saber quanto um resultado custa agora ou quanto custava na semana passada, use a CLOB. Para saber quem negociou o quê, use a Data. A maioria dos projetos somente de leitura usa a Gamma para localizar mercados e a CLOB para consultar o preço de cada token.

A tabela vem da referência agent-skills da Polymarket e da página oficial de limites, consultadas em 4 de setembro de 2026.

API	URL-base	Autenticação para leitura	Rotas principais	Limite de leitura
Gamma	https://gamma-api.polymarket.com	Não	/events, /markets, /tags, /sports, /public-search	4.000 solicitações por 10s no geral, 500 em /events, 300 em /markets
CLOB	https://clob.polymarket.com	Não	/book, /price, /midpoint, /spreads, /prices-history	9.000 solicitações por 10s no geral, 1.500 em /book, /price e /midpoint
Data	https://data-api.polymarket.com	Não	/trades, /positions, /closed-positions	1.000 solicitações por 10s no geral, 200 em /trades, 150 em /positions

Fontes: Polymarket agent-skills, market-data.md e limites da API da Polymarket, ambas consultadas em 4 de setembro de 2026.

Como ler mercados sem autenticação?

Envie um GET simples à Gamma. Não é preciso ter chave, cabeçalho nem conta. GET https://gamma-api.polymarket.com/events?active=true&closed=false&limit=100 devolve eventos abertos. GET https://gamma-api.polymarket.com/events?slug=which-party-will-win-the-house-in-2026 devolve um evento pelo slug, a mesma sequência que aparece na URL da Polymarket. Para mercados, o padrão é o mesmo em /markets?slug=....

Três parâmetros resolvem quase tudo. limit aceita de 1 a 500 e usa 20 como padrão. offset faz a paginação. order ordena por volume_24hr, volume, liquidity, start_date, end_date, competitive ou closed_time, e ascending inverte a direção. Para navegar por categoria, consulte primeiro GET /tags e depois filtre por tag_id.

Um evento é um contêiner. Um mercado é uma pergunta de Sim ou Não dentro dele. "Qual partido vencerá a Câmara em 2026?" é um evento. "O Partido Democrata controlará a Câmara após as eleições de meio de mandato de 2026?" é um mercado dentro desse evento. Um código que confunde os dois falha no primeiro evento com vários resultados.

O que os preços significam?

Um preço da Polymarket é um número de 0 a 1 que pode ser lido diretamente como probabilidade. Um mercado em 0,895 indica 89,5%. A Gamma devolve outcomePrices como um vetor alinhado a outcomes, além de lastTradePrice, bestBid e bestAsk para cada mercado.

Esta é uma resposta real do evento Gamma which-party-will-win-the-house-in-2026, consultada em 4 de setembro de 2026:

{
  "question": "Will the Democratic Party control the House after the 2026 Midterm elections?",
  "outcomes": ["Yes", "No"],
  "outcomePrices": ["0.895", "0.105"],
  "lastTradePrice": 0.9,
  "bestBid": 0.89,
  "bestAsk": 0.9,
  "volume": 5723307.96
}

Para qualquer uso sensível ao tempo, prefira a CLOB à Gamma. GET /price?token_id=TOKEN_ID&side=BUY devolve a melhor oferta de venda, GET /midpoint?token_id=TOKEN_ID devolve o ponto médio entre a melhor compra e a melhor venda, e GET /book?token_id=TOKEN_ID traz o livro inteiro. Há versões em lote como solicitações POST em /prices, /midpoints, /spreads e /books, com até 500 tokens por chamada.

O identificador importante é tokenID, o token de resultado ERC1155. Cada mercado tem um token por resultado. conditionID identifica o mercado na blockchain, enquanto questionID é o hash dos dados complementares da UMA que decidem o resultado. O sinalizador neg_risk identifica mercados em um grupo de resultados mutuamente exclusivos.

Como obter o histórico de preços?

Use o endpoint /prices-history da CLOB, com o id do token. Ele aceita um intervalo (1h, 6h, 1d, 1w, 1m, max) ou uma faixa absoluta com horários de início e fim. A resposta contém entradas no formato {t: timestamp, p: price}. O limite de leitura é de 1.000 solicitações por 10 segundos, suficiente para preencher o histórico de algumas centenas de mercados em minutos, não em dias.

Há duas observações práticas. O histórico é por token, não por mercado. Um mercado de Sim ou Não exige duas consultas se você quiser as duas pontas, embora a segunda seja quase exatamente um menos a primeira. Além disso, a série traz preços amostrados, não todas as negociações. Para obter as execuções reais, use /trades na API Data.

Como funciona a resolução?

Um mercado da Polymarket paga conforme o resultado decidido pelo oráculo otimista da UMA, não por uma escolha da equipe da Polymarket. O questionID de cada mercado é o hash dos dados complementares lidos pelo oráculo. Por isso, o texto exato da resolução é tão importante. Dois mercados com títulos quase iguais podem ter desfechos diferentes por causa de uma data ou fonte nas regras.

Para um bot, a consequência é simples. Leia a descrição, não apenas o título. Um mercado chamado "Fed corta juros em outubro" pode ser resolvido por um comunicado específico do FOMC, publicado em determinada data. Uma manchete que parece indicar corte pode não atender à regra.

Quais são os limites da API?

A Polymarket publica limites por endpoint e aplica controle de fluxo. Solicitações acima do limite ficam mais lentas e entram em uma fila, em vez de falharem imediatamente com um erro 429. Um laço mal escrito perde desempenho sem produzir um erro claro. Em 4 de setembro de 2026, os limites publicados incluíam um teto geral de 15.000 solicitações por 10 segundos, 4.000 por 10 segundos na Gamma, 9.000 por 10 segundos na CLOB e 1.000 por 10 segundos na Data (limites da API da Polymarket).

Endpoints de negociação têm limites para picos e para períodos sustentados. POST /order aparece com 5.000 solicitações por 10 segundos em picos e 120.000 por 10 minutos de forma sustentada. Uma integração somente de leitura não chegará perto desses números.

Qual biblioteca cliente devo usar?

Use os SDKs unificados. Em 4 de setembro de 2026, os repositórios py-clob-client e clob-client estavam arquivados no GitHub. Ambos haviam recebido o último envio em 25 de maio de 2026, e o README em Python dizia que o cliente deixara de funcionar e não deveria ser usado em integrações novas ou existentes (Polymarket/py-clob-client). Os substitutos são py-sdk, instalado com pip install polymarket-client, e ts-sdk (Polymarket/py-sdk).

Se você só precisa ler dados, não precisa de biblioteca. Três solicitações GET com requests ou fetch resolvem a descoberta, o preço e o histórico. Uma dependência que não entra no projeto não pode ser arquivada no meio do caminho.

Um exemplo de leitura em Python

import requests

GAMMA = "https://gamma-api.polymarket.com"
CLOB = "https://clob.polymarket.com"

# 1. Vinte eventos abertos, começando pelos mais movimentados.
events = requests.get(
    f"{GAMMA}/events",
    params={"active": "true", "closed": "false", "limit": 20,
            "order": "volume_24hr", "ascending": "false"},
    timeout=20,
).json()

for event in events:
    print(event["title"])
    for market in event.get("markets", []):
        # outcomePrices e clobTokenIds chegam como strings JSON.
        prices = market.get("outcomePrices")
        print("   ", market["question"], prices)

# 2. Ponto médio ao vivo para um token de resultado.
token_id = "REPLACE_WITH_A_CLOB_TOKEN_ID"
mid = requests.get(f"{CLOB}/midpoint", params={"token_id": token_id}, timeout=20).json()
print("midpoint:", mid)

A saída esperada tem uma linha por evento e outra linha recuada por mercado, com os preços dos resultados como strings. Depois vem um único dicionário, como {'mid': '0.895'}. Observe a codificação: a Gamma devolve outcomePrices e clobTokenIds como strings JSON dentro do JSON. É preciso analisá-las uma segunda vez antes do uso.

Antes de agendar o código, trate estes problemas: evento sem nenhum mercado, outcomePrices ausente porque o mercado ainda não teve negociação, slug que deixou de existir após uma mudança de nome e controle de fluxo que aparece como resposta lenta, não como erro.

Onde isso deixa de funcionar?

Restrições por país são o primeiro obstáculo. A Polymarket está bloqueada na Itália desde 27 de julho de 2026 por ordem da Agenzia delle Dogane e dei Monopoli, aplicada pelos provedores de internet no DNS (Key4biz, 28 de julho de 2026). O bloqueio também aponta os hostnames da API para a página de aviso da agência. Assim, uma solicitação a gamma-api.polymarket.com feita de uma conexão italiana falha com erro de certificado, em vez de devolver dados.

No Brasil, a base é outra. A Resolução CMN nº 5.298, de 24 de abril de 2026 veda derivativos ligados a eventos políticos, eleitorais, sociais, culturais, de entretenimento e outros sem referência econômico-financeira. O acesso técnico a um endpoint público e a autorização para negociar não são a mesma coisa. Antes de operar ou automatizar ordens, verifique as regras aplicáveis. Isto não é orientação jurídica.

O segundo obstáculo é que ler preços não equivale a manter um histórico. A API da Polymarket informa o que o mercado pensa. Ela não registra o que você pensou, quando pensou nem se estava certo. Essa é uma camada diferente, a que transforma um fluxo de dados em histórico.

É isso que a API da insiderz oferece. Ela lista os mesmos eventos e recebe uma call, ou seja, uma previsão pública, travada com o horário e o preço de mercado daquele instante. Quando o evento é resolvido, compara a call com o mercado. Não há dinheiro. Bots usam os mesmos endpoints, as mesmas regras e o mesmo ranking das pessoas. Se você está criando a parte de previsão, não a parte de negociação, leia como criar um bot de previsão ou vá direto para a versão em 100 linhas de Python.