Kalshi Backtesting in Python: Historical Data Guide
Guides

Kalshi Backtesting in Python: Historical Data Guide

· EdgeOutcome Team· kalshi, backtesting, historical-data
Last updated

Kalshi backtesting on live endpoints is a trap that fails quietly. You write a loop over open markets, it runs, it returns data, and then the dataset shrinks every week as markets age out of the live tier. Nothing errors. Your sample just gets thinner, and the strategies that look best are the ones that ran while the market was still fresh.

Kalshi split its exchange data into a live tier and a historical tier, and the split is governed by cutoff timestamps you can query. Everything below was tested against the live API on October 5, 2026.

Key Takeaway: Kalshi backtesting means pulling from GET /historical/markets and GET /historical/markets/{ticker}/candlesticks, not from the live market endpoints. Archived markets disappear from the live tiers and the live candlestick route starts returning HTTP 404 for them. The two candlestick routes also use different field names, so one parser cannot read both. Start with GET /historical/cutoff and route every request by the market’s settlement time.

Kalshi backtesting: what the API gives you

Four endpoints matter for a backtest, and the one you pick is decided by a timestamp rather than by preference.

  • GET /historical/cutoff — the current cutoffs, one per data type. No auth needed.
  • GET /historical/markets — settled markets that have been archived, filterable by series_ticker, event_ticker, ticker and a min_close_ts / max_close_ts window.
  • GET /historical/markets/{ticker}/candlesticks — OHLC, bid/ask and volume for an archived market, start_ts, end_ts and period_interval required.
  • GET /historical/trades — the print-by-print tape for archived markets, with cursor pagination.

The live equivalents still exist and still matter: GET /markets/{ticker}/candlesticks is the fast route for anything trading now, and GET /markets/candlesticks takes up to 100 tickers in one call with a ceiling of 10,000 candles returned. Both are live-tier tools. If you want the full picture of what Kalshi exposes, our Kalshi data overview maps every route and the two gaps no endpoint fills.

The cutoff is the routing rule

Run this first, every time, and never hardcode the result:

import json, urllib.parse, urllib.request

BASE = "https://api.elections.kalshi.com/trade-api/v2"

def get(path, **params):
    url = BASE + path + ("?" + urllib.parse.urlencode(params) if params else "")
    with urllib.request.urlopen(url, timeout=30) as r:
        return json.load(r)

print(get("/historical/cutoff"))
# {'market_positions_last_updated_ts': '2026-08-05T00:00:00Z',
#  'market_settled_ts': '2026-08-05T00:00:00Z',
#  'orders_updated_ts': '2026-09-20T00:00:00Z',
#  'trades_created_ts': '2026-08-05T00:00:00Z'}

Those are the values we received on October 5, 2026. Each field has its own window, and market_settled_ts is the one that decides where market data lives: a market that settled before that timestamp exists only in the historical tier.

The failure mode is easy to reproduce. The New York high-temperature market KXHIGHNY-26JUL01-T99 settled on July 2, 2026:

  • GET /series/KXHIGHNY/markets/KXHIGHNY-26JUL01-T99/candlesticks → HTTP 404
  • GET /historical/markets/KXHIGHNY-26JUL01-T99/candlesticks → HTTP 200
  • GET /historical/markets?series_ticker=KXHIGHNY&min_close_ts=1782864000&max_close_ts=1782950400 → the market, with result and settlement_value_dollars attached

Note the direction of travel: the cutoff keeps moving forward, so a pipeline written against the live tier in June silently loses data in August. The official description of the split and its fields is in Kalshi’s Historical Data guide.

Two candlestick schemas, one API

This is the part that breaks backtests after they already look correct. The two candlestick routes return the same information under different names.

Live route (/series/{series}/markets/{ticker}/candlesticks):

{"end_period_ts": 1790953200, "volume_fp": "707.00", "open_interest_fp": "689.00",
 "price": {"open_dollars": "0.0100", "close_dollars": "0.0100", "mean_dollars": "0.0108"},
 "yes_bid": {"close_dollars": "0.0000"}, "yes_ask": {"close_dollars": "0.0100"}}

Historical route (/historical/markets/{ticker}/candlesticks):

{"end_period_ts": 1782968400, "volume": "20868.27", "open_interest": "105915.67",
 "price": {"open": "0.0100", "close": "0.0100", "mean": "0.0100", "previous": "0.0100"},
 "yes_bid": {"close": "0.0000"}, "yes_ask": {"close": "1.0000"}}

Both are real responses from October 5, 2026. Writes a KeyError or a column of nulls into your database if you assume one shape. It is the same class of problem as the field renames that catch out Kalshi API v2 pipelines, just on a different route.

Two more behaviours worth knowing before you plan a decade-long study:

  • Daily candles are sparse. For KXHIGHNY-26JAN10-T52 over a nine-day window, hourly returned 39 candles and daily returned 2, reproducibly. The same daily request with a shorter end timestamp returned none. Plan on hourly.
  • The live batch route ignores archived tickers. GET /markets/candlesticks returned HTTP 200 with {"markets": []} when we passed an archived market, so there is no shortcut around per-ticker historical calls.

A working loop for an archived backtest dataset

This is the shape we use. Enumerate archived markets for a series and window, then pull a point-in-time price for each one instead of the settlement mark.

import time

def archived_markets(series_ticker, min_close_ts, max_close_ts, max_pages=10):
    out, cursor = [], None
    for _ in range(max_pages):
        q = dict(series_ticker=series_ticker, min_close_ts=min_close_ts,
                 max_close_ts=max_close_ts, limit=200)
        if cursor:
            q["cursor"] = cursor
        page = get("/historical/markets", **q)
        out += page["markets"]
        cursor = page.get("cursor")
        if not cursor:
            break
    return out

