API Kalshi
Negocie e consulte a primeira bolsa de mercados de previsão regulamentada pela CFTC. Contratos binários sim/não sobre eventos do mundo real, precificados de 1 a 99 centavos.
URL Base: https://external-api.kalshi.com/trade-api/v2
URL de Demonstração: https://external-api.demo.kalshi.co/trade-api/v2
Obtenha sua chave de API em https://kalshi.com/account/api-keys (requer plano Premier ou Market Maker)
Conceitos Chave
Hierarquia: Séries > Eventos > Mercados
- Séries — modelos de eventos recorrentes (ex.: "Relatório Mensal de Empregos", "Pedidos Semanais de Seguro-Desemprego")
- Eventos — instâncias específicas dentro de uma série (ex.: "Relatório de Empregos de Maio de 2026")
- Mercados — resultados binários individuais dentro de um evento (ex.: "Os empregos adicionados serão acima de 200k?")
Precificação de Contratos Binários
- Os preços estão em centavos (1-99), representando probabilidade implícita
- Um contrato Sim a 65c = mercado implica 65% de probabilidade
- A oferta de compra do Sim no preço X é equivalente à oferta de venda do Não em (100 - X) — os livros de ofertas mostram apenas ofertas de compra do Sim e do Não
- Liquidação: paga $1,00 (100 centavos) se Sim, $0 se Não
- Todos os valores monetários (saldo, preços, liquidações) estão em centavos
Formato do Ticker
- Série:
KXBTC,KXJOBLESS,KXINX - Evento:
KXBTC-25MAY30(série + data) - Mercado:
KXBTC-25MAY30-T100000(evento + limite/resultado)
Tickers de jogos esportivos seguem um padrão diferente: {SERIES}-{YYMONDD}{TIME1}{TIME2}-{TIME}
- Exemplo:
KXNHLGAME-25MAY12EDMORL-EDM(NHL, 12 de Maio de 2025, Edmonton vs Orlando, Edmonton vence) - Cada evento de jogo tem dois mercados SIM mutuamente exclusivos — um por time
CRÍTICO: Navegação em Mercados Baseada em Séries
NÃO use /markets?keyword= para esportes, eleições ou qualquer categoria baseada em séries. Isso retorna apenas pacotes de apostas combinadas multi-jogo, não os mercados reais de jogos. Pesquisar "NHL", "Fulham", "Premier League" etc. retorna zero resultados ou resultados irrelevantes.
Sempre navegue: Séries → Eventos → Mercados. Os mercados de jogos estão sob a hierarquia de séries/eventos e devem ser acessados via /events?series_ticker=KXXX. Além disso, /markets/{ticker} pode retornar 404 para mercados de jogos — os preços de compra e venda aparecem apenas na resposta do endpoint de eventos (/events/{event_ticker} com with_nested_markets=true).
Este padrão se aplica a todas as categorias baseadas em séries, não apenas esportes:
- Jogos esportivos — NHL, NBA, NFL, MLB, EPL, etc.
- Disputas políticas — mercados de candidatos individuais dentro de eventos com múltiplos candidatos
- Mercados específicos de empresas — lucros, mudanças de CEO dentro de uma série
- Dados econômicos recorrentes — relatórios de empregos, pedidos de seguro-desemprego, IPC, etc.
Tickers de Séries Esportivas Conhecidos:
| Esporte | Ticker da Série | Exemplo |
|---|---|---|
| NHL | KXNHLGAME | KXNHLGAME-25MAY12EDMORL |
| NBA | KXNBAGAME | KXNBAGAME-25MAY12BOSLAL |
| NFL | KXNFLGAME | KXNFLGAME-25SEP07KCDET |
| MLB | KXMLBGAME | KXMLBGAME-25MAY12NYYLAD |
| EPL (Premier League) | KXEPLGAME | KXEPLGAME-25MAY12FULARS |
Fluxo de trabalho correto para esportes:
# 1. Liste jogos abertos para um esporte
curl -s "https://external-api.kalshi.com/trade-api/v2/events?series_ticker=KXNHLGAME&status=open&with_nested_markets=true"
# 2. Obtenha um jogo específico com compra/venda ao vivo
curl -s "https://external-api.kalshi.com/trade-api/v2/events/KXNHLGAME-25MAY12EDMORL?with_nested_markets=true"
# ERRADO — não faça isso:
# curl -s "https://external-api.kalshi.com/trade-api/v2/markets?keyword=NHL" ← retorna apostas combinadas, não jogos
Como Chamar
A Kalshi usa autenticação por assinatura RSA com par de chaves. Três cabeçalhos são necessários em requisições autenticadas:
| Cabeçalho | Valor |
|---|---|
KALSHI-ACCESS-KEY | ID da chave de API ($KALSHI_ACCESS_KEY) |
KALSHI-ACCESS-SIGNATURE | Assinatura RSA-PSS de timestamp + method + path |
KALSHI-ACCESS-TIMESTAMP | Timestamp Unix (ms) |
Endpoints GET públicos (mercados, eventos, livros de ofertas) podem ser chamados sem cabeçalhos de autenticação.
# Endpoint público — sem autenticação necessária
curl -s "https://external-api.kalshi.com/trade-api/v2/markets?limit=10&status=open"
Para endpoints autenticados, use assinatura RSA-PSS diretamente (não o SDK kalshi_python — ele não funciona):
import os, time, base64, requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.backends import default_backend
from dotenv import load_dotenv
load_dotenv('/data/workspace/.env')
BASE_URL = "https://api.elections.kalshi.com"
def kalshi_headers(method: str, path: str) -> dict:
import re
raw = os.environ["KALSHI_PRIVATE_KEY"]
# Decodifique sequências de escape literais primeiro (alguns canais de entrada salvam '\n' como
# dois caracteres barra invertida+n em vez de uma nova linha real).
raw = (raw.replace('\\r\\n', '\n').replace('\\n', '\n')
.replace('\\r', '\n').replace('\\t', ' '))
# Remova marcadores PEM se presentes, então remova TODO o espaço em branco e reencapsule.
body = re.sub(r'-----BEGIN[^-]+-----', '', raw)
body = re.sub(r'-----END[^-]+-----', '', body)
body = re.sub(r'\s+', '', body)
wrapped = '\n'.join(body[i:i+64] for i in range(0, len(body), 64))
pem = f"-----BEGIN RSA PRIVATE KEY-----\n{wrapped}\n-----END RSA PRIVATE KEY-----\n"
private_key = serialization.load_pem_private_key(pem.encode(), password=None, backend=default_backend())
ts = str(int(time.time() * 1000))
msg = (ts + method + path).encode() # path NÃO deve incluir query string
sig = private_key.sign(msg, padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.DIGEST_LENGTH), hashes.SHA256())
return {
"KALSHI-ACCESS-KEY": os.environ["KALSHI_ACCESS_KEY"].strip(),
"KALSHI-ACCESS-TIMESTAMP": ts,
"KALSHI-ACCESS-SIGNATURE": base64.b64encode(sig).decode(),
"Content-Type": "application/json"
}
path = "/trade-api/v2/portfolio/balance"
resp = requests.get(BASE_URL + path, headers=kalshi_headers("GET", path))
print(resp.json()) # {"balance": 5000, ...} — saldo em centavos
Armadilhas de assinatura:
- PSS, não PKCS1v15 — o preenchimento PKCS1v15 retorna 401. Deve usar PSS com SHA256.
- Remova query strings antes de assinar — a assinatura é calculada apenas no caminho limpo (ex.:
/trade-api/v2/portfolio/balance), não/trade-api/v2/portfolio/balance?param=value. Incluir query string resultará em 401. - Formato da variável de ambiente da chave —
KALSHI_PRIVATE_KEYaceita qualquer um dos: corpo base64 bruto, PEM completo com novas linhas reais, ou PEM completo com novas linhas colapsadas em espaço em branco (comum ao colar através de formulários web). O auxiliar normaliza todos os formatos automaticamente. Para o armazenamento mais robusto, salve como um PEM multilinha entre aspas duplas com escapes\nem.envpara que o python-dotenv o reidrate em uma string PEM real.
Especificação da API
Especificação OpenAPI completa: https://docs.kalshi.com/openapi.yaml
Roteamento de Intenções
Mapeie a intenção do usuário para o endpoint correto. Todos os caminhos são relativos à URL base.
Eventos
| Método | Endpoint | Parâmetros Principais | Descrição |
|---|---|---|---|
| GET | /events | limit (1-200), cursor, status, series_ticker, with_nested_markets | Listar eventos (exclui multivariados) |
| GET | /events/{event_ticker} | event_ticker, with_nested_markets | Obter evento específico |
| GET | /events/{event_ticker}/metadata | event_ticker | Apenas metadados do evento |
| GET | /events/multivariate | limit, cursor, series_ticker, collection_ticker, with_nested_markets | Listar eventos multivariados (combinação) |
Mercados
| Método | Endpoint | Parâmetros Principais | Descrição |
|---|---|---|---|
| GET | /markets | limit, cursor, status, ticker, event_ticker, series_ticker, min_close_ts, max_close_ts | Listar/filtrar mercados |
| GET | /markets/{ticker} | ticker | Obter detalhes específicos do mercado |
| GET | /markets/{ticker}/orderbook | ticker, depth | Livro de ofertas atual (ofertas de compra do Sim + do Não) |
| GET | /markets/orderbooks | tickers (array, max 100) | Livros de ofertas em lote |
| GET | /markets/trades | ticker, limit, cursor, min_ts, max_ts | Negociações em todos os mercados |
Velas (Candlesticks)
| Método | Endpoint | Parâmetros Principais | Descrição |
|---|---|---|---|
| GET | /series/{series_ticker}/markets/{ticker}/candlesticks | series_ticker, ticker, start_ts, end_ts, period_interval | Velas de nível de mercado |
| GET | /series/{series_ticker}/events/{ticker}/candlesticks | series_ticker, ticker, start_ts, end_ts, period_interval | Velas agregadas de nível de evento |
| GET | /markets/candlesticks | market_tickers, start_ts, end_ts, period_interval | Velas em lote |
period_interval valores: 1 (1 min), 60 (1 hora), 1440 (1 dia)
Previsão e Dados Ao Vivo
| Método | Endpoint | Parâmetros Principais | Descrição |
|---|---|---|---|
| GET | /series/{series_ticker}/events/{ticker}/forecast_percentile_history | percentiles (0-10000), start_ts, end_ts, period_interval | Histórico de percentis de previsão |
| GET | /live_data/milestone/{milestone_id} | milestone_id, include_player_stats | Dados de marco ao vivo |
| GET | /live_data/batch | milestone_ids (array, max 100), include_player_stats | Dados ao vivo em lote |
| GET | /live_data/game-stats/{milestone_id} | milestone_id | Estatísticas jogo a jogo (futebol americano, basquete, futebol, hóquei, beisebol) |
Séries
| Método | Endpoint | Parâmetros Principais | Descrição |
|---|---|---|---|
| GET | /series/{series_ticker} | series_ticker, include_volume | Obter modelo da série |
| GET | /series | category, tags, include_volume, min_updated_ts | Listar todas as séries |
Informações da Bolsa
| Método | Endpoint | Parâmetros Principais | Descrição |
|---|---|---|---|
| GET | /exchange/status | — | Status atual da bolsa |
| GET | /exchange/schedule | — | Horários de funcionamento |
| GET | /exchange/announcements | — | Anúncios da plataforma |
| GET | /exchange/user_data_timestamp | — | Timestamp de sincronização de dados |
| GET | /series/fee_changes | series_ticker, show_historical | Histórico de alterações de taxas |
Pesquisa e Descoberta
| Método | Endpoint | Parâmetros Principais | Descrição |
|---|---|---|---|
| GET | /search/tags_by_categories | — | Tags organizadas por categorias de séries |
| GET | /search/filters_by_sport | — | Filtros organizados por esporte |
Ordens (Autenticado)
| Método | Endpoint | Parâmetros Principais | Descrição |
|---|---|---|---|
| GET | /portfolio/orders | ticker, event_ticker, status, limit, cursor, subaccount | Listar ordens do usuário |
| GET | /portfolio/orders/{order_id} | order_id | Obter ordem específica |
| POST | /portfolio/orders | Corpo: ticker, action, side, type, count, yes_price/no_price | Criar ordem |
| DELETE | /portfolio/orders/{order_id} | order_id, subaccount | Cancelar ordem |
| POST | /portfolio/orders/{order_id}/amend | order_id, Corpo: novo count/price | Alterar ordem |
| POST | /portfolio/orders/{order_id}/decrease | order_id, Corpo: valor de redução | Diminuir quantidade da ordem |
| POST | /portfolio/orders/batched | Corpo: array de ordens | Criar em lote (tamanho máximo escala com nível) |
| DELETE | /portfolio/orders/batched | Corpo: array de IDs de ordens | Cancelar em lote |
| GET | /portfolio/orders/queue_positions | market_tickers, event_ticker, subaccount | Todas as posições de ordens pendentes |
| GET | /portfolio/orders/{order_id}/queue_position | order_id | Posição específica na fila da ordem |
Ordens V2 — Ordens de Evento-Mercado (Autenticado, Ponto Fixo)
| Método | Endpoint | Parâmetros Principais | Descrição |
|---|---|---|---|
| POST | /portfolio/events/orders | Corpo: ticker do evento, lado do mercado, preço (ponto fixo), quantidade | Criar ordem V2 |
| POST | /portfolio/events/orders/batched | Corpo: array de ordens V2 | Criar V2 em lote |
| DELETE | /portfolio/events/orders/{order_id} | order_id, subaccount | Cancelar ordem V2 |
| DELETE | /portfolio/events/orders/batched | Corpo: array de IDs de ordens | Cancelar V2 em lote |
| POST | /portfolio/events/orders/{order_id}/amend | order_id, Corpo: novo count/preço | Alterar ordem V2 |
| POST | /portfolio/events/orders/{order_id}/decrease | order_id, Corpo: nova quantidade restante | Diminuir ordem V2 |
Grupos de Ordens (Autenticado)
| Método | Endpoint | Parâmetros Principais | Descrição |
|---|---|---|---|
| GET | /portfolio/order_groups | subaccount | Listar todos os grupos de ordens |
| POST | /portfolio/order_groups/create | Corpo: limite de contratos | Criar grupo de ordens |
| GET | /portfolio/order_groups/{id} | id, subaccount | Obter grupo específico |
| DELETE | /portfolio/order_groups/{id} | id, subaccount | Excluir grupo e cancelar todas as ordens |
| PUT | /portfolio/order_groups/{id}/limit | id, Corpo: novo limite | Atualizar limite de contratos |
| PUT | /portfolio/order_groups/{id}/trigger | id, subaccount | Acionar grupo (cancelar todas as ordens) |
| PUT | /portfolio/order_groups/{id}/reset | id, subaccount | Redefinir contador de contratos correspondidos |
Portfólio (Autenticado)
| Método | Endpoint | Parâmetros Principais | Descrição |
|---|---|---|---|
| GET | /portfolio/balance | subaccount | Saldo e valor do portfólio (em centavos) |
| GET | /portfolio/positions | cursor, limit, count_filter, ticker, event_ticker, subaccount | Posições do usuário |
| GET | /portfolio/fills | ticker, order_id, min_ts, max_ts, limit, cursor, subaccount | Todas as execuções de negociação |
| GET | /portfolio/settlements | limit, cursor, ticker, event_ticker, min_ts, max_ts, subaccount | Histórico de liquidações |
| GET | /portfolio/deposits | limit, cursor | Histórico de depósitos |
| GET | /portfolio/withdrawals | limit, cursor | Histórico de saques |
| GET | /portfolio/summary/total_resting_order_value | — | Valor total de ordens pendentes (…) |
Pré-requisitos
- Conta Kalshi (nível Premier ou Market Maker)
- Chave de API gerada em https://kalshi.com/account/api-keys
- Par de chaves RSA para autenticação
Suporte
Entre em contato com o suporte da Kalshi para problemas relacionados à conta. Para problemas com esta skill, abra uma issue no repositório.
Licença
MIT