Volatility Range Risk Scenarios
HTTP Request
POST /api/v1/global/scenarios/volRangeRiskScenarios
Returns Risk scenarios including instruments values and P&Ls for a list of vanilla options, forwards and perps
Risk scenarios are defined by given forward price shifts and list of volatility shifts
We recommend to use the same baseCurrency/quoteCurrency and single source in request instruments array per each request
Supported exchanges and assets (baseCurrency/quoteCurrency)
DERIBIT: BTC/USD, ETH/USD, SOL/USDC, XRP/USDC
OKX: BTC/USD, ETH/USD
BYBIT: BTC/USDC, ETH/USDC, SOL/USDC
The request body model must contain array of riskScenarioInstruments ranging in size from 1 to 100 and also riskScenarioParameters model
Request RiskScenarioInstrument JSON model parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| instrumentId | String | Yes | User defined unique instrument ID |
| size | Num | Yes | Position size (positive for LONG, negative for SHORT) |
| baseCurrency | String | Yes | Base currency ticker:BTC,ETH,SOL,XRP |
| quoteCurrency | String | Yes | Quote currency ticker:USD,USDC |
| source | String | Yes | Exchange sources:DERIBIT,OKX,BYBIT |
| priceMethod | String | Yes | Calculation method: DERIBIT, OKX, BYBIT, OTCEach method represent instrument valuation model used by exchange. As of now 'OTC' equals to 'DERIBIT' |
| instrumentType | String | Yes | Instrument type:CALL,PUT,FORWARD,PERPETUAL,SPOT |
| inverse | Boolean | No | FORWARD/PERPETUAL:false for linear instruments, true for inverse instrumentsCALL/PUT:inverse = true forDERIBIT: BTC/USD, ETH/USD and OKX: BTC/USD, ETH/USDinverse = false forDERIBIT: SOL/USDC, XRP/USDCBYBIT: BTC/USDC, ETH/USDC, SOL/USDCbr/>Not required for instrumentType SPOT |
| volatilityModel | String | No | instrumentType: CALL/PUT SVI, SABR, VANNA_VOLGAVolatility model is calibrated to the Exchange given by the sourceNot required for instrumentType FORWARD/PERPETUAL/SPOT |
| expirationTimestamp | Num | No | instrumentType: CALL/PUT Instrument expiration timestamp (in seconds) Must be >= current timestampNot required for instrumentType SPOT |
| strike | Num | No | instrumentType: CALL/PUT Required. Option strike, must be > 0instrumentType: FORWARD/PERPETUALNot required, but if given, equals to forward strike price. instrumentType: SPOTNot required. |
Request RiskScenarioParameters JSON model parameters
| Parameter | Type | Description |
|---|---|---|
| priceRangeSteps | Num | Number of steps for the priceRangeExample: priceRange = 0.2, priceRangeSteps = 4 The scenarios output will generate 9 different price shifts (scenario) from -4 to 4 [-4, -3, -2, -1, 0, 1, 2, 3, 4]which corresponds to the following percentage forwardPrice shift [-0.2, -0.15, -0.1, -0.05, 0, 0.05, 0.1, 0.15, 0.2] |
| priceRange | Num | Max percent forwardPrice shift |
| volShifts | Num Array | Array of absolute volatility shifts Max array size: 16 elements Example: volShifts = [-0.2, 0.0, 0.2, 0.5].Given 60% impliedVol for option the resulted volatility scenarios are [0.4, 0.6, 0.8, 1.1] |
Response RiskScenarioInstrument JSON model parameters
| Parameter | Type | Description |
|---|---|---|
| instrumentId | String | User defined instrumentId |
| size | Num | User defined size |
| baseCurrency | String | User defined baseCurrency |
| quoteCurrency | String | User defined quoteCurrency |
| source | String | User defined source |
| instrumentType | String | User defined instrumentType |
| inverse | Boolean | User defined inverseNull for instrumentType SPOT |
| volatilityModel | String | User defined volatilityModelNull for instrumentType FORWARD/PERPETUAL/SPOT |
| expirationTimestamp | Num | Instrument expiration timestamp (in seconds) Null for instrumentType SPOT |
| observationTimestamp | Num | Instrument observation timestamp (in seconds) |
| strike | Num | Instrument strike Null for instrumentType SPOT |
| spotPrice | Num | Current spot price |
| forwardPrice | Num | Current forward price (or perpetual price for instrumentType = PERPETUAL)Null for instrumentType SPOT |
| instrumentPrice | Num | Current instrument price Null for instrumentType SPOT |
| volatility | Num | Current instrument implied volatility at strike Null for instrumentType FORWARD/PERPETUAL/SPOT |
| volScenarios | Map | Map of string vol scenario name (Internally defined key) and scenario volatility (value) |
Response RiskScenarioItem JSON model parameters
| Parameter | Type | Description |
|---|---|---|
| scenario | Num | Scenario number |
| spotPrice | Num | Scenario spot price |
| forwardPrice | Num | Scenario forward price |
| price | Map | Map of scenario name (key) and (value) for:CALL/PUT option percent priceFORWARD/PERPETUAL/SPOT instrument price |
| basePl | Map | Map of scenario name (key) and (value) base currency pl for a given scenario |
| quotePl | Map | Map of scenario name (key) and (value) quote currency pl for a given scenario |
| baseValue | Map | Map of scenario name (key) and (value) base currency instrument value for a given scenario |
| baseDelta | Map | Map of scenario name (key) and (value) base currency delta for a given scenario |
| baseNetDelta | Map | Map of scenario name (key) and (value) base currency net delta for a given scenario |
| baseGamma | Map | Map of scenario name (key) and (value) base currency gamma for a given scenario |
| baseTheta | Map | Map of scenario name (key) and (value) base currency theta for a given scenario |
| baseVega | Map | Map of scenario name (key) and (value) base currency vega for a given scenario |
| baseVolga | Map | Map of scenario name (key) and (value) base currency volga for a given scenario |
Request Example
POST /api/v1/global/volRangeRiskScenarios
body
{
"riskScenarioInstruments": [
{
"instrumentId": "BTC-28MAR25-100000-C-INVERSE",
"size": 7,
"baseCurrency": "BTC",
"quoteCurrency": "USD",
"source": "DERIBIT",
"priceMethod": "DERIBIT",
"instrumentType": "CALL",
"inverse": true,
"volatilityModel": "SVI",
"expirationTimestamp": 1743148800,
"strike": 100000
}
],
"riskScenarioParameters": {
"priceRangeSteps": 2,
"priceRange": 0.75,
"volShifts": [
-0.2,
0,
0.3
]
}
}
Response Example
{
"riskScenarioInstrumentResults": [
{
"instrumentId": "BTC-28MAR25-100000-C-INVERSE",
"size": 7.0,
"baseCurrency": "BTC",
"quoteCurrency": "USD",
"source": "DERIBIT",
"instrumentType": "CALL",
"inverse": true,
"volatilityModel": "SVI",
"expirationTimestamp": 1743148800,
"observationTimestamp": 1730471319,
"strike": 100000.0,
"spotPrice": 71438.85,
"forwardPrice": 74749.64000000001,
"instrumentPrice": 0.04754938805491263,
"volatility": 0.561528952921775,
"volScenarios": {
"volScenario0": 0.36152895292177495,
"volScenario1": 0.561528952921775,
"volScenario2": 0.8615289529217749
},
"riskScenarioItems": [
{
"scenario": -2,
"spotPrice": 17859.7125,
"forwardPrice": 18687.410000000003,
"price": {
"volScenario1": 1.952315278781154E-7,
"volScenario2": 3.631735213607019E-4,
"volScenario0": 0.0
},
"basePl": {
"volScenario1": -0.04754919282338475,
"volScenario2": -0.04718621453355193,
"volScenario0": -0.04754938805491263
},
"quotePl": {
"volScenario1": -849.2149134327151,
"volScenario2": -842.7322255325591,
"volScenario0": -849.2184002116738
},
"baseValue": {
"volScenario1": 1.3666206951468077E-6,
"volScenario2": 0.002542214649524913,
"volScenario0": 0.0
},
"baseDelta": {
"volScenario1": 2.0355702253633314E-5,
"volScenario2": 0.018022628418320297,
"volScenario0": 0.0
},
"baseNetDelta": {
"volScenario1": 1.8989081558486507E-5,
"volScenario2": 0.015480413768795383,
"volScenario0": 0.0
},
"baseGamma": {
"volScenario1": 1.514752614978865E-8,
"volScenario2": 5.718681253838012E-6,
"volScenario0": 3.699036612243339E-15
},
"baseTheta": {
"volScenario1": -1.1685239600122903E-7,
"volScenario2": -1.0384539634611145E-4,
"volScenario0": -1.1828410821726712E-14
},
"baseVega": {
"volScenario1": 6.106813957916593E-7,
"volScenario2": 3.5372568203119307E-4,
"volScenario0": 9.601355232943799E-14
},
"baseVanna": {
"volScenario1": 8.386245399036736E-6,
"volScenario2": 0.0021653209289899025,
"volScenario0": 3.113045561702043E-12
},
"baseVolga": {
"volScenario1": 2.4103676656514204E-7,
"volScenario2": 3.840723936284607E-5,
"volScenario0": 1.4216814652074002E-13
}
},
{
"scenario": -1,
"spotPrice": 44649.28125,
"forwardPrice": 46718.52500000001,
"price": {
"volScenario1": 0.0029973085131187673,
"volScenario2": 0.028971750697830277,
"volScenario0": 3.927379514840944E-5
},
"basePl": {
"volScenario1": -0.04455207954179386,
"volScenario2": -0.01857763735708235,
"volScenario0": -0.047510114259764216
},
"quotePl": {
"volScenario1": -1989.2183297339252,
"volScenario2": -829.4781553168766,
"volScenario0": -2121.2924538038483
},
"baseValue": {
"volScenario1": 0.02098115959183137,
"volScenario2": 0.20280225488481193,
"volScenario0": 2.7491656603886606E-4
},
"baseDelta": {
"volScenario1": 0.17517522156888665,
"volScenario2": 0.9193552136237242,
"volScenario0": 0.004720359041740717
},
"baseNetDelta": {
"volScenario1": 0.1541940619770553,
"volScenario2": 0.7165529587389122,
"volScenario0": 0.004445442475701852
},
"baseGamma": {
"volScenario1": 2.575796238980164E-5,
"volScenario2": 6.114688627234845E-5,
"volScenario0": 1.6024277116162831E-6
},
"baseTheta": {
"volScenario1": -4.967609218155835E-4,
"volScenario2": -0.0027759121196084474,
"volScenario0": -1.2810209300430361E-5
},
"baseVega": {
"volScenario1": 0.0025961183808837006,
"volScenario2": 0.00945551215861791,
"volScenario0": 1.0398300494929673E-4
},
"baseVanna": {
"volScenario1": 0.01688479838663,
"volScenario2": 0.028844595258567005,
"volScenario0": 0.001558082737929327
},
"baseVolga": {
"volScenario1": 2.0977900092920495E-4,
"volScenario2": 2.0484855392242755E-4,
"volScenario0": 3.166589677711857E-5
}
},
{
"scenario": 0,
"spotPrice": 71438.85,
"forwardPrice": 74749.64000000001,
"price": {
"volScenario1": 0.04754938805491263,
"volScenario2": 0.11642413120247697,
"volScenario0": 0.012813558216785214
},
"basePl": {
"volScenario1": 0.0,
"volScenario2": 0.06887474314756434,
"volScenario0": -0.03473582983812741
},
"quotePl": {
"volScenario1": 0.0,
"volScenario2": 4920.332444507377,
"volScenario0": -2481.487737431509
},
"baseValue": {
"volScenario1": 0.3328457163843884,
"volScenario2": 0.8149689184173388,
"volScenario0": 0.0896949075174965
},
"baseDelta": {
"volScenario1": 1.8289528278531098,
"volScenario2": 2.782939137617278,
"volScenario0": 0.8682978524997611
},
"baseNetDelta": {
"volScenario1": 1.4961071114687212,
"volScenario2": 1.9679702191999393,
"volScenario0": 0.7786029449822646
},
"baseGamma": {
"volScenario1": 8.949721158739276E-5,
"volScenario2": 6.919101555810553E-5,
"volScenario0": 8.752475079533116E-5
},
"baseTheta": {
"volScenario1": -0.0027616294584344976,
"volScenario2": -0.0050257519979098044,
"volScenario0": -0.0011195117194026016
},
"baseVega": {
"volScenario1": 0.014432530183791908,
"volScenario2": 0.017119079089988422,
"volScenario0": 0.009087298257923515
},
"baseVanna": {
"volScenario1": 0.04035250928086261,
"volScenario2": 0.02525682066859588,
"volScenario0": 0.054876755104168055
},
"baseVolga": {
"volScenario1": 1.6359168804779182E-4,
"volScenario2": 4.158133370924697E-5,
"volScenario0": 4.018727674678084E-4
}
},
{
"scenario": 1,
"spotPrice": 98228.41875000001,
"forwardPrice": 102780.75500000002,
"price": {
"volScenario1": 0.15331372601002022,
"volScenario2": 0.22611565519189758,
"volScenario0": 0.10418048838433439
},
"basePl": {
"volScenario1": 0.10576433795510759,
"volScenario2": 0.17856626713698495,
"volScenario0": 0.05663110032942176
},
"quotePl": {
"volScenario1": 10389.06367747083,
"volScenario2": 17540.282062956125,
"volScenario0": 5562.783437431704
},
"baseValue": {
"volScenario1": 1.0731960820701416,
"volScenario2": 1.582809586343283,
"volScenario0": 0.7292634186903407
},
"baseDelta": {
"volScenario1": 4.2046120348163445,
"volScenario2": 4.387446243438381,
"volScenario0": 4.148279555347311
},
"baseNetDelta": {
"volScenario1": 3.131415952746203,
"volScenario2": 2.8046366570950982,
"volScenario0": 3.4190161366569707
},
"baseGamma": {
"volScenario1": 7.729648579183701E-5,
"volScenario2": 4.939540388747498E-5,
"volScenario0": 1.2066945656792024E-4
},
"baseTheta": {
"volScenario1": -0.0032795809116707986,
"volScenario2": -0.0049333347789067335,
"volScenario0": -0.002122256226547145
},
"baseVega": {
"volScenario1": 0.017139392235737648,
"volScenario2": 0.016804280890226803,
"volScenario0": 0.01722677393735587
},
"baseVanna": {
"volScenario1": 0.004861028086461348,
"volScenario2": 0.006857430194184649,
"volScenario0": -3.791998300739517E-4
},
"baseVolga": {
"volScenario1": -7.860890329054528E-6,
"volScenario2": -1.4057992287046165E-5,
"volScenario0": 5.632402396605775E-7
}
},
{
"scenario": 2,
"spotPrice": 125017.98750000002,
"forwardPrice": 130811.87000000002,
"price": {
"volScenario1": 0.27569450358668607,
"volScenario2": 0.329448054335531,
"volScenario0": 0.24740228786410845
},
"basePl": {
"volScenario1": 0.22814511553177344,
"volScenario2": 0.2818986662806183,
"volScenario0": 0.19985289980919582
},
"quotePl": {
"volScenario1": 28522.24320173731,
"volScenario2": 35242.40393733702,
"volScenario0": 24985.2073301848
},
"baseValue": {
"volScenario1": 1.9298615251068025,
"volScenario2": 2.306136380348717,
"volScenario0": 1.7318160150487591
},
"baseDelta": {
"volScenario1": 5.771080743470329,
"volScenario2": 5.4446898467132465,
"volScenario0": 6.305885093441675
},
"baseNetDelta": {
"volScenario1": 3.841219218363527,
"volScenario2": 3.13855346636453,
"volScenario0": 4.574069078392915
},
"baseGamma": {
"volScenario1": 4.0621987957396654E-5,
"volScenario2": 3.05231933121728E-5,
"volScenario0": 4.260519448398271E-5
},
"baseTheta": {
"volScenario1": -0.0021935883149175298,
"volScenario2": -0.0038798895699720783,
"volScenario0": -9.536705294553385E-4
},
"baseVega": {
"volScenario1": 0.011463894791956352,
"volScenario2": 0.01321595980788489,
"volScenario0": 0.007741132487274927
},
"baseVanna": {
"volScenario1": -0.018559386242288898,
"volScenario2": -0.0052886083245054245,
"volScenario0": -0.03570086956504899
},
"baseVolga": {
"volScenario1": 1.097205775452186E-4,
"volScenario2": 2.5645896625989204E-5,
"volScenario0": 2.9117465563801426E-4
}
}
]
}
]
}