cURL Python Node Ruby

Introduction

API endpoint:

https://api.everysk.com

Everysk API is organized around the open standard protocol REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. All API responses are returned in JSON, including errors.

We also have some specific language examples to make integration easier. You can switch the programming language of the examples with the tabs in the top right. You can request a Trial API Key at Contact Us.

Versioning

You can pass a specific API version such as:

https://api.everysk.com/v2

When we make backwards-incompatible changes to the API, we release new versions. Each API we provide has a separate version (listed below).

Version Status
v2 Current
v1 Deprecated

The current version of the Everysk API is v2.

Authentication

A request example with arguments:

curl -X POST \
  -H "Content-Type: application/json" \
  -u YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN \
  -d {} \
  https://api.everysk.com/v2/health_check
# Alternatively pass a Bearer token in an Authorization header.

# Use:
  -H "Authorization: Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN"

# Instead of:
  -u YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN
import requests

url = 'https://api.everysk.com/v2/health_check'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
}
payload = {}

response = requests.request('POST', url, json=payload, headers=headers)

print(response.text)
var request = require("request");

var url = 'https://api.everysk.com/v2/health_check';
var headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
};
var payload = {};

var options = {
    method: 'POST',
    url: url,
    headers: headers,
    body: payload,
    json: true
};
request(options, function (error, response, body) {
    if (error) throw new Error(error);

    console.log(body);
});
require 'uri'
require 'net/http'
require 'json'

url = URI("https://api.everysk.com/v2/health_check")
headers = {
    'Content-Type'=> 'application/json',
    'Authorization'=> 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
}
payload = {}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
req = Net::HTTP::Post.new(url.path, initheader=headers)
req.body = payload.to_json
response = http.request(req)

puts response.read_body

The above call returns a JSON structure like this:

{
  "api_status": "OK",
  "version": "v2",
  "name": "Everysk API"
}

The API uses exclusive POST HTTP method to access resources URI. In the POST, you represent the arguments of methods in JSON encoded dictionary in the request body.

The maximum JSON encoded payload size is 1MB. Be sure to encode the following HTTP Content-Type header for your requests: "application/json"

Authenticate your account when using the API by including your secret API key in the request. Authentication to the API is performed via HTTP Basic Authentication. In short, you will use your Everysk API Account SID as the username and your Auth Token as the password for HTTP Basic authentication. API requests without authentication will fail. You can manage your API keys in the API Settings. Be sure to keep your Account SID and Auth Token secret.

The API is served over HTTPS. Calls made over plain HTTP will fail.

Errors

An error response example:

{
  "code": 400,
  "message": "Bad Request - Please visit https://www.everysk.com/api/docs for more information."
}

The API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.), and codes in the 5xx range indicate an error with Everysk's servers.

HTTP Status Code Summary:

Code Message Description
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable. This could be due to a missing required field, an invalid parameter, etc.
401 Unauthorized No valid credentials provided.
403 Forbidden The credentials provided do not have permission to access the requested resource.
404 Not Found The requested resource doesn't exist.
429 Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
5XX Server Errors Something went wrong with Everysk Servers.

Rate limiting

Example on how to check the remaining requests in the current window:

curl -X POST \
  -i https://api.everysk.com/v2/health_check \
  -u YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN

Example of HTTP header response:

HTTP/2 200
content-type: application/json; charset=utf-8
x-everysk-request-id: ed888caa18904ca5b5f05e305ab11551
x-everysk-request-duration: 81.3500881195
x-everysk-rate-limit-allowed: 60
x-everysk-rate-limit-remaining: 49
x-everysk-rate-limit-reset: 10

Example rate limit error response:

{
  "code": 429,
  "message": "Too Many Requests - You've exceeded the rate limit for your api account SID. Please try again using truncated exponential backoff."
}

Everysk API is rate-limited to 60 requests per minute as default, depending on the applicable plan. This safety limit is set by Everysk to protect the integrity of our system. If you exceed the limit established in your plan, any request you send will return a 429 error: "Too Many Requests". If you require a higher limit, please contact us.

The API will respond to every request with five HTTP headers, providing additional information about the status of the request:

Header Description
X-Everysk-Request-Id This header provides an unique identifier for your request. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.
X-Everysk-Request-Duration This header specifies the amount of time that Everysk servers spent processing this request, in milliseconds.
X-Everysk-Rate-Limit-Allowed This header provides the number of requests you are allowed per 1 minute window.
X-Everysk-Rate-Limit-Remaining This header provides the number of requests you can make before hitting the limit.
X-Everysk-Rate-Limit-Reset This header provides the remaining window before the rate limit resets, in seconds.

Risk Attribution

To calculate the MCTR, run the following:

curl -X POST \
  -H "Content-Type: application/json" \
  -u YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN \
  -d '{ \
      "securities": [ \
        { \
          "id": "id1", \
          "symbol": "AAPL", \
          "quantity": 1000.0 \
        }, \
        { \
          "id": "id2", \
          "symbol": "SIE:XETR", \
          "quantity": 750.0 \
        }, \
        { \
          "id": "id3", \
          "symbol": "SPY 20180316 P280 4.82", \
          "quantity": 50.0 \
        }, \
        { \
          "id": "id4", \
          "symbol": "SPY 20180316 P270 2.10", \
          "quantity": -50.0 \
        }, \
        {
          "id": "id5", \
          "symbol": "SPY 20180316 C285 2.08", \
          "quantity": -50.0 \
        } \
      ], \
      "date": "20180118", \
      "projection": ["SPY"] \
  }' \
  https://api.everysk.com/v2/calculations/risk_attribution
