Genesis Arbitrage

Genesis Arbitrage · · 15 min de leitura

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/arbitrage da 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.

PolymarketKalshi
Grupo de mercadosEvento com um ou mais mercadosSérie que contém eventos
MercadoCondição binária com resultados Yes e NoMercado binário com um ticker
Resultado na APIYes e No têm cada um um token IDLados YES e NO de um mesmo mercado
PreçoDe US$ 0,00 a US$ 1,00String em dólares, p. ex. "0.4200"
Livro de ofertasBids e asks de cada resultadoSó 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.

APIO que fornece
Gamma APIEventos e mercados: metadados, datas, IDs dos resultados
CLOB APIPreços e livros de ofertas; com chaves, ordens
Data APIPosições e atividade de carteiras, histórico de preços
WebSocketCanal 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êPolymarketKalshi
Mercados, preços, livros (REST)Sem chaveSem chave
Fluxo de livros (WebSocket)Canal de mercado, sem chaveChave obrigatória, mesmo para canais públicos
OrdensAssinatura da carteira e credenciais CLOBPedido 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çãoPor que é difícil
Pareamento de eventosAs 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çãoA fonte, a redação e os casos-limite podem diferir sob a mesma manchete
Datas de resoluçãoOs mercados encerram em dias diferentes; o dinheiro fica preso até a data mais tardia
TaxasFórmulas diferentes: na Polymarket só pagam os takers, na Kalshi o tipo de taxa é definido por série
Profundidade do livroSó 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.

PernaNíveis do livroCusto
YES na Polymarket500 a 0,40 e 500 a 0,41200 + 205 = US$ 405
NO na Kalshi600 a 0,55 e 400 a 0,56330 + 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.

modeO que você recebePlanos da API
exactEventos pareados exatamente em duas plataformas, o padrãoStart, Pro, Max
dutchYES em todos os resultados de um evento em uma plataformaStart, Pro, Max
llmPares de eventos verificados por IAPro, Max
sportSurebets em 13 plataformas, somente pré-jogoPro, 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

EndpointO que retornaPlanos da API
/predictions/platformsModo do feed da plataforma (ws, rest, down), horário das últimas cotações e da varredura completa, número de mercadosStart, Pro, Max
/predictions/analyticsOpen interest e volume, variações de preço em 1 h e 24 h, fluxos de dinheiroPro, Max
/predictions/smart-moneyGrandes negociações e baleias em 24 h, padrões de insiders, concentração de posiçõesPro, Max
/predictions/tradesFita 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.000Pro, Max
/predictions/tradersTop 300 traders da Polymarket por PnL em 30 dias, 7 dias ou todo o períodoPro, 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.