markets/src

Mostlyright TypeScript SDK / markets/src

markets/src

Classes

ContractIdError

Defined in: packages-ts/markets/src/resolvers/kalshi-nhigh.ts:27

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

Error

Constructors

new ContractIdError()

new ContractIdError(message): ContractIdError

Defined in: packages-ts/markets/src/resolvers/kalshi-nhigh.ts:28

Parameters

message

string

Returns

ContractIdError

Overrides

Error.constructor

EarningsContractIdError

Defined in: packages-ts/markets/src/resolvers/earnings.ts:80

Custom error type for earnings 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

Error

Constructors

new EarningsContractIdError()

new EarningsContractIdError(message): EarningsContractIdError

Defined in: packages-ts/markets/src/resolvers/earnings.ts:81

Parameters

message

string

Returns

EarningsContractIdError

Overrides

Error.constructor

EarningsPitError

Defined in: packages-ts/markets/src/pit/earnings.ts:32

Error raised by alignEventDate for a bad event date, an unknown ticker, or a mis-paired (eventDate, callInstant). A named subclass so callers can instanceof-check rather than parse error messages.

Extends

Error

Constructors

new EarningsPitError()

new EarningsPitError(message): EarningsPitError

Defined in: packages-ts/markets/src/pit/earnings.ts:33

Parameters

message

string

Returns

EarningsPitError

Overrides

Error.constructor

KalshiTickerError

Defined in: packages-ts/markets/src/kalshi-ticker.ts:27

Raised on a malformed ticker / unknown city / lo > hi.

Extends

Error

Constructors

new KalshiTickerError()

new KalshiTickerError(message): KalshiTickerError

Defined in: packages-ts/markets/src/kalshi-ticker.ts:28

Parameters

message

string

Returns

KalshiTickerError

Overrides

Error.constructor

Interfaces

AlignEventDateOptions

Defined in: packages-ts/markets/src/pit/earnings.ts:109

Properties

callInstant?

readonly optional callInstant: string

Defined in: packages-ts/markets/src/pit/earnings.ts:119

Optional ISO-8601 UTC instant of the call. When given, the event date is re-projected to the HQ-local calendar date of that instant (the ±1-UTC-day correction) — so a call that straddles a UTC day boundary lands on the correct local date. The re-projected hq-local date must be within ±1 calendar day of the supplied eventDate; a larger divergence throws (it signals a mis-paired (eventDate, callInstant)). When omitted, eventDate is returned unchanged (after coercion).

EarningsCalendarRow

Defined in: packages-ts/markets/src/data/generated/earnings-calendar.ts:8

Properties

callScheduledAt

callScheduledAt: string

Defined in: packages-ts/markets/src/data/generated/earnings-calendar.ts:10

hqTimezone

hqTimezone: string

Defined in: packages-ts/markets/src/data/generated/earnings-calendar.ts:11

provider

provider: string

Defined in: packages-ts/markets/src/data/generated/earnings-calendar.ts:12

ticker

ticker: string

Defined in: packages-ts/markets/src/data/generated/earnings-calendar.ts:9

EarningsResolution

Defined in: packages-ts/markets/src/resolvers/earnings.ts:53

The frozen tuple a Kalshi earnings-mention contract resolves to.

Mirrors import(”./kalshi-nhigh.js”).NHighResolution: an immutable (ticker, targetWord, eventDate, resolutionRule) carrier so a resolution cannot be mutated downstream (the frozen-tuple contract enforced via Object.freeze, the TS twin of the Python @dataclass(frozen=True)).

Properties

eventDate

readonly eventDate: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:57

Calendar date the call airs / the market settles for (YYYY-MM-DD).

resolutionRule

readonly resolutionRule: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:63

Stable settlement-rule label (not an executable rule). Kalshi resolutions carry RESOLUTION_RULE; Polymarket derives carry the any-speaker variant.

resolutionStatus

readonly resolutionStatus: "qualifying_event" | "no_qualifying_event"

Defined in: packages-ts/markets/src/resolvers/earnings.ts:70

Whether a qualifying call exists for this date. "qualifying_event" for a normal resolution; "no_qualifying_event" when a derive sees a postponed/cancelled call. The Kalshi resolveEarnings path is always "qualifying_event".

targetWord

readonly targetWord: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:55

ticker

readonly ticker: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:54

KalshiStation

Defined in: packages-ts/markets/src/data/generated/kalshi-stations.ts:5

Properties

citation

citation: string

Defined in: packages-ts/markets/src/data/generated/kalshi-stations.ts:7

station

station: string

Defined in: packages-ts/markets/src/data/generated/kalshi-stations.ts:6

NHighResolution

Defined in: packages-ts/markets/src/resolvers/kalshi-nhigh.ts:13

Properties

cityTicker

readonly cityTicker: string

Defined in: packages-ts/markets/src/resolvers/kalshi-nhigh.ts:16

contractDate

readonly contractDate: string

