@mostlyrightmd/markets

Classes

ContractIdError

Custom error type for contract-id parsing / validation failures.

Mirrors the Python ValueError/TypeError distinction: in TS we use a named subclass so callers can instanceof-check rather than parse error messages.

Extends

ContractError

Constructors

new ContractIdError()

new ContractIdError(message): ContractIdError

Parameters

message

string

Returns

ContractIdError

Overrides

ContractError.constructor

KalshiTickerError

Raised on a malformed ticker / unknown city / lo > hi. A ContractError subclass (DX-H5): a bad ticker is an invalid local call, not a transport failure — it is raised before any I/O.

Extends

ContractError

Constructors

new KalshiTickerError()

new KalshiTickerError(message): KalshiTickerError

Parameters

message

string

Returns

KalshiTickerError

Overrides

ContractError.constructor

Interfaces

KalshiStation

Properties

citation

citation: string

station

station: string

NHighResolution

Properties

cityTicker

readonly cityTicker: string

contractDate

readonly contractDate: string

settlementSource

readonly settlementSource: "cli.archive"

settlementStation

readonly settlementStation: string

NLowResolution

Properties

cityTicker

readonly cityTicker: string

contractDate

readonly contractDate: string

settlementSource

readonly settlementSource: "cli.archive"

settlementStation

readonly settlementStation: string

ParsedKalshiTicker

Properties

city

readonly city: string

The 3-letter catalog city key (e.g. NYC) — alias-resolved.

kind

readonly kind: KalshiStrikeKind

"threshold" (-T<n>) or "range" (-B<lo>-<hi>).

lowerStrike?

readonly optional lowerStrike: number

Range bounds (present when kind === "range").

measure

readonly measure: KalshiMeasure

"high" (KXHIGH*) or "low" (KXLOW*).

series

readonly series: string

The full series token (e.g. KXHIGHNY).

station

readonly station: string

The resolved settlement station ICAO (e.g. KNYC).

strike?

readonly optional strike: number

Threshold strike (present when kind === "threshold").

upperStrike?

readonly optional upperStrike: number

PolymarketCityStation

Indexable

[measure: string]: undefined | string

Properties

default

default: string

high?

optional high: string

low?

optional low: string

Type Aliases

KalshiMeasure

KalshiMeasure: "high" | "low"

KalshiSettlement

KalshiSettlement: NHighResolution | NLowResolution

KalshiStrikeKind

KalshiStrikeKind: "threshold" | "range"

Variables

KALSHI_SETTLEMENT_STATIONS

const KALSHI_SETTLEMENT_STATIONS: Readonly<Record<string, KalshiStation>>

KNOWN_WRONG_STATIONS

const KNOWN_WRONG_STATIONS: ReadonlySet<string>

POLYMARKET_CITY_STATIONS

const POLYMARKET_CITY_STATIONS: Readonly<Record<string, PolymarketCityStation>>

version

const version: "1.9.9" = "1.9.9"

Public package version; kept in lockstep with package.json.

Functions

kalshiNhighResolve()

kalshiNhighResolve(ticker, settlementDate): NHighResolution

Resolve a Kalshi NHIGH contract to its settlement source + station.

The contract id format is KHIGH<CITY> (case-insensitive), where <CITY> is a city ticker present in KALSHI_SETTLEMENT_STATIONS.

Parameters

ticker

string

Kalshi market identifier. Case-insensitive.

settlementDate

Calendar date the market settles for. Either a UTC date-only Date (H/M/S/ms == 0) or a YYYY-MM-DD string.

string | Date

Returns

NHighResolution

A frozen NHighResolution.

Throws

The contract id doesn’t follow KHIGH<CITY>, the city is unknown, or the settlement date is invalid.

kalshiNlowResolve()

kalshiNlowResolve(ticker, settlementDate): NLowResolution

Resolve a Kalshi NLOW contract to its settlement source + station.

The contract id format is KLOW<CITY> (case-insensitive), where <CITY> is a city ticker present in KALSHI_SETTLEMENT_STATIONS.

Parameters

ticker

string

Kalshi market identifier. Case-insensitive.

settlementDate

Calendar date the market settles for. Either a UTC date-only Date (H/M/S/ms == 0) or a YYYY-MM-DD string.

string | Date

Returns

NLowResolution

A frozen NLowResolution.

Throws

The contract id doesn’t follow KLOW<CITY>, the city is unknown, or the settlement date is invalid.

kalshiSettlementFor()

kalshiSettlementFor(ticker, date): KalshiSettlement

Resolve a Kalshi NHIGH or NLOW contract id to its settlement metadata.

KHIGH* prefixes dispatch to the NHIGH resolver; KLOW* prefixes dispatch to NLOW. Anything else raises ContractIdError.

Parameters

ticker

string

date

string

Returns

KalshiSettlement

Example

kalshiSettlementFor("KHIGHNYC", "2025-01-06")
  // → { settlementSource: "cli.archive", settlementStation: "KNYC",
  //     cityTicker: "NYC", contractDate: "2025-01-06" }

parseTicker()

parseTicker(ticker): ParsedKalshiTicker

Parse a full Kalshi market ticker into series/measure/city/strike + resolve the settlement station via the parity-critical whitelist (with the NY→NYC alias on a raw-suffix miss).

Parameters

ticker

string

Returns

ParsedKalshiTicker

Throws

malformed ticker, unknown city, or lo > hi.

settleKalshiOutcome()

settleKalshiOutcome(parsed, observed): null | 0 | 1

Settle an observed value against a parsed Kalshi ticker’s strike.

INCLUSIVE comparison (documented, see file header + -SUMMARY.md) threshold: value >= strike; range: lo <= value <= hi.

Parameters

parsed

ParsedKalshiTicker

observed

null | number

Returns

null | 0 | 1

1 (YES), 0 (NO), or null when observed is null (NaN label → NA outcome, row preserved — mirrors Python).