Como Usar a API da Kalshi: Guia de Mercados de Previsão

E se você pudesse usar APIs de nível institucional em uma bolsa regulada pela CFTC para negociar mercados de previsão programaticamente? Oferecendo interfaces REST, WebSocket e FIX 4.4 para o primeiro mercado de previsão autorizado federalmente nos EUA, a Kalshi faz exatamente isso. Somente no primeiro semestre de 2025, a empresa gerou mais de US$ 200 milhões em receita.

Os mercados de previsão explodiram em popularidade, mas os desenvolvedores enfrentam uma escolha entre infraestrutura regulada e flexibilidade cripto-nativa. Plataformas não reguladas operam em zonas cinzentas legais, exigem carteiras de blockchain e expõem os usuários a riscos de contratos inteligentes. A Kalshi elimina esses pontos de atrito operando como um Mercado Contratual Designado sob a supervisão da CFTC, oferecendo liquidação baseada em moeda fiduciária, padrões de API tradicionais e conformidade com as regulamentações financeiras dos EUA. Você cria aplicativos de negociação que as instituições podem realmente usar.

Sumário:

• Entendendo a Arquitetura da Kalshi
• Autenticação e Configuração
• Endpoints Principais da API
• Dados em Tempo Real com WebSocket
• Kalshi vs Polymarket para Desenvolvedores
• Conclusão

botão

Entendendo a Arquitetura da Kalshi

A Kalshi opera como uma bolsa centralizada com contratos de eventos auto-certificados. Compreender essa arquitetura ajuda você a projetar integrações robustas.

Status de Mercado Contratual Designado

A Kalshi possui uma licença da CFTC que lhe permite oferecer contratos de eventos legalmente em todos os 50 estados dos EUA. Ao contrário das apostas esportivas reguladas pelo estado, a Kalshi opera sob jurisdição federal, contornando a fragmentada colcha de retalhos das leis estaduais de jogos de azar. Este status exige conformidade rigorosa: cada mercado passa por revisão da CFTC, a liquidação segue manuais publicados e a bolsa mantém sistemas de vigilância para detectar manipulações.

Livro de Ordens de Limite Centralizado (CLOB)

A Kalshi combina ordens através de um CLOB tradicional — lances e ofertas se encontram a preços especificados com profundidade visível. Isso difere dos criadores de mercado automatizados (AMMs) usados por bolsas descentralizadas. O CLOB oferece transparência de preços, permite ordens de limite e possibilita estratégias de criação de mercado. Os criadores de mercado recebem aproximadamente US$ 35.000 diariamente em incentivos de liquidez (anualizado em cerca de US$ 12,7 milhões), garantindo spreads apertados mesmo em mercados menos ativos.

Estrutura dos Contratos de Eventos

Cada contrato representa um resultado binário: Sim paga US$ 1,00, Não paga US$ 0,00. Os preços flutuam entre US$ 0,01 e US$ 0,99, refletindo as probabilidades implícitas do mercado. Um contrato negociado a US$ 0,63 implica uma chance de 63% de o evento ocorrer. A liquidação ocorre a US$ 1,00 ou US$ 0,00 após a verificação do resultado.

Os contratos especificam condições de liquidação exatas: a definição do evento, a fonte de dados autorizada e a metodologia de resolução. Por exemplo, um contrato "O IPC excederá 3,5% em janeiro?" especifica o comunicado exato do Bureau of Labor Statistics e como interpretar os ajustes sazonais.

Oráculo e Liquidação

A Kalshi usa um oráculo centralizado operado pela equipe da bolsa. Os resultados são resolvidos com base em fontes oficiais — relatórios governamentais, provedores de dados respeitáveis ou organizações de notícias estabelecidas. A resolução geralmente é concluída em horas após a conclusão do evento. Este modelo centralizado prioriza a velocidade e a clareza em detrimento da descentralização, com a supervisão da CFTC fornecendo responsabilidade.

Autenticação e Configuração

A autenticação da Kalshi requer solicitações assinadas com RSA usando chaves privadas geradas no seu painel de controle da conta. Isso fornece verificação criptográfica das chamadas de API.

Configuração do Ambiente

A Kalshi oferece dois ambientes:

• Demo: https://demo-api.kalshi.co/v1 — Teste com dinheiro fictício
• Produção: https://api.kalshi.com/v1 — Negociação real com USD

Sempre desenvolva primeiro usando o ambiente de demonstração. Os ambientes são funcionalmente idênticos, mas os mercados de demonstração podem ter liquidez simulada.

Gerando Chaves de API

