Execution: venue.trade() in chat code, strategy.execute() in strategy agents. Data reference: Kalshi Data.

Overview

Kalshi is a CFTC-regulated exchange for binary event contracts. Winning contracts settle at $1; prices are probabilities in roughly [0.01, 0.99]. Scalar Field connects to your own Kalshi account — we never create a trader account on your behalf. Cash stays on Kalshi; deposits and withdrawals happen at Kalshi, never through us.

Specification	Value
Instruments	Event contracts (YES / NO outcomes)
Modes	`KALSHI` (live only; no paper venue)
Hours	Near-24/7; weekly trading pause Thu 03:00–05:00 ET
Fill model	Synthesized IOC for market; GTC for limit
Slippage tolerance	`slippage_bps` on synthesized market orders (default 50)
Currency	USD held on the Kalshi account (`cash`)
Min quantity	0.01 contracts

Connecting

Sign in at kalshi.com/account/profile and click Create API Key. Kalshi shows the private key exactly once — copy both the API Key ID and the PEM private key.
From Portfolio → Kalshi (or the venue card), open Connect and paste the API Key ID and private key.
Scalar Field validates the key against Kalshi, then stores it Fernet-encrypted for trading and portfolio reads.
Disconnect removes our stored copy only; your key stays active on Kalshi.

The stored key is never granted write::transfer. Perpetual futures (Kalshi margin) are not supported in this integration.

Execution and accounting model

This is the contract for audit-grade use of venue.trade, venue.history, venue.account, and venue.cancel on Kalshi. Field meanings come from Kalshi’s Trade API: V2 orders are a single YES book, and fill outcome_side / book_side describe directional exposure, not a second price scale.

Symbol model

Discover markets with screenKalshiMarkets(). Do not invent tickers.

Field	Meaning	Example
`ticker`	Kalshi market identity	`KXHIGHNY-26AUG10-T60`
`symbol`	YES (stated) outcome handle	`K:KXHIGHNY-26AUG10-T60`
`symbol_no`	NO (opposite) outcome handle	`K:KXHIGHNY-26AUG10-T60:NO`

Pass symbol to trade YES and symbol_no to trade NO. Bare tickers are treated as the YES leg. Positions, fills, and history use the same handles. Kalshi stores a signed position_fp per market: positive = YES, negative = NO. Scalar Field splits that into one position row per held outcome, matching Polymarket’s one-row-per-outcome shape.

Book identities

Kalshi’s public order book returns bids only on each leg. Asks are implied by complementarity (Kalshi orderbook docs):

YES ask = 1 − best NO bid
NO ask  = 1 − best YES bid

The V2 create path quotes that same book from the YES leg only:

bid = buy YES (economically sell NO)
ask = sell YES (economically buy NO)

venue.trade converts your (action, outcome, limit_price) into that YES-leg (side, price) before submit. avg_price on the trade response is converted back to the outcome you passed in.

Quantity rules

Kalshi contract counts are fixed-point strings with minimum granularity 0.01 (Fixed-Point Representation). Requests accept 0–2 decimal places; responses emit 2 decimals. This integration truncates toward zero (ROUND_DOWN) to 0.01 before submit. If the result is 0, the order is rejected locally — Kalshi never sees it.

venue.trade("buy", symbol, 0.01, account="KALSHI")    # valid
venue.trade("buy", symbol, 0.019, account="KALSHI")   # submitted as 0.01
venue.trade("buy", symbol, 0.001, account="KALSHI")   # rejected: rounds to 0

More than two decimal places are not rounded to nearest; they are truncated. Size from a dollar budget with qty = int(budget / price * 100) / 100, then confirm the resting/filled qty — do not assume the exchange kept extra precision.

Order support

Kalshi’s V2 create path (POST /portfolio/events/orders) requires price and time_in_force. There is no native market order type.

