Communitygithub.com

Starchild-ai-agent/official-skills

Mercados de previsão Kalshi: contratos binários de eventos sobre política, economia, esportes e clima.

O que é official-skills?

Esta skill integra o agente à Kalshi, a primeira bolsa de mercados de previsão regulamentada pela CFTC nos Estados Unidos. Ela permite que o agente negocie e consulte contratos binários sim/não sobre eventos do mundo real, como relatórios econômicos (IPC, folha de pagamento), resultados esportivos (NHL, NBA, NFL, EPL, etc.) e probabilidades eleitorais. A skill fornece uma hierarquia clara de navegação (Série > Evento > Mercado), instruções detalhadas de autenticação via RSA-PSS, e um roteamento de intenções completo para todos os endpoints da API. Suporta tanto consultas públicas (mercados, order books) quanto operações autenticadas (criação de ordens, gerenciamento de portfólio). A documentação enfatiza a navegação correta por séries para evitar resultados irrelevantes, especialmente em esportes e eleições, onde a busca por palavra-chave pode falhar.

Funciona com~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Starchild-ai-agent/official-skills/tree/HEAD/kalshi

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

EsporteTicker da SérieExemplo
NHLKXNHLGAMEKXNHLGAME-25MAY12EDMORL
NBAKXNBAGAMEKXNBAGAME-25MAY12BOSLAL
NFLKXNFLGAMEKXNFLGAME-25SEP07KCDET
MLBKXMLBGAMEKXMLBGAME-25MAY12NYYLAD
EPL (Premier League)KXEPLGAMEKXEPLGAME-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çalhoValor
KALSHI-ACCESS-KEYID da chave de API ($KALSHI_ACCESS_KEY)
KALSHI-ACCESS-SIGNATUREAssinatura RSA-PSS de timestamp + method + path
KALSHI-ACCESS-TIMESTAMPTimestamp 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_KEY aceita 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 \n em .env para 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étodoEndpointParâmetros PrincipaisDescrição
GET/eventslimit (1-200), cursor, status, series_ticker, with_nested_marketsListar eventos (exclui multivariados)
GET/events/{event_ticker}event_ticker, with_nested_marketsObter evento específico
GET/events/{event_ticker}/metadataevent_tickerApenas metadados do evento
GET/events/multivariatelimit, cursor, series_ticker, collection_ticker, with_nested_marketsListar eventos multivariados (combinação)

Mercados

MétodoEndpointParâmetros PrincipaisDescrição
GET/marketslimit, cursor, status, ticker, event_ticker, series_ticker, min_close_ts, max_close_tsListar/filtrar mercados
GET/markets/{ticker}tickerObter detalhes específicos do mercado
GET/markets/{ticker}/orderbookticker, depthLivro de ofertas atual (ofertas de compra do Sim + do Não)
GET/markets/orderbookstickers (array, max 100)Livros de ofertas em lote
GET/markets/tradesticker, limit, cursor, min_ts, max_tsNegociações em todos os mercados

Velas (Candlesticks)

MétodoEndpointParâmetros PrincipaisDescrição
GET/series/{series_ticker}/markets/{ticker}/candlesticksseries_ticker, ticker, start_ts, end_ts, period_intervalVelas de nível de mercado
GET/series/{series_ticker}/events/{ticker}/candlesticksseries_ticker, ticker, start_ts, end_ts, period_intervalVelas agregadas de nível de evento
GET/markets/candlesticksmarket_tickers, start_ts, end_ts, period_intervalVelas em lote

period_interval valores: 1 (1 min), 60 (1 hora), 1440 (1 dia)

Previsão e Dados Ao Vivo

MétodoEndpointParâmetros PrincipaisDescrição
GET/series/{series_ticker}/events/{ticker}/forecast_percentile_historypercentiles (0-10000), start_ts, end_ts, period_intervalHistórico de percentis de previsão
GET/live_data/milestone/{milestone_id}milestone_id, include_player_statsDados de marco ao vivo
GET/live_data/batchmilestone_ids (array, max 100), include_player_statsDados ao vivo em lote
GET/live_data/game-stats/{milestone_id}milestone_idEstatísticas jogo a jogo (futebol americano, basquete, futebol, hóquei, beisebol)