import requests

url = 'https://api.everysk.com/v2/calculations/risk_attribution'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
}
payload = {
    "securities": [
      {
        "id": "id1",
        "symbol": "AAPL",
        "quantity": 1000.0
      },
      {
        "id": "id2",
        "symbol": "SIE:XETR",
        "quantity": 750.0
      },
      {
        "id": "id3",
        "symbol": "SPY 20180316 P280 4.82",
        "quantity": 50.0
      },
      {
        "id": "id4",
        "symbol": "SPY 20180316 P270 2.10",
        "quantity": -50.0
      },
      {
        "id": "id5",
        "symbol": "SPY 20180316 C285 2.08",
        "quantity": -50.0
      }
    ],
    "date": "20180118",
    "projection": ["SPY"]
}

response = requests.request('POST', url, json=payload, headers=headers)

print(response.text)
var request = require("request");

var url = 'https://api.everysk.com/v2/calculations/risk_attribution';
var headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
};
var payload = {
    "securities": [
      {
        "id": "id1",
        "symbol": "AAPL",
        "quantity": 1000.0
      },
      {
        "id": "id2",
        "symbol": "SIE:XETR",
        "quantity": 750.0
      },
      {
        "id": "id3",
        "symbol": "SPY 20180316 P280 4.82",
        "quantity": 50.0
      },
      {
        "id": "id4",
        "symbol": "SPY 20180316 P270 2.10",
        "quantity": -50.0
      },
      {
        "id": "id5",
        "symbol": "SPY 20180316 C285 2.08",
        "quantity": -50.0
      }
    ],
    "date": "20180118",
    "projection": ["SPY"]
};

var options = {
    method: 'POST',
    url: url,
    headers: headers,
    body: payload,
    json: true
};
request(options, function (error, response, body) {
    if (error) throw new Error(error);

    console.log(body);
});
require 'uri'
require 'net/http'
require 'json'

url = URI("https://api.everysk.com/v2/calculations/risk_attribution")
headers = {
    'Content-Type'=> 'application/json',
    'Authorization'=> 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
}
payload = {
    "securities"=> [
      {
        "id"=> "id1",
        "symbol"=> "AAPL",
        "quantity"=> 1000.0
      },
      {
        "id"=> "id2",
        "symbol"=> "SIE:XETR",
        "quantity"=> 750.0
      },
      {
        "id"=> "id3",
        "symbol"=> "SPY 20180316 P280 4.82",
        "quantity"=> 50.0
      },
      {
        "id"=> "id4",
        "symbol"=> "SPY 20180316 P270 2.10",
        "quantity"=> -50.0
      },
      {
        "id"=> "id5",
        "symbol"=> "SPY 20180316 C285 2.08",
        "quantity"=> -50.0
      }
    ],
    "date"=> "20180118",
    "projection"=> ["SPY"]
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
req = Net::HTTP::Post.new(url.path, initheader=headers)
req.body = payload.to_json
response = http.request(req)

puts response.read_body

The above call returns the following JSON object:

{
  "risk_attribution": {
    "results": [
      {
        "id": "id3",
        "mctr": [
          {
            "projection": "SPY",
            "value": 0.096956913445985
          },
          {
            "projection": "residual",
            "value": -0.001587145732826
          }
        ]
      },
      {
        "id": "id5",
        "mctr": [
          {
            "projection": "SPY",
            "value": 0.067216469014247
          },
          {
            "projection": "residual",
            "value": 0.001866791196407
          }
        ]
      },
      {
        "id": "id1",
        "mctr": [
          {
            "projection": "SPY",
            "value": -0.030214670480493
          },
          {
            "projection": "residual",
            "value": 0.061500104578984
          }
        ]
      },
      {
        "id": "id2",
        "mctr": [
          {
            "projection": "SPY",
            "value": -0.022257840090924
          },
          {
            "projection": "residual",
            "value": 0.017627694218011
          }
        ]
      },
      {
        "id": "id4",
        "mctr": [
          {
            "projection": "SPY",
            "value": -0.047619053005682
          },
          {
            "projection": "residual",
            "value": 0.001029368761176
          }
        ]
      }
    ],
    "unmapped_tickers": []
  }
}

The goal of risk attribution is to calculate the contribution to the overall portfolio risk from each security. We use a measure called Marginal Contribution to Total Risk (MCTR) for risk attribution.

To compute the risk attribution (MCTR) for a portfolio, make an HTTP POST to your calculation resource URI:

HTTP Request

POST /calculations/risk_attribution

HTTP Parameters

Parameter Description
securities array REQUIRED It is an array of objects that describes the securities in the portfolio. Each object represents a security with an unique id, symbol, quantity and label. For more details click here.
date string date optional, default is null (today) Portfolio date in the format: "YYYYMMDD". The Portfolio Date is important because it instructs the API to use the market conditions and security prices prevailing on that date. Therefore, historical portfolios will be calculated without look ahead. In order to run the portfolio using market conditions prevailing today, use null. The furthest historical date allowed by the API is a year ago from today.
base_currency string optional, default is "USD" 3-letter ISO 4217 code for currency. Portfolios can have their base currency changed via the API call. By changing the base currency, a new set of currency risks is automatically taken into account. For all supported currencies click here.
nlv double optional, default is null (calculated) The net liquidating value of the portfolio (also called NAV). When not supplied by user, the API will calculate the net liquidating value of all the cash securities. Securities traded on margin are assumed to have nlv zero. Supplying an NLV effectively reconciles the margin.
horizon integer optional, default is 5 Forecast horizon in days: 1, 5, 20, 60 or 120.
aggregation string optional, default is "position" (no aggregation) Aggregation computes individual security MCTR's and aggregates them according to the supported criteria: "position", "liquidity", "market_capitalization", "sector", "country_of_risk", "implied_rating", "duration" or "aggregation_label". For more information click here.
projection array optional, default is ["IND:SPX"] User supplied array of securities to be used as a top-down factor model. Maximum number of elements in the projection array is 10
volatility_half_life integer optional, default is 0 Half life of volatility information in months: 0 (no decay), 2, 6 or 12.
correlation_half_life integer optional, default is 6 Half life of correlation information in months: 0 (no decay), 2, 6 or 12.
risk_measure string optional, default is "volatility" Specifies the forward looking portfolio risk property being measured by MCTR, such as: "volatility", "var" or "cvar". "volatility": forward looking annualized volatility of the P&L distribution for the portfolio. "var": Value-at-Risk of the P&L distribution for the portfolio. "cvar": Conditional Value-at-Risk of the P&L distribution for the portfolio.
use_drift boolean optional, default is false A flag to determine if the ex-ante simulations are centered on zero or if the historical mean should be taken into account. For more details click here.
forecasts array optional, default is null An array of objects that represents expected prices and probabilities for a security in the future. For more details click here.
volatility_surface array optional, default is null An array of objects that represents the volatility surface for a security. The volatility surface is parameterized by time to expiration in years and moneyness. For more details click here.
filter string optional, default is null (use the whole portfolio) Filter Expression: When present it runs a pre-processing calculation to select securities that satisfy certain criteria. For more details click here.

Stress Test

To calculate the CVaR-, EV, CVaR+, run the following:

curl -X POST \
  -H "Content-Type: application/json" \
  -u YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN \
  -d '{ \
      "securities": [ \
        { \
          "id": "id1", \
          "symbol": "AAPL", \
          "quantity": 1000.0 \
        }, \
        { \
          "id": "id2", \
          "symbol": "SIE:XETR", \
          "quantity": 750.0 \
        }, \
        { \
          "id": "id3", \
          "symbol": "SPY 20180316 P280 4.82", \
          "quantity": 50.0 \
        }, \
        { \
          "id": "id4", \
          "symbol": "SPY 20180316 P270 2.10", \
          "quantity": -50.0 \
        }, \
        {
          "id": "id5", \
          "symbol": "SPY 20180316 C285 2.08", \
          "quantity": -50.0 \
        } \
      ], \
      "date": "20180118", \
      "projection": ["SPY"], \
      "shock": "IND:SPX", \
      "magnitude": -0.1 \
  }' \
  https://api.everysk.com/v2/calculations/stress_test