Defined in: packages-ts/markets/src/resolvers/kalshi-nhigh.ts:17

settlementSource

readonly settlementSource: "cli.archive"

Defined in: packages-ts/markets/src/resolvers/kalshi-nhigh.ts:14

settlementStation

readonly settlementStation: string

Defined in: packages-ts/markets/src/resolvers/kalshi-nhigh.ts:15

NLowResolution

Defined in: packages-ts/markets/src/resolvers/kalshi-nlow.ts:13

Properties

cityTicker

readonly cityTicker: string

Defined in: packages-ts/markets/src/resolvers/kalshi-nlow.ts:16

contractDate

readonly contractDate: string

Defined in: packages-ts/markets/src/resolvers/kalshi-nlow.ts:17

settlementSource

readonly settlementSource: "cli.archive"

Defined in: packages-ts/markets/src/resolvers/kalshi-nlow.ts:14

settlementStation

readonly settlementStation: string

Defined in: packages-ts/markets/src/resolvers/kalshi-nlow.ts:15

ParsedKalshiTicker

Defined in: packages-ts/markets/src/kalshi-ticker.ts:37

Properties

city

readonly city: string

Defined in: packages-ts/markets/src/kalshi-ticker.ts:43

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

hi?

readonly optional hi: number

Defined in: packages-ts/markets/src/kalshi-ticker.ts:52

kind

readonly kind: KalshiStrikeKind

Defined in: packages-ts/markets/src/kalshi-ticker.ts:47

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

lo?

readonly optional lo: number

Defined in: packages-ts/markets/src/kalshi-ticker.ts:51

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

measure

readonly measure: KalshiMeasure

Defined in: packages-ts/markets/src/kalshi-ticker.ts:41

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

series

readonly series: string

Defined in: packages-ts/markets/src/kalshi-ticker.ts:39

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

station

readonly station: string

Defined in: packages-ts/markets/src/kalshi-ticker.ts:45

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

strike?

readonly optional strike: number

Defined in: packages-ts/markets/src/kalshi-ticker.ts:49

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

PolymarketCityStation

Defined in: packages-ts/markets/src/data/generated/polymarket-city-stations.ts:5

Indexable

[measure: string]: undefined | string

Properties

default

default: string

Defined in: packages-ts/markets/src/data/generated/polymarket-city-stations.ts:6

high?

optional high: string

Defined in: packages-ts/markets/src/data/generated/polymarket-city-stations.ts:7

low?

optional low: string

Defined in: packages-ts/markets/src/data/generated/polymarket-city-stations.ts:8

PolymarketEarningsEvent

Defined in: packages-ts/markets/src/resolvers/earnings.ts:302

Untrusted Polymarket event payload shape (all fields optional).

Properties

eventDate?

readonly optional eventDate: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:309

ISO YYYY-MM-DD calendar date. A time-bearing value is rejected.

name?

readonly optional name: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:305

slug?

readonly optional slug: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:304

status?

readonly optional status: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:311

targetWord?

readonly optional targetWord: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:307

ticker?

readonly optional ticker: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:306

title?

readonly optional title: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:303

webcastUrl?

readonly optional webcastUrl: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:310

ResolveEarningsOptions

Defined in: packages-ts/markets/src/resolvers/earnings.ts:143

Properties

targetWord

readonly targetWord: string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:145

The word/phrase the market resolves on. Required, non-empty.

Type Aliases

KalshiMeasure

KalshiMeasure: "high" | "low"

Defined in: packages-ts/markets/src/kalshi-ticker.ts:34

KalshiSettlement

KalshiSettlement: NHighResolution | NLowResolution

Defined in: packages-ts/markets/src/kalshi-settlement.ts:11

KalshiStrikeKind

KalshiStrikeKind: "threshold" | "range"

Defined in: packages-ts/markets/src/kalshi-ticker.ts:35

Variables

EARNINGS_CALENDAR_SEED

const EARNINGS_CALENDAR_SEED: ReadonlyArray<EarningsCalendarRow>

Defined in: packages-ts/markets/src/data/generated/earnings-calendar.ts:15

EARNINGS_SERIES_ROSTER

const EARNINGS_SERIES_ROSTER: ReadonlySet<string>

Defined in: packages-ts/markets/src/data/generated/earnings-calendar.ts:42

KALSHI_SETTLEMENT_STATIONS

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

Defined in: packages-ts/markets/src/data/generated/kalshi-stations.ts:10

KNOWN_WRONG_STATIONS

const KNOWN_WRONG_STATIONS: ReadonlySet<string>

Defined in: packages-ts/markets/src/data/generated/kalshi-stations.ts:97

POLYMARKET_CITY_STATIONS

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

Defined in: packages-ts/markets/src/data/generated/polymarket-city-stations.ts:12

TICKER_HQ_TIMEZONE

const TICKER_HQ_TIMEZONE: Readonly<Record<string, string>>