Séries

MétodoEndpointParâmetros PrincipaisDescrição
GET/series/{series_ticker}series_ticker, include_volumeObter modelo da série
GET/seriescategory, tags, include_volume, min_updated_tsListar todas as séries

Informações da Bolsa

MétodoEndpointParâmetros PrincipaisDescriçã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_changesseries_ticker, show_historicalHistórico de alterações de taxas

Pesquisa e Descoberta

MétodoEndpointParâmetros PrincipaisDescriçã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étodoEndpointParâmetros PrincipaisDescrição
GET/portfolio/ordersticker, event_ticker, status, limit, cursor, subaccountListar ordens do usuário
GET/portfolio/orders/{order_id}order_idObter ordem específica
POST/portfolio/ordersCorpo: ticker, action, side, type, count, yes_price/no_priceCriar ordem
DELETE/portfolio/orders/{order_id}order_id, subaccountCancelar ordem
POST/portfolio/orders/{order_id}/amendorder_id, Corpo: novo count/priceAlterar ordem
POST/portfolio/orders/{order_id}/decreaseorder_id, Corpo: valor de reduçãoDiminuir quantidade da ordem
POST/portfolio/orders/batchedCorpo: array de ordensCriar em lote (tamanho máximo escala com nível)
DELETE/portfolio/orders/batchedCorpo: array de IDs de ordensCancelar em lote
GET/portfolio/orders/queue_positionsmarket_tickers, event_ticker, subaccountTodas as posições de ordens pendentes
GET/portfolio/orders/{order_id}/queue_positionorder_idPosição específica na fila da ordem

Ordens V2 — Ordens de Evento-Mercado (Autenticado, Ponto Fixo)

MétodoEndpointParâmetros PrincipaisDescrição
POST/portfolio/events/ordersCorpo: ticker do evento, lado do mercado, preço (ponto fixo), quantidadeCriar ordem V2
POST/portfolio/events/orders/batchedCorpo: array de ordens V2Criar V2 em lote
DELETE/portfolio/events/orders/{order_id}order_id, subaccountCancelar ordem V2
DELETE/portfolio/events/orders/batchedCorpo: array de IDs de ordensCancelar V2 em lote
POST/portfolio/events/orders/{order_id}/amendorder_id, Corpo: novo count/preçoAlterar ordem V2
POST/portfolio/events/orders/{order_id}/decreaseorder_id, Corpo: nova quantidade restanteDiminuir ordem V2

Grupos de Ordens (Autenticado)

MétodoEndpointParâmetros PrincipaisDescrição
GET/portfolio/order_groupssubaccountListar todos os grupos de ordens
POST/portfolio/order_groups/createCorpo: limite de contratosCriar grupo de ordens
GET/portfolio/order_groups/{id}id, subaccountObter grupo específico
DELETE/portfolio/order_groups/{id}id, subaccountExcluir grupo e cancelar todas as ordens
PUT/portfolio/order_groups/{id}/limitid, Corpo: novo limiteAtualizar limite de contratos
PUT/portfolio/order_groups/{id}/triggerid, subaccountAcionar grupo (cancelar todas as ordens)
PUT/portfolio/order_groups/{id}/resetid, subaccountRedefinir contador de contratos correspondidos

Portfólio (Autenticado)

MétodoEndpointParâmetros PrincipaisDescrição
GET/portfolio/balancesubaccountSaldo e valor do portfólio (em centavos)
GET/portfolio/positionscursor, limit, count_filter, ticker, event_ticker, subaccountPosições do usuário
GET/portfolio/fillsticker, order_id, min_ts, max_ts, limit, cursor, subaccountTodas as execuções de negociação
GET/portfolio/settlementslimit, cursor, ticker, event_ticker, min_ts, max_ts, subaccountHistórico de liquidações
GET/portfolio/depositslimit, cursorHistórico de depósitos
GET/portfolio/withdrawalslimit, cursorHistórico de saques
GET/portfolio/summary/total_resting_order_value—Valor total de ordens pendentes (…)

Pré-requisitos

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

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

Habilidades Relacionadas