import requests

url = 'https://api.everysk.com/v2/calculations/stress_test'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
}
payload = {
    "securities": [
      {
        "id": "id1",
        "symbol": "AAPL",
        "quantity": 1000.0
      },
      {
        "id": "id2",
        "symbol": "SIE:XETR",
        "quantity": 750.0
      },
      {
        "id": "id3",
        "symbol": "SPY 20180316 P280 4.82",
        "quantity": 50.0
      },
      {
        "id": "id4",
        "symbol": "SPY 20180316 P270 2.10",
        "quantity": -50.0
      },
      {
        "id": "id5",
        "symbol": "SPY 20180316 C285 2.08",
        "quantity": -50.0
      }
    ],
    "date": "20180118",
    "projection": ["SPY"],
    "shock": "IND:SPX",
    "magnitude": -0.1
}

response = requests.request('POST', url, json=payload, headers=headers)

print(response.text)
var request = require("request");

var url = 'https://api.everysk.com/v2/calculations/stress_test';
var headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
};
var payload = {
    "securities": [
      {
        "id": "id1",
        "symbol": "AAPL",
        "quantity": 1000.0
      },
      {
        "id": "id2",
        "symbol": "SIE:XETR",
        "quantity": 750.0
      },
      {
        "id": "id3",
        "symbol": "SPY 20180316 P280 4.82",
        "quantity": 50.0
      },
      {
        "id": "id4",
        "symbol": "SPY 20180316 P270 2.10",
        "quantity": -50.0
      },
      {
        "id": "id5",
        "symbol": "SPY 20180316 C285 2.08",
        "quantity": -50.0
      }
    ],
    "date": "20180118",
    "projection": ["SPY"],
    "shock": "IND:SPX",
    "magnitude": -0.1
};

var options = {
    method: 'POST',
    url: url,
    headers: headers,
    body: payload,
    json: true
};
request(options, function (error, response, body) {
    if (error) throw new Error(error);

    console.log(body);
});
require 'uri'
require 'net/http'
require 'json'

