Kalshi Perps Strategy Reference

This section covers platform: kalshi_perps: strategies that trade Kalshi's perpetual futures on crypto assets. It lists every key a Kalshi Perps strategy accepts, what each one does when your Bot runs, and the caveats that matter once real money is involved. Event-contract strategies on Kalshi use a different format; see Kalshi.

The reference is split across this page and the pages listed under In this section. This page has the overview: how perps differ from event contracts, a minimal strategy, the full parameter table with a link from every key to its details, the top-level keys and format rules, what the Bot does on every tick, paper trading, and deploying a Perps Bot.

Studio's AI writes the strategy for you as a short YAML document. Studio checks it every time it is saved and again when you deploy, so a strategy with an invalid setting is refused before it can trade. You don't have to write YAML yourself, but reading it is the best way to confirm the strategy does what you asked. Some mistakes still get through. Misspelled keys inside a block are ignored rather than rejected (see Unknown and misspelled keys), and a few settings save fine but only fail once the Bot runs, such as a leverage above the market's cap or a ticker Kalshi doesn't list.

All values in the examples in this section are illustrative. They show how the settings work, not what to trade, how much to commit or which thresholds to use. Nothing here is a recommendation or a claim about results. Leverage magnifies losses as well as gains.

In this section

• Kalshi Perps Markets and Execution: The markets list and its perp tickers, the loop.interval cadence, and execution: taker vs limit entries, slippage, limit offset and time limit, and what happens when a close doesn't go through.
• Kalshi Perps Sizing and Risk: Margin and leverage sizing, the Bot's own take-profit and stop-loss and their limits, and funding awareness.
• Kalshi Perps Archetypes: The trend_rider, breakout_hunter and dip_reverter archetypes: the rules for params, the ATR stop, and what each archetype does with every parameter.
• Kalshi Perps Custom Strategies: Custom rules: indicators, the fields rules can read (including Coinbase MACD), operators and crossovers, actions and size_pct, missing data, setups, evaluation order, and patterns for rules that behave.
• Kalshi Perps Example Strategies: Seven complete strategies that save as written: one trend_rider archetype and six custom strategies using crossovers, setups, add and trim, resting entries and Coinbase MACD.

How perps strategies differ from event contracts

A perpetual ("perp") follows the price of a crypto asset and never expires. That changes almost everything about how a strategy is written.

What this means in practice:

• Signed positions. Your Bot is long, short or flat, counted in contracts. position is this Bot's own position, built from its own fills. It is not your whole account's position, which your other Perps Bots and your manual trades share.
• Dollar prices per contract. One KXBTCPERP contract is 0.0001 BTC, so it trades near $6.45 when BTC is near $64,500. Every price field, and every price you write in a rule, is in dollars per contract.
• Leverage. Each entry commits margin_usd and multiplies it by leverage to get its notional size (see Sizing and Risk). All your Perps Bots trade one cross-margined account, and Kalshi liquidates across that whole account.
• No settlement. A position stays open until a rule closes it, the Bot's own take-profit or stop-loss closes it, you close it, or it is liquidated. While it is open it pays or receives funding.
• The Bot enforces its own exits. Take-profit and stop-loss are not orders resting at the exchange. The Bot checks them on every tick (the check it runs every loop.interval seconds), so they stop protecting you while the Bot is stopped. See Limits of Bot-enforced exits.
• A document of its own. There is no market, edge, trading_schedule or orders. Actions are open_long, open_short, add, reduce and close. Custom perps rules also have crossover operators and setups, which other venues don't.

A minimal Kalshi Perps strategy

version: 1
platform: kalshi_perps
strategy: trend_rider
strategy_name: Minimal perps example
markets:
  - ticker: KXBTCPERP
sizing:
  margin_usd: 10
  leverage: 1
risk:
  stop_loss_pct: 3

Every 60 seconds (the default), the Bot checks KXBTCPERP. With its default settings, trend_rider compares a 9-candle and a 21-candle exponential moving average of hourly candles. It holds a long while the fast average is above the slow one and a short while it is below. Each entry commits $10 × 1 = $10 of notional, which is 1 contract at about $6.45. The Bot closes the position if the price moves 3% against its average entry.

