Advanced Kalshi Rules

Kalshi custom strategies can extend a rule in three ways. Composite orders rest limit buys priced from the live order book. Per-fill exits manage each purchase at its own price. Rule-level schedules give one entry rule its own trading hours. This section covers every key, how it behaves live, in paper trading and in backtests, and the combinations the validator refuses.

The section is split into the pages listed under In this section: one page per feature, plus a page of complete example strategies. This page covers what applies to all three features: where the keys work and which ones can be combined, rule order, save-time and deploy checks, validator messages, and how each feature runs in paper trading and backtests.

Everything here builds on the rule model in Custom Rules: every loop, rules run top to bottom and the first rule that matches acts.

Note: The examples use small, illustrative sizes, prices and thresholds to show how each key works. They are not recommendations, and nothing in this section suggests a strategy will make money. Backtest and paper trade any strategy before you deploy it live, and keep first deployments small.

In this section

• Composite Orders and max_combined_price: Composite orders that rest one or two limit buys priced from the live book: how legs are priced and sized, what one firing does, keeping a quote in the queue, the max_combined_price cap for paired YES/NO quotes, and Deep Research sweeps for paired quotes.
• Per-Fill Profit Targets and Stops: Per-fill exits on sell_yes/sell_no rules: how fills become lots, entry_profit_offset, entry_stop_loss_offset, entry_profit_targets tables, entry_profit_min_time_to_expiry, and when the Bot blocks trading because it can't trust its lots.
• Rule-Level Trading Schedules: A trading_schedule on individual buy_yes/buy_no rules for time-varying entry thresholds: how it combines with the top-level schedule, orders at window edges, overnight and overlapping windows, and format rules.
• Advanced Kalshi Rule Examples: Complete strategies that pass Studio's save checks: a paired YES/NO quote with a combined cap, a NO bid under the ask, per-fill targets and stops, an entry-price profit table, time-varying entry thresholds and one target table for YES and NO fills. The last example shows a combination the validator rejects.

Overview

All of them need platform: kalshi and strategy: custom.

Where these keys don't work

• Custom Polymarket and Polymarket US strategies reject them when you save.
• Built-in strategies such as spread_capture reject per-fill exits and rule-level schedules. A Polymarket US built-in rejects any rules block, so composite orders fail at save there too. Kalshi and Polymarket built-ins don't check orders or max_combined_price, but those keys never trade live on a built-in strategy. Leave them out: a stray orders block still changes the backtest (a Kalshi backtest switches to the maker replay, and a Polymarket backtest fails).
• Kalshi Perps and Arbitrage strategies ignore these keys without an error. Perps has its own exits; see Kalshi Perps.

What can be combined

Advanced strategies come in two shapes that don't mix. A quoting strategy rests composite orders and exits whole positions with sell_all, pulling quotes with cancel_all. A taking strategy enters with buy_yes/buy_no, and can add per-fill exits and rule-level schedules. The validator enforces the split:

Rule order and requirements

First match wins, so the order of rules decides what happens when several could act. A reliable order, top to bottom:

1. Safety exits. Whole-position sell_all or cancel_all rules for conditions where you want out regardless, such as close to expiry or around a scheduled announcement.
2. Per-fill stops. entry_stop_loss_offset rules.
3. Per-fill profit targets. entry_profit_offset and entry_profit_targets rules.
4. Entries. buy_yes/buy_no rules, with or without their own schedules, or a composite quote rule.
5. Fallback cancel. A cancel_all that clears resting orders once the entry conditions stop holding.

Exits sit above entries so an exit always wins over new risk in the same loop. Per-fill rules fall through when no lot qualifies (how a per-fill rule matches), so they don't block the entries below them. A scheduled entry falls through when its window is closed (how the two schedules combine).

rules:
  - name: exit_all_near_close
    when:
      all:
        - {field: position_size, op: ">", value: 0}
        - {field: time_to_expiry, op: "<=", value: "10m"}
    action: sell_all
  - name: stop_each_fill
    when:
      all:
        - {field: yes_position_size, op: ">", value: 0}
    action: sell_yes
    entry_stop_loss_offset: 0.10
  - name: take_profit_each_fill
    when:
      all:
        - {field: yes_position_size, op: ">", value: 0}
    action: sell_yes
    entry_profit_offset: 0.05
  - name: enter_yes
    when:
      all:
        - {field: order_count, op: "==", value: 0}
        - {field: yes_best_ask, op: "<=", value: 0.45}
        - {field: yes_position_size, op: "<", value: 3}
    action: buy_yes
    size: 1
  - name: cancel_unfilled_entry
    when:
      all:
        - {field: order_count, op: ">", value: 0}
    action: cancel_all

