ZenQuant.Options.Chain (zen_quant v0.2.0)

Copy Markdown View Source

Builds and enriches canonical option chains from already-fetched payloads.

from_payload/2 accepts a list of entry maps, a JSON-RPC-style %{"result" => entries} envelope, or a map keyed by option symbol. Source field names are configurable through :fields, so the input contract is not tied to one venue's response keys.

enrich/3 derives each priceable leg's Black-Scholes greeks from its implied volatility. It performs no I/O and reads no system clock: callers supply the reference date or datetime. Unpriceable legs are retained and marked by default; callers can instead request a distinct error. Canonical raw greek units match the chain analytics surface: delta and gamma are per underlying-price unit, vega and rho are per percentage-point change, and theta is per calendar day.

API Functions

FunctionArityDescriptionParam Kinds
enrich3Populate every chain leg with analytic greeks from its implied volatility.chain: exchange_data, reference: value
from_payload2Build a canonical option chain from an already-fetched payload.payload: exchange_data

Summary

Types

enrichment_status()

Per-leg result added by enrich/3.

error_reason()

Chain construction or enrichment failure.

field_selector()

Source key or ordered source-key alternatives for a canonical field.

fields()

Source selectors keyed by canonical option field.

option()

Canonical chain entry consumed by ZenQuant.Options analytics.

t()

Canonical option chain keyed by Deribit-format option symbol.

unpriceable_reason()

Why a readable option leg could not receive Black-Scholes greeks.

Functions

enrich(chain, reference, opts \\ [])

Enriches each priceable leg and explicitly marks or rejects unpriceable legs.

from_payload(payload, opts \\ [])

Builds the canonical chain without fetching or silently dropping entries.

Types

enrichment_status()

@type enrichment_status() :: :enriched | {:unpriceable, unpriceable_reason()}

Per-leg result added by enrich/3.

error_reason()

@type error_reason() ::
  {:invalid_option_payload, term()}
  | {:invalid_option_fields, term()}
  | {:invalid_option_entry, term()}
  | {:unpriceable_option_entry, term(), unpriceable_reason()}
  | {:invalid_reference, term()}
  | {:invalid_enrichment_options, term()}

Chain construction or enrichment failure.

field_selector()

@type field_selector() :: atom() | String.t() | [atom() | String.t()]

Source key or ordered source-key alternatives for a canonical field.

fields()

@type fields() :: %{optional(atom()) => field_selector()}

Source selectors keyed by canonical option field.

option()

@type option() :: %{
  optional(:enrichment_status) => enrichment_status(),
  symbol: String.t(),
  open_interest: number(),
  bid_price: number() | nil,
  ask_price: number() | nil,
  mark_price: number() | nil,
  underlying_price: number() | nil,
  mark_iv: number() | nil,
  implied_volatility: number() | nil,
  raw: map()
}

Canonical chain entry consumed by ZenQuant.Options analytics.

t()

@type t() :: %{optional(String.t()) => option()}

Canonical option chain keyed by Deribit-format option symbol.

unpriceable_reason()

@type unpriceable_reason() ::
  :expired
  | :at_expiry
  | :underlying_price_unavailable
  | :implied_volatility_unavailable
  | {:pricing_error, term()}

Why a readable option leg could not receive Black-Scholes greeks.

Functions

enrich(chain, reference, opts \\ [])

@spec enrich(t() | term(), Date.t() | DateTime.t() | term(), keyword()) ::
  {:ok, t()} | {:error, error_reason()}

Enriches each priceable leg and explicitly marks or rejects unpriceable legs.

from_payload(payload, opts \\ [])

@spec from_payload(
  term(),
  keyword()
) :: {:ok, t()} | {:error, error_reason()}

Builds the canonical chain without fetching or silently dropping entries.