Everything left out takes its default: loop checks every 60 seconds, execution uses immediate (taker) entries with a 0.5% slippage bound, params uses the archetype's defaults, there is no take-profit, and funding_awareness is off.

All Kalshi Perps parameters

This is the complete list. At the top level, any other key is rejected. Inside a block, any other key is ignored without an error, except in archetype params (see Unknown and misspelled keys). Percentages are plain numbers: 2 means 2%. Prices are dollars per contract.

Document root

version

Always 1, written as a plain number. version: "1" in quotes fails to parse, and any other number fails with version must be 1.

platform

Always kalshi_perps, in lowercase. Kalshi_Perps and kalshi-perps fail with platform must be kalshi_perps.

strategy

The three archetypes are tuned only through params. rules, indicators, setups and setup_rules are rejected on them. A custom strategy needs at least one rule, and it ignores params. Any other value fails with unknown perps strategy.

strategy_name and strategy_name_origin

strategy_name is the name Studio shows. Studio trims it and keeps the first 80 characters. strategy_name_origin records where the name came from: user (you typed it), generated (Studio named it) or curated (a Turbine strategy). Any other value, including the older legacy, is saved as generated. Neither key changes how the Bot trades.

Use strategy_name, not name. Event-contract documents accept name, but here it is an unknown top-level key.

Unknown and misspelled keys

At the top level, an unknown key is an error. This catches keys copied from event-contract strategies, such as name, market, edge and trading_schedule:

# Rejected: `name` is an event-contract key; Kalshi Perps uses `strategy_name`
# error: name: unknown top-level field
version: 1
platform: kalshi_perps
strategy: trend_rider
name: BTC trend
markets:
  - ticker: KXBTCPERP
sizing:
  margin_usd: 10
  leverage: 1

Inside a block, unknown keys are ignored without an error, and the setting you meant falls back to its default:

• risk: {max_loss: 50} gives no loss limit at all, and risk: {stoploss_pct: 3} gives no stop-loss.
• execution: {entry_mod: limit} runs in taker mode.
• size: 50 on a reduce rule closes 100% of the position. The key is size_pct.
• expires_after: 360 on a setup means it never expires. The key is expires_after_seconds.
• action on a setup rule does nothing. Setup rules never trade.

The one checked block is archetype params: an unknown key there fails with params.<key>: unknown param for <strategy>, including a key that belongs to a different archetype.

Warning: Check key names against the parameter table. A misspelled risk or execution key saves without an error. A missing stop-loss gets a deploy warning only when sizing.leverage is above 1, and even then the deploy goes ahead.

Whole numbers and other format rules

• Whole-number keys drop fractions. version, loop.interval, execution.limit_ttl_seconds, indicators[].window and setups[].expires_after_seconds are cut down to a whole number before they are checked. interval: 60.5 runs as 60, and interval: 9.9 becomes 9 and is rejected.
• Archetype windows must be whole. In params, 9.0 works but 9.5 fails with must be a positive integer.
• Zero means default. 0 is replaced by the default for loop.interval, max_slippage_pct, limit_offset_pct, limit_ttl_seconds (limit mode) and a reduce rule's size_pct.
• Blocks are mappings. loop: 60 and execution: taker fail to parse. Write loop: {interval: 60} and execution: {entry_mode: taker}. Each markets entry is a mapping too (- ticker: KXBTCPERP), not a bare string.
• One document. Anything after a --- line is ignored, and saving through Studio removes it.
• Syntax. Duplicate keys and tab indentation fail to parse. JSON works. YAML anchors and aliases work, but a top-level <<: merge is an unknown key.

What happens on every tick

Every tick follows the same order, whatever the strategy type. Knowing it explains most surprises: why a rule didn't run, why an exit came first, why a later market was skipped.

1. The Bot cancels its resting entries whose limit_ttl_seconds has passed.

2. It updates its own position from its fills.

