NAV
shell

Introduction

Portfolio Optimizer is at heart an 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:

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:

The API also optionally requires the following HTTP header to be provided with all the API requests:

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:

Contributor usage

Higher limits are available in authenticated mode, and they require contributing to the API running costs:

Specific usage

For specific usages, higher limits are available in authenticated mode, but please first 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 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?

Assets Covariance

Covariance Matrix (from returns)

Computes the covariance matrix of assets 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.

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 (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 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.

Portfolio Generation

Random Portfolio Weights

Computes one or several random portfolio(s) weights, optionally subject to:

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 at every time period toward random portfolio weights.

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 Risk Contributions Portfolio

Computes the weights of the assets composing an equal risk contributions portfolio, optionally subject to:

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.5999975015091795]
}

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

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:

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 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
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:

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 equal to $\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%, 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.

Portfolio Construction

Investable Portfolio

Computes an investable portfolio as close as possible to a desired portfolio, taking into account:

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]
}

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, in percentage, i=0..assets-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..portfolios-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]],
        "portfoliosAssetsWeights": [[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 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
portfoliosAssetsWeights number[] [] Array of arrays, with portfoliosAssetsWeights[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 portfoliosAssetsWeights.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 portfoliosAssetsWeights.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

Mean-Variance Efficient Frontier

Computes the (discretized) mean-variance efficient frontier associated to a list of assets, optionally subject to:

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:

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 arrays, with assetsReturns[i] corresponding to the returns of the 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.