Cómo usar la API de Kalshi: Guía de Mercados de Predicción

¿Qué pasaría si pudieras usar APIs de grado institucional en una bolsa regulada por la CFTC para operar mercados de predicción programáticamente? Ofreciendo interfaces REST, WebSocket y FIX 4.4 al primer mercado de predicción autorizado federalmente en EE. UU., Kalshi hace precisamente eso. Solo en la primera mitad de 2025, la compañía generó más de $200 millones en ingresos.

Los mercados de predicción han experimentado una explosión en popularidad, pero los desarrolladores se enfrentan a una elección entre una infraestructura regulada y la flexibilidad cripto-nativa. Las plataformas no reguladas operan en zonas grises legales, requieren carteras de blockchain y exponen a los usuarios a riesgos de contratos inteligentes. Kalshi elimina estos puntos de fricción al operar como un Mercado de Contratos Designado bajo la supervisión de la CFTC, ofreciendo liquidación basada en moneda fiduciaria, patrones de API tradicionales y cumplimiento con las regulaciones financieras de EE. UU. Construyes aplicaciones de trading que las instituciones pueden usar realmente.

Tabla de Contenidos:

• Comprendiendo la Arquitectura de Kalshi
• Autenticación y Configuración
• Puntos Finales Clave de la API
• Datos en Tiempo Real con WebSocket
• Kalshi vs Polymarket para Desarrolladores
• Conclusión

Comprendiendo la Arquitectura de Kalshi

Kalshi opera como un exchange centralizado con contratos de eventos autocertificados. Comprender esta arquitectura te ayuda a diseñar integraciones robustas.

Estado de Mercado de Contratos Designado

Kalshi posee una licencia de la CFTC que le permite ofrecer contratos de eventos legalmente en los 50 estados de EE. UU. A diferencia de las apuestas deportivas reguladas por el estado, Kalshi opera bajo jurisdicción federal, evitando el fragmentado mosaico de leyes estatales sobre el juego. Este estado requiere un estricto cumplimiento: cada mercado se somete a revisión de la CFTC, la liquidación sigue los reglamentos publicados y el exchange mantiene sistemas de vigilancia para detectar manipulaciones.

Libro Central de Órdenes Límite (CLOB)

Kalshi empareja órdenes a través de un CLOB tradicional: las ofertas y demandas se encuentran a precios específicos con profundidad visible. Esto difiere de los creadores de mercado automatizados (AMMs) utilizados por los exchanges descentralizados. El CLOB proporciona transparencia de precios, permite órdenes límite y habilita estrategias de creación de mercado. Los creadores de mercado reciben aproximadamente $35,000 diarios en incentivos de liquidez (anualizados ~$12.7 millones), asegurando márgenes ajustados incluso en mercados menos activos.

Estructura de los Contratos de Eventos

Cada contrato representa un resultado binario: Sí paga $1.00, No paga $0.00. Los precios fluctúan entre $0.01 y $0.99, reflejando probabilidades implícitas del mercado. Un contrato que se negocia a $0.63 implica un 63% de posibilidades de que el evento ocurra. La liquidación se produce a $1.00 o $0.00 después de la verificación del resultado.

Los contratos especifican las condiciones exactas de liquidación: la definición del evento, la fuente de datos autorizada y la metodología de resolución. Por ejemplo, un contrato que pregunta "¿Superará el IPC el 3.5% en enero?" especifica la publicación exacta de la Oficina de Estadísticas Laborales y cómo interpretar los ajustes estacionales.

Oráculo y Liquidación

Kalshi utiliza un oráculo centralizado operado por el personal del exchange. Los resultados se resuelven basándose en fuentes oficiales: informes gubernamentales, proveedores de datos reputados u organizaciones de noticias establecidas. La resolución generalmente se completa dentro de las horas posteriores a la conclusión del evento. Este modelo centralizado prioriza la velocidad y la claridad sobre la descentralización, con la supervisión de la CFTC brindando rendición de cuentas.

Autenticación y Configuración

La autenticación de Kalshi requiere solicitudes firmadas con RSA utilizando claves privadas generadas en el panel de control de tu cuenta. Esto proporciona verificación criptográfica de las llamadas a la API.

Configuración del Entorno

Kalshi proporciona dos entornos:

• Demo: https://demo-api.kalshi.co/v1 — Prueba con dinero ficticio
• Producción: https://api.kalshi.com/v1 — Trading real con USD

Desarrolla siempre primero contra el entorno de demostración. Los entornos son funcionalmente idénticos, pero los mercados de demostración pueden tener liquidez simulada.

Generando Claves de API

Navega a Configuración → API en tu panel de control de Kalshi. Crea un nuevo par de claves:

1. Haz clic en "Generar Clave de API"
2. Guarda el ID de la Clave de API (comienza con kalshi_prod_ o kalshi_demo_)
3. Descarga la clave privada inmediatamente; Kalshi nunca la volverá a mostrar
4. Asegura la clave privada con permisos de archivo (chmod 600)

