Skip to main content
Version: Upcoming

Schema: SpdrTheoExpSurface (ID: 1960)

SpdrTheoExpSurface records reprent a client theoretical volatility surface for a ExpiryKey (ticker + expiration). These records can either directly specify parameters to be used in a parameterized surface function or can link to a record (eg. SpdrTheoExp2PtCurve) containing x/y points sampling a client constructed curve. Alternatively, they can specify that a SpiderRock implied skew curve should be used along with client supplied atm volatilities.

Surface dynamics can be specified in multiple ways with these records and a number of pricing parameter overrides are also available.

See the technical note on client supplied theoretical surfaces for more details.

METADATA​

AttributeValue
Topic1945-client-theos
MLink TokenClientTheo
SRSE ProductSRTheo

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

BODY​

#FieldTypeDefault ValueComment
10=ekeyExpiryKey
11=theoModelstring(16)
12=clientFirmstring(16)client firm this theo model is associated with (controls visibility)
100tickerTickerKey
103skewFuncenum : SkewFunc
106volTimeUnitsenum : VolTimeUnitsDefaultdefault uses the SR native time metric (trading minutes); V6 is a prior SR metric (trading days)
109uPrcRefRuleenum : uPrcRefRuleNbboMid
112refUPrcfloat-1-1 = use SR uPrc @ record insert
115refUPrcWeightfloat0w: [0,1];adjRefUPrc = w * refUPrc + (1 - w) * uPrc;note: w=1 implies sticky strike behavior;w=0 implies sticky delta behavior
118refSRAtmfloat-1-1 = use SR surface atm @ record insert
121refSRAtmWeightfloat0w: [0,1];theoVolAdj = theoVol + tvSlope * (uPrc - refUPrc) + w * (liveSRAtm - refSRAtm)
124paramAfloat0param A - J are inputs to the skewFunc model selected above
127paramBfloat0
130paramCfloat0
133paramDfloat0
136paramEfloat0
139paramFfloat0
142paramGfloat0
145paramHfloat0
148paramIfloat0
151paramJfloat0
154theoVolfloattheo volatility @ hypothetical atm strike (note: hypothetical atm strike depends on the definition of xAxis implied by the skewFunc model;usually the strike where xAxis = 0)
157bOpnVolfloat0buy open vol
160bClsVolfloat0buy close vol
163sOpnVolfloat0sell open vol
166sClsVolfloat0sell close vol
169bOpnEdgefloat0edge spread to open when buying
172bClsEdgefloat0edge spread to close when buying
175sOpnEdgefloat0edge spread to open when selling
178sClsEdgefloat0edge spread to close when selling
181buySellConventionenum : BuySellConventionNone
184lnDDivfloat-99(depricated)
187shDDivfloat-99(depricated)
190lnSDivfloat-99long sdiv
193shSDivfloat-99short sdiv
196tvSlopefloat0tvSlope = dTheoVol / dUPrc;theoVolAdj = theoVol + tvSlope * (uPrc - refUPrc). Note: tvSlope affects the calculation of theoSurface veSlope values which in turn affect hedgeDelta calculations when account.hedgeType = 'TvS'
199divRuleenum : DivRuleUseSRImpliedspecifies how DDiv and SDiv values will be incorporated
202userRateOverrideenum : YesNoNouse rate from the UserRateOverride table instead of SR Rate curve
205userSDivOverrideenum : YesNoNouse sdiv from the UserSDivOverride table instead of SR SDiv
208userDDivOverrideenum : YesNoNouse dividends from the UserDividendOverride table instead of SR Dividends
211minUBidfloat0any non-hold status will revert to markup if live uMid is outside of [minUBid, maxUAsk]
214maxUAskfloat0
217theoStatusenum : TheoStatusHold
220commentstring(16)
223updatedDateTimedatetime of last record update. will default to current datetime on record load of not supplied
226modifiedBystring(24)user who last modified this record
229modifiedInenum : SysEnvironment
232timestampDateTimetimestamp of last modification

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 = 'SpdrTheoExpSurface'

# 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 = 'SpdrTheoExpSurface'

