Communitygithub.com

Kalshi API - Mercados de Predicción

Opera y consulta el primer exchange de mercados de predicción regulado por la CFTC. Contratos binarios de sí/no sobre eventos del mundo real, con precios de 1 a 99 centavos.

¿Qué es Kalshi API - Mercados de Predicción?

Este skill permite a agentes de IA comerciar y consultar mercados de predicción binarios en Kalshi, la primera plataforma regulada por la CFTC en EE. UU. Cubre eventos de política, economía, deportes y clima, con contratos que cotizan en centavos (1-99) que representan probabilidades implícitas. El skill proporciona acceso completo a la API de Kalshi, incluyendo autenticación mediante firma RSA-PSS, navegación jerárquica (Serie → Evento → Mercado), y endpoints para obtener datos de mercado, libros de órdenes, velas, y ejecutar operaciones. Es especialmente útil para agentes que necesitan analizar o negociar en mercados de eventos como informes de empleo, partidos deportivos o elecciones. La documentación incluye ejemplos de código en Python y Bash, resuelve problemas comunes de firma y formateo de claves, y advierte sobre errores típicos como usar búsquedas por palabra clave en deportes (que solo devuelven parlays) en lugar de navegar por la jerarquía correcta.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

API de Kalshi

Opera y consulta el primer exchange de mercados de predicción regulado por la CFTC. Contratos binarios de sí/no sobre eventos del mundo real con precios de 1 a 99 centavos.

URL base: https://external-api.kalshi.com/trade-api/v2 URL demo: https://external-api.demo.kalshi.co/trade-api/v2

Obtén tu clave API en https://kalshi.com/account/api-keys (se requiere nivel Premier o Market Maker)

Conceptos Clave

Jerarquía: Series > Eventos > Mercados

  • Series — plantillas de eventos recurrentes (ej., "Informe de Empleo Mensual", "Solicitudes de Desempleo Semanales")
  • Eventos — instancias específicas dentro de una serie (ej., "Informe de Empleo de Mayo 2026")
  • Mercados — resultados binarios individuales dentro de un evento (ej., "¿Los empleos añadidos superarán los 200k?")

Precios de Contratos Binarios

  • Los precios están en centavos (1-99), representando probabilidad implícita
  • Un contrato a 65c = el mercado implica 65% de probabilidad
  • Una oferta de compra a precio X en Sí es equivalente a una oferta de venta en No a (100 - X) — los libros de órdenes muestran solo ofertas de compra y venta de Sí
  • Liquidación: paga $1.00 (100 centavos) si Sí, $0 si No
  • Todos los valores monetarios (saldo, precios, liquidaciones) están en centavos

Formato de Ticker

  • Serie: KXBTC, KXJOBLESS, KXINX
  • Evento: KXBTC-25MAY30 (serie + fecha)
  • Mercado: KXBTC-25MAY30-T100000 (evento + umbral/resultado)

Tickers de partidos deportivos siguen un patrón diferente: {SERIE}-{YYAAMMDD}{EQUIPO1}{EQUIPO2}-{EQUIPO}

  • Ejemplo: KXNHLGAME-25MAY12EDMORL-EDM (NHL, 12 de mayo de 2025, Edmonton vs Orlando, Edmonton gana)
  • Cada evento de partido tiene dos mercados de SÍ mutuamente excluyentes — uno por equipo

CRÍTICO: Navegación de Mercados Basada en Series

NO uses /markets?keyword= para deportes, elecciones o cualquier categoría basada en series. Solo devuelve paquetes de parlays multijuego, no los mercados reales a nivel de partido. Buscar "NHL", "Fulham", "Premier League", etc., devuelve cero o resultados irrelevantes.

Siempre navega: Serie → Evento → Mercado. Los mercados a nivel de partido están bajo la jerarquía serie/evento y deben ser accedidos a través de /events?series_ticker=KXXX. Además, /markets/{ticker} puede devolver 404 para mercados de partidos — los precios de oferta/demanda solo aparecen en la respuesta del endpoint de eventos (/events/{event_ticker} con with_nested_markets=true).

