Guia da API da Polymarket - Crie o seu primeiro bot de trading em 2026

Capítulo 27 de 33

A versão curta

A Polymarket expõe três APIs públicas: CLOB (trading), Gamma (descoberta de mercados) e Data (analítica). O SDK oficial de Python é o py-clob-client 0.34.6. A autenticação usa uma chave de API + assinatura ECDSA, com as ordens assinadas via EIP-712 através de uma carteira proxy na Polygon. Os limites de taxa restringem você a cerca de 60 ordens/minuto por chave. O maior obstáculo para desenvolvedores novatos é o problema de mapeamento entre condition_id → token_id entre o Gamma e o CLOB - resolva-o primeiro e todo o resto se encaixa. Todo mês, ganha-se na Polymarket cerca de 40 milhões $ em recompensas de liquidez e spread capturado por bots, quase inteiramente por usuários da API.

Parte 1: As três APIs

A Polymarket separa de forma limpa as responsabilidades em três serviços distintos. Usar a API certa para cada tarefa mantém o seu bot rápido, simples e dentro dos limites de taxa.

Um loop de bot típico usa o Gamma para encontrar mercados, o CLOB para buscar order books e enviar operações, e o Data para fazer back-test do desempenho da estratégia offline. Pense no Gamma como o "catálogo", no CLOB como a "bolsa" e no Data como o "armazém".

Parte 2: Autenticação e o modelo de carteira proxy

A Polymarket não assina as operações com a chave privada da sua carteira principal. Em vez disso, usa uma carteira proxy no estilo Gnosis Safe: a sua carteira principal autoriza um proxy, e o proxy executa todas as operações na Polygon. O seu bot de API conversa com esse proxy.

O que você precisa

• Chave de API - gere em Settings → Developer da Polymarket
• Chave privada - a chave da sua carteira de trading (NÃO a frase semente da sua MetaMask principal)
• Endereço funder - o endereço da sua carteira proxy (mostrado em Settings → Wallet)
• Chain ID - 137 (Polygon mainnet)
• Tipo de assinatura - 1 (POLY_PROXY, padrão para usuários de varejo)

Parte 3: Instalar o py-clob-client

O SDK oficial de Python é a forma mais rápida de ir do zero à sua primeira ordem. Usaremos a versão 0.34.6, que é a atual em abril de 2026.

# Create a virtual environment first
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# Install the SDK
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

Configuração básica do cliente

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON

load_dotenv()

client = ClobClient(
 host="https://clob.polymarket.com",
 key=os.environ["POLY_PRIVATE_KEY"],
 chain_id=POLYGON, # 137
 signature_type=1, # POLY_PROXY
 funder=os.environ["POLY_FUNDER"],
)

# One-time: derive and cache API credentials
client.set_api_creds(client.create_or_derive_api_creds())

A chamada a create_or_derive_api_creds() assina uma mensagem com a sua chave privada e a troca por uma chave de API, um secret e uma passphrase. Coloque-os em cache no seu .env após a primeira execução para não chamar o endpoint de derivação a cada inicialização.

Parte 4: Descobrir mercados via Gamma

Antes de poder operar, você precisa encontrar mercados que valham a pena. O Gamma retorna JSON com tudo o que a interface da Polymarket mostra: pergunta, resultados, preços, volume 24h, vencimento, tags e imagens.

import requests

resp = requests.get(
 "https://gamma-api.polymarket.com/markets",
 params={
 "active": "true",
 "closed": "false",
 "tag_slug": "politics",
 "limit": 20,
 "order": "volume24hr",
 "ascending": "false",
 },
 timeout=10,
)
resp.raise_for_status()
markets = resp.json()

for m in markets:
 print(f"{m['slug']:50} Yes ${float(m['outcomePrices'][0]):.3f} Vol24h ${m.get('volume24hr', 0):,.0f}")

Parâmetros úteis de consulta do Gamma

Parte 5: O mapeamento condition_id → token_id

Este é o ponto de dor número 1 no desenvolvimento de bots da Polymarket. O Gamma retorna um condition_id (um por mercado). As operações do CLOB usam um token_id (um por resultado). Você sempre precisa dos dois.

# Each Gamma market object contains 'clobTokenIds' - a JSON string array
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # First outcome
no_token = token_ids[1] # Second outcome

# Alternative: ask CLOB directly using condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

A pegadinha da ordem dos resultados

O array outcomes e o array clobTokenIds do Gamma são indexados entre si. Sempre leia o rótulo do resultado em vez de supor que o índice 0 é "Yes". Em mercados de múltiplos resultados (NegRisk, Oscar, eleições), o índice 0 pode ser "Kamala Harris" ou "Taylor Swift" - a ordem é determinística, mas específica de cada mercado.

Parte 6: Ler order books

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