url = URI("https://api.everysk.com/v2/calculations/stress_test")
headers = {
    'Content-Type'=> 'application/json',
    'Authorization'=> 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
}
payload = {
    "securities"=> [
      {
        "id"=> "id1",
        "symbol"=> "AAPL",
        "quantity"=> 1000.0
      },
      {
        "id"=> "id2",
        "symbol"=> "SIE:XETR",
        "quantity"=> 750.0
      },
      {
        "id"=> "id3",
        "symbol"=> "SPY 20180316 P280 4.82",
        "quantity"=> 50.0
      },
      {
        "id"=> "id4",
        "symbol"=> "SPY 20180316 P270 2.10",
        "quantity"=> -50.0
      },
      {
        "id"=> "id5",
        "symbol"=> "SPY 20180316 C285 2.08",
        "quantity"=> -50.0
      }
    ],
    "date"=> "20180118",
    "projection"=> ["SPY"],
    "shock"=> "IND:SPX",
    "magnitude"=> -0.1
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
req = Net::HTTP::Post.new(url.path, initheader=headers)
req.body = payload.to_json
response = http.request(req)

puts response.read_body

The above call returns the following JSON object:

{
  "stress_test": {
    "results": [
      {
        "id": "id3",
        "ev": [
          {
            "projection": "SPY",
            "value": 0.19248009261768
          },
          {
            "projection": "residual",
            "value": -0.000214771327424
          }
        ],
        "cvar_neg": [
          {
            "projection": "SPY",
            "value": 0.182956175398105
          },
          {
            "projection": "residual",
            "value": -0.000316653378127
          }
        ],
        "cvar_pos": [
          {
            "projection": "SPY",
            "value": 0.198925193905857
          },
          {
            "projection": "residual",
            "value": 0.000347917197198
          }
        ]
      },
      {
        "id": "id5",
        "ev": [
          {
            "projection": "SPY",
            "value": 0.032954931973253
          },
          {
            "projection": "residual",
            "value": -3.331576995e-06
          }
        ],
        "cvar_neg": [
          {
            "projection": "SPY",
            "value": 0.031763574513232
          },
          {
            "projection": "residual",
            "value": 5.829558761e-06
          }
        ],
        "cvar_pos": [
          {
            "projection": "SPY",
            "value": 0.033761156903945
          },
          {
            "projection": "residual",
            "value": -0.000134414106236
          }
        ]
      },
      {
        "id": "id2",
        "ev": [
          {
            "projection": "SPY",
            "value": -0.044083444761319
          },
          {
            "projection": "residual",
            "value": -0.001678775304007
          }
        ],
        "cvar_neg": [
          {
            "projection": "SPY",
            "value": -0.042145674989584
          },
          {
            "projection": "residual",
            "value": -0.007702628227174
          }
        ],
        "cvar_pos": [
          {
            "projection": "SPY",
            "value": -0.04539478779004
          },
          {
            "projection": "residual",
            "value": 0.005539051861544
          }
        ]
      },
      {
        "id": "id1",
        "ev": [
          {
            "projection": "SPY",
            "value": -0.057306859627206
          },
          {
            "projection": "residual",
            "value": -0.00111887584763
          }
        ],
        "cvar_neg": [
          {
            "projection": "SPY",
            "value": -0.054795925402436
          },
          {
            "projection": "residual",
            "value": -0.022103209066903
          }
        ],
        "cvar_pos": [
          {
            "projection": "SPY",
            "value": -0.05900607908003
          },
          {
            "projection": "residual",
            "value": 0.021277501099807
          }
        ]
      },
      {
        "id": "id4",
        "ev": [
          {
            "projection": "SPY",
            "value": -0.09483474460531
          },
          {
            "projection": "residual",
            "value": 0.000275809837853
          }
        ],
        "cvar_neg": [
          {
            "projection": "SPY",
            "value": -0.089998995494264
          },
          {
            "projection": "residual",
            "value": 0.000363704129649
          }
        ],
        "cvar_pos": [
          {
            "projection": "SPY",
            "value": -0.098107231346463
          },
          {
            "projection": "residual",
            "value": -0.000125465549635
          }
        ]
      }
    ],
    "extrapolated": true,
    "dynamic_range": [
      -0.012847654018806,
      0.013071391177579
    ],
    "unmapped_tickers": []
  }
}

Stress Test calculates the expected behavior of the portfolio under different scenarios, including extreme events. Everysk API calculates the probabilities of extreme events happening and factors those probabilities into the calculations. For example: it takes into account that correlations and volatility tend to increase in periods of market distress, resulting in large price oscillations for securities.

This API call returns 3 main measures for the specific scenario requested, namely:

To compute CVaR-, EV, CVaR+ for a portfolio, make an HTTP POST to your calculation resource URI:

HTTP Request

POST /calculations/stress_test

HTTP Parameters

Parameter Description
securities array REQUIRED It is an array of objects that describes the securities in the portfolio. Each object represents a security with an unique id, symbol, quantity and label. For more details click here.
date string date optional, default is null (today) Portfolio date in the format: "YYYYMMDD". The Portfolio Date is important because it instructs the API to use the market conditions and security prices prevailing on that date. Therefore, historical portfolios will be calculated without look ahead. In order to run the portfolio using market conditions prevailing today, use null. The furthest historical date allowed by the API is a year ago from today.
base_currency string optional, default is "USD" 3-letter ISO 4217 code for currency. Portfolios can have their base currency changed via the API call. By changing the base currency, a new set of currency risks is automatically taken into account. For all supported currencies click here.
nlv double optional, default is null (calculated) The net liquidating value of the portfolio (also called NAV). When not supplied by user, the API will calculate the net liquidating value of all the cash securities. Securities traded on margin are assumed to have nlv zero. Supplying an NLV effectively reconciles the margin.
horizon integer optional, default is 5 Forecast horizon in days: 1, 5, 20, 60 or 120.
aggregation string optional, default is "position" (no aggregation) Aggregation computes individual security MCTR's and aggregates them according to the supported criteria: "position", "liquidity", "market_capitalization", "sector", "country_of_risk", "implied_rating", "duration" or "aggregation_label". For more information click here.
projection array optional, default is ["IND:SPX"] User supplied array of securities to be used as a top-down factor model. Maximum number of elements in the projection array is 10
volatility_half_life integer optional, default is 0 Half life of volatility information in months: 0 (no decay), 2, 6 or 12.
correlation_half_life integer optional, default is 6 Half life of correlation information in months: 0 (no decay), 2, 6 or 12.
shock string optional, default is "IND:SPX" The security being used for the stress test.
magnitude double REQUIRED The magnitude of the shock. For more details click here.
confidence string optional, default is "95%" This parameter determines the confidence level for calculating CVaR. For more details click here.
use_drift boolean optional, default is false A flag to determine if the ex-ante simulations are centered on zero or if the historical mean should be taken into account. For more details click here.
forecasts array optional, default is null An array of objects that represents expected prices and probabilities for a security in the future. For more details click here.
volatility_surface array optional, default is null An array of objects that represents the volatility surface for a security. The volatility surface is parameterized by time to expiration in years and moneyness. For more details click here.
filter string optional, default is null (use the whole portfolio) Filter Expression: When present it runs a pre-processing calculation to select identifiers that satisfy certain criteria. For more details click here.

Exposure

To calculate the exposure, run the following:

curl -X POST \
  -H "Content-Type: application/json" \
  -u YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN \
  -d '{ \
      "securities": [ \
        { \
          "id": "id1", \
          "symbol": "AAPL", \
          "quantity": 1000.0 \
        }, \
        { \
          "id": "id2", \
          "symbol": "SIE:XETR", \
          "quantity": 750.0 \
        }, \
        { \
          "id": "id3", \
          "symbol": "SPY 20180316 P280 4.82", \
          "quantity": 50.0 \
        }, \
        { \
          "id": "id4", \
          "symbol": "SPY 20180316 P270 2.10", \
          "quantity": -50.0 \
        }, \
        {
          "id": "id5", \
          "symbol": "SPY 20180316 C285 2.08", \
          "quantity": -50.0 \
        } \
      ], \
      "date": "20180118" \
  }' \
  https://api.everysk.com/v2/calculations/exposure
