Backtest prediction markets with an AI agent

A coding agent such as Claude Code, Codex or Cursor can run a whole backtest: find the markets, download the files, write the test, run it and check it. It needs two things from Kalshi Eye: the MCP server to find markets and files, and the Python client to download them. This guide sets both up and gives the agent the rules that keep a prediction market backtest honest.

Updated November 13, 2026. Every backtester example was run on the free sample.

1. Connect the agent

Add the Kalshi Eye MCP server and sign in. The agent can then search Kalshi, Polymarket and Limitless markets, see what was recorded and list files. Other clients are on the MCP server page.

# Claude Code
claude mcp add --transport http -s user kalshieye https://kalshieye.com/mcp   # then /mcp to sign in

# Codex
codex mcp add kalshieye --url https://kalshieye.com/mcp
codex mcp login kalshieye

2. Give it the Python client

A backtest reads the files from disk, so the agent downloads them with the Python client and an API key. Put the key in the environment the agent runs in, not in the chat.

pip install "kalshieye[pandas]" duckdb
export KALSHIEYE_API_KEY=clab_...   # from kalshieye.com/app/api/

This is what the agent will run to fetch a day:

from kalshieye import Client

kx = Client()  # reads KALSHIEYE_API_KEY
# BTC 15 min on October 25, 2026 is the free sample: every dataset, on any plan.
kx.download(["settlements", "bbo_1m", "book_l2", "trades", "incidents"],
            "2026-10-25", "2026-10-25", series=["KXBTC15M"])
# Files land in ./kalshieye-data/<dataset>/date=2026-10-25/...

Files already on disk are skipped and don't count again. Without an account, the free sample on Hugging Face has the same files in the same layout.

3. Give it the rules

Agents write backtests that run but flatter the result: fills at the mid, bars used before they end, no fees. Save this as AGENTS.md (Codex, Cursor) or CLAUDE.md (Claude Code) in the project, so the agent reads it before it writes any code.

# Backtesting with Kalshi Eye data

## Data
- Find series, markets and file keys with the kalshieye MCP tools (search, get_series,
  get_market, dataset_series, list_files).
- Download with the Python client: kalshieye.Client().download(datasets, start, end, series=[...]).
  Files land in ./kalshieye-data/<dataset>/date=YYYY-MM-DD/...; read them in place with
  DuckDB, pandas or Polars. Columns: https://kalshieye.com/docs/datasets/
- Times are UTC nanoseconds. Order rows by ts_recv (when the recorder got them), then seq.

## Rules
- Outcomes come from settlements: settlement_value is what one YES contract paid (1 or 0).
  Leave out result = 'void'. Read one day past the test window: late markets settle after midnight UTC.
- Buy at the ask and sell at the bid, never at the mid or the last trade. A null ask means nobody was selling.
- Kalshi books are bids only: a NO bid at p is a YES ask at 1 - p. bbo and bbo_1m already give yes_ask.
- A bbo_1m row is labeled with the minute it starts; its closing bid and ask are known only when it ends.
- Fill no more than the size offered: yes_ask_size in bbo, or the levels in book_l2.
- Taker fee per order: fee_multiplier x 0.07 x P x (1 - P) x contracts, rounded up to the cent.
  fee_type in the series file says whether resting orders pay too.
- Drop hours the recorder missed: incidents rows with coverage_pct < 100.
- Place entries from the settlement's close_ts, not the schedule: some markets close early.
- Judge a rule by profit after fees, by entry price. Never by win rate alone.
- Find a rule on one stretch of days and test it on a later one. Say how many markets it traded.

4. Ask for the backtest

Name the markets, the days, the rule, the backtester and the check you want:

Using Kalshi Eye, backtest buying 10 YES contracts at the ask 5 minutes before
close in every KXBTC15M market on October 25, 2026. Download the files with the
kalshieye client, run it in NautilusTrader, charge Kalshi's fee, and report profit
after fees by entry price. Then check the total with a DuckDB query.

The agent looks up KXBTC15M with the MCP tools, downloads the day, adapts the NautilusTrader example, runs it and compares it with a query. Ask it to show each fill and fee before the totals.

Which backtester

On the free sample, the four backtesters agree where they should. Buying at the ask five minutes before close, NautilusTrader and hftbacktest give the same fills and fees on the markets where both filled, and backtesting.py matches the same rule in DuckDB to the cent.

Check what the agent did

• Fills. Each buy should be at the ask standing at the entry time, for no more than the size offered. Ask for a table of fills.
• Fees. At 50¢ the fee is 1.75¢ a contract; a one-contract order pays 2¢ after rounding.
• Time. Nothing read after the entry: no bar used before it ended, no result read from a markets file.
• A second method. The same rule in DuckDB, or in a second backtester, should give the same total.
• Enough markets. One day of 15-minute markets is under a hundred trades. That shows the code works, not that the rule does.

Questions

Next

• Kalshi Eye in Claude Code, Codex and Cursor: the setup for each agent.
• How to backtest Kalshi markets: the same rules worked through in SQL.
• Data dictionary: every dataset and column.