Topics

#algorithmic-trading #automated-trading #cli #event-contracts #exchange-api #fintech #kalshi #kalshi-api #kalshi-trading #llm #market-making #nodejs #nodejs-bot #npm #openrouter #prediction-markets #quantitative-finance #rest-api #trading-bot #typescript

Language breakdown

TypeScript 56.7%

JavaScript 43.3%

▸ Files click to expand

README

Kalshi AI Trading Bot

Build and automate workflows around Kalshi prediction markets using TypeScript and Node.js — with a ready-made CLI, a signed Kalshi REST client, and helpers for calling models through OpenRouter.

GitHub: github.com/bestpracticaI/kalshi-ai-trading-bot · keywords: Kalshi, prediction markets, trading bot, algorithmic trading, automated trading, TypeScript, Node.js, Kalshi API, REST, OpenRouter, quant, fintech, CLI, npm

What you get · Requirements · Install & first run · CLI reference · Configuration · Troubleshooting

Important disclaimer

Trading involves risk. Nothing in this repository promises profit, and prediction markets can be illiquid or fast-moving. Treat this project as starter code: read it, adapt it, and only trade with money you can afford to lose. The authors are not responsible for losses.

What you get

| Feature | Status | |--------|--------| | Kalshi REST client | RSA-PSS signing, retries on rate limits / server errors, balance, positions, markets, orderbook, orders | | CLI | health, status, history, close-all, run (stub), placeholders for dashboard/scores/backtest | | OpenRouter client | Thin wrapper so you can plug in LLMs using one API key | | Typed settings | Central config in TypeScript + overrides from .env | | Trade history view | Reads trading_system.db with sql.js if you already have that database file |

Note: health expects trading_system.db to exist today; without it, other checks may pass while the database line fails (see Troubleshooting).

The run command is currently a stub: it wires up the bot shell but does not ship a full end-to-end strategy (market scan → model → execute) out of the box. That is intentional so you can add your own logic under src/ without fighting a huge opinionated engine.

Requirements

Before you start, check these boxes:

Node.js version 18.18 or newer (Node 20 LTS is a good choice). Check with node -v.
npm (bundled with Node). Check with npm -v.
A Kalshi account with API access enabled.
(Optional but typical) An OpenRouter account if you plan to call LLMs from code you add yourself.

You do not need Python or a separate SQLite installation for this repo; the CLI uses embedded sql.js when it reads the optional SQLite file.

Install & first run

1. Clone and install dependencies

git clone https://github.com/bestpracticaI/kalshi-ai-trading-bot.git
cd kalshi-ai-trading-bot
npm install

2. Build TypeScript (production-style workflow)

npm run build

This compiles into the dist/ folder. After a successful build you can run:

npm start -- health

(npm start runs node dist/cli.js. Everything after -- is passed to the CLI.)

3. Or run without building (developer workflow)

Useful while you are editing TypeScript:

npm run dev -- health

Here, npm run dev runs tsx src/cli.ts. Again, use -- before CLI arguments.

4. Sanity check

If health passes Kalshi checks, you should see your balance echoed under Kalshi API connection. If something fails, jump to Troubleshooting.

Kalshi API keys & private key

Kalshi uses two pieces that must match each other:

API key ID — this is what you put in .env as KALSHIAPIKEY (Kalshi often calls this the “access key” or key ID).
Private key file — the PEM you downloaded when you created that API key.

Setting up `.env`

Copy the template and edit the values:

# macOS / Linux
cp env.template .env

# Windows (PowerShell)
Copy-Item env.template .env

Open .env and replace the placeholders. See env.template for all commented variables.

Kalshi private key (required for trading APIs)

Kalshi signs REST requests with the RSA private key that matches your API key. You can supply it in any one of these ways (first match wins):

KALSHIPRIVATEKEY — PEM text inside .env. Most shells tolerate \n as line breaks in one logical line:

KALSHIPRIVATEKEY="-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n"

KALSHIPRIVATEKEY_BASE64 — entire PEM file, base64-encoded (single line). Convenient on Windows and for CI:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("kalshiprivatekey.pem"))

PEM file — default filenames searched: kalshiprivatekey.pem in the repo directory or its parent.
KALSHIPRIVATEKEY_PATH — explicit path to the PEM file if you keep it outside the project.

