Skip to main content
Version: 8.6.10.4

Schema: TheoExpirySurface (ID: 1970)

TheoExpirySurface records carry a client theoretical volatility surface for one ExpiryKey (ticker + expiration) and one theo model: the centre line, its dynamics, its pricing package and its validity.

The skew shape comes from one of three sources: a parametric function on this record (skewSource = Parametric), an x/y point curve on the TheoExpiryPtSkew record with the same key (PtSkew), or the SpiderRock live expiry skew rescaled to theoVol with a tilt and a curvature multiplier (SRSurface).

The level is a blend of the client vol path and the live SpiderRock atm vol: theoVolAdj = srAtmWeight * srAtmVol + (1 - srAtmWeight) * (theoVol + tvSlope * (uPrc - refUPrc)). srAtmWeight = 1 tracks the SR atm vol, 0 floats on the client path.

The vol response to the underlier (hedge delta) is tvSlope plus the strike-specific slope the skew implies, at any srAtmWeight. tvSlope is either given (dynamics = TvSlope) or derived as ssr * skewSlope(atmStrike), the SR surface's fixed-strike skew slope at the atm strike (dynamics = SSR).

The SRSurface source anchors at refUPrc and is evaluated at the live underlier or at a shocked evalUPrc, which covers both trading (live) and risk scenario (shocked) use.

Every consumer (alt limit, auction responder, risk theo markup, hedge greeks, scanners) resolves the same theo point from this record and applies its own offsets; nothing on this record describes how to trade it.

A surface prices only while theoStatus = Valid, the live underlier is inside [minUBid, maxUAsk] and the record is within maxAgeDays of its timestamp; otherwise consumers hold or skip.

Pricing package precedence, separately for rate, sdiv and discrete dividends: the value on this record, else the client's override table when the matching flag is Yes, else the SpiderRock live value.

METADATA​

AttributeValue
Topic1945-client-theos
MLink TokenClientTheo
MLink EndpointMLink-Live
SRSE ProductSRTheo

Note: The symbol = next to a field number indicates that it is a primary key.

BODY​

#FieldTypeDefault ValueComment
10=ekeyExpiryKeyexpiry this surface belongs to (ticker + expiration)
11=theoModelstring(16)client theo model name; a client may run several models per expiry
12=clientFirmstring(16)client firm this theo model is associated with (controls visibility)
100tickerTickerKeyunderlier ticker (same as ekey.ticker; kept for filtering and joins)
103skewSourceenum : TheoSkewSourceParametric = skewFunc + paramA..N; PtSkew = TheoExpiryPtSkew with the same key; SRSurface = SR live expiry skew rescaled to theoVol (paramA = linear tilt, paramB = curvature multiplier; 0 = SR shape unchanged)
106skewFuncenum : TheoSkewFuncparametric skew function (skewSource = Parametric only); SVI uses paramA..D, SVI_Extended reserves paramE..N
109paramAfloat0parametric curve parameter
112paramBfloat0parametric curve parameter
115paramCfloat0parametric curve parameter
118paramDfloat0parametric curve parameter
121paramEfloat0parametric curve parameter
124paramFfloat0parametric curve parameter
127paramGfloat0parametric curve parameter
130paramHfloat0parametric curve parameter
133paramIfloat0parametric curve parameter
136paramJfloat0parametric curve parameter
139paramKfloat0parametric curve parameter
142paramLfloat0parametric curve parameter
145paramMfloat0parametric curve parameter
148paramNfloat0parametric curve parameter
151theoVolfloat-99client theo vol at the reference strike (x = 0 of the skew source) when uPrc = refUPrc; the level for AtmRatio / AtmDiff point curves and for SRSurface; -99 = none, valid only for a PtSkew curve with yType = Vol on an axis that needs no axisVol
154refUPrcfloat-99underlier price (as quoted, before any contract adjustment) the vol path is anchored at; -99 = the evaluation spot, i.e. no vol path term
157srAtmWeightfloat0w: [0,1]; theoVolAdj = w * srAtmVol + (1 - w) * (theoVol + tvSlope * (uPrc - refUPrc)); 1 = track the SR atm vol, 0 = float on the client vol path; tvSlope drives the hedge delta at any w
160evalUPrcfloat-99underlier price the skew is evaluated at; -99 = the live underlier; a value = a shocked spot, honoured by scenario consumers only, never by trading limits or marks (no scenario consumer reads it yet)
163dynamicsenum : TheoDynamicsTvSlope = use tvSlope as given; SSR = derive tvSlope from the SR skew through ssr; None = TvSlope
166tvSlopefloat0dTheoVol / dUPrc of the client vol path (dynamics = TvSlope); the per-strike vol response is tvSlope plus the skew-implied strike-specific slope
169ssrfloat-99skew-stickiness ratio (dynamics = SSR): tvSlope = ssr * skewSlope(atmStrike), where skewSlope(atmStrike) is the SR surface's fixed-strike skew slope dVol / dStrike at the atm strike; 1 = sticky strike, 0 = sticky delta, equity indices typically above 1; -99 = use the house SSR published on the SR live surface
172minUBidfloat0the surface is valid while the live underlier is inside [minUBid, maxUAsk]; 0 = no lower bound
175maxUAskfloat0upper bound of the valid underlier range; 0 = no upper bound
178maxAgeDaysint1days after timestamp the record stays current (a rules-based record, srAtmWeight = 1 or SSR, can be weekly); 0 = 1; the resolver caps it at 30
181theoSDivfloat-99theo sdiv (annualized continuous, decimal); -99 = fall through to the override table (if userSDivOverride = Yes) else SR live sdiv
184theoRatefloat-99theo rate (annualized continuous, decimal; 0.05 = 5 pct); -99 = fall through to the override table (if userRateOverride = Yes) else SR live rate
187userRateOverrideenum : YesNoNouse the UserRateOverride curve instead of the SR rate curve when theoRate is not set
190userSDivOverrideenum : YesNoNouse the UserSDivOverride record instead of SR sdiv when theoSDiv is not set
193userDDivOverrideenum : YesNoNouse the UserDividendOverride record instead of SR discrete dividends
196theoStatusenum : TheoSurfaceStatusValid is the only status consumers price from; None and Invalid hold
199modifiedBystring(24)user who last modified this record
202modifiedInenum : SysEnvironmentsource of the last modification (SRSE, MLink, tool)
205timestampDateTimetimestamp of last modification; the record is current for maxAgeDays after this
208commenttext1free-form client note; not read by any consumer