Navegue até Configurações → API no seu painel da Kalshi. Crie um novo par de chaves:

1. Clique em "Gerar Chave de API"
2. Armazene o ID da Chave de API (começa com kalshi_prod_ ou kalshi_demo_)
3. Baixe a chave privada imediatamente — a Kalshi nunca a exibirá novamente
4. Proteja a chave privada com permissões de arquivo (chmod 600)

A chave privada usa a assinatura RSA-PSS. A Kalshi oferece SDKs oficiais que lidam com a assinatura automaticamente, ou você pode implementá-la manualmente usando bibliotecas criptográficas padrão.

Instalação do SDK

A Kalshi oferece SDKs oficiais para Python (síncrono e assíncrono) e TypeScript:

# Python synchronous
pip install kalshi-python-sync

# Python asynchronous
pip install kalshi-python-async

# TypeScript/Node.js
npm install @kalshi/sdk

Existem SDKs da comunidade para Go e outras linguagens, mas os SDKs oficiais oferecem as implementações de assinatura mais confiáveis e segurança de tipo.

Autenticação Manual (Sem SDK)

Se for implementar a assinatura personalizada, siga este fluxo:

import requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
import base64
import json
from datetime import datetime, timezone

class KalshiAuth:
    def __init__(self, api_key_id, private_key_path):
        self.api_key_id = api_key_id
        with open(private_key_path, "rb") as key_file:
            self.private_key = serialization.load_pem_private_key(
                key_file.read(),
                password=None
            )
        self.base_url = "https://api.kalshi.com/v1"

    def sign_request(self, method, path, body=None):
        # Create timestamp
        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")[:-3] + "Z"

        # Build string to sign
        string_to_sign = f"{timestamp}{method}{path}"
        if body:
            string_to_sign += json.dumps(body, separators=(',', ':'))

        # Sign with RSA-PSS
        signature = self.private_key.sign(
            string_to_sign.encode('utf-8'),
            padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=32),
            hashes.SHA256()
        )

        return {
            "KALSHI-ACCESS-KEY": self.api_key_id,
            "KALSHI-ACCESS-TIMESTAMP": timestamp,
            "KALSHI-ACCESS-SIGNATURE": base64.b64encode(signature).decode('utf-8'),
            "Content-Type": "application/json"
        }

    def request(self, method, path, body=None):
        url = f"{self.base_url}{path}"
        headers = self.sign_request(method, path, body)

        if method == "GET":
            response = requests.get(url, headers=headers)
        elif method == "POST":
            response = requests.post(url, headers=headers, json=body)
        elif method == "DELETE":
            response = requests.delete(url, headers=headers)

        return response.json()

# Usage
kalshi = KalshiAuth(
    api_key_id="kalshi_prod_abc123",
    private_key_path="~/.kalshi/private_key.pem"
)

# Get markets
markets = kalshi.request("GET", "/markets")
print(markets)

A string de assinatura combina o carimbo de data/hora, o método HTTP, o caminho e o corpo JSON (se presente). RSA-PSS com SHA-256 fornece verificação criptográfica de que as solicitações se originam da sua conta.

Sessões Baseadas em Token

Após a autenticação inicial, obtenha um token de sessão para solicitações subsequentes:

# Login to get session token
login_response = kalshi.request("POST", "/log_in")
session_token = login_response["token"]

# Use token for subsequent requests (valid for 30 minutes)
headers = {
    "Authorization": f"Bearer {session_token}",
    "Content-Type": "application/json"
}

Os tokens expiram a cada 30 minutos. Implemente uma lógica de atualização automática antes da expiração para manter sessões contínuas.

Dica ProfissionalApidog

Endpoints Principais da API

A API REST da Kalshi segue as convenções padrão com uma estrutura de endpoint lógica por tipo de recurso.

Dados de Mercado (Públicos)

Recupere os mercados disponíveis:

curl "https://api.kalshi.com/v1/markets" \
  -H "Content-Type: application/json"

Obtenha detalhes específicos do mercado:

curl "https://api.kalshi.com/v1/markets/INXCHI-25JAN31-T69.5" \
  -H "Content-Type: application/json"

O formato do ticker codifica os detalhes do contrato: INXCHI-25JAN31-T69.5 representa um mercado de Inflação/Índice de Atividade Nacional do Fed de Chicago que expira em 31 de janeiro de 2025, com um limite de 69,5.

Consulte a profundidade do livro de ordens:

curl "https://api.kalshi.com/v1/markets/INXCHI-25JAN31-T69.5/orderbook" \
  -H "Content-Type: application/json"