import requests

url = 'https://api.everysk.com/v2/calculations/exposure'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
}
payload = {
    "securities": [
      {
        "id": "id1",
        "symbol": "AAPL",
        "quantity": 1000.0
      },
      {
        "id": "id2",
        "symbol": "SIE:XETR",
        "quantity": 750.0
      },
      {
        "id": "id3",
        "symbol": "SPY 20180316 P280 4.82",
        "quantity": 50.0
      },
      {
        "id": "id4",
        "symbol": "SPY 20180316 P270 2.10",
        "quantity": -50.0
      },
      {
        "id": "id5",
        "symbol": "SPY 20180316 C285 2.08",
        "quantity": -50.0
      }
    ],
    "date": "20180118"
}

response = requests.request('POST', url, json=payload, headers=headers)

print(response.text)
var request = require("request");

var url = 'https://api.everysk.com/v2/calculations/exposure';
var headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
};
var payload = {
    "securities": [
      {
        "id": "id1",
        "symbol": "AAPL",
        "quantity": 1000.0
      },
      {
        "id": "id2",
        "symbol": "SIE:XETR",
        "quantity": 750.0
      },
      {
        "id": "id3",
        "symbol": "SPY 20180316 P280 4.82",
        "quantity": 50.0
      },
      {
        "id": "id4",
        "symbol": "SPY 20180316 P270 2.10",
        "quantity": -50.0
      },
      {
        "id": "id5",
        "symbol": "SPY 20180316 C285 2.08",
        "quantity": -50.0
      }
    ],
    "date": "20180118"
};

var options = {
    method: 'POST',
    url: url,
    headers: headers,
    body: payload,
    json: true
};
request(options, function (error, response, body) {
    if (error) throw new Error(error);

    console.log(body);
});
require 'uri'
require 'net/http'
require 'json'