Get Schema API Call​

import requests 

# Replace with your desired MLINK URL 
MLINK_PROD_URL = 'https://mlink-live.nms.saturn.spiderrockconnect.com/rest/json'

# Replace with your MLINK API Key
API_KEY = 'XXXX-XXXX-XXXX-XXXX'

# Replace with your desired MsgType.  
MSG_TYPE = 'TheoExpirySurface'

# Request Parameters for Get Schema Of The MsgType
params = {
    # Required Parameters
    "apiKey": API_KEY,
    "cmd": 'getschema',
    "msgType": MSG_TYPE, 
}

response = requests.get(MLINK_PROD_URL, params=params)

Get Msg API Call​

import requests 

# Replace with your desired MLINK URL 
MLINK_PROD_URL = 'https://mlink-live.nms.saturn.spiderrockconnect.com/rest/json'

# Replace with your MLINK API Key
API_KEY = 'XXXX-XXXX-XXXX-XXXX'

# Replace with your desired MsgType.  
MSG_TYPE = 'TheoExpirySurface'

# Replace with your pkey value for getting the specific message desired
PKEY = 'ReplaceThisValueForTheQueryToWork'

# Replace with your desired view. A "|" separated list of views can be provided
# If no view is provided, all views will be returned. 
VIEW = 'ticker|skewSource|skewFunc|paramA|paramB|paramC|paramD|paramE|paramF|paramG|paramH|paramI|paramJ|paramK|paramL|paramM|paramN|theoVol|refUPrc|srAtmWeight|evalUPrc|dynamics|tvSlope|ssr|minUBid|maxUAsk|maxAgeDays|theoSDiv|theoRate|userRateOverride|userSDivOverride|userDDivOverride|theoStatus|modifiedBy|modifiedIn|timestamp|comment'

# Replace with your desired where clause.
# a string in the form "field1:eq:valuse" or "(field1:ne:value1 & field1:ne:value2)
# "WHERE" clauses can contain the following comparison symbols:
# :gt: is greater than
# :ge: is greater than or equal to
# :lt: is less than
# :le: is less than or equal to
# :eq: is equal
# :ne: is not equal
# %26 is an AND statement
# | is an OR statement
# :sw: is starts with
# :ew: is ends with
# :cv: is contains values
# :nv: is does not contain value
# :cb: is contained between (two dates for instance) separated by '$'
WHERE = 'theoModel:eq:ExampleString'

# Request Parameters for getmsg Of The MsgType
params = {
    # Required Parameters
    "apiKey": API_KEY,
    "cmd": 'getmsg',
    "pkey": PKEY,
    "msgType": MSG_TYPE,
    # Optional Parameters
    "view": VIEW, 
    "where": WHERE
}

