Portfolio Optimisation API
The Portfolio Optimisation model can be accessed via an API to integrate the capabilities in external systems.
Basic Portfolio Construction Endpoint
To generate portfolio compositions from scratch use the following POST request endpoint:
https://87iyxbm0e1.execute-api.eu-west-2.amazonaws.com/Prod/generate/portfolio
Request Body
The request body has 5 top level attributes
Table 1: Request Top level attributes
| Attribute Key | Attribute Value TYPE and description |
| risk_appetite |
NUMBER value between 0 and 1 to reflect the amount of risk allowed in the portfolio. 0 is no risk, 1 is maximum risk |
| capital |
NUMBER Available capital to purchase assets. Can be excluded but not advised. |
| segment_weights |
OBJECT how the optimisation should consider the diversification preferences. This is a complex structure, see Segment Weights section below |
| max_allocation |
NUMBER The maximum percent any 1 security may take up of the portfolio. i.e. 0.3 means no single stock will be more than 30% of the portfolio |
| key | STRING The access key to the service |
Segment Weights
Segments weights is a deeply nested map/dictionary object.
The object key is segment_weights, as mentioned in Table 1.
The next level down is the Asset Class level, also known as the security type. This defines the type of security its child objects are. For example stocks, bonds or ETFs.
The level below asset class level is the Asset Industry level. This will be the type of business sector the asset belongs. For example Industrial, Technology or Healthcare.
The available industries are:
Technology Industrial Healthcare Utilities Transport Finance Automotive Consumer Entertainment
Finally, the level below the asset industry level is the Region level. This can define the types of regions the portfolio can search for assets in. For example, USA, UK, India.
The value assigned to the region key is the maximum amount allowed from that Asset Class, in that Industry, in that Region. This value should be between 0 and 1. Where the sum of the values is not equal to more than 1.
The structure looks like the following:
"segment_weights": {
"asset_class": {
"asset_industry": {
"region": max allocation for this definition
}
}
}
In a real request this may look like
"segment_weights": {
"stocks": {
"Industrial": {
"usa": 0.5
}
}
}
}
An example request body:
{
"risk_appetite": 0,
"capital": 1000,
"segment_weights": {
"stocks": {
"Industrial": {
"usa": 0.5
},
"Technology":{
"usa": 0.5
}
}
},
"max_allocation": 0.25,
"key": "AAAAAAAA11111111"
}
Response Body
The response body has 8 top level attributes
Table 2: Response Top level attributes
| Attribute Key | Attribute Value TYPE and description |
| status |
STRING A status state |
| message |
STRING A message from the API regarding the results |
| allocations |
[ Allocations Response Object ] An object with a similar structure to the requested segment weights. Detailing the recommended portfolio allocations |
| sharpe |
NUMBER The Sharpe Ratio for the recommend portfolio |
| expectedAnalystReturn |
NUMBER The expected return of the portfolio, based on the analyst estimates |
| xai |
KEY: VALUE The XAI response detailing the explanation of the portfolio. Key: Value pair is the feature: output. For example "Value at Risk": " is medium" |
| xaiColour | KEY:VALUE The recommended UX colouring for the XAI response as the colour may differ for different risk appetites |
| xaiDetails | KEY: VALUE A descriptive sentence to help give insight into the xai response |
| remainingCapital |
NUMBER the remaining capital after the proposed asset purchases |
| currentAssetValue |
NUMBER Sum of the assets values at time of API call |
| expectedAssetValue | NUMBER Sum of the expected asset value based on the 12 month analyst price targets (i.e. what the portfolio will be worth in 12 months) |
| expectedBenchmarkValue | NUMBER The value of the portfolio if it grows at the same rate as the benchmark |
| risks |
KEY: VALUE The 3 risk measures of the portfolio. avgLoss is Average Loss, var is Value At Risk or VAR, volatility is the current volatility |
The Allocations Response Object is set up very similarly to the Segment Weights.
Asset Type
Asset Industry
Region
Asset ISIN : Asset Response Object
Each allocation will have an Asset Response Object, which has 9 attributes.
Table 3: Asset Response Object attribute
| Attribute Key | Attribute Value TYPE and description |
| name |
STRING Regular name of the asset i.e. Walt Disney Company |
| ticker |
STRING The Stock ticker associated with the asset. i.e. DIS |
| allocation |
NUMBER The percent of the portfolio to be made up of this asset. 0.2 means 20% of the portfolio should be this asset |
| xai |
KEY:VALUE The XAI response detailing the explanation of the portfolio. Key: Value pair is the feature: output. For example "Value at Risk": " is medium" |
| xaiColour | KEY:VALUE The recommended UX colouring for the XAI response as the colour may differ for different risk appetites |
| xaiDetails | KEY:VALUE A descriptive sentence to help give insight into the xai response |
| currentPrice |
NUMBER The latest closing price on record |
| expectedAnalystPrice |
NUMBER The weighted average of the price targets from analysts covering the security. |
| expectedAnalystReturn |
NUMBER The potential return of current price / expectedAnalystPrice, 0.45 means a 45% return over the next 1 year. |
| potentialLosses |
NUMBER The value at risk and potential loss in value of the portfolio |
| expectedVolatility |
NUMBER The volatility metric of the asset |
An Example Response Body
{
"headers": {},
"body": {
"status": "Success",
"message": "Portfolio Complete",
"allocations": {
"Stocks": {
"Entertainment": {
"usa": {
"US2546871060": {
"name": "Walt Disney Company",
"ticker": "DIS",
"allocation": 0.23,
"xai": {
"Value at Risk": " is medium",
"Analyst Expected Return": " is low and medium",
"Volatility": " is medium",
"Risk Appetite": " is low",
"Expected Avg Loss": " is high and medium"
},
"xaiColour": {
"Value at Risk": 2.0,
"Analyst Expected Return": 1.0,
"Volatility": 2.0,
"Risk Appetite": 1.0,
"Expected Avg Loss": 3.0,
"Suitability To You": 1.0
},
"xaiDetails": {
"Value at Risk": "You should be able to withstand a loss of up to $11.61 per share",
"Analyst Expected Return": "Analysts expect the price to FALL by 0.0% to $92.69",
"Volatility": "The expected volatility of this asset is 9.8% fluctuation between $83.95 and $102.19 are expected",
"Risk Appetite": "No insight",
"Expected Avg Loss": "You should expect average loss to be -0.34",
"Suitability To You": "Your profile is set to be CAUTIOUS. This asset is expected to give SLOW and STEADY returns. You also have interest in this industry (Entertainment)."
},
"currentPrice": 98.87,
"expectedAnalystPrice": 144.22,
"expectedAnalystReturn": 0.45,
"potentialLosses": 0.010904000140726566,
"expectedVolatility": 0.1660899966955185
}
}
},
"Technology": {
"usa": {
"US38259P5089": {
"name": "Alphabet Inc",
"ticker": "GOOG",
"allocation": 0.39,
"xai": {
"Value at Risk": " is high and medium",
"Analyst Expected Return": " medium",
"Volatility": " is high",
"Risk Appetite": " is low",
"Expected Avg Loss": " is low"
},
"xaiColour": {
"Value at Risk": 2.0,
"Analyst Expected Return": 1.0,
"Volatility": 2.0,
"Risk Appetite": 1.0,
"Expected Avg Loss": 3.0,
"Suitability To You": 1.0
},
"xaiDetails": {
"Value at Risk": "You should be able to withstand a loss of up to $11.61 per share",
"Analyst Expected Return": "Analysts expect the price to FALL by 0.0% to $92.69",
"Volatility": "The expected volatility of this asset is 9.8% fluctuation between $83.95 and $102.19 are expected",
"Risk Appetite": "No insight",
"Expected Avg Loss": "You should expect average loss to be -0.34",
"Suitability To You": "Your profile is set to be CAUTIOUS. This asset is expected to give SLOW and STEADY returns. You also have interest in this industry (Technology)."
},
"currentPrice": 97.59,
"expectedAnalystPrice": 140.49,
"expectedAnalystReturn": 0.43,
"potentialLosses": 0.0,
"expectedVolatility": 0.0
}
}
},
"Transport": {
"usa": {
"US2473617023": {
"name": "Delta Airlines Inc",
"ticker": "DAL",
"allocation": 0.06,
"xai": {
"Value at Risk": " is medium",
"Analyst Expected Return": " is low and medium",
"Volatility": " is medium",
"Risk Appetite": " is low",
"Expected Avg Loss": " is high and medium"
},
"currentPrice": 35.09,
"expectedAnalystPrice": 48.03,
"expectedAnalystReturn": 0.36,
"potentialLosses": 5.329999839887023E-4,
"expectedVolatility": 0.13045600056648254
},
"US90353T1007": {
"name": "Uber Technologies Inc",
"ticker": "UBER",
"allocation": 0.28,
"xai": {
"Value at Risk": " is high and medium",
"Analyst Expected Return": " medium",
"Volatility": " is high",
"Risk Appetite": " is low",
"Expected Avg Loss": " is low"
},
"xaiColour": {
"Value at Risk": 2.0,
"Analyst Expected Return": 1.0,
"Volatility": 2.0,
"Risk Appetite": 1.0,
"Expected Avg Loss": 3.0,
"Suitability To You": 1.0
},
"xaiDetails": {
"Value at Risk": "You should be able to withstand a loss of up to $11.61 per share",
"Analyst Expected Return": "Analysts expect the price to FALL by 0.0% to $92.69",
"Volatility": "The expected volatility of this asset is 9.8% fluctuation between $83.95 and $102.19 are expected",
"Risk Appetite": "No insight",
"Expected Avg Loss": "You should expect average loss to be -0.34",
"Suitability To You": "Your profile is set to be CAUTIOUS. This asset is expected to give SLOW and STEADY returns. You also have interest in this industry (Transport)."
},
"currentPrice": 28.5,
"expectedAnalystPrice": 47.1,
"expectedAnalystReturn": 0.65,
"potentialLosses": 0.005698999855667353,
"expectedVolatility": 0.2289460003376007
}
}
}
}
},
"sharpe": -0.10966719182564104,
"expectedAnalystReturn": 50.19,
"xai": {
"Value at Risk": " is medium",
"Analyst Expected Return": " is low and medium",
"Volatility": " is medium",
"Risk Appetite": " is low",
"Expected Avg Loss": " is high and medium"
},
"xaiColour": {
"Value at Risk": 1.0,
"Analyst Expected Return": 1.0,
"Volatility": 1.0,
"Risk Appetite": 1.0,
"Expected Avg Loss": 2.0,
"Suitability To You": 1.0
},
"xaiDetails": {
"Value at Risk": "You should be able to withstand a loss of up to $135.95",
"Analyst Expected Return": "Analysts expect the portfolio prices to RISE by 11.28%, so the portfolio's expected future value is $1069.07",
"Volatility": "The expected volatility of this asset is 11.78% fluctuation between $847.53 and $1073.87 are expected",
"Risk Appetite": "No insight",
"Expected Avg Loss": "You should expect average loss to be -0.17",
"Suitability To You": "Your profile is set to be CAUTIOUS. This portfolio is expected to give HIGH GROWTH returns. You also have HIGH interest in the selected industries."
},
"remainingCapital": 32.5,
"currentAssetValue": 967.4999923706055,
"expectedAssetValue": 1077.020991506958,
"risks": {
"avgLoss": -0.0022350099799223243,
"var": 0.1399750201404095,
"volatility": 0.1151988697052002
},
"expectedBenchmarkValue": 1064.249991607666
},
"statusCode": "OK",
"statusCodeValue": 200
}
Rebalance Portfolio Endpoint
To rebalance an existing portfolio POST request endpoint:
https://87iyxbm0e1.execute-api.eu-west-2.amazonaws.com/Prod/generate/portfolio/rebalance
Request Body
The request body has 7 top level attributes, 5 from Table 1 plus 2 additional tax_rate and current_portfolio
Table 2: Rebalance Request Top level attributes
| Attribute Key | Attribute Value TYPE and description |
| risk_appetite | NUMBER value between 0 and 1 to reflect the amount of risk allowed in the portfolio. 0 is no risk, 1 is maximum risk |
| capital | NUMBER Available capital to purchase assets. Can be excluded but not advised. |
| tax_rate | NUMBER value between 0 and 1 to reflect the expected capital gains tax rate for profits on share sales. |
| segment_weights | OBJECT how the optimisation should consider the diversification preferences. This is a complex structure, see Segment Weights section above |
| current_portfolio |
OBJECT List of existing assets, the count and the cost. The IDs should ideally be the ISIN number of the asset. Though Stock Tickers will work. See Current Portfolio section below |
| max_allocation | NUMBER The maximum percent any 1 security may take up of the portfolio. i.e. 0.3 means no single stock will be more than 30% of the portfolio |
| key | STRING The access key to the service |
Current Portfolio
The structure looks like the following:
"current_portfolio": {
"isin": {
"share_count": 0,
"cost": 0
}
}
In a real request this may look like
"current_portfolio": {
"US38259P5089": {
"share_count": 3,
"cost": 90
},
"US2473617023": {
"share_count": 4,
"cost": 30
},
"US90353T1007": {
"share_count": 5,
"cost": 35
}
}
An example request body:
{
"risk_appetite": 1,
"capital": 1000,
"tax_rate": 0.3,
"segment_weights": {
"stocks": {
"Consumer": {
"usa": 0.5
},
"Technology": {
"usa": 0.5
}
}
},
"current_portfolio": {
"US38259P5089": {
"share_count": 3,
"cost": 90
},
"US2473617023": {
"share_count": 4,
"cost": 30
},
"US90353T1007": {
"share_count": 5,
"cost": 35
}
},
"max_allocation": 0.5,
"key": "AAAAAAAA11111111"
}
Response Body
The response body has 9 top level attributes, the same as the response from the Basic Portfolio Construction Endpoint. Plus the rebalance impact
Table 4: Rebalance Response Top level attributes
| Attribute Key | Attribute Value TYPE and description |
| status | STRING A status state |
| message | STRING A message from the API regarding the results |
| allocations | [ Allocations Response Object ] An object with a similar structure to the requested segment weights. Detailing the recommended portfolio allocations. See above |
| sharpe | NUMBER The Sharpe Ratio for the recommend portfolio |
| expectedAnalystReturn | NUMBER The expected return of the portfolio, based on the analyst estimates |
| xai | KEY: VALUE The XAI response detailing the explanation of the portfolio. Key: Value pair is the feature: output. For example "Value at Risk": " is medium" |
| xaiColour | KEY:VALUE The recommended UX colouring for the XAI response as the colour may differ for different risk appetites |
| xaiDetails | KEY:VALUE A descriptive sentence to help give insight into the xai response |
| remainingCapital | NUMBER the remaining capital after the proposed asset purchases |
| currentAssetValue |
NUMBER Sum of the assets values at time of API call |
| previousAssetValue |
NUMBER Sum of the previous assets values, before the rebalance, at time of API call |
| expectedAssetValue |
NUMBER Sum of the expected asset value based on the 12 month analyst price targets (i.e. what the portfolio will be worth in 12 months) |
| previousExpectedAssetValue |
NUMBER Sum of the expected asset prior to the rebalance (i.e. what the portfolio would have been worth in 12 months if no rebalance had happened) |
| expectedBenchmarkValue | NUMBER The value of the portfolio if it grows at the same rate as the benchmark |
| risks | KEY: VALUE The 3 risk measures of the portfolio. avgLoss is Average Loss, var is Value At Risk or VAR, volatility is the current volatility |
| rebalanceImpact |
OBJECT detailed object containing all the attributes related to the impact of the rebalance See table 5 for more |
Table 5: Rebalance Impact Response attributes
| Attribute Key | Attribute Value TYPE and description |
| gains |
NUMBER The value of the gains from sale of assets |
| losses |
NUMBER The value of the losses from the sale of assets |
| reinvested |
NUMBER The value of the profits that should be reinvested |
| sell |
KEY:VALUE The assets that should be sold to construct the new portfolio |
| buy |
KEY:VALUE The assets that should be bought to construct the new portfolio |
| pretaxProfit |
NUMBER The profit from the sale of assets |
| taxRate |
NUMBER The tax rate to be applied to profits |
| taxOwed |
NUMBER The tax owed on the profits from the sale of assets |
| reinvestmentRate |
NUMBER the rate at which profits should be reinvested |
| profitsTaken |
NUMBER The value of the profits to be withdrawn |
| riskReturnChanges |
KEY:VALUE Details of the changes in key attributes of the portfolio |
An Example Response Body
{
"headers": {},
"body": {
"status": "Success",
"message": "Portfolio Complete",
"allocations": {
"Stocks": {
"Consumer": {
"usa": {
"US1912161007": {
"name": "Coca-Cola Company",
"ticker": "KO",
"allocation": 0.2,
"xai": {
"Value at Risk": " is medium",
"Analyst Expected Return": " is low and medium",
"Volatility": " is medium",
"Risk Appetite": " is high",
"Expected Avg Loss": " is high and medium"
},
"xaiColour": {
"Value at Risk": 2.0,
"Analyst Expected Return": 1.0,
"Volatility": 2.0,
"Risk Appetite": 1.0,
"Expected Avg Loss": 3.0,
"Suitability To You": 1.0
},
"shareCount": 5.0,
"currentPrice": 62.7,
"expectedAnalystPrice": 67.57,
"expectedAnalystReturn": 0.08,
"potentialLosses": -0.0016659999964758754,
"expectedVolatility": 0.06466200202703476
},
"US0231351067": {
"name": "Amazon Inc",
"ticker": "AMZN",
"allocation": 0.3,
"xai": {
"Value at Risk": " is medium",
"Analyst Expected Return": " is low and medium",
"Volatility": " is medium",
"Risk Appetite": " is high",
"Expected Avg Loss": " is high and medium"
},
"xaiColour": {
"Value at Risk": 2.0,
"Analyst Expected Return": 1.0,
"Volatility": 2.0,
"Risk Appetite": 1.0,
"Expected Avg Loss": 3.0,
"Suitability To You": 1.0
},
"shareCount": 5.0,
"currentPrice": 92.42,
"expectedAnalystPrice": 140.92,
"expectedAnalystReturn": 0.52,
"potentialLosses": 0.006237000226974487,
"expectedVolatility": 0.1776459962129593
}
}
},
"Technology": {
"usa": {
"US67066G1040": {
"name": "NVIDIA Corporation",
"ticker": "NVDA",
"allocation": 0.2,
"xai": {
"Value at Risk": " is high and medium",
"Analyst Expected Return": " medium",
"Volatility": " is high",
"Risk Appetite": " is high",
"Expected Avg Loss": " is low"
},
"xaiColour": {
"Value at Risk": 2.0,
"Analyst Expected Return": 1.0,
"Volatility": 2.0,
"Risk Appetite": 1.0,
"Expected Avg Loss": 3.0,
"Suitability To You": 1.0
},
"shareCount": 2.0,
"currentPrice": 156.39,
"expectedAnalystPrice": 197.36,
"expectedAnalystReturn": 0.26,
"potentialLosses": -0.010495999827980995,
"expectedVolatility": 0.21685199439525604
},
"US38259P5089": {
"name": "Alphabet Inc",
"ticker": "GOOG",
"allocation": 0.3,
"xai": {
"Value at Risk": " is medium",
"Analyst Expected Return": " is low and medium",
"Volatility": " is medium",
"Risk Appetite": " is high",
"Expected Avg Loss": " is high and medium"
},
"xaiColour": {
"Value at Risk": 2.0,
"Analyst Expected Return": 1.0,
"Volatility": 2.0,
"Risk Appetite": 1.0,
"Expected Avg Loss": 3.0,
"Suitability To You": 1.0
},
"shareCount": 5.0,
"currentPrice": 95.44,
"expectedAnalystPrice": 140.49,
"expectedAnalystReturn": 0.47,
"potentialLosses": 0.0,
"expectedVolatility": 0.0
}
}
}
}
},
"risks": {
"avgLoss": -8.451500325463712E-4,
"var": 0.18811587750911712,
"volatility": 0.1577939609438181
},
"sharpe": -0.022216650772190805,
"expectedAnalystReturn": 16.31,
"xai": {
"Value at Risk": " is medium",
"Analyst Expected Return": " is high",
"Volatility": " is medium",
"Risk Appetite": " is low and medium",
"Expected Avg Loss": " is high and medium",
"Suitability To You": " is okay"
},
"xaiColour": {
"Value at Risk": 2.0,
"Analyst Expected Return": 1.0,
"Volatility": 2.0,
"Risk Appetite": 1.0,
"Expected Avg Loss": 3.0,
"Suitability To You": 1.0
},
"xaiDetails": {
"Value at Risk": "You should be able to withstand a loss of up to $175.53",
"Analyst Expected Return": "Analysts expect the portfolio prices to RISE by 16.31%, so the portfolio's expected future value is $1085.3",
"Volatility": "The expected volatility of this asset is 15.78% fluctuation between $785.87 and $1080.35 are expected",
"Risk Appetite": "No insight",
"Expected Avg Loss": "You should expect average loss to be -0.08",
"Suitability To You": "Your profile is set to be CAUTIOUS. This portfolio is expected to give HIGH GROWTH returns. You also have HIGH interest in the selected industries."
},
"remainingCapital": 34.39,
"currentAssetValue": 933.1099815368652,
"previousAssetValue": 967.4999923706055,
"expectedAssetValue": 1085.300219525528,
"previousExpectedAssetValue": 1077.4079915039063,
"rebalanceImpact": {
"gains": 103.37999725341797,
"losses": -7.049999237060547,
"reinvested": 19.32524938583374,
"sell": {
"US5949181045": 1.0,
"US9497461015": 1.0,
"US0378331005": 1.0,
"US4581401001": 3.0
},
"buy": {
"US30303M1027": 2.0,
"US0605051046": 1.0,
"US0079031078": 3.0
},
"pretaxProfit": 110.42999649047852,
"taxRate": 0.3,
"taxOwed": 33.12899894714355,
"reinvestmentRate": 0.25,
"profitsTaken": 57.975748157501215,
"riskReturnChanges": {
"Expected Value at Risk Change": "0.1404 → 0.1881",
"Expected Volatility Change": "0.1155 → 0.1577",
"Expected Loss Change": "-0.0022 → -8.0E-4",
"Expected Return Change": "11.36 → 16.31"
}
},
"expectedBenchmarkValue": 1026.4209796905518
},
"statusCode": "OK",
"statusCodeValue": 200
}
XAI Colour Details
1 should be Green or a positive colour
2 should be Orange/Amber or a neutral colour
3 should be Red or a negative colour