url = URI("https://api.everysk.com/v2/calculations/exposure")
headers = {
    'Content-Type'=> 'application/json',
    'Authorization'=> 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
}
payload = {
    "securities"=> [
      {
        "id"=> "id1",
        "symbol"=> "AAPL",
        "quantity"=> 1000.0
      },
      {
        "id"=> "id2",
        "symbol"=> "SIE:XETR",
        "quantity"=> 750.0
      },
      {
        "id"=> "id3",
        "symbol"=> "SPY 20180316 P280 4.82",
        "quantity"=> 50.0
      },
      {
        "id"=> "id4",
        "symbol"=> "SPY 20180316 P270 2.10",
        "quantity"=> -50.0
      },
      {
        "id"=> "id5",
        "symbol"=> "SPY 20180316 C285 2.08",
        "quantity"=> -50.0
      }
    ],
    "date"=> "20180118"
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
req = Net::HTTP::Post.new(url.path, initheader=headers)
req.body = payload.to_json
response = http.request(req)

puts response.read_body

The above call returns the following JSON object:

{
  "exposure": {
    "results": [
      {
        "id": "id4",
        "gross": 327562.3495692536,
        "net": 327562.3495692536
      },
      {
        "id": "id1",
        "gross": 179260.0,
        "net": 179260.0
      },
      {
        "id": "id2",
        "gross": 112254.4125,
        "net": 112254.4125
      },
      {
        "id": "id5",
        "gross": 453419.07855536445,
        "net": -453419.07855536445
      },
      {
        "id": "id3",
        "gross": 675281.5948164026,
        "net": -675281.5948164026
      }
    ],
    "nlv": 315614.4125,
    "unmapped_tickers": []
  }
}

Calculates the delta-adjusted notional exposure of each security, converted to the base currency of the portfolio.

To compute the exposures for a portfolio, make an HTTP POST to your calculation resource URI:

HTTP Request

POST /calculations/exposure

HTTP Parameters

Parameter Description
securities array REQUIRED It is an array of objects that describes the securities in the portfolio. Each object represents a security with an unique id, symbol, quantity and label. For more details click here.
date string date optional, default is null (today) Portfolio date in the format: "YYYYMMDD". The Portfolio Date is important because it instructs the API to use the market conditions and security prices prevailing on that date. Therefore, historical portfolios will be calculated without look ahead. In order to run the portfolio using market conditions prevailing today, use null. The furthest historical date allowed by the API is a year ago from today.
base_currency string optional, default is "USD" 3-letter ISO 4217 code for currency. Portfolios can have their base currency changed via the API call. By changing the base currency, a new set of currency risks is automatically taken into account. For all supported currencies click here.
nlv double optional, default is null (calculated) The net liquidating value of the portfolio (also called NAV). When not supplied by user, the API will calculate the net liquidating value of all the cash securities. Securities traded on margin are assumed to have nlv zero. Supplying an NLV effectively reconciles the margin.
horizon integer optional, default is 5 Forecast horizon in days: 1, 5, 20, 60 or 120.
aggregation string optional, default is "position" (no aggregation) Aggregation computes individual security MCTR's and aggregates them according to the supported criteria: "position", "liquidity", "market_capitalization", "sector", "country_of_risk", "implied_rating", "duration" or "aggregation_label". For more information click here.
filter string optional, default is null (use the whole portfolio) Filter Expression: When present it runs a pre-processing calculation to select identifiers that satisfy certain criteria. For more details click here.

Properties

To calculate the properties, run the following:

curl -X POST \
  -H "Content-Type: application/json" \
  -u YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN \
  -d '{ \
      "securities": [ \
        { \
          "id": "id1", \
          "symbol": "AAPL", \
          "quantity": 1000.0 \
        }, \
        { \
          "id": "id2", \
          "symbol": "SIE:XETR", \
          "quantity": 750.0 \
        }, \
        { \
          "id": "id3", \
          "symbol": "SPY 20180316 P280 4.82", \
          "quantity": 50.0 \
        }, \
        { \
          "id": "id4", \
          "symbol": "SPY 20180316 P270 2.10", \
          "quantity": -50.0 \
        }, \
        {
          "id": "id5", \
          "symbol": "SPY 20180316 C285 2.08", \
          "quantity": -50.0 \
        } \
      ], \
      "date": "20180118" \
  }' \
  https://api.everysk.com/v2/calculations/properties
import requests

url = 'https://api.everysk.com/v2/calculations/properties'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
}
payload = {
    "securities": [
      {
        "id": "id1",
        "symbol": "AAPL",
        "quantity": 1000.0
      },
      {
        "id": "id2",
        "symbol": "SIE:XETR",
        "quantity": 750.0
      },
      {
        "id": "id3",
        "symbol": "SPY 20180316 P280 4.82",
        "quantity": 50.0
      },
      {
        "id": "id4",
        "symbol": "SPY 20180316 P270 2.10",
        "quantity": -50.0
      },
      {
        "id": "id5",
        "symbol": "SPY 20180316 C285 2.08",
        "quantity": -50.0
      }
    ],
    "date": "20180118"
}

response = requests.request('POST', url, json=payload, headers=headers)

print(response.text)
var request = require("request");

var url = 'https://api.everysk.com/v2/calculations/properties';
var headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
};
var payload = {
    "securities": [
      {
        "id": "id1",
        "symbol": "AAPL",
        "quantity": 1000.0
      },
      {
        "id": "id2",
        "symbol": "SIE:XETR",
        "quantity": 750.0
      },
      {
        "id": "id3",
        "symbol": "SPY 20180316 P280 4.82",
        "quantity": 50.0
      },
      {
        "id": "id4",
        "symbol": "SPY 20180316 P270 2.10",
        "quantity": -50.0
      },
      {
        "id": "id5",
        "symbol": "SPY 20180316 C285 2.08",
        "quantity": -50.0
      }
    ],
    "date": "20180118"
};

var options = {
    method: 'POST',
    url: url,
    headers: headers,
    body: payload,
    json: true
};
request(options, function (error, response, body) {
    if (error) throw new Error(error);

    console.log(body);
});
require 'uri'
require 'net/http'
require 'json'

