Kalshi Strategy Reference

This section lists every setting a Kalshi strategy accepts, what each one does when your Bot runs, and where live trading and backtests behave differently. It covers platform: kalshi (event contracts). Kalshi Perps has its own format; see Kalshi Perps.

Studio's AI writes the strategy for you as a short YAML document. You don't have to write YAML by hand, but reading it lets you check that the strategy does what you asked. Studio checks the document every time it is saved and again when you deploy, so a strategy with an invalid setting is refused before it can trade. The check can't catch everything: misspelled keys inside params and edge aliases are ignored, and it doesn't confirm that a ticker exists. See Unknown and misspelled keys.

All values in the examples in this section are illustrative. They show how the settings work, not what to trade or how much. Nothing here is a recommendation or a claim about results.

In this section

The Kalshi reference is split into these pages:

• Kalshi Market Selection: How a Kalshi strategy picks markets with ticker, event_ticker, series_ticker or query, how selection works on a rolling series, and which selector wins when more than one is set.
• Kalshi Risk and Loop Settings: Every Kalshi risk key (max_position, price_floor and price_ceiling, max_loss, max_entries_per_market, max_notional, max_portfolio_positions), what each one counts and when it resets, and the loop interval.
• Kalshi Active Window and Trading Schedule: Limit when a Kalshi strategy may trade with a one-time active_window or a recurring weekly trading_schedule: timezones, windows, daylight saving, what a schedule blocks, and rule-level schedules.
• Kalshi Example Strategies: Seven complete strategies that pass Studio's checks: a one-shot event trade, a rolling crypto series, an every-bracket sweep, a spend-capped scale-in, weekday hours, an event window and a scheduled built-in, each with the deploy limits it needs.
• Kalshi Strategies the Validator Rejects: Common Kalshi strategy mistakes Studio refuses at save time, with the exact error and how to fix each one.

This page keeps what every Kalshi strategy shares: a minimal strategy, the full parameter table, the document root keys, how built-in strategies and custom rules run on Kalshi, and units and execution, including the deployment risk limits and backtest support.

A minimal Kalshi strategy

Every Kalshi strategy has the same skeleton: a version, the platform, a strategy type, the market, risk limits, a loop interval, and either rules (custom strategies) or params (built-in strategies).

version: 1
platform: kalshi
strategy: custom
strategy_name: Minimal Kalshi example
market:
  ticker: KXMLBGAME-26OCT15NYYBOS-NYY
risk:
  max_position: 2
  price_floor: 0.05
  price_ceiling: 0.60
loop:
  interval: 30
rules:
  - name: take_profit
    when:
      all:
        - {field: yes_position_size, op: ">", value: 0}
        - {field: yes_best_bid, op: ">=", value: 0.70}
    action: sell_yes
  - name: enter_yes
    when:
      all:
        - {field: position_size, op: "==", value: 0}
        - {field: yes_best_ask, op: "<=", value: 0.40}
    action: buy_yes
    size: 1

About every 30 seconds (30 seconds after each cycle finishes), the Bot reads this one market. If it holds YES and the best YES bid is at least $0.70, it sells. If it holds nothing and YES can be bought for $0.40 or less, it buys 1 contract. The ticker is illustrative; Studio does not check that a ticker exists when it saves.

All Kalshi parameters

This is the complete list. Anything not in this table is either rejected or ignored (see Unknown and misspelled keys). Prices are dollars per contract from 0 to 1, so 0.05 means 5¢.

Document root

version

Always 1. Leaving it out fails with unsupported DSL version 0 (want 1). Write it as the plain number 1, not "1".

platform

Write kalshi. Case and surrounding spaces don't matter. platform has no default: if you leave it out the strategy is not treated as Kalshi and is refused. A Studio session belongs to one venue, so you can't move a strategy to another venue by editing this line; Studio rejects the save as a platform mismatch.

strategy

custom runs your own rules. The other five values run a built-in strategy tuned with params. Some settings only work with custom: active_window, max_loss, max_notional, derived, and the advanced rule keys. trading_schedule, max_entries_per_market and max_portfolio_positions are accepted by every Kalshi strategy type.

A custom strategy needs at least one rule and at least one exit rule (sell_yes, sell_no, sell_all or cancel_all).

strategy_name and strategy_name_origin

strategy_name is the label Studio shows for the strategy. strategy_name_origin records whether you typed the name (user), the AI generated it (generated) or it came from a curated template (curated). Other values, including the older legacy, are saved as generated. Neither changes how the Bot trades. Renaming a strategy doesn't change its behavior.

Unknown and misspelled keys

Studio is strict everywhere except inside params and edge aliases:

• An unknown top-level key is rejected, for example description: unknown top-level field.
• Unknown keys inside market, risk, loop, active_window, rules, conditions, orders, trading_schedule and derived are rejected. A typo such as max_notinal fails with risk.max_notinal: unknown risk field.
• Unknown keys inside params and each edge alias are silently ignored. A typo such as refesh: 30s saves without an error, and the setting falls back to its default.