Este patrón aplica a todas las categorías basadas en series, no solo deportes:

  • Partidos deportivos — NHL, NBA, NFL, MLB, EPL, etc.
  • Carreras políticas — mercados de candidatos individuales dentro de eventos con múltiples candidatos
  • Mercados específicos de empresas — ganancias, cambios de CEO dentro de una serie
  • Datos económicos recurrentes — informes de empleo, solicitudes de desempleo, IPC, etc.

Tickers de series deportivas conocidas:

DeporteTicker de SerieEjemplo
NHLKXNHLGAMEKXNHLGAME-25MAY12EDMORL
NBAKXNBAGAMEKXNBAGAME-25MAY12BOSLAL
NFLKXNFLGAMEKXNFLGAME-25SEP07KCDET
MLBKXMLBGAMEKXMLBGAME-25MAY12NYYLAD
EPL (Premier League)KXEPLGAMEKXEPLGAME-25MAY12FULARS

Flujo de trabajo correcto para deportes:

# 1. Listar partidos abiertos para un deporte
curl -s "https://external-api.kalshi.com/trade-api/v2/events?series_ticker=KXNHLGAME&status=open&with_nested_markets=true"

# 2. Obtener partido específico con oferta/demanda en vivo
curl -s "https://external-api.kalshi.com/trade-api/v2/events/KXNHLGAME-25MAY12EDMORL?with_nested_markets=true"

# INCORRECTO — no hagas esto:
# curl -s "https://external-api.kalshi.com/trade-api/v2/markets?keyword=NHL"  ← devuelve parlays, no partidos

Cómo Llamar

Kalshi utiliza autenticación por firma de par de claves RSA. Se requieren tres encabezados en las solicitudes autenticadas:

EncabezadoValor
KALSHI-ACCESS-KEYID de clave API ($KALSHI_ACCESS_KEY)
KALSHI-ACCESS-SIGNATUREFirma RSA-PSS de timestamp + método + ruta
KALSHI-ACCESS-TIMESTAMPTimestamp Unix (ms)

Los endpoints GET públicos (mercados, eventos, libros de órdenes) se pueden llamar sin encabezados de autenticación.

# Endpoint público — no necesita autenticación
curl -s "https://external-api.kalshi.com/trade-api/v2/markets?limit=10&status=open"

Para endpoints autenticados, usa firmado RSA-PSS directo (no el SDK kalshi_python — no 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"]
    # Decodificar secuencias de escape literales primero (algunos canales de entrada
    # guardan '\n' como dos caracteres de barra invertida + n en lugar de un salto de línea real).
    raw = (raw.replace('\\r\\n', '\n').replace('\\n', '\n')
              .replace('\\r', '\n').replace('\\t', ' '))
    # Eliminar marcadores PEM si están presentes, luego eliminar TODOS los espacios y reajustar.
    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()  # la ruta NO debe incluir la cadena de consulta
    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, ...} — el saldo está en centavos

Problemas comunes con la firma:

  • PSS no PKCS1v15 — el relleno PKCS1v15 devuelve 401. Debe usar PSS con SHA256.
  • Eliminar cadenas de consulta antes de firmar — la firma se calcula solo sobre la ruta desnuda (ej., /trade-api/v2/portfolio/balance), no /trade-api/v2/portfolio/balance?param=value. Incluir la cadena de consulta resultará en 401.
  • Formato de la variable de entorno de la clave — KALSHI_PRIVATE_KEY acepta cualquiera de: cuerpo base64 sin procesar, PEM completa con saltos de línea reales, o PEM completa con saltos de línea colapsados en espacios (común al pegar a través de formularios web). El helper normaliza todos los formatos automáticamente. Para el almacenamiento más robusto, guarda como una PEM multilínea entre comillas dobles con escapes \n en .env para que python-dotenv la reconstituya como una cadena PEM real.

Especificación de la API

Especificación OpenAPI completa: https://docs.kalshi.com/openapi.yaml

Enrutamiento de Intenciones

Asigna la intención del usuario al endpoint correcto. Todas las rutas son relativas a la URL base.

Eventos

