Portfolio Optimization

Preview

Portfolio Optimization

+ Day(s) remaining in the trial

Overview

The Portfolio Optimization Service is built upon a flexible mathematical model. This model allows for the construction or rebalancing of an investment portfolio based on a wide range of objectives and investor preferences. For example, the investor might want to avoid sin stocks, focus on socially responsible investments, or limit contribution to asset classes while minimizing the overall volatility with respect to a benchmark.

Getting started

Where do I find a list of assets?

For a list of the sample assets available for use with the Portfolio Optimization Service, see the [Portfolio Optimization Service Sample Data Set](http://public.dhe.ibm.com/software/analytics/solutions/en/fintech/portfolio_optimization_service_sample_dataset.xlsx) spreadsheet.

Security

Keys

Pick a key to use with this API. Make sure you are logged in with your IBM id for your keys to be populated in the dropdown below. By selecting a key, it will be pre-filled for each endpoint in the Documentation section that can be used with the built-in testing. If you want to change which key to use for a particular endpoint, you can do so at the endpoint in the Documentation section.
You can manage your API keys in the <MyAPIs> section. API keys authenticate you to your subscription, so make sure to keep them secret. Do not share the X-IBM-Client-Secret portion of any API key in publicly accessible places such as GitHub, or client-side code.



Manage your keys
 

Global Parameters

This section contains global variables, which apply to all of the endpoint definitions of this API. You can use this section to set these variables once, and have the values pre-filled for every endpoint in the Documentation section. The values set can be used with the built-in testing. You can always override the value in the endpoint definition of the Documentation section.
Global variables


Documentation

Portfolio Optimization:

Portfolio Optimization

Construct an optimal portfolio
This operation constructs a portfolio given certain constraints. Use this operation to construct a new portfolio from a defined universe of assets. You must specify an investable amount. The operation builds the optimal portfolio given a universe of assets, an objective, and constraints. This operation can be done on an absolute (no benchmark) or relative (against a benchmark) basis.

POST   /portfolio/construct

			https://{hostname}/api/v1/{tenantid}/portfolio/construct
		
Keys
Header parameters

X-IBM-Access-Token

STRING , required

API key obtained when you created the service

Global variables

hostname

BASEURL , required

tenantid

BASEURL , required

Request code
								
HttpResponse<String> response = Unirest.post("https://ibm.com/api/v1/optimization/portfolio/construct") .header("x-ibm-access-token", "string") .header("accept", "application/json") .header("content-type", "application/json") .body("{\"constraints\":[{\"CashAdjust\":0,\"InPortfolio\":\"string\",\"attribute\":\"string\",\"constant\":0,\"description\":\"string\",\"measure\":\"string\",\"members\":\"string\",\"portfolio\":\"string\",\"relation\":\"string\",\"timestep\":0}],\"objectives\":[{\"TargetPortfolio\":\"string\",\"attribute\":\"string\",\"description\":\"string\",\"measure\":\"string\",\"portfolio\":\"string\",\"sense\":\"string\",\"timestep\":0}],\"portfolios\":[{\"ParentPortfolio\":\"string\",\"holdings\":[{\"asset\":\"string\",\"quantity\":0}],\"name\":\"string\",\"type\":\"string\"}]}") .asString();
Request model

constraints

ARRAY , required

Specifies the relation to impose when optimizing the portfolio. For example, you can specify allocation relation for specific categories, directional trade relations, number of trades allowed and cash flow. For the construct endpoint, you must specify a constraint on the root portfolio that contains a positive value for CashAdjust. This value represents the amount to be invested into the new portfolio.

CashAdjust

DOUBLE , optional

The number of monetary units to flow into (positive value) or out of (negative value) the root portfolio.

InPortfolio

STRING , optional

The name of a portfolio that contains the assets of the portfolio specified by the portfolio parameter.

attribute

STRING , required

A numerical characteristic or property of an asset. Valid values include value, return, weight, and count.

constant

DOUBLE , optional

Can be a decimal number or an integer. When the attribute parameter is weight or return, constant is a decimal number which, when multiplied by 100, equals the percentage of the required weight or return. For example, 0.01 specifies a percentage of 1%. When the attribute parameter is count, constant is an integer representing a number of units. Use constant with the relation parameter to limit the attribute.

description

STRING , optional

Text that describes the constraint

measure

STRING , optional

A function of the attribute. The valid values are expectation, variance, and tracking error.

members

STRING , optional

The portfolio containing the assets that the measure is to be applied to.

portfolio

STRING , optional

The name of the portfolio.

relation

STRING , optional

A comparative operator. The valid values are greater-or-equal, less-or-equal, and equal.

timestep

DOUBLE , optional

Corresponds to a distinct point in time at which the problem is measured and computed. The value may be either 30 (in 30 days) or 0 (current time). If timestep is not specified, the default is 0.

objectives

ARRAY , required

Specifies the objectives to target for the optimization of the root portfolio. The objective includes the name of the root portfolio, the measure to use (variance, return, or tracking error), whether to minimize or maximize the measure, and whether this objective is to be met now or in 30 days.

TargetPortfolio

STRING , optional

The name of the portfolio to be compared to the root portfolio.

attribute

STRING , required

A numerical characteristic or property of an asset such as return.

description

STRING , optional

Text that describes the objective.

measure

STRING , required

A function of the attribute that can be maximized or minimized by the setting of the sense parameter. The valid values are expectation and variance.

portfolio

STRING , required

The name of the root portfolio.

sense

STRING , required

Either minimize or maximize the measure.

timestep

DOUBLE , required

Corresponds to a distinct point in time at which the problem is measured and computed. The value may be either 30 (in 30 days) or 0 (current time). If timestep is not specified, the default is 0.

portfolios

ARRAY , required

Each portfolio contains the portfolio name, type, and the assets. For each asset, specify the identifier and current quantity. You can specify three types of portfolios: You must specify a portfolio of type root that contains the full set of assets to optimize. For the construct problem, the asset quantities in the root portfolio are set to 0. You can specify a portfolio of type subportfolio that contains assets in the type root and grouped based on similar characteristics. For the construct problem, the asset quantities are set to 0. You can specify a portfolio of type benchmark that contains assets in a benchmark fund. For the construct problem, these assets have quantities and do not need to be part of the root type.

ParentPortfolio

STRING , optional

The name of the parent portfolio when the type is subportfolio.

holdings

ARRAY , required

An array of holdings for this portfolio.

asset

STRING , required

The ID of the asset. To choose a valid ID, see 'Where do I find a list of assets?' in the 'Getting started' section of this API Reference.

quantity

DOUBLE , required

The units held of the asset.

name

STRING , required

The name of the portfolio.

type

STRING , required

The type of portfolio. The type can be root, benchmark, or subportfolio.

Request example
{
  "constraints": [{
    "CashAdjust": double,
    "InPortfolio": string,
    "attribute": [value, return, weight, count],
    "constant": double,
    "description": string,
    "measure": [variance, expectation, tracking error],
    "members": string,
    "portfolio": string,
    "relation": [greater-or-equal, less-or-equal, equal],
    "timestep": double
  }],
  "objectives": [{
    "TargetPortfolio": string,
    "attribute": [return],
    "description": string,
    "measure": [variance, expectation],
    "portfolio": string,
    "sense": [minimize, maximize],
    "timestep": double
  }],
  "portfolios": [{
    "ParentPortfolio": string,
    "holdings": [{
    "asset": string,
    "quantity": double
  }],
    "name": string,
    "type": [root, subportfolio, benchmark]
  }]
}
Response model

200

OK

Body

holdings [SolutionHoldingsDef]

ARRAY , required

Contains the information about all trades that are performed on the holdings. For each holding, the asset, quantity, value, and quantity of the trade are specified.

metadata [SolutionMetadataDef]

ARRAY , required

Contains the status of the portfolio, the message, status code, the result of the objectives specified in the request, the ID of the transaction, and the start and end times of the request.

performance [SolutionPerformanceDef]

ARRAY , required

Specifies the algorithm used to perform the optimization, how many threads were used, and how long the processing took.

asset

STRING , required

The ID of the asset.

optimizedQuantity

DOUBLE , required

The optimal number of units to be held.

optimizedTrade

DOUBLE , required

The optimal number of units to trade.

quantity

DOUBLE , required

The units held currently.

message

STRING , required

Text that provides details about the status. The value is Optimal if the optimization was successful.

objectiveValue

DOUBLE , required

The result of the objectives measure parameter. For example, if the objective is to minimize the variance of a portfolio's return, then the value is the variance of the optimal portfolio.

status

STRING , required

The status of the request. The value is Optimal if the optimization was successful.

statusCode

DOUBLE , required

A number that corresponds to the status. The value is an error code if the optimization failed.

algorithm

STRING , required

The name of the algorithm used for optimizing the portfolio.

threads

DOUBLE , required

The number of threads used in the process of optimizing the portfolio.

time

DOUBLE , required

The time in seconds that the optimization process took.

400

Invalid input. The portfolio cannot be optimized.

Body

description

STRING , required

httpcode

DOUBLE , required

The HTTP return code.

requestendtimestamp

STRING , required

Nanosecond timestamp of when the request ended.

requeststarttimestamp

STRING , required

Nanosecond timestamp of when the request started.

transactionid

STRING , required

The unique that represents this request.

500

Error occurred in the optimizer.

Body

description

STRING , required

httpcode

DOUBLE , required

The HTTP return code.

requestendtimestamp

STRING , required

Nanosecond timestamp of when the request ended.

requeststarttimestamp

STRING , required

Nanosecond timestamp of when the request started.

transactionid

STRING , required

The unique that represents this request.

Response example

200

OK

								{
  "holdings" : [{
    "asset" : string,
    "optimizedQuantity" : double,
    "optimizedTrade" : double,
    "quantity" : double
  }],
  "metadata" : [{
    "message" : string,
    "objectiveValue" : double,
    "status" : string,
    "statusCode" : double
  }],
  "performance" : [{
    "algorithm" : string,
    "threads" : double,
    "time" : double
  }]
}
							

400

Invalid input. The portfolio cannot be optimized.

								{
  "description" : "This is an error message.",
  "httpcode" : 400.0,
  "requestendtimestamp" : "2017-08-04t17-25-23.717332797-pdt",
  "requeststarttimestamp" : "2017-08-04t17-25-23.652372109-pdt",
  "transactionid" : "b6b85242-797b-11e7-b5a5-be2e44b06b34"
}
							

500

Error occurred in the optimizer.

								{
  "description" : "This is an error message.",
  "httpcode" : 400.0,
  "requestendtimestamp" : "2017-08-04t17-25-23.717332797-pdt",
  "requeststarttimestamp" : "2017-08-04t17-25-23.652372109-pdt",
  "transactionid" : "b6b85242-797b-11e7-b5a5-be2e44b06b34"
}
							
Rebalance the given portfolio
This operation optimizes a portfolio. Use this operation to rebalance a portfolio based on an objective and constraints. The portfolio must be investable and contain assets with both values and quantities. This operation can be done on an absolute (no benchmark) or relative (against a benchmark) basis.

POST   /portfolio/rebalance

			https://{hostname}/api/v1/{tenantid}/portfolio/rebalance
		
Keys
Header parameters

X-IBM-Access-Token

STRING , required

API key obtained when you created the service

Global variables

hostname

BASEURL , required

tenantid

BASEURL , required

Request code
								
HttpResponse<String> response = Unirest.post("https://ibm.com/api/v1/optimization/portfolio/rebalance") .header("x-ibm-access-token", "string") .header("accept", "application/json") .header("content-type", "application/json") .body("{\"constraints\":[{\"CashAdjust\":0,\"InPortfolio\":\"string\",\"attribute\":\"string\",\"constant\":0,\"description\":\"string\",\"measure\":\"string\",\"members\":\"string\",\"portfolio\":\"string\",\"relation\":\"string\",\"timestep\":0}],\"objectives\":[{\"TargetPortfolio\":\"string\",\"attribute\":\"string\",\"description\":\"string\",\"measure\":\"string\",\"portfolio\":\"string\",\"sense\":\"string\",\"timestep\":0}],\"portfolios\":[{\"ParentPortfolio\":\"string\",\"holdings\":[{\"asset\":\"string\",\"quantity\":0}],\"name\":\"string\",\"type\":\"string\"}]}") .asString();
Request model

constraints

ARRAY , required

Specifies the relation to impose when optimizing the portfolio. For example, you can specify allocation relation for specific categories, directional trade relations, number of trades allowed and cash flow. For the construct endpoint, you must specify a constraint on the root portfolio that contains a positive value for CashAdjust. This value represents the amount to be invested into the new portfolio.

CashAdjust

DOUBLE , optional

The number of monetary units to flow into (positive value) or out of (negative value) the root portfolio.

InPortfolio

STRING , optional

The name of a portfolio that contains the assets of the portfolio specified by the portfolio parameter.

attribute

STRING , required

A numerical characteristic or property of an asset. Valid values include value, return, weight, and count.

constant

DOUBLE , optional

Can be a decimal number or an integer. When the attribute parameter is weight or return, constant is a decimal number which, when multiplied by 100, equals the percentage of the required weight or return. For example, 0.01 specifies a percentage of 1%. When the attribute parameter is count, constant is an integer representing a number of units. Use constant with the relation parameter to limit the attribute.

description

STRING , optional

Text that describes the constraint

measure

STRING , optional

A function of the attribute. The valid values are expectation, variance, and tracking error.

members

STRING , optional

The portfolio containing the assets that the measure is to be applied to.

portfolio

STRING , optional

The name of the portfolio.

relation

STRING , optional

A comparative operator. The valid values are greater-or-equal, less-or-equal, and equal.

timestep

DOUBLE , optional

Corresponds to a distinct point in time at which the problem is measured and computed. The value may be either 30 (in 30 days) or 0 (current time). If timestep is not specified, the default is 0.

objectives

ARRAY , required

Specifies the objectives to target for the optimization of the root portfolio. The objective includes the name of the root portfolio, the measure to use (variance, return, or tracking error), whether to minimize or maximize the measure, and whether this objective is to be met now or in 30 days.

TargetPortfolio

STRING , optional

The name of the portfolio to be compared to the root portfolio.

attribute

STRING , required

A numerical characteristic or property of an asset such as return.

description

STRING , optional

Text that describes the objective.

measure

STRING , required

A function of the attribute that can be maximized or minimized by the setting of the sense parameter. The valid values are expectation and variance.

portfolio

STRING , required

The name of the root portfolio.

sense

STRING , required

Either minimize or maximize the measure.

timestep

DOUBLE , required

Corresponds to a distinct point in time at which the problem is measured and computed. The value may be either 30 (in 30 days) or 0 (current time). If timestep is not specified, the default is 0.

portfolios

ARRAY , required

Each portfolio contains the portfolio name, type, and the assets. For each asset, specify the identifier and current quantity. You can specify three types of portfolios: You must specify a portfolio of type root that contains the full set of assets to optimize. For the construct problem, the asset quantities in the root portfolio are set to 0. You can specify a portfolio of type subportfolio that contains assets in the type root and grouped based on similar characteristics. For the construct problem, the asset quantities are set to 0. You can specify a portfolio of type benchmark that contains assets in a benchmark fund. For the construct problem, these assets have quantities and do not need to be part of the root type.

ParentPortfolio

STRING , optional

The name of the parent portfolio when the type is subportfolio.

holdings

ARRAY , required

An array of holdings for this portfolio.

asset

STRING , required

The ID of the asset. To choose a valid ID, see 'Where do I find a list of assets?' in the 'Getting started' section of this API Reference.

quantity

DOUBLE , required

The units held of the asset.

name

STRING , required

The name of the portfolio.

type

STRING , required

The type of portfolio. The type can be root, benchmark, or subportfolio.

Request example
{
  "constraints": [{
    "CashAdjust": double,
    "InPortfolio": string,
    "attribute": [value, return, weight, count],
    "constant": double,
    "description": string,
    "measure": [variance, expectation, tracking error],
    "members": string,
    "portfolio": string,
    "relation": [greater-or-equal, less-or-equal, equal],
    "timestep": double
  }],
  "objectives": [{
    "TargetPortfolio": string,
    "attribute": [return],
    "description": string,
    "measure": [variance, expectation],
    "portfolio": string,
    "sense": [minimize, maximize],
    "timestep": double
  }],
  "portfolios": [{
    "ParentPortfolio": string,
    "holdings": [{
    "asset": string,
    "quantity": double
  }],
    "name": string,
    "type": [root, subportfolio, benchmark]
  }]
}
Response model

200

OK

Body

holdings [SolutionHoldingsDef]

ARRAY , required

Contains the information about all trades that are performed on the holdings. For each holding, the asset, quantity, value, and quantity of the trade are specified.

metadata [SolutionMetadataDef]

ARRAY , required

Contains the status of the portfolio, the message, status code, the result of the objectives specified in the request, the ID of the transaction, and the start and end times of the request.

performance [SolutionPerformanceDef]

ARRAY , required

Specifies the algorithm used to perform the optimization, how many threads were used, and how long the processing took.

asset

STRING , required

The ID of the asset.

optimizedQuantity

DOUBLE , required

The optimal number of units to be held.

optimizedTrade

DOUBLE , required

The optimal number of units to trade.

quantity

DOUBLE , required

The units held currently.

message

STRING , required

Text that provides details about the status. The value is Optimal if the optimization was successful.

objectiveValue

DOUBLE , required

The result of the objectives measure parameter. For example, if the objective is to minimize the variance of a portfolio's return, then the value is the variance of the optimal portfolio.

status

STRING , required

The status of the request. The value is Optimal if the optimization was successful.

statusCode

DOUBLE , required

A number that corresponds to the status. The value is an error code if the optimization failed.

algorithm

STRING , required

The name of the algorithm used for optimizing the portfolio.

threads

DOUBLE , required

The number of threads used in the process of optimizing the portfolio.

time

DOUBLE , required

The time in seconds that the optimization process took.

400

Invalid input. The portfolio cannot be optimized.

Body

description

STRING , required

httpcode

DOUBLE , required

The HTTP return code.

requestendtimestamp

STRING , required

Nanosecond timestamp of when the request ended.

requeststarttimestamp

STRING , required

Nanosecond timestamp of when the request started.

transactionid

STRING , required

The unique that represents this request.

500

Error occurred in the optimizer.

Body

description

STRING , required

httpcode

DOUBLE , required

The HTTP return code.

requestendtimestamp

STRING , required

Nanosecond timestamp of when the request ended.

requeststarttimestamp

STRING , required

Nanosecond timestamp of when the request started.

transactionid

STRING , required

The unique that represents this request.

Response example

200

OK

								{
  "holdings" : [{
    "asset" : string,
    "optimizedQuantity" : double,
    "optimizedTrade" : double,
    "quantity" : double
  }],
  "metadata" : [{
    "message" : string,
    "objectiveValue" : double,
    "status" : string,
    "statusCode" : double
  }],
  "performance" : [{
    "algorithm" : string,
    "threads" : double,
    "time" : double
  }]
}
							

400

Invalid input. The portfolio cannot be optimized.

								{
  "description" : "This is an error message.",
  "httpcode" : 400.0,
  "requestendtimestamp" : "2017-08-04t17-25-23.717332797-pdt",
  "requeststarttimestamp" : "2017-08-04t17-25-23.652372109-pdt",
  "transactionid" : "b6b85242-797b-11e7-b5a5-be2e44b06b34"
}
							

500

Error occurred in the optimizer.

								{
  "description" : "This is an error message.",
  "httpcode" : 400.0,
  "requestendtimestamp" : "2017-08-04t17-25-23.717332797-pdt",
  "requeststarttimestamp" : "2017-08-04t17-25-23.652372109-pdt",
  "transactionid" : "b6b85242-797b-11e7-b5a5-be2e44b06b34"
}
							

Loading content...

Resources