# Rejected: top-level keys are checked, so an extra description field is refused
# error: description: unknown top-level field
version: 1
platform: kalshi
strategy: custom
description: my first strategy
market:
  ticker: KXMLBGAME-26OCT15NYYBOS-NYY
risk:
  max_position: 2
  price_ceiling: 0.60
loop:
  interval: 30
rules:
  - name: take_profit
    when:
      all:
        - {field: yes_position_size, op: ">", value: 0}
        - {field: yes_best_bid, op: ">=", value: 0.70}
    action: sell_yes
  - name: enter_yes
    when:
      all:
        - {field: position_size, op: "==", value: 0}
        - {field: yes_best_ask, op: "<=", value: 0.40}
    action: buy_yes

Whole-number settings (version, max_position, max_entries_per_market, max_portfolio_positions, interval, rule and order size) must be whole: interval: 10.9 fails with loop.interval: must be a whole number, got 10.9, while 10.0 is fine. Numbers in quotes ("30") and numbers with units (30s) are refused too.

Formatting rules

• Keep the whole strategy in one YAML document. Anything after a --- line is ignored.
• JSON also works, because JSON is valid YAML.
• Anchors and aliases (&name, *name) work anywhere, for example to reuse a condition.
• Merge keys (<<:) only work inside market, risk, loop, active_window and params.
• Indent with spaces. A tab used for indentation is a parse error.

Built-in strategies on Kalshi

Set strategy to one of five built-in strategies and tune it with params. There are no rules: the strategy decides entries, exits and sizes.

On Kalshi, built-in strategies can use trading_schedule, max_portfolio_positions and max_entries_per_market (except with spread_capture; see risk.max_entries_per_market). They can't use active_window, max_notional, max_loss or derived. A plain rules block or an edge block on a built-in strategy saves but never runs (rules that use per-fill exits or a rule-level trading_schedule are rejected instead), so don't add rules to a built-in expecting them to trade. Unknown params keys are ignored.

Every price threshold in params is a YES price in dollars, including the ones that trigger NO buys. Built-in exits sell only what the Bot holds, on the side it holds: the Bot works out its position from its own fills in this deployment, so a restart doesn't lose track of it. A redeploy or update doesn't manage positions the previous deployment bought, and a built-in doesn't enter a market while the account holds contracts there that the Bot didn't buy. Exits are reduce-only, immediate-or-cancel sells at the best bid, split to fit Max contracts per order. Entries aren't split: several built-in strategies size them above 1 contract (mean_reversion buys min(max_position, 10)). Studio pre-fills Max contracts per order from that largest entry (see deployment limits), but if you lower it, a larger entry is refused, not shrunk. An entry that hasn't filled after two loops is cancelled. The full reference, including each strategy's caveats, is on Built-in strategies.

Custom rules on Kalshi

strategy: custom runs your rules top to bottom every cycle; the first rule whose conditions are true acts, and nothing below it runs that cycle. The exception is a buy rule that matches while entries are blocked (a closed trading_schedule, active_window.end, an edge data outage, or Max daily loss): it is skipped, and the rules below it still run. Kalshi has the widest rule support of any venue:

• All 17 fields: price, spread, volume, time_to_expiry, position_size, unrealized_pnl, balance, order_count, the order book fields yes_best_bid, yes_best_ask, no_best_bid and no_best_ask, and the Kalshi-only yes_position_size, no_position_size, portfolio_position_count, paired_best_bid_sum and paired_best_ask_sum. On Kalshi, price is the best YES bid (the last trade when there's no bid), position_size, the side positions and unrealized_pnl describe this Bot's attributed holdings, and order_count reads your whole account in that market.
• All 7 actions. Buys are limit orders at the ask (clamped into your price band). sell_yes and sell_no sell the whole side immediately-or-cancel at the bid. sell_all sells both sides the same way. cancel_all cancels only this Bot's orders in that market.
• Advanced keys that only Kalshi custom strategies accept: composite orders with max_combined_price, per-fill exits (entry_profit_offset, entry_stop_loss_offset, entry_profit_targets, entry_profit_min_time_to_expiry) and rule-level trading_schedule. See Advanced Kalshi rules.
• External data: edge aliases (Coinbase, NWS weather, FOMC/CPI calendar) and derived metrics such as spot price minus strike. See Edge data.

Position fields read your account's whole position in that market. Without a schedule, sell rules act on that whole position, including contracts you bought by hand. Rule syntax, every field, and the checks Studio runs on your rule logic are on Custom rules.

Units and execution

• Prices are dollars per contract from 0 to 1 (0.05 = 5¢). The Bot sends Kalshi limit prices in whole cents, rounding a computed price to the nearest cent.
• Sizes are whole contracts. An omitted or 0 buy size means 1.
• max_notional and max_loss are dollars. max_loss includes fees.
• loop.interval is seconds. Schedule times are local HH:MM; active_window times are absolute instants.
• Orders are placed each cycle, not continuously. A custom buy is a good-till-canceled limit order at the ask. If it doesn't fill at once, it rests on the book. It goes away when it fills, when a cancel_all rule fires, when a composite orders rule re-quotes in that market, when a schedule closes, when an active window ends, when max_loss halts the deployment, or when required edge data or a derived value is unavailable. When any rule has its own trading_schedule, entry orders also expire at the next schedule change.
• Every order passes fixed Kalshi checks first. The market must be open with a close time in the future, and its most recent trade, by anyone, must be at most 120 seconds old. A market that has never traded passes. This applies to sells too, so on a quiet market a stop-loss or take-profit can be refused until a fresh trade prints. A buy also needs a two-sided, uncrossed book, and a custom sell needs a bid on the side it sells. You can't change these checks.
• Missing book values. Order book fields, and the paired sums built from them, read as unavailable when a side is empty. A condition that reads an unavailable value, as its field or its value_field, is false whatever the operator, including !=, live and in backtests. See Unavailable values.
• Order budget and backoff. One Bot sends at most 20 orders per rolling 60 seconds, shared across all its markets. Each composite leg counts; cancels don't. Orders beyond that are skipped, not refused. After Kalshi answers with a rate-limit error, new orders are skipped for the wait Kalshi asks for, or 5 minutes if it doesn't say. Keep this in mind with selection: all on a series with many brackets.

Deployment risk limits

When you deploy, you confirm a set of risk limits in the deploy dialog. They aren't part of the YAML, but every order must pass them as well as the strategy's own checks. An order that breaks a limit is refused, not shrunk.

The largest single order is the biggest buy size across your rules (an omitted size counts as 1) or composite orders leg. For built-in strategies it is min(max_position, 10) for mean_reversion, max_position for observation_momentum, min(max_position, 5) for pre_announcement_drift, fade_size for panic_fade and 1 for spread_capture. Exits the Bot splits (below) don't count.

• Max contracts per order is checked on every order, sells included. Custom exits, per-fill exits and max_loss liquidations are split into orders of at most min(40, Max contracts per order) contracts. Built-in strategy orders are not split, which is why their pre-fill covers their largest order.
• Max open contracts counts held plus resting contracts in that market, from any source. The Bot applies the lower of this and max_position.
• Max daily loss watches this deployment's P&L since 00:00 UTC: the realized P&L of today's fills, after fees, plus the unrealized P&L of everything the deployment still holds, valued at the bid against its entry price. A position opened before today counts its whole open loss; a market that settled counts at $1 or $0 on the day it closed; a held side with no bid counts at $0. Only this deployment's own fills and the positions you adopt at deploy count, not manual trades. Once the loss reaches the limit, buys are refused until 00:00 UTC (reason max_daily_loss). A buy rule that matches meanwhile is skipped and the rules below it, exits included, still run. Sells are never blocked by this limit. The stop persists even if P&L recovers, the process restarts, or the limit is raised or disabled within the same deployment run. At 00:00 UTC it resets only after the new day's state is saved; ongoing unrealized losses can immediately trip the new day's limit. Updating or redeploying the Bot starts a new deployment, whose count starts at $0: the positions you adopt count from their value at deploy, and the earlier deployment's losses today don't carry over. The limit never sells anything by itself.
• Max daily notional counts traded notional in that market since 00:00 UTC, including fills this Bot didn't make, and checks buys only. A restart doesn't reset it.
• Exits, custom and built-in, and max_loss liquidations are split into orders of at most min(40, Max contracts per order) contracts. Built-in entries are not split, so a built-in that sizes entries from max_position needs a Max contracts per order at least that large.
• API error limit and Error window minutes: once the Bot hits that many Kalshi API errors inside the window, it refuses new orders until one more window has passed, then resumes by itself. Reduce-only exits (custom-rule and built-in sells, per-fill exits and max_loss liquidations) keep going.
• For an already deployed Bot, the dialog starts from its verified current limits. If those settings are unknown, review the suggested limits before confirming an update.

The daily-loss stop is saved on the runner's filesystem. Missing or corrupt state, or an interrupted P&L check, pauses new entries for the rest of the UTC day while exits remain allowed. If the state can't be saved, entries pause without a promised reset time. Keeping the state requires retaining that filesystem; it isn't a remote backup. Existing Bots need a strategy update or redeploy to receive this compiled check; upgrading the runner alone doesn't add it to previously compiled code.

Note: Max daily loss pauses entries for the rest of the day. risk.max_loss is the loss halt for a whole deployment: it sells the deployment's inventory and never trades that deployment again.

See Risk & Limits for the wider picture and Monitoring for watching a live Bot.

Backtesting and Deep Research

Kalshi strategies can be backtested (see Backtest and Data sources), with these exceptions and differences:

Backtests don't read your real account, and fills are simulated. Treat a backtest as a way to find problems, not as a forecast.

Kalshi backtest fees include trade fees and cent-alignment rounding. For partial fills of one order, rounding overpayment accumulates across fills. Each fill's rounding rebate is capped at that fill's trade and rounding fees, so its modeled net fee cannot be negative. Any unapplied overpayment stays on the same order for a later fill that can cover the rebate; it is not credited immediately. These are simulated fees, not a promise of a live rebate or fill.

Deep Research is Kalshi-only and covers crypto and weather markets. It runs many backtest variants of your strategy, re-checking every variant as a normal save would. Anything that blocks a backtest (such as query or active_window) also blocks research.