kalshi-ai-trading-bot: A Python Toolkit for Kalshi Prediction Market Strategies
A toolkit for building AI-automated trading strategies on Kalshi prediction markets.
At a glance
- What is it?
- Ryan Frigo's MIT-licensed repo gives you a signed Kalshi client, SQLite telemetry, a Streamlit dashboard, and three example strategies. It is a scaffolding project, not a turnkey bot, and the README says so before you risk money.
- Who is it for?
- Adopt it if you are a Python developer who already understands Kalshi's order book and wants a signed client, ingestion job, position tracker, and SQLite telemetry to build on. Do not adopt it if you want a bot that makes money out of the box: the README states the examples lose money on certain markets and that Beast Mode led to significant losses historically.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 71 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap this repo fills between Kalshi's API and a working strategy
Kalshi exposes a REST and WebSocket API that requires RSA request signing. Before you can test any idea about mispriced contracts, you have to write that signing layer, handle retries and rate limits, persist a market universe, and track positions. That plumbing is the same regardless of whether your strategy is an LLM scoring headlines or a fixed edge threshold on the NO side. This repo packages that plumbing so the strategy is the only part you write.
The intended user is a Python developer who already trades or follows prediction markets and wants to automate a hypothesis. It is not aimed at someone looking for a hands-off income stream. The README opens with a warning block: no strategy in the repo is guaranteed to make money, the examples lose money on certain markets, and the project is described as a toolkit rather than a turnkey bot. That framing is unusually direct and it sets the correct expectation.
What the components actually do, from signing to settlement
The architecture is a set of jobs and clients under src/, with a CLI as the entry point. The Kalshi client at src/clients/kalshi_client.py handles authenticated REST plus WebSocket, RSA signing, retries, and rate-limit handling. Market ingestion in src/jobs/ingest.py pulls the full tradeable universe through the Events API and persists it to SQLite. Position tracking in src/jobs/track.py manages stop-loss, take-profit, time-based, and resolution-based exits, and it sends real sell orders to Kalshi when it fires.
The LLM layer is a single OpenRouter client in src/clients/openrouter_client.py. According to the README, one API key covers any model on OpenRouter, swapping models is a one-line config change, a fallback chain triggers on errors, and a daily cost tracker persists spend. There is also an xai_client.py. Telemetry lands in SQLite through src/utils/database.py: trades, AI decisions, and cost metrics. beast_mode_dashboard.py is a Streamlit app reading that data. paper_trader.py logs signals against settled markets without sending orders.
The README is explicit about what is not finished. Multi-agent debate runners live in src/agents/ and a sentiment analyzer in src/data/, but these are described as scaffolding that is not fully wired. The AI Directional strategy is not a five-model ensemble despite earlier README claims; one model is called per decision, and the fallback chain only fires on errors. Real parallel multi-model voting would require forking src/jobs/decide.py.
Getting it running: setup_env.py, .env, and the three strategy flags
Setup is four steps. Clone the repo, run python setup_env.py to create .venv and install dependencies, copy env.template to .env and fill in KALSHI_API_KEY and OPENROUTER_API_KEY, then run python cli.py health to verify connectivity. The dashboard starts separately with python cli.py dashboard.
The three example strategies are selected by flag. python cli.py run --paper runs the AI Directional strategy in paper mode; python cli.py run --live sends real orders. python cli.py run --safe-compounder is the edge-based NO-side strategy with no LLM involved, and it takes --live, --loop, and --interval 300. python cli.py run --beast enables aggressive settings with no category guardrails. The CLI also exposes status, scores, history, and close-all.
Defaults for the AI strategy are listed in the README and configurable in src/config/settings.py: 15% max drawdown, 45% minimum confidence, 3% max position size, 30% max sector concentration, and quarter-Kelly sizing. The Safe Compounder has its own rule set: NO side only, YES last at or below 20 cents, NO ask above 80 cents, edge above 5 cents, maximum 10% per position, and it skips sports, entertainment, and mention markets. Python 3.12 or newer is required.
Shutdown, liquidation, and the state that outlives your process
Ctrl-C sends SIGINT, which the README says triggers graceful shutdown: the bot finishes the in-flight cycle, logs, and exits. Open positions stay on Kalshi until they resolve. That is a meaningful operational detail. Killing the process does not flatten your book.
To flatten it, the documented sequence is Ctrl-C, then python cli.py close-all for a dry-run preview, then python cli.py close-all --live to place limit sells at the current best bid for every open position, then python cli.py status to verify. The README notes that close-all queries Kalshi directly rather than the local database. That distinction matters because SQLite telemetry can drift from exchange state if a write fails or a process is killed mid-cycle, and the close-all path avoids acting on a stale local view.
Where the toolkit stops being the right tool
The most concrete limitation is the one the authors state themselves: Beast Mode is not recommended for live trading, and running it with real money historically led to significant losses on this repo. That is a documented failure mode, not a hypothetical. A second limitation is the ensemble gap. If your thesis depends on aggregating multiple model opinions, the code in src/agents/ will not do it today; you would be forking src/jobs/decide.py to build the voting logic yourself.
There is also a structural constraint worth naming. The Safe Compounder places resting maker orders one cent below the ask. Maker orders do not guarantee fills, so a strategy that looks profitable on historical edge calculations can sit unfilled while the market moves past it. The README does not describe fill-rate tracking or order-cancellation logic for stale resting orders, and I cannot confirm from the supplied material whether either exists. If your strategy depends on maker fills, that is the first thing to inspect in the source.
Finally, the repo has no published releases, so there is no versioned artifact to pin. You are tracking main. For a system that sends real orders, that means your dependency is a moving branch.
How this differs from a general-purpose trading framework
A framework like Freqtrade or Hummingbot targets exchange-traded crypto pairs with continuous order books and unified CCXT-style abstractions. Kalshi is a different instrument: binary contracts on discrete real-world events, with settlement on resolution rather than a mark price. A crypto bot framework would give you backtesting engines, hyperparameter optimization, and a strategy marketplace, but you would still write the Kalshi signing layer, the Events API ingestion, and resolution-based exit logic from scratch.
This repo makes the opposite trade. It is narrow: one venue, one asset class, Python 3.12+, SQLite for state, Streamlit for the UI. In exchange, the parts that are Kalshi-specific are already written, including resolution-based exits and the close-all liquidation path that queries the exchange directly. If you intend to trade both crypto and prediction markets, you would end up running two systems. If Kalshi is the whole scope, the narrower tool removes more work.
Licence, maintenance, and what to check before committing capital
The project is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. That is permissive enough for internal trading use. It is not legal advice; if you redistribute the code or run it on behalf of others, read the LICENSE file and the Kalshi API terms yourself, since exchange rules on automated trading are separate from the software licence.
Maintenance cost is real. There are no releases, so upgrades mean pulling main and reconciling your forks of src/jobs/decide.py or the strategies against upstream changes. The README's own warning that what worked last quarter may not work this quarter applies to the code as much as the markets. Before you point it at a funded account, run python cli.py health, run the AI strategy with --paper, and read src/jobs/track.py to confirm the exit conditions match your risk tolerance. Then confirm for yourself that src/agents/ is still unwired, because if you are relying on ensemble behaviour and it is scaffolding, the strategy you think you are running is not the strategy you are running.
Editorial conclusion
Adopt it if you are a Python developer who already understands Kalshi's order book and wants a signed client, ingestion job, position tracker, and SQLite telemetry to build on. Do not adopt it if you want a bot that makes money out of the box: the README states the examples lose money on certain markets and that Beast Mode led to significant losses historically. Before going live, verify that the multi-agent code in src/agents/ is still unwired from the trading path, and run python cli.py health against your own Kalshi key.
Community notes