Os order books são retornados como arrays ordenados (bids decrescentes, asks crescentes). Cada nível tem price e size. Para estimar o slippage de uma ordem maior, percorra o livro e acumule nocional até consumir o seu tamanho alvo.

Parte 7: Enviar ordens

Ordem limitada (GTC - o padrão)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # Shares, not dollars. 100 shares @ $0.45 = $45 max cost.
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

A chamada a create_order assina uma mensagem estruturada EIP-712 com a sua chave privada. post_order a envia ao CLOB. Você nunca envia chaves privadas brutas pela rede - apenas ordens assinadas.

Tipos de ordem

Cancelar

# Single order
client.cancel(order_id="0xabc...")

# Cancel all orders on a specific market
client.cancel_market_orders(market=market['conditionId'])

# Nuclear option: cancel everything
client.cancel_all()

Parte 8: Streaming via WebSocket

Consultar o Gamma a cada segundo é desperdício e você atingirá os limites de taxa rápido. O feed de WebSocket transmite atualizações de order book e de operações em tempo real, com latência abaixo de um segundo.

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

Existem dois feeds: o feed /market (order book e operações públicos) e o feed /user (os seus próprios eventos de ordem e execução, autenticado). Bots de produção costumam se conectar a ambos, reconectam automaticamente na desconexão e tratam o WebSocket como a fonte da verdade do estado atual do livro.

Parte 9: Limites de taxa e backoff

Quando você recebe um HTTP 429, o servidor retorna um cabeçalho Retry-After. Implemente um backoff exponencial com jitter:

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Too many retries")

Parte 10: Uma arquitetura de bot de referência

Todo bot robusto da Polymarket tem os mesmos seis componentes. Construa cada um como o seu próprio módulo; mantenha-os fracamente acoplados.

Parte 11: Modos de falha comuns

• Dados de WebSocket desatualizados - Acompanhe o horário da última mensagem por ativo; se não houver atualizações por >30s em um mercado ativo, force um refresh via REST.
• Colisões de nonce - O py-clob-client gerencia os nonce das ordens para você, mas se você escrever o seu próprio assinante, incremente o nonce a cada ordem.
• Saldo insuficiente - Sempre verifique o saldo de pUSD antes de enviar; o livro pode mostrar a sua ordem, mas o casamento a rejeitará.
• Mercado pausado ou em resolução - Verifique market.active && !market.closed antes de operar. As atualizações do Gamma ficam atrás do CLOB em alguns segundos ao redor da resolução.
• Desalinhamento do adaptador NegRisk - Mercados de múltiplos resultados passam por um adaptador NegRisk separado. O SDK cuida disso, mas confirme que a sua ordem foi para o venue correto.

Parte 12: Recompensas de liquidez via API

A Polymarket roda cerca de 5 milhões $/mês em recompensas de liquidez gerais mais 5 milhões $+/mês em recompensas específicas de esportes (ver Recompensas de liquidez). A grande maioria flui para market makers movidos a API que conseguem manter cotações apertadas de dois lados em milhares de mercados.

A fórmula de recompensa premia ordens próximas do ponto médio, o tamanho e o tempo no livro. Um loop de market making mínimo:

1. Leia o order book do mercado alvo
2. Calcule um ponto médio justo (p. ex., VWAP dos 3 níveis superiores de cada lado)
3. Poste um bid em mid − spread_target/2 e um ask em mid + spread_target/2
4. A cada atualização do WebSocket, reprecifique se a sua cotação se desviar mais de um tick do alvo
5. Cancele e saia se o livro afinar ou se surgirem notícias

Parte 13: Ir para produção

• Hospedagem: um VPS de 6 $/mês (Hetzner, DigitalOcean) na Europa ou US-East basta para a maioria dos bots. Co-localize com um Polygon RPC se precisar de latência abaixo de 10ms.
• RPC: use Alchemy, Infura ou QuickNode para um Polygon RPC confiável. Os planos gratuitos servem até você enviar centenas de ordens por minuto.
• Monitoramento: Prometheus + Grafana para métricas; um bot do Telegram para alertas. Registre cada ID de ordem que você envia e cada execução que você recebe.
• Backups: persista o estado a cada minuto. Se o VPS morrer no meio de uma execução, você quer retomar em segundos, não reconciliar na mão.
• Impostos: o seu logger é também a sua trilha de auditoria - ver Guia fiscal.

Parte 14 - Dicas profissionais validadas para a API da Polymarket

Folha de consulta: situação → ação

E agora?

• Ferramentas e recursos - painéis, analítica e feeds de dados de terceiros que complementam a API
• Estratégias avançadas - arbitragem de múltiplas pernas e construções tipo opções adequadas a bots
• Recompensas de liquidez - fórmulas exatas para ganhar rebates de market-making
• Guia do order book - intuição mais profunda para ler o livro antes de programar contra ele
• Glossário - definições em linguagem simples de cada termo deste guia