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:

• 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

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.

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

Assets Covariance

Covariance Matrix (from returns)

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

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

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

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

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

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

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

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

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 Construction

Investable Portfolio

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

• The desired portfolio assets weights
• The portfolio monetary value
• The portfolio assets prices
• The possibility, for some of the portfolio assets, to buy fractional shares
• The obligation, for some of the portfolio assets, to buy round lots of shares

HTTP Request

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

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]],
        "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

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

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.