MétodoEndpointParámetros PrincipalesDescripción
GET/eventslimit (1-200), cursor, status, series_ticker, with_nested_marketsListar eventos (excluye multivariantes)
GET/events/{event_ticker}event_ticker, with_nested_marketsObtener evento específico
GET/events/{event_ticker}/metadataevent_tickerSolo metadatos del evento
GET/events/multivariatelimit, cursor, series_ticker, collection_ticker, with_nested_marketsListar eventos multivariantes (combinados)

Mercados

MétodoEndpointParámetros PrincipalesDescripción
GET/marketslimit, cursor, status, ticker, event_ticker, series_ticker, min_close_ts, max_close_tsListar/filtrar mercados
GET/markets/{ticker}tickerObtener detalles de mercado específico
GET/markets/{ticker}/orderbookticker, depthLibro de órdenes actual (ofertas de Sí + ofertas de No)
GET/markets/orderbookstickers (array, máx 100)Libros de órdenes por lote
GET/markets/tradesticker, limit, cursor, min_ts, max_tsOperaciones en todos los mercados

Velas

MétodoEndpointParámetros PrincipalesDescripción
GET/series/{series_ticker}/markets/{ticker}/candlesticksseries_ticker, ticker, start_ts, end_ts, period_intervalVelas a nivel de mercado
GET/series/{series_ticker}/events/{ticker}/candlesticksseries_ticker, ticker, start_ts, end_ts, period_intervalVelas agregadas a nivel de evento
GET/markets/candlesticksmarket_tickers, start_ts, end_ts, period_intervalVelas por lote

Valores de period_interval: 1 (1 min), 60 (1 hora), 1440 (1 día)

Pronóstico y Datos en Vivo

MétodoEndpointParámetros PrincipalesDescripción
GET/series/{series_ticker}/events/{ticker}/forecast_percentile_historypercentiles (0-10000), start_ts, end_ts, period_intervalHistórico de percentiles de pronóstico
GET/live_data/milestone/{milestone_id}milestone_id, include_player_statsDatos de hito en vivo
GET/live_data/batchmilestone_ids (array, máx 100), include_player_statsDatos en vivo por lote
GET/live_data/game-stats/{milestone_id}milestone_idEstadísticas jugada por jugada (fútbol americano, baloncesto, fútbol, hockey, béisbol)

Series

MétodoEndpointParámetros PrincipalesDescripción
GET/series/{series_ticker}series_ticker, include_volumeObtener plantilla de serie
GET/seriescategory, tags, include_volume, min_updated_tsListar todas las series

Información del Exchange

MétodoEndpointParámetros PrincipalesDescripción
GET/exchange/status—Estado actual del exchange
GET/exchange/schedule—Horario de operación
GET/exchange/announcements—Anuncios de la plataforma
GET/exchange/user_data_timestamp—Timestamp de sincronización de datos
GET/series/fee_changesseries_ticker, show_historicalHistorial de cambios de tarifas

Búsqueda y Descubrimiento

MétodoEndpointParámetros PrincipalesDescripción
GET/search/tags_by_categories—Etiquetas organizadas por categorías de series
GET/search/filters_by_sport—Filtros organizados por deporte

Órdenes (Autenticado)

MétodoEndpointParámetros PrincipalesDescripción
GET/portfolio/ordersticker, event_ticker, status, limit, cursor, subaccountListar órdenes del usuario
GET/portfolio/orders/{order_id}order_idObtener orden específica
POST/portfolio/ordersCuerpo: ticker, action, side, type, count, yes_price/no_priceCrear orden
DELETE/portfolio/orders/{order_id}order_id, subaccountCancelar orden
POST/portfolio/orders/{order_id}/amendorder_id, Cuerpo: nuevo count/priceModificar orden
POST/portfolio/orders/{order_id}/decreaseorder_id, Cuerpo: cantidad de reducciónReducir cantidad de la orden
POST/portfolio/orders/batchedCuerpo: array de órdenesCrear por lote (tamaño máximo escala con el nivel)
DELETE/portfolio/orders/batchedCuerpo: array de IDs de ordenCancelar por lote
GET/portfolio/orders/queue_positionsmarket_tickers, event_ticker, subaccountTodas las posiciones de órdenes en reposo
GET/portfolio/orders/{order_id}/queue_positionorder_idPosición de orden específica