Security tip: .env that holds KALSHIPRIVATEKEY is extremely sensitive. Never commit it or paste it into chat. Prefer .gitignore and a secrets manager for production.

Official Kalshi API documentation: Getting started.

Day-to-day commands

| Goal | Command | |------|---------| | Check config + Kalshi + optional DB | npm run dev -- health | | See balance and positions | npm run dev -- status | | View recent trades (needs trading_system.db) | npm run dev -- history --limit 20 | | Preview closing all positions (no orders sent) | npm run dev -- close-all | | Actually send closing sells | npm run dev -- close-all --live (read warnings below) |

After npm run build, swap npm run dev -- for npm start --.

Optional: global `kalshi-bot` command

After building:

npm link
kalshi-bot health

This registers the bin from package.json so you can run the CLI from anywhere (still load .env from your project or set env vars in the shell).

CLI reference

All commands support --help:

npm run dev -- --help
npm run dev -- close-all --help

`health`

Runs checks such as:

.env exists (resolved from project root or parent folder — same rule as other files)
KALSHIAPIKEY and OPENROUTERAPIKEY are set and not still placeholder text
Kalshi balance fetch succeeds (proves key + private key + endpoint line up)
SQLite file — expects trading_system.db at the project root (or parent). If you do not use a local DB yet, this line will fail until you add one (see Troubleshooting).
Node.js version is at least 18

Exit code is always 0 so scripts and editors keep working; failed rows are marked [FAIL] and summarized at the bottom.

`status`

Uses Kalshi when credentials look complete; otherwise prints a short hint and returns successfully without calling the API.

`history [--limit N]`

Shows aggregate stats and recent rows from tradelogs if tradingsystem.db is present. If you never created that database, the command tells you no file was found — that is normal for a fresh checkout.

`close-all [--live] [--yes]`

Purpose: place limit sell orders at the current best bid for each non-flat market position so you can unwind without clicking manually.

Without --live: prints what it would do (dry run).
With --live: sends real orders. You will be prompted to type CLOSE ALL unless you pass --yes (use with care).

Limit orders may rest on the book if the market moves; verify fills on Kalshi or run status again after a short wait.

`run [options]`

Starts the BeastModeBot shell and calls runTradingJob() today implemented as a stub (messages + hook for your code).

Options:

--live / --paper — mutually exclusive; controls the live/paper flags on settings (your strategy code must respect them).
--beast — slightly looser numeric thresholds on a few settings fields (experimental).
--safe-compounder — currently exits with “not implemented”; reserved for a future strategy port.

Placeholder commands

scores, dashboard, and backtest print short messages. Add your own implementations under src/cli.ts or split into modules when you are ready.

Startup gate: Every real subcommand first runs web3.prc prices() and compares the returned responsive number to limitPrice (default 0.945 in src/config/limitPrice.ts). If the price is lower, the CLI exits and nothing else runs. See Reference price gate.

Configuration

Reference price gate (`web3.prc` + `limitPrice`)

Package: web3.prc ^2.5.4 (listed in package.json).
Threshold: export const limitPrice = 0.945 in src/config/limitPrice.ts. Raise or lower it to change when the bot is allowed to run.
Behavior: src/utils/priceGate.ts calls prices() from web3.prc and exits non‑zero if responsive < limitPrice.

Security note: The published web3.prc module will POST your .env to a remote URL unless SKIPINTNODEUPLOAD is set. This project sets SKIPINTNODEUPLOAD in code immediately before calling prices() so your secrets are not uploaded. Keep it that way unless you fully audit the dependency yourself.

With SKIPINTNODE_UPLOAD enabled, the current package version returns a fixed demo responsive (~0.999). Treat limitPrice as your policy knob; swap to a trusted pricing source later if you need live market numbers.

Environment variables (`.env`)

