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:
| Deporte | Ticker de Serie | Ejemplo |
|---|---|---|
| NHL | KXNHLGAME | KXNHLGAME-25MAY12EDMORL |
| NBA | KXNBAGAME | KXNBAGAME-25MAY12BOSLAL |
| NFL | KXNFLGAME | KXNFLGAME-25SEP07KCDET |
| MLB | KXMLBGAME | KXMLBGAME-25MAY12NYYLAD |
| EPL (Premier League) | KXEPLGAME | KXEPLGAME-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:
| Encabezado | Valor |
|---|---|
KALSHI-ACCESS-KEY | ID de clave API ($KALSHI_ACCESS_KEY) |
KALSHI-ACCESS-SIGNATURE | Firma RSA-PSS de timestamp + método + ruta |
KALSHI-ACCESS-TIMESTAMP | Timestamp 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_KEYacepta 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\nen.envpara 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étodo | Endpoint | Parámetros Principales | Descripción |
|---|---|---|---|
| GET | /events | limit (1-200), cursor, status, series_ticker, with_nested_markets | Listar eventos (excluye multivariantes) |
| GET | /events/{event_ticker} | event_ticker, with_nested_markets | Obtener evento específico |
| GET | /events/{event_ticker}/metadata | event_ticker | Solo metadatos del evento |
| GET | /events/multivariate | limit, cursor, series_ticker, collection_ticker, with_nested_markets | Listar eventos multivariantes (combinados) |
Mercados
| Método | Endpoint | Parámetros Principales | Descripción |
|---|---|---|---|
| GET | /markets | limit, cursor, status, ticker, event_ticker, series_ticker, min_close_ts, max_close_ts | Listar/filtrar mercados |
| GET | /markets/{ticker} | ticker | Obtener detalles de mercado específico |
| GET | /markets/{ticker}/orderbook | ticker, depth | Libro de órdenes actual (ofertas de Sí + ofertas de No) |
| GET | /markets/orderbooks | tickers (array, máx 100) | Libros de órdenes por lote |
| GET | /markets/trades | ticker, limit, cursor, min_ts, max_ts | Operaciones en todos los mercados |
Velas
| Método | Endpoint | Parámetros Principales | Descripción |
|---|---|---|---|
| GET | /series/{series_ticker}/markets/{ticker}/candlesticks | series_ticker, ticker, start_ts, end_ts, period_interval | Velas a nivel de mercado |
| GET | /series/{series_ticker}/events/{ticker}/candlesticks | series_ticker, ticker, start_ts, end_ts, period_interval | Velas agregadas a nivel de evento |
| GET | /markets/candlesticks | market_tickers, start_ts, end_ts, period_interval | Velas por lote |
Valores de period_interval: 1 (1 min), 60 (1 hora), 1440 (1 día)
Pronóstico y Datos en Vivo
| Método | Endpoint | Parámetros Principales | Descripción |
|---|---|---|---|
| GET | /series/{series_ticker}/events/{ticker}/forecast_percentile_history | percentiles (0-10000), start_ts, end_ts, period_interval | Histórico de percentiles de pronóstico |
| GET | /live_data/milestone/{milestone_id} | milestone_id, include_player_stats | Datos de hito en vivo |
| GET | /live_data/batch | milestone_ids (array, máx 100), include_player_stats | Datos en vivo por lote |
| GET | /live_data/game-stats/{milestone_id} | milestone_id | Estadísticas jugada por jugada (fútbol americano, baloncesto, fútbol, hockey, béisbol) |
Series
| Método | Endpoint | Parámetros Principales | Descripción |
|---|---|---|---|
| GET | /series/{series_ticker} | series_ticker, include_volume | Obtener plantilla de serie |
| GET | /series | category, tags, include_volume, min_updated_ts | Listar todas las series |
Información del Exchange
| Método | Endpoint | Parámetros Principales | Descripció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_changes | series_ticker, show_historical | Historial de cambios de tarifas |
Búsqueda y Descubrimiento
| Método | Endpoint | Parámetros Principales | Descripció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étodo | Endpoint | Parámetros Principales | Descripción |
|---|---|---|---|
| GET | /portfolio/orders | ticker, event_ticker, status, limit, cursor, subaccount | Listar órdenes del usuario |
| GET | /portfolio/orders/{order_id} | order_id | Obtener orden específica |
| POST | /portfolio/orders | Cuerpo: ticker, action, side, type, count, yes_price/no_price | Crear orden |
| DELETE | /portfolio/orders/{order_id} | order_id, subaccount | Cancelar orden |
| POST | /portfolio/orders/{order_id}/amend | order_id, Cuerpo: nuevo count/price | Modificar orden |
| POST | /portfolio/orders/{order_id}/decrease | order_id, Cuerpo: cantidad de reducción | Reducir cantidad de la orden |
| POST | /portfolio/orders/batched | Cuerpo: array de órdenes | Crear por lote (tamaño máximo escala con el nivel) |
| DELETE | /portfolio/orders/batched | Cuerpo: array de IDs de orden | Cancelar por lote |
| GET | /portfolio/orders/queue_positions | market_tickers, event_ticker, subaccount | Todas las posiciones de órdenes en reposo |
| GET | /portfolio/orders/{order_id}/queue_position | order_id | Posición de orden específica |
Órdenes V2 — Órdenes de Mercado de Eventos (Autenticado, Punto Fijo)
| Método | Endpoint | Parámetros Principales | Descripción |
|---|---|---|---|
| POST | /portfolio/events/orders | Cuerpo: ticker de evento, lado del mercado, precio (punto fijo), count | Crear orden V2 |
| POST | /portfolio/events/orders/batched | Cuerpo: array de órdenes V2 | Crear por lote V2 |
| DELETE | /portfolio/events/orders/{order_id} | order_id, subaccount | Cancelar orden V2 |
| DELETE | /portfolio/events/orders/batched | Cuerpo: array de IDs de orden | Cancelar por lote V2 |
| POST | /portfolio/events/orders/{order_id}/amend | order_id, Cuerpo: nuevo count/price | Modificar orden V2 |
| POST | /portfolio/events/orders/{order_id}/decrease | order_id, Cuerpo: nuevo count restante | Reducir orden V2 |
Grupos de Órdenes (Autenticado)
| Método | Endpoint | Parámetros Principales | Descripción |
|---|---|---|---|
| GET | /portfolio/order_groups | subaccount | Listar todos los grupos de órdenes |
| POST | /portfolio/order_groups/create | Cuerpo: límite de contratos | Crear grupo de órdenes |
| GET | /portfolio/order_groups/{id} | id, subaccount | Obtener grupo específico |
| DELETE | /portfolio/order_groups/{id} | id, subaccount | Eliminar grupo y cancelar todas las órdenes |
| PUT | /portfolio/order_groups/{id}/limit | id, Cuerpo: nuevo límite | Actualizar límite de contratos |
| PUT | /portfolio/order_groups/{id}/trigger | id, subaccount | Activar grupo (cancelar todas las órdenes) |
| PUT | /portfolio/order_groups/{id}/reset | id, subaccount | Reiniciar contador de contratos emparejados |
Portafolio (Autenticado)
| Método | Endpoint | Parámetros Principales | Descripción |
|---|---|---|---|
| GET | /portfolio/balance | subaccount | Saldo y valor del portafolio (en centavos) |
| GET | /portfolio/positions | cursor, limit, count_filter, ticker, event_ticker, subaccount | Posiciones del usuario |
| GET | /portfolio/fills | ticker, order_id, min_ts, max_ts, limit, cursor, subaccount | Todas las ejecuciones de operaciones |
| GET | /portfolio/settlements | limit, cursor, ticker, event_ticker, min_ts, max_ts, subaccount | Historial de liquidaciones |
| GET | /portfolio/deposits | limit, cursor | Historial de depósitos |
| GET | /portfolio/withdrawals | limit, cursor | Historial de retiros |
| GET | /portfolio/summary/total_resting_order_value | — | Valor total de órdenes en reposo |
| GET | /portfolio/fees | min_ts, max_ts, limit, cursor | Historial de tarifas |
| GET | /portfolio/subaccounts | — | Listar subcuentas |
| POST | /portfolio/subaccounts | Cuerpo: subaccount_id, display_name | Crear subcuenta |
| DELETE | /portfolio/subaccounts/{subaccount_id} | subaccount_id | Eliminar subcuenta |
Integración con Agent SDK
No se necesita integración adicional.
Configuración
Sigue estos pasos para configurar el skill:
- 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).
- 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.
- 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