Guia da API da Polymarket: Conecte um Bot em 5 Passos

Autenticação

Assinatura de carteira, depois uma API key derivada dela. Mantenha a chave privada fora do host do bot se puder.

Leitura

Gamma API para mercados e metadados, sem autenticação. CLOB API para o livro.

Operação

CLOB API, requisições assinadas. Compras como ordens a mercado, vendas como ordens limitadas.

Taxa de taker

0.07 x p x (1-p) por ação nos mercados de cripto. Makers não pagam nada.

Liquidação

Mercados curtos de cripto liquidam pela média de 60 segundos do oráculo contra a abertura da janela.

Geografia

Bloqueia EUA, Reino Unido, França e vários outros países.

Docs

docs.polymarket.com

Cinco passos, simplificados de propósito. Os trechos mostram o formato de cada chamada, não código de produção: sem retries, sem tratamento de erros, sem backoff de rate limit. A biblioteca cliente oficial cuida da assinatura; os exemplos a utilizam.

1. Instale o cliente e derive as credenciais

   A Polymarket migrou para a CLOB v2 em 2026, então use o cliente v2. As credenciais são derivadas de uma assinatura de carteira uma única vez e depois reutilizadas.

   pip install py-clob-client-v2
   
   from py_clob_client.client import ClobClient
   
   HOST = "https://clob.polymarket.com"
   client = ClobClient(HOST, key=PRIVATE_KEY, chain_id=137, signature_type=1)
   creds = client.create_or_derive_api_key()   # assine uma vez, guarde o resultado
   client.set_api_creds(creds)

   Contas criadas por e-mail usam um tipo de assinatura diferente das contas por carteira. Vários tipos autenticam sem problema, mas só o certo enxerga seu saldo, então confira a chamada de saldo antes de operar.

2. Encontre o mercado e seus token ids

   A Gamma é o catálogo somente leitura. Os slugs dos mercados curtos de cripto são determinísticos, e um mercado fechado desaparece das consultas por slug mas continua acessível pelo id numérico.

   import requests
   
   GAMMA = "https://gamma-api.polymarket.com"
   m = requests.get(f"{GAMMA}/markets", params={"slug": "btc-updown-5m-1757500800"}).json()[0]
   up_token, down_token = m["clobTokenIds"]     # um token por resultado
   market_id = m["id"]                           # guarde isto: sobrevive ao fechamento

3. Leia o livro

   book = client.get_order_book(up_token)
   best_ask = float(book.asks[0].price)    # o que uma compra paga agora
   best_bid = float(book.bids[0].price)    # o que uma venda recebe agora
   spread = best_ask - best_bid            # pule a janela se isto estiver largo

   Registre cada leitura com o relógio em que foi feita. Uma janela sem leitura recente não é uma operação que você poderia ter feito.

4. Envie uma ordem

   Uma compra fill-or-kill precisa ser uma ordem a mercado por um valor em dólares com no máximo duas casas decimais. Vendas funcionam como ordens limitadas que tomam o que está disponível.

   from py_clob_client.clob_types import MarketOrderArgs, OrderArgs, OrderType
   
   buy = client.create_market_order(MarketOrderArgs(token_id=up_token, amount=25.00, side="BUY"))
   resp = client.post_order(buy, OrderType.FOK)
   assert resp.get("success"), resp          # lance exceção em qualquer outro caso, nunca presuma uma execução
   
   sell = client.create_order(OrderArgs(token_id=up_token, price=0.90, size=30, side="SELL"))
   client.post_order(sell, OrderType.FAK)

   Uma ordem pode dar erro na rede e mesmo assim ser executada. Consulte suas operações após qualquer exceção e reconcilie antes da próxima janela.

5. Leia as execuções e resgate

   Os ganhos não se resgatam sozinhos. Após a liquidação, as ações ficam na carteira até você resgatar a condição, e um saldo não resgatado acaba bloqueando novas ordens.

   fills = client.get_trades()                # suas execuções, com a taxa paga por execução
   # O resgate é uma chamada on-chain por condition id. O cliente relayer encapsula isso;
   # sem ele, resgate na interface web todos os dias.

O que conferir antes de usar dinheiro real

• Confirme que a taxa na sua primeira execução real bate com 0.07 x p x (1-p). Bateu em todas as execuções registradas.
• O mínimo por ordem é 5 ações; apostas percentuais minúsculas são arredondadas para cima ou rejeitadas.
• Os rate limits são generosos para um único bot, mas agrupe as leituras do livro onde a API permitir.
• Recompensas para makers existem em alguns mercados e exigem um tamanho mínimo de ordem, atualmente 50 ações. Uma cotação de 10 ações não rende nada.