Type	Supported?	What we submit
Market (`order_type` omitted or `"market"`)	Yes, synthesized	Opposite-side touch, widened by `slippage_bps`, snapped to `price_ranges`, IOC. Unfilled remainder is cancelled, not left resting — status `PARTIALLY_FILLED` or `FAILED` (`NO_FILL`).
Limit	Yes	Snapped conservatively onto `price_ranges` (bid rounds down, ask rounds up). GTC only.
Time-in-force	Not caller-selectable	Market → `immediate_or_cancel`. Limit → `good_till_canceled`. Passing `day` / `ioc` / `fok` on a limit fails with `TIF_NOT_SUPPORTED`. Kalshi itself also supports `fill_or_kill`; this integration does not expose it.
Stop / stop-limit	No	`ORDER_TYPE_NOT_SUPPORTED`

Off-grid limit prices are snapped, not rejected at our layer. Kalshi may still reject a price that falls outside the market’s price_ranges after snapping. During the Thursday 03:00–05:00 ET pause, placement fails with TRADING_PAUSED; cancels still work. Resting GTC orders are submitted with cancel_order_on_pause=false, so they survive the pause. Settlement is automatic. Winning contracts pay $1; there is no redeem call (REDEEM_NOT_SUPPORTED). Settled positions appear in venue.history(category="settlement").

Cash vs buying power

Kalshi’s GET /portfolio/balance returns balance_dollars (documented as available USD) and portfolio_value (open-position valuation in cents). It does not return a buying-power field. venue.account(account="KALSHI") therefore looks like:

{
  "name": "KALSHI",
  "cash": 32.9335,            # balance_dollars
  "portfolio_value": ...,     # cash + marked positions
  "buying_power": None,       # omitted — do not coerce to 0
  "positions": [...],
  "open_orders": [...],
}

When buying_power is missing or None, use cash as the available USD balance. Clients that do buying_power or 0 will conclude the account cannot trade. cash is USD on the Kalshi account. It does not include position mark-to-market; that lives in positions[].market_value / portfolio_value.

Resting-order cash reservation

Kalshi does not publish a reserved_cash (or equivalent) on the direct-member balance payload. GET /portfolio/total_resting_order_value is documented as FCM-only and is not used here. Observed behavior, consistent with that API:

A resting GTC bid appears in open_orders immediately.
cash (balance_dollars) often does not decrease while the order rests.
The matching engine still enforces availability; a bid that cannot be collateralized is rejected at place or fill time.

Do not treat cash as “unreserved buying power” and stack resting bids that sum to more than cash without checking open_orders. A workable available-cash estimate when buying_power is null:

acct = venue.account(account="KALSHI")["accounts"][0]
cash = acct["cash"]
reserved = sum(
    (o["remaining_qty"] or 0) * (o["price"] or 0)
    for o in acct.get("open_orders") or []
    if (o.get("side") or "").lower() == "buy"
)
available = max(cash - reserved, 0)   # estimate only; Kalshi may already have reserved

Treat that as an estimate. Kalshi’s availability check is authoritative.

History semantics and cash formulas

This is the accounting trap. Kalshi fills carry both yes_price_dollars and no_price_dollars (they sum to 1) plus canonical direction fields (Order direction):

Kalshi field	Meaning
`action`	Legacy `buy` / `sell`. Deprecated; still present until at least May 28, 2026.
`outcome_side`	Outcome the fill positions you for. Buy-YES and sell-NO → `yes`. Buy-NO and sell-YES → `no`.
`book_side`	Same bit in book vocabulary: `bid` ≡ `yes`, `ask` ≡ `no`. V2 quotes the YES leg: `bid` pays YES, `ask` receives YES.
`count_fp`	Contracts filled.
`fee_cost`	Net fee on that fill (trade fee + rounding − rebate).

Unified venue.history(category="trade", account="KALSHI") maps those as:

History field	Source	What it is
`side`	Kalshi `action`	`"buy"` or `"sell"`
`outcome`	`outcome_side`	`"YES"` or `"NO"` — exposure after the fill, not necessarily the contract you clicked
`symbol`	ticker + `outcome_side`	`K:TICKER` or `K:TICKER:NO`
`price`	`yes_price` if outcome is YES, else `no_price`	Recorded outcome-leg price
`qty`	`count_fp`	Contracts
`amount`	`qty * price`	Quoted notional of the recorded leg, unsigned
`fees`	`fee_cost`	Net Kalshi fee on the fill
`multiplier`	always `1`

The general venue invariant amount == qty * price * multiplier holds. amount is not cash. Closing a held YES contract at a YES price of $0.43 is a sell-YES, which Kalshi encodes as outcome_side=no. History then looks like:

{
  "side": "sell",
  "outcome": "NO",
  "price": 0.57,      # no_price = 1 - 0.43
  "qty": 1,
  "amount": 0.57,     # quoted NO notional — not proceeds
  "fees": ...,
}

Gross cash credited by the YES book is the YES price:

1 - 0.57 = 0.43

qty * price (0.57) is the wrong proceeds figure.

Quoted notional vs cash

Quantity	How to read it
Quoted notional	`amount` = `qty * price` on the recorded outcome leg
YES-leg price	`price` if `outcome == "YES"` else `1 - price`
Gross cash	Signed YES-leg notional (below)
Fees	`fees` from history (authoritative). Do not use `venue.trade()` `fee_amount`
Net cash	Gross cash − `fees`

Reconstruct cash from a history row. V2 cash follows the YES book: bid pays yes_price, ask receives yes_price.

def kalshi_cash(row):
    qty = row["qty"]
    price = row["price"]          # outcome-leg recorded price
    fees = row.get("fees") or 0
    outcome = (row.get("outcome") or "YES").upper()
    side = (row.get("side") or "buy").lower()

    yes_price = price if outcome == "YES" else (1 - price)
    # bid ≡ buy YES or sell NO; ask ≡ sell YES or buy NO
    is_bid = (side == "buy" and outcome == "YES") or (side == "sell" and outcome == "NO")
    gross = -qty * yes_price if is_bid else +qty * yes_price
    return gross, gross - fees

Worked examples (1 contract, ignore fees first)

Intent	`side`	`outcome`	Recorded `price`	`amount`	Gross cash
Buy YES at $0.43	`buy`	`YES`	0.43	0.43	−0.43
Close YES at $0.43 (sell YES)	`sell`	`NO`	0.57	0.57	+0.43 = `+(1 − 0.57)`
Buy NO at $0.57	`buy`	`NO`	0.57	0.57	+0.43 = `+(1 − 0.57)`
Close NO at $0.57 (sell NO)	`sell`	`YES`	0.43	0.43	−0.43

Buy-NO opening a short YES credits the YES price. That is the V2 single-book identity: buying NO is selling YES. Terminal PnL still matches “paid

0.57 for NO" once the

1 complementary payoff is included at settlement. Net cash is always gross − fees. Do not use:

sell_proceeds = qty * price          # wrong on complement-encoded sells
buy_cost = qty * price               # wrong when outcome is NO

