serenity_types package

Submodules

serenity_types.pricing module

serenity_types.pricing.derivatives module

serenity_types.pricing.derivatives.options module

serenity_types.pricing.derivatives.options.valuation module

class serenity_types.pricing.derivatives.options.valuation.MarketDataOverride(*, replacement: float | None = None, additiveBump: float | None = None)

Bases: CamelModel

Helper type for representing replacements and bumps for market data inputs in pricing.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

additive_bump: float | None

A value (potentially negative) to add the observed value from stored or live market data.

classmethod check_bump_or_replace_but_not_both(replacement, values)

replacement: float | None

Replacement value for the given market data point.

class serenity_types.pricing.derivatives.options.valuation.OptionValuation(*, optionValuationId: str, qty: int | None = 1, optionAssetId: UUID | None = None, underlierAssetId: UUID | None = None, strike: float | None = None, expiry: datetime | None = None, optionType: OptionType | None = None, optionStyle: OptionStyle | None = OptionStyle.EUROPEAN, contractSize: float | None = 1, impliedVolOverride: MarketDataOverride | None = None, spotPriceOverride: MarketDataOverride | None = None)

Bases: CamelModel

A collection of option economics and market data overrides used to describe a single option valuation requested from the service. This is intentionally meant to support both listed contract pricing and more general pricing of option economics. For market data, everything is defaulted, but the client can override or bump (shift) any of the inputs to get the exact pricing scenario desired.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

contract_size: float | None

For scaling purposes, the # of underlying per contract. Only used if option_asset_id is not set, otherwise it’s loaded from the contract specification in the database.

expiry: datetime | None

Expiration expressed in absolute terms as a date/time. Not required if optionAssetId provided

implied_vol_override: MarketDataOverride | None

Replace or modify the stored volatility surface’s IV for this option.

option_asset_id: UUID | None

Look up all option economics based on the unique ID of a specific listed option contract.

option_style: OptionStyle | None

The variety of option being priced. Our pricer only supports EUROPEAN at this time, so defaults accordingly.

option_type: OptionType | None

Whether we are pricing a PUT or CALL option.

option_valuation_id: str

Correlation ID to use for this requested option valuation. If pricing based on a listed contract with optionAssetId, by convention the unique ID or symbol of that option should be used.

qty: int | None

Number of option contracts; used when computing the spot notional of the option position. If you take the default every scaled value (e.g. spot_notional, delta_ccy) will be a unit notional value.

spot_price_override: MarketDataOverride | None

Replace or modify the stored or observed spot price used when pricing this option.

strike: float | None

Absolute value of the strike. Not required if optionAssetId provided. In future we may wish to support different StrikeType representations here, but some cases (like DELTA) are potentially trickier, so not for initial version.

underlier_asset_id: UUID | None

Serenity asset identifier of the underlier, e.g. BTC (tok.btc.bitcoin). Not required if optionAssetId provided. Note we will be switching to the Exposure UUID instead in a future release (e.g. tok.btc), once the reference data is available.

class serenity_types.pricing.derivatives.options.valuation.OptionValuationRequest(*, asOfTime: datetime | None = None, modelConfigId: UUID | None = None, baseCurrencyId: UUID | None = None, discountingMethod: DiscountingMethod | None = DiscountingMethod.SELF_DISCOUNTING, projectionMethod: ProjectionMethod | None = None, volSurfaceId: UUID | None = None, volSurface: InterpolatedVolatilitySurface | None = None, discountingCurveOverride: YieldCurveOverride | None = None, projectionCurveOverride: YieldCurveOverride | None = None, volModel: VolModel | None = VolModel.SVI, options: List[OptionValuation])

Bases: CamelModel

A batch request to run one or more option valuations using a single model configuration and base set of curves and the vol surface. Reasonable defaults will be provided for any missing inputs, e.g. if you price a set of Deribit BTC options, the latest BTC volatility surface will be used along with the latest discounting curves for BTC and USD. Note that because the request only references a single volatility surface this means all included options must have the same underlier as the one in VolatilitySurfaceVersion.interpolated.definition.underlier_asset_id.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