Defined in: packages-ts/markets/src/data/generated/earnings-hq-timezone.ts:7

version

const version: "1.15.0" = "1.15.0"

Defined in: packages-ts/markets/src/index.ts:9

Placeholder version string from the TS-W0 Wave 1 scaffold. The authoritative package version lives in package.json#version (currently 0.1.0-rc.7); this constant has not been bumped.

WEBCAST_HOST_ALLOWLIST

const WEBCAST_HOST_ALLOWLIST: ReadonlySet<string>

Defined in: packages-ts/markets/src/resolvers/earnings.ts:234

Netloc allowlist for webcast / resolution-source hosts. A host NOT on this list is refused before any provider classification or derive (T-27-15 security boundary) — mirrors polymarket.RESOLUTION_SOURCE_ALLOWLIST. These are the exact public webcast hosts behind the provider fingerprints; a substring fingerprint alone is NOT a trust decision — the allowlist is.

WEBCAST_PROVIDER_FINGERPRINTS

const WEBCAST_PROVIDER_FINGERPRINTS: Readonly<Record<string, string>>

Defined in: packages-ts/markets/src/data/generated/earnings-webcast-providers.ts:8

Functions

alignEventDate()

alignEventDate(eventDate, ticker, options): string

Defined in: packages-ts/markets/src/pit/earnings.ts:137

Coerce + hq-tz-correct an earnings eventDate to the issuer-local date.

Parameters

eventDate

The calendar date the call airs / the market settles for. Either a UTC date-only Date (H/M/S/ms == 0) or a YYYY-MM-DD string — a time-bearing Date is rejected.

string | Date

ticker

string

The issuer ticker; its IANA HQ timezone is looked up in TICKER_HQ_TIMEZONE.

options

AlignEventDateOptions = {}

Returns

string

The HQ-local calendar date as YYYY-MM-DD.

Throws

eventDate is time-bearing/invalid, ticker is unknown, callInstant is naive (no UTC offset), or the re-projected date diverges from eventDate by more than ±1 calendar day.

deriveEarnings()

deriveEarnings(event): null | EarningsResolution

Defined in: packages-ts/markets/src/resolvers/earnings.ts:342

Derive a frozen EarningsResolution from a Polymarket event payload.

The payload is untrusted. The derive refuses (returns null) when:

the slug/title/name does not look like an earnings-mention market;
a webcastUrl is present but its host is NOT on WEBCAST_HOST_ALLOWLIST (security boundary — refuse before derive);
the ticker is missing or not in EARNINGS_SERIES_ROSTER;
targetWord or eventDate is missing / unparseable.

A postponed / cancelled call yields a resolution with resolutionStatus="no_qualifying_event".

Parameters

event

PolymarketEarningsEvent

Returns

null | EarningsResolution

detectProvider()

detectProvider(webcastUrl): null | string

Defined in: packages-ts/markets/src/resolvers/earnings.ts:283

Name the webcast provider for webcastUrl, or null.

The host is first checked against WEBCAST_HOST_ALLOWLIST (the security boundary): a non-allowlisted host returns null — it is NEVER fingerprinted from a raw substring (so a hostile evil.example/q4inc cannot spoof a provider). An allowlisted host is then matched against WEBCAST_PROVIDER_FINGERPRINTS by host substring.

Parameters

webcastUrl

string

Returns

null | string

helloMarkets()

helloMarkets(): string

Defined in: packages-ts/markets/src/index.ts:17

Smoke-test export from the TS-W0 Wave 1 scaffold. Returns the literal string "hello @mostlyrightmd/markets". Retained so the published package has at least one importable runtime export until the scaffold is removed in a later phase.

Returns

string

kalshiNhighResolve()

kalshiNhighResolve(contractId, settlementDate): NHighResolution

Defined in: packages-ts/markets/src/resolvers/kalshi-nhigh.ts:107

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

contractId

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(contractId, settlementDate): NLowResolution

Defined in: packages-ts/markets/src/resolvers/kalshi-nlow.ts:87

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

contractId

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(contractId, date): KalshiSettlement

Defined in: packages-ts/markets/src/kalshi-settlement.ts:24

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

contractId

string

date

string

Returns

KalshiSettlement

Example

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

parseTicker()

parseTicker(ticker): ParsedKalshiTicker

Defined in: packages-ts/markets/src/kalshi-ticker.ts:88

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.

resolveEarnings()

resolveEarnings(contractId, eventDate, options): EarningsResolution

Defined in: packages-ts/markets/src/resolvers/earnings.ts:165

Resolve a Kalshi earnings-mention contract to its frozen tuple.

The contractId is the Kalshi market identifier — one of the three root variants KXEARNINGSMENTION<TICKER> (e.g. KXEARNINGSMENTIONNKE), KXMENTIONEARN<TICKER>, or the Berkshire fixed root KXBRKEM. The suffix is the ticker; it is validated against EARNINGS_SERIES_ROSTER.