3. For each market, in list order:

   1. It reads the market and account state: prices, its position, P&L, your available balance, the exchange's liquidation estimate and, when funding_awareness is on, the funding estimate.
   2. It runs its own exits: take-profit, then stop-loss, then the archetype ATR stop, which an archetype first places if its open position has none. If one of them sends a close, the strategy is skipped for that market on this tick.
   3. Otherwise it runs the strategy: the archetype's logic, or your custom rules in evaluation order.

   If anything fails for one market, such as a failed request to Kalshi, the Bot skips only that market for this tick and goes on to the next.

4. It waits loop.interval seconds and starts again.

Note: Crossover history and setups live only while the Bot runs: a stop, restart, redeploy or update clears them. The Bot's position and its ATR stops carry over. The position is rebuilt from the Bot's own fills, and each ATR stop is saved with it.

Backtesting and paper trading

Historical backtesting is not available for Kalshi Perps. Studio marks every perps strategy as unsupported for backtests. To see a strategy run before committing real money, deploy it as a paper Bot, and see Backtesting for the venues that support it.

A paper Bot reads live Kalshi market data and simulates your account. Its fills and costs differ from live trading:

• Taker orders fill completely at the top of the book when it is within the order's limit. Resting orders fill only when the price trades through them.
• Fees are assumed at 5 basis points of notional for taker fills and 1 for maker fills.
• Funding is charged every hour at the live estimate. Kalshi itself settles funding a few times a day.
• Nothing is liquidated, and liquidation_price is always missing.
• Leverage below 1 is treated as 1 for margin.
• The starting balance is the one you choose. If you don't choose one, it is your live perps balance when Studio could read it during the deploy, or $1,000 otherwise.

Deploying and running a Perps Bot

Before you deploy

• Fund the perps balance. Perps Bots use your Kalshi API key but trade a separate perpetuals balance, which you fund in the Kalshi app. When you deploy with new credentials and that balance is $0, Studio warns you that the Bot can't trade until it is funded.
• Leverage without a stop. Studio warns when sizing.leverage is above 1 and risk.stop_loss_pct isn't set. Both are warnings: the deploy goes ahead.

Deployment risk limits

Perps Bots read only some of your Studio deployment risk limits:

The deploy dialog shows only these two for Perps. Max contracts per order, Max open contracts, Max daily notional traded and Max daily loss are not read by Perps Bots. Your strategy's sizing and risk are its size controls.

Perps Bots also space their order attempts at least 1 second apart. An entry skipped by this pacing tries again on the next tick if its signal or comparison still holds; a crossover entry doesn't. Closes aren't paced, but each close restarts the 1-second wait. See markets for how this affects several markets on one tick.

Note: Failed requests to Kalshi count toward the API error limit, including rejected orders, but failed funding estimates don't. A tripped limit clears after one error window without a restart.

Stops, restarts and updates

• Stopping a Perps Bot cancels its own resting orders and leaves its positions open. From then on no take-profit, stop-loss or rule protects them, so close them in the Kalshi app if you don't want to hold them.
• Restarting, redeploying or updating keeps the Bot's position, rebuilt from its own fills, and its ATR stops, which are saved with it. The clean stop beforehand cancels its resting orders. It clears crossover memory and setups, and the first reading after the restart never counts as a crossover. Turbine occasionally updates the software your Bots run on, which restarts each Bot once; that restart clears crossover memory and setups the same way. An update that rebuilds the runner also clears the Bot's saved position, so the Bot first rebuilds its position from its own orders and fills on Kalshi, holding entries and exits until it has (the log shows holding: rebuilding this Bot's Position), and then places its ATR stop again from the rebuilt average entry. See Upgrading a runner.
• Stop all on your Kalshi Bots also stops your Perps Bots, but its optional sale covers Kalshi event-contract positions only. Perps positions stay open; close them in the Kalshi app. See Run.
• Removing a market with Update Bot while the Bot holds a position there leaves that position unmanaged. Close it first.

Several Bots, one account

All your Perps Bots trade one cross-margined account. Each Bot tracks its own position from its own fills, and its take-profit, stop-loss and rules close only that position, limited to what the account still holds. available_balance and liquidation_price belong to the account, not to any one Bot, and liquidation applies across the whole account: one Bot's losses can liquidate what the others hold. Watch margin across all your Perps Bots together; see Monitoring and Risk.