Communitygithub.com

Starchild-ai-agent/official-skills

Marchés de prédiction Kalshi : contrats binaires sur des événements politiques, économiques, sportifs et météorologiques.

Qu'est-ce que official-skills ?

Cette compétence permet à un agent IA d'interagir directement avec l'API de Kalshi, la première bourse de marchés de prédiction régulée par la CFTC aux États-Unis. Elle offre la possibilité de consulter et de trader des contrats binaires (oui/non) sur une large gamme d'événements réels : indicateurs économiques (CPI, emploi), compétitions sportives (NHL, NBA, NFL, MLB, EPL), élections politiques, et bien plus encore. L'agent peut naviguer dans la hiérarchie des données (Séries > Événements > Marchés), récupérer les cotations en direct, les carnets d'ordres, et exécuter des transactions via une signature RSA-PSS. La compétence fournit également des avertissements essentiels sur les pièges courants, comme la nécessité d'utiliser la navigation par série pour les événements sportifs et politiques, plutôt que la recherche par mot-clé qui ne renvoie que des paris multi-matchs non pertinents. Destinée aux développeurs et aux utilisateurs avancés, elle est compatible avec les environnements Python utilisant des bibliothèques comme `requests` et `cryptography`.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

API Kalshi

Tradez et interrogez la première bourse de marchés de prédiction régulée par la CFTC. Contrats binaires oui/non sur des événements réels, prix entre 1 et 99 cents.

URL de base : https://external-api.kalshi.com/trade-api/v2 URL de démonstration : https://external-api.demo.kalshi.co/trade-api/v2

Obtenez votre clé API sur https://kalshi.com/account/api-keys (niveau Premier ou Market Maker requis)

Concepts clés

Hiérarchie : Séries > Événements > Marchés

  • Séries — modèles d'événements récurrents (ex. "Rapport mensuel sur l'emploi", "Demandes hebdomadaires d'allocations chômage")
  • Événements — instances spécifiques d'une série (ex. "Rapport sur l'emploi de mai 2026")
  • Marchés — résultats binaires individuels au sein d'un événement (ex. "Les créations d'emplois seront-elles supérieures à 200 000 ?")

Tarification des contrats binaires

  • Les prix sont en cents (1-99), représentant une probabilité implicite
  • Un contrat Oui à 65c = le marché implique une probabilité de 65 %
  • L'offre Oui au prix X équivaut à la demande Non à (100 - X) — les carnets d'ordres affichent uniquement les offres Oui et les offres Non
  • Règlement : paie 1,00 $ (100 cents) si Oui, 0 $ si Non
  • Toutes les valeurs monétaires (solde, prix, règlements) sont en cents

Format du ticker

  • Série : KXBTC, KXJOBLESS, KXINX
  • Événement : KXBTC-25MAY30 (série + date)
  • Marché : KXBTC-25MAY30-T100000 (événement + seuil/résultat)

Les tickers de matchs sportifs suivent un modèle différent : {SERIES}-{YYMONDD}{TEAM1}{TEAM2}-{TEAM}

  • Exemple : KXNHLGAME-25MAY12EDMORL-EDM (NHL, 12 mai 2025, Edmonton contre Orlando, Edmonton gagnant)
  • Chaque événement de match a deux marchés OUI mutuellement exclusifs — un par équipe

CRITIQUE : Navigation sur le marché basée sur les séries

N'UTILISEZ PAS /markets?keyword= pour les sports, les élections ou toute catégorie basée sur une série. Cela ne renvoie que des packs de paris multi-matchs, et non les marchés réels au niveau des matchs. La recherche de "NHL", "Fulham", "Premier League", etc. renvoie zéro résultat ou des résultats non pertinents.

Naviguez toujours : Série → Événements → Marchés. Les marchés au niveau des matchs se trouvent sous la hiérarchie série/événement et doivent être consultés via /events?series_ticker=KXXX. De plus, /markets/{ticker} peut retourner une erreur 404 pour les marchés de matchs. Les prix d'achat et de vente n'apparaissent que dans la réponse du point de terminaison de l'événement (/events/{event_ticker} avec with_nested_markets=true).

Ce modèle s'applique à toutes les catégories basées sur les séries, pas seulement aux sports :

  • Matchs sportifs — NHL, NBA, NFL, MLB, EPL, etc.
  • Courses politiques — marchés de candidats individuels au sein d'événements multi-candidats
  • Marchés spécifiques à une entreprise — bénéfices, changements de PDG au sein d'une série
  • Données économiques récurrentes — rapports sur l'emploi, demandes d'allocations chômage, CPI, etc.

Tickers de séries sportives connus :

SportTicker de sérieExemple
NHLKXNHLGAMEKXNHLGAME-25MAY12EDMORL
NBAKXNBAGAMEKXNBAGAME-25MAY12BOSLAL
NFLKXNFLGAMEKXNFLGAME-25SEP07KCDET
MLBKXMLBGAMEKXMLBGAME-25MAY12NYYLAD
EPL (Premier League)KXEPLGAMEKXEPLGAME-25MAY12FULARS

Flux de travail correct pour les sports :