url = URI("https://api.everysk.com/v2/calculations/properties")
headers = {
    'Content-Type'=> 'application/json',
    'Authorization'=> 'Bearer YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN'
}
payload = {
    "securities"=> [
      {
        "id"=> "id1",
        "symbol"=> "AAPL",
        "quantity"=> 1000.0
      },
      {
        "id"=> "id2",
        "symbol"=> "SIE:XETR",
        "quantity"=> 750.0
      },
      {
        "id"=> "id3",
        "symbol"=> "SPY 20180316 P280 4.82",
        "quantity"=> 50.0
      },
      {
        "id"=> "id4",
        "symbol"=> "SPY 20180316 P270 2.10",
        "quantity"=> -50.0
      },
      {
        "id"=> "id5",
        "symbol"=> "SPY 20180316 C285 2.08",
        "quantity"=> -50.0
      }
    ],
    "date"=> "20180118"
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
req = Net::HTTP::Post.new(url.path, initheader=headers)
req.body = payload.to_json
response = http.request(req)

puts response.read_body

The above call returns the following JSON object:

{
    "properties": {
        "results": [
          {
            "property": "var",
            "value": -0.035158326333446
          },
          {
            "property": "cvar",
            "value": -0.044845337238832
          },
          {
            "property": "liquidity",
            "value": 0.000753567602616
          },
          {
            "property": "net_exposure",
            "value": -1.614704180540277
          },
          {
            "property": "gross_exposure",
            "value": 5.53769842637025
          },
          {
            "property": "expected_return",
            "value": -0.054870904971009
          },
          {
            "property": "expected_volatility",
            "value": 0.14314354343333
          },
          {
            "property": "delta",
            "value": -801138.3238025135
          },
          {
            "property": "vega",
            "value": -1773.3535916940648
          },
          {
            "property": "gamma",
            "value": -1.221585162864691
          },
          {
            "property": "theta",
            "value": 196.84008207267567
          }
        ],
        "unmapped_tickers": []
    }
}

Calculates the overall portfolio properties with a single API call, namely:

Property Description
CVaR The average of the worst (1-confidence) percentile outcomes from the forward looking profit and loss (PL) distribution of the portfolio.
Var The Value at Risk with confidence.
Liquidity The number of fractional days to fully unwind the portfolio, assuming a participation rate of 20% from the average volume traded in the last 20 days (ignores non-equity securities).
Net Exposure The delta-adjusted net exposure, expressed in the base currency of the portfolio.
Gross Exposure The delta-adjusted gross exposure, expressed in the base currency of the portfolio.
Expected Return Annualized mean of the forward looking PL distribution of the portfolio.
Expected Volatility Annualized standard deviation of the forward looking PL distribution of the portfolio.
Delta The notional delta of the portfolio in base currency, including FX, futures, index and/or equity options.
Vega The notional vega of the portfolio in base currency, including FX, futures, index and/or equity options.
Gamma The notional gamma of the portfolio in base currency, including FX, futures, index and/or equity options.
Theta The notional theta of the portfolio in base currency, including FX, futures, index and/or equity options.

HTTP Request

POST /calculations/properties

HTTP Parameters

Parameter Description
securities array REQUIRED It is an array of objects that describes the securities in the portfolio. Each object represents a security with an unique id, symbol, quantity and label. For more details click here.
date string date optional, default is null (today) Portfolio date in the format: "YYYYMMDD". The Portfolio Date is important because it instructs the API to use the market conditions and security prices prevailing on that date. Therefore, historical portfolios will be calculated without look ahead. In order to run the portfolio using market conditions prevailing today, use null. The furthest historical date allowed by the API is a year ago from today.
base_currency string optional, default is "USD" 3-letter ISO 4217 code for currency. Portfolios can have their base currency changed via the API call. By changing the base currency, a new set of currency risks is automatically taken into account. For all supported currencies click here.
nlv double optional, default is null (calculated) The net liquidating value of the portfolio (also called NAV). When not supplied by user, the API will calculate the net liquidating value of all the cash securities. Securities traded on margin are assumed to have nlv zero. Supplying an NLV effectively reconciles the margin.
horizon integer optional, default is 5 Forecast horizon in days: 1, 5, 20, 60 or 120.
aggregation string optional, default is "position" (no aggregation) Aggregation computes individual security MCTR's and aggregates them according to the supported criteria: "position", "liquidity", "market_capitalization", "sector", "country_of_risk", "implied_rating", "duration" or "aggregation_label". For more information click here.
projection array optional, default is ["IND:SPX"] User supplied array of securities to be used as a top-down factor model. Maximum number of elements in the projection array is 10
volatility_half_life integer optional, default is 0 Half life of volatility information in months: 0 (no decay), 2, 6 or 12.
correlation_half_life integer optional, default is 6 Half life of correlation information in months: 0 (no decay), 2, 6 or 12.
confidence string optional, default is "95%" This parameter determines the confidence level for calculating CVaR. For more details click here.
use_drift boolean optional, default is false A flag to determine if the ex-ante simulations are centered on zero or if the historical mean should be taken into account. For more details click here.
forecasts array optional, default is null An array of objects that represents expected prices and probabilities for a security in the future. For more details click here.
volatility_surface array optional, default is null An array of objects that represents the volatility surface for a security. The volatility surface is parameterized by time to expiration in years and moneyness. For more details click here.
filter string optional, default is null (use the whole portfolio) Filter Expression: When present it runs a pre-processing calculation to select identifiers that satisfy certain criteria. For more details click here.

Parameter Details

Securities

Example of long/short global stocks portfolio with user defined label (JSON):

[
  {
    "id": "0f82eb",
    "symbol": "GMEXICOB:XMEX",
    "quantity": 125000.0,
    "label": "AB"
  },
  {
    "id": "76ac8d",
    "symbol": "CNCO",
    "quantity": 150000.0,
    "label": "DL"
  },
  {
    "id": "47e7ba",
    "symbol": "SIE:XETR",
    "quantity": 10000.0,
    "label": "DL"
  },
  {
    "id": "86f551",
    "symbol": "BN:XPAR",
    "quantity": 4000.0,
    "label": "AB"
  },
  {
    "id": "1b9b11",
    "symbol": "BMW:XETR",
    "quantity": 2000.0,
    "label": "AB"
  },
  {
    "id": "a089b0",
    "symbol": "AAPL",
    "quantity": -1000.0,
    "label": "AB"
  },
  {
    "id": "bc1413",
    "symbol": "FB",
    "quantity": -2400.0,
    "label": "DL"
  }
]

The parameter securities is an array of objects representing each security in the portfolio. Each object in the array has the following attributes:

Attribute Description
id string REQUIRED An unique identifier (UID) for a security.
symbol string REQUIRED Security symbol: Please refer to our symbology.
quantity double REQUIRED Numbers of shares or contracts. Positive quantities are longs and negative are shorts. For fixed income securities, mutual funds, swaps, cash and margin the amounts are defined in the security's currency.
label string optional, default is "" (no aggregation label) Aggregation label defined by the user. It is utilized when aggregation is set to "aggregation_label".

Maximum securities length:

Magnitude

The parameter magnitude is an instantaneous shock as a decimal number: -10% = -0.10.

Certain rates/spreads can also be shocked and the magnitude of the shock is an absolute widening or tightening of the rate/spread. For example:

Shock Magnitude Current level New level
IND:SPX -1% 2821 2792
IND:LIBOR3M -1% 1.77 0.77

In the table above, the shock in SPX is a percent change, whereas the libor shock is an absolute shift.

For a list of rates and spreads that are shocked in absolute terms please click here.

Confidence

The parameter confidence can be one of: 1sigma, 2sigma, 3sigma, 85%, 90% or 95%. For example: 1sigma represents the left tail outside a one-sigma move from the mean of the profit and loss distribution (PL). It would represent roughly the worst/best 16% (=68%+16%) forecasted outcomes. Conversely, 95% explicitly represents the worst/best 5% forecasted outcomes.

The table below clarifies:

Confidence Probability
1sigma One sigma dispersion around the mean (approx. 68.27%) + one tail Tail measure*15.86%
2sigma Two sigma dispersion around the mean (approx. 95.45%) + one tail Tail measure*2.27%
3sigma Three sigma dispersion around the mean (approx. 99.73%) + one tail Tail measure*0.13%
85% Explicit 85% Tail measure* = 15%
90% Explicit 90% Tail measure* = 10%
95% Explicit 95% Tail measure* = 5%

* Tail measure = (1-confidence)

Use Drift

By default our simulations are zero-centered. This flag specifies that the dispersion of simulations should be around the average of the historical risk factors instead.

In the calculation of the averages, volatility_half_life and correlation_half_life are taken into account.

Forecasts

Example of forecast (JSON):

[
  {
    "symbol": "NFLX",
    "years": 1.0,
    "targets": [160, 260, 400, 480],
    "probabilities": [0.55, 0.15, 0.15,0.15]
  },
  {
    "symbol": "SPY",
    "years": 0.5,
    "targets": [270, 260, 200],
    "probabilities": [0.5, 0.4, 0.1]
  }
]

User-supplied forecasts can represent outcomes that are difficult to be captured by the covariance matrix, for example: a takeover situation, a pharmaceutical company clearing a drug trial or even a large correction not captured with the historical data.

The parameter forecasts is an array of objects representing the price forecast for a security in the portfolio. Each object in the array has the following attributes:

Attribute Description
years double REQUIRED Timeframe for the forecast to materialize in years.
targets array REQUIRED Target prices at a horizon represented by attribute years. Can contain any number of targets.
probabilities array REQUIRED Probabilities associated to each element inside the attribute targets.

The arrays targets and probabilities have to be of same size and probabilities need to sum to 1.0.

Volatility Surface

Example of volatility surface (JSON):

[
  {
    "symbol": "IBM",
    "time_to_expiration": [0.12, 0.25],
    "moneyness": [0.97, 1, 1.03, 1.05],
    "volatilities": [
      [0.36, 0.16, 0.33, 0.26],
      [0.19, 0.20, 0.17, 0.16]
    ]    
  }
]

Surfaces are parameterized in years to expiration and moneyness. When supplied, the surface is used to price any options on the underlying. When omitted, an implied volatility is calculated with Black and Scholes.

The parameter volatility_surface is an array of objects representing the implied volatilities for underlying securities in the portfolio. Each object in the array has the following attributes:

Attribute Description
time_to_expiration array REQUIRED Various times to expiration (as a fraction of a year).
moneyness array REQUIRED Various moneyness.
volatilities 2d array REQUIRED Implied volatilities, with times_to_expiration rows and moneyness columns.

Filter Expression

Example using logical operator 'and'. Retrieve identifiers for positions that are long and also denominated in a currency different than the base currency of the portfolio:

"exposure('long') and currency('foreign securities')"

Example using logical operator 'or'. Retrieve any shorts or illiquid positions:

"exposure('short') or liquidity('>300%')"

Example using logical operator 'not'. Retrieve all positions that are not long options:

"not(type('equity option long delta'))"

Example using logical operators combined:

"currency('foreign securities') and (not(exposure('short') or liquidity('>300%')))"

Filters are powerful constructs to return the unique identifiers of certain positions in the portfolio, satisfying a specific criteria. When used, they isolate the behavior of an unique group, compared to the whole. For example: how illiquid securities might react to an oil shock.

The parameter filter supports the following expressions:

Filter Function Description
currency Extracts the unique identifiers according to different currency related buckets: 'foreign securities', 'domestic securities'
exposure Extracts the unique identifiers that represent long exposures (including long calls and short puts) and short exposures (including long puts and short calls): 'long', 'short'
type Extracts the identifiers of securities from a specific type: 'equity option long delta', 'equity option short delta', 'future option long delta', 'future option short delta', 'foreign equity long', 'foreign equity short', 'us equity long', 'us equity short', 'fx forward', 'fx option long delta', 'fx option short delta'
liquidity Extracts the identifiers of securities satisfying certain liquidity criteria: '0-5%', '5-25%', '25-50%', '50-100%', '100-300%', '>300%'

Liquidity above is expressed as the proportion of the 20-day average trading volume required to unwind a position in full, taking into account a 20% participation rate. Thus, ">300%" means that will take at least 3 days to unwind the position(s) in full.

Simple filters above can be combined into complex filters using logical expressions, namely: or, and and not. Please see various examples in the right panel.

Filters that do not satisfy all the conditions return an empty dictionary, therefore the whole portfolio is used.