Como escolher uma API de dados da Polymarket

Se você está procurando dados históricos da Polymarket, já bateu na parede que traz todo mundo aqui: a API da própria Polymarket serve só o estado atual. Peça o livro de ofertas de um mercado resolvido e você recebe um 404; o histórico de preços que ela guarda tem cerca de um ponto por minuto, sem nada sobre profundidade. Nenhum dos dois está bloqueado atrás de um plano. O livro simplesmente não está lá.

Então você precisa de um provedor que gravou o livro enquanto os mercados estavam ativos. O problema é que todo provedor desse setor divulga o mesmo número de destaque, e ele está entre os menos informativos que existem. Veja o que verificar em vez disso.

1. Snapshots por mercado por minuto, não total de snapshots

O total de snapshots é o número de destaque em todo lugar, e ele quase não significa nada. Um total é só taxa de captura × mercados acompanhados × tempo de coleta. Um provedor com um número maior pode ter melhor resolução — ou pode simplesmente estar coletando há mais tempo, ou contando linhas redundantes em mercados que ninguém negocia.

O que você realmente precisa saber é: no mercado específico que me interessa, quantos snapshots por minuto eu recebo? Um mercado de 5 minutos amostrado duas vezes por minuto dá a você dez pontos de dados para modelar todo o ciclo de vida de um mercado. Isso não basta para testar nada.

# Pull the same market from each provider, then compare density.
snaps = fetch_snapshots(market_id)          # provider-specific call

span_s  = (snaps[-1]["timestamp"] - snaps[0]["timestamp"]) / 1000
per_min = len(snaps) / (span_s / 60)

print(f"{len(snaps)} snapshots over {span_s:.0f}s = {per_min:.1f}/min")

# Gaps matter more than the average. One 90-second hole in a 5-minute
# market means you cannot model the part where it was decided.
gaps = [
    (b["timestamp"] - a["timestamp"]) / 1000
    for a, b in zip(snaps, snaps[1:])
]
print(f"max gap: {max(gaps):.1f}s   median: {sorted(gaps)[len(gaps)//2]:.1f}s")

2. Profundidade real do livro, ou só o topo do livro?

Esse é o maior fator isolado para o seu backtest significar alguma coisa, e é onde a linguagem de marketing fica mais escorregadia. “Dados do livro de ofertas” pode significar qualquer coisa, da escada completa a um único par de bid/ask.

Se você pretende operar qualquer tamanho relevante, precisa da escada. Uma ordem de 500 cotas em um mercado Up/Down raso não é executada no primeiro nível — ela percorre o livro, e a diferença entre o primeiro nível e o seu preço médio real de execução é frequentemente maior do que a vantagem que você está testando.

def simulate_fill(levels, qty):
    """Walk the ladder. This is what actually happens to your order."""
    filled = cost = 0.0
    for lvl in levels:
        take = min(lvl["size"], qty - filled)
        cost += take * lvl["price"]
        filled += take
        if filled >= qty:
            break
    if filled < qty:
        return None            # Not enough liquidity to fill at all.
    return cost / filled

book = snapshot["orderbook"]["asks"]
print("top of book:", book[0]["price"])
print("true fill  :", simulate_fill(book, 500))
# A gap of 2-3c here on a $1 binary is routine, and it is
# larger than most claimed edges.

3. Os mercados resolvidos são realmente mantidos?

O motivo inteiro de pagar por esses dados é que a Polymarket os descarta. Então verifique se o provedor realmente os guarda, em vez de só repassar os endpoints ao vivo com um cache.

O teste leva um minuto: encontre um mercado resolvido há semanas, peça os snapshots dele e confirme que você recebe o caminho de preços completo com profundidade — não só um registro de metadados dizendo qual lado ganhou. Saber o resultado não é dado; toda estratégia que vale a pena testar é sobre o caminho, não sobre a resposta.

4. Janela de histórico versus profundidade de histórico

Os provedores vendem histórico em dois formatos diferentes, e a distinção importa mais do que o número bruto de dias:

• Uma janela móvel — os N dias mais recentes, com os dados mais antigos saindo. Serve para ajustar estratégias às condições atuais do mercado.
• Um arquivo mantido — tudo desde o início da coleta. Necessário se você quer testar em diferentes regimes de volatilidade.

Do que você precisa depende, honestamente, da sua estratégia. Se você opera mercados de 5 minutos e reajusta toda semana, 30 dias bastam e pagar por mais é desperdício. Se você quer saber se a sua vantagem sobreviveu às condições do ano passado, uma janela móvel não consegue responder a isso por preço nenhum.

5. Vazão que você consegue usar de verdade