A resposta retorna os níveis de compra e venda com as quantidades, permitindo que você avalie a liquidez antes de colocar ordens.

DicaApidog

Operações de Negociação (Autenticadas)

Faça uma ordem de compra:

order = kalshi.request("POST", "/orders", {
    "market_id": "INXCHI-25JAN31-T69.5",
    "side": "yes",
    "order_type": "limit",
    "price": 6500,  # $0.65 in cents
    "quantity": 100,  # Number of contracts
    "client_order_id": "my-strategy-001"  # Optional tracking ID
})

Os preços da Kalshi são em centavos (1 = US$ 0,01). Uma ordem de limite a 6500 é executada a US$ 0,65 ou melhor.

Cancele uma ordem aberta:

kalshi.request("DELETE", f"/orders/{order['id']}")

Liste suas ordens abertas:

curl "https://api.kalshi.com/v1/orders" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Portfólio e Conta

Verifique o saldo da conta:

curl "https://api.kalshi.com/v1/portfolio/balance" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Recupere posições:

curl "https://api.kalshi.com/v1/portfolio/positions" \
  -H "Authorization: Bearer $SESSION_TOKEN"

O endpoint de posições retorna suas participações atuais em todos os mercados, incluindo P&L não realizado com base nos últimos preços negociados.

Obtenha o histórico de negociações:

curl "https://api.kalshi.com/v1/portfolio/fills" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Os "fills" (execuções) incluem ordens executadas com carimbos de data/hora, preços e taxas pagas.

Liquidação e Resolução

Consulte o status de liquidação para mercados expirados:

curl "https://api.kalshi.com/v1/markets/INXCHI-25JAN31-T69.5/settlement" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Após a resolução, contratos vencedores creditam US$ 1,00 por ação à sua conta; posições perdedoras liquidam a US$ 0,00.

Dados em Tempo Real com WebSocket

O polling REST introduz latência. A API WebSocket da Kalshi transmite atualizações do livro de ordens em tempo real, execuções de negociações e mudanças no status do mercado.

Conectando ao WebSocket

const WebSocket = require('ws');

const ws = new WebSocket('wss://api.kalshi.com/v1/ws', {
  headers: {
    'Authorization': `Bearer ${sessionToken}`
  }
});

ws.on('open', () => {
  console.log('Connected to Kalshi WebSocket');

  // Subscribe to order book updates for specific market
  ws.send(JSON.stringify({
    type: 'subscribe',
    channels: ['orderbook:INXCHI-25JAN31-T69.5']
  }));
});

ws.on('message', (data) => {
  const message = JSON.parse(data);

  switch(message.type) {
    case 'orderbook_update':
      console.log('Order book changed:', message.data);
      break;
    case 'trade':
      console.log('Trade executed:', message.data);
      break;
    case 'market_status':
      console.log('Market status:', message.data);
      break;
  }
});

// Heartbeat to maintain connection
setInterval(() => {
  ws.send(JSON.stringify({ type: 'ping' }));
}, 30000);

As conexões WebSocket exigem "heartbeats" periódicos (a cada 30 segundos) para evitar o timeout. Implemente uma lógica de reconexão automática para aplicações de produção.

Canais de Assinatura

Canais disponíveis incluem:

• orderbook:{market_id} — Atualizações de lances/ofertas
• trades:{market_id} — Execuções recentes
• market_status:{market_id} — Paradas de negociação, liquidações
• user_orders — Mudanças no status da sua ordem
• user_fills — Suas execuções de negociação

Assine vários canais em uma única mensagem para um streaming de dados eficiente.

Apidog

botão

Kalshi vs Polymarket para Desenvolvedores

Ambas as plataformas oferecem APIs para mercados de previsão, mas suas arquiteturas atendem a diferentes casos de uso.

Status Regulatório

A Kalshi opera como um Mercado Contratual Designado regulado pela CFTC. Isso proporciona clareza legal para usuários dos EUA, mas exige conformidade com KYC/AML e restringe o acesso a 42 estados (excluindo Arizona, Illinois, Massachusetts, Maryland, Michigan, Montana, Nova Jersey, Ohio).

A Polymarket obteve recentemente aprovação da CFTC através da aquisição da QCX LLC e possui uma licença DCM com uma No-Action Letter. Atualmente, opera internacionalmente com disponibilidade limitada nos EUA, aguardando o lançamento completo. Anteriormente, foi multada em US$ 1,4 milhão por operar sem registro (janeiro de 2022).

Arquitetura Técnica