as_of_time: datetime | None

The as-of time to use for loading all marketdata, surfaces, yield curves and refdata from the database. Defaulted to the latest up to this time.

base_currency_id: UUID | None

Base currency to use for expressing all notional values. Defaults to USD.

classmethod check_non_empty_options_list(options, values)

classmethod check_vol_surface_id_or_vol_surface(vol_surface, values)

discounting_curve_override: YieldCurveOverride | None

Various forms of modifications to the discounting curve: choosing a variant in the database; passing in a complete curve by value; and/or replacing or shifting the extracted rate.

discounting_method: DiscountingMethod | None

How to derive the discount rate: from the projection rate (self-discounting), or from pre-built discounting curves either provided in API or loaded from the system.

model_config_id: UUID | None

The specific derivatives analytics model configuration to load; this is used to drive defaults.

options: List[OptionValuation]

The full set of option valuations to run with the given market data inputs. The client may provide individual overrides or bumps for all inputs as part of each valuation object.

projection_curve_override: YieldCurveOverride | None

Various forms of modifications to the projection curve: choosing a variant in the database; passing in a complete curve by value; and/or replacing or shifting the extracted rate.

projection_method: ProjectionMethod | None

How to derive the projection rate when in real-time mode: from live futures prices, or from a curve. The default depends on as_of_time. In the case of as_of_time being None the system runs in real-time pricing mode and uses ProjectionMode.FUTURES. When as_of_time is provided the system runs in historical pricing mode and defaults to ProjectionMode.CURVE. Setting both as_of_time and ProjectionMode.FUTURES will yield a validation error from the API.

vol_model: VolModel | None

The volatility model used for valuation purposes.

vol_surface: InterpolatedVolatilitySurface | None

The optional client-provided volatility surface to use. If the client provides neither a VS ID nor their own volatility surface, the system will load the default for the underlying as-of the as_of_time.

vol_surface_id: UUID | None

The optional unique ID of the surface to load, latest version as-of the as_of_time.

class serenity_types.pricing.derivatives.options.valuation.OptionValuationResult(*, optionValuationId: str, volModel: VolModel, pv: float, iv: float, spotNotional: float, spotPrice: float, forwardPrice: float, projectionRate: float, discountingRate: float, delta: float, deltaQty: float, deltaCcy: float, gamma: float, gammaCcy: float, vega: float, vegaCcy: float, rho: float, rhoCcy: float, theta: float, thetaCcy: float)

Bases: CamelModel

The result of a series of option valuations based on the parameters in the OptionValuationRequest. Note that the basic calculation is just Black-Scholes, but if you provide additional information regarding the position scaling it will also provide position notional and greek exposures in base currency to allow bucketing of greeks and NAV calculations.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

delta: float

Greek output: delta, the option’s sensitivity to spot changes.

delta_ccy: float

Delta X value, a.k.a. the partial derivative of position value with respect to spot, expressed in base currency

delta_qty: float

Delta X qty X contract_size, the delta exposure expressed in qty of underlying.

discounting_rate: float

The discounting rate used when computing the forward; equal to projection_rate with SELF_DISCOUNTING.

forward_price: float

Input forward price for this valuation.

gamma: float

Greek output: gamma, the delta’s sensitivity to spot changes.

gamma_ccy: float

Gamma X value^2, a.k.a. the second derivative of position value with respect to spot, expressed in base currency.

iv: float

Implied volatility (IV)

option_valuation_id: str

Correlation ID for the original OptionValuation.

projection_rate: float

The projection rate used when computing the forward.

pv: float

Present value (PV) a.k.a. theoretical price or theo.

rho: float

Greek output: rho, the delta’s sensitivity to interest rate changes.

rho_ccy: float