def price_before_settlement(ticker, close_ts, hours_before=24, interval=60):
    """Close of the last hourly candle at least `hours_before` before trading close."""
    candles = get(f"/historical/markets/{ticker}/candlesticks",
                  start_ts=close_ts - 5 * 86400, end_ts=close_ts,
                  period_interval=interval)["candlesticks"]
    past = [c for c in candles if c["end_period_ts"] <= close_ts - hours_before * 3600]
    if not past:
        return None
    c = past[-1]                      # historical schema: no _dollars, no _fp
    return float(c["price"]["close"] or c["price"]["previous"])

Two practical notes from running this at scale. Use the market’s close_time as the anchor, not settlement_ts. And throttle: a 160-market loop of these calls ran into multi-second stalls, so we added a delay between requests. Kalshi’s rate limits are documented as token budgets per tier with a {"error": "too many requests"} body and no Retry-After header, so backoff has to be your own — see the rate limit documentation.

What a real sample looks like

We pulled 60 archived weather markets (30 New York, 30 Chicago high-temperature contracts, volume above 1,000 contracts, settled between May 1 and August 4, 2026) and compared each one’s price 24 hours before trading close with its actual outcome.

  • 60 markets, 24 settled YES — a 40.0% base rate
  • Brier score using the 24-hour price as the probability: 0.2510
  • Weighted mean absolute calibration gap: 0.126

The distribution is more interesting than the average. Markets trading between 0.10 and 0.30 (19 of the sample) settled YES 7 times, an average price of 0.17 against a 37% realised rate. On this sample, a rule that bought every contract under 0.30 would have looked excellent, and that is exactly the reading we do not want you to take away: 22 contracts in one summer of one product family is not a strategy test. It is a note that cheap tails on weather contracts deserve a much larger sample before anyone calls them mispriced.

Treat that as a template, not a result. Run it over every series you can enumerate, model the fee side honestly with our payout calculator, and let the sample size decide.

Expert insight: The most common backtest error on Kalshi is not a wrong parameter, it is the wrong price. last_price_dollars on a settled market is frequently the final mark near 0.01 or 0.99, so any study built on it inherits the outcome it is supposed to predict. Point-in-time prices from candlesticks cost one extra request per market and are the difference between a study and a tautology.

Three ways a Kalshi backtest lies to you

  1. Settlement-mark bias. Use candles, never last_price_dollars, for the entry price. A market that settled YES usually shows a last trade near 1.00.
  2. Survivorship in the live tier. Query only /markets and your sample is the set of markets that have not aged out yet — recent, and skewed toward whatever is trading this month.
  3. Fees that are not zero. Kalshi’s taker fee is round up(0.07 × C × P × (1 - P)), capped at 1.75 cents per contract, and maker fees are not always zero by series. A gross edge of 2 cents on a 50-cent contract can be entirely eaten at the extremes. Work the numbers before you believe a result; if you are new to the API side of this, start with our Kalshi API Python tutorial and the free cheat sheet.

Building the dataset is the cheap part. Kalshi publishes the archive, needs no API key for market data, and the only real cost is time and a storage decision. What separates a useful backtest from a spreadsheet of candles is whether the price you used existed at the moment you claim you could have traded it.


EdgeOutcome may earn a commission if you open an account through links on this page. It does not change what we publish.

New to Kalshi? The start page has live odds on both platforms, and the API reference documents the endpoints above.

18+. Prediction markets involve real financial risk. Availability depends on your country and US state.

Frequently Asked Questions

Is there an endpoint for Kalshi historical data?

Yes. Since Kalshi partitioned its data into live and historical tiers, archived markets are served by GET /trade-api/v2/historical/markets, with candlesticks at /historical/markets/{ticker}/candlesticks. Everything older than the archive cutoff only exists there. Checked on October 5, 2026, the cutoff was 2026-08-05 for settled markets and trades.

Why does the live candlestick endpoint return 404 for a market I know traded?

Because the market has been archived. Once a market settles before the cutoff timestamp, GET /series/{series_ticker}/markets/{ticker}/candlesticks returns HTTP 404, while the historical route returns the same market's candles. Route by the market's settlement time, not by whether you can still see it in the web app.

Do Kalshi historical candlesticks use the same field names as the live ones?

No. Live candles return fixed-point and dollar-suffixed fields such as price.close_dollars, volume_fp and open_interest_fp. Historical candles return plain fields: price.close, volume and open_interest, with bid and ask levels under yes_bid.open and yes_ask.close. A parser written for one schema writes nulls against the other.

Which candlestick interval should a Kalshi backtest use?

Use 1 (minute) or 60 (hour). In our tests on October 5, 2026, a daily request (period_interval=1440) returned only 2 candles where the hourly schema returned 39 for the same market and window, and for some markets the daily feed was empty. Hourly candles are the reliable granularity for archived weather and index markets.

Does the batch candlestick endpoint work for archived markets?

No. GET /markets/candlesticks accepts up to 100 tickers and returned HTTP 200 with an empty markets array when we passed an archived ticker on October 5, 2026. For archived markets you have to call the historical candlestick route per ticker, or export and store candles yourself while the market is live.

EdgeOutcome
EdgeOutcome Team

Data-driven prediction market analysis. EdgeOutcome helps traders find real edges on Kalshi and Polymarket — not hype, just numbers. More about us →