Kalshi Market Data Scraper

Backtest-ready Kalshi settlement data with candlesticks and optional trade-level data.

This Actor collects settled Kalshi markets across any category, bridges Kalshi's live and historical API split using GET /historical/cutoff, and emits one normalized dataset item per settled market. Runs are resumable — interrupted runs pick up where they left off without duplicating rows.

Features

• Any category — Economics, Politics, or any valid Kalshi category string
• Configurable lookback — no upper limit on lookbackDays
• All series in category — or narrow with seriesAllowlist
• Candlestick data — 1-minute, hourly, or daily intervals with auto-degradation for large runs
• Trade-level data — optional per-market trade history via includeTrades
• Partial failure handling — failed markets are skipped and logged (configurable via skipFailedMarkets)
• Budget-aware — returns partial results with budgetExceeded: true when runtime budget is exceeded
• Resumable — state is persisted after each market; re-running continues from the last checkpoint
• Structured JSON logging — configurable log level (debug/info/warn/error)
• Public REST only — no authentication required

Input

Parameter	Type	Default	Description
mode	string	"collect"	Operating mode: "collect" gathers settled market data, "alert" monitors active markets and sends webhook notifications.
category	string	"Economics"	Kalshi market category to collect.
lookbackDays	integer	365	Maximum lookback window in days. No upper limit.
seriesAllowlist	string[]	(all)	Optional series tickers. When empty, all series in the category are collected.
candlestickPeriodInterval	integer	60	Candle interval in minutes: 1, 60, or 1440. May be auto-degraded.
maxMarkets	integer	(unlimited)	Optional ceiling on total market rows to emit.
excludeMultivariate	boolean	true	Skip mutually exclusive multivariate events.
includeTrades	boolean	false	Fetch trade-level data for each market alongside candlesticks.
skipFailedMarkets	boolean	true	Skip failed enrichments instead of aborting the entire run.
requestRateLimitRps	number	8	Kalshi API request cap (1–10 requests per second).
candlestickConcurrency	integer	2	Concurrent candlestick/trade fetches (1–5).
logLevel	string	"info"	Minimum log level: debug, info, warn, error.
totalRuntimeBudgetMs	integer	900000	Total runtime budget in milliseconds (default 15 min).
degradationThresholds	object	{minuteToHourly: 25, hourlyToDaily: 400}	Market-count thresholds for auto-degrading candlestick interval.
generateReport	boolean	false	Generate HTML and Markdown settlement analysis reports after collection.
exportCsv	boolean	false	Export collected data as a CSV file in the key-value store.
webhookUrl	string	(none)	Slack or Discord webhook URL for alert notifications. Required when mode is "alert".
alertConditions	object[]	(none)	Price conditions to monitor in alert mode. Each has tickerPattern, field (lastPrice/yesAsk/yesBid), operator (above/below), thresholdDollars.

Output

Each dataset row is a NormalizedMarketRow with the following fields:

Identifiers

• runId, category, seriesTicker, seriesTitle, eventTicker, eventTitle, eventSubtitle
• marketTicker, title, subtitle, marketType, status, result

Partition & Timestamps

• sourcePartition — "live" or "historical" (determined by cutoff)
• settlementTs, closeTime, openTime
• expectedExpirationTime, expirationTime, latestExpirationTime, settlementTimerSeconds

Market Values (dollar-denominated fixed-point strings)

• settlementValueDollars, lastPriceDollars, volumeFp, openInterestFp, liquidityDollars
• yesAskDollars, yesBidDollars, noAskDollars, noBidDollars
• yesAskSizeFp, yesBidSizeFp, notionalValueDollars

Pricing Structure & Rules

• responsePriceUnits, priceLevelStructure, priceRanges
• strikeType, floorStrike, capStrike, customStrike
• rulesPrimary, rulesSecondary
• yesSubTitle, noSubTitle

Candlestick Data

• usedHistoricalCutoffTs — the cutoff timestamp used for live/historical routing
• candlestickPeriodInterval — the interval actually used (may differ from input if degraded)
• candlestickCount, candlestickStartTs, candlestickEndTs
• candlesticks[] — array of CanonicalCandlestick objects, each containing endPeriodTs, openInterestFp, volumeFp, price, yesAsk, yesBid (each with openDollars, highDollars, lowDollars, closeDollars, meanDollars, previousDollars), and rawShape ("live" or "historical")

Trade Data (when includeTrades: true)

• includedTrades — whether trades were requested
• tradeCount — number of trades collected
• trades[] — array of NormalizedTrade objects, each containing tradeId, ticker, count, yesPriceDollars, noPriceDollars, takerSide, createdTime

Diagnostics

• warnings[] — per-market warnings (e.g., missing candlesticks, failed trade fetch)

Pricing

This Actor uses pay-per-event billing. You are only charged for what you use.

Event	Price	When charged
Market collected	$0.003	Each settled market collected with candlestick data
Market with trades	$0.005	Each settled market collected with candlestick + trade data
Report generated	$0.01	Once per run when generateReport: true
CSV exported	$0.005	Once per run when exportCsv: true
Alert scan	$0.005	Once per alert run when breaches are detected
Webhook sent	$0.01	Once per alert run when webhook is delivered successfully

Cost examples:

• 10 markets with candlesticks only → ~$0.03
• 10 markets with trades + report + CSV → ~$0.065
• Alert scan with no breaches → free (no charge)

No charge is applied for failed operations, empty results, or local test runs.

Notes

• Final inclusion uses market.settlement_ts, not event close time.
• Live and historical candlestick payloads use different field names; this Actor normalizes them into one canonical shape while preserving fixed-point string values.
• Deprecated cent-denominated market fields are not used.
• When markets exist in both live and historical APIs (near the cutoff boundary), the version with richer data is kept based on a completeness score.
• Candlestick interval is auto-degraded when the estimated market count exceeds configurable thresholds (1-min → 60-min → daily). The chosen interval and reason are reported in the summary.
• The run summary includes budgetExceeded, failureCount, skippedMarketTickers, and warnings for operational visibility.