# 1. Lister les matchs ouverts pour un sport
curl -s "https://external-api.kalshi.com/trade-api/v2/events?series_ticker=KXNHLGAME&status=open&with_nested_markets=true"

# 2. Obtenir un match spécifique avec l'offre/la demande en direct
curl -s "https://external-api.kalshi.com/trade-api/v2/events/KXNHLGAME-25MAY12EDMORL?with_nested_markets=true"

# FAUX — ne faites pas ceci :
# curl -s "https://external-api.kalshi.com/trade-api/v2/markets?keyword=NHL"  ← renvoie des paris multiples, pas des matchs

Comment appeler

Kalshi utilise l'authentification par signature de paire de clés RSA. Trois en-têtes sont requis sur les requêtes authentifiées :

En-têteValeur
KALSHI-ACCESS-KEYID de la clé API ($KALSHI_ACCESS_KEY)
KALSHI-ACCESS-SIGNATURESignature RSA-PSS de timestamp + méthode + chemin
KALSHI-ACCESS-TIMESTAMPTimestamp Unix (ms)

Les points de terminaison GET publics (marchés, événements, carnets d'ordres) peuvent être appelés sans en-têtes d'authentification.

# Point de terminaison public — pas d'authentification requise
curl -s "https://external-api.kalshi.com/trade-api/v2/markets?limit=10&status=open"

Pour les points de terminaison authentifiés, utilisez la signature RSA-PSS directe (pas le SDK kalshi_python — il ne fonctionne pas) :

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"]
    # Décode d'abord les séquences d'échappement littérales (certains canaux d'entrée
    # enregistrent '\n' comme deux caractères barre oblique inverse + n au lieu d'un
    # vrai saut de ligne).
    raw = (raw.replace('\\r\\n', '\n').replace('\\n', '\n')
              .replace('\\r', '\n').replace('\\t', ' '))
    # Supprime les marqueurs PEM s'ils sont présents, puis supprime TOUS les espaces
    # et réencapsule.
    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()  # le chemin ne doit PAS inclure la chaîne de requête
    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, ...} — le solde est en cents

Pièges de signature :

  • PSS pas PKCS1v15 — Le remplissage PKCS1v15 renvoie 401. Doit utiliser PSS avec SHA256.
  • Supprimez les chaînes de requête avant de signer — la signature est calculée sur le chemin nu uniquement (par exemple /trade-api/v2/portfolio/balance), pas sur /trade-api/v2/portfolio/balance?param=valeur. L'inclusion de la chaîne de requête entraînera une erreur 401.
  • Format de la variable d'environnement pour la clé — KALSHI_PRIVATE_KEY accepte : le corps base64 brut, le PEM complet avec des sauts de ligne réels, ou le PEM complet avec des sauts de ligne réduits à des espaces blancs (courant lors du collage via des formulaires Web). Le helper normalise automatiquement tous les formats. Pour le stockage le plus robuste, enregistrez-le sous forme de PEM multi-lignes entre guillemets doubles avec des échappements \n dans .env pour que python-dotenv le réhydrate en une chaîne PEM réelle.

Spécification de l'API

Spécification OpenAPI complète : https://docs.kalshi.com/openapi.yaml

Routage des intentions

Faites correspondre l'intention de l'utilisateur au bon point de terminaison. Tous les chemins sont relatifs à l'URL de base.

Événements

MéthodePoint de terminaisonParamètres principauxDescription
GET/eventslimit (1-200), cursor, status, series_ticker, with_nested_marketsLister les événements (exclut multivarié)
GET/events/{event_ticker}event_ticker, with_nested_marketsObtenir un événement spécifique
GET/events/{event_ticker}/metadataevent_tickerMétadonnées de l'événement uniquement
GET/events/multivariatelimit, cursor, series_ticker, collection_ticker, with_nested_marketsLister les événements multivariés (combo)

Marchés

MéthodePoint de terminaisonParamètres principauxDescription
GET/marketslimit, cursor, status, ticker, event_ticker, series_ticker, min_close_ts, max_close_tsLister/filtrer les marchés
GET/markets/{ticker}tickerObtenir les détails d'un marché spécifique
GET/markets/{ticker}/orderbookticker, depthCarnet d'ordres actuel (offres oui + offres non)
GET/markets/orderbookstickers (tableau, max 100)Carnets d'ordres par lots
GET/markets/tradesticker, limit, cursor, min_ts, max_tsTransactions sur les marchés

Chandeliers

MéthodePoint de terminaisonParamètres principauxDescription
GET/series/{series_ticker}/markets/{ticker}/candlesticksseries_ticker, ticker, start_ts, end_ts, period_intervalChandeliers au niveau du marché
GET/series/{series_ticker}/events/{ticker}/candlesticksseries_ticker, ticker, start_ts, end_ts, period_intervalChandeliers agrégés au niveau de l'événement
GET/markets/candlesticksmarket_tickers, start_ts, end_ts, period_intervalChandeliers par lots

Valeurs period_interval : 1 (1 min), 60 (1 heure), 1440 (1 jour)

Prévisions et données en direct