Settlement rows (category: "settlement") are different: amount is revenue (payout), closed_pnl is already revenue − cost_basis − fees, and price is payout per contract. Portfolio venue.history merges Kalshi live fills/settlements with /historical/* so completed activity older than the rolling ~3-month live cutoff is not dropped. Public market-data helpers do not do that merge — see Kalshi Data.

Fees

Kalshi charges exchange fees plus a rounding fee so balances stay on the member’s precision grid (

0.0001 for direct members). Net fee = trade fee + rounding − rebate, always ≥

0 (Fee rounding).

Surface	Fee field	Authoritative?
`POST /portfolio/events/orders` (our `venue.trade`)	`average_fee_paid` × `fill_count`, returned as `fees`. Omitted by Kalshi when `fill_count == 0`. Not copied onto unified `fee_amount`.	No. Immediate, possibly incomplete. Resting limits that fill later will not show the final fee here.
`GET /portfolio/fills` / `/historical/fills`	`fee_cost` → history `fees`	Yes. Use reconciled trade history for fee and cash accounting.

Kalshi order responses may omit finalized fees. Use venue.history(category="trade", account="KALSHI") for authoritative fee and cash accounting. Scalar Field does not add a platform fee on Kalshi; fees on history is Kalshi’s fee_cost. There is a short delay before fills, balances, and positions show up on REST (Get User Data Timestamp). After a fill, prefer the order response for filled_qty / avg_price, then re-read venue.history / venue.account rather than treating the synchronous fees field as final.

Cancel

venue.cancel(broker_order_id, account="KALSHI") is supported. The primary path is Kalshi V2: DELETE /portfolio/events/orders/{order_id}. Success:

`status`	Meaning
`CANCELLED`	Resting remainder cancelled, zero fills on the read-back
`PARTIALLY_FILLED`	Some qty filled before the cancel; remainder cancelled

Pass symbol when you have it (market_ticker is required for V2 auto-routing). Cancels still work during the weekly trading pause. Failure is status="FAILED" with reason set to the exception string. Typical cases:

Situation	What you see today
Unknown / already-cancelled order	V2 often 404s. The client then retries legacy `DELETE /portfolio/orders/{id}`. That V1 path is deprecated and may return HTTP 410. `reason` can contain that raw deprecated-endpoint error — it is not a stable `ORDER_ALREADY_CANCELLED` / `TRADE_NOT_FOUND` code.
Not connected	`NO_KALSHI_ACCOUNT`

Do not parse 410 / V1 deprecation text as “cancel is unsupported”. Resting-order cancel on V2 works. Treat any FAILED after a cancel as “confirm via open_orders / get_order” rather than retrying blindly.

Errors

Normalized reasons this integration emits itself:

`reason`	When
`NO_KALSHI_ACCOUNT`	No connected key
`TRADING_PAUSED`	Weekly Thu 03:00–05:00 ET (placement only)
`TIF_NOT_SUPPORTED`	Resting limit with TIF other than GTC
`ORDER_TYPE_NOT_SUPPORTED`	Stop / stop-limit
`REDEEM_NOT_SUPPORTED`	`action="redeem"`
Quantity rounds to 0	`Quantity {qty} rounds to 0 contracts (minimum 0.01)`
Unknown / closed market	`Unknown Kalshi market …` / `… is {status} and cannot be traded`
Empty book on a synthesized market order	`… has no liquidity on the {bid/ask} side`
IOC matched nothing	`NO_FILL (immediate-or-cancel found no liquidity)`

Everything else (insufficient balance, invalid price after snap, unknown order, already cancelled) is forwarded from Kalshi as FAILED + the HTTP/error body. Those strings are not a stable enum.

Usage

End-to-end: find a market, buy YES, verify, close the held qty, account for complement-encoded history, confirm flat.

from scalarlib import screenKalshiMarkets, getKalshiOrderbook, venue

markets = screenKalshiMarkets(query="bitcoin", closed=False, limit=20)
row = markets.iloc[0]
yes = row["symbol"]          # human YES handle
no = row["symbol_no"]
ticker = row["ticker"]

book = getKalshiOrderbook(ticker)
print(book["yes"]["bid"], book["yes"]["ask"])   # ask = 1 - best NO bid

# Buy 1 YES (market = synthesized IOC)
buy = venue.trade("buy", yes, 1, account="KALSHI")
print(buy["status"], buy["filled_qty"], buy["avg_price"], buy.get("fees"))

acct = venue.account(account="KALSHI")["accounts"][0]
print("cash", acct["cash"], "buying_power", acct.get("buying_power"))  # buying_power is None
pos = next(p for p in acct["positions"] if p["symbol"] == buy["symbol"])
print(pos["qty"], pos["outcome"], pos["avg_price"])

# Close the actual held qty (do not assume 1.00 if the IOC partial-filled)
sell = venue.trade("sell", pos["symbol"], pos["qty"], account="KALSHI")

hist = venue.history(category="trade", account="KALSHI", symbol=pos["symbol"], limit=20)
for t in hist:
    yes_px = t["price"] if t.get("outcome") == "YES" else (1 - t["price"])
    is_bid = (t["side"] == "buy" and t.get("outcome") == "YES") or (
        t["side"] == "sell" and t.get("outcome") == "NO"
    )
    gross = -t["qty"] * yes_px if is_bid else +t["qty"] * yes_px
    net = gross - (t.get("fees") or 0)
    print(t["side"], t.get("outcome"), t["price"], t["amount"], "cash", gross, "net", net)

acct = venue.account(account="KALSHI")["accounts"][0]
assert not any(p["symbol"] == pos["symbol"] for p in acct["positions"])
assert not any(o.get("symbol") == pos["symbol"] for o in acct.get("open_orders") or [])

Limit on the NO leg:

resp = venue.trade(
    "buy", no, 5,
    account="KALSHI", order_type="limit", limit_price=0.42,
)
# Resting: status PENDING, cash typically unchanged, order in open_orders
venue.cancel(resp["broker_order_id"], account="KALSHI", symbol=no)

In strategy agents, use strategy.execute(symbol, target_qty) with brokerage_account="KALSHI".

Data Functions

Market data is public (no Kalshi connection required). Full reference, including sparse candles and live-vs-historical coverage: Kalshi Data.

Function	Purpose
`screenKalshiMarkets(...)`	Discover/filter markets. Query `status`: `"open"` (default; `None` same as omit) / `"closed"` / `"settled"`
`screenKalshiEvents(...)`	Discover events. Query `status`: `"open"` / `"closed"` / `"settled"` / omit; other values raise `ValueError`
`getKalshiMarket(ticker)`	Full public Market payload (result, settlement_ts, rules, disputed/amended)
`getKalshiOrderbook(ticker)`	Live YES/NO book (asks derived)
`getKalshiCandles(ticker, start, end, period_interval)`	OHLC (1 / 60 / 1440 min). Empty intervals have null OHLC. Live then historical
`getKalshiTrades(ticker)`	Public trade tape with `is_complete` / `next_cursor`; live then historical

Notes

Weekly maintenance pause: Thursday 03:00–05:00 ET — order placement fails with TRADING_PAUSED; cancels still work.
The stored API key cannot withdraw or transfer funds (write::transfer is never granted).
Perpetual futures (margin) are not supported in this integration.
Orders, fills, and settlements older than Kalshi’s ~3-month live cutoff are merged from /historical/* on portfolio reads (venue.history, positions, resting/completed orders). Public getKalshiTrades / getKalshiCandles also fail over to GET /historical/trades and GET /historical/markets/{ticker}/candlesticks.

Getting Started

Trading

Trading Venues

Market Data

Usage & Pricing

Trading on Kalshi

Overview

Connecting

Execution and accounting model

Symbol model

Book identities

Quantity rules

Order support

Cash vs buying power

Resting-order cash reservation

History semantics and cash formulas

Quoted notional vs cash

Worked examples (1 contract, ignore fees first)

Fees

Cancel

Errors

Usage

Data Functions

Notes

​Overview

​Connecting

​Execution and accounting model

​Symbol model

​Book identities

​Quantity rules

​Order support

​Cash vs buying power

​Resting-order cash reservation

​History semantics and cash formulas

​Quoted notional vs cash

​Worked examples (1 contract, ignore fees first)

​Fees

​Cancel

​Errors

​Usage

​Data Functions

​Notes

​Related

Overview

Connecting

Execution and accounting model

Symbol model

Book identities

Quantity rules

Order support

Cash vs buying power

Resting-order cash reservation

History semantics and cash formulas

Quoted notional vs cash

Worked examples (1 contract, ignore fees first)

Fees

Cancel

Errors

Usage

Data Functions

Notes

Related