Two limits on the fallback. First, a composite rule that stops with an error skips the rest of that market's rules for the loop, fallback included. Errors include a missing book side, a post-only cross, a leg Kalshi rejects, and a leg refused by a deployment risk limit or your buying power; see What one firing does. Second, a matched sell_all doesn't cancel resting orders, so pair it with a cancel_all where needed.

Save-time behavior checks

Studio's behavior checks treat advanced rules differently:

• A buy_yes or buy_no rule with its own trading_schedule is exempt from "entry predicate is exhaustive". An entry whose conditions always match is allowed when its window limits it.
• Rules with a rule-level schedule or a per-fill exit key never make the rules below them unreachable. Per-fill rules also don't count toward "exit rules collectively match every held-position state" or "exit predicate fires in profitable, neutral, and losing states". That's why a per-fill rule gated only on yes_position_size > 0 saves.
• An earlier rule without a schedule or per-fill key can still make a scheduled or per-fill rule below it unreachable.
• Composite orders rules aren't checked as entries, so a quote rule whose conditions always match still saves. A composite rule can still make the rules below it unreachable, and it never counts as the required exit rule.

Before you deploy

• Start flat in every market a per-fill strategy may trade, with no resting orders there. How fills become lots explains why.
• Keep those markets to this Bot. No manual trades and no other Bot on the same account and market.
• Check the deploy dialog limits. Studio prefills Max contracts per order from your largest buy or leg (see Leg size). Make sure Max open contracts and max_position both cover held + resting + new legs, and remember per-fill exits sell at most Max contracts per order per loop. Deploys through MCP size their defaults from the strategy the same way.
• Include an exit rule. Every custom strategy needs at least one sell_all, cancel_all, sell_yes or sell_no rule.
• Mind max_entries_per_market with pairs. Each leg uses one entry, so a paired quote needs at least 2.

Common validator messages

Field-level mistakes in composite legs, per-fill exits and rule schedules, and the message each one gets when you save. For combinations the validator refuses, see What can be combined. Mistakes specific to max_combined_price are listed on the composite orders page.

Backtests and paper trading

All three features run in paper trading. In backtests, each one needs a specific mode:

Maker replay versus live

Any rule with orders sends the whole strategy to the Kalshi maker replay, the backtest mode for resting orders. It models your place in the queue from the historical book and trades. When complete historical market data isn't available, it falls back to an approximate model that assumes you're at the front of the queue, which is optimistic. Read replay results with these differences in mind:

• Queue position. The replay keeps an unchanged quote in place instead of cancelling and re-sending it every loop, so it can show queue priority a live quote rule without an order_count gate never gets.
• Only three kinds of rule act. Rules with orders, cancel_all and sell_all do something in the replay. A matched buy_yes, buy_no, sell_yes, sell_no or skip rule does nothing there but still ends evaluation for that moment. So a sell_yes stop in a quoting strategy works live but does nothing in its backtest, and it also blocks the quote rule below it while it matches. Use sell_all and cancel_all for exits in quoting strategies you want to backtest.
• sell_all cancels quotes in the replay, but not live. Add an explicit cancel_all so live behavior matches.
• Limits count differently. The replay checks risk.max_position per outcome as each order arrives, and counts max_entries_per_market by filled orders only. Live counts resting orders too.
• Prices use a finer grid than whole cents, so sub-cent offsets price differently.
• Post-only crosses are rejected when the order arrives, after modeled latency, instead of stopping the rule beforehand. A leg that isn't post-only and would cross also rests at its limit instead of trading immediately.

Per-fill exits in backtests

Per-fill exits run in taker backtests; the maker replay rejects them ("entry-relative exits are not supported by maker replay; use taker execution"). The simulated starting account must be flat; otherwise the backtest is refused with "entry-relative exits require a flat historical starting account". Stops and targets are judged on the bid, and an exit fills on the next event only if there is enough depth at its price.

Exit size per event is the smallest of the lot, 40, and the backtest's Max contracts per order. When the backtest isn't given risk limits, that limit defaults to risk.max_position. Live, it is the Max contracts per order you deploy with, which Studio prefills from your largest buy size or composite leg. Entries are capped by the same limit, so a lot normally sells in one order in both. Give the backtest the same risk limits as your deploy to compare like with like.