mostlyright.markets.economy_trades

Kalshi venue price-history for SETTLED economy markets — with documented depth.

candles(...) retrieves Kalshi OHLC candlesticks for a settled economics market (/series/{s}/markets/{m}/candlesticks), mirroring mostlyright.markets._kalshi_trades. It is the venue-history companion to the economy vertical’s settlement join (mostlyright.economy.research_economy): where research_economy produces the leakage-safe settlement PAIRS, this surfaces the traded price panel for a settled economy contract.

The shallow-depth limit is a first-class, documented behavior (RESEARCH Pitfall 3). The PUBLIC Kalshi API surfaces only ~ RECENT settled markets per series (oldest ~2026-05), and a market’s candlesticks span its own ~1-month life. The FEDS-2026-010 first-contract dates (2021-2023) are therefore NOT retrievable from the public settled-markets endpoint — deep research needs the FEDS replication dataset or a running collector. This module refuses to pretend otherwise:

• A window entirely before the public-depth floor (~2026-05) returns an EMPTY DataFrame stamped df.attrs["public_depth_limited"] = True — never a fabricated 2021-2023 candle.
• A window below the indicator’s FEDS floor raises DataAvailabilityError (the floor is a data-availability CONTRACT, mirroring economy.history).

The realistic depth expectation is documented in the module docstring and the MAX_PUBLIC_DEPTH_NOTE constant.

This module lives in mostlyright.markets (not economy) because it drives the Kalshi venue client — the workspace edge is one-way markets → economy, so it MAY reuse both the markets Kalshi client and the economy floor/routing tables.

Module Attributes

INTERVALS	Supported candle intervals → seconds (mirrors _kalshi_trades.INTERVALS).
PUBLIC_DEPTH_FLOOR	The realistic public-API depth floor.
MAX_PUBLIC_DEPTH_NOTE	The documented shallow-depth limit (surfaced so a caller sets realistic expectations).

Functions

candles(ticker, *, interval, from_time, to_time)	OHLC candles for a settled economy market ticker between from_time and to_time.

mostlyright.markets.economy_trades.INTERVALS : dict[str, int] = {‘1d’: 86400, ‘1h’: 3600, ‘1m’: 60}

Supported candle intervals → seconds (mirrors _kalshi_trades.INTERVALS).

mostlyright.markets.economy_trades.MAX_PUBLIC_DEPTH_NOTE : str = “Kalshi’s public settled-markets API surfaces only ~50-90 RECENT settled markets per series (oldest ~2026-05), and a market’s candlesticks span its own ~1-month life. The FEDS-2026-010 first-contract history (2021-2023) is NOT retrievable from the public endpoint — deep economy research needs the FEDS replication dataset or a running collector. A pre-2026-05 window returns an empty, clearly-labeled result (public_depth_limited=True); it is never a fabricated deep candle.”

The documented shallow-depth limit (surfaced so a caller sets realistic expectations). The public Kalshi API is NOT a deep historical source.

mostlyright.markets.economy_trades.PUBLIC_DEPTH_FLOOR : date = datetime.date(2026, 5, 1)

The realistic public-API depth floor. The public settled-markets endpoint surfaces only recent markets (oldest observed ~2026-05); a window entirely before this returns labeled-empty rather than a fabricated old candle.

mostlyright.markets.economy_trades.candles(ticker, , interval, from_time, to_time)

OHLC candles for a settled economy market ticker between from_time and to_time.

• Parameters:
  • ticker (str) – Full Kalshi economy market ticker (e.g. "KXCPI-26JUL-T3.2"). The series root (KXCPI) is resolved to its economy indicator for the FEDS floor check.
  • interval (str) – Candle granularity — one of INTERVALS keys.
  • from_time (datetime) – tz-aware UTC datetimes bounding the window.
  • to_time (datetime) – tz-aware UTC datetimes bounding the window.
• Return type: DataFrame
• Returns: pd.DataFrame with columns ticker, end_time_utc, open, high, low, close, volume, open_interest, source (prices in cents; see _kalshi_trades.candles). ticker is a leading identity column (DX-H4). For a window entirely before the public-depth floor (~2026-05) the frame is EMPTY with df.attrs["public_depth_limited"] = True — never a fabricated deep candle.
• Raises:
  • TypeError – from_time/to_time not tz-aware datetimes.
  • ValueError – from_time >= to_time OR interval not in INTERVALS.
  • DataAvailabilityError – the window is below the resolved indicator’s FEDS first-contract floor (a data-availability contract violation).