La clave privada utiliza la firma RSA-PSS. Kalshi proporciona SDKs oficiales que manejan la firma automáticamente, o puedes implementarla manualmente utilizando bibliotecas criptográficas estándar.

Instalación del SDK

Kalshi ofrece SDKs oficiales para Python (sincrónico y asincrónico) y TypeScript:

# Python sincrónico
pip install kalshi-python-sync

# Python asincrónico  
pip install kalshi-python-async

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

Existen SDKs comunitarios para Go y otros lenguajes, pero los SDKs oficiales proporcionan las implementaciones de firma más confiables y seguridad de tipos.

Autenticación Manual (Sin SDK)

Si implementas una firma personalizada, sigue este flujo:

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)

La cadena de firma combina la marca de tiempo, el método HTTP, la ruta y el cuerpo JSON (si está presente). RSA-PSS con SHA-256 proporciona verificación criptográfica de que las solicitudes se originan desde tu cuenta.

Sesiones Basadas en Token

Después de la autenticación inicial, obtén un token de sesión para las solicitudes posteriores:

# 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"
}

Los tokens expiran cada 30 minutos. Implementa una lógica de actualización automática antes de la expiración para mantener sesiones continuas.

Consejo profesionalApidog

Puntos Finales Clave de la API

La API REST de Kalshi sigue convenciones estándar con una estructura lógica de puntos finales por tipo de recurso.

Datos de Mercado (Públicos)

Recuperar mercados disponibles:

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

Obtener detalles específicos del mercado:

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

El formato del ticker codifica los detalles del contrato: INXCHI-25JAN31-T69.5 representa un mercado del Índice de Actividad Nacional de Inflación/Fed de Chicago que vence el 31 de enero de 2025, con un umbral de 69.5.

Consultar la profundidad del libro de órdenes:

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

La respuesta devuelve niveles de oferta y demanda con cantidades, lo que te permite evaluar la liquidez antes de colocar órdenes.

ConsejoApidog

Operaciones de Trading (Autenticadas)

Realizar una orden 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
})

Los precios de Kalshi están en centavos (1 = $0.01). Una orden límite a 6500 se ejecuta a $0.65 o mejor.

Cancelar una orden abierta:

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

Listar tus órdenes abiertas:

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

Portafolio y Cuenta

Consultar saldo de la cuenta:

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

Recuperar posiciones:

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

El punto final de posiciones devuelve tus tenencias actuales en todos los mercados, incluyendo ganancias y pérdidas no realizadas basadas en los últimos precios negociados.

Obtener historial de trading:

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

Las ejecuciones incluyen órdenes realizadas con marcas de tiempo, precios y tarifas pagadas.

Liquidación y Resolución

Consultar estado de liquidación para mercados expirados:

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

Después de la resolución, los contratos ganadores acreditan $1.00 por acción a tu cuenta; las posiciones perdedoras se liquidan a $0.00.

Datos en Tiempo Real con WebSocket

El sondeo REST introduce latencia. La API WebSocket de Kalshi transmite actualizaciones en tiempo real del libro de órdenes, ejecuciones de trading y cambios de estado del mercado.

Conectándose a 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);

Las conexiones WebSocket requieren latidos periódicos (cada 30 segundos) para evitar el tiempo de espera. Implementa una lógica de reconexión automática para aplicaciones de producción.

Canales de Suscripción

Los canales disponibles incluyen:

• orderbook:{market_id} — Actualizaciones de oferta/demanda
• trades:{market_id} — Ejecuciones recientes
• market_status:{market_id} — Interrupciones de trading, liquidaciones
• user_orders — Cambios en el estado de tus órdenes
• user_fills — Ejecuciones de tus trades

Suscríbete a múltiples canales en un solo mensaje para una transmisión de datos eficiente.

Apidog

Kalshi vs Polymarket para Desarrolladores

Ambas plataformas ofrecen APIs de mercados de predicción, pero sus arquitecturas sirven a diferentes casos de uso.

Estado Regulatorio

Kalshi opera como un Mercado de Contratos Designado regulado por la CFTC. Esto proporciona claridad legal para los usuarios estadounidenses, pero requiere cumplimiento de KYC/AML y restringe el acceso a 42 estados (excluyendo Arizona, Illinois, Massachusetts, Maryland, Michigan, Montana, Nueva Jersey, Ohio).

Polymarket obtuvo recientemente la aprobación de la CFTC a través de la adquisición de QCX LLC y posee una licencia DCM con Carta de No Acción. Actualmente opera internacionalmente con disponibilidad limitada en EE. UU. pendiente de un despliegue completo. Anteriormente fue multado con $1.4 millones por operar sin registro (enero de 2022).

Arquitectura Técnica