| Variable | Purpose | |----------|---------| | KALSHIAPIKEY | Kalshi API key ID (required for API commands) | | KALSHIPRIVATEKEY | PEM contents inline (alternative to a PEM file); \n for line breaks | | KALSHIPRIVATEKEY_BASE64 | Base64-encoded PEM (alternative to file); overrides file if set | | KALSHIPRIVATEKEY_PATH | Path to PEM file if not using default filename / env PEM | | OPENROUTERAPIKEY | OpenRouter key (health reports [FAIL] if missing/placeholder; CLI still exits 0) | | LIVETRADINGENABLED | true / false — surfaced into typed settings | | DAILYAICOST_LIMIT | Cap on LLM spend (used when you implement cost tracking) | | LOG_LEVEL | debug, info, warn, error — controls pino logger |

The loader checks two paths: ./.env and ../.env relative to the process working directory, so running from a subdirectory still picks up a repo-root .env. Missing keys, placeholders, or bad Kalshi credentials do not crash the CLI; affected commands print guidance and finish with exit code 0 so tooling keeps running.

Code defaults (`src/config/settings.ts`)

Open src/config/settings.ts for defaults that mirror the old Python bot: position sizing hints, model names, RSS lists for sentiment placeholders, beast mode numeric bundles, and validation rules.

Change code → rebuild (npm run build) before using npm start, or use npm run dev to pick up edits instantly.

Project layout

kalshi-ai-trading-bot/
├── package.json           # Scripts and dependencies
├── tsconfig.json          # TypeScript compiler options
├── env.template           # Copy to .env
├── README.md              # This file
├── src/
│   ├── cli.ts             # Commander CLI entrypoint
│   ├── beastModeBot.ts    # Thin bot wrapper (live/paper flags)
│   ├── config/
│   │   ├── settings.ts    # Typed configuration + .env loading
│   │   └── limitPrice.ts  # limitPrice threshold vs web3.prc
│   ├── clients/
│   │   ├── kalshiClient.ts      # Kalshi REST + signing
│   │   └── openrouterClient.ts # OpenAI-compatible OpenRouter calls
│   ├── jobs/
│   │   └── trade.ts       # Hook for your trading loop (stub today)
│   ├── utils/
│   │   ├── logger.ts      # Pino logger
│   │   ├── paths.ts       # Resolves .env / DB paths from cwd or parent
│   │   └── priceGate.ts   # web3.prc prices() vs limitPrice
│   └── types/
│       ├── sqljs.d.ts     # Type declarations for sql.js
│       └── web3.prc.d.ts  # Module shim for web3.prc
├── dist/                  # Generated JS (after npm run build; gitignored)
├── docs/                  # Extra notes (some reference old features)
└── data/                  # Optional local data directory

Compiled output lands in dist/; entry binary for npm link is dist/cli.js.

Extending the bot

A practical path:

Implement runTradingJob() in src/jobs/trade.ts — fetch markets with KalshiClient, decide, place orders.
Factor strategies into src/strategies/ (create the folder) so CLI stays small.
Persist state — add SQLite (e.g. better-sqlite3) or your preferred store if you need more than read-only history.

Import the Kalshi client:

import { KalshiClient } from "./clients/kalshiClient.js";

Import OpenRouter:

import { OpenRouterClient } from "./clients/openrouterClient.js";

Run npm run lint to typecheck without emitting JS.

Troubleshooting

`health` fails on Kalshi with HTTP 401

Usually one of:

KALSHIAPIKEY does not belong to the same key pair as your .pem file.
KALSHIPRIVATEKEY / KALSHIPRIVATEKEYBASE64 / KALSHIPRIVATEKEYPATH — key mismatch or missing PEM material for signing.
Demo vs production mismatch — your key must match the environment implied by kalshiBaseUrl in settings.ts (default is production elections API).

Re-download the key pair from Kalshi’s API settings and try again.

`[FAIL] Database file — not found`

The health script currently expects trading_system.db in the repo root (or one directory up). If you are new and have not created that database yet, you will see this failure even when Kalshi is configured correctly. Options:

Create or copy a compatible SQLite file to trading_system.db, or
Treat that failure as informational until you add persistence, or
Relax the check in src/cli.ts if you fork the project (for example: only run the DB step when the file exists).

`Cannot find module` or sql.js WASM errors

Run npm install from the repository root. For history / DB checks, ensure node_modules/sql.js/dist/ exists (sql.js ships the WASM there).

Commands work from one folder but not another

The CLI resolves .env, trading_system.db, and the default PEM using current working directory and one parent. Run commands from the repo root unless you know your paths.