Partial derivative of the spot notional value of the contract with respect to rho X 1bp, expressed in base currency.

spot_notional: float

The base currency notional of the position: number of contracts (qty) X spot_price X contract_size.

spot_price: float

Input spot price for this valuation.

theta: float

Greek output: theta, the delta’s sensitivity to time decay.

theta_ccy: float

Partial derivative of the spot notional value of the contract with respect to theta X 1 day, expressed in base currency.

vega: float

Greek output: vega, the option’s sensitivity to volatility changes.

vega_ccy: float

Partial derivative of the position value of the contract with respect to vega X 1%, expressed in base currency.

vol_model: VolModel

The specific volatility model used; as SVI calibrations yield different greeks, this needs to be explicit.

class serenity_types.pricing.derivatives.options.valuation.YieldCurveOverride(*, yieldCurveId: UUID | None = None, yieldCurve: InterpolatedYieldCurve | None = None, rateOverride: MarketDataOverride | None = None)

Bases: CamelModel

Helper for representing explicitly either override by UUID (load that YieldCurveDefinition from the database for the appropriate as_of_time) or by value. The client can also specify mutations to make to this input market data. In the case where you want to replace the rate entirely do not specify either yield_curve_id or yield_curve; in the case where you want to do a shift of the yield curve, specify either ID or curve and then an additive_bump. Everything null or both yield_curve_id and yield_curve specified yields validation errors.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

classmethod check_yield_curve_ids_or_yield_curve(yield_curve, values)

rate_override: MarketDataOverride | None

Optionally modifies the input data. Note properly you should not need to both provide a yield_curve and modify it, but in case clients want to play back our stored yield_curve via API without having to mutate the curve themselves, it could make sense.

yield_curve: InterpolatedYieldCurve | None

Optionally specifies a supported yield curve bootstrapped by the client or loaded separately. Not every definition is accepted, e.g. you cannot pass in a CurveUsage.PROJECTION curve for discounting.

yield_curve_id: UUID | None

Optionally specifies a supported YieldCurveDefinition UUID from the database. Not every definition is accepted, e.g. you cannot pass in a CurveUsage.PROJECTION curve for discounting.

serenity_types.pricing.derivatives.options.volsurface module

class serenity_types.pricing.derivatives.options.volsurface.DiscountingMethod(value)

Bases: Enum

The strategy to use for deriving the discount rate, i.e. the assumed interest rate to use when discounting prices to present.

CURVE = 'CURVE'

Extract a discount factor from discount curves, either provided via API or loaded from database.

SELF_DISCOUNTING = 'SELF_DISCOUNTING'

Use the base asset’s projection rate as the discount rate instead of a discount curve. This is the default, and the option you should choose if you want to reproduce the Deribit forward pricing model.

class serenity_types.pricing.derivatives.options.volsurface.InterpolatedVolatilitySurface(*, definition: VolatilitySurfaceDefinition, strikes: List[float], timeToExpiries: List[float], vols: List[float], inputParams: Dict[str, object], calibrationParams: Dict[float, Dict[str, float]])

Bases: CamelModel

A calibrated volatility surface with a dense grid of fitted vols. Each array is of equal length and corresponds to (x, y, z) for the mesh.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

calibration_params: Dict[float, Dict[str, float]]

Informational set of calibration parameters, e.g. the SVI parameters. Keying is time_to_expiry expressed in year fractions to parameter set, where the parameter keys are VolModel-specific.

definition: VolatilitySurfaceDefinition

The unique set of parameters used to calibrate / fit this surface.

input_params: Dict[str, object]

Informational set of input parameters, e.g. yield curves used for the forward. May be empty and keys will depend on the configuration, e.g. DiscountingType.

strikes: List[float]

All strikes expressed as log-money values, the x-axis in the mesh.

time_to_expiries: List[float]

All times to expiry expressed as year fractions, the y-axis in the mesh.

vols: List[float]

