API da Polymarket e API da Kalshi: preços, livros de ofertas e arbitragem entre elas
Em resumo
- Polymarket e Kalshi fornecem mercados, preços e livros de ofertas por APIs REST oficiais sem chave. Para enviar ordens são necessários uma chave e um pedido assinado, e na Kalshi também para abrir uma conexão WebSocket.
- O preço de um contrato é uma fração de dólar: 0,42 significa 42¢ e, na visão do mercado, uma probabilidade de cerca de 42%. Só o livro de ofertas mostra quanto custará um volume específico.
- A arbitragem entre plataformas exige parear eventos, conferir regras e datas de resolução, percorrer os livros de ofertas e descontar as taxas. O endpoint
/predictions/arbitrageda Genesis API retorna pacotes com tudo isso já calculado; as operações você faz por conta própria.
A API da Polymarket e a API da Kalshi são as interfaces de programação oficiais de duas plataformas de mercados de previsão: por elas um programa lê mercados, preços dos contratos YES e NO e livros de ofertas e, com uma chave e um pedido assinado, envia ordens. Os dados de mercado das duas plataformas podem ser lidos sem chave. Para a arbitragem entre as duas, os preços não bastam: é preciso parear os eventos e calcular o lucro percorrendo os livros de ofertas com as taxas. Os pacotes prontos vêm do endpoint /predictions/arbitrage da Genesis API.
Como os dados dos mercados de previsão são estruturados
Um mercado de previsão negocia contratos sobre o resultado de um evento. Cada mercado é uma pergunta de sim ou não: um contrato YES paga US$ 1 se o evento acontece, e um contrato NO paga US$ 1 se não acontece. Como as plataformas resolvem os mercados e por que seus preços se afastam é explicado no artigo Mercados de previsão: como funcionam a Polymarket e a Kalshi e na lição O que são mercados de previsão. Aqui está como esses mesmos objetos aparecem nas APIs.
| Polymarket | Kalshi | |
|---|---|---|
| Grupo de mercados | Evento com um ou mais mercados | Série que contém eventos |
| Mercado | Condição binária com resultados Yes e No | Mercado binário com um ticker |
| Resultado na API | Yes e No têm cada um um token ID | Lados YES e NO de um mesmo mercado |
| Preço | De US$ 0,00 a US$ 1,00 | String em dólares, p. ex. "0.4200" |
| Livro de ofertas | Bids e asks de cada resultado | Só bids de YES e de NO |
O preço é uma fração de dólar: 0,42 são 42¢ por um contrato que paga US$ 1 se o seu resultado acontece. Por isso o preço se lê como a estimativa de probabilidade do mercado, aqui cerca de 42%. O site da Polymarket mostra o ponto médio entre o melhor bid e o melhor ask, ou o preço da última negociação quando o spread é maior que US$ 0,10 (documentação da Polymarket). Para precificar uma operação, usa-se o livro de ofertas.
Livro de ofertas: bids, asks e preços espelhados
Um livro de ofertas é a lista de ordens de compra (bids) e de venda (asks) com seus preços e tamanhos. Na Polymarket cada resultado tem seu próprio livro, consultado por token_id. A Kalshi retorna apenas bids dos dois lados: um bid de YES ao preço X equivale a um ask de NO a US$ 1,00 − X (documentação da Kalshi).
Um exemplo ilustrativo: o melhor bid de NO na Kalshi é 0,58. Então YES é oferecido a 1 − 0,58 = 0,42, ou seja, 42¢.
APIs oficiais da Polymarket e da Kalshi
Polymarket
Os dados da Polymarket vêm de três APIs REST e de fluxos WebSocket (visão geral da API). Os dados de mercado, incluindo preços e livros de ofertas do CLOB, não exigem chave.
| API | O que fornece |
|---|---|
| Gamma API | Eventos e mercados: metadados, datas, IDs dos resultados |
| CLOB API | Preços e livros de ofertas; com chaves, ordens |
| Data API | Posições e atividade de carteiras, histórico de preços |
| WebSocket | Canal de mercado para livros e preços; canal de usuário para ordens e negociações da conta |
As ordens usam uma autenticação CLOB em duas etapas: uma assinatura da carteira (L1) emite credenciais CLOB (L2), que assinam os pedidos de trading. O ID do resultado para o livro vem da Gamma API: os mercados v1 o trazem na string JSON clobTokenIds, os mercados v2 em positionIds; o índice 0 é YES e o 1 é NO (campos do mercado). Em vez de pedidos brutos, dá para usar o SDK oficial de Python, o pacote polymarket-client.
Kalshi
Para mercados de previsão, a Kalshi oferece uma API REST (Trade API v2), WebSocket e FIX. O host REST recomendado é external-api.kalshi.com; o antigo api.elections.kalshi.com ainda funciona, e há um ambiente demo separado para testes (ambientes da API). Séries, eventos, mercados, livros de ofertas e negociações são públicos.
Um pedido de trading é assinado com uma chave privada (Ed25519 ou RSA): o ID da chave, o carimbo de tempo e a assinatura vão nos cabeçalhos KALSHI-ACCESS-KEY, KALSHI-ACCESS-TIMESTAMP e KALSHI-ACCESS-SIGNATURE (chaves de API da Kalshi). As condições do mercado, incluindo as regras de resolução, chegam como texto em rules_primary e rules_secondary; os melhores preços estão em yes_bid_dollars, yes_ask_dollars, no_bid_dollars e no_ask_dollars.
Quando é preciso uma chave
| O quê | Polymarket | Kalshi |
|---|---|---|
| Mercados, preços, livros (REST) | Sem chave | Sem chave |
| Fluxo de livros (WebSocket) | Canal de mercado, sem chave | Chave obrigatória, mesmo para canais públicos |
| Ordens | Assinatura da carteira e credenciais CLOB | Pedido assinado com uma chave privada |
Ler um livro de ofertas sem chave: curl e Python
# Polymarket: the book of one outcome by token_id
curl "https://clob.polymarket.com/book?token_id=$TOKEN_ID"
# Kalshi: the book of a market by ticker
K=https://external-api.kalshi.com/trade-api/v2
curl "$K/markets/$TICKER/orderbook"
A Polymarket retorna bids e asks, níveis com price e size como strings, além de tick_size e min_order_size. A Kalshi retorna um objeto orderbook_fp com os arrays yes_dollars e no_dollars, em que cada nível é um par de preço em dólares e quantidade de contratos.
O que um volume específico custa só aparece ao percorrer os níveis. Esta função percorre os asks da Polymarket a partir do melhor e retorna o melhor preço, o preço médio e o pior preço:
import requests
CLOB = "https://clob.polymarket.com"
def walk_asks(token_id: str, shares: float):
"""Best, average and worst price to buy `shares` shares.
The platform fee is not included here.
"""
r = requests.get(f"{CLOB}/book", params={"token_id": token_id},
timeout=10)
r.raise_for_status()
left, cost, prices = shares, 0.0, []
for level in reversed(r.json()["asks"]): # the best ask is last
price, size = float(level["price"]), float(level["size"])
take = min(left, size)
cost += take * price
prices.append(price)
left -= take
if left <= 1e-9:
return prices[0], round(cost / shares, 4), prices[-1]
return None # the book is too thin for the full size
print(walk_asks("TOKEN_ID_YES", 1000))
O preço médio aqui é o VWAP da ordem: quanto mais fundo uma compra entra no livro, mais ela se afasta do melhor preço. Essa diferença é o slippage, e o volume disponível perto do melhor preço é a profundidade de mercado.
Por que a arbitragem entre Polymarket e Kalshi é difícil
A arbitragem de previsão entre plataformas consiste em comprar YES em uma e NO na outra quando, juntos, custam menos de US$ 1: se as duas resolvem da mesma forma, uma das pernas paga US$ 1 aconteça o que acontecer. Comparar dois preços pelas APIs oficiais é fácil; o par só vira uma operação depois de cinco verificações.
| Verificação | Por que é difícil |
|---|---|
| Pareamento de eventos | As perguntas são redigidas de forma diferente, e os IDs e a estrutura variam: um evento com mercados na Polymarket, uma série com eventos na Kalshi |
| Regras de resolução | A fonte, a redação e os casos-limite podem diferir sob a mesma manchete |
| Datas de resolução | Os mercados encerram em dias diferentes; o dinheiro fica preso até a data mais tardia |
| Taxas | Fórmulas diferentes: na Polymarket só pagam os takers, na Kalshi o tipo de taxa é definido por série |
| Profundidade do livro | Só um número limitado de contratos é vendido ao melhor preço |
Na Polymarket só o taker paga taxa, e o valor depende do preço da cota e da categoria do mercado (taxas da Polymarket). Na Kalshi o tipo de taxa e o multiplicador ficam na série, nos campos fee_type e fee_multiplier (séries na API da Kalshi). É preciso ter fundos nas duas plataformas de antemão, e o acesso a cada uma depende do seu país e das regras da plataforma.
Exemplo resolvido: YES na Polymarket, NO na Kalshi
Um exemplo ilustrativo: um mercado «O evento X acontece até 31 de dezembro» está listado nas duas plataformas com regras idênticas e se resolve em 46 dias. Você quer 1.000 cotas de cada lado.
| Perna | Níveis do livro | Custo |
|---|---|---|
| YES na Polymarket | 500 a 0,40 e 500 a 0,41 | 200 + 205 = US$ 405 |
| NO na Kalshi | 600 a 0,55 e 400 a 0,56 | 330 + 224 = US$ 554 |
Os asks de NO na Kalshi vêm dos bids de YES: um bid de YES de 0,45 por 600 contratos é um ask de NO a 0,55, e um bid de 0,44 por 400 é um ask a 0,56.
Aos melhores preços, o par custa 0,40 + 0,55 = 0,95: uma vantagem de 5¢ por cota, ou 0,05 / 0,95 = 5,26% sobre o dinheiro aplicado. Os preços médios de execução pelos livros são 0,405 e 0,554, juntos 0,959, então a vantagem encolhe para 4,1¢. As taxas do exemplo são US$ 6 na Polymarket e US$ 17 na Kalshi, US$ 23 no total.
O lucro é o pagamento menos o custo das duas pernas e as taxas, e a taxa anual (APR) sai dos dias até a resolução:
No exemplo: 1.000 − 959 − 23 = US$ 18 de lucro, 18 / 982 × 100 = 1,83% sobre o dinheiro aplicado e 1,83 × 365 / 46 = 14,5% ao ano. Dos 5,26% aos melhores preços, cerca de um terço sobrevive aos livros e às taxas.
Se as duas plataformas resolvem da mesma forma, uma perna paga US$ 1.000 aconteça o que acontecer: entram US$ 982 e voltam US$ 18 a mais. Se as regras divergem e as duas pernas perdem, a perda é de US$ 982 inteiros.
Arbitragem de previsão na Genesis API
O endpoint /predictions/arbitrage retorna pacotes com esse trabalho já feito. Os mercados de Polymarket, Kalshi, Limitless, Predict.fun e Opinion são pareados, cada perna é percorrida pelo seu livro com taxas, e são calculados o lucro em $ e em %, o APR e os dias até a resolução. São os dados da página Arbitragem de previsões, em JSON.
mode | O que você recebe | Planos da API |
|---|---|---|
exact | Eventos pareados exatamente em duas plataformas, o padrão | Start, Pro, Max |
dutch | YES em todos os resultados de um evento em uma plataforma | Start, Pro, Max |
llm | Pares de eventos verificados por IA | Pro, Max |
sport | Surebets em 13 plataformas, somente pré-jogo | Pro, Max |
O pacote do exemplo acima ficaria assim em uma resposta, com os campos reduzidos:
{
"kind": "cross",
"match": "exact",
"title": "Will event X happen by December 31?",
"days_left": 46,
"shares": 1000,
"size_usd": 959,
"fees_usd": 23,
"profit_usd": 18,
"profit_pct": 1.83,
"apr_pct": 14.5,
"risks": [],
"legs": [
{
"platform": "polymarket",
"side": "yes",
"price_best": 0.4,
"price_avg": 0.405,
"price_worst": 0.41,
"cost_usd": 405,
"fee_usd": 6
},
{
"platform": "kalshi",
"side": "no",
"price_best": 0.55,
"price_avg": 0.554,
"price_worst": 0.56,
"cost_usd": 554,
"fee_usd": 17
}
]
}
Em uma perna, side diz o que comprar: yes, no ou bet, uma aposta em casa de apostas. price_best, price_avg e price_worst são o melhor preço, o preço médio e o pior preço ao percorrer o livro; cost_usd e fee_usd são o custo e a taxa da perna; url leva ao mercado. apr_pct é null quando a resolução está a menos de um dia.
Os códigos em risks sinalizam o que a matemática não consegue verificar: rules_differ indica que as regras de resolução das plataformas podem diferir, end_mismatch que as datas de resolução diferem. No modo sport, um pacote com uma perna em casa de apostas tem profit_usd = null, porque o limite da aposta é desconhecido. As surebets são tratadas no artigo sobre APIs de odds de casas de apostas.
Filtre os pacotes com min_profit_pct, min_profit_usd, min_apr, max_days, platform e category. Todos os filtros e campos estão no guia Mercados de previsão e surebets na Genesis API. Sem código, os mesmos pacotes estão na página do serviço; suas colunas e tags são explicadas no guia Arbitragem de previsões.
Status das plataformas, análise e negociações
| Endpoint | O que retorna | Planos da API |
|---|---|---|
/predictions/platforms | Modo do feed da plataforma (ws, rest, down), horário das últimas cotações e da varredura completa, número de mercados | Start, Pro, Max |
/predictions/analytics | Open interest e volume, variações de preço em 1 h e 24 h, fluxos de dinheiro | Pro, Max |
/predictions/smart-money | Grandes negociações e baleias em 24 h, padrões de insiders, concentração de posições | Pro, Max |
/predictions/trades | Fita de negociações da Polymarket: live a partir de US$ 1.000 e negociações de carteiras smart a partir de US$ 100, today e 7d takers a partir de US$ 5.000 | Pro, Max |
/predictions/traders | Top 300 traders da Polymarket por PnL em 30 dias, 7 dias ou todo o período | Pro, Max |
Peça /predictions/platforms junto com os pacotes: se o feed de uma plataforma está em down, seus preços nos pacotes podem estar desatualizados. Cada negociação da fita traz rótulos da carteira (tags), a marca insider, o papel taker ou maker e os valores atuais bid_now e ask_now do resultado. O rótulo insider descreve como uma carteira se comporta e não prova nada.
No Trial, esses endpoints retornam 403 plan_restricted. O Start custa US$ 50 por mês e atualiza os dados a cada 30 s, o Pro US$ 100 e 10 s, o Max US$ 200 e 5 s. Compare os planos nos preços da Genesis API; as mesmas telas no site são Análise e Smart Money.
Python: pacotes exact com min_profit_pct e max_days
A cada meta.freshness_sec segundos, o script busca pacotes exact com pelo menos 1% de lucro que se resolvem em até 60 dias. Ele ignora pacotes com alguma plataforma em down e imprime os demais com os preços do percurso no livro. A chave vem da variável de ambiente GENESIS_API_KEY; como obtê-la está no início rápido.
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
PARAMS = {"mode": "exact", "min_profit_pct": 1, "max_days": 60}
def get(path, params=None):
while True:
r = requests.get(f"{API}{path}", headers=HEADERS,
params=params, timeout=10)
if r.status_code in (429, 503):
wait = int(r.headers.get("Retry-After", "5"))
if wait > 60: # the period quota is used up
raise SystemExit(f"Wait {wait} s: quota exhausted")
time.sleep(wait)
continue
r.raise_for_status() # 403: endpoint or mode not in your plan
return r.json()
while True:
feeds = get("/predictions/platforms")["data"]["platforms"]
down = {p["platform"] for p in feeds if p["mode"] == "down"}
body = get("/predictions/arbitrage", PARAMS)
for b in body["data"]:
if any(leg["platform"] in down for leg in b["legs"]):
continue # this platform's prices may be stale
print(f"{b['profit_pct']}% · ${b['profit_usd']} · "
f"APR {b['apr_pct']} · {b['days_left']} d · "
f"{b['title'][:40]}")
for leg in b["legs"]:
print(f" {leg['platform']} {leg['side']}: "
f"{leg['price_best']} / {leg['price_avg']} / "
f"{leg['price_worst']}, fee ${leg['fee_usd']}")
if b["risks"]:
print(" risks:", ", ".join(b["risks"]))
time.sleep(body["meta"]["freshness_sec"])
Cada ciclo faz duas chamadas. No Start são 2 × 86.400 / 30 = 5.760 chamadas por dia e 5.760 × 30 = 172.800 em 30 dias, contra uma cota de 2 M. Uma resposta filtrada vem sem ETag, então a economia está no intervalo de polling: consultar mais rápido que meta.freshness_sec não traz dados novos. Mais nos guias Limites da Genesis API e respostas e erros.
Perguntas e respostas
A Polymarket tem uma API oficial?
Sim. A Gamma API fornece eventos e mercados, a CLOB API preços, livros de ofertas e ordens, a Data API posições, atividade e histórico de preços, e as atualizações dos livros chegam por WebSocket. Os dados de mercado não exigem chave; as ordens exigem uma assinatura da carteira e credenciais CLOB. Veja a documentação da Polymarket.
Preciso de uma chave para ler os mercados da Kalshi?
Não para REST: séries, eventos, mercados, livros de ofertas e negociações são públicos (início rápido da Kalshi). Uma chave é exigida para ordens e para conectar ao WebSocket, mesmo que você queira só canais públicos.
Posso operar pela Genesis API?
Não. A Genesis API apenas lê dados e não envia ordens. Você abre um pacote por conta própria nas plataformas pelos links legs[].url. O trading automatizado pelas APIs oficiais da Polymarket e da Kalshi fica fora da Genesis API e é por sua conta e risco.
Com que frequência os dados são atualizados?
A Genesis API serve um novo snapshot a cada meta.freshness_sec: 30 s no Start, 10 s no Pro e 5 s no Max. A atualidade das cotações das próprias plataformas aparece em quotes_at e full_scan_at em /predictions/platforms.
Qual plano da Genesis API preciso para a arbitragem entre Polymarket e Kalshi?
Start: inclui os modos exact e dutch e o status das plataformas. Os modos llm e sport, a análise, o smart money, as negociações e o ranking de traders estão no Pro e no Max.