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

Pinger

Ping

Allows to determine the status of the API.

HTTP Request

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

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

Logarithmic Returns

Computes the logarithmic returns of assets.

HTTP Request

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

Average Returns

Computes the average returns of assets.

HTTP Request

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

Correlation Matrix Validation

Validates whether a matrix is a correlation matrix.

HTTP Request

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

References

Nicholas J. Higham, Computing the Nearest Correlation Matrix—A Problem from Finance, IMA J. Numer. Anal. 22, 329–343, 2002.

Assets Covariance

Covariance Matrix (from returns)

Computes the covariance matrix of assets from their returns.

HTTP Request

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

Sample Covariance Matrix (from returns)

Computes the sample covariance matrix of assets returns.

HTTP Request

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

Covariance Matrix Validation

Validates whether a matrix is a covariance matrix.

HTTP Request

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

Assets Variances

Variances (from returns)

Computes the variances of assets from their returns.

HTTP Request

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

Variances (from covariance matrix)

Computes the variances of assets from their covariance matrix.

HTTP Request

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

Sample variances (from returns)

Computes the sample variances of assets from their returns.

HTTP Request

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

Constant Rebalancing Portfolio Values

Computes one or several multi-period portfolio(s) values, the portfolio(s) being rebalanced toward constant portfolio weights at each time period.

HTTP Request

The following command computes 3 constantly rebalanced portfolios, each made of 3 assets:

curl "https://api.portfoliooptimizer.io/v1/portfolio/generation/multi-period/constant-rebalancing"  \
  -H "Content-Type: application/json" \
  -d '{ "assets": 3, 
        "assetsPrices": [[100, 105, 110], [15, 12.5, 11.25], [0.5, 0.51, 0.49]],
        "assetsWeights": [[0.5,0.5,0], [0,0.5,0.5], [0.5,0,0.5]]    }'

It returns the following JSON:

{
  "portfolios": [{
      "portfolioValues": [100,94.16666666666667,91.70039682539684]
    },
    {
      "portfolioValues": [100,92.66666666666667,86.21633986928106]
    },
    {
      "portfolioValues": [100,103.5,103.93487394957984]
    }]
}

Headers

Refer to the API headers section.

Query Parameters

N/A

Body Parameters

HTTP Response

Success 200

Errors

Refer to the API response codes section.

No Rebalancing Portfolio Values (Buy and Hold Portfolio Values)

Computes one or several multi-period portfolio(s) values, the portfolio(s) never being rebalanced.

HTTP Request

The following command computes 3 buy and hold portfolios, each made of 3 assets with only one asset invested:

curl "https://api.portfoliooptimizer.io/v1/portfolio/generation/multi-period/no-rebalancing"  \
  -H "Content-Type: application/json" \
  -d '{ "assets": 3, 
        "assetsPrices": [[100, 105, 110], [15, 12.5, 11.25], [0.5, 0.51, 0.49]],
        "assetsInitialWeights": [[1,0,0], [0,1,0], [0,0,1]] }'

It returns the following JSON:

{
  "portfolios": [{ 
                  "portfolioValues": [100,105,110] 
                 },
                 { 
                  "portfolioValues": [100, 83.33333333333334,75] 
                 },
                 { 
                  "portfolioValues": [100,102,98] 
                 }]
}

Headers

Refer to the API headers section.

Query Parameters

N/A

Body Parameters

HTTP Response

Success 200

Errors

Refer to the API response codes section.

Random Rebalancing Portfolio Values

Computes one or several multi-period portfolio(s) values, the portfolio(s) being rebalanced toward random portfolio weights at each time period.

HTTP Request

The following command computes 2 randomly rebalanced 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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

References

Scientific Beta Maximum Decorrelation Indices

Maximum Return Portfolio

Computes the weights of the assets composing the maximum return portfolio, optionally subject to:

• Minimum and maximum weights constraints
• Minimum and maximum portfolio exposure constraints

HTTP Request

The following command computes the portfolio weights for $n=2$ assets, with returns $\mu_1 = 2$%, $\mu_2 = 1$%, with 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/maximum-return"  \
  -H "Content-Type: application/json" \
  -d '{ "assets": 2,
        "assetsReturns": [0.02, 0.01],
        "constraints": {"maximumAssetsWeights": [0.4, 1] }}'

It returns the following JSON, which corresponds to $w_1 = 40$% and $w_2 = 60$%:

{
  "assetsWeights":[0.4,0.6]
}

Headers

Refer to the API headers section.

Query Parameters

N/A

Body Parameters

HTTP Response

Success 200

Errors

Refer to the API response codes section.

References

Harry M. Markowitz, Portfolio Selection, Efficient Diversification of Investments, Second edition, Blackwell Publishers Inc.

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

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

References

John Lintner, The Valuation of Risk Assets and the Selection of Risky Investments in Stock Portfolios and Capital Budgets, The Review of Economics and Statistics Vol. 47, No. 1 (Feb., 1965), pp. 13-37

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

References

Yves Choueifaty and Yves Coignard, Toward Maximum Diversification, The Journal of Portfolio Management Fall 2008, 35 (1) 40-51

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 desired portfolio monetary value
• The portfolio assets prices
• The possibility to buy fractional shares for some portfolio assets
• The requirement to buy shares by round lots for some portfolio assets, with a possible minimum quantity of such lots
• The requirement to invest a minimum monetary amount for some portfolio assets

HTTP Request

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

Errors

Refer to the API response codes section.

References

T. Roncalli, G. Weisang, Risk parity portfolios with risk factors, Quantitative Finance, Volume 16, 2016

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

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

HTTP Response

Success 200

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

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

HTTP Response

Success 200

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.