All fitted vols, the z-axis in the mesh.

class serenity_types.pricing.derivatives.options.volsurface.ProjectionMethod(value)

Bases: Enum

The strategy to use for deriving the projection rates, i.e. the forward interest rates.

CURVE = 'CURVE'

Projection rate is extracted from a projection curve, either provided via API or loaded from database. This option is respected in both real-time pricing and historical pricing modes, though in real-time the curve version loaded is always the very latest. Select CURVE if you want a more stable forward.

FUTURES = 'FUTURES'

Projection rate is snapped from the corresponding Deribit futures prices; this option is only supported in real-time pricing mode. Select FUTURES if in real-time you want to reproduce Deribit forward pricing model and incorporate up-to-the-moment market view on the forward.

class serenity_types.pricing.derivatives.options.volsurface.RawVolatilitySurface(*, strikeType: StrikeType, spotPrice: float, volPoints: List[VolPoint])

Bases: CamelModel

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

spot_price: float

The observed spot price that went into the IV calculations.

strike_type: StrikeType

Strike representation used for this surface, e.g. ABSOLUTE or LOG_MONEYNESS.

vol_points: List[VolPoint]

The discrete IV points available for fitting as a volatility surface.

class serenity_types.pricing.derivatives.options.volsurface.StrikeType(value)

Bases: Enum

Currently supported strike representations.

ABSOLUTE = 'ABSOLUTE'

Absolute value of strike, e.g. the 20000 option.

LOG_MONEYNESS = 'LOG_MONEYNESS'

Relative value of strike vs. current spot with log transformation: log(strike / spot).

class serenity_types.pricing.derivatives.options.volsurface.VolModel(value)

Bases: Enum

Currently supported volatility models.

BLACK_SCHOLES = 'BLACK_SCHOLES'

Classic Black-Scholes volatility model.

SVI = 'SVI'

Stochastic volatility (SVI) calibrated volatility model.

class serenity_types.pricing.derivatives.options.volsurface.VolPoint(*, optionAssetId: UUID, timeToExpiry: float, strikeValue: float, markPrice: float, projectionRate: float, discountingRate: float, forwardPrice: float, iv: float)

Bases: CamelModel

An individual IV input point.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

discounting_rate: float

The discounting rate used when computing the forward; equal to projection_rate with SELF_DISCOUNTING, which is currently the default for our IV calculations.

forward_price: float

The computed forward price that went into the IV calculation.

iv: float

The computed implied volatility (IV) that corresponds to the given mark_price and other inputs.

mark_price: float

The observed option premium used as input to the IV calculation.

option_asset_id: UUID

The specific option that was used for vol fitting purposes.

projection_rate: float

The projection rate used when computing the forward.

strike_value: float

Value of strike for this point, unit defined by StrikeType.

time_to_expiry: float

The time to expiry for this point, expressed as a year fraction.

class serenity_types.pricing.derivatives.options.volsurface.VolatilitySurfaceAvailability(*, definition: VolatilitySurfaceDefinition, asOfTimes: List[datetime])

Bases: CamelModel

Information about version availability for a given volsurface definition.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

as_of_times: List[datetime]

The list of all available as_of_times in the requested window.

definition: VolatilitySurfaceDefinition

Description of the particular volsurface parameters that are available to load.

class serenity_types.pricing.derivatives.options.volsurface.VolatilitySurfaceDefinition(*, volSurfaceId: UUID, volModel: VolModel, strikeType: StrikeType, underlierAssetId: UUID, displayName: str)

Bases: CamelModel

A uniquely-identified set of VS parameters for fitting a VolatilitySurface.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

display_name: str

Human-readable description of this curve, e.g. Deribit BTC (SVI, ABSOLUTE)

strike_type: StrikeType

Strike representation used for this surface, e.g. ABSOLUTE or LOG_MONEYNESS.

underlier_asset_id: UUID

