WebSockets da Polymarket: dados em tempo real que não caem

Se o seu bot faz polling de GET /book com um timer, esta página vai poupar a maior parte do seu orçamento de limite de requisições e um bom pedaço de latência. A Polymarket envia as atualizações do livro por WebSocket, e uma assinatura custa uma conexão em vez de milhares de requisições.

Os quatro streams

Assinando o canal market

Conecte-se e envie uma mensagem JSON de assinatura. assets_ids recebe IDs de tokens — os mesmos que você obtém dos metadados do mercado — e type precisa ser "market".

{
  "assets_ids": ["65818619657568813474341868652308942079804919287380422192892211131408793125422"],
  "type": "market",
  "initial_dump": true,
  "level": 2,
  "custom_feature_enabled": true
}

Mantenha initial_dump: true, a menos que tenha um motivo específico para não fazer isso. Sem ele, você começa sem nenhum estado do livro e precisa esperar as atualizações incrementais para reconstruí-lo, o que significa que seu bot começa a vida com uma visão incompleta.

Tipos de mensagem

Toda mensagem traz um event_type. Trate todos os casos — um tipo desconhecido deve ser registrado em log, não descartado em silêncio, porque é assim que você descobre que o protocolo mudou.

Mantendo a conexão: PING a cada 10 segundos

Esta é a exigência que pega todo mundo. O cliente precisa enviar um PING a cada 10 segundos; o servidor responde PONG. Perca o heartbeat e a conexão cai.

Repare na direção: é um heartbeat do cliente. Você não está esperando o servidor mandar ping para você. O keepalive embutido de uma biblioteca WebSocket em outro intervalo não substitui isso — envie você mesmo o PING no nível da aplicação.

import asyncio, json, time
import websockets

URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"
STALE_AFTER = 30          # seconds without any message = treat as dead


async def stream(token_ids, on_event):
    backoff = 1
    while True:
        try:
            async with websockets.connect(URL) as ws:
                await ws.send(json.dumps({
                    "assets_ids": token_ids,
                    "type": "market",
                    "initial_dump": True,
                    "custom_feature_enabled": True,   # or lose 3 event types
                }))
                backoff = 1                            # reconnected cleanly
                last_msg = time.monotonic()

                async def heartbeat():
                    while True:
                        await asyncio.sleep(10)        # required cadence
                        await ws.send("PING")

                hb = asyncio.create_task(heartbeat())
                try:
                    while True:
                        # Silence is a failure mode, not a quiet market.
                        raw = await asyncio.wait_for(ws.recv(), timeout=STALE_AFTER)
                        last_msg = time.monotonic()
                        if raw == "PONG":
                            continue
                        for msg in json.loads(raw) if raw.startswith("[") else [json.loads(raw)]:
                            on_event(msg)
                finally:
                    hb.cancel()

        except Exception as exc:
            # Reconnect with capped exponential backoff + jitter.
            wait = min(backoff, 30) * (0.5 + 0.5 * asyncio.get_event_loop().time() % 1)
            print(f"ws down ({exc}); reconnecting in {wait:.1f}s")
            await asyncio.sleep(wait)
            backoff = min(backoff * 2, 30)

Mudando as assinaturas sem reconectar

Mercados de cinco minutos vencem o tempo todo, então um bot que acompanha os “mercados BTC 5m atuais” precisa mudar o conjunto de assinaturas continuamente. Você não precisa derrubar a conexão para isso — o canal market aceita assinar e cancelar assinaturas em uma conexão ativa.

Isso importa mais do que parece. Reconectar a cada rotação de mercado significa pagar repetidamente o custo de abrir a conexão, pedir de novo os initial dumps e criar uma janela em que você não recebe nada justamente no momento em que um novo mercado abre.

O modo de falha que custa dinheiro

Um WebSocket que caiu não lança exceção. Ele para de entregar mensagens. Para um bot ingênuo, “nenhuma atualização” é indistinguível de “o mercado não está se mexendo” — então um bot com uma posição aberta vai ficar parado em um preço defasado indefinidamente, certo de que nada mudou.

• Acompanhe a idade da última mensagem. Se nada chegou em ~30 segundos em um mercado ativo, você está desconectado, não em calmaria. O timeout de asyncio.wait_for acima faz exatamente esse trabalho.
• Trate a defasagem como condição de erro. Pare de cotar, zere a posição se as suas regras de risco exigirem e reconecte — não continue operando com um livro congelado.
• Use backoff na reconexão, com jitter. Um loop de reconexão apertado durante uma queda é o jeito de ser limitado por taxa além de desconectado, e uma frota reconectando em sincronia piora tudo.
• Ressincronize o estado depois de reconectar. Você perdeu atualizações enquanto esteve fora. Tome o novo initial_dump como verdade e descarte seu livro anterior, em vez de juntar atualizações incrementais a um snapshot defasado.
• Reconcilie as posições depois de qualquer lacuna. Se você ficou desconectado do canal User, pode ter perdido uma execução. Leia as posições de novo antes de agir com base em um estado presumido.

WebSockets e limites de requisições

Uma pergunta frequente, e a resposta é o objetivo de todo o exercício: uma assinatura não consome o orçamento de limite por requisição como o polling consome. Os limites documentados da Polymarket são limites HTTP por endpoint, e o streaming os contorna quase por completo.

Você ainda vai fazer chamadas HTTP — descoberta de mercados, tick sizes, envio de ordens, reconciliação de posições — e elas continuam sujeitas aos limites de requisições documentados. O streaming só elimina a maior e menos útil fonte de volume de requisições.

O que os streams não vão dar a você

Um limite que vale dizer com clareza, porque é a próxima coisa que as pessoas tentam. Um WebSocket dá a você o livro a partir do momento em que você assina. Ele não consegue dar o livro da última terça-feira.

A Polymarket não guarda livro de ofertas histórico. Depois que um mercado é resolvido, o livro dele retorna 404, e prices-history guarda só cerca de um ponto por minuto. Se você quer testar uma estratégia contra como os mercados realmente foram negociados, precisa de snapshots que alguém gravou na hora. A PolyTest faz isso para os mercados cripto Up/Down, com 8 níveis de profundidade por lado e mercados resolvidos mantidos. Ou comece hoje o seu próprio coletor, aceite que você parte de zero histórico e espere.