A Kalshi utiliza infraestrutura centralizada com correspondência de ordens off-chain e liquidação em USD fiduciário. O acesso à API segue padrões tradicionais: REST sobre HTTPS, WebSocket para streaming, FIX 4.4 para negociação institucional. Os tempos de resposta são medidos em milissegundos.

A Polymarket opera na blockchain Polygon com arquitetura CLOB híbrida — correspondência de ordens off-chain, liquidação on-chain via Conditional Tokens Framework. A integração requer interação com blockchain: ordens assinadas EIP-712, chamadas de contrato inteligente, transações USDC. A finalidade da liquidação requer confirmação da blockchain (segundos a minutos).

Modelos de Autenticação

A Kalshi usa solicitações assinadas com RSA-PSS com chaves de API, sessões baseadas em token que expiram a cada 30 minutos. Requer armazenamento seguro de chave privada e assinatura criptográfica.

A Polymarket usa assinaturas de carteira blockchain (MetaMask, WalletConnect). Os usuários assinam ordens com chaves privadas que controlam seus endereços Polygon. Não há tokens de sessão — cada transação requer uma nova assinatura.

Moeda de Liquidação

A Kalshi liquida em USD via transferência bancária, ACH, cartão de débito, PayPal, Apple Pay, Google Pay. O saque mínimo é geralmente de US$ 10. O tempo de processamento é de 1 a 3 dias úteis para ACH, mais rápido para transferências eletrônicas.

A Polymarket liquida em USDC na blockchain Polygon. Liquidação instantânea após a resolução, mas requer carteira de criptomoedas e infraestrutura de on-ramp/off-ramp. Taxas de gás se aplicam para saques.

Protocolos de API

A Kalshi oferece três protocolos:

• REST: HTTP padrão para todas as operações
• WebSocket: Streaming em tempo real para dados de mercado e atualizações de ordens
• FIX 4.4: Protocolo padrão da indústria para negociação institucional de alta frequência

A Polymarket requer:

• GraphQL: Consultas flexíveis para dados de blockchain
• EIP-712: Assinatura de dados tipados para ordens
• Chamadas de Contrato Inteligente: Interação direta com blockchain para liquidação

Recomendações de Caso de Uso

Escolha a Kalshi para:

• Mesas de negociação institucionais que exigem conformidade regulatória
• Aplicações que atendem a usuários de varejo dos EUA
• Entradas/saídas de moeda fiduciária sem a complexidade das criptomoedas
• Negociação algorítmica de baixa latência
• Integrações financeiras tradicionais

Escolha a Polymarket para:

• Protocolos DeFi que exigem composabilidade de contratos inteligentes
• Usuários globais fora das jurisdições dos EUA
• Aplicações cripto-nativas com infraestrutura de carteira existente
• Criação rápida de mercado (horas vs. dias para aprovação)
• Verificação e transparência on-chain

Complexidade da Integração

A integração da Kalshi requer de 2 a 4 semanas para funcionalidades básicas de dados de mercado e negociação, assumindo experiência com API REST. Os padrões HTTP familiares reduzem a curva de aprendizado.

A integração da Polymarket requer de 3 a 6 meses para mercados de contratos inteligentes prontos para produção, incluindo auditoria de segurança (orçamento de US$ 50K-US$ 200K), integração de oráculo e bootstrapping de liquidez. Experiência em blockchain é obrigatória.

Estrutura de Custos

A Kalshi cobra taxas de negociação com base nos ganhos esperados (0,7-3,5%, média de 0,8%). O acesso à API é gratuito — você paga apenas as taxas de negociação. Não há taxas de saque para ACH.

A Polymarket cobra uma taxa de 0,01% para "takers" em mercados principais, com taxas de gás para transações de blockchain. Não há taxas em alguns mercados, mas os custos de rede se aplicam.

Conclusão

A API da Kalshi oferece acesso regulado a mercados de previsão através de protocolos REST e WebSocket familiares. Você autentica com solicitações assinadas com RSA, negocia contratos de eventos via livro de ordens de limite centralizado e liquida em USD por meio de bancos tradicionais. A supervisão da CFTC garante conformidade legal para aplicações nos EUA, enquanto a taxa de receita anual de US$ 200 milhões demonstra viabilidade institucional.

Comece com o ambiente de demonstração para testar padrões de integração. Implemente o gerenciamento adequado de chaves e a assinatura de solicitações antes de passar para a produção. Use o streaming WebSocket para aplicações em tempo real que exigem baixa latência. Monitore a expiração do token de 30 minutos e implemente a lógica de atualização para operação contínua.

Comece a usar o Apidog hoje — importe seus endpoints da API Kalshi em segundos e comece a testar suas estratégias de mercado de previsão com zero configuração.

botão