Introduction
Portfolio Optimizer is at heart a Web API which makes the science of portfolio optimization accessible to everyone.
It is based on REST for easy integration, uses JSON for the exchange of data and uses the two most common HTTP verbs (GET, POST) to represent the actions.
It is also as secured as an API could be (HTTPS access, no usage of cookies, no manipulation of personal data).
API Base URL
The base URL for the API is: https://api.portfoliooptimizer.io/.
API Versioning
The API uses version numbers added to its base URL to distinguish between different versions of the API.
The current version number is v1.
API Authentication
The API supports two authentication modes:
- No authentication (i.e., anonymous usage)
- Key-based authentication
In anonymous mode, as its name suggests, there is no need to provide any authentication information, but the most restrictive API limits apply.
In key-based authentication mode, other API limits apply, and the following HTTP header needs to be provided with all the API requests:
X-API-Key: my-api-key
To authenticate with your personnal API key, use the following code:
curl https://api.portfoliooptimizer.io/v1/... \
-H "X-API-Key: my-api-key" ...
API Headers
The API requires the following HTTP header to be provided with all the API requests:
Content-Type: application/json
, because the API uses JSON to exchange data
The API also optionally requires the following HTTP header to be provided with all the API requests:
X-API-Key
, in order to use the key-based authentication mode
To provide all the required headers, use the following code:
curl https://api.portfoliooptimizer.io/v1/... \
-H "Content-Type: application/json" -H "X-API-Key: my-api-key" ...
API Limits
Free usage
Depending on the authentication mode, different limits are enforced in order to allow as many people as possible to use the API freely:
- Unauthenticated mode
- The API requests are restricted to a subset of all the available endpoints and/or endpoints features
- The API requests are limited to 1 request per second for all the non-authenticated users combined
- The API requests are limited to 1 second of execution time
- The API requests are limited to 10 assets, 100 portfolios, 500 series data points
- The API requests are restricted to a subset of all the available endpoints and/or endpoints features
- Authenticated mode
- The API requests are restricted to a subset of all the available endpoints and/or endpoints features
- The API requests are limited to ~1 request per second per API key
- The API requests are limited to ~1 second of execution time
- The API requests are limited to ~10 assets, ~100 portfolios, ~500 series data points
Contributor usage
Higher limits are available in authenticated mode, and they require contributing to the API running costs:
- The API requests can access all the available endpoints
- The API requests are limited to 17,280 requests per 24 hour per API key, with no concurrent request allowed
- The API requests are limited to 2.5 seconds of execution time
- The API requests are limited to 50 assets
Specific usage
Even higher limits, or no limits at all, are available in authenticated mode for really specific usages (dedicated backtesting platform...).
Please contact me to discuss about the exact needs.
Example of response message HTTP headers:
...
x-ratelimit-limit-second: 1 # The number of API requests is limited to 1 per second
x-ratelimit-remaining-second: 0 # 0 additional API requests can be made in the current second
...
API Response Codes
The API uses HTTP response codes to provide details on successful and failed API requests.
HTTP Code | Description | Notes |
---|---|---|
200 | Request successfully processed | The response message body contains the output data |
400 | Input JSON content is incorrect | The response message body contains information on the incorrect input JSON content |
401 | Provided API key is not valid | |
404 | Requested endpoint not found | The requested endpoint might exist, but needs to be accessed with another HTTP method (e.g., POST instead of GET) |
429 | Too many requests received | The response message HTTP headers X-RateLimit-* contains information on the API limits |
500 | Internal error | Something went wrong on Portfolio Optimizer side, do not hesitate to report the issue |
502 | Bad gateway | Portfolio Optimizer is under maintenance, sorry for the inconvenience ! If the outage lasts for too long, do not hesitate to report the issue |
Pinger
Ping
Allows to determine the status of the API.
HTTP Request
Endpoint | Method |
---|---|
/v1/ping |
GET |
curl "https://api.portfoliooptimizer.io/v1/ping"
The above command returns JSON structured like this:
{}
Headers
N/A
Query Parameters
N/A
Body Parameters
N/A
HTTP Response
Success 200
N/A
Errors
Refer to the API response codes section.
Assets Returns
Arithmetic Returns
Computes the arithmetic returns of assets.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/returns/arithmetic |
POST |
The following command computes the arithmetic returns of 2 assets, one with prices 1,2 and the other with prices 2,3,6:
curl "https://api.portfoliooptimizer.io/v1/assets/returns/arithmetic" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsPrices":[[1,2], [2,3,6]] }'
It returns the following JSON, which corresponds to an arithmetic return of 100% for the first asset (1 -> 2), and arithmetic returns of successively 50% (2 -> 3) and 100% (3 -> 6) for the second asset:
{
"assetsReturns" : [[1], [0.5,1]]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsPrices |
number[] [] | Array containing assets arrays, with assetsPrices[i][j] corresponding to the prices of asset i+1, i=0..assets-1 at the j+1-th time period |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsReturns |
number[] [] | Array containing assets arrays, with assetsReturns[i] corresponding to the returns of asset i+1, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
Logarithmic Returns
Computes the logarithmic returns of assets.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/returns/logarithmic |
POST |
The following command computes the logarithmic returns of 2 assets, one with prices 1,2 and the other with prices 2,3,6:
curl "https://api.portfoliooptimizer.io/v1/assets/returns/logarithmic" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsPrices":[[1,2], [2,3,6]] }'
It returns the following JSON, which corresponds to a logarithmic return of ~69% for the first asset (1 -> 2), and logarithmic returns of successively ~40% (2 -> 3) and ~69% (3 -> 6) for the second asset:
{
"assetsReturns" : [[0.6931471805599453],[0.4054651081081644,0.6931471805599453]]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsPrices |
number[] [] | Array containing assets arrays, with assetsPrices[i][j] corresponding to the prices of asset i+1, i=0..assets-1 at the j+1-th time period |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsReturns |
number[] [] | Array containing assets arrays, with assetsReturns[i] corresponding to the returns of asset i+1, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
Average Returns
Computes the average returns of assets.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/returns/average |
POST |
The following command computes the average returns of 2 assets, one with returns 10%, -5% and the other with returns 0%,-1%,1%:
curl "https://api.portfoliooptimizer.io/v1/assets/returns/average" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns":[[0.10,-0.05], [0,-0.01,0.01]] }'
It returns the following JSON, which corresponds to an average return of 2.5% for the first asset, and of 0% for the second asset:
{
"assetsReturns": [0.025,0]
}
Headers
Refer to the API response codes section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] [] | Array containing assets arrays, with assetsReturns[i] corresponding to the returns of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsReturns |
number[] | Array containing assets numbers, with assetsReturns[i] corresponding to the arithmetic average of all asset i+1 returns, i=0..assets-1 |
Errors
Refer to the API response code description.
Assets Correlation
Correlation Matrix (from returns)
Computes the correlation matrix of assets from their returns.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/correlation/matrix |
POST |
The following command computes the correlation matrix of 2 assets based on 4 returns per asset:
curl "https://api.portfoliooptimizer.io/v1/assets/correlation/matrix" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns":[[0.01,0,0.02,-0.03], [0.01,0,0.02,-0.03]] }'
It returns the following JSON, which numerically corresponds to the correlation matrix $\begin{bmatrix} 1 & 1 \newline 1 & 1 \end{bmatrix}$:
{
"assetsCorrelationMatrix":[[1, 0.9999999999999999], [0.9999999999999999, 1]]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] [] | Array containing assets arrays of identical length, with assetsReturns[i] corresponding to the returns of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsCorrelationMatrix |
number[] [] | Array containing assets arrays, with assetsCorrelationMatrix[i] an array containing assets numbers and assetsCorrelationMatrix[i][j] corresponding to the correlation between the returns of assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
Errors
Refer to the API response codes section.
Correlation Matrix (from covariance matrix)
Computes the correlation matrix of assets from their covariance matrix.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/correlation/matrix |
POST |
The following command computes the correlation matrix of 2 assets based on their covariance matrix $\begin{bmatrix} 0.01 & -0.0025 \newline -0.0025 & 0.0025 \end{bmatrix}$:
curl "https://api.portfoliooptimizer.io/v1/assets/correlation/matrix" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsCovarianceMatrix":[[0.01,-0.0025],[-0.0025,0.0025]] }'
It returns the following JSON, which numerically corresponds to the correlation matrix $\begin{bmatrix} 1 & -0.5 \newline -0.5 & 1 \end{bmatrix}$:
{
"assetsCorrelationMatrix":[[1, -0.4999999999999999], [-0.4999999999999999, 1]]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsCorrelationMatrix |
number[] [] | Array containing assets arrays, with assetsCorrelationMatrix[i] an array containing assets numbers and assetsCorrelationMatrix[i][j] corresponding to the correlation between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
Errors
Refer to the API response codes section.
Correlation Matrix Validation
Validates whether a matrix is a correlation matrix.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/correlation/matrix/validation |
POST |
The following command validates whether the matrix $\begin{bmatrix} 1 & -0.00035 \newline -0.00035 & 1 \end{bmatrix}$ is a valid correlation matrix:
curl "https://api.portfoliooptimizer.io/v1/assets/correlation/matrix/validation" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsCorrelationMatrix":[[1,-0.00035],[-0.00035,1]] }'
It returns the following JSON, which validates that the matrix is indeed a valid correlation matrix:
{
"message":"valid correlation matrix"
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCorrelationMatrix |
number[] [] | Array containing assets arrays, with assetsCorrelationMatrix[i] an array containing assets numbers and assetsCorrelationMatrix[i][j] corresponding to the correlation between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
message |
string | Indicates whether the matrix is a valid correlation matrix |
Errors
Refer to the API response codes section.
References
When is a correlation matrix not a correlation matrix?
Nearest Correlation Matrix
Computes the nearest correlation matrix to an approximate correlation matrix, optionally keeping a selected number of correlations fixed.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/correlation/matrix/nearest |
POST |
The following command computes the nearest correlation matrix to the approximate correlation matrix $\begin{bmatrix} 1 & 1 & 0 \newline 1 & 1 & 1 \newline 0 & 1 & 1 \end{bmatrix}$:
curl "https://api.portfoliooptimizer.io/v1/assets/correlation/matrix/nearest" \
-H "Content-Type: application/json" \
-d '{ "assets": 3,
"assetsApproximateCorrelationMatrix": [[1, 1, 0],[1, 1, 1],[0, 1, 1]] }'
It returns the following JSON, which numerically corresponds to the correlation matrix $\begin{bmatrix} 1.0000 & 0.7606 & 0.1573 \newline 0.7606 & 1.0000 & 0.7606 \newline 0.1573 & 0.7606 & 1.0000 \end{bmatrix}$:
{
"assetsCorrelationMatrix":[[1,0.7606306078350177,0.15733356650676536],
[0.7606306078350177,1,0.7606306078350177],
[0.15733356650676536,0.7606306078350177,1]]
}
The following command computes the nearest correlation matrix to the approximate correlation matrix $\begin{bmatrix} 1 & 0.5 & 0.9 \newline 0.5 & 1 & -0.2 \newline 0.9 & -0.2 & 1 \end{bmatrix}$, keeping the negative correlation $-0.2$ between the assets 2 and 3 fixed:
curl "https://api.portfoliooptimizer.io/v1/assets/correlation/matrix/nearest" \
-H "Content-Type: application/json" \
-d '{ "assets": 3,
"assetsApproximateCorrelationMatrix": [[1, 0.5, 0.9],[0.5, 1, -0.2],[0.9, -0.2, 1]],
"assetsFixedCorrelations": [[2,3]] }'
It returns the following JSON, which numerically corresponds to the correlation matrix $\begin{bmatrix} 1.0000 & 0.4315 & 0.7975 \newline 0.4315 & 1.0000 & -0.2000 \newline 0.7975 & -0.2000 & 1.0000 \end{bmatrix}$:
{
"assetsCorrelationMatrix":[[1,0.4314569968899409,0.7974943959465133],
[0.4314569968899409,1,-0.2],
[0.7974943959465133,-0.2,1]]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsApproximateCorrelationMatrix |
number[] [] | Array containing assets arrays, with assetsApproximateCorrelationMatrix[i] an array containing assets numbers and assetsApproximateCorrelationMatrix[i][j] corresponding to the approximate correlation between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
assetsFixedCorrelations |
number[] [] | Optional Array containing k >= 1 arrays, with assetsFixedCorrelations[k] an array containing two strictly positive integers [i+1,j+1] corresponding to the assets i+1 and j+1 for which to keep the correlation assetsApproximateCorrelationMatrix[i][j] fixed, i=0..assets-1, j=0..assets-1, i <> j |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsCorrelationMatrix |
number[] [] | Array containing assets arrays, with assetsCorrelationMatrix[i] an array containing assets numbers and assetsCorrelationMatrix[i][j] corresponding to the correlation between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
Errors
Refer to the API response codes section.
References
Assets Covariance
Covariance Matrix (from returns)
Computes the covariance matrix of assets from their returns.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/covariance/matrix |
POST |
The following command computes the covariance matrix of 2 assets based on 4 returns per asset:
curl "https://api.portfoliooptimizer.io/v1/assets/covariance/matrix" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns":[[0.01,0,0.02,-0.03], [0.01,0,0.02,-0.03]] }'
It returns the following JSON, which corresponds to the covariance matrix $\begin{bmatrix} 0.00035 & 0.00035 \newline 0.00035 & 0.00035 \end{bmatrix}$:
{
"assetsCovarianceMatrix":[[0.00035,0.00035],[0.00035,0.00035]]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] [] | Array containing assets arrays of identical length, with assetsReturns[i] corresponding to the returns of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between the returns of assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
Errors
Refer to the API response codes section.
Covariance Matrix (from correlation matrix and standard deviations)
Computes the covariance matrix of assets from their correlation matrix and their volatilities (i.e., standard deviations).
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/covariance/matrix |
POST |
The following command computes the covariance matrix of 2 assets based on their correlation matrix $\begin{bmatrix} 1 & -0.5 \newline -0.5 & 1 \end{bmatrix}$ and their standard deviations $\sigma_1 = 10$% and $\sigma_2 = 5$%:
curl "https://api.portfoliooptimizer.io/v1/assets/covariance/matrix" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsCorrelationMatrix":[[1,-0.5], [-0.5,1]],
"assetsVolatilities": [0.10, 0.05] }'
It returns the following JSON, which numerically corresponds to the covariance matrix $\begin{bmatrix} 0.01 & -0.0025 \newline -0.0025 & 0.0025 \end{bmatrix}$:
{
"assetsCovarianceMatrix":[[0.010000000000000002,-0.0025000000000000005],
[-0.0025000000000000005,0.0025000000000000005]]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCorrelationMatrix |
number[] [] | Array containing assets arrays, with assetsCorrelationMatrix[i] an array containing assets numbers and assetsCorrelationMatrix[i][j] corresponding to the correlation between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
assetsVolatilities |
number[] | Array containing assets numbers, with assetsVolatilities[i] corresponding to the volatility of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
Errors
Refer to the API response codes section.
Covariance Matrix (from correlation matrix and variances)
Computes the covariance matrix of assets from their correlation matrix and their variances.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/covariance/matrix |
POST |
The following command computes the covariance matrix of 2 assets based on their correlation matrix $\begin{bmatrix} 1 & -0.5 \newline -0.5 & 1 \end{bmatrix}$ and their variances $\sigma_1^2 = 0.01$ and $\sigma_2^2 = 0.0025$:
curl "https://api.portfoliooptimizer.io/v1/assets/covariance/matrix" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsCorrelationMatrix":[[1,-0.5], [-0.5,1]],
"assetsVariances": [0.01, 0.0025] }'
It returns the following JSON, which numerically corresponds to the covariance matrix $\begin{bmatrix} 0.01 & -0.0025 \newline -0.0025 & 0.0025 \end{bmatrix}$:
{
"assetsCovarianceMatrix":[[0.010000000000000002,-0.0025000000000000005],
[-0.0025000000000000005,0.0025000000000000005]]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCorrelationMatrix |
number[] [] | Array containing assets arrays, with assetsCorrelationMatrix[i] an array containing assets numbers and assetsCorrelationMatrix[i][j] corresponding to the correlation between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
assetsVariances |
number[] | Array containing assets numbers, with assetsVariances[i] corresponding to the variance of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
Errors
Refer to the API response codes section.
Sample Covariance Matrix (from returns)
Computes the sample covariance matrix of assets returns.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/covariance/matrix/sample |
POST |
The following command computes the sample covariance matrix of 2 assets based on 4 returns per asset:
curl "https://api.portfoliooptimizer.io/v1/assets/covariance/matrix/sample" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns":[[0.01,0.01,0.02,0.01], [-0.02,-0.02,-0.04,-0.02]] }'
It returns the following JSON, which corresponds to the covariance matrix $\begin{bmatrix} 0.000025 & -0.00005 \newline -0.00005 & 0.0001 \end{bmatrix}$:
{
"assetsCovarianceMatrix":[[0.000025,-0.00005],[-0.00005,0.0001]]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assetsReturns |
number[] [] | Array containing assets arrays of identical length, with assetsReturns[i] corresponding to the returns of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the sample covariance between the returns of assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
Errors
Refer to the API response codes section.
Covariance Matrix Validation
Validates whether a matrix is a covariance matrix.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/covariance/matrix/validation |
POST |
The following command validates whether the matrix $\begin{bmatrix} 0.00035 & -0.00035 \newline -0.00035 & 0.00035 \end{bmatrix}$ is a valid covariance matrix:
curl "https://api.portfoliooptimizer.io/v1/assets/covariance/matrix/validation" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsCovarianceMatrix":[[0.00035,-0.00035],[-0.00035,0.00035]] }'
It returns the following JSON, which validates that the matrix is indeed a valid covariance matrix:
{
"message":"valid covariance matrix"
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
message |
string | Indicates whether the matrix is a valid covariance matrix |
Errors
Refer to the API response codes section.
Assets Variances
Variances (from returns)
Computes the variances of assets from their returns.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/variances |
POST |
The following command computes the variances of 2 assets based on 4 returns per asset:
curl "https://api.portfoliooptimizer.io/v1/assets/variances" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns":[[0.01,0,0.02,-0.03], [0.01,0,0.02,-0.03]] }'
It returns the following JSON, which corresponds to variances $\sigma_1^2 = 0.00035$ and $\sigma_2^2 = 0.00035$:
{
"assetsVariances":[0.00035,0.00035]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] [] | Array containing assets arrays of identical length, with assetsReturns[i] corresponding to the returns of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsVariances |
number[] | Array containing assets numbers, with assetsVariances[i] corresponding to the variance of asset i+1, i=0..assets-1 |
Errors
Refer to the API response codes section.
Variances (from covariance matrix)
Computes the variances of assets from their covariance matrix.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/variances |
POST |
The following command computes the variances of 2 assets with covariance matrix $\begin{bmatrix} 0.01 & -0.0025 \newline -0.0025 & 0.0025 \end{bmatrix}$:
curl "https://api.portfoliooptimizer.io/v1/assets/variances" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsCovarianceMatrix":[[0.01,-0.0025],[-0.0025,0.0025]] }'
It returns the following JSON, which corresponds to variances $\sigma_1^2 = 0.01$ and $\sigma_2^2 = 0.0025$:
{
"assetsVariances":[0.01,0.0025]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsVariances |
number[] | Array containing assets numbers, with assetsVariances[i] corresponding to the variance of asset i+1, i=0..assets-1 |
Errors
Refer to the API response codes section.
Variances (from volatilities)
Computes the variances of assets from their volatilities (i.e., standard deviations).
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/variances |
POST |
The following command computes the variances of 2 assets with volatilities $\sigma_1 = 0.1$ and $\sigma_2 = 0.05$:
curl "https://api.portfoliooptimizer.io/v1/assets/variances" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsVolatilities":[0.1, 0.05] }'
It returns the following JSON, which corresponds to variances $\sigma_1^2 \approx 0.01$ and $\sigma_2^2 \approx 0.0025$:
{
"assetsVariances":[0.010000000000000002,0.0025000000000000005]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsVolatilities |
number[] | Array containing assets numbers, with assetsVolatilities[i] corresponding to the volatility of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsVariances |
number[] | Array containing assets numbers, with assetsVariances[i] corresponding to the variance of asset i+1, i=0..assets-1 |
Errors
Refer to the API response codes section.
Sample variances (from returns)
Computes the sample variances of assets from their returns.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/variances/sample |
POST |
The following command computes the sample variances of 2 assets based on 4 returns per asset:
curl "https://api.portfoliooptimizer.io/v1/assets/variances/sample" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns":[[0.01,0.01,0.02,0.01], [-0.02,-0.02,-0.04,-0.02]] }'
It returns the following JSON, which corresponds to variances $\sigma_1^2 = 0.000025$ and $\sigma_2^2 = 0.0001$:
{
"assetsVariances":[0.000025,0.0001]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] [] | Array containing assets arrays of identical length, with assetsReturns[i] corresponding to the returns of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsVariances |
number[] | Array containing assets numbers, with assetsVariances[i] corresponding to the sample variance of asset i+1, i=0..assets-1 |
Errors
Refer to the API response codes section.
Assets Volatilities
Volatilities (from returns)
Computes the volatilities (i.e., standard deviations) of assets from their returns.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/volatilities |
POST |
The following command computes the volatilities of 2 assets based on 4 returns per asset:
curl "https://api.portfoliooptimizer.io/v1/assets/volatilities" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns":[[0.01,0,0.02,-0.03], [0.01,0,0.02,-0.03]] }'
It returns the following JSON, which corresponds to volatilities $\sigma_1 \approx 1.87$% and $\sigma_2 \approx 1.87$%:
{
"assetsVolatilities":[0.01870828693386971,0.01870828693386971]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] [] | Array containing assets arrays of identical length, with assetsReturns[i] corresponding to the returns of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsVolatilities |
number[] | Array containing assets numbers, with assetsVolatilities[i] corresponding to the volatility of asset i+1, i=0..assets-1 |
Errors
Refer to the API response codes section.
Volatilities (from covariance matrix)
Computes the volatilities (i.e., standard deviations) of assets from their covariance matrix.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/volatilities |
POST |
The following command computes the volatilities of 2 assets with covariance matrix $\begin{bmatrix} 0.01 & -0.0025 \newline -0.0025 & 0.0025 \end{bmatrix}$:
curl "https://api.portfoliooptimizer.io/v1/assets/volatilities" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsCovarianceMatrix":[[0.01,-0.0025],[-0.0025,0.0025]] }'
It returns the following JSON, which corresponds to volatilities $\sigma_1 = 0.1$% and $\sigma_2 = 0.05$%:
{
"assetsVolatilities":[0.1,0.05]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsVolatilities |
number[] | Array containing assets numbers, with assetsVolatilities[i] corresponding to the volatility of asset i+1, i=0..assets-1 |
Errors
Refer to the API response codes section.
Volatilities (from variances)
Computes the volatilities (i.e., standard deviations) of assets from their variances.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/volatilities |
POST |
The following command computes the volatilities of 2 assets with variances $\sigma_1^2 = 0.01$ and $\sigma_2^2 = 0.0025$:
curl "https://api.portfoliooptimizer.io/v1/assets/volatilities" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsVariances":[0.01, 0.0025] }'
It returns the following JSON, which corresponds to volatilities $\sigma_1 = 0.1$ and $\sigma_2 = 0.05$:
{
"assetsVolatilities":[0.1,0.05]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsVariances |
number[] | Array containing assets numbers, with assetsVariances[i] corresponding to the variance of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsVolatilities |
number[] | Array containing assets numbers, with assetsVolatilities[i] corresponding to the volatility of asset i+1, i=0..assets-1 |
Errors
Refer to the API response codes section.
Sample volatilities (from returns)
Computes the sample volatilities (i.e., sample standard deviations) of assets from their returns.
HTTP Request
Endpoint | Method |
---|---|
/v1/assets/volatilities/sample |
POST |
The following command computes the sample volatilities of 2 assets based on 4 returns per asset:
curl "https://api.portfoliooptimizer.io/v1/assets/volatilities/sample" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns":[[0.01,0.01,0.02,0.01], [-0.02,-0.02,-0.04,-0.02]] }'
It returns the following JSON, which corresponds to volatilities $\sigma_1 = 0.005$% and $\sigma_2 = 0.01$%:
{
"assetsVolatilities":[0.005,0.01]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] [] | Array containing assets arrays of identical length, with assetsReturns[i] corresponding to the returns of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsVolatilities |
number[] | Array containing assets numbers, with assetsVolatilities[i] corresponding to the sample volatility of asset i+1, i=0..assets-1 |
Errors
Refer to the API response codes section.
Portfolio Generation
Random Portfolio Weights
Computes one or several random portfolio(s) weights, optionally subject to:
- Minimum and maximum weights constraints
- Minimum and maximum portfolio exposure constraints
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/generation/random |
POST |
The following command computes 2 random portfolios, each made of 3 assets:
curl "https://api.portfoliooptimizer.io/v1/portfolio/generation/random" \
-H "Content-Type: application/json" \
-d '{ "assets": 3, "portfolios": 2 }'
It can return the following JSON:
{
"portfolios":[
{
"assetsWeights":[0.11429744284625785,0.0038592674702259393,0.8818432896835162]
},
{
"assetsWeights":[0.546026607601722,0.07707923859010406,0.376894153808174]
}
]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
portfolios |
integer | Optional, defaults to 25 The number of random portfolios to compute |
constraints |
object | Optional The constraints on the portfolio and on the assets |
constraints.minimumAssetsWeights |
number[] | Optional, defaults minimumAssetsWeights[i] = 0, i=0..assets-1 Array containing assets numbers, corresponding to the minimum weights constraints and satisfying 0 <= minimumAssetsWeights[i] <= 1, i=0..assets-1 |
constraints.maximumAssetsWeights |
number[] | Optional, defaults maximumAssetsWeights[i] = 1, i=0..assets-1 Array containing assets numbers, corresponding to the maximum weights constraints and satisfying 0 <= maximumAssetsWeights[i] <= 1 and minimumAssetsWeights[i] <= maximumAssetsWeights[i], i=0..assets-1 |
constraints.minimumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the minimum portfolio exposure, in percentage, with 0 <= minimumPortfolioExposure <= 1 |
constraints.maximumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the maximum portfolio exposure, in percentage, with 0 <= maximumPortfolioExposure <= 1 and minimumPortfolioExposure <= maximumPortfolioExposure |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
portfolios |
object[] | Array containing portfolios arrays, with portfolios[i] corresponding the i+1-th portfolio, i=0..portfolios-1 |
portfolios[i].assetsWeights |
number[] | Array containing assets numbers, with portfolios[i].assetsWeights[j] corresponding to the weight of the asset j+1 in the i+1-th portfolio, in percentage, j=0..assets-1 |
Errors
Refer to the API response codes section.
References
William Thornton Shaw, Monte Carlo Portfolio Optimization for General Investor Risk-Return Objectives and Arbitrary Return Distributions: A Solution for Long-Only Portfolios
Random Portfolio Values
Computes one or several multi-period random portfolio(s) values, the portfolio(s) being rebalanced toward random portfolio weights at each time period.
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/generation/multi-period/random-rebalancing |
POST |
The following command computes 2 random portfolios, each made of 3 assets:
curl "https://api.portfoliooptimizer.io/v1/portfolio/generation/multi-period/random-rebalancing" \
-H "Content-Type: application/json" \
-d '{ "assets": 3,
"assetsPrices": [[100, 105, 110], [15, 12.5, 11.25], [0.5, 0.51, 0.49]],
"portfolios": 2 }'
It can return the following JSON:
{
"portfolios":[{
"portfolioValues":[100,90.8178403620342,84.65407625993741]
},
{
"portfolioValues":[100,102.43258698946813,101.32419718013273]
}]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsPrices |
number[] [] | Array containing assets arrays, with assetsPrices[i][j] corresponding to the prices of asset i+1, i=0..assets-1 at the j+1-th time period |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
portfolios |
object[] | Array containing portfolios arrays, with portfolios[i] corresponding the i+1-th portfolio, i=0..portfolios-1 |
portfolios[i].portfolioValues |
number[] | Array containing assetsPrices[0].length numbers, with portfolios[i].portfolioValues[j] corresponding to the value of the i+1-th portfolio at the j+1-th time period |
Errors
Refer to the API response codes section.
References
R Stein, Not fooled by randomness: Using random portfolios to analyse investment funds, Investment Analysts Journal, 43:79, 1-15, DOI: 10.1080/10293523.2014.11082564](https://www.tandfonline.com/doi/abs/10.1080/10293523.2014.11082564)
Portfolio Optimization
Equal Sharpe Ratio Contributions Portfolio
Computes the weights of the assets composing an equal Sharpe Ratio contributions portfolio.
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/equal-sharpe-ratio-contributions |
POST |
The following command computes the portfolio weights for $n=2$ assets, with assets returns $\mu_1 = 0.05$% and $\mu_2 = 0.1$%, an assets covariance matrix $\Sigma = \begin{bmatrix} 0.05 & 0.02 \newline 0.02 & 0.07 \end{bmatrix}$ and a with a risk free rate of $0$%:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/equal-sharpe-ratio-contributions" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns": [0.05, 0.1],
"assetsCovarianceMatrix": [[0.05, 0.02], [0.02, 0.07]],
"riskFreeRate": 0 }'
It returns the following JSON, which corresponds to $w_1 \approx 67$% and $w_2 \approx 33$%:
{
"assetsWeights":[0.6666666666666666, 0.3333333333333333]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] | Array containing assets numbers, with assetsReturns[i] corresponding to the return of asset i+1, i=0..assets-1 |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
riskFreeRate |
number | Number corresponding to the value of the risk free rate, in the same unit as the returns of the assets in assetsReturns |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
Andreas Steiner, Sharpe Ratio Contribution and Attribution Analysis
Equal Risk Contributions Portfolio
Computes the weights of the assets composing an equal risk contributions portfolio, optionally subject to:
- Minimum and maximum weights constraints
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/equal-risk-contributions |
POST |
The following command computes the portfolio weights for $n=2$ assets, with a covariance matrix $\Sigma = \begin{bmatrix} 0.0025 & 0.0005 \newline 0.0005 & 0.01 \end{bmatrix}$, a maximum weight constraint $u_1$ for asset 1 equal to 40% and a maximum weight constraint $u_2$ for asset 2 equal to 100%:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/equal-risk-contributions" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsCovarianceMatrix": [[0.0025, 0.0005], [0.0005, 0.01]],
"constraints": {"maximumAssetsWeights": [0.4, 1]} }'
It returns the following JSON, which corresponds to $w_1 = 40$% and $w_2 \approx 60$%:
{
"assetsWeights":[0.4, 0.5999999999046443]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
constraints |
object | Optional The constraints on the portfolio and on the assets |
constraints.minimumAssetsWeights |
number[] | Optional, defaults minimumAssetsWeights[i] = 0, i=0..assets-1 Array containing assets numbers, corresponding to the minimum weights constraints and satisfying 0 <= minimumAssetsWeights[i] <= 1, i=0..assets-1 |
constraints.maximumAssetsWeights |
number[] | Optional, defaults maximumAssetsWeights[i] = 1, i=0..assets-1 Array containing assets numbers, corresponding to the maximum weights constraints and satisfying 0 <= maximumAssetsWeights[i] <= 1 and minimumAssetsWeights[i] <= maximumAssetsWeights[i], i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
Richard, Jean-Charles and Roncalli, Thierry, Constrained Risk Budgeting Portfolios: Theory, Algorithms, Applications & Puzzles
Equal Weighted Portfolio
Computes the weights of the assets composing an equal weighted portfolio.
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/equal-weighted |
POST |
The following command computes the portfolio weights for $n=2$ assets:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/equal-weighted" \
-H "Content-Type: application/json" \
-d '{ "assets": 2 }'
It returns the following JSON, which corresponds to $w_1 = w_2 = 50$%:
{
"assetsWeights":[0.5,0.5]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
Victor DeMiguel and al., Optimal Versus Naive Diversification: How Inefficient is the 1/N Portfolio Strategy?
Inverse Variance Weighted Portfolio
Computes the weights of the assets composing an inverse variance weighted portfolio.
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/inverse-variance-weighted |
POST |
The following command computes the portfolio weights for $n=2$ assets, with $\sigma_1^2 = 1$ and $\sigma_2^2 = 0.5$:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/inverse-variance-weighted" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsVariances": [1, 0.5] }'
It returns the following JSON, which corresponds to $w_1 \approx 33$% and $w_2 \approx 67$%:
{
"assetsWeights":[0.3333333333333333,0.6666666666666666]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsVariances |
number[] | Array containing assets numbers, with assetsVariances[i] corresponding to the variance of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
Raul Leote de Carvalho and al., Demystifying Equity Risk-Based Strategies: A Simple Alpha Plus Beta Description
Inverse Volatility Weighted Portfolio
Computes the weights of the assets composing an inverse volatility weighted portfolio.
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/inverse-volatility-weighted |
POST |
The following command computes the portfolio weights for $n=2$ assets, with $\sigma_1 = 5$% and $\sigma_2 = 10$%:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/inverse-volatility-weighted" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsVolatilities": [0.05, 0.10] }'
It returns the following JSON, which corresponds to $w_1 \approx 67$% and $w_2 \approx 33$%:
{
"assetsWeights":[0.6666666666666666,0.3333333333333333]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsVolatilities |
number[] | Array containing assets numbers, with assetsVolatilities[i] corresponding to the volatility of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
Raul Leote de Carvalho and al., Demystifying Equity Risk-Based Strategies: A Simple Alpha Plus Beta Description
Market Capitalization Weighted Portfolio
Computes the weights of the assets composing a market capitalization weighted portfolio.
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/market-capitalization-weighted |
POST |
The following command computes the portfolio weights for $n=2$ assets, with $mktcap_1 = 1$ and $mktcap_2 = 2$:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/market-capitalization-weighted" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsMarketCapitalizations": [1, 2] }'
It returns the following JSON, which corresponds to $w_1 \approx 33$% and $w_2 \approx 67$%:
{
"assetsWeights":[0.3333333333333333,0.6666666666666666]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsMarketCapitalizations |
number[] | Array containing assets numbers, with assetsMarketCapitalizations[i] corresponding to the market capitalization of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
N/A
Maximum Decorrelation Portfolio
Computes the weights of the assets composing the maximum decorrelation portfolio, optionally subject to:
- Minimum and maximum weights constraints
- Minimum and maximum portfolio exposure constraints
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/maximum-decorrelation |
POST |
The following command computes the portfolio weights for $n=2$ assets, with a correlation matrix equal to $\begin{bmatrix} 1 & 0.90 & 0.85 \newline 0.90 & 1 & 0.70 \newline 0.85 & 0.70 & 1 \end{bmatrix}$:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/maximum-decorrelation" \
-H "Content-Type: application/json" \
-d '{ "assets": 3,
"assetsCorrelationMatrix": [[1,0.90,0.85], [0.90,1,0.70], [0.85,0.70,1]] }'
It returns the following JSON, which corresponds to $w_1 = 0$%, $w_2 = 50$% and $w_3 = 50$%:
{
"assetsWeights":[0,0.5,0.5]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCorrelationMatrix |
number[] [] | Array containing assets arrays, with assetsCorrelationMatrix[i] an array containing assets numbers and assetsCorrelationMatrix[i][j] corresponding to the correlation between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
constraints |
object | Optional The constraints on the portfolio and on the assets |
constraints.minimumAssetsWeights |
number[] | Optional, defaults minimumAssetsWeights[i] = 0, i=0..assets-1 Array containing assets numbers, corresponding to the minimum weights constraints and satisfying 0 <= minimumAssetsWeights[i] <= 1, i=0..assets-1 |
constraints.maximumAssetsWeights |
number[] | Optional, defaults maximumAssetsWeights[i] = 1, i=0..assets-1 Array containing assets numbers, corresponding to the maximum weights constraints and satisfying 0 <= maximumAssetsWeights[i] <= 1 and minimumAssetsWeights[i] <= maximumAssetsWeights[i], i=0..assets-1 |
constraints.minimumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the minimum portfolio exposure, in percentage, with 0 <= minimumPortfolioExposure <= 1 |
constraints.maximumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the maximum portfolio exposure, in percentage, with 0 <= maximumPortfolioExposure <= 1 and minimumPortfolioExposure <= maximumPortfolioExposure |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
Scientific Beta Maximum Decorrelation Indices
Maximum Sharpe Ratio Portfolio
Computes the weights of the assets composing the maximum Sharpe Ratio portfolio, optionally subject to:
- Minimum and maximum weights constraints
- Minimum and maximum portfolio exposure constraints
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/maximum-sharpe-ratio |
POST |
The following command computes the portfolio weights for $n=2$ assets, with assets returns $\mu_1 = 0.05$% and $\mu_2 = 0.1$%, an assets covariance matrix $\Sigma = \begin{bmatrix} 0.05 & 0.02 \newline 0.02 & 0.07 \end{bmatrix}$ and a with a risk free rate of $0$%:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/maximum-sharpe-ratio" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns": [0.05, 0.1],
"assetsCovarianceMatrix": [[0.05, 0.02], [0.02, 0.07]],
"riskFreeRate": 0 }'
It returns the following JSON, which corresponds to $w_1 \approx 27$% and $w_2 \approx 73$%:
{
"assetsWeights":[0.27272727272727276,0.7272727272727273]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] | Array containing assets numbers, with assetsReturns[i] corresponding to the return of asset i+1, i=0..assets-1 |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
riskFreeRate |
number | Number corresponding to the value of the risk free rate, in the same unit as the returns of the assets in assetsReturns |
constraints |
object | Optional The constraints on the portfolio and on the assets |
constraints.minimumAssetsWeights |
number[] | Optional, defaults minimumAssetsWeights[i] = 0, i=0..assets-1 Array containing assets numbers, corresponding to the minimum weights constraints and satisfying 0 <= minimumAssetsWeights[i] <= 1, i=0..assets-1 |
constraints.maximumAssetsWeights |
number[] | Optional, defaults maximumAssetsWeights[i] = 1, i=0..assets-1 Array containing assets numbers, corresponding to the maximum weights constraints and satisfying 0 <= maximumAssetsWeights[i] <= 1 and minimumAssetsWeights[i] <= maximumAssetsWeights[i], i=0..assets-1 |
constraints.minimumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the minimum portfolio exposure, in percentage, with 0 <= minimumPortfolioExposure <= 1 |
constraints.maximumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the maximum portfolio exposure, in percentage, with 0 <= maximumPortfolioExposure <= 1 and minimumPortfolioExposure <= maximumPortfolioExposure |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
Mean-Variance Efficient Portfolio
Computes the weights of the assets composing an efficient mean-variance portfolio - that is, a portfolio belonging to the mean-variance efficient frontier -, optionally subject to:
- Minimum and maximum weights constraints
- Minimum and maximum portfolio exposure constraints
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/mean-variance |
POST |
The following command computes the portfolio weights for $n=2$ assets, with assets returns $\mu_1 = 0.1$% and $\mu_2 = 0.2$%, an assets covariance matrix $\Sigma = \begin{bmatrix} 1 & 0.3 \newline 0.3 & 1 \end{bmatrix}$ and a portfolio return constraint $r_c$ equal to $0.15$%:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/mean-variance" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns": [0.1, 0.2],
"assetsCovarianceMatrix": [[1, 0.3], [0.3, 1]],
"constraints": {"portfolioReturn": 0.15} }'
It returns the following JSON, which corresponds to $w_1 = 50$% and $w_2 = 50$%:
{
"assetsWeights":[0.5,0.5]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] | Array containing assets numbers, with assetsReturns[i] corresponding to the return of asset i+1, i=0..assets-1 |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
constraints |
object | The constraints on the portfolio and on the assets |
constraints.portfolioReturn |
number | Conditional, exclusive with constraints.portfolioVolatility and constraints.riskTolerance Corresponds to the portfolio return constraint |
constraints.portfolioVolatility |
number | Conditional, exclusive with constraints.portfolioReturn and constraints.riskTolerance Corresponds to the portfolio volatility constraint, with portfolioVolatility >= 0, in percentage |
constraints.riskTolerance |
number | Conditional, exclusive with constraints.portfolioReturn and constraints.portfolioVolatility Corresponds to the portfolio risk tolerance parameter, with riskTolerance >= 0 |
constraints.minimumAssetsWeights |
number[] | Optional, defaults minimumAssetsWeights[i] = 0, i=0..assets-1 Array containing assets numbers, corresponding to the minimum weights constraints and satisfying 0 <= minimumAssetsWeights[i] <= 1, i=0..assets-1 |
constraints.maximumAssetsWeights |
number[] | Optional, defaults maximumAssetsWeights[i] = 1, i=0..assets-1 Array containing assets numbers, corresponding to the maximum weights constraints and satisfying 0 <= maximumAssetsWeights[i] <= 1 and minimumAssetsWeights[i] <= maximumAssetsWeights[i], i=0..assets-1 |
constraints.minimumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the minimum portfolio exposure, in percentage, with 0 <= minimumPortfolioExposure <= 1 |
constraints.maximumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the maximum portfolio exposure, in percentage, with 0 <= maximumPortfolioExposure <= 1 and minimumPortfolioExposure <= maximumPortfolioExposure |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
Harry M. Markowitz, Portfolio Selection, Efficient Diversification of Investments, Second edition, Blackwell Publishers Inc.
Minimum Correlation Portfolio
Computes the weights of the assets composing the minimum correlation portfolio, using the Minimum Correlation Algorithm discovered by David Varadi.
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/minimum-correlation |
POST |
The following command computes the portfolio weights for $n=3$ assets, using the correlation matrix and the standard deviations provided as examples in the Minimum Correlation Algorithm paper: $C = \begin{bmatrix} 1 & 0.90 & 0.85 \newline 0.90 & 1 & 0.70 \newline 0.85 & 0.70 & 1 \end{bmatrix}$ and $\sigma = (0.14, 0.18, 0.22) {}^t$:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/minimum-correlation" \
-H "Content-Type: application/json" \
-d '{ "assets": 3,
"assetsCorrelationMatrix":[[1,0.90,0.85], [0.90,1,0.70], [0.85,0.70,1]],
"assetsVolatilities": [0.14, 0.18, 0.22] }'
It returns the following JSON, which corresponds numerically to the portfolio weights computed in the Minimum Correlation Algorithm paper: $w_1 \approx 21$%, $w_2 \approx 31$% and $w_3 \approx 48$%:
{
"assetsWeights":[ 0.21059806981924115,0.3087866303991204,0.48061529978163836]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCorrelationMatrix |
number[] [] | Array containing assets arrays, with assetsCorrelationMatrix[i] an array containing assets numbers and assetsCorrelationMatrix[i][j] corresponding to the correlation between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
assetsVolatilities |
number[] | Array containing assets numbers, with assetsVolatilities[i] corresponding to the volatility of asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
CSSA, Minimum Correlation Algorithm Paper Release
Minimum Variance Portfolio
Computes the weights of the assets composing the minimum variance portfolio, optionally subject to:
- Minimum and maximum weights constraints
- Minimum and maximum portfolio exposure constraints
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/minimum-variance |
POST |
The following command computes the portfolio weights for $n=2$ assets, with a covariance matrix $\Sigma$ equal to $\begin{bmatrix} 0.0025 & 0.0005 \newline 0.0005 & 0.01 \end{bmatrix}$, a maximum weight constraint $u_1$ for asset 1 equal to 40%, a maximum weight constraint $u_2$ for asset 2 equal to 100% and an exact portfolio exposure of 50% thanks to $w_{min} = w_{max} = 50$%:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/minimum-variance" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsCovarianceMatrix": [[0.0025, 0.0005], [0.0005, 0.01]],
"constraints": {"maximumAssetsWeights": [0.4, 1],
"minimumPortfolioExposure": 0.50, "maximumPortfolioExposure": 0.50} }'
It returns the following JSON, which corresponds to $w_1 = 40$% and $w_2 \approx 10$%:
{
"assetsWeights":[0.4,0.09999999999998999]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
constraints |
object | Optional The constraints on the portfolio and on the assets |
constraints.minimumAssetsWeights |
number[] | Optional, defaults minimumAssetsWeights[i] = 0, i=0..assets-1 Array containing assets numbers, corresponding to the minimum weights constraints and satisfying 0 <= minimumAssetsWeights[i] <= 1, i=0..assets-1 |
constraints.maximumAssetsWeights |
number[] | Optional, defaults maximumAssetsWeights[i] = 1, i=0..assets-1 Array containing assets numbers, corresponding to the maximum weights constraints and satisfying 0 <= maximumAssetsWeights[i] <= 1 and minimumAssetsWeights[i] <= maximumAssetsWeights[i], i=0..assets-1 |
constraints.minimumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the minimum portfolio exposure, in percentage, with 0 <= minimumPortfolioExposure <= 1 |
constraints.maximumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the maximum portfolio exposure, in percentage, with 0 <= maximumPortfolioExposure <= 1 and minimumPortfolioExposure <= maximumPortfolioExposure |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
Harry M. Markowitz, Portfolio Selection, Efficient Diversification of Investments, Second edition, Blackwell Publishers Inc.
Most Diversified Portfolio
Computes the weights of the assets composing the most diversified portfolio, optionally subject to:
- Minimum and maximum weights constraints
- Minimum and maximum portfolio exposure constraints
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/optimization/most-diversified |
POST |
The following command computes the portfolio weights for $n=2$ assets, with a covariance matrix $\Sigma$ equal to $\begin{bmatrix} 0.0400 & 0.0100 \newline 0.0100 & 0.0100 \end{bmatrix}$:
curl "https://api.portfoliooptimizer.io/v1/portfolio/optimization/most-diversified" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsCovarianceMatrix": [[0.0400, 0.0100], [0.0100, 0.0100]] }'
It returns the following JSON, which corresponds to $w_1 \approx 33$% and $w_2 \approx 67$%:
{
"assetsWeights":[0.33333333333333337,0.6666666666666666]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
constraints |
object | Optional The constraints on the portfolio and on the assets |
constraints.minimumAssetsWeights |
number[] | Optional, defaults minimumAssetsWeights[i] = 0, i=0..assets-1 Array containing assets numbers, corresponding to the minimum weights constraints and satisfying 0 <= minimumAssetsWeights[i] <= 1, i=0..assets-1 |
constraints.maximumAssetsWeights |
number[] | Optional, defaults maximumAssetsWeights[i] = 1, i=0..assets-1 Array containing assets numbers, corresponding to the maximum weights constraints and satisfying 0 <= maximumAssetsWeights[i] <= 1 and minimumAssetsWeights[i] <= maximumAssetsWeights[i], i=0..assets-1 |
constraints.minimumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the minimum portfolio exposure, in percentage, with 0 <= minimumPortfolioExposure <= 1 |
constraints.maximumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the maximum portfolio exposure, in percentage, with 0 <= maximumPortfolioExposure <= 1 and minimumPortfolioExposure <= maximumPortfolioExposure |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
Portfolio Construction
Investable Portfolio
Computes an investable portfolio as close as possible to a desired portfolio, taking into account:
- The desired portfolio assets weights
- The desired portfolio assets groups weights
- The desired portfolio maximum assets groups weights
- The portfolio monetary value
- The portfolio assets prices
- The possibility, for some of the portfolio assets, to buy fractional shares
- The obligation, for some of the portfolio assets, to buy round lots of shares
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/construction/investable |
POST |
The following command computes an investable portfolio of 10,000\$ made of 3 assets with respective prices 10\$, 25\$ and 500\$ and with weights as close as possible to the desired weights of $w_1 = 5$%, $w_2 = 60$% and $w_3 = 35$%:
curl "https://api.portfoliooptimizer.io/v1/portfolio/construction/investable" \
-H "Content-Type: application/json" \
-d '{ "assets": 3,
"assetsPrices": [10, 25, 500],
"assetsWeights": [0.05, 0.60, 0.35],
"portfolioValue": 10000 }'
It returns the following JSON, which indicates that the investable portfolio perfectly matches the desired portfolio because the investable portfolio weights are 5% for asset 1 (corresponding to 50 shares), 60% for asset 2 (corresponding to 240 shares) and 35% for asset 3 (corresponding to 7 shares):
{
"assetsPositions":[50,240,7],
"assetsWeights":[0.05,0.6,0.35]
}
The following command computes an investable portfolio of 10,000\$ made of 4 assets with respective prices 10\$, 25\$, 100\$ and 500\$ and with weights as close as possible to the desired weights of $w_1 = 20$% and with groups weights as close as possible to the desired groups weights of $wg_1 = 40$%, with group 1 made of assets 1 and 2, and $wg_2 = 40$%, with group 2 made of assets 3 and 4:
curl "https://api.portfoliooptimizer.io/v1/portfolio/construction/investable" \
-H "Content-Type: application/json" \
-d '{ "assets": 4,
"assetsPrices": [10, 25, 100, 500],
"assetsWeights": [0.20, null, null, null],
"assetsGroupsWeights": { "assetsGroups": [[1,2], [3,4]], "weights": [0.40, 0.40] },
"portfolioValue": 10000 }'
It returns the following JSON, which indicates that the investable portfolio perfectly matches the desired portfolio because the investable portfolio weights are 20% for asset 1, 40% for group 1 made of assets 1 and 2 and 40% for group 2 made of assets 3 and 4:
{
"assetsPositions":[200,80,20,4],
"assetsWeights":[0.2,0.2,0.2,0.2]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the desired portfolio (possibly null), in percentage, i=0..assets-1 |
assetsGroupsWeights |
object | Optional |
assetsGroupsWeights.assetsGroups |
number[] [] | Array containing at least one array, with assetsGroupsWeights.assetsGroups[i] an array containing at least two and at most assets unique and strictly positive integers corresponding to the indexes of the assets belonging to a group of assets in the desired portfolio |
assetsGroupsWeights.weights |
number[] | Array containing assetsGroupsWeights.assetsGroups.length numbers, with assetsGroupsWeights.weights[i] corresponding to the weight of the group of assets defined by the indexes in assetsGroupsWeights.groups[i] in the desired portfolio, in percentage, i=0..assetsGroupsWeights.groups.length-1 |
maximumAssetsGroupsWeights |
object | Optional |
maximumAssetsGroupsWeights.assetsGroups |
number[] [] | Array containing at least one array, with maximumAssetsGroupsWeights.assetsGroups[i] an array containing at least two and at most assets unique and strictly positive integers corresponding to the indexes of the assets belonging to a group of assets in the desired portfolio |
maximumAssetsGroupsWeights.maximumWeights |
number[] | Array containing maximumAssetsGroupsWeights.assetsGroups.length numbers, with maximumAssetsGroupsWeights.maximumWeights[i] corresponding to the maximum weight of the group of assets defined by the indexes in maximumAssetsGroupsWeights.groups[i] in the desired portfolio, in percentage, i=0..maximumAssetsGroupsWeights.groups.length-1 |
portfolioValue |
number | The monetary value of the portfolio, including cash |
assetsPrices |
number[] | Array containing assets numbers, with assetsPrices[i] corresponding to the price of asset i+1, i=0..assets-1 |
assetsSizeLots |
number[] | Optional, defaults assetsSizeLots[i] = 1, i=0..assets-1 Array containing assets numbers, with assetsSizeLots[i] corresponding to size of the lots when buying asset i+1, i=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
assetsPositions |
integer[] | Array containing assets integers, with assetsPositions[i] corresponding to the number of shares of the asset i+1 in the investable portfolio, i=0..assets-1 |
assetsWeights |
number[] | Array containing assets numbers, with assetsWeights[i] corresponding to the weight of the asset i+1 in the investable portfolio, in percentage, i=0..assets-1 |
Errors
Refer to the API response codes section.
References
Steiner, Andreas, Accuracy and Rounding in Portfolio Construction
Portfolio Analysis
Portfolio Drawdowns
Computes the drawdown function - also called the underwater equity curve -, as well as the worst 10 drawdowns of one or several portfolio(s).
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/analysis/drawdowns |
POST |
The following command computes the drawdown (underwater) curve and the worst 10 drawdowns of a portfolio whose values are [100, 110, 105, 95, 85, 70]:
curl "https://api.portfoliooptimizer.io/v1/portfolio/analysis/drawdowns" \
-H "Content-Type: application/json" \
-d '{ "portfoliosValues": [[100, 95, 100, 90, 85, 70]] }'
It returns the following JSON, which corresponds in particular to a maximum drawdown of 30%, which began in the third period, which reached its bottom in the sixth period, and which is not ended yet:
{
"portfolios":[{
"portfolioDrawdowns":[0,0.05,0,0.1,0.15,0.3],
"portfolioWorstDrawdowns":[{
"drawdownDepth":0.3,
"drawdownStart":3,
"drawdownBottom":6,
"drawdownEnd":0
},
{
"drawdownDepth":0.05,
"drawdownStart":1,
"drawdownBottom":2,
"drawdownEnd":3
}]
}]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
portfoliosValues |
number[] [] | Array of arrays, with portfoliosValues[i][j] corresponding to the value of the i+1-th portfolio at the j+1-th time period |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
portfolios |
object[] | Array containing portfoliosValues.length objects, with portfolios[i] corresponding to the i+1-th portfolio for which the drawdowns have been computed, i=0..portfoliosValues.length -1 |
portfolios[i].portfolioDrawdowns |
number[] | Array containing portfoliosValues[i].length numbers, with portfolios[i].portfolioDrawdowns[j] corresponding to the value of the drawdown function of the i+1-th portfolio at the j+1-th time period, in percentage |
portfolios[i].portfolioWorstDrawdowns |
object[] | Array containing at most 10 arrays, with portfolios[i].portfolioWorstDrawdowns[j] corresponding to the worst j+1-th drawdown of i+1-th portfolio |
portfolios[i].portfolioWorstDrawdowns[j].drawdownDepth |
number | The depth - or magnitude - of the worst j+1-th drawdown of the i+1-th portfolio, in percentage |
portfolios[i].portfolioWorstDrawdowns[j].drawdownStart |
number | The time period at which the worst j+1-th drawdown of the i+1-th portfolio starts |
portfolios[i].portfolioWorstDrawdowns[j].drawdownBottom |
number | The time period at which the worst j+1-th drawdown of the i+1-th portfolio bottoms, that is, with no more lower lows |
portfolios[i].portfolioWorstDrawdowns[j].drawdownEnd |
number | The time period at which the worst j+1-th drawdown of the i+1-th portfolio ends, with the value 0 meaning that it does not end (yet) |
Errors
Refer to the API response codes section.
References
Carl R. Bacon, Practical Portfolio Performance Measurement and Attribution
Portfolio Mean-Variance (from assets returns and covariance matrix)
Computes the return and the volatility of one or several portfolio(s).
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/analysis/mean-variance |
POST |
The following command computes the return and the volatility of 2 portfolios of $n=2$ assets, with returns equal to $\mu_1 = 1$% and $\mu_2 = 5$% and a covariance matrix equal to $\Sigma = \begin{bmatrix} 0.0025 & 0.0005 \newline 0.0005 & 0.01 \end{bmatrix}$:
curl "https://api.portfoliooptimizer.io/v1/portfolio/analysis/mean-variance" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns": [0.01, 0.05],
"assetsCovarianceMatrix": [[0.0025, 0.0005], [0.0005, 0.01]],
"assetsWeights": [[1, 0], [0, 1]] }'
It returns the following JSON, which corresponds to the return and to the volatility of the first asset and of the second asset:
{
"portfolios":[
{
"portfolioReturn":0.01,
"portfolioVolatility":0.05
},
{
"portfolioReturn":0.05,
"portfolioVolatility":0.1
}
]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] | Array containing assets numbers, with assetsReturns[i] corresponding to the return of asset i+1, i=0..assets-1 |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
assetsWeights |
number[] [] | Array of arrays, with assetsWeights[i][j] corresponding to the weight of the asset j+1 in the i+1-th portfolio, in percentage, j=0..assets-1 |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
portfolios |
object[] | Array containing assetsWeights.length objects, with portfolios[i] corresponding to the i+1-th portfolio for which the return and the volatility have been computed, i=0..portfolios-1 |
portfolios[i].portfolioReturn |
number | The return of the i+1-th portfolio |
portfolios[i].portfolioVolatility |
number | The volatility of the i+1-th portfolio |
Errors
Refer to the API response codes section.
References
Harry M. Markowitz, Portfolio Selection, Efficient Diversification of Investments, Second edition, Blackwell Publishers Inc.
Portfolio Mean-Variance (from portfolio values)
Computes the average return and the volatility of one or several portfolio(s).
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/analysis/mean-variance |
POST |
The following command computes the average return and the volatility of a portfolio whose values are [100, 110, 105, 95, 85, 70]:
curl "https://api.portfoliooptimizer.io/v1/portfolio/analysis/mean-variance" \
-H "Content-Type: application/json" \
-d '{ "portfoliosValues": [[100, 95, 100, 90, 85, 70]] }'
It returns the following JSON, which corresponds to a portfolio average return of around $-6.6$% and to a portfolio volatility of around $7$%:
{
"portfolios":[
{
"portfolioReturn":-0.06587891296869626,
"portfolioVolatility":0.0745630142872523
}
]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
portfoliosValues |
number[] [] | Array of arrays, with portfoliosValues[i][j] corresponding to the value of the i+1-th portfolio at the *j+1-th *time period |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
portfolios |
object[] | Array containing portfoliosValues.length objects, with portfolios[i] corresponding to the i+1-th portfolio for which the average return and the volatility have been computed, i=0..portfolios-1 |
portfolios[i].portfolioReturn |
number | The average return of the i+1-th portfolio |
portfolios[i].portfolioVolatility |
number | The volatility of the i+1-th portfolio |
Errors
Refer to the API response codes section.
References
Carl R. Bacon, Practical Portfolio Performance Measurement and Attribution
Portfolio Return Contributions
Performs a return contribution analysis of one or several portfolio(s), optionally using groups of assets.
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/analysis/contributions/return |
POST |
The following command performs a return contributions analysis of a portfolio made of 3 assets with returns $\mu_1 = 1$%, $\mu_2 = -1$%, $\mu_3 = 2.5$% and with weights $w_1 = 50$%, $w_2 = 25$%, $w_3 = 25$%; additionally, the first 2 assets are grouped together, and the last asset is in its own group:
curl "https://api.portfoliooptimizer.io/v1/portfolio/analysis/contributions/return" \
-H "Content-Type: application/json" \
-d '{ "assets": 3,
"assetsReturns": [0.01, -0.01, 0.025],
"assetsWeights": [[0.50, 0.25, 0.25]],
"assetsGroups": [[1,2],[3]] }'
It returns the following JSON, which corresponds for example to a return contribution of the first asset to the return of the portfolio of $0.5$%, and to a return contribution of the first group of assets to the return of the portfolio of $0.25$%:
{
"portfolios":[
{
"portfolioReturnContributions": [0.005,-0.0025,0.00625],
"portfolioGroupsReturnContributions":[0.0025,0.00625]
}
]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] | Array containing assets numbers, with assetsReturns[i] corresponding to the return of asset i+1, i=0..assets-1 |
assetsWeights |
number[] [] | Array of arrays, with assetsWeights[i][j] corresponding to the weight of the asset j+1 in the i+1-th portfolio, in percentage, j=0..assets-1 |
assetsGroups |
number[] [] | Optional Array containing at least one array, with assetsGroups[i] an array containing at least one and at most assets unique and strictly positive integers corresponding to the indexes of the assets belonging to a group of assets |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
portfolios |
object[] | Array containing assetsWeights.length objects, with portfolios[i] corresponding to the i+1-th portfolio for which a return contribution analysis has been performed, i=0..portfolios-1 |
portfolios[i].portfolioReturnContributions |
number[] | Array containing assets elements, corresponding to the return contributions of the assets to the return of the i+1-th portfolio |
portfolios[i].portfolioGroupsReturnContributions |
number[] | Optional Array containing assetsGroups.length elements, corresponding to the return contributions of the assetsGroups.length groups of assets to the return of the i+1-th portfolio |
Errors
Refer to the API response codes section.
References
Carl R. Bacon, Practical Portfolio Performance Measurement and Attribution
Portfolio Risk Contributions
Performs a risk contribution analysis of one or several portfolio(s), optionally using groups of assets.
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/analysis/contributions/risk |
POST |
The following command performs a risk contributions analysis of a portfolio made of 3 assets with covariance matrix $\Sigma = \begin{bmatrix} 0.0001 & 0 & 0 \newline 0 & 0.0001 & 0 \newline 0 & 0 & 0.04 \end{bmatrix}$ and with weights $w_1 = 50$%, $w_2 = 25$%, $w_3 = 25$%:
curl "https://api.portfoliooptimizer.io/v1/portfolio/analysis/contributions/risk" \
-H "Content-Type: application/json" \
-d '{ "assets": 3,
"assetsCovarianceMatrix": [[0.0001,0,0],[0,0.0001,0],[0,0,0.04]],
"assetsWeights": [[0.50, 0.25, 0.25]] }'
It returns the following JSON, which corresponds for example to a risk contribution of the last asset to the risk of the portfolio of $\approx 0.05$%; the volatility of the portfolio being $\approx 0.05$%, it means the last asset is nearly responsible for the whole portfolio volatility!:
{
"portfolios":[
{
"portfolioRiskContributions": [0.0004969039949999533,0.00012422599874998834,0.049690399499995326]
}
]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
assetsWeights |
number[] [] | Array of arrays, with assetsWeights[i][j] corresponding to the weight of the asset j+1 in the i+1-th portfolio, in percentage, j=0..assets-1 |
assetsGroups |
number[] [] | Optional Array containing at least one array, with assetsGroups[i] an array containing at least one and at most assets unique and strictly positive integers corresponding to the indexes of the assets belonging to a group of assets |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
portfolios |
object[] | Array containing assetsWeights.length objects, with portfolios[i] corresponding to the i+1-th portfolio for which a risk contribution analysis has been performed, i=0..portfolios-1 |
portfolios[i].portfolioRiskContributions |
number[] | Array containing assets elements, corresponding to the risk contributions of the assets to the risk of the i+1-th portfolio |
portfolios[i].portfolioGroupsRiskContributions |
number[] | Optional Array containing assetsGroups.length elements, corresponding to the risk contributions of the assetsGroups.length groups of assets to the risk of the i+1-th portfolio |
Errors
Refer to the API response codes section.
References
Mean-Variance Efficient Frontier
Computes the (discretized) mean-variance efficient frontier associated to a list of assets, optionally subject to:
- Minimum and maximum weights constraints
- Minimum and maximum portfolio exposure constraints
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/analysis/mean-variance/efficient-frontier |
POST |
The following command computes 3 portfolios belonging to the mean-variance efficient frontier of $n=2$ assets, with returns equal to $\mu_1 = 1$% and $\mu_2 = 5$%, a covariance matrix equal to $\Sigma = \begin{bmatrix} 0.0025 & 0.0005 \newline 0.0005 & 0.01 \end{bmatrix}$, a minimum weight constraint $l_1$ for asset 1 equal to 20% and a minimum weight constraint $l_2$ for asset 2 equal to 0%:
curl "https://api.portfoliooptimizer.io/v1/portfolio/analysis/mean-variance/efficient-frontier" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns": [0.01, 0.05],
"assetsCovarianceMatrix": [[0.0025, 0.0005], [0.0005, 0.01]],
"portfolios": 3,
"constraints": {"minimumAssetsWeights": [0.2, 0]} }'
It returns the following JSON, which corresponds to the 3 computed portfolios, defined by their assets weights, their returns and their volatilities:
{
"efficientFrontierPortfolios":[
{
"assetsWeights":[0.8260869565217391,0.17391304347826086],
"portfolioReturn":0.016956521739130433,
"portfolioVolatility":0.0463915284620315
},
{
"assetsWeights":[0.5130434782608696,0.48695652173913045],
"portfolioReturn":0.02947826086956522,
"portfolioVolatility":0.05726369211623199
},
{
"assetsWeights":[0.2,0.8],
"portfolioReturn":0.04200000000000001,
"portfolioVolatility":0.08160882305241265
}
]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] [] | Array containing assets arrays, with assetsReturns[i] corresponding to the returns of asset i+1, i=0..assets-1 |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
portfolios |
integer | Optional, defaults to 25 The number of portfolios to compute on the mean-variance efficient frontier |
constraints |
object | Optional The constraints on the portfolio and on the assets |
constraints.minimumAssetsWeights |
number[] | Optional, defaults minimumAssetsWeights[i] = 0, i=0..assets-1 Array containing assets numbers, corresponding to the minimum weights constraints and satisfying 0 <= minimumAssetsWeights[i] <= 1, i=0..assets-1 |
constraints.maximumAssetsWeights |
number[] | Optional, defaults maximumAssetsWeights[i] = 1, i=0..assets-1 Array containing assets numbers, corresponding to the maximum weights constraints and satisfying 0 <= maximumAssetsWeights[i] <= 1 and minimumAssetsWeights[i] <= maximumAssetsWeights[i], i=0..assets-1 |
constraints.minimumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the minimum portfolio exposure, in percentage, with 0 <= minimumPortfolioExposure <= 1 |
constraints.maximumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the maximum portfolio exposure, in percentage, with 0 <= maximumPortfolioExposure <= 1 and minimumPortfolioExposure <= maximumPortfolioExposure |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
efficientFrontierPortfolios |
object[] | Array containing portfolios objects, with efficientFrontierPortfolios[i] corresponding to a portfolio on the mean-variance efficient frontier, i=0..portfolios-1 |
efficientFrontierPortfolios[i].assetsWeights |
number[] | Array containing assets numbers, with efficientFrontierPortfolios[i].assetsWeights[j] corresponding to the weight of the asset j+1 in the i-th portfolio, in percentage, j=0..assets-1 |
efficientFrontierPortfolios[i].portfolioReturn |
number | The return of the i-th portfolio |
efficientFrontierPortfolios[i].portfolioVolatility |
number | The volatility of the i-th portfolio |
Errors
Refer to the API response codes section.
References
Harry M. Markowitz, Portfolio Selection, Efficient Diversification of Investments, Second edition, Blackwell Publishers Inc.
Mean-Variance Minimum Variance Frontier
Computes the (discretized) mean-variance minimum variance frontier associated to a list of assets, optionally subject to:
- Minimum and maximum weights constraints
- Minimum and maximum portfolio exposure constraints
HTTP Request
Endpoint | Method |
---|---|
/v1/portfolio/analysis/mean-variance/minimum-variance-frontier |
POST |
The following command computes 4 portfolios belonging to the mean-variance minimum variance frontier of $n=2$ assets, with returns equal to $\mu_1 = 1$% and $\mu_2 = 5$%, a covariance matrix equal to $\Sigma = \begin{bmatrix} 0.0025 & 0.0005 \newline 0.0005 & 0.01 \end{bmatrix}$, a minimum weight constraint $l_1$ for asset 1 equal to 20% and a minimum weight constraint $l_2$ for asset 2 equal to 0%:
curl "https://api.portfoliooptimizer.io/v1/portfolio/analysis/mean-variance/minimum-variance-frontier" \
-H "Content-Type: application/json" \
-d '{ "assets": 2,
"assetsReturns": [0.01, 0.05],
"assetsCovarianceMatrix": [[0.0025, 0.0005], [0.0005, 0.01]],
"portfolios": 4,
"constraints": {"minimumAssetsWeights": [0.2, 0]} }'
It returns the following JSON, which corresponds to the 4 computed portfolios, defined by their assets weights, their returns and their volatilities:
{
"minimumVarianceFrontierPortfolios":[
{
"assetsWeights":[1,0],
"portfolioReturn":0.01,
"portfolioVolatility":0.05
},
{
"assetsWeights":[0.7333333333333333,0.2666666666666667],
"portfolioReturn":0.02066666666666667,
"portfolioVolatility":0.04744587559642156
},
{
"assetsWeights":[0.4666666666666667,0.5333333333333333],
"portfolioReturn":0.03133333333333334,
"portfolioVolatility":0.06031399321697891
},
{
"assetsWeights":[0.2,0.8],
"portfolioReturn":0.04200000000000001,
"portfolioVolatility":0.08160882305241265
}
]
}
Headers
Refer to the API headers section.
Query Parameters
N/A
Body Parameters
Field | Type | Description |
---|---|---|
assets |
number | The number of assets |
assetsReturns |
number[] | Array containing assets numbers, with assetsReturns[i] corresponding to the return of asset i+1, i=0..assets-1 |
assetsCovarianceMatrix |
number[] [] | Array containing assets arrays, with assetsCovarianceMatrix[i] an array containing assets numbers and assetsCovarianceMatrix[i][j] corresponding to the covariance between assets i+1 and j+1, i=0..assets-1, j=0..assets-1 |
portfolios |
integer | Optional, defaults to 25 The number of portfolios to compute on the mean-variance minimum variance frontier |
constraints |
object | Optional The constraints on the portfolio and on the assets |
constraints.minimumAssetsWeights |
number[] | Optional, defaults minimumAssetsWeights[i] = 0, i=0..assets-1 Array containing assets numbers, corresponding to the minimum weights constraints and satisfying 0 <= minimumAssetsWeights[i] <= 1, i=0..assets-1 |
constraints.maximumAssetsWeights |
number[] | Optional, defaults maximumAssetsWeights[i] = 1, i=0..assets-1 Array containing assets numbers, corresponding to the maximum weights constraints and satisfying 0 <= maximumAssetsWeights[i] <= 1 and minimumAssetsWeights[i] <= maximumAssetsWeights[i], i=0..assets-1 |
constraints.minimumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the minimum portfolio exposure, in percentage, with 0 <= minimumPortfolioExposure <= 1 |
constraints.maximumPortfolioExposure |
number | Optional, defaults to 1 Corresponds to the maximum portfolio exposure, in percentage, with 0 <= maximumPortfolioExposure <= 1 and minimumPortfolioExposure <= maximumPortfolioExposure |
HTTP Response
Success 200
Field | Type | Description |
---|---|---|
minimumVarianceFrontierPortfolios |
object[] | Array containing portfolios objects, with minimumVarianceFrontierPortfolios[i] corresponding to a portfolio on the mean-variance minimum variance frontier, i=0..portfolios-1 |
minimumVarianceFrontierPortfolios[i].assetsWeights |
number[] | Array containing assets numbers, with minimumVarianceFrontierPortfolios[i].assetsWeights[j] corresponding to the weight of the asset j+1 in the i-th portfolio, in percentage, j=0..assets-1 |
minimumVarianceFrontierPortfolios[i].portfolioReturn |
number | The return of the i-th portfolio |
minimumVarianceFrontierPortfolios[i].portfolioVolatility |
number | The volatility of the i-th portfolio |
Errors
Refer to the API response codes section.
References
Harry M. Markowitz, Portfolio Selection, Efficient Diversification of Investments, Second edition, Blackwell Publishers Inc.
Support
If you encounter any issues with the API, or if you have any questions, feel free to contact me.