O SDK Python da Polymarket em 2026 (e como sair do py-clob-client)

Isso importa mais do que uma atualização de versão comum por um motivo: quase todo exemplo de código da Polymarket na internet é anterior a ele. Posts de blog, respostas no Stack Overflow, exemplos no GitHub e — como foram treinados com esse material — o código que seu assistente de IA escreve quando você pede um bot para a Polymarket. Se você já se pegou depurando imports que não existem, é por isso.

O que realmente mudou

A abordagem antiga dava a você um cliente por serviço da Polymarket. Você importava um cliente CLOB para o livro de ofertas, chamava a Gamma por HTTP cru para descobrir mercados, acessava a Data API separadamente para posições e incluía um pacote de builder-signing se precisasse de transações do relayer. Quatro modelos mentais, quatro formatos de erro, quatro estilos de paginação.

O SDK unificado junta tudo isso em um só cliente que cobre todas as superfícies.

Instalação

pip install polymarket-client
# uv add polymarket-client
# poetry add polymarket-client

Quatro clientes — escolha com cuidado

import asyncio
from polymarket import AsyncPublicClient


async def main() -> None:
    async with AsyncPublicClient() as client:
        pages = client.list_markets(closed=False)
        first = await pages.first_page()
        for market in first.items:
            print(market.slug)


asyncio.run(main())

Os dados públicos não exigem credenciais, então construa e teste tudo o que puder com o AsyncPublicClient antes de introduzir uma chave. Descoberta, parsing, paginação, geração de sinais e backoff podem ser exercitados sem nada em risco.

Paginação

Uma única interface de paginador em todos os métodos de listagem. Três formas de consumi-lo, dependendo de você se importar ou não com os limites entre páginas:

pages = client.list_markets(closed=False, page_size=10)

# 1. Page at a time — use this when you need to control pacing
#    against the tight /markets rate limit (300 req / 10s).
async for page in pages:
    for market in page.items:
        ...

# 2. Item at a time, boundaries ignored.
async for market in pages.iter_items():
    ...

# 3. Manual, resumable.
page = await pages.first_page()
if page.next_cursor:
    nxt = await pages.from_cursor(page.next_cursor).first_page()

Modelos tipados

Os métodos retornam tipos de verdade em vez de dicionários, exportados pelo pacote de nível superior:

from polymarket import Event, Market, OrderBook, PriceHistoryPoint

Esta é a melhoria menos glamorosa e provavelmente a mais valiosa. Com os clientes antigos, um campo renomeado ou ausente aparecia como um KeyError no fundo do loop da sua estratégia, em tempo de execução — muitas vezes em produção, muitas vezes com uma posição aberta. Os modelos tipados levam essa falha para onde ela deve estar.

Assinaturas em tempo real

subscribe() junta vários feeds em um único stream de eventos tipados, o que é uma melhoria genuína em relação a gerenciar várias conexões WebSocket na mão.

from polymarket.streams import MarketSpec, SportsSpec

async with await client.subscribe(
    [MarketSpec(token_ids=[token_id]), SportsSpec()],
) as stream:
    async for event in stream:
        # MarketBookEvent | MarketPriceChangeEvent
        # | MarketLastTradePriceEvent | MarketTickSizeChangeEvent
        # | MarketBestBidAskEvent | NewMarketEvent
        # | MarketResolvedEvent | SportsEvent
        handle(event)

O SDK cuida do heartbeat, dos frames e das reconexões que você teria que implementar por conta própria — incluindo a exigência de enviar PING a cada 10 segundos em uma conexão crua. Detalhes no guia de WebSocket.

Enviando uma ordem

market = await client.get_market(slug="<market-slug>")
token_id = market.outcomes.yes.token_id
assert token_id is not None

response = await client.place_market_order(
    token_id=token_id,
    side="BUY",
    amount="10",     # pUSD to spend, not shares to buy
)

if not response.ok:
    raise RuntimeError(response.message)

# Settlement is on-chain and asynchronous.
hashes = await client.wait_for_order_fill_settlement(response)

# Reconcile rather than assuming.
page = await client.list_positions(market=[market.condition_id]).first_page()
position = next((p for p in page.items if p.token_id == token_id), None)

Migrando do py-clob-client

1. Faça um inventário de todas as chamadas à Polymarket, incluindo chamadas cruas com requests para a Gamma e a Data API. Elas também entram no escopo — o SDK unificado as cobre, e incorporá-las é a maior parte do benefício.
2. Instale o polymarket-client e remova os pacotes antigos. Manter os dois instalados para migrar aos poucos é um convite para importar o símbolo client errado.
3. Substitua a construção dos clientes. Um único AsyncSecureClient.create(...) substitui os antigos clientes por serviço e o tratamento separado de credenciais de cada um.
4. Troque o acesso por dict por acesso por atributo. market["condition_id"] vira market.condition_id. É tedioso, e é aí que o verificador de tipos começa a se pagar.
5. Reescreva a paginação com a interface de paginador em vez de loops manuais de offset ou cursor.
6. Substitua o código WebSocket feito à mão por subscribe() e apague sua lógica de heartbeat e reconexão.
7. Rode primeiro de novo os seus caminhos somente leitura, com o cliente público, antes de deixar qualquer coisa enviar uma ordem.

Por que seu assistente de IA erra nisso

Vale tratar disso diretamente, já que é assim que muita gente chega aqui. Peça a um LLM código Python para a Polymarket e você vai receber, com muita frequência, imports de py_clob_client, construção de ClobClient(...) e objetos OrderArgs. O modelo não está com defeito — ele está reproduzindo a esmagadora maioria do código da Polymarket que já viu, que é anterior aos SDKs unificados.

• Confira primeiro a linha de import. from polymarket import ... é o atual; from py_clob_client... não é.
• Cole a documentação atual no contexto. A Polymarket publica Markdown legível por máquina em docs.polymarket.com/llms.txt, e toda página tem uma variante .md. Dar ao modelo a coisa real funciona melhor do que discutir com ele.
• Desconfie de código confiante que não roda. O código gerado frequentemente mistura APIs antigas e novas em algo que nunca existiu.

O mesmo problema vale para provedores de dados. Publicamos llms.txt, llms-full.txt e uma especificação OpenAPI, e permitimos crawlers de IA, justamente para que os assistentes consigam escrever integrações corretas com a PolyTest sem chutar. Alguns provedores bloqueiam esses crawlers, o que é uma escolha legítima, mas significa que seu assistente vai improvisar a superfície da API deles.

O que o SDK ainda não consegue fazer

O SDK unificado é uma interface muito melhor para as APIs da Polymarket. Ele não muda o que essas APIs contêm — e o que quem constrói bots mais quer não está nelas.

Não existe livro de ofertas histórico. client.get_market() retorna os metadados de um mercado resolvido, mas o livro dele sumiu: /book retorna 404, e prices-history guarda só cerca de um ponto por minuto. Nenhum método do SDK, plano ou credencial recupera o livro.

Para fazer backtesting você precisa de snapshots gravados enquanto os mercados estavam ativos. A PolyTest os oferece para os mercados cripto Up/Down — mais de 240M de snapshots pontuais, 8 níveis de profundidade por lado, timestamps abaixo de um segundo, mercados resolvidos mantidos. É uma API REST simples com um header X-API-Key, então entra no mesmo código assíncrono, ao lado do SDK. Comece grátis ou leia como criar um bot para ver o caminho completo.