MéthodePoint de terminaisonParamètres principauxDescription
GET/series/{series_ticker}/events/{ticker}/forecast_percentile_historypercentiles (0-10000), start_ts, end_ts, period_intervalHistorique des centiles de prévision
GET/live_data/milestone/{milestone_id}milestone_id, include_player_statsDonnées d'étape en direct
GET/live_data/batchmilestone_ids (tableau, max 100), include_player_statsDonnées en direct par lots
GET/live_data/game-stats/{milestone_id}milestone_idStatistiques play-by-play (football, basket-ball, football, hockey, baseball)

Séries

MéthodePoint de terminaisonParamètres principauxDescription
GET/series/{series_ticker}series_ticker, include_volumeObtenir le modèle de série
GET/seriescategory, tags, include_volume, min_updated_tsLister toutes les séries

Informations sur la bourse

MéthodePoint de terminaisonParamètres principauxDescription
GET/exchange/status—Statut actuel de la bourse
GET/exchange/schedule—Heures d'ouverture
GET/exchange/announcements—Annonces de la plateforme
GET/exchange/user_data_timestamp—Timestamp de synchronisation des données
GET/series/fee_changesseries_ticker, show_historicalHistorique des changements de frais

Recherche et découverte

MéthodePoint de terminaisonParamètres principauxDescription
GET/search/tags_by_categories—Tags organisés par catégories de séries
GET/search/filters_by_sport—Filtres organisés par sport

Ordres (Authentifié)

MéthodePoint de terminaisonParamètres principauxDescription
GET/portfolio/ordersticker, event_ticker, status, limit, cursor, subaccountLister les ordres de l'utilisateur
GET/portfolio/orders/{order_id}order_idObtenir un ordre spécifique
POST/portfolio/ordersCorps : ticker, action, side, type, count, yes_price/no_priceCréer un ordre
DELETE/portfolio/orders/{order_id}order_id, subaccountAnnuler un ordre
POST/portfolio/orders/{order_id}/amendorder_id, Corps : nouveau count/priceModifier un ordre
POST/portfolio/orders/{order_id}/decreaseorder_id, Corps : montant de la réductionDiminuer le nombre d'ordres
POST/portfolio/orders/batchedCorps : tableau d'ordresCréation par lots (la taille max évolue avec le niveau)
DELETE/portfolio/orders/batchedCorps : tableau d'IDs d'ordresAnnulation par lots
GET/portfolio/orders/queue_positionsmarket_tickers, event_ticker, subaccountToutes les positions dans la file d'attente des ordres en cours
GET/portfolio/orders/{order_id}/queue_positionorder_idPosition dans la file d'attente d'un ordre spécifique

Ordres V2 — Ordres Événement-Marché (Authentifié, Point Fixe)

MéthodePoint de terminaisonParamètres principauxDescription
POST/portfolio/events/ordersCorps : ticker d'événement, côté du marché, prix (point fixe), countCréer un ordre V2
POST/portfolio/events/orders/batchedCorps : tableau d'ordres V2Créer par lots V2
DELETE/portfolio/events/orders/{order_id}order_id, subaccountAnnuler un ordre V2
DELETE/portfolio/events/orders/batchedCorps : tableau d'IDs d'ordresAnnuler par lots V2
POST/portfolio/events/orders/{order_id}/amendorder_id, Corps : nouveau count/priceModifier un ordre V2
POST/portfolio/events/orders/{order_id}/decreaseorder_id, Corps : nouveau nombre restantDiminuer un ordre V2

Groupes d'ordres (Authentifié)

MéthodePoint de terminaisonParamètres principauxDescription
GET/portfolio/order_groupssubaccountLister tous les groupes d'ordres
POST/portfolio/order_groups/createCorps : limite de contratsCréer un groupe d'ordres
GET/portfolio/order_groups/{id}id, subaccountObtenir un groupe spécifique
DELETE/portfolio/order_groups/{id}id, subaccountSupprimer le groupe et annuler tous les ordres
PUT/portfolio/order_groups/{id}/limitid, Corps : nouvelle limiteMettre à jour la limite de contrats
PUT/portfolio/order_groups/{id}/triggerid, subaccountDéclencher le groupe (annuler tous les ordres)
PUT/portfolio/order_groups/{id}/resetid, subaccountRéinitialiser le compteur de contrats correspondant

Portefeuille (Authentifié)

MéthodePoint de terminaisonParamètres principauxDescription
GET/portfolio/balancesubaccountSolde et valeur du portefeuille (en cents)
GET/portfolio/positionscursor, limit, count_filter, ticker, event_ticker, subaccountPositions de l'utilisateur
GET/portfolio/fillsticker, order_id, min_ts, max_ts, limit, cursor, subaccountToutes les exécutions de transactions
GET/portfolio/settlementslimit, cursor, ticker, event_ticker, min_ts, max_ts, subaccountHistorique des règlements
GET/portfolio/depositslimit, cursorHistorique des dépôts
GET/portfolio/withdrawalslimit, cursorHistorique des retraits
GET/portfolio/summary/total_resting_order_value—Valeur totale des ordres en cours (suite)

...

[limité pour la traduction]

Individual skills in this repo

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

Skills associés