Bourse.Unified.OptionSurface (bourse v0.1.0)

Coherent option discovery and instrument-Greeks surface for option venues.

Joins market identity with risk data by canonical unified symbol, preserves native provenance (info) and distinct source vs local observation timestamps, and fails explicitly on missing identity, ambiguous matches or stale data.

Summary

Functions

discover(exchange, opts \\ [])

Discovers active option calls and puts for a venue.

instrument_greeks(exchange, symbol, opts \\ [])

Fetches instrument Greeks for one canonical symbol and joins market identity.

surface(exchange, opts \\ [])

Builds the joined option+Greeks surface for active instruments.

Functions

discover(exchange, opts \\ [])

@spec discover(Bourse.Exchange.t(), keyword() | map()) ::
  {:ok, [Bourse.OptionInstrument.t()]} | {:error, Bourse.Error.t()}

Discovers active option calls and puts for a venue.

Options:

:base / "base" — restrict to an underlying base currency
:quotes — when true (default), attempt to attach bid/ask/IV/OI via fetch_option_chain when available
:observed_at — override local observation time (tests)
:request_opts — options forwarded to venue HTTP calls

instrument_greeks(exchange, symbol, opts \\ [])

@spec instrument_greeks(Bourse.Exchange.t(), String.t(), keyword() | map()) ::
  {:ok, Bourse.InstrumentGreeks.t()} | {:error, Bourse.Error.t()}

Fetches instrument Greeks for one canonical symbol and joins market identity.

Options:

:max_age_ms — when set, fails if source timestamp is missing or older than this many milliseconds relative to observed_at
:observed_at — override local observation time (tests)
:request_opts — options forwarded to venue HTTP calls

surface(exchange, opts \\ [])

@spec surface(Bourse.Exchange.t(), keyword() | map()) ::
  {:ok,
   [
     %{
       instrument: Bourse.OptionInstrument.t(),
       greeks: Bourse.InstrumentGreeks.t()
     }
   ]}
  | {:error, Bourse.Error.t()}

Builds the joined option+Greeks surface for active instruments.

Options:

:base / "base" — restrict discovery
:limit — cap the number of instruments whose Greeks are fetched
:max_age_ms — freshness gate applied per instrument
:observed_at — override local observation time (tests)
:request_opts — options forwarded to venue HTTP calls