Kalshi utiliza una infraestructura centralizada con emparejamiento de órdenes fuera de la cadena y liquidación en USD fiduciarios. El acceso a la API sigue patrones tradicionales: REST sobre HTTPS, WebSocket para streaming, FIX 4.4 para trading institucional. Los tiempos de respuesta se miden en milisegundos.

Polymarket opera en la blockchain de Polygon con una arquitectura CLOB híbrida: emparejamiento de órdenes fuera de la cadena, liquidación en la cadena a través del Marco de Tokens Condicionales. La integración requiere interacción con la blockchain: órdenes firmadas EIP-712, llamadas a contratos inteligentes, transacciones USDC. La finalidad de la liquidación requiere confirmación en la blockchain (de segundos a minutos).

Modelos de Autenticación

Kalshi utiliza solicitudes firmadas con RSA-PSS con claves API, sesiones basadas en tokens que expiran cada 30 minutos. Requiere almacenamiento seguro de claves privadas y firma criptográfica.

Polymarket utiliza firmas de monederos de blockchain (MetaMask, WalletConnect). Los usuarios firman órdenes con claves privadas que controlan sus direcciones de Polygon. No hay tokens de sesión; cada transacción requiere una firma nueva.

Moneda de Liquidación

Kalshi liquida en USD mediante transferencia bancaria, ACH, tarjeta de débito, PayPal, Apple Pay, Google Pay. El retiro mínimo suele ser de $10. El tiempo de procesamiento es de 1 a 3 días hábiles para ACH, más rápido para transferencias.

Polymarket liquida en USDC en la blockchain de Polygon. Liquidación instantánea tras la resolución, pero requiere una cartera de criptomonedas e infraestructura de entrada/salida de cripto. Se aplican tarifas de gas para los retiros.

Protocolos de API

Kalshi ofrece tres protocolos:

• REST: HTTP estándar para todas las operaciones
• WebSocket: Streaming en tiempo real para datos de mercado y actualizaciones de órdenes
• FIX 4.4: Protocolo estándar de la industria para el trading institucional de alta frecuencia

Polymarket requiere:

• GraphQL: Consultas flexibles para datos de blockchain
• EIP-712: Firma de datos tipados para órdenes
• Llamadas a Contratos Inteligentes: Interacción directa con la blockchain para la liquidación

Recomendaciones de Casos de Uso

Elige Kalshi para:

• Mesas de trading institucionales que requieren cumplimiento normativo
• Aplicaciones que sirven a usuarios minoristas de EE. UU.
• Entradas/salidas de fiat sin la complejidad cripto
• Trading algorítmico de baja latencia
• Integraciones financieras tradicionales

Elige Polymarket para:

• Protocolos DeFi que requieren componibilidad de contratos inteligentes
• Usuarios globales fuera de las jurisdicciones de EE. UU.
• Aplicaciones cripto-nativas con infraestructura de cartera existente
• Creación rápida de mercados (horas frente a días para la aprobación)
• Verificación y transparencia en la cadena

Complejidad de la Integración

La integración de Kalshi requiere de 2 a 4 semanas para funcionalidades básicas de datos de mercado y trading, asumiendo experiencia con API REST. Los patrones HTTP familiares reducen la curva de aprendizaje.

La integración de Polymarket requiere de 3 a 6 meses para mercados de contratos inteligentes listos para producción, incluyendo auditoría de seguridad (presupuesto de $50K-$200K), integración de oráculos y arranque de liquidez. La experiencia en blockchain es obligatoria.

Estructura de Costos

Kalshi cobra tarifas de trading basadas en las ganancias esperadas (0.7-3.5%, promediando 0.8%). El acceso a la API es gratuito, solo pagas las tarifas de trading. No hay tarifas de retiro para ACH.

Polymarket cobra una tarifa de 'taker' del 0.01% en los mercados principales, con tarifas de gas para las transacciones de blockchain. No hay tarifas en algunos mercados, pero se aplican los costos de la red.

Conclusión

La API de Kalshi proporciona acceso regulado a los mercados de predicción a través de los protocolos familiares REST y WebSocket. Te autenticas con solicitudes firmadas con RSA, negocias contratos de eventos a través de un libro central de órdenes límite y liquidas en USD a través de la banca tradicional. La supervisión de la CFTC garantiza el cumplimiento legal para las aplicaciones de EE. UU., mientras que la tasa de ingresos anualizada de $200 millones demuestra la viabilidad institucional.

Comienza con el entorno de demostración para probar los patrones de integración. Implementa una gestión adecuada de claves y la firma de solicitudes antes de pasar a producción. Utiliza el streaming de WebSocket para aplicaciones en tiempo real que requieran baja latencia. Supervisa la expiración del token cada 30 minutos e implementa una lógica de actualización para un funcionamiento continuo.

Empieza hoy mismo con Apidog: importa tus puntos finales de la API de Kalshi en segundos y comienza a probar tus estrategias de mercado de predicción sin configuración.