Órdenes V2 — Órdenes de Mercado de Eventos (Autenticado, Punto Fijo)

MétodoEndpointParámetros PrincipalesDescripción
POST/portfolio/events/ordersCuerpo: ticker de evento, lado del mercado, precio (punto fijo), countCrear orden V2
POST/portfolio/events/orders/batchedCuerpo: array de órdenes V2Crear por lote V2
DELETE/portfolio/events/orders/{order_id}order_id, subaccountCancelar orden V2
DELETE/portfolio/events/orders/batchedCuerpo: array de IDs de ordenCancelar por lote V2
POST/portfolio/events/orders/{order_id}/amendorder_id, Cuerpo: nuevo count/priceModificar orden V2
POST/portfolio/events/orders/{order_id}/decreaseorder_id, Cuerpo: nuevo count restanteReducir orden V2

Grupos de Órdenes (Autenticado)

MétodoEndpointParámetros PrincipalesDescripción
GET/portfolio/order_groupssubaccountListar todos los grupos de órdenes
POST/portfolio/order_groups/createCuerpo: límite de contratosCrear grupo de órdenes
GET/portfolio/order_groups/{id}id, subaccountObtener grupo específico
DELETE/portfolio/order_groups/{id}id, subaccountEliminar grupo y cancelar todas las órdenes
PUT/portfolio/order_groups/{id}/limitid, Cuerpo: nuevo límiteActualizar límite de contratos
PUT/portfolio/order_groups/{id}/triggerid, subaccountActivar grupo (cancelar todas las órdenes)
PUT/portfolio/order_groups/{id}/resetid, subaccountReiniciar contador de contratos emparejados

Portafolio (Autenticado)

MétodoEndpointParámetros PrincipalesDescripción
GET/portfolio/balancesubaccountSaldo y valor del portafolio (en centavos)
GET/portfolio/positionscursor, limit, count_filter, ticker, event_ticker, subaccountPosiciones del usuario
GET/portfolio/fillsticker, order_id, min_ts, max_ts, limit, cursor, subaccountTodas las ejecuciones de operaciones
GET/portfolio/settlementslimit, cursor, ticker, event_ticker, min_ts, max_ts, subaccountHistorial de liquidaciones
GET/portfolio/depositslimit, cursorHistorial de depósitos
GET/portfolio/withdrawalslimit, cursorHistorial de retiros
GET/portfolio/summary/total_resting_order_value—Valor total de órdenes en reposo
GET/portfolio/feesmin_ts, max_ts, limit, cursorHistorial de tarifas
GET/portfolio/subaccounts—Listar subcuentas
POST/portfolio/subaccountsCuerpo: subaccount_id, display_nameCrear subcuenta
DELETE/portfolio/subaccounts/{subaccount_id}subaccount_idEliminar subcuenta

Integración con Agent SDK

No se necesita integración adicional.

Configuración

Sigue estos pasos para configurar el skill:

  1. Crea una cuenta en Kalshi — Regístrate en https://kalshi.com y actualiza a nivel Premier o Market Maker (requerido para acceso a la API).
  2. Genera una clave API — Ve a https://kalshi.com/account/api-keys y genera un nuevo par de claves. Guarda el Access Key ID y el Private Key de forma segura.
  3. Configura las variables de entorno — Añade las siguientes variables a tu archivo .env:
KALSHI_ACCESS_KEY=tu_access_key_id_aquí
KALSHI_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...tu_clave_privada_aquí...
-----END RSA PRIVATE KEY-----"

Nota: La clave privada debe almacenarse como una cadena PEM con saltos de línea literales \n o caracteres de nueva línea reales. 4. Verifica la conexión — Ejecuta el script de ejemplo para comprobar que la autenticación funciona:

python3 -c "
import os, time, base64, requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

BASE_URL = 'https://api.elections.kalshi.com'

# ... (usa el código de ejemplo de la sección 'Cómo Llamar')
"

Referencia de la API

Documentación oficial: https://kalshi.com/docs/api

Individual skills in this repo

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

Skills relacionados