The linked asset for this surface, e.g. for a Bitcoin volatility surface, this is BTC (tok.btc.bitcoin). Note we will be switching to the Exposure UUID instead in a future release (e.g. tok.btc), once the reference data is available.

vol_model: VolModel

Volatility model used for this surface.

vol_surface_id: UUID

Unique ID for this volatility surface’s collection of attributes; note that surfaces are re-fitted hourly, and so there are going to be many versions over time.

class serenity_types.pricing.derivatives.options.volsurface.VolatilitySurfaceVersion(*, raw: RawVolatilitySurface, interpolated: InterpolatedVolatilitySurface, asOfTime: datetime, buildTime: datetime)

Bases: CamelModel

A single version of a fitted volatility surface, with both the raw and interpolated content.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

as_of_time: datetime

The time window, generally top of the hour, for which we have fitted the volatility surface; latest prices as of this time are used as input to the surface calibration.

build_time: datetime

The actual time of the build; due to DQ or system issues this might be different from as_of_time.

interpolated: InterpolatedVolatilitySurface

The interpolated volatility surface.

raw: RawVolatilitySurface

The raw volatility surface inputs.

serenity_types.pricing.derivatives.rates module

serenity_types.pricing.derivatives.rates module.yield_curve

class serenity_types.pricing.derivatives.rates.yield_curve.CurvePoint(*, tenor: str | None = None, pillarDate: date | None = None, duration: float | None = None, rateSourceType: RateSourceType, rateSources: List[str] | None = None, referenceAssets: List[UUID] | None = None, markPrices: List[float] | None = None, rate: float, discountFactor: float)

Bases: CamelModel

A discrete input point on the curve, with all the metadata describing what is being provided and its source to help reproduce the results.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

discount_factor: float

The input DF value, if rate not provided.

duration: float | None

The duration for this point, expressed as a year fraction.

mark_prices: List[float] | None

In the case where a DF is backed out from the implied forward of a reference asset or basket thereof, the observed prices that should go into the bootstrapping method.

pillar_date: date | None

The specific forward date for the given rate and DF, e.g. the 1W point for today would be the next business day a week ahead.

rate: float

The input rate value, if DF not provided.

rate_source_type: RateSourceType

The type of input being provided for this CurvePoint, e.g. if it’s from a 3M future, this would be FUTURE_PX, while if it’s from traditional rates fixings, it would be FIXINGS.

rate_sources: List[str] | None

The specific rate sources used, e.g. OIS, SOFR or LIBOR; for LENDING_RATE, DeFi or other sources used, e.g. CHAINLINK, IPOR or AAVE. For FUNDING_RATE this holds the UUID for the exchange Organization ID.

reference_assets: List[UUID] | None

In the case where an implied forward is backed out from market observables, the assets observed.

tenor: str | None

A relative date code, e.g. 1Y or 3M.

class serenity_types.pricing.derivatives.rates.yield_curve.CurveUsage(value)

Bases: Enum

Intended usage of this curve, e.g. for discounting or for projection purposes.

DISCOUNTING = 'DISCOUNTING'

Curve points for discounting future cashflows.

PROJECTION = 'PROJECTION'

Curve points indicating the market forward view.

class serenity_types.pricing.derivatives.rates.yield_curve.InterpolatedYieldCurve(*, definition: YieldCurveDefinition, durations: List[float], rates: List[float], discountFactors: List[float])

Bases: CamelModel

A term structure of rates and discount factors built from a RAW representation. This is the version that you should pass in for option valuation purposes, and is suitable for extracting rates and discount factors as well as plotting purposes.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

definition: YieldCurveDefinition

The unique set of parameters used to bootstrap this yield curve.

discount_factors: List[float]

Array of all discount factors (DF’s) along the curve.

durations: List[float]

Array of all durations along the curve, as year fractions.

rates: List[float]

Array of all interpolated rates along the curve.

class serenity_types.pricing.derivatives.rates.yield_curve.InterpolationMethod(value)