Limites de requisições parecem um detalhe até você rodar seu primeiro backtest de verdade. Puxar todos os snapshots de um mês de mercados de 5 minutos em três moedas são muitas requisições, e um limite de 10 req/s transforma uma tarde de pesquisa em um trabalho que roda a noite toda.

Dois números importam, e os provedores muitas vezes publicam só um: vazão sustentada (requisições por minuto) e capacidade de pico (requisições por segundo). Um limite alto por minuto com um pico baixo ainda trava uma busca em paralelo.

Se você puxa histórico em massa com frequência, pergunte também se existe um caminho de exportação em massa. Paginar um milhão de snapshots por um endpoint REST é possível, mas não é a ferramenta certa.

6. Dá para avaliar antes de pagar?

Não dá para avaliar a qualidade dos dados por uma página de marketing. Qualquer provedor confiante nos seus dados vai deixar você olhar para eles antes de pagar, com um plano gratuito ou um teste, e de preferência com uma referência da API que você consiga ler sem se cadastrar.

Mas tenha clareza sobre para que serve um plano gratuito ou um teste. O nosso é um teste de 3 dias do plano Builder completo, com profundidade do livro de ofertas incluída, para você conferir a cobertura, a densidade de snapshots e o formato das respostas antes de se comprometer — mas três dias e uma janela de 14 dias fazem dele uma ferramenta de avaliação, e não um plano de pesquisa. Seja qual for o provedor, descubra quais partes realmente podem ser exercitadas de graça antes de tirar conclusões.

7. Suas ferramentas conseguem ler a documentação?

Uma consideração mais recente, e que vale verificar porque é invisível até morder. Se você constrói com Cursor, Claude Code ou Codex, a capacidade do seu assistente de escrever uma integração correta depende de ele conseguir ler a documentação do provedor.

Alguns provedores de dados bloqueiam crawlers de IA no robots.txt — uma escolha legítima sobre dados de treinamento, mas que significa que os modelos não conseguem ver a documentação deles e vão improvisar uma superfície de API. Você consegue verificar qualquer provedor em uns cinco segundos:

curl -s https://<provider>/robots.txt | grep -iA1 "GPTBot\|ClaudeBot\|Google-Extended"

# "Disallow: /" under those agents means your AI assistant
# cannot read their docs and will guess at the API instead.

Como referência, a PolyTest permite esses crawlers e publica llms.txt, llms-full.txt e uma especificação OpenAPI. Mas o teste prático é mais simples do que ler arquivos de política: peça ao seu assistente que escreva uma integração com cada provedor e veja qual produz código que funciona.

Quando você não deveria pagar ninguém

Vale dizer com clareza, já que isso se aplica a nós tanto quanto a qualquer um. Você não precisa de um provedor de dados pago se:

• Você só precisa de dados ao vivo. A API pública e os streams WebSocket da Polymarket são gratuitos, não exigem autenticação para dados de mercado e são perfeitamente bons. Provedores de histórico existem para o histórico, e nada mais.
• Você está testando infraestrutura, não uma estratégia. Autenticação, parsing, reconexões e tratamento de limites de requisições podem ser exercitados nos endpoints ao vivo gratuitos.
• Sua estratégia não depende de execuções. Se você estuda taxas-base ou frequências de resolução, essa informação sobrevive nos metadados públicos.
• Você está disposto a gravar os dados por conta própria. Rodar um coletor no WebSocket público é totalmente viável. Custa um servidor pequeno e a disciplina de mantê-lo rodando — o problema é que você começa com zero histórico e não consegue preencher o passado, então só ajuda se você começar bem antes de precisar dos dados.

O argumento para pagar é estreito e específico: você quer um histórico que não gravou, a partir de hoje.

Um teste que você pode rodar hoje à tarde

1. Cadastre-se no plano gratuito ou no teste de todos os provedores da sua lista.
2. Escolha um mercado — mesma moeda, mesmo timeframe, mesmo dia — e puxe-o de cada um.
3. Compare os snapshots por minuto e a lacuna máxima. Densidade e continuidade valem mais do que qualquer número de destaque.
4. Verifique os níveis do livro por snapshot. Se não for uma escada, você não consegue modelar execuções.
5. Peça um mercado resolvido há um mês e confirme que você recebe o caminho completo, não só um resultado.
6. Rode o seu padrão de consulta realista mais pesado e veja qual provedor limita você primeiro.
7. Peça ao seu assistente de IA que escreva uma integração com cada um e veja qual documentação ele realmente consegue ler.

Essa sequência leva uma tarde e diz mais do que qualquer tabela comparativa, incluindo esta. Se quiser começar pela nossa, há um teste grátis de 3 dias, e a referência de endpoints pode ser lida sem nenhum cadastro.