response = requests.get(MLINK_PROD_URL, params=params)

Get Msgs API Call​

import requests 

# Replace with your desired MLINK URL 
MLINK_PROD_URL = 'https://mlink-live.nms.saturn.spiderrockconnect.com/rest/json'

# Replace with your MLINK API Key
API_KEY = 'XXXX-XXXX-XXXX-XXXX'

# Replace with your desired MsgType.  
MSG_TYPE = 'TheoExpirySurface'

# Replace with your desired view. A "|" separated list of views can be provided
# If no view is provided, all views will be returned
VIEW = 'ticker|skewSource|skewFunc|paramA|paramB|paramC|paramD|paramE|paramF|paramG|paramH|paramI|paramJ|paramK|paramL|paramM|paramN|theoVol|refUPrc|srAtmWeight|evalUPrc|dynamics|tvSlope|ssr|minUBid|maxUAsk|maxAgeDays|theoSDiv|theoRate|userRateOverride|userSDivOverride|userDDivOverride|theoStatus|modifiedBy|modifiedIn|timestamp|comment'

# Replace with your desired where clause.
# a string in the form "field1:eq:value" or "(field1:ne:value1 & field1:ne:value2)
# "WHERE" clauses can contain the following comparison symbols:
# :gt: is greater than
# :ge: is greater than or equal to
# :lt: is less than
# :le: is less than or equal to
# :eq: is equal
# :ne: is not equal
# %26 is an AND statement
# | is an OR statement
# :sw: is starts with
# :ew: is ends with
# :cv: is contains values
# :nv: is does not contain value
# :cb: is contained between (two dates for instance) separated by '$'
WHERE = 'theoModel:eq:ExampleString'

# Replace with your desired limit of how many messages you receive. The default limit is 500
LIMIT = 500

# Order clause eg. "(field1:DESC | field1:ASC | field2:DESC:ABS | field2:ASC:ABS" (default is unordered; default is faster)
ORDER = 'ticker:ASC'

# Request Parameters for getmsgs Of The MsgType
params = {
    # Required Parameters
    "apiKey": API_KEY,
    "cmd": 'getmsgs',
    "msgType": MSG_TYPE,
    # Optional Parameters
    "view": VIEW, 
    "where": WHERE,
    "limit": LIMIT,
    "order": ORDER
}

response = requests.get(MLINK_PROD_URL, params=params)

Get Aggregate API Call​

import requests 

# Replace with your desired MLINK URL 
MLINK_PROD_URL = 'https://mlink-live.nms.saturn.spiderrockconnect.com/rest/json'

# Replace with your MLINK API Key
API_KEY = 'XXXX-XXXX-XXXX-XXXX'

# Replace with your desired MsgType.  
MSG_TYPE = 'TheoExpirySurface'

# Replace with fields you want to see aggregate values for. A "|" separated list of measures should be provided
MEASURE = 'ticker|skewSource|skewFunc|paramA|paramB|paramC|paramD|paramE|paramF|paramG|paramH|paramI|paramJ|paramK|paramL|paramM|paramN|theoVol|refUPrc|srAtmWeight|evalUPrc|dynamics|tvSlope|ssr|minUBid|maxUAsk|maxAgeDays|theoSDiv|theoRate|userRateOverride|userSDivOverride|userDDivOverride|theoStatus|modifiedBy|modifiedIn|timestamp|comment'

# Replace with fields you want to see aggregated. A "|" separated list of fields should be provided
GROUP = 'skewSource|skewFunc|dynamics|userRateOverride|userSDivOverride|userDDivOverride|theoStatus|modifiedIn'

# Replace with your desired where clause.
# a string in the form "field1:eq:value" or "(field1:ne:value1 & field1:ne:value2)
# "WHERE" clauses can contain the following comparison symbols:
# :gt: is greater than
# :ge: is greater than or equal to
# :lt: is less than
# :le: is less than or equal to
# :eq: is equal
# :ne: is not equal
# %26 is an AND statement
# | is an OR statement
# :sw: is starts with
# :ew: is ends with
# :cv: is contains values
# :nv: is does not contain value
# :cb: is contained between (two dates for instance) separated by '$'
WHERE = 'theoModel:eq:ExampleString'

# Request Parameters for getaggregate Of The MsgType
params = {
    # Required Parameters
    "apiKey": API_KEY,
    "cmd": 'getaggregate',
    "msgType": MSG_TYPE,
    "measure": MEASURE,
    "group": GROUP,
    # Optional Parameters
    "where": WHERE,
}

response = requests.get(MLINK_PROD_URL, params=params)

Get Count API Call​

import requests 

