Skip to main content

​
Overview

The Simple Kalshi Bot is configured using environment variables stored in a .env file. This guide covers all available configuration options for both paper trading (bot.py) and real trading (consensus.py).

​
Environment File Setup

Create a .env file in your project root by copying the example: 
cp .env.example .env
Then edit .env with your configuration values.

​
Core Configuration

​
Kalshi API Credentials

​
KALSHI_API_KEY_ID
string
required
Your Kalshi API key ID. Create this in your Kalshi account profile under API Keys.Required for: Real trading with consensus.pyExample: KALSHI_API_KEY_ID=your-api-key-id
​
KALSHI_PRIVATE_KEY_PATH
string
required
Path to your RSA private key file for API authentication.Required for: Real trading with consensus.pyDefault: ~/.key/kalshi/keyExample: KALSHI_PRIVATE_KEY_PATH=~/.key/kalshi/key
​
KALSHI_USE_DEMO
boolean
default:"true"
Whether to use the Kalshi demo API or production API.Example: KALSHI_USE_DEMO=true
Always start with KALSHI_USE_DEMO=true to test your configuration without risking real funds.

​
Trading Safety

​
DRY_RUN
boolean
default:"true"
Simulate trades without executing real orders.
  • true - Simulate orders (recommended for testing)
  • false - Execute real orders
Example: DRY_RUN=true
Keep DRY_RUN=true until you have fully tested your configuration. Only set to false when ready for live trading.

​
Trading Parameters

​
Position Sizing

​
STAKE_USD
number
default:"5"
Amount in USD to stake per trade for paper trading strategies.Used by: bot.py for PREVIOUS, MOMENTUM, and other paper trading strategiesExample: STAKE_USD=5
​
INITIAL_BANKROLL_USD
number
default:"500"
Initial bankroll for CONSENSUS strategy risk management.Used by: bot.py for calculating position sizes based on risk percentageExample: INITIAL_BANKROLL_USD=500

​
Market Selection

​
KALSHI_EVENT_TICKER_PREFIX
string
default:"KXBTC15M"
Market series to watch and trade.Example: KALSHI_EVENT_TICKER_PREFIX=KXBTC15MPopular options:
  • KXBTC15M - Bitcoin 15-minute price markets
  • KXETH15M - Ethereum 15-minute price markets

​
Timing

​
POLL_SECONDS
number
default:"5"
How often to check for new markets and price updates (in seconds).Example: POLL_SECONDS=5
​
MOMENTUM_WINDOW_SECONDS
number
default:"60"
Lookback window for BTC momentum strategy (in seconds).The bot compares current BTC price to the price from this many seconds ago to determine momentum direction.Example: MOMENTUM_WINDOW_SECONDS=60

​
CONSENSUS Strategy Risk Controls

These parameters control risk management for the CONSENSUS and CONSENSUS_2 strategies:
​
CONSENSUS_RISK_PCT
number
default:"0.01"
Target risk per trade as a percentage of bankroll.Example: CONSENSUS_RISK_PCT=0.01 (risk 1% of bankroll per trade)
​
CONSENSUS_MAX_RISK_PCT
number
default:"0.02"
Maximum risk per trade as a percentage of bankroll.Example: CONSENSUS_MAX_RISK_PCT=0.02 (max 2% of bankroll per trade)
​
CONSENSUS_MAX_PRICE
number
default:"0.55"
Maximum price to pay for a contract (0.00-1.00).Higher prices mean less edge. Only trades when ask price is below this threshold.Example: CONSENSUS_MAX_PRICE=0.55 (skip trades above $0.55)
​
CONSENSUS_FEE_PCT
number
default:"0.0"
Trading fee percentage to account for in P&L calculations.Example: CONSENSUS_FEE_PCT=0.0 (0% fees)
​
CONSENSUS_ROLLING_WINDOW
number
default:"30"
Number of recent trades to use for rolling performance metrics.The bot calculates win rate over the last N trades to ensure the strategy is still performing above break-even.Example: CONSENSUS_ROLLING_WINDOW=30

​
Loss Caps

​
CONSENSUS_DAILY_LOSS_CAP_R
number
default:"3"
Daily loss cap in R-multiples (where R = CONSENSUS_RISK_PCT × bankroll).Trading stops for the day if daily losses exceed this threshold.Example: CONSENSUS_DAILY_LOSS_CAP_R=3 (stop after losing 3R in one day)
​
CONSENSUS_WEEKLY_LOSS_CAP_R
number
default:"8"
Weekly loss cap in R-multiples.Trading stops for the week if weekly losses exceed this threshold.Example: CONSENSUS_WEEKLY_LOSS_CAP_R=8 (stop after losing 8R in one week)

​
Output Configuration

​
MOCK_TRADES_CSV_PATH
string
default:"data/mock_trades.csv"
CSV file path for paper trading results from bot.py.Example: MOCK_TRADES_CSV_PATH=data/mock_trades.csv
​
CONSENSUS_TRADES_CSV
string
default:"data/consensus_trades.csv"
CSV file path for real trading results from consensus.py.Example: CONSENSUS_TRADES_CSV=data/consensus_trades.csv

​
Example Configurations

​
Conservative Paper Trading

# Safe testing configuration
KALSHI_USE_DEMO=true
DRY_RUN=true
STAKE_USD=2
INITIAL_BANKROLL_USD=200
CONSENSUS_RISK_PCT=0.005
CONSENSUS_MAX_RISK_PCT=0.01
CONSENSUS_MAX_PRICE=0.50

​
Aggressive Real Trading

# Live trading with higher risk
KALSHI_API_KEY_ID=your-key-id
KALSHI_PRIVATE_KEY_PATH=~/.key/kalshi/key
KALSHI_USE_DEMO=false
DRY_RUN=false
STAKE_USD=10
INITIAL_BANKROLL_USD=1000
CONSENSUS_RISK_PCT=0.02
CONSENSUS_MAX_RISK_PCT=0.05
CONSENSUS_MAX_PRICE=0.60
Only use aggressive configurations after extensive testing in demo mode. Start with conservative settings and scale up gradually.

​
Validation

Before running the bot, verify your configuration:
1

Check API credentials

Ensure KALSHI_API_KEY_ID and KALSHI_PRIVATE_KEY_PATH are set correctly for real trading.
2

Verify safety settings

Confirm DRY_RUN=true and KALSHI_USE_DEMO=true for initial testing.
3

Review risk parameters

Calculate maximum position size: INITIAL_BANKROLL_USD × CONSENSUS_MAX_RISK_PCT
4

Test connectivity

Run the bot briefly to verify API connection and market data retrieval.

​
Next Steps

Running the Bot

Learn how to run paper and real trading modes

Analyzing Results

Understand trading performance metrics

Build docs developers (and LLMs) love

Get started for freeTalk to us