API REST: Consultar Mercados, Books e Histórico

Aula 13: API REST — Consultar Mercados

A API REST da Polymarket permite consultar mercados, books de ordens, histórico de preços e muito mais. Todas as chamadas de leitura são públicas — não precisas de autenticação para consultar dados.

Mecanismo: A API segue o padrão REST com respostas JSON. Os endpoints principais são /markets (lista de mercados), /book (ordens por mercado) e /price (histórico de preços). Suporta paginação, filtros por tag, e parâmetros de ordenação.

import requests

HOST = "https://clob.polymarket.com"

# Listar mercados de futebol abertos
resp = requests.get(
    f"{HOST}/markets",
    params={"limit": 100, "offset": 0, "tag": "soccer", "closed": False},
)
markets = resp.json()
for m in markets["data"]:
    print(f"{m['question'][:60]:60s} | Vol: {m['volume']:>10s} | Liq: {m['liquidity']:>10s}")

# Obter book de ordens para um mercado específico
if markets["data"]:
    market_id = markets["data"][0]["condition_id"]
    book_resp = requests.get(f"{HOST}/book", params={"token_id": market_id})
    book = book_resp.json()
    print(f"\nBest Bid: {book['bids'][0]['price'] if book['bids'] else 'N/A'}")
    print(f"Best Ask: {book['asks'][0]['price'] if book['asks'] else 'N/A'}")

Aprofundamento operacional

A API REST transforma a Polymarket em fonte de research, mas dados brutos nao sao inteligencia. Antes de calcular qualquer metrica, voce precisa saber o que cada endpoint entrega, qual e a unidade de cada campo e como lidar com paginacao, mercados encerrados e campos ausentes.

O erro comum e montar um dataset com a primeira resposta bem-sucedida e assumir que ela representa o mercado inteiro. Em prediction markets, isso gera viesses: voce perde mercados sem liquidez, ignora historico incompleto e mistura eventos com estados de vida diferentes.

Pipeline minimo de dados

1. Descobrir mercados por categoria, tag ou busca.
2. Normalizar IDs: event, market, condition e token.
3. Buscar book e precos atuais.
4. Buscar historico quando a pergunta exigir movimento.
5. Salvar timestamp da coleta.
6. Validar campos obrigatorios antes de calcular sinais.

Exercicio pratico

Monte uma tabela com cinco mercados e estas colunas: question, condition_id, token_id, best_bid, best_ask, spread, volume, liquidity, end_date e collected_at. Sem essa normalizacao, qualquer modelo posterior fica fragil.

Auditoria aplicada

Esta aula deve terminar com uma pequena auditoria escrita. O objetivo nao e produzir uma nota bonita, mas transformar “API REST: Consultar Mercados, Books e Histórico” em uma decisao verificavel. Use os conceitos centrais da aula (os conceitos principais da aula) para construir um registro que possa ser revisado depois, quando o mercado ja tiver se movido ou o evento ja tiver sido resolvido.

Comece pela pergunta operacional: o que eu consigo observar agora que muda minha decisao? Depois separe evidencia, inferencia e decisao. Evidencia e dado verificavel: preco, spread, profundidade, regra de resolucao, horario, volume, estado do book, endpoint consultado ou custo calculado. Inferencia e a leitura que voce faz a partir desses dados. Decisao e o que voce faz com a leitura: estudar mais, descartar, entrar com ordem limit, esperar liquidez, reduzir stake, usar API apenas para leitura ou classificar como No Bet.

Protocolo de revisao

1. Escreva a tese em uma frase curta.
2. Liste os tres dados que sustentam a tese.
3. Liste o principal dado que poderia invalidar a tese.
4. Defina o custo de estar errado: perda financeira, slippage, fee, tempo preso, erro de resolucao ou risco operacional.
5. Defina o gatilho de pausa. Se esse gatilho acontecer, a decisao deve ser reavaliada antes de qualquer nova ordem.

Perguntas de controle

• O mercado esta suficientemente liquido para o tamanho que eu quero usar?
• O preco atual ainda paga o risco depois de spread, fees e slippage?
• A regra de resolucao esta clara o suficiente para eu aceitar exposicao?
• Se eu estivesse explicando este trade para outra pessoa, conseguiria separar dado de opiniao?
• Existe um caminho simples de saida se a leitura estiver errada?

Saida esperada

No fim da aula, salve uma nota de cinco linhas: mercado observado, preco observado, risco principal, decisao tomada e motivo para revisar depois. Esse habito cria memoria operacional. Sem memoria, o operador repete erros com mais confianca. Com memoria, cada aula vira uma parte do sistema de pesquisa.