# Replace with your desired MLINK URL 
MLINK_PROD_URL = 'https://mlink-live.nms.saturn.spiderrockconnect.com/rest/json'

# Replace with your MLINK API Key
API_KEY = 'XXXX-XXXX-XXXX-XXXX'

# Replace with your desired MsgType.  
MSG_TYPE = 'TheoExpirySurface'

# Replace with your desired where clause.
# a string in the form "field1:eq:value" or "(field1:ne:value1 & field1:ne:value2)
# "WHERE" clauses can contain the following comparison symbols:
# :gt: is greater than
# :ge: is greater than or equal to
# :lt: is less than
# :le: is less than or equal to
# :eq: is equal
# :ne: is not equal
# %26 is an AND statement
# | is an OR statement
# :sw: is starts with
# :ew: is ends with
# :cv: is contains values
# :nv: is does not contain value
# :cb: is contained between (two dates for instance) separated by '$'
WHERE = 'theoModel:eq:ExampleString'

# Request Parameters for getCount Of The MsgType
params = {
# Required Parameters
"apiKey": API_KEY,
"cmd": 'getcount',
"msgType": MSG_TYPE,
# Optional Parameters
"where": WHERE,
}

response = requests.get(MLINK_PROD_URL, params=params)

Post Msgs API Call​

import requests

# Replace with your desired MLINK URL
MLINK_PROD_URL = 'https://mlink-live.nms.saturn.spiderrockconnect.com/rest/json'

# Replace with your MLINK API Key
API_KEY = 'XXXX-XXXX-XXXX-XXXX'

# Request Parameters
params = {
    # Required Parameters
    "apiKey": API_KEY,
    "cmd": 'postmsgs',
    "postaction": "I", # (I)nsert, (U)pdate, (D)elete, or (R)eplace
    "postmerge": "Y", # (Y)es or (N)o
}

payload = {
    "header": {
        "mTyp": "TheoExpirySurface"
    },
    "message": {
        "pkey": {
            "ekey": {
                "at": "EQT",
                "ts": "NMS",
                "tk": "AAPL",
                "dt": "2025-01-01"
            },
            "theoModel": "exampleString", // string
            "clientFirm": "exampleString" // string
        },
        "ticker": {
            "at": "EQT",
            "ts": "NMS",
            "tk": "AAPL"
        },
        "skewSource": "enumValue", // enum(TheoSkewSource) - None, Parametric, PtSkew, SRSurface
        "skewFunc": "enumValue", // enum(TheoSkewFunc) - None, SVI, SVI_Extended
        "paramA": 0, // float. Default=0
        "paramB": 0, // float. Default=0
        "paramC": 0, // float. Default=0
        "paramD": 0, // float. Default=0
        "paramE": 0, // float. Default=0
        "paramF": 0, // float. Default=0
        "paramG": 0, // float. Default=0
        "paramH": 0, // float. Default=0
        "paramI": 0, // float. Default=0
        "paramJ": 0, // float. Default=0
        "paramK": 0, // float. Default=0
        "paramL": 0, // float. Default=0
        "paramM": 0, // float. Default=0
        "paramN": 0, // float. Default=0
        "theoVol": -99, // float. Default=-99
        "refUPrc": -99, // float. Default=-99
        "srAtmWeight": 0, // float. Default=0
        "evalUPrc": -99, // float. Default=-99
        "dynamics": "enumValue", // enum(TheoDynamics) - None, TvSlope, SSR
        "tvSlope": 0, // float. Default=0
        "ssr": -99, // float. Default=-99
        "minUBid": 0, // float. Default=0
        "maxUAsk": 0, // float. Default=0
        "maxAgeDays": 1, // int. Default=1
        "theoSDiv": -99, // float. Default=-99
        "theoRate": -99, // float. Default=-99
        "userRateOverride": "No", // enum(YesNo) - None, Yes, No. Default=No
        "userSDivOverride": "No", // enum(YesNo) - None, Yes, No. Default=No
        "userDDivOverride": "No", // enum(YesNo) - None, Yes, No. Default=No
        "theoStatus": "enumValue", // enum(TheoSurfaceStatus) - None, Valid, Invalid
        "modifiedBy": "exampleString", // string
        "modifiedIn": "enumValue", // enum(SysEnvironment) - None, Neptune, Pluto, V7_Stable, V7_Latest, Saturn, Venus, Mars, SysTest, V7_Current
        "timestamp": "2025-01-01 12:00:00.000000", // yyyy-MM-dd HH:mm:ss.SSSSSS
        "comment": "exampleString" // text1
    }
}

response = requests.post(MLINK_PROD_URL, params=params, json=payload)
Table of Contents