Bases: Enum

Specific interpolation method used. Currently only supports flat-forward.

FLAT_FWD = 'FLAT_FWD'

class serenity_types.pricing.derivatives.rates.yield_curve.RateSourceType(value)

Bases: Enum

Sources of rates & discount factors. In the most general case the yield curve can be built from multiple imports, so we tag each CurvePoint that is the input to the interpolated YC with the particular source, e.g. we might have an 8H rate at the short end from perpetual future funding rates and implied forwards backed out from calendar spreads.

FIXING = 'FIXING'

Observed traditional rate fixings.

FUNDING_RATE = 'FUNDING_RATE'

Observed exchange perpetual future funding rate.

FUTURE_PX = 'FUTURE_PX'

Implied forward backed out from observed future prices.

LENDING_RATE = 'LENDING_RATE'

Observed CeFi / OTC or DeFi lending rate.

OPTION_PX = 'OPTION_PX'

Implied forward backed out from observed option prices & spreads.

STAKING_RATE = 'STAKING_RATE'

Observed proof-of-stake protocol staking rate.

class serenity_types.pricing.derivatives.rates.yield_curve.RawYieldCurve(*, points: List[CurvePoint])

Bases: CamelModel

A term structure of yield curve inputs. The RAW representation is offered to clients so they can either do their own interpolation or for diagnostics.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

points: List[CurvePoint]

The list of market data observations that went into this raw yield curve, e.g. rates, discount factors and futures prices corresponding to various tenors.

class serenity_types.pricing.derivatives.rates.yield_curve.YieldCurveAvailability(*, definition: YieldCurveDefinition, asOfTimes: List[datetime])

Bases: CamelModel

Information about version availability for a given YC definition.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

as_of_times: List[datetime]

The list of all available as_of_times in the requested window.

definition: YieldCurveDefinition

Description of the particular yield curve parameters that are available to load.

class serenity_types.pricing.derivatives.rates.yield_curve.YieldCurveDefinition(*, yieldCurveId: UUID, curveUsage: CurveUsage, interpolationMethod: InterpolationMethod, rateSourceType: RateSourceType, underlierAssetId: UUID, displayName: str)

Bases: CamelModel

A uniquely-identified set of YC parameters for bootstrapping a YieldCurve.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

curve_usage: CurveUsage

The curve’s intended purpose, e.g. for discounting or representing market view on forward rates.

display_name: str

Human-readable description of this curve, e.g. OIS (FLAT_FWD)

interpolation_method: InterpolationMethod

The specific interpolator type used to bootstrap this curve.

rate_source_type: RateSourceType

The type of input being provided for this CurvePoint, e.g. if it’s from a 3M future, this would be FUTURE_PX, while if it’s from traditional rates fixings, it would be FIXINGS.

underlier_asset_id: UUID

The linked asset for this curve, e.g. for an Ethereum staking curve, this would be ETH (tok.eth.ethereum). Note we will be switching to the Exposure UUID instead in a future release (e.g. tok.eth), once the reference data is available.

yield_curve_id: UUID

Unique ID for this particular combination of yield curve attributes; note yield curves are bootstrapped daily, and so there are going to be many versions over time.

class serenity_types.pricing.derivatives.rates.yield_curve.YieldCurveVersion(*, raw: RawYieldCurve, interpolated: InterpolatedYieldCurve, asOfTime: datetime, buildTime: datetime)

Bases: CamelModel

A single version of a YieldCurveDefinition, inclusive of its raw and interpolated YC content.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

as_of_time: datetime

The time window, generally UTC midnight, for which we have bootstrapped this yield curve; latest rates / input prices as of this time are used.

build_time: datetime

The actual time of the build; due to DQ or system issues this might be different from as_of_time.

interpolated: InterpolatedYieldCurve

The bootstrapped yield curve.

raw: RawYieldCurve

The raw yield curve input.

Module contents