# 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|skewFunc|volTimeUnits|uPrcRefRule|refUPrc|refUPrcWeight|refSRAtm|refSRAtmWeight|paramA|paramB|paramC|paramD|paramE|paramF|paramG|paramH|paramI|paramJ|theoVol|bOpnVol|bClsVol|sOpnVol|sClsVol|bOpnEdge|bClsEdge|sOpnEdge|sClsEdge|buySellConvention|lnDDiv|shDDiv|lnSDiv|shSDiv|tvSlope|divRule|userRateOverride|userSDivOverride|userDDivOverride|minUBid|maxUAsk|theoStatus|comment|updated|modifiedBy|modifiedIn|timestamp'

# 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 = 'SpdrTheoExpSurface'

# 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|skewFunc|volTimeUnits|uPrcRefRule|refUPrc|refUPrcWeight|refSRAtm|refSRAtmWeight|paramA|paramB|paramC|paramD|paramE|paramF|paramG|paramH|paramI|paramJ|theoVol|bOpnVol|bClsVol|sOpnVol|sClsVol|bOpnEdge|bClsEdge|sOpnEdge|sClsEdge|buySellConvention|lnDDiv|shDDiv|lnSDiv|shSDiv|tvSlope|divRule|userRateOverride|userSDivOverride|userDDivOverride|minUBid|maxUAsk|theoStatus|comment|updated|modifiedBy|modifiedIn|timestamp'

# 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 = 'SpdrTheoExpSurface'

# Replace with fields you want to see aggregate values for. A "|" separated list of measures should be provided
MEASURE = 'ticker|skewFunc|volTimeUnits|uPrcRefRule|refUPrc|refUPrcWeight|refSRAtm|refSRAtmWeight|paramA|paramB|paramC|paramD|paramE|paramF|paramG|paramH|paramI|paramJ|theoVol|bOpnVol|bClsVol|sOpnVol|sClsVol|bOpnEdge|bClsEdge|sOpnEdge|sClsEdge|buySellConvention|lnDDiv|shDDiv|lnSDiv|shSDiv|tvSlope|divRule|userRateOverride|userSDivOverride|userDDivOverride|minUBid|maxUAsk|theoStatus|comment|updated|modifiedBy|modifiedIn|timestamp'

# Replace with fields you want to see aggregated. A "|" separated list of fields should be provided
GROUP = 'skewFunc|volTimeUnits|uPrcRefRule|buySellConvention|divRule|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 = 'SpdrTheoExpSurface'

# 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": "SpdrTheoExpSurface"
    },
    "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"
        },
        "skewFunc": "enumValue", // enum(SkewFunc) - None, ICurve, SRDynCurve, TheoSpline, SVI
        "volTimeUnits": "Default", // enum(VolTimeUnits) - Default, V6. Default=Default
        "uPrcRefRule": "NbboMid", // enum(uPrcRefRule) - NbboMid, NbboCross. Default=NbboMid
        "refUPrc": -1, // float. Default=-1
        "refUPrcWeight": 0, // float. Default=0
        "refSRAtm": -1, // float. Default=-1
        "refSRAtmWeight": 0, // float. Default=0
        "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
        "theoVol": 1.0, // float
        "bOpnVol": 0, // float. Default=0
        "bClsVol": 0, // float. Default=0
        "sOpnVol": 0, // float. Default=0
        "sClsVol": 0, // float. Default=0
        "bOpnEdge": 0, // float. Default=0
        "bClsEdge": 0, // float. Default=0
        "sOpnEdge": 0, // float. Default=0
        "sClsEdge": 0, // float. Default=0
        "buySellConvention": "None", // enum(BuySellConvention) - None, Minimum, BSSpread, BSPctSprd, BSOffsetPts, BSOffsetPct. Default=None
        "lnDDiv": -99, // float. Default=-99
        "shDDiv": -99, // float. Default=-99
        "lnSDiv": -99, // float. Default=-99
        "shSDiv": -99, // float. Default=-99
        "tvSlope": 0, // float. Default=0
        "divRule": "UseSRImplied", // enum(DivRule) - UseSRImplied, SDivValue, SDivOffset, MinMaxValue. Default=UseSRImplied
        "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
        "minUBid": 0, // float. Default=0
        "maxUAsk": 0, // float. Default=0
        "theoStatus": "Hold", // enum(TheoStatus) - Hold, Auto, Scanner, Markup, CloseOnly. Default=Hold
        "comment": "exampleString", // string
        "updated": "2025-01-01 12:00:00.000000", // yyyy-MM-dd HH:mm:ss.SSSSSS
        "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
    }
}

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