Introduction
Sandbox Base URL
https://sandbox.hydrogenplatform.com/proton/v1
Production Base URL
https://api.hydrogenplatform.com/proton/v1
The Hydrogen Proton API is designed for added financial engineering functionality on top of the core Nucleus API within the Hydrogen Atom platform. Proton offers analytical tools, scoring, recommendations, and simulations to power investing, savings, insurance, and wellness products. This REST API provides functionality with relevance for direct-to-consumer, intermediary, and research-oriented lines of business, as well as for internal use within an organization.
Partners utilize the Hydrogen Proton API to achieve one or more of the following objectives:
1. Convert current financial engineering capabilities into a scalable, automated structure
2. Extend current financial engineering capabilities to be more robust or comprehensive
3. Create new financial engineering capabilities to power digital products where none currently exist
Authentication
API Authentication
After successful registration of your application, you will be provided a client_id
and client_secret
which will be used to identify your application when calling any Hydrogen API.
We require all API calls to be made over HTTPS connections.
OAuth2 Authorization
Example Request
curl -X POST https://api.hydrogenplatform.com/authorization/v1/oauth/token?grant_type=client_credentials \
-H "Authorization: Basic aHlkcm9nZW5faWQ6aHlkcm9nZW5fc2VjcmV0"
Example Response
{
"access_token": "ac6b8213-2a77-4ecc-89fd-68c9f2aff256",
"token_type": "bearer",
"expires_in": 86400,
"scope": "all",
"apps": "nucleus,proton,electron"
}
All subsequent API calls will then be made like the following example:
curl -X GET https://api.hydrogenplatform.com/proton/v1/risk_score \
-H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256"
Hydrogen uses OAuth 2.0 to facilitate authorization on the API, an industry standard framework for authorization. The client credentials flow is used by your application to obtain permission to act on its own behalf. A call will be made to our OAuth server to exchange your client_id
, client_secret
, and grant_type=client_credentials
for an access_token
, which can then be used to make calls to Hydrogen on behalf of the application.
REQUEST ARGUMENTS
Parameter | Type | Required | Description |
---|---|---|---|
client_id |
string | required | Application id for identification, which will be given to you when you are onboarded. |
client_secret |
string | required | Application secret, which will be given to you only once when you are onboarded. Please keep this in a safe place. |
grant_type |
string | required | Must be set to client_credentials . |
RESPONSE
Field | Description |
---|---|
access_token |
Token that will be used for all subsequent API calls. |
expires_in |
When the token expires in seconds and will need to be called again. Default is 86400 or 24 hours. |
token_type |
Always will be bearer . |
scope |
The scope your user has been granted in the application. |
Token Refresh
An access_token
will need to be refreshed to continue being authorized for the app. Access tokens are short lived: 24 hours. The Client Credentials grant type doesn’t return a refresh token. When your access_token
expires, the app has to simply request a new token which will invalidate the previous token.
Errors
ERROR CODES
Code | Description |
---|---|
400 |
Bad Request. |
401 |
Unauthorized. Occurs when you are using an invalid or expired access token. |
403 |
Forbidden. The request was valid but you are not authorized to access the resource. |
404 |
Not Found. Occurs when you are requesting a resource which doesn’t exist such as an incorrect URL or incorrect ID. |
429 |
Too Many Requests. Exceeded the rate limit set. Currently, there is no rate limit on the APIs. |
500 |
Internal Server Error. |
503 |
Service Unavailable. If the API is down for maintenance you will see this error. |
STATUS CODES
Code | Description |
---|---|
200 |
Ok. The request was successful. |
Versioning
The Proton API is currently in major version 1.0. All features which are not backwards compatible will be pushed as a major version release. Features that we consider to be backwards compatible include the following:
- Adding new API resources
- Adding new optional request parameters to existing API methods
- Adding new fields to existing API responses
- Changing the order of fields in existing API responses
- Changing the length or format of objects
Terminology
Throughout this documentation, there will be a number of financial terms and concepts that may be confusing to the developer not privy to financial jargon. After first outlining basic platform terms, we have defined some financial terms that may be referred to or represented in the parameters or their descriptions.
Nucleus Terms
Name | Description |
---|---|
Client | A client is identified based on a unique identifier, usually a government issued ID (e.g. social security number). A client can have multiple accounts, models, allocations and goals. |
Goal | A desired financial outcome in the future, defined by time and monetary value. |
Allocation | An abstract collection of one or more models grouped together and strategically weighted. Each account is assigned to one allocation, which can contain multiple models. |
Model | An abstract collection of one or more securities grouped together and strategically weighted. An account can be subscribed to n-number of models through an allocation. Each model holds n-number of securities and may be a component of n-number of allocations. |
Account | A client can have one or more accounts and each account can be assigned to one allocation. An account can hold n-number of portfolios. |
Portfolio | Portfolios are unique to a given account, while models have holdings with theoretical strategic weights; portfolios reflect actual account holdings, which depend on changes in the model, account additions and withdrawals, dividends, canceled trades, and other account-specific activity. Portfolios may or may not be subscribed to a model, which can be a component of an allocation. |
Security | A security is defined as any financial instrument or product that an investor may own. Securities have certain attributes, like prices and unique identifiers. Securities are held within models and portfolios. |
Asset Size | The aggregate monetary value of an investment account based on underlying positions. The asset size changes as securities fluctuate or monies/securities are deposited/withdrawn. |
Investing Terms
Name | Description |
---|---|
Accumulation | Accumulation goals are defined by a target amount of capital in the future, assumed to be redeemed in full upon termination of the goal horizon. |
Confidence Target | Confidence targets, indicated by conf_tgt when applicable, serve as the basis for a percentile analysis of Monte Carlo outcomes, in which outcomes below the ((1 – c)*100)th percentile, where c is the confidence target on a scale from 0 to 1, are excluded as a left-tail margin. If the confidence target is not satisfied, this is reflected by a goal probability that is less than the confidence target. |
Decumulation | Decumulation goals are defined by redeeming a target amount of capital periodically over a horizon, and may also include an accumulation phase. |
Drift-Based Rebalancing | Drift-based rebalancing generates a signal whenever a portfolio holding deviates from its strategic target by a predefined amount. |
Efficient Frontier | An efficient frontier is a collection of optimal portfolios across a maximal range of risk and return levels. |
Goal Horizon | The amount of time until the funds are needed for a given goal. A goal may have a decumulation horizon as well as an accumulation horizon. |
Monte Carlo | Using a random walk, this process estimates future values by simulating individual periods of portfolio growth based on samples derived from the given risk and return portfolio attributes, in conjunction with ongoing cash inflows or outflows (which occur at the end of each period) in the simulated account. |
Optimization | A programmatic mathematical process by which securities are weighted to optimally achieve an objective. |
Percentage | Throughout the API, percentages are represented in decimal format. For example, 0.02 translates to 2%. |
Rebalance | Execute trades in an account in order to move holdings in line with the model or allocation strategic weights. |
Tax (Principal and Non-Principal) | Principal_tax and nonprincipal_tax refer to an expected tax rate paid on the redemption of principal funds (e.g. contributed capital) and non-principal funds (e.g. gains/profits). |
Ticker | The unique identifier of a given security. Unlike a CUSIP, this is a string of letters usually five characters or less. |
Universe | The pool of securities that are acceptable to select for a given model, allocation or portfolio. |
Data Dependencies
Proton uses the following data from the Nucleus API:
- Securities
- Securities are defined with
POST /security
. Securities are required to have aticker
andasset_class
. - Security prices are defined with
POST /security_price
. Regardless of the date specified, a backtest will only go as far back as the most recent date where all securities included in the backtest have aprice
. - Parameters that require security information (for example, a security’s asset class) will match the entry exactly to the security information defined in
/security
.
- Securities are defined with
- Models
- Models are defined with
POST /model
. - Depending on the type of rebalancing or backtest utilized, the following parameters may be required:
downside
,tax_efficienty_id
,period_rebal
,rebalance_period
,drift_rebal
, anddefault_drift_factor
. - Model holdings are defined with
POST /model_holding
. Each holding is required to have asecurity_id
,date
,current_weight
, andstrategic_weight
. Depending on the type of rebalancing or backtest utilized, the following parameters may be required:drift_factor
,is_cash
,is_safe_security
.
- Models are defined with
- Allocations
- Allocations are defined with
POST /allocation
. - Allocations are required to have a
performance
andvolatility
for endpoints that assign a client to an allocation based on an optimizer or risk score. - Each allocation must have a composition, consisting of models, defined with
POST /allocation_composition
. For allocations following a core-satellite methodology, one model within the allocation composition must be marked ascore
. - Since allocations must have model holdings, the models and the models’ holdings must be created with
POST /model
andPOST /model_holding
, respectively.
- Allocations are defined with
Savings & Investing
Goals
Accumulation Goal Allocation
This service offers a framework to match an accumulation goal to an appropriate portfolio, with the ability to prioritize an investor’s risk appetite or prioritize the goal achievement. Allocations are selected from a universe based upon best fit for the selected priority, drawing from pre-defined portfolios and dynamically generated portfolios. This framework also has built-in support for a goal recommendation engine, which recommends actions that may be taken to increase the expected goal achievement probability if a goal cannot be achieved in the initially presented allocation context.
HTTP REQUEST
Example Request
POST /goal_accumulation/allocation
curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
-H "Content-Type: application/json" \
-d '{
"allocation_method": "create",
"allocation_priority": "goal",
"allocations": [
"406ec16e-ebae-4130-a6c0-1cacb72569a2",
"740f6466-3300-4122-927d-4a691359fa32",
"0a02058f-4046-48de-b3d2-aeefd6d4efac"
],
"opt_config": {
"tickers": ["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
"min_assets": 6,
"w_config": {
"w_min_major": 0.05,
"w_max_major": 1,
"w_min_minor": 0.05,
"w_max_minor": 0.1,
"cash_amount": 0.0
},
"w_asset_config": {
"US_Equities": 1.0,
"Fixed_Income": 1.0,
"Intl_Equities": 1.0,
"EM_Equities": 1.0,
"Commodities": 1.0
},
"sec_types": ["minor", "major", "minor", "minor", "minor", "minor"],
"start_date": "2016-01-01",
"end_date": "2017-01-01"
},
"risk_score": 77,
"trading_days_per_year": 252,
"horizon": 5,
"horizon_frequency": "year",
"deposit_config": [
{
"dep_start_reference": "a_start",
"dep_start_period": 0,
"dep_end_reference": "a_start",
"dep_end_period": 3,
"dep_amount": 2000,
"dep_frequency": "year",
"dep_inflation": 0.0
}
],
"goal_config": {
"goal_amount": 25000,
"goal_inflation": 0.0
},
"recommendation_config": {
"recommend": true,
"inv_min": 0,
"inv_max": 1000,
"dep_min": 0,
"dep_max": 1000,
"horizon_min": 1,
"horizon_max": 10,
"recommended_inflation": 0.0
},
"curr_inv": 10000,
"recommend_type": "recurring",
"conf_tgt": 0.9,
"n": 1000,
"remove_outliers": true,
"thresh_type": "perc",
"thresh": 0,
"withdrawal_tax": 0.0
}' "https://api.hydrogenplatform.com/proton/v1/goal_accumulation/allocation"
ARGUMENTS
Parameter | Description |
---|---|
allocation_method string, required |
The allocation universe source, may be either create or select . create constructs an allocation universe from a dynamically generated efficient frontier, based on opt_config . select derives an allocation universe from pre-defined allocations, as stipulated by allocations . |
allocation_priority string, required |
The priority to consider when deriving the appropriate allocation, may be risk or goal . risk finds a portfolio that corresponds to an investor’s risk_score within the universe of potential portfolios. goal does not consider the investor’s risk_score , but rather allocates to a portfolio that best achieves the goal. |
opt_config map, conditional requirement |
Portfolio optimization configuration, required if allocation_method = create . Information in opt_config refers to security data, which must be created in advance using the Nucleus endpoints POST /security and POST /security_price . opt_config includes the fields shown below. |
tickers array, required |
A list of tickers to consider during the optimization process, referencing securities defined in the Nucleus API. We recommend using no more than 25 tickers in a single optimization. Pre-screening a securities universe prior to calling the service will result in faster execution times as well as more meaningful results. |
min_assets integer, required |
The minimum number of portfolio assets, excluding the cash security (if applicable). |
w_config map, required |
Weight constraints for security types, including w_min_major , w_max_major , w_min_minor , w_max_minor , and cash_amount , which stipulate lower and upper bounds for minor and major securities, as well as a constant weight for cash securities. Minimums are joined with zero to form a binary constraint. This means that the minimum weight of securities of each type may either be 0 or the stipulated minimum. For example, a w_min_major constraint of 5% indicates that if a major” security is chosen during the optimization, its weight will be either 0% or >= 5%. |
w_asset_config map, required |
Weight constraints for asset classes. Stipulates a maximum weight for the asset classes represented in tickers . If an asset class is represented in tickers but not found in w_asset_config , the weight for that asset class will not be constrained. |
sec_types array, required |
A type for each security in tickers . Values may be major , minor , and cash . major and minor designations interact with w_config to set distinct weight constraints for different kinds of securities. A maximum of one security may be labelled with the cash type. |
start_date date, required |
Start date for historical prices in yyyy-mm-dd format. |
end_date date, required |
End date for historical prices in yyyy-mm-dd format. |
allocations array(UUID), conditional requirement |
A list of allocation identifiers, required if allocation_method = select . These identifiers refer to data defined using the Nucleus endpoint POST /allocation . |
curr_inv float, required |
The current amount invested toward the goal. |
horizon integer, required |
The goal horizon, with a frequency defined by horizon_frequency . For example, for a client that is looking to make a major purchase in 30 years, use horizon = 30. |
horizon_frequency string, required |
The frequency in relation to the number defined in horizon , and at which to run the simulation. Must be one of the following: year , six_months , quarter , month , week , day . |
goal_config map, required |
Information to configure the accumulation goal amount. |
goal_amount string, required |
The target goal amount, in today’s dollars. |
goal_inflation integer |
The annualized inflation rate for goal_amount . Defaults to 0. |
deposit_config array(map) |
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below. |
dep_start_reference string |
The reference for the starting point of the deposit. May be a_start or a_end , which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_start . |
dep_start_period integer |
The starting period for the deposit, relative to dep_start_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_end_reference string |
The reference for the ending point of the deposit. May be a_start or a_end , which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_end . |
dep_end_period integer |
The ending period for the deposit, relative to dep_end_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_amount float |
The deposit amount, in today’s dollars. Defaults to 0. |
dep_frequency string |
The frequency of the deposit. Must be one of the following: year , six_months , quarter , month , week , day . Defaults to year . |
dep_inflation float |
The annualized inflation rate for the deposit. Defaults to 0. |
recommendation_config map |
Information to configure the goal recommendation engine, including the fields shown below. |
recommend boolean |
If true , generate a recommended action to improve goal probability. Recommendations are only generated if a goal is off-track. Defaults to true . |
inv_min float |
The lower bound for one-time deposit recommendations. Defaults to 0. |
inv_max float |
The upper bound for one-time deposit recommendations. Defaults to goal_amount . |
dep_min float |
The lower bound for recurring deposit recommendations. Defaults to 0. |
dep_max float |
The upper bound for recurring deposit recommendations. Defaults to goal_amount divided by horizon . |
horizon_min integer |
The minimum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 1. |
horizon_max integer |
The maximum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 64. |
recommended_inflation float |
The annualized inflation rate attributed to a recommended recurring deposit. |
recommend_type string |
The type of recommended action. Value may be recurring , one-time , combo , or horizon . recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon . |
conf_tgt float |
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90. |
n integer |
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000. |
remove_outliers boolean |
If true , remove outlying results. If true , outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true. |
thresh_type string |
The goal deviation threshold type. Value may be perc or amnt . perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc . |
thresh float |
The goal deviation threshold value, corresponding to thresh_type . Defaults to 0. |
withdrawal_tax float |
The tax rate to apply to all withdrawals. Defaults to 0. |
trading_days_per_year integer |
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day . Defaults to 252. |
risk_score integer |
The investor’s risk score from 0 to 100, where 0 indicates minimum risk appetite and 100 indicates maximum risk appetite. |
Example Response
{
"current_status": {
"on_track": false,
"progress": 0.4,
"goal_probability": 0.4146,
"goal_achievement_score": 46,
"return_details": {
"0": {
"period_earnings": 0,
"period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"cumulative_deposits": 0,
"cumulative_withdrawals": 0,
"ending_balance": 10000
},
"1": {
"period_earnings": 185.03,
"period_deposit": 2000,
"period_withdrawal": 0,
"cumulative_earnings": 185.03,
"cumulative_deposits": 2000,
"cumulative_withdrawals": 0,
"ending_balance": 12185.03
},
"2": {
"period_earnings": 718.45,
"period_deposit": 2000,
"period_withdrawal": 0,
"cumulative_earnings": 903.48,
"cumulative_deposits": 4000,
"cumulative_withdrawals": 0,
"ending_balance": 14903.48
},
"3": {
"period_earnings": 976.09,
"period_deposit": 2000,
"period_withdrawal": 0,
"cumulative_earnings": 1879.58,
"cumulative_deposits": 6000,
"cumulative_withdrawals": 0,
"ending_balance": 17879.58
},
"4": {
"period_earnings": 1415.43,
"period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 3295.01,
"cumulative_deposits": 6000,
"cumulative_withdrawals": 0,
"ending_balance": 19295.01
},
"5": {
"period_earnings": 1499.23,
"period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 4794.23,
"cumulative_deposits": 6000,
"cumulative_withdrawals": 0,
"ending_balance": 20794.23
}
},
"adjusted_goal_amount": 25000
},
"recommended_status": {
"on_track": true,
"progress": 0.4,
"goal_probability": 0.9066,
"goal_achievement_score": 100,
"action": [
{
"value": 781.25,
"freq_unit": "year",
"value_type": "recurring_deposit"
}
],
"return_details": {
"0": {
"period_earnings": 0,
"period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"cumulative_deposits": 0,
"cumulative_withdrawals": 0,
"ending_balance": 10000
},
"1": {
"period_earnings": 208.86,
"period_deposit": 2781.25,
"period_withdrawal": 0,
"cumulative_earnings": 208.86,
"cumulative_deposits": 2781.25,
"cumulative_withdrawals": 0,
"ending_balance": 12990.11
},
"2": {
"period_earnings": 833.12,
"period_deposit": 2781.25,
"period_withdrawal": 0,
"cumulative_earnings": 1041.98,
"cumulative_deposits": 5562.5,
"cumulative_withdrawals": 0,
"ending_balance": 16604.48
},
"3": {
"period_earnings": 1248.32,
"period_deposit": 2781.25,
"period_withdrawal": 0,
"cumulative_earnings": 2290.29,
"cumulative_deposits": 8343.75,
"cumulative_withdrawals": 0,
"ending_balance": 20634.04
},
"4": {
"period_earnings": 1370.32,
"period_deposit": 781.25,
"period_withdrawal": 0,
"cumulative_earnings": 3660.62,
"cumulative_deposits": 9125,
"cumulative_withdrawals": 0,
"ending_balance": 22785.62
},
"5": {
"period_earnings": 1551.02,
"period_deposit": 781.25,
"period_withdrawal": 0,
"cumulative_earnings": 5211.63,
"cumulative_deposits": 9906.25,
"cumulative_withdrawals": 0,
"ending_balance": 25117.88
}
},
"adjusted_goal_amount": 25000
},
"allocation": {
"ret": 0.1018,
"risk": 0.0665,
"assets": [
"AGG",
"AMZN",
"CMCSA",
"GOOGL",
"KHC",
"XOM"
],
"weights": [
0.5,
0.1,
0.1,
0.1,
0.1,
0.1
],
"identifier": null
}
}
RESPONSE
Field | Description |
---|---|
current_status |
The current status of the goal. |
on_track |
If true , the goal is on track. |
progress |
The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon . |
goal_probability |
The probability of achieving the goal with the given portfolio. |
goal_achievement_score |
A ratio of goal_probability to the conf_tgt on a scale from 0 to 100. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_deposit |
The deposit made for this period in the accumulation phase. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_deposits |
The cumulative deposits made up to and including this period for the decumulation phase. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
adjusted_goal_amount |
The effective goal target amount, adjusted for taxes, inflation, and goal deviation threshold. |
recommended_status |
The goal status based on the provided recommendation. |
on_track |
If true , the goal is on track. |
progress |
The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon . |
goal_probability |
The probability of achieving the goal with the given portfolio. |
goal_achievement_score |
A ratio of goal_probability to the conf_tgt on a scale from 0 to 100. |
action |
The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits. |
value |
The value of the recommended action. |
freq_unit |
The frequency unit of value . |
value_type |
The type of recommendation being made. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_deposit |
The deposit made for this period in the accumulation phase. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_deposits |
The cumulative deposits made up to and including this period for the decumulation phase. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
adjusted_goal_amount |
The effective goal target amount, adjusted for taxes, inflation, and goal deviation threshold. |
allocation |
Information about the chosen portfolio, including risk and return. |
ret |
The portfolio annualized return. |
risk |
The portfolio annualized standard deviation. |
assets |
The securities in the created portfolio, returned if allocation_method = create . |
weights |
The weights for each of the securities in the created portfolio, returned if allocation_method = create . |
identifier |
The allocation’s id, returned if allocation_method = select . |
NUCLEUS DATA DEPENDENCIES
1. Allocations: POST /allocation
2. Securities: POST /security
3. Security Prices: POST /security_price
Accumulation Goal Recommendation
This service is a recommendation engine that generates actions to increase the likelihood of achieving an accumulation goal, based on portfolio attributes and a target goal amount. Available actions include various types of cash inflows as well as goal horizon extension. The engine will attempt to find the minimal recommended action that satisfies a goal confidence target, subject to the given constraints.
HTTP REQUEST
POST /goal_accumulation/recommendation
Example Request
curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
-H "Content-Type: application/json" \
-d '{
"p_ret": [0.09],
"p_risk": [0.05],
"trading_days_per_year": 252,
"horizon": 5,
"horizon_frequency": "year",
"deposit_config": [
{
"dep_start_reference": "a_start",
"dep_start_period": 0,
"dep_end_reference": "a_start",
"dep_end_period": 3,
"dep_amount": 2000,
"dep_frequency": "year",
"dep_inflation": 0.0
}
],
"goal_config": {
"goal_amount": 25000,
"goal_inflation": 0.0
},
"recommendation_config": {
"inv_min": 0,
"inv_max": 1000,
"dep_min": 0,
"dep_max": 1000,
"horizon_min": 1,
"horizon_max": 10,
"recommended_inflation": 0.0
},
"curr_inv": 10000,
"recommend_type": "recurring",
"conf_tgt": 0.9,
"n": 1000,
"remove_outliers": true,
"thresh_type": "perc",
"thresh": 0,
"withdrawal_tax": 0.0
}' "https://api.hydrogenplatform.com/proton/v1/goal_accumulation/recommendation"
ARGUMENTS
Parameter | Description |
---|---|
p_ret array, required |
The annual portfolio return per period. The length of the array must be less than or equal to horizon . If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_ret of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods. |
p_risk array, required |
The annual portfolio standard deviation per period. The length of the array must be less than or equal to horizon . If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_risk of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods. |
curr_inv float, required |
The current amount invested toward the goal. |
horizon integer, required |
The goal horizon, with a frequency defined by horizon_frequency . For example, for a client that is looking to make a major purchase in 30 years, use horizon = 30. |
horizon_frequency string, required |
The frequency in relation to the number defined in horizon , and at which to run the simulation. Must be one of the following: year , six_months , quarter , month , week , day . |
goal_config map, required |
Information to configure the accumulation goal amount. |
goal_amount string, required |
The target goal amount, in today’s dollars. |
goal_inflation integer |
The annualized inflation rate for goal_amount . Defaults to 0. |
deposit_config array(map) |
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below. |
dep_start_reference string |
The reference for the starting point of the deposit. May be a_start or a_end , which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_start . |
dep_start_period integer |
The starting period for the deposit, relative to dep_start_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_end_reference string |
The reference for the ending point of the deposit. May be a_start or a_end , which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_end . |
dep_end_period integer |
The ending period for the deposit, relative to dep_end_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_amount float |
The deposit amount, in today’s dollars. Defaults to 0. |
dep_frequency string |
The frequency of the deposit. Must be one of the following: year , six_months , quarter , month , week , day . Defaults to year . |
dep_inflation float |
The annualized inflation rate for the deposit. Defaults to 0. |
recommendation_config map |
Information to configure the goal recommendation engine, including the fields shown below. |
inv_min float |
The lower bound for one-time deposit recommendations. Defaults to 0. |
inv_max float |
The upper bound for one-time deposit recommendations. Defaults to goal_amount . |
dep_min float |
The lower bound for recurring deposit recommendations. Defaults to 0. |
dep_max float |
The upper bound for recurring deposit recommendations. Defaults to goal_amount divided by horizon . |
horizon_min integer |
The minimum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 1. |
horizon_max integer |
The maximum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 64. |
recommended_inflation float |
The annualized inflation rate attributed to a recommended recurring deposit. |
recommend_type string |
The type of recommended action. Value may be recurring , one-time , combo , or horizon . recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon . |
conf_tgt float |
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90. |
n integer |
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000. |
remove_outliers boolean |
If true , remove outlying results. If true , outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true. |
thresh_type string |
The goal deviation threshold type. Value may be “perc” or “amnt”. perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc . |
thresh float |
The goal deviation threshold value, corresponding to thresh_type . Defaults to 0. |
withdrawal_tax float |
The tax rate to apply to all withdrawals. Defaults to 0. |
trading_days_per_year integer |
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day . Defaults to 252. |
Example Response
{
"on_track": true,
"progress": 0.4,
"goal_probability": 0.9174,
"goal_achievement_score": 100,
"action": [
{
"value": 812.5,
"freq_unit": "year",
"value_type": "recurring_deposit"
}
],
"return_details": {
"0": {
"period_earnings": 0,
"period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"cumulative_deposits": 0,
"cumulative_withdrawals": 0,
"ending_balance": 10000
},
"1": {
"period_earnings": 263.63,
"period_deposit": 2812.5,
"period_withdrawal": 0,
"cumulative_earnings": 263.63,
"cumulative_deposits": 2812.5,
"cumulative_withdrawals": 0,
"ending_balance": 13076.13
},
"2": {
"period_earnings": 796.32,
"period_deposit": 2812.5,
"period_withdrawal": 0,
"cumulative_earnings": 1059.95,
"cumulative_deposits": 5625,
"cumulative_withdrawals": 0,
"ending_balance": 16684.95
},
"3": {
"period_earnings": 927.94,
"period_deposit": 2812.5,
"period_withdrawal": 0,
"cumulative_earnings": 1987.88,
"cumulative_deposits": 8437.5,
"cumulative_withdrawals": 0,
"ending_balance": 20425.38
},
"4": {
"period_earnings": 1419.98,
"period_deposit": 812.5,
"period_withdrawal": 0,
"cumulative_earnings": 3407.86,
"cumulative_deposits": 9250,
"cumulative_withdrawals": 0,
"ending_balance": 22657.86
},
"5": {
"period_earnings": 1823.4,
"period_deposit": 812.5,
"period_withdrawal": 0,
"cumulative_earnings": 5231.26,
"cumulative_deposits": 10062.5,
"cumulative_withdrawals": 0,
"ending_balance": 25293.76
}
},
"adjusted_goal_amount": 25000
}
RESPONSE
Field | Description |
---|---|
on_track |
If true , the goal is on track. |
progress |
The goal progress percentage, defined as the current invested amount divided by the target goal_amount . |
goal_probability |
The probability of achieving the goal with the given portfolio. |
goal_achievement_score |
A ratio of goal_probability to the conf_tgt on a scale from 0 to 100. |
action |
The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits. |
value |
The value of the recommended action. |
freq_unit |
The frequency unit of value . |
value_type |
The type of recommendation being made. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_deposit |
The deposit made for this period in the accumulation phase. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_deposit |
The cumulative deposits made up to and including this period for the accumulation phase. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
adjusted_goal_amount |
The effective goal target amount, adjusted for taxes, inflation, and goal deviation threshold. |
Accumulation Goal Status
This service analyzes the state of expected goal achievement for an accumulation goal, based on the current goal configuration and context. In addition to a raw indication of whether a goal is on or off track, the service provides other metrics for advanced analysis. This framework also has built-in support for a goal recommendation engine, which recommends actions that may be taken to increase the expected goal achievement probability if a goal is off track.
HTTP REQUEST
POST /goal_accumulation/status
Example Request
curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
-H "Content-Type: application/json" \
-d '{
"p_ret": [0.09],
"p_risk": [0.05],
"trading_days_per_year": 252,
"horizon": 5,
"horizon_frequency": "year",
"deposit_config": [
{
"dep_start_reference": "a_start",
"dep_start_period": 0,
"dep_end_reference": "a_start",
"dep_end_period": 3,
"dep_amount": 2000,
"dep_frequency": "year",
"dep_inflation": 0.0
}
],
"goal_config": {
"goal_amount": 25000,
"goal_inflation": 0.0
},
"recommendation_config": {
"recommend": true,
"inv_min": 0,
"inv_max": 1000,
"dep_min": 0,
"dep_max": 1000,
"horizon_min": 1,
"horizon_max": 10,
"recommended_inflation": 0.0
},
"curr_inv": 10000,
"recommend_type": "recurring",
"conf_tgt": 0.9,
"n": 1000,
"remove_outliers": true,
"thresh_type": "perc",
"thresh": 0,
"withdrawal_tax": 0.0
}' "https://api.hydrogenplatform.com/proton/v1/goal_accumulation/status"
ARGUMENTS
Parameter | Description |
---|---|
p_ret array, required |
The annual portfolio return per period. The length of the array must be less than or equal to horizon . If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_ret of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods. |
p_risk array, required |
The annual portfolio standard deviation per period. The length of the array must be less than or equal to horizon . If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_risk of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods. |
curr_inv float, required |
The current amount invested toward the goal. |
horizon integer, required |
The goal horizon, with a frequency defined by horizon_frequency . For example, for a client that is looking to make a major purchase in 30 years, use horizon = 30. |
horizon_frequency string, required |
The frequency in relation to the number defined in horizon , and at which to run the simulation. Must be one of the following: year , six_months , quarter , month , week , day . |
goal_config map, required |
Information to configure the accumulation goal amount. |
goal_amount string, required |
The target goal amount, in today’s dollars. |
goal_inflation integer |
The annualized inflation rate for goal_amount . Defaults to 0. |
deposit_config array(map) |
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below. |
dep_start_reference string |
The reference for the starting point of the deposit. May be a_start or a_end , which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_start . |
dep_start_period integer |
The starting period for the deposit, relative to dep_start_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_end_reference string |
The reference for the ending point of the deposit. May be a_start or a_end , which refer to the start of the accumulation phase and the end of the accumulation phase, respectively. Defaults to a_end . |
dep_end_period integer |
The ending period for the deposit, relative to dep_end_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_amount float |
The deposit amount, in today’s dollars. Defaults to 0. |
dep_frequency string |
The frequency of the deposit. Must be one of the following: year , six_months , quarter , month , week , day . Defaults to year . |
dep_inflation float |
The annualized inflation rate for the deposit. Defaults to 0. |
recommendation_config map |
Information to configure the goal recommendation engine, including the fields shown below. |
recommend boolean |
If true , generate a recommended action to improve goal probability. Recommendations are only generated if a goal is off-track. Defaults to true . |
inv_min float |
The lower bound for one-time deposit recommendations. Defaults to 0. |
inv_max float |
The upper bound for one-time deposit recommendations. Defaults to goal_amount . |
dep_min float |
The lower bound for recurring deposit recommendations. Defaults to 0. |
dep_max float |
The upper bound for recurring deposit recommendations. Defaults to goal_amount divided by horizon . |
horizon_min integer |
The minimum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 1. |
horizon_max integer |
The maximum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 64. |
recommended_inflation float |
The annualized inflation rate attributed to a recommended recurring deposit. |
recommend_type string |
The type of recommended action. Value may be recurring , one-time , combo , or horizon . recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon . |
conf_tgt float |
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90. |
n integer |
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000. |
remove_outliers boolean |
If true , remove outlying results. If true , outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true. |
thresh_type string |
The goal deviation threshold type. Value may be “perc” or “amnt”. perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc . |
thresh float |
The goal deviation threshold value, corresponding to thresh_type . Defaults to 0. |
withdrawal_tax float |
The tax rate to apply to all withdrawals. Defaults to 0. |
trading_days_per_year integer |
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day . Defaults to 252. |
Example Response
{
"current_status": {
"on_track": false,
"progress": 0.4,
"goal_probability": 0.1803,
"goal_achievement_score": 20,
"return_details": {
"0": {
"period_earnings": 0,
"period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"cumulative_deposits": 0,
"cumulative_withdrawals": 0,
"ending_balance": 10000
},
"1": {
"period_earnings": 232.9,
"period_deposit": 2000,
"period_withdrawal": 0,
"cumulative_earnings": 232.9,
"cumulative_deposits": 2000,
"cumulative_withdrawals": 0,
"ending_balance": 12232.9
},
"2": {
"period_earnings": 749.58,
"period_deposit": 2000,
"period_withdrawal": 0,
"cumulative_earnings": 982.47,
"cumulative_deposits": 4000,
"cumulative_withdrawals": 0,
"ending_balance": 14982.47
},
"3": {
"period_earnings": 989.45,
"period_deposit": 2000,
"period_withdrawal": 0,
"cumulative_earnings": 1971.92,
"cumulative_deposits": 6000,
"cumulative_withdrawals": 0,
"ending_balance": 17971.92
},
"4": {
"period_earnings": 1304.16,
"period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 3276.08,
"cumulative_deposits": 6000,
"cumulative_withdrawals": 0,
"ending_balance": 19276.08
},
"5": {
"period_earnings": 1383.55,
"period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 4659.63,
"cumulative_deposits": 6000,
"cumulative_withdrawals": 0,
"ending_balance": 20659.63
}
},
"adjusted_goal_amount": 25000
},
"recommended_status": {
"on_track": true,
"progress": 0.4,
"goal_probability": 0.9139,
"goal_achievement_score": 100,
"action": [
{
"value": 796.875,
"freq_unit": "year",
"value_type": "recurring_deposit"
}
],
"return_details": {
"0": {
"period_earnings": 0,
"period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"cumulative_deposits": 0,
"cumulative_withdrawals": 0,
"ending_balance": 10000
},
"1": {
"period_earnings": 299.41,
"period_deposit": 2796.88,
"period_withdrawal": 0,
"cumulative_earnings": 299.41,
"cumulative_deposits": 2796.88,
"cumulative_withdrawals": 0,
"ending_balance": 13096.28
},
"2": {
"period_earnings": 790.19,
"period_deposit": 2796.88,
"period_withdrawal": 0,
"cumulative_earnings": 1089.6,
"cumulative_deposits": 5593.75,
"cumulative_withdrawals": 0,
"ending_balance": 16683.35
},
"3": {
"period_earnings": 1044.57,
"period_deposit": 2796.88,
"period_withdrawal": 0,
"cumulative_earnings": 2134.16,
"cumulative_deposits": 8390.62,
"cumulative_withdrawals": 0,
"ending_balance": 20524.79
},
"4": {
"period_earnings": 1380.04,
"period_deposit": 796.88,
"period_withdrawal": 0,
"cumulative_earnings": 3514.2,
"cumulative_deposits": 9187.5,
"cumulative_withdrawals": 0,
"ending_balance": 22701.7
},
"5": {
"period_earnings": 1656.7,
"period_deposit": 796.88,
"period_withdrawal": 0,
"cumulative_earnings": 5170.9,
"cumulative_deposits": 9984.38,
"cumulative_withdrawals": 0,
"ending_balance": 25155.28
}
},
"adjusted_goal_amount": 25000
}
}
RESPONSE
Field | Description |
---|---|
current_status |
The current status of the goal. |
on_track |
If true , the goal is on track. |
progress |
The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon . |
goal_probability |
The probability of achieving the goal with the given portfolio. |
goal_achievement_score |
A ratio of goal_probability to the conf_tgt on a scale from 0 to 100. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_deposit |
The deposit made for this period in the accumulation phase. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_deposit |
The cumulative deposits made up to and including this period for the decumulation phase. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
adjusted_goal_amount |
The effective goal target amount, adjusted for taxes, inflation, and goal deviation threshold. |
recommended_status |
The goal status based on the provided recommendation. |
on_track |
If true , the goal is on track. |
progress |
The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon . |
goal_probability |
The probability of achieving the goal with the given portfolio. |
goal_achievement_score |
A ratio of goal_probability to the conf_tgt on a scale from 0 to 100. |
action |
The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits. |
value |
The value of the recommended action. |
freq_unit |
The frequency unit of value . |
value_type |
The type of recommendation being made. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_deposit |
The deposit made for this period in the accumulation phase. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_deposit |
The cumulative deposits made up to and including this period for the decumulation phase. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
adjusted_goal_amount |
The effective goal target amount, adjusted for taxes, inflation, and goal deviation threshold. |
Decumulation Goal Allocation
This service offers a framework to match a decumulation goal to an appropriate portfolio, with the ability to prioritize an investor’s risk appetite or prioritize the goal achievement. Allocations are selected from a universe based upon best fit for the selected priority, drawing from pre-defined portfolios and dynamically generated portfolios. This framework also has built-in support for a goal recommendation engine, which recommends actions that may be taken to increase the expected goal achievement probability if a goal cannot be achieved in the initially presented allocation context.
HTTP REQUEST
POST /goal_decumulation/allocation
Example Request
curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
-H "Content-Type: application/json" \
-d '{
"allocation_method": "create",
"allocation_priority": "goal",
"allocations": [
"406ec16e-ebae-4130-a6c0-1cacb72569a2",
"740f6466-3300-4122-927d-4a691359fa32",
"0a02058f-4046-48de-b3d2-aeefd6d4efac"
],
"opt_config": {
"tickers": ["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
"min_assets": 6,
"w_config": {
"w_min_major": 0.05,
"w_max_major": 1,
"w_min_minor": 0.05,
"w_max_minor": 0.1,
"cash_amount": 0.0
},
"w_asset_config": {
"US_Equities": 1.0,
"Fixed_Income": 1.0,
"Intl_Equities": 1.0,
"EM_Equities": 1.0,
"Commodities": 1.0
},
"sec_types": ["minor", "major","minor", "minor", "minor", "minor"],
"start_date": "2016-01-01",
"end_date": "2017-01-01"
},
"risk_score": 77,
"trading_days_per_year": 252,
"a_horizon": 3,
"d_horizon": 2,
"horizon_frequency": "year",
"deposit_config": [
{
"dep_start_reference": "a_start",
"dep_start_period": 0,
"dep_end_reference": "a_start",
"dep_end_period": 3,
"dep_amount": 2000,
"dep_frequency": "year",
"dep_inflation": 0.0
}
],
"withdrawal_config": [
{
"with_amount": 11000,
"with_start_reference": "a_end",
"with_start_period": 0,
"with_end_reference": "d_end",
"with_end_period": 0,
"with_frequency": "year",
"with_inflation": 0.0
}
],
"recommendation_config": {
"recommend": true,
"inv_min": 0,
"inv_max": 1000,
"dep_min": 0,
"dep_max": 1000,
"horizon_min": 1,
"horizon_max": 10,
"recommended_inflation": 0.0
},
"curr_inv": 10000,
"recommend_type": "recurring",
"conf_tgt": 0.9,
"n": 1000,
"remove_outliers": true,
"thresh_type": "perc",
"thresh": 0,
"withdrawal_tax": 0.0
}' "https://api.hydrogenplatform.com/proton/v1/goal_decumulation/allocation"
ARGUMENTS
Parameter | Description |
---|---|
allocation_method string, required |
The allocation universe source, may be either create or select . create constructs an allocation universe from a dynamically generated efficient frontier, based on opt_config . select derives an allocation universe from pre-defined allocations, as stipulated by allocations . |
allocation_priority string, required |
The priority to consider when deriving the appropriate allocation, may be risk or goal . risk finds a portfolio that corresponds to an investor’s risk_score within the universe of potential portfolios. goal does not consider the investor’s risk_score , but rather allocates to a portfolio that best achieves the goal. |
opt_config map, conditional requirement |
Portfolio optimization configuration, required if allocation_method = create . Information in opt_config refers to security data, which must be created in advance using the Nucleus endpoints POST /security and POST /security_price . opt_config includes the fields shown below. |
tickers array, required |
A list of tickers to consider during the optimization process, referencing securities defined in the Nucleus API. We recommend using no more than 25 tickers in a single optimization. Pre-screening a securities universe prior to calling the service will result in faster execution times as well as more meaningful results. |
min_assets integer, required |
The minimum number of portfolio assets, excluding the cash security (if applicable). |
w_config map, required |
Weight constraints for security types, including w_min_major , w_max_major , w_min_minor , w_max_minor , and cash_amount , which stipulate lower and upper bounds for minor and major securities, as well as a constant weight for cash securities. Minimums are joined with zero to form a binary constraint. This means that the minimum weight of securities of each type may either be 0 or the stipulated minimum. For example, a w_min_major constraint of 5% indicates that if a major” security is chosen during the optimization, its weight will be either 0% or >= 5%. |
w_asset_config map, required |
Weight constraints for asset classes. Stipulates a maximum weight for the asset classes represented in tickers . If an asset class is represented in tickers but not found in w_asset_config , the weight for that asset class will not be constrained. |
sec_types array, required |
A type for each security in tickers . Values may be major , minor , and cash . major and minor designations interact with w_config to set distinct weight constraints for different kinds of securities. A maximum of one security may be labelled with the cash type. |
start_date date, required |
Start date for historical prices in yyyy-mm-dd format. |
end_date date, required |
End date for historical prices in yyyy-mm-dd format. |
allocations array(UUID), conditional requirement |
A list of allocation identifiers, required if allocation_method = select . These identifiers refer to data defined using the Nucleus endpoint POST /allocation . |
curr_inv float, required |
The current amount invested toward the goal. |
a_horizon integer, required |
The accumulation horizon, with a frequency defined by horizon_frequency . For example, for a client that is looking to retire in 30 years, use a_horizon = 30. |
d_horizon integer, required |
The decumulation horizon, with a frequency defined by horizon_frequency . For example, for a client that is looking to take withdrawals for 25 years during retirement, use d_horizon = 25. |
horizon_frequency string, required |
The frequency in relation to the numbers defined in a_horizon and d_horizon , and at which to run the simulation. Must be one of the following: year , six_months , quarter , month , week , day . |
withdrawal_config array(map), required |
The withdrawals to occur during the goal’s decumulation phase. withdrawal_config is an array of maps, with each map containing the fields shown below. |
with_amount float, required |
The withdrawal amount, in today’s dollars. |
with_start_reference string |
The reference for the starting point of the withdrawal. May be a_end or d_end , which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to a_end . |
with_start_period integer |
The starting period for the withdrawal, relative to with_start_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency . Defaults to 0. |
with_end_reference string |
The reference for the ending point of the withdrawal. May be a_end or d_end , which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to d_end . |
with_end_period integer |
The ending period for the withdrawal, relative to with_end_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency . Defaults to 0. |
with_frequency string |
The frequency of the withdrawal. Must be one of the following: year , six_months , quarter , month , week , day . Defaults to year . |
with_inflation float |
The annualized inflation rate for the withdrawal. Defaults to 0. |
deposit_config array(map) |
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below. |
dep_start_reference string |
The reference for the starting point of the deposit. May be a_start , a_end , or d_end , which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_start . |
dep_start_period integer |
The starting period for the deposit, relative to dep_start_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_end_reference string |
The reference for the ending point of the deposit. May be a_start , a_end , or d_end , which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_end . |
dep_end_period integer |
The ending period for the deposit, relative to dep_end_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_amount float |
The deposit amount, in today’s dollars. Defaults to 0. |
dep_frequency string |
The frequency of the deposit. Must be one of the following: year , six_months , quarter , month , week , day . Defaults to year . |
dep_inflation float |
The annualized inflation rate for the deposit. Defaults to 0. |
recommendation_config map |
Information to configure the goal recommendation engine, including the fields shown below. |
recommend boolean |
If true , generate a recommended action to improve goal probability. Recommendations are only generated if a goal is off-track. Defaults to true . |
inv_min float |
The lower bound for one-time deposit recommendations. Defaults to 0. |
inv_max float |
The upper bound for one-time deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon . |
dep_min float |
The lower bound for recurring deposit recommendations. Defaults to 0. |
dep_max float |
The upper bound for recurring deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon divided by a_horizon . |
horizon_min integer |
The minimum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 1. |
horizon_max integer |
The maximum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 64. |
recommended_inflation float |
The annualized inflation rate attributed to a recommended recurring deposit. |
recommend_type string |
The type of recommended action. Value may be recurring , one-time , combo , or horizon . recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon . |
conf_tgt float |
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90. |
n integer |
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000. |
remove_outliers boolean |
If true , remove outlying results. If true , outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true. |
thresh_type string |
The goal deviation threshold type. Value may be “perc” or “amnt”. perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc . |
thresh float |
The goal deviation threshold value, corresponding to thresh_type . Defaults to 0. |
withdrawal_tax float |
The tax rate to apply to all withdrawals. Defaults to 0. |
trading_days_per_year integer |
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day . Defaults to 252. |
risk_score integer |
The investor’s risk score from 0 to 100, where 0 indicates minimum risk appetite and 100 indicates maximum risk appetite. |
Example Response
{
"current_status": {
"on_track": false,
"progress": 0.4545,
"goal_probability": 0.6306,
"goal_achievement_score": 70,
"return_details": {
"0": {
"period_earnings": 0,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"accumulation_cumulative_deposit": 0,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 10000
},
"1": {
"period_earnings": 223.91,
"accumulation_period_deposit": 2000,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 223.91,
"accumulation_cumulative_deposit": 2000,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 12223.91
},
"2": {
"period_earnings": 688.86,
"accumulation_period_deposit": 2000,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 912.77,
"accumulation_cumulative_deposit": 4000,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 14912.77
},
"3": {
"period_earnings": 1028.55,
"accumulation_period_deposit": 2000,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 1941.31,
"accumulation_cumulative_deposit": 6000,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 17941.31
},
"4": {
"period_earnings": 1308.43,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 11000,
"cumulative_earnings": 3249.74,
"accumulation_cumulative_deposit": 6000,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 11000,
"ending_balance": 8249.74
},
"5": {
"period_earnings": 0,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 8249.74,
"cumulative_earnings": 3249.74,
"accumulation_cumulative_deposit": 6000,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 19249.74,
"ending_balance": 0
}
}
},
"recommended_status": {
"on_track": true,
"progress": 0.4545,
"goal_probability": 0.9144,
"goal_achievement_score": 100,
"action": [
{
"value": 609.375,
"freq_unit": "year",
"value_type": "recurring_deposit"
}
],
"return_details": {
"0": {
"period_earnings": 0,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"accumulation_cumulative_deposit": 0,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 10000
},
"1": {
"period_earnings": 224.84,
"accumulation_period_deposit": 2609.38,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 224.84,
"accumulation_cumulative_deposit": 2609.38,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 12834.22
},
"2": {
"period_earnings": 697.17,
"accumulation_period_deposit": 2609.38,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 922.02,
"accumulation_cumulative_deposit": 5218.75,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 16140.77
},
"3": {
"period_earnings": 1179.99,
"accumulation_period_deposit": 2609.38,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 2102.01,
"accumulation_cumulative_deposit": 7828.12,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 19930.13
},
"4": {
"period_earnings": 1481.46,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 11000,
"cumulative_earnings": 3583.46,
"accumulation_cumulative_deposit": 7828.12,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 11000,
"ending_balance": 10411.59
},
"5": {
"period_earnings": 775.15,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 11000,
"cumulative_earnings": 4358.61,
"accumulation_cumulative_deposit": 7828.12,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 22000,
"ending_balance": 186.74
}
}
},
"allocation": {
"ret": 0.1018,
"risk": 0.0665,
"assets": [
"AGG",
"AMZN",
"CMCSA",
"GOOGL",
"KHC",
"XOM"
],
"weights": [
0.5,
0.1,
0.1,
0.1,
0.1,
0.1
],
"identifier": null
}
}
RESPONSE
Field | Description |
---|---|
current_status |
The current status of the goal. |
on_track |
If true , the goal is on track. |
progress |
The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon . |
goal_probability |
The probability of achieving the goal with the given portfolio. |
goal_achievement_score |
A ratio of goal_probability to the conf_tgt on a scale from 0 to 100. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
accumulation_period_deposit |
The deposit made for this period in the accumulation phase. |
decumulation_period_deposit |
The deposit made for this period in the decumulation phase. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
accumulation_cumulative_deposit |
The cumulative deposits made up to and including this period for the accumulation phase. |
decumulation_cumulative_deposit |
The cumulative deposits made up to and including this period for the decumulation phase. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
recommended_status |
The goal status based on the provided recommendation. |
on_track |
If true , the goal is on track. |
progress |
The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon . |
goal_probability |
The probability of achieving the goal with the given portfolio. |
goal_achievement_score |
A ratio of goal_probability to the conf_tgt on a scale from 0 to 100. |
action |
The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits. |
value |
The value of the recommended action. |
freq_unit |
The frequency unit of value . |
value_type |
The type of recommendation being made. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
accumulation_period_deposit |
The deposit made for this period in the accumulation phase. |
decumulation_period_deposit |
The deposit made for this period in the decumulation phase. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
accumulation_cumulative_deposit |
The cumulative deposits made up to and including this period for the accumulation phase. |
decumulation_cumulative_deposit |
The cumulative deposits made up to and including this period for the decumulation phase. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
allocation |
Information about the chosen portfolio, including risk and return. |
ret |
The portfolio annualized return. |
risk |
The portfolio annualized standard deviation. |
assets |
The securities in the created portfolio, returned if allocation_method = create . |
weights |
The weights for each of the securities in the created portfolio, returned if allocation_method = create . |
identifier |
The allocation’s id, returned if allocation_method = select . |
NUCLEUS DATA DEPENDENCIES
1. Allocations: POST /allocation
2. Securities: POST /security
3. Security Prices: POST /security_price
Decumulation Goal Recommendation
This service is a recommendation engine that generates actions to increase the likelihood of achieving a decumulation goal, based on portfolio attributes and a target goal amount. Available actions include various types of cash inflows as well as goal horizon extension. The engine will attempt to find the minimal recommended action that satisfies a goal confidence target, subject to the given constraints.
HTTP REQUEST
POST /goal_decumulation/recommendation
Example Request
curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
-H "Content-Type: application/json" \
-d '{
"p_ret": [0.09],
"p_risk": [0.05],
"trading_days_per_year": 252,
"a_horizon": 3,
"d_horizon": 2,
"horizon_frequency": "year",
"deposit_config": [
{
"dep_start_reference": "a_start",
"dep_start_period": 0,
"dep_end_reference": "a_start",
"dep_end_period": 3,
"dep_amount": 2000,
"dep_frequency": "year",
"dep_inflation": 0.0
}
],
"withdrawal_config": [
{
"with_amount": 11000,
"with_start_reference": "a_end",
"with_start_period": 0,
"with_end_reference": "d_end",
"with_end_period": 0,
"with_frequency": "year",
"with_inflation": 0.0
}
],
"recommendation_config": {
"inv_min": 0,
"inv_max": 1000,
"dep_min": 0,
"dep_max": 1000,
"horizon_min": 1,
"horizon_max": 10,
"recommended_inflation": 0.0
},
"curr_inv": 10000,
"recommend_type": "recurring",
"conf_tgt": 0.9,
"n": 1000,
"remove_outliers": true,
"thresh_type": "perc",
"thresh": 0,
"withdrawal_tax": 0.0
}' "https://api.hydrogenplatform.com/proton/v1/goal_decumulation/recommendation"
ARGUMENTS
Parameter | Description |
---|---|
p_ret array, required |
The annual portfolio return per period. The length of the array must be less than or equal to the sum of a_horizon and d_horizon . If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_ret of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods. |
p_risk array, required |
The annual portfolio standard deviation per period. The length of the array must be less than or equal to the sum of a_horizon and d_horizon . If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_risk of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods. |
curr_inv float, required |
The current amount invested toward the goal. |
a_horizon integer, required |
The accumulation horizon, with a frequency defined by horizon_frequency . For example, for a client that is looking to retire in 30 years, use a_horizon = 30. |
d_horizon integer, required |
The decumulation horizon, with a frequency defined by horizon_frequency . For example, for a client that is looking to take withdrawals for 25 years during retirement, use d_horizon = 25. |
horizon_frequency string, required |
The frequency in relation to the numbers defined in a_horizon and d_horizon , and at which to run the simulation. Must be one of the following: year , six_months , quarter , month , week , day . |
withdrawal_config array(map), required |
The withdrawals to occur during the goal’s decumulation phase. withdrawal_config is an array of maps, with each map containing the fields shown below. |
with_amount float, required |
The withdrawal amount, in today’s dollars. |
with_start_reference string |
The reference for the starting point of the withdrawal. May be a_end or d_end , which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to a_end . |
with_start_period integer |
The starting period for the withdrawal, relative to with_start_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency . Defaults to 0. |
with_end_reference string |
The reference for the ending point of the withdrawal. May be a_end or d_end , which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to d_end . |
with_end_period integer |
The ending period for the withdrawal, relative to with_end_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency . Defaults to 0. |
with_frequency string |
The frequency of the withdrawal. Must be one of the following: year , six_months , quarter , month , week , day . Defaults to year . |
with_inflation float |
The annualized inflation rate for the withdrawal. Defaults to 0. |
deposit_config array(map) |
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below. |
dep_start_reference string |
The reference for the starting point of the deposit. May be a_start , a_end , or d_end , which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_start . |
dep_start_period integer |
The starting period for the deposit, relative to dep_start_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_end_reference string |
The reference for the ending point of the deposit. May be a_start , a_end , or d_end , which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_end . |
dep_end_period integer |
The ending period for the deposit, relative to dep_end_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_amount float |
The deposit amount, in today’s dollars. Defaults to 0. |
dep_frequency string |
The frequency of the deposit. Must be one of the following: year , six_months , quarter , month , week , day . Defaults to year . |
dep_inflation float |
The annualized inflation rate for the deposit. Defaults to 0. |
recommendation_config map |
Information to configure the goal recommendation engine, including the fields shown below. |
inv_min float |
The lower bound for one-time deposit recommendations. Defaults to 0. |
inv_max float |
The upper bound for one-time deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon . |
dep_min float |
The lower bound for recurring deposit recommendations. Defaults to 0. |
dep_max float |
The upper bound for recurring deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon divided by a_horizon . |
horizon_min integer |
The minimum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 1. |
horizon_max integer |
The maximum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 64. |
recommended_inflation float |
The annualized inflation rate attributed to a recommended recurring deposit. |
recommend_type string |
The type of recommended action. Value may be recurring , one-time , combo , or horizon . recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon . |
conf_tgt float |
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90. |
n integer |
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000. |
remove_outliers boolean |
If true , remove outlying results. If true , outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true. |
thresh_type string |
The goal deviation threshold type. Value may be “perc” or “amnt”. perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc . |
thresh float |
The goal deviation threshold value, corresponding to thresh_type . Defaults to 0. |
withdrawal_tax float |
The tax rate to apply to all withdrawals. Defaults to 0. |
trading_days_per_year integer |
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day . Defaults to 252. |
Example Response
{
"on_track": true,
"progress": 0.4545,
"goal_probability": 0.9014,
"goal_achievement_score": 100,
"action": [
{
"value": 578.125,
"freq_unit": "year",
"value_type": "recurring_deposit"
}
],
"return_details": {
"0": {
"period_earnings": 0,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"accumulation_cumulative_deposit": 0,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 10000
},
"1": {
"period_earnings": 252.06,
"accumulation_period_deposit": 2578.12,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 252.06,
"accumulation_cumulative_deposit": 2578.12,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 12830.18
},
"2": {
"period_earnings": 793.84,
"accumulation_period_deposit": 2578.12,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 1045.89,
"accumulation_cumulative_deposit": 5156.25,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 16202.14
},
"3": {
"period_earnings": 1135.68,
"accumulation_period_deposit": 2578.12,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 2181.57,
"accumulation_cumulative_deposit": 7734.38,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 19915.95
},
"4": {
"period_earnings": 1212.82,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 11000,
"cumulative_earnings": 3394.39,
"accumulation_cumulative_deposit": 7734.38,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 11000,
"ending_balance": 10128.77
},
"5": {
"period_earnings": 875.44,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 11000,
"cumulative_earnings": 4269.84,
"accumulation_cumulative_deposit": 7734.38,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 22000,
"ending_balance": 4.21
}
}
}
RESPONSE
Field | Description |
---|---|
on_track |
If true , the goal is on track. |
progress |
The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon . |
goal_probability |
The probability of achieving the goal with the given portfolio. |
goal_achievement_score |
A ratio of goal_probability to the conf_tgt on a scale from 0 to 100. |
action |
The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits. |
value |
The value of the recommended action. |
freq_unit |
The frequency unit of value . |
value_type |
The type of recommendation being made. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
accumulation_period_deposit |
The deposit made for this period in the accumulation phase. |
decumulation_period_deposit |
The deposit made for this period in the decumulation phase. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
accumulation_cumulative_deposit |
The cumulative deposits made up to and including this period for the accumulation phase. |
decumulation_cumulative_deposit |
The cumulative deposits made up to and including this period for the decumulation phase. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Decumulation Goal Status
This service analyzes the state of expected goal achievement for a decumulation goal, based on the current goal configuration and context. In addition to a raw indication of whether a goal is on or off track, the service provides other metrics for advanced analysis. This framework also has built-in support for a goal recommendation engine, which recommends actions that may be taken to increase the expected goal achievement probability if a goal is off track.
HTTP REQUEST
POST /goal_decumulation/status
Example Request
curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
-H "Content-Type: application/json" \
-d '{
"p_ret": [0.09],
"p_risk": [0.05],
"trading_days_per_year": 252,
"a_horizon": 3,
"d_horizon": 2,
"horizon_frequency": "year",
"deposit_config": [
{
"dep_start_reference": "a_start",
"dep_start_period": 0,
"dep_end_reference": "a_start",
"dep_end_period": 3,
"dep_amount": 2000,
"dep_frequency": "year",
"dep_inflation": 0.0
}
],
"withdrawal_config": [
{
"with_amount": 11000,
"with_start_reference": "a_end",
"with_start_period": 0,
"with_end_reference": "d_end",
"with_end_period": 0,
"with_frequency": "year",
"with_inflation": 0.0
}
],
"recommendation_config": {
"recommend": true,
"inv_min": 0,
"inv_max": 1000,
"dep_min": 0,
"dep_max": 1000,
"horizon_min": 1,
"horizon_max": 10,
"recommended_inflation": 0.0
},
"curr_inv": 10000,
"recommend_type": "recurring",
"conf_tgt": 0.9,
"n": 1000,
"remove_outliers": true,
"thresh_type": "perc",
"thresh": 0,
"withdrawal_tax": 0.0
}' "https://api.hydrogenplatform.com/proton/v1/goal_decumulation/status"
ARGUMENTS
Parameter | Description |
---|---|
p_ret array, required |
The annual portfolio return per period. The length of the array must be less than or equal to the sum of a_horizon and d_horizon . If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_ret of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods. |
p_risk array, required |
The annual portfolio standard deviation per period. The length of the array must be less than or equal to the sum of a_horizon and d_horizon . If it is less, values will be conformed to the number of time periods by persisting the last value. For example, [0.04, 0.06] would result in an implied p_risk of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four time periods. |
curr_inv float, required |
The current amount invested toward the goal. |
a_horizon integer, required |
The accumulation horizon, with a frequency defined by horizon_frequency . For example, for a client that is looking to retire in 30 years, use a_horizon = 30. |
d_horizon integer, required |
The decumulation horizon, with a frequency defined by horizon_frequency . For example, for a client that is looking to take withdrawals for 25 years during retirement, use d_horizon = 25. |
horizon_frequency string, required |
The frequency in relation to the numbers defined in a_horizon and d_horizon , and at which to run the simulation. Must be one of the following: year , six_months , quarter , month , week , day . |
withdrawal_config array(map), required |
The withdrawals to occur during the goal’s decumulation phase. withdrawal_config is an array of maps, with each map containing the fields shown below. |
with_amount float, required |
The withdrawal amount, in today’s dollars. |
with_start_reference string |
The reference for the starting point of the withdrawal. May be a_end or d_end , which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to a_end . |
with_start_period integer |
The starting period for the withdrawal, relative to with_start_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency . Defaults to 0. |
with_end_reference string |
The reference for the ending point of the withdrawal. May be a_end or d_end , which refer to the end of the accumulation phase and the end of the decumulation phase, respectively. Defaults to d_end . |
with_end_period integer |
The ending period for the withdrawal, relative to with_end_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon with_frequency . Defaults to 0. |
with_frequency string |
The frequency of the withdrawal. Must be one of the following: year , six_months , quarter , month , week , day . Defaults to year . |
with_inflation float |
The annualized inflation rate for the withdrawal. Defaults to 0. |
deposit_config array(map) |
The deposits to occur over the course of the goal horizon. deposit_config is an array of maps, with each map containing the fields shown below. |
dep_start_reference string |
The reference for the starting point of the deposit. May be a_start , a_end , or d_end , which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_start . |
dep_start_period integer |
The starting period for the deposit, relative to dep_start_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_end_reference string |
The reference for the ending point of the deposit. May be a_start , a_end , or d_end , which refer to the start of the accumulation phase, the end of the accumulation phase, and the end of the decumulation phase, respectively. Defaults to a_end . |
dep_end_period integer |
The ending period for the deposit, relative to dep_end_reference . A value of 0 corresponds to the reference point, a positive number indicates a period after the reference point, and a negative number indicates a period before the reference point. Periodicity depends upon dep_frequency . Defaults to 0. |
dep_amount float |
The deposit amount, in today’s dollars. Defaults to 0. |
dep_frequency string |
The frequency of the deposit. Must be one of the following: year , six_months , quarter , month , week , day . Defaults to year . |
dep_inflation float |
The annualized inflation rate for the deposit. Defaults to 0. |
recommendation_config map |
Information to configure the goal recommendation engine, including the fields shown below. |
recommend boolean |
If true , generate a recommended action to improve goal probability. Recommendations are only generated if a goal is off-track. Defaults to true . |
inv_min float |
The lower bound for one-time deposit recommendations. Defaults to 0. |
inv_max float |
The upper bound for one-time deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon . |
dep_min float |
The lower bound for recurring deposit recommendations. Defaults to 0. |
dep_max float |
The upper bound for recurring deposit recommendations. Defaults to the first with_amount found in withdrawal_config multiplied by d_horizon divided by a_horizon . |
horizon_min integer |
The minimum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 1. |
horizon_max integer |
The maximum number of periods (defined by horizon_frequency ) that the accumulation horizon may be extended when recommend_type = horizon . Defaults to 64. |
recommended_inflation float |
The annualized inflation rate attributed to a recommended recurring deposit. |
recommend_type string |
The type of recommended action. Value may be recurring , one-time , combo , or horizon . recurring returns a recurring periodic deposit. one-time returns a one-time deposit at the current time (occurring at time-zero, and reflected by an effective increase in the initial balance). combo returns a combination of recurring and one-time deposits. horizon returns a new accumulation horizon for the goal. Defaults to horizon . |
conf_tgt float |
The confidence target for goal achievement. conf_tgt indicates the level of statistical confidence that applies to the goal analysis. In some cases, the stipulated conf_tgt may be impossible to achieve within the given goal parameters; in these cases, the service will attempt to come as close as possible to satisfying the confidence target. Defaults to 0.90. |
n integer |
The number of simulations to run in the monte carlo simulation. Larger n values will make goal simulation results more consistent, but increase the execution time of the service. It has a maximum allowable value of 10000. Defaults to 2000. |
remove_outliers boolean |
If true , remove outlying results. If true , outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. Defaults to true. |
thresh_type string |
The goal deviation threshold type. Value may be “perc” or “amnt”. perc indicates a percentage-based goal deviation threshold. amnt indicates a dollar-based goal deviation threshold. Defaults to perc . |
thresh float |
The goal deviation threshold value, corresponding to thresh_type . Defaults to 0. |
withdrawal_tax float |
The tax rate to apply to all withdrawals. Defaults to 0. |
trading_days_per_year integer |
The number of days per year for which a portfolio is subject to market fluctuation. trading_days_per_year impacts goal simulation results when horizon_frequency = day . Defaults to 252. |
Example Response
{
"current_status": {
"on_track": false,
"progress": 0.4545,
"goal_probability": 0.5323,
"goal_achievement_score": 59,
"return_details": {
"0": {
"period_earnings": 0,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"accumulation_cumulative_deposit": 0,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 10000
},
"1": {
"period_earnings": 272.95,
"accumulation_period_deposit": 2000,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 272.95,
"accumulation_cumulative_deposit": 2000,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 12272.95
},
"2": {
"period_earnings": 697.56,
"accumulation_period_deposit": 2000,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 970.51,
"accumulation_cumulative_deposit": 4000,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 14970.51
},
"3": {
"period_earnings": 1038.89,
"accumulation_period_deposit": 2000,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 2009.4,
"accumulation_cumulative_deposit": 6000,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 18009.4
},
"4": {
"period_earnings": 1097.18,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 11000,
"cumulative_earnings": 3106.58,
"accumulation_cumulative_deposit": 6000,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 11000,
"ending_balance": 8106.58
},
"5": {
"period_earnings": 0,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 8106.58,
"cumulative_earnings": 3106.58,
"accumulation_cumulative_deposit": 6000,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 19106.58,
"ending_balance": 0
}
}
},
"recommended_status": {
"on_track": true,
"progress": 0.4545,
"goal_probability": 0.9144,
"goal_achievement_score": 100,
"action": [
{
"value": 593.75,
"freq_unit": "year",
"value_type": "recurring_deposit"
}
],
"return_details": {
"0": {
"period_earnings": 0,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"accumulation_cumulative_deposit": 0,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 10000
},
"1": {
"period_earnings": 257.94,
"accumulation_period_deposit": 2593.75,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 257.94,
"accumulation_cumulative_deposit": 2593.75,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 12851.69
},
"2": {
"period_earnings": 808.5,
"accumulation_period_deposit": 2593.75,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 1066.44,
"accumulation_cumulative_deposit": 5187.5,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 16253.94
},
"3": {
"period_earnings": 1081.53,
"accumulation_period_deposit": 2593.75,
"decumulation_period_deposit": 0,
"period_withdrawal": 0,
"cumulative_earnings": 2147.98,
"accumulation_cumulative_deposit": 7781.25,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 0,
"ending_balance": 19929.23
},
"4": {
"period_earnings": 1384.31,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 11000,
"cumulative_earnings": 3532.29,
"accumulation_cumulative_deposit": 7781.25,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 11000,
"ending_balance": 10313.54
},
"5": {
"period_earnings": 891.49,
"accumulation_period_deposit": 0,
"decumulation_period_deposit": 0,
"period_withdrawal": 11000,
"cumulative_earnings": 4423.78,
"accumulation_cumulative_deposit": 7781.25,
"decumulation_cumulative_deposit": 0,
"cumulative_withdrawals": 22000,
"ending_balance": 205.03
}
}
}
}
RESPONSE
Field | Description |
---|---|
current_status |
The current status of the goal. |
on_track |
If true , the goal is on track. |
progress |
The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon . |
goal_probability |
The probability of achieving the goal with the given portfolio. |
goal_achievement_score |
A ratio of goal_probability to the conf_tgt on a scale from 0 to 100. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
accumulation_period_deposit |
The deposit made for this period in the accumulation phase. |
decumulation_period_deposit |
The deposit made for this period in the decumulation phase. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
accumulation_cumulative_deposit |
The cumulative deposits made up to and including this period for the accumulation phase. |
decumulation_cumulative_deposit |
The cumulative deposits made up to and including this period for the decumulation phase. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
recommended_status |
The goal status based on the provided recommendation. |
on_track |
If true , the goal is on track. |
progress |
The goal progress percentage, defined as the current invested amount divided by the total target withdrawal amount over d_horizon . |
goal_probability |
The probability of achieving the goal with the given portfolio. |
goal_achievement_score |
A ratio of goal_probability to the conf_tgt on a scale from 0 to 100. |
action |
The recommended action. Actions represent additions to the current configuration. For example, a recommended recurring deposit of 100 indicates 100 in addition to any existing deposits. |
value |
The value of the recommended action. |
freq_unit |
The frequency unit of value . |
value_type |
The type of recommendation being made. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
accumulation_period_deposit |
The deposit made for this period in the accumulation phase. |
decumulation_period_deposit |
The deposit made for this period in the decumulation phase. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
accumulation_cumulative_deposit |
The cumulative deposits made up to and including this period for the accumulation phase. |
decumulation_cumulative_deposit |
The cumulative deposits made up to and including this period for the decumulation phase. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Portfolio Construction
Mean-Variance Optimization
This service generates portfolios based on the principles of convex optimization. Securities are systematically weighted to maximize expected portfolio return for a given level of portfolio risk, subject to the defined constraints. Two outcomes can be achieved with this framework: target portfolio construction and efficient frontier construction. A target portfolio is a single optimal portfolio that adheres to a desired risk or return level, while an efficient frontier is a collection of optimal portfolios across a maximal range of risk and return levels.
HTTP REQUEST
POST /mvo
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"tickers": ["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"],
"min_assets": 2,
"w_config": {
"w_min_major": 0.05,
"w_max_major": 0.7,
"w_min_minor": 0.05,
"w_max_minor": 0.3,
"cash_amount": 0.03
},
"w_asset_config": {
"US_Equities": 1.0,
"Fixed_Income": 1.0,
"Intl_Equities": 1.0,
"EM_Equities": 1.0,
"Commodities": 1.0
},
"sec_types": ["major", "major", "minor", "minor", "minor", "Cash"],
"tgt_type": "risk",
"tgt_val": 0.09,
"start_date": "2015-01-01",
"end_date": "2017-01-01"
}' "https://api.hydrogenplatform.com/proton/v1/mvo"
ARGUMENTS
Parameter | Description |
---|---|
tickers array, required |
A list of tickers to consider during the optimization process, referencing securities defined in the Nucleus API. We recommend using no more than 25 tickers in a single optimization. Pre-screening a securities universe prior to calling the service will result in faster execution times as well as more meaningful results. |
min_assets integer, required |
The minimum number of portfolio assets, excluding the cash security (if applicable). |
w_config map, required |
Weight constraints for security types. Values that can be set are w_min_major , w_max_major , w_min_minor , w_max_minor , and cash_amount , which stipulate lower and upper bounds for minor and major securities, as well as a constant weight for cash securities. Minimums are joined with zero to form a binary constraint. This means that the minimum weight of securities of each type may either be 0 (i.e. not included in the final portfolio) or the stipulated minimum. For example, a w_min_major constraint of 5% indicates that if a major security is chosen during the optimization, its weight must be greater than or equal to 5%. If, however, the security is not chosen, its weight is also allowable at 0%. |
w_asset_config map, required |
Weight constraints for asset classes. Stipulates a maximum weight for each asset class represented in tickers. If an asset class is not found, the max constraint defaults to 100%. |
sec_types array, required |
A type for each security. Values may be major , minor , and cash . major and minor designations interact with w_config to set distinct weight constraints for different kinds of securities. A maximum of one security may be defined as cash . |
tgt_type string |
The target type for a target portfolio. If specified, a target portfolio is returned. Value may be risk or return . Risk targets place an upper bound on the allowed portfolio risk, while return targets place a lower bound on the allowed portfolio return. If excluded, a frontier of portfolios is returned. |
tgt_val float |
The target value for a target portfolio. Corresponds to tgt_type , and should indicate either an annualized portfolio return or an annualized portfolio standard deviation. If excluded, defaults to 0 . |
start_date date |
Start date for historical prices, represented in yyyy-mm-dd format. If excluded, defaults to today. |
end_date date |
End date for historical prices, represented in yyyy-mm-dd format. If excluded, defaults to today. |
Example Response
{
"target_portfolio": {
"securities": [
"AGG",
"VTI",
"SHY"
],
"weights": [
0.3345,
0.6355,
0.03
],
"ret": 0.0413,
"risk": 0.09
}
}
RESPONSE
Field | Description |
---|---|
frontier |
Returned if tgt_type is excluded from the request. This includes the securities, weights, risk and return for the series of optimal portfolios. |
target_portfolio |
Returned if tgt_type = risk or return . This includes the securities, weights, risk and return for the given portfolio. |
securities |
The securities in the portfolio. |
weights |
The weights for each of the securities in the portfolio. |
ret |
The return of the portfolio. |
risk |
The risk of the portfolio. |
NUCLEUS DATA DEPENDENCIES
1. Securities: POST /security
2. Security Prices: POST /security_price
Portfolio Management
Rebalancing
This service generates trade signals to strategically rebalance a model portfolio, with support for three types of rebalancing: period-based, drift-based, and Downside Protection. Period-based rebalancing generates a signal at the beginning of each time period with a pre-defined frequency. Drift-based rebalancing generates a signal whenever a portfolio holding deviates from its strategic target by a pre-defined amount. Downside Protection generates signals based on the observed risk of portfolio holdings, reducing exposure in stages as risk increases and restoring exposure in stages as risk decreases.
HTTP REQUEST
POST /rebalancing_signal
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"model_id": "a83fd921-11ab-4003-a340-9bca9d3e01bd",
"start_date": "2016-12-01",
"end_date": "2017-12-08",
"initial_weights": {
"CMCSA": 0.05,
"^IRX": 0.05,
"KO": 0.05,
"AMZN": 0.05,
"GOOGL": 0.1,
"CSCO": 0.1,
"AGG": 0.1,
"XOM": 0.1,
"INTC": 0.1,
"KHC": 0.1,
"MCD": 0.1,
"WMT": 0.1
}
}' "https://api.hydrogenplatform.com/proton/v1/rebalancing_signal"
ARGUMENTS
Parameter | Description |
---|---|
model_id UUID, required |
Identifier of the model in the Nucleus API to rebalance. In order to perform rebalancing, downside , drift_rebal or period_rebal must be set in the Nucleus endpoint /model . The drift_factor from /model_holding is used as of the start_date throughout the full simulation. If no drift factor is set in /model_holding , the default_drift_factor from /model is used. If period_rebal , set rebalance_period . If drift_rebal , set default_drift_factor . If downside , set safe_sec and cash_sec . |
start_date date, required |
Start date for analysis, represented in yyyy-mm-dd format. If excluded, defaults to today. |
end_date date, required |
End date for analysis, represented in yyyy-mm-dd format. If excluded, defaults to today. |
initial_weights map |
Initial weights for model holdings. If excluded, defaults to the model’s strategic_weight from /model_holding as of the start_date . |
Example Response
{
"rebalance_signals": [
{
"date": "2017-03-28T00:00:00",
"ticker": "CMCSA",
"signal": "SELL",
"amount": 12.745833518909741,
"type": 2
},
{
"date": "2017-03-28T00:00:00",
"ticker": "^IRX",
"signal": "BUY",
"amount": 155.94057228998332,
"type": 2
},
{
"date": "2017-03-28T00:00:00",
"ticker": "KO",
"signal": "SELL",
"amount": 12.63570207140365,
"type": 2
},
{
"date": "2017-03-28T00:00:00",
"ticker": "AMZN",
"signal": "SELL",
"amount": 16.0155517951892,
"type": 2
},
{
"date": "2017-03-28T00:00:00",
"ticker": "GOOGL",
"signal": "SELL",
"amount": 18.65995935855528,
"type": 2
},
{
"date": "2017-03-28T00:00:00",
"ticker": "CSCO",
"signal": "SELL",
"amount": 15.988445088739898,
"type": 2
},
{
"date": "2017-03-28T00:00:00",
"ticker": "AGG",
"signal": "SELL",
"amount": 45.96572996834058,
"type": 2
},
{
"date": "2017-03-28T00:00:00",
"ticker": "XOM",
"signal": "SELL",
"amount": 3.144146724151982,
"type": 2
},
{
"date": "2017-03-28T00:00:00",
"ticker": "INTC",
"signal": "SELL",
"amount": 5.25300352775003,
"type": 2
},
{
"date": "2017-03-28T00:00:00",
"ticker": "MCD",
"signal": "SELL",
"amount": 12.879881718355065,
"type": 2
},
{
"date": "2017-03-28T00:00:00",
"ticker": "WMT",
"signal": "SELL",
"amount": 12.65231851858788,
"type": 2
}
]
}
RESPONSE
Field | Description |
---|---|
rebalance_signals |
The rebalancing signals for the specified model. |
date |
The date of the given rebalancing signal. |
ticker |
The unique identifier of a given security. |
signal |
The trade action, either BUY or SELL . |
amount |
The amount of the trade as a percentage. For example, amount = 0.02 translates to selling 2% of a given ticker . |
type |
The type of trade signal. 1 = period-based, 2 = drift-based, and 4 = downside protection. |
NUCLEUS DATA DEPENDENCIES
1. Models: POST /model
2. Model Holdings: POST /model_holding
(model holdings are only required for the starting date of the backtest simulation)
3. Securities: POST /security
4. Security Prices: POST /security_price
Risk Scoring
Risk Score
This service calculates a risk score based on numerical answers to questions that evaluate risk appetite. The returned score is normalized on a scale from 0 to 100, where 0 indicates minimum risk appetite and 100 indicates maximum risk appetite.
HTTP REQUEST
POST /risk_score
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"answers": [10, 400, 3, 9],
"max_answers": [10, 1000, 4, 10],
"weights": [0.25, 0.25, 0.25, 0.25]
}' "https://api.hydrogenplatform.com/proton/v1/risk_score"
ARGUMENTS
Parameter | Description |
---|---|
answers array, required |
Answer values. Values must be greater than or equal to zero. Higher answer values are assumed to indicate more appetite for risk. |
max_answers array, required |
Maximum possible answer values. Values must be greater than or equal to zero. Scales for answers and max_answers need not be consistent, as values are automatically normalized. |
weights array |
Weights for each answer. If sum is not 1, values are normalized proportionally. Example: [60, 80, 60] would be normalized to [0.3, 0.4, 0.3] . If excluded, answer values are equal-weighted. |
Example Response
{
"risk_score": 76
}
RESPONSE
Field | Description |
---|---|
risk_score |
A risk score from 0 to 100. |
Dimensional Risk Score
This service calculates a risk score based on numerical answers to questions that evaluate risk appetite across multiple dimensions. Multi-dimensional analysis offers a more robust way to assess risk, as responses can be both strategically weighted and mapped to one or more distinct risk dimensions that are also strategically weighted. The returned score is normalized on a scale from 0 to 100, where 0 indicates minimum risk appetite and 100 indicates maximum risk appetite.
HTTP REQUEST
POST /dimensional_risk_score
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"answers": [10, 400, 3, 9],
"max_answers": [10, 1000, 4, 10],
"answer_dims": [["dim1"], ["dim2"], ["dim3"], ["dim4"]],
"dims": ["dim1", "dim2", "dim3", "dim4"],
"dim_weights": [0.25, 0.25, 0.25, 0.25],
"answer_weights": [0.25, 0.25, 0.25, 0.25]
}' "https://api.hydrogenplatform.com/proton/v1/dimensional_risk_score"
ARGUMENTS
Parameter | Description |
---|---|
answers array, required |
Answer values. Values must be greater than or equal to zero. Higher answer values are assumed to indicate more appetite for risk. |
max_answers array, required |
Maximum possible answer values. Values must be greater than or equal to zero. Scales for answers and max_answers need not be consistent, as values are automatically normalized. |
answer_dims array, required |
Question risk dimensions. Maps individual answers to one or multiple risk dimensions. Should only include labels found in dims . |
dims array, required |
Labels for available risk dimensions. Each item should be a string and can be custom configured to reflect any number of dimensions. When more than one question maps to a given dimension, relationships between various answer_weights serve as the basis for weighting answers within that dimension. |
dim_weights array |
Weights for each risk dimension. Values correspond to and should match the length of dims . If sum is not 1, values are normalized proportionally. Example: [60, 80, 60] would be normalized to [0.3, 0.4, 0.3] . If excluded, dimensions are equal-weighted. |
answer_weights array |
Weights for each risk dimension answer. If sum is not 1, values are normalized proportionally. Example: [60, 80, 60] would be normalized to [0.3, 0.4, 0.3] . If excluded, answer values are equal-weighted. |
Example Response
{
"risk_score": 76,
"dim_scores": {
"dim1": 100,
"dim2": 40,
"dim3": 75,
"dim4": 90
}
}
RESPONSE
Field | Description |
---|---|
risk_score |
A multi-dimensional risk score from 0 to 100. |
dim_scores |
A score from 0 to 100 for each dimension that was evaluated. |
Risk Allocation
This service returns a portfolio based on an investor’s risk score, drawing from a universe of pre-defined allocations
or a dynamically generated efficient frontier. The risk score is used to conduct a percentile analysis within the portfolio universe; a risk score of 0 maps to the lowest risk portfolio within the universe, while a risk score of 100 maps to the highest risk portfolio within the universe. The user is matched to the most suitable allocaiton, given it’s standard deviation and the user’s risk score.
HTTP REQUEST
POST /risk_allocation
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"risk_score": 49,
"allocation_method": "create",
"opt_config":
{
"tickers": ["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"],
"min_assets": 1,
"w_config": {
"w_min_major": 0.05,
"w_max_major": 1,
"w_min_minor": 0.05,
"w_max_minor": 1,
"cash_amount": 0.03
},
"w_asset_config": {
"US_Equities": 1.0,
"Fixed_Income": 1.0,
"Intl_Equities": 1.0,
"EM_Equities": 1.0,
"Commodities": 1.0
},
"sec_types": ["major", "major", "minor", "minor", "minor", "Cash"],
"start_date": "2016-01-01",
"end_date": "2017-01-01"
},
"allocations": ["347b1a30-342f-41f0-b484-78c350fc4243", "7688625f-ca41-47bd-a473-87f6f85abd78","99949b0d-b72e-4707-b405-d2342471085c", "ebcce5d0-3673-4607-a932-f8be3879ea6d", "a2f73f0a-a9db-4856-95d9-29fecd20fc3a", "5ad40620-0e4a-446d-ae04-955eedf866c6", "eae9d068-e273-41ee-90c6-d8a857b91bc7"]
}' "https://api.hydrogenplatform.com/proton/v1/risk_allocation"
ARGUMENTS
Parameter | Description |
---|---|
risk_score integer, required |
A risk score from 0 to 100. If score is not between 0 to 100, it will automatically be normalized onto a 0 to 100 scale. |
allocation_method string, required |
The allocation universe resource. Value may be either create or select . create derives an allocation universe from a dynamically generated efficient frontier, based on opt_config . select derives an allocation universe from pre-defined allocations, as stipulated by the identifiers found in allocations . |
opt_config map, conditional requirement |
Portfolio optimization configuration, required if allocation_method = create . Information in opt_config refers to security data, which must be created in advance using the Nucleus endpoint POST /security . opt_config includes the following parameters: |
tickers array, required |
A list of symbols for securities included in the portfolio. We recommend using no more than 25 tickers in a single optimization. Pre-screening a securities universe prior to calling the service will result in faster execution times as well as more meaningful results. |
min_assets integer, required |
The minimum number of portfolio assets, excluding the cash security (if applicable). |
w_config map, required |
Weight constraints for security types. Values that can be set are w_min_major , w_max_major , w_min_minor , w_max_minor , and cash_amount , which stipulate lower and upper bounds for minor and major securities, as well as a constant weight for cash securities. Minimums are joined with zero to form a binary constraint. This means that the minimum weight of securities of each type may either be 0 (i.e. not included in the final portfolio) or the stipulated minimum. For example, a w_min_major constraint of 5% indicates that if a “major” security is chosen during the optimization, its weight must be greater than or equal to 5%. If, however, the security is not chosen, its weight is also allowable at 0%. |
w_asset_config map, required |
Weight constraints for asset classes. Stipulates a maximum weight for each asset class represented in tickers. If an asset class is not found, the max constraint defaults to 100%. |
sec_types array, required |
A type for each security. Values may be major , minor , and cash . major and minor designations interact with w_config to set distinct weight constraints for different kinds of securities. A maximum of one security may be defined as cash . |
start_date date, required |
Start date for historical prices, represented in yyyy-mm-dd format. |
end_date date, required |
End date for historical prices, represented in yyyy-mm-dd format. |
allocations array(UUID) |
List of allocation_id s in the Nucleus API to select from. As a pre-requisite, must have values for the performance and volatility arguments within the chosen allocation_id . If excluded, the universe defaults to include all available allocations. |
Example Response
{
"securities": [
"AGG",
"VTI"
],
"weights": [
0.5336,
0.4664
],
"ret": 0.061,
"risk": 0.0627
}
RESPONSE
Field | Description |
---|---|
securities |
If allocation_method = create , the tickers of the securities that should be included in the allocation created. |
weights |
If allocation_method = create , the weights of each security that should be included in the allocation created. |
id |
If allocation_method = select , the id of the allocation assigned to the client. |
ret |
The annualized return of the portfolio. |
risk |
The annualized standard deviation of the portfolio. |
NUCLEUS DATA DEPENDENCIES
1. Allocations: POST /allocation
; performance
and volatility
must be set when allocation_method
= select
2. Securities: POST /security
; required if allocation_method
= create
3. Security Prices: POST /security_price
; required if allocation_method
= create
Simulations
Model Backtest
This service simulates the behavior of a model over a specific date range in the past. It supports three types of model rebalancing: period-based, drift-based, and Downside Protection. Period-based rebalancing generates a signal at the beginning of each time period with pre-defined frequency. Drift-based rebalancing generates a signal whenever a model holding deviates from its strategic target by a pre-defined amount. Downside Protection generates signals based on the observed risk of model holdings, reducing exposure in stages as risk increases and restoring exposure in stages as risk decreases. These rebalancing types can be assigned to a model in the Nucleus API Model Service.
HTTP REQUEST
POST /backtest
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"model_id": "9aad12e8-25dc-421d-a041-1b157fff7738",
"start_date": "2016-12-01",
"end_date": "2016-12-05",
"initial_weights": {
"GOOGL": 0.25,
"CSCO": 0.25,
"MCD": 0.25,
"WMT": 0.25
},
"asset_size": 1000,
"asset_sizes": true,
"trades": true,
"holdings": true,
"stats": true
}' "https://api.hydrogenplatform.com/proton/v1/backtest"
ARGUMENTS
Parameter | Description |
---|---|
model_id UUID, required |
Identifier of the model in the Nucleus API to backtest. In order to perform the backtest, downside , drift_rebal or period_rebal must be set in the Nucleus endpoint /model . The drift_factor from /model_holding is used as of the start_date throughout the full simulation. If no drift factor is set in /model_holding , the default_drift_factor from /model is used. If period_rebal , set rebalance_period . If drift_rebal , set default_drift_factor . If downside , set safe_sec and cash_sec . |
start_date date, required |
Start date for analysis, represented in yyyy-mm-dd format. |
end_date date, required |
End date for analysis, represented in yyyy-mm-dd format. |
initial_weights map |
Initial weights for model holdings. If excluded, defaults to the model’s strategic_weight from /model_holding as of the start_date . |
asset_size float |
The initial asset size. If excluded, defaults to 1000 . |
asset_sizes boolean |
If true , show the asset sizes from the backtest. If excluded, defaults to true . |
trades boolean |
If true , show the trades from the backtest. If excluded, defaults to true . |
holdings boolean |
If true , show the holdings from the backtest. If excluded, defaults to true . |
stats boolean |
If true , show risk and return statistics from the backtest. If excluded, defaults to true . |
Example Response
{
"asset_sizes": {
"2016-12-01T00:00:00": 1000,
"2016-12-02T00:00:00": 998.6022625755537,
"2016-12-05T00:00:00": 1004.3918279210744
},
"trades": [
{
"date": "2016-12-05T00:00:00",
"ticker": "GOOGL",
"signal": "SELL",
"amount": 0.00039250387412376186,
"type": 2
},
{
"date": "2016-12-05T00:00:00",
"ticker": "CSCO",
"signal": "BUY",
"amount": 0.0013502458022483788,
"type": 2
},
{
"date": "2016-12-05T00:00:00",
"ticker": "MCD",
"signal": "BUY",
"amount": 0.0001361108332734451,
"type": 2
},
{
"date": "2016-12-05T00:00:00",
"ticker": "WMT",
"signal": "SELL",
"amount": 0.0010938527613980065,
"type": 2
}
],
"holdings": [
{
"date": "2016-12-02T00:00:00",
"tickers": [
"GOOGL",
"CSCO",
"MCD",
"WMT"
],
"weights": [
0.25039250387412376,
0.24864975419775162,
0.24986388916672655,
0.251093852761398
],
"amount": [
250.04252090065808,
248.30220713073004,
249.51464505782053,
250.742889486345
]
},
{
"date": "2016-12-05T00:00:00",
"tickers": [
"GOOGL",
"CSCO",
"MCD",
"WMT"
],
"weights": [
0.2530329073979014,
0.2509383051693015,
0.2507662014695168,
0.24526258596328018
],
"amount": [
254.14418438556214,
252.0403830244111,
251.8675234747924,
246.33973703630863
]
}
],
"stats": {
"cumulative_return": 0.004391827921074398,
"annualized_return": 0.7331968693633459,
"annualized_volatility": 0.08076823639707757
}
}
RESPONSE
Field | Description |
---|---|
asset_sizes |
The asset size per day, beginning on the start_date , for the given time period. |
trades |
Rebalancing signals for the given model. |
date |
The date of the signal. |
ticker |
The ticker of the security. |
signal |
The signal, either BUY or SELL. |
amount |
The amount of the trade. |
type |
The type of trade signal. 1 = period-based, 2 = drift-based, and 4 = downside protection. |
holdings |
The model’s composition by date. |
date |
The date for the holding details. |
tickers |
The tickers of the holdings. |
weights |
The weights of the holdings, represented on a percentage basis. |
amount |
The total value for each security. |
stats |
Model metrics for the duration of the backtest. |
cumulative_return |
The cumulative return. |
annualized_return |
The annualized return. |
annualized_volatility |
The annualized standard deviation of returns. |
NUCLEUS DATA DEPENDENCIES
1. Models: POST /model
2. Model Holdings: POST /model_holding
(model holdings are only required for the starting date of the backtest simulation)
3. Securities: POST /security
4. Security Prices: POST /security_price
Event Study
When clients are weighing their options between portfolios, they can run a simulation to see how the portfolio would have performed during key historical events. This will help them understand a portfolio’s exposure to various financial climates. The resulting performance and risk statistics can serve as a basis to evaluate a portfolio in the context of a given event.
The events
parameter accepts the following event labels, each corresponding to a particular date range:
dot_com_bubble
: (5/14/2001 - 9/30/2002)2008_financial_crisis
: (10/8/2007 - 03/02/2009)brexit
: (6/23/2016 - 6/27/2016)2011_black_monday
: (7/21/2011 - 8/10/2011)september_eleventh
: (9/10/2001 - 9/21/2001)1987_black_monday
: (10/5/1987 - 10/19/1987)1992_black_wednesday
: (9/14/1992 - 10/9/1992)1997_asian_financial_crisis
: (10/21/1997 - 10/27/1997)
HTTP REQUEST
POST /event_study
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"portfolio_tickers": [
"CVX",
"PFE",
"JNJ"
],
"portfolio_weights": [
0.3,
0.4,
0.3
],
"events": [
"2008_financial_crisis"
]
}' "https://api.hydrogenplatform.com/proton/v1/event_study"
ARGUMENTS
Parameter | Description |
---|---|
portfolio_tickers array, required |
A list of tickers for securities included in the portfolio, referencing securities defined in the Nucleus API. |
portfolio_weights array, required |
Weights of the securities in the portfolio. Must add up to 1 . |
events array |
Historical events to analyze. Each item must be one of: dot_com_bubble , 2008_financial_crisis , brexit , 2011_black_monday , september_eleventh , 1987_black_monday , 1992_black_wednesday , 1997_asian_financial_crisis . Defaults to all available events. |
Example Response
{
"event_summary": [
{
"event_name": "2008_financial_crisis",
"stats": {
"cumulative_return": -0.4068333255300416,
"annualized_return": -0.310936012869381,
"annualized_volatility": 0.3384477617390186
}
}
]
}
RESPONSE
Field | Description |
---|---|
event_summary |
Summary statistics for the events analyzed. Each underlying object contains the fields shown below. |
event_name |
Label for the event, as provided in events . |
stats |
Portfolio statistics for the duration of the event indicated by event_name . |
cumlative_return |
Cumulative return over the event duration. |
annualized_return |
Annualized return over the event duration. |
annualized_volatility |
Annualized standard deviation over the event duration. |
NUCLEUS DATA DEPENDENCIES
1. Securities: POST /security
2. Security Prices: POST /security_price
Monte Carlo
This service extrapolates the future value of a hypothetical investment account via a random walk Monte Carlo. Future values are approximated by simulating individual periods of portfolio growth based on samples derived from the given historical performance and volatility portfolio attributes, in conjunction with ongoing cash inflows or outflows (which occur at the end of each period) in the simulated account. The return samples are stochastic; they assume portfolio returns are distributed normally, and are chained together in a random walk sequence.
HTTP REQUEST
POST /monte_carlo
Example Request
curl -X POST -H "Authorization: Bearer a771cd86-361b-4bef-9fbd-882922fae346" \
-H "Content-Type: application/json" \
-d '{
"n": 5,
"mu": [0.06],
"sigma": [0.06],
"cf": [[100,3]],
"ret_mod": [0],
"init_bal": 1000,
"result_type": "raw",
"remove_outliers": false
}' "https://api.hydrogenplatform.com/proton/v1/monte_carlo"
ARGUMENTS
Parameter | Description |
---|---|
cf array, required |
The cash flows to occur during the simulation. This parameter is an array containing sub-arrays with 2 elements. The first element of each sub-array is a cash flow amount, and the second is a time period duration. Example: [[100.00,10], [250.00,15]] . This example indicates cash flows of 100.00 will take place for 10 consecutive time periods, followed by cash flows of 250 for 15 periods (for a total of 25 time periods). Cash flows of 0 must be defined explicitly. |
mu array, required |
The periodic mean portfolio return. The length of the array must be less than or equal to the number of time periods present in cf . If it is less, values will be conformed to the number of time periods. For example, [0.04, 0.06] would result in an implied mu of [0.04, 0.04, 0.06, 0.06] for a simulation that spans four time periods. |
sigma array, required |
The periodic portfolio standard deviation. The length of the array must be less than or equal to the number of time periods present in cf If it is less, values will be conformed to the number of time periods. Values must be greater than 0. |
ret_mod array |
A periodic return modifier. Use this value to adjust the randomly generated return for each period of the simulation on an absolute basis. For example, to reflect a fee of 1% taken out each period, use [-0.01] . If excluded, defaults to [0] . |
init_bal integer |
The initial investment at time zero. If excluded, defaults to 100 . |
n integer |
The number of simulations to run. Larger values will increase the execution time of the service. The maximum acceptable value is 10000 . If excluded, defaults to 1000 . |
remove_outliers boolean |
If true , remove outlying results. If true , outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 threshold. If excluded, defaults to false . |
result_type string |
The type of simulation results to display in the output. Value may be raw , mean , median , percentiles , or custom . raw returns all simulation results; mean returns the average simulation result; median returns the median simulation result; percentiles return the 10th, 20th, 30th, 40th, 50th, 60th, 70th, 80th, and 90th percentile simulation results; custom returns results for the percentile(s) defined in p . For example, [30, 50, 70] would return the 30th, 50th, and 70th percentiles. If excluded, defaults to raw . |
p array |
Custom result percentile(s). If excluded, defaults to [50] . |
Example Response
{
"sims": [
[
1000,
1090.874868998463,
1303.8267202482432,
1367.7724868494115
],
[
1000,
1157.704933755286,
1383.2549423200296,
1570.2679896586226
],
[
1000,
1105.6950123839047,
1329.867596314487,
1500.5911768880942
],
[
1000,
1206.739074646278,
1336.2530298473926,
1418.8009611252592
],
[
1000,
1250.0493618204787,
1406.3931638747138,
1603.5918233043417
]
]
}
RESPONSE
Field | Description |
---|---|
sims |
A collection of Monte Carlo results. If result_type = raw , this returns multiple sets of results, defined by n . |
Savings Calculator
While more detail is usually welcomed by financial professionals, some firms opt to provide simple calculators for simple savings or investing products. This endpoint provides a calculator that can show a simple growth of investment over time. After providing return, deposit, and balance information, the calculator returns an ending balance and simulation details. Earnings are calculated at the beginning of each period, before deposits for that period are considered. Tax rates, if provided, are applied in the return calculation. Returns are calculated at the same frequency stipulated in horizon_frequency_interval
.
HTTP REQUEST
POST /savings_calculator
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"initial_balance": 10000,
"horizon": 5,
"return_schedule": [0.02, 0.025, 0.025, 0.025, 0.03],
"horizon_frequency_interval": "year",
"deposit_schedule":
[
{
"deposit_amount": 100,
"deposit_frequency_interval": "month",
"deposit_duration": 120,
"adjust_deposit_for_inflation": true
},
{
"deposit_amount": 2000,
"deposit_frequency_interval": "year",
"deposit_duration": 10,
"adjust_deposit_for_inflation": true
}
],
"tax_rate": 0.33,
"inflation_rate": 0.02
}' "https://api.hydrogenplatform.com/proton/v1/savings_calculator"
ARGUMENTS
Parameter | Description |
---|---|
initial_balance float, required |
The initial balance of the investment. |
horizon integer, required |
The number of intervals defined in horizon_frequency_interval . |
return_schedule array, required |
The return schedule for the given horizon . The number of entries in the array must be 1 or must match the number of intervals indicated in horizon . |
horizon_frequency_interval string |
The frequency interval for the horizon . The value may be one of the following: year , quarter , month , or week . If excluded, defaults to year . |
deposit_schedule array(map) |
Details on the deposit plan. If excluded, no deposits are included in the calculation. |
deposit_amount float |
The amount deposited in a given period and frequency. If excluded, defaults to 0 . |
deposit_frequency_interval string |
The period interval to be used in relation to deposit_duration . The value may be one of the following: year , quarter , month , week . If excluded, defaults to year . |
deposit_duration string |
The amount of intervals for the time period. If excluded, defaults to the number of intervals given in horizon . |
adjust_deposit_for_inflation boolean |
If true , adjusts the deposit using the inflation_rate . If excluded, defaults to true . |
tax_rate float |
The tax rate to be applied to investment earnings. If excluded, defaults to 0 . |
inflation_rate float |
The annualized inflation rate. If excluded, defaults to 0 . |
Example Response
{
"ending_balance": 28120.1,
"return_details": {
"0": {
"period_earnings": 0,
"period_contribution": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"ending_balance": 10000
},
"1": {
"period_earnings": 134,
"period_contribution": 3200,
"period_withdrawal": 0,
"cumulative_earnings": 134,
"cumulative_contributions": 3200,
"cumulative_withdrawals": 0,
"ending_balance": 13334
},
"2": {
"period_earnings": 223.34,
"period_contribution": 3264,
"period_withdrawal": 0,
"cumulative_earnings": 357.34,
"cumulative_contributions": 6464,
"cumulative_withdrawals": 0,
"ending_balance": 16821.34
},
"3": {
"period_earnings": 281.76,
"period_contribution": 3329.28,
"period_withdrawal": 0,
"cumulative_earnings": 639.1,
"cumulative_contributions": 9793.28,
"cumulative_withdrawals": 0,
"ending_balance": 20432.38
},
"4": {
"period_earnings": 342.24,
"period_contribution": 3395.87,
"period_withdrawal": 0,
"cumulative_earnings": 981.34,
"cumulative_contributions": 13189.15,
"cumulative_withdrawals": 0,
"ending_balance": 24170.49
},
"5": {
"period_earnings": 485.83,
"period_contribution": 3463.78,
"period_withdrawal": 0,
"cumulative_earnings": 1467.17,
"cumulative_contributions": 16652.93,
"cumulative_withdrawals": 0,
"ending_balance": 28120.1
}
}
}
RESPONSE
Field | Description |
---|---|
ending_balance |
The ending balance of the investment, represented in future dollars. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_contribution |
The deposit made for this period. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Insurance
Annuities
Annuity Calculator
When planning for retirement or other financial outcomes, a fixed annuity allows an investor to receive a series of payments over a given period of time in the future. This tool analyzes fixed annuities and solves for a variety of relevant variables including the annuity amount, the investor’s initial balance, ongoing contributions to the annuity, the accumulation horizon, and the decumulation horizon.
Annuity Amount
This service helps determine the annuity amount that is attainable based on the details provided.
HTTP REQUEST
POST /annuity_calculator/annuity_amount
Example Request
curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
-H "Content-Type: application/json" \
-d '{
"portfolio_return": 0.1,
"initial_balance": 2000,
"accumulation_horizon": 3,
"decumulation_horizon": 2,
"annuity_frequency_interval": "year",
"inflation_rate": 0.02,
"tax_rate": 0.25,
"deposit_schedule": {
"deposit_amount": 500,
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
}
}' "https://api.hydrogenplatform.com/proton/v1/annuity_calculator/annuity_amount"
ARGUMENTS
Parameter | Description |
---|---|
portfolio_return float, required |
The annualized rate of return of the portfolio. |
initial_balance float, required |
The starting balance in the annuity plan, prior to any periodic contributions. |
accumulation_horizon integer, required |
The number of years until the commencement of annuity payments. |
decumulation_horizon integer, required |
The number of years that annuity payments last. |
annuity_frequency_interval string |
The period interval that relates to annuity_amount . Must be one of the following: year , quarter , month , week . Defaults to year . |
inflation_rate float |
The annualized inflation rate to apply to portfolio_return . Defaults to 0 . |
tax_rate float |
The tax rate to apply to annuity_amount . Defaults to 0 . |
deposit_schedule map |
The schedule of deposits to be made during the accumulation_horizon . Includes the fields shown below. |
deposit_amount string |
The amount deposited per a given period and number of intervals. Deposits are assumed to end at the end of the accumulation_horizon . Defaults to 0 . |
deposit_frequency_interval string |
The period interval to be used in relation to the deposit_amount . Defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposit_amount will be increased by inflation_rate . Defaults to true . |
Example Response
{
"annuity_amount": 1753.96,
"annuity_frequency_interval": "year",
"cumulative_annuity_amount": 5013.15,
"return_details": {
"0": {
"period_contribution": 0,
"cumulative_contributions": 0,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 0,
"cumulative_earnings": 0,
"ending_balance": 2000
},
"1": {
"period_contribution": 500,
"cumulative_contributions": 500,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 200,
"cumulative_earnings": 200,
"ending_balance": 2700
},
"2": {
"period_contribution": 510,
"cumulative_contributions": 1010,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 270,
"cumulative_earnings": 470,
"ending_balance": 3480
},
"3": {
"period_contribution": 520.2,
"cumulative_contributions": 1530.2,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 348,
"cumulative_earnings": 818,
"ending_balance": 4348.2
},
"4": {
"period_contribution": 0,
"cumulative_contributions": 1530.2,
"period_withdrawal": 2481.76,
"cumulative_withdrawals": 2481.76,
"period_tax": 827.25,
"cumulative_tax": 827.25,
"period_earnings": 434.82,
"cumulative_earnings": 1252.82,
"ending_balance": 2301.26
},
"5": {
"period_contribution": 0,
"cumulative_contributions": 1530.2,
"period_withdrawal": 2531.39,
"cumulative_withdrawals": 5013.15,
"period_tax": 843.8,
"cumulative_tax": 1671.05,
"period_earnings": 230.13,
"cumulative_earnings": 1482.95,
"ending_balance": 0
}
}
}
RESPONSE
Field | Description |
---|---|
annuity_amount |
The periodic annuity amount. |
annuity_frequency_interval |
The frequency at which annuity_amount is drawn from the portfolio. |
cumulative_annuity_amount |
The total amount received from the annuity over the course of the plan. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_contribution |
The deposit made for this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
period_tax |
The tax amount for this period. |
cumulative_tax |
The cumulative taxes up to and including this period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions are made. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Initial Balance
This service helps determine the initial balance that an investor needs in order to satisfy the annuity details provided.
HTTP REQUEST
POST /annuity_calculator/initial_balance
Example Request
curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
-H "Content-Type: application/json" \
-d '{
"portfolio_return": 0.1,
"accumulation_horizon": 3,
"decumulation_horizon": 2,
"annuity_amount": 3000,
"annuity_frequency_interval": "year",
"inflation_rate": 0.02,
"tax_rate": 0.25,
"deposit_schedule": {
"deposit_amount": 500,
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
}
}' "https://api.hydrogenplatform.com/proton/v1/annuity_calculator/initial_balance"
ARGUMENTS
Parameter | Description |
---|---|
portfolio_return float, required |
The annualized rate of return of the portfolio. |
accumulation_horizon integer, required |
The number of years until the commencement of annuity payments. |
decumulation_horizon integer, required |
The number of years that annuity payments last. |
annuity_amount float, required |
The amount of the annuity, represented in today’s dollars. |
annuity_frequency_interval string |
The period interval that relates to annuity_amount . Must be one of the following: year , quarter , month , week . Defaults to year . |
inflation_rate float |
The annualized inflation rate to apply to portfolio_return . Defaults to 0 . |
tax_rate float |
The tax rate to apply to annuity_amount . Defaults to 0 . |
deposit_schedule map |
The schedule of deposits to be made during the accumulation_horizon . Includes the fields shown below. |
deposit_amount string |
The amount deposited per a given period and number of intervals. Deposits are assumed to end at the end of the accumulation_horizon . Defaults to 0 . |
deposit_frequency_interval string |
The period interval to be used in relation to the deposit_amount . Defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposit_amount will be increased by inflation_rate . Defaults to true . |
Example Response
{
"initial_balance": 4320.83,
"cumulative_annuity_amount": 8574.56,
"return_details": {
"0": {
"period_contribution": 0,
"cumulative_contributions": 0,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 0,
"cumulative_earnings": 0,
"ending_balance": 4320.83
},
"1": {
"period_contribution": 500,
"cumulative_contributions": 500,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 432.08,
"cumulative_earnings": 432.08,
"ending_balance": 5252.91
},
"2": {
"period_contribution": 510,
"cumulative_contributions": 1010,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 525.29,
"cumulative_earnings": 957.37,
"ending_balance": 6288.21
},
"3": {
"period_contribution": 520.2,
"cumulative_contributions": 1530.2,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 628.82,
"cumulative_earnings": 1586.2,
"ending_balance": 7437.23
},
"4": {
"period_contribution": 0,
"cumulative_contributions": 1530.2,
"period_withdrawal": 4244.83,
"cumulative_withdrawals": 4244.83,
"period_tax": 1414.94,
"cumulative_tax": 1414.94,
"period_earnings": 743.72,
"cumulative_earnings": 2329.92,
"ending_balance": 3936.12
},
"5": {
"period_contribution": 0,
"cumulative_contributions": 1530.2,
"period_withdrawal": 4329.73,
"cumulative_withdrawals": 8574.56,
"period_tax": 1443.24,
"cumulative_tax": 2858.19,
"period_earnings": 393.61,
"cumulative_earnings": 2723.53,
"ending_balance": 0
}
}
}
RESPONSE
Field | Description |
---|---|
initial_balance |
The starting balance in the annuity plan, prior to any periodic contributions. |
cumulative_annuity_amount |
The total amount received from the annuity over the course of the plan. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_contribution |
The deposit made for this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
period_tax |
The tax amount for this period. |
cumulative_tax |
The cumulative taxes up to and including this period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions are made. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Deposit Amount
This service helps determine the recurring amount to be contributed over the accumulation horizon, in order to satisfy the annuity details provided.
HTTP REQUEST
POST /annuity_calculator/deposit_amount
Example Request
curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
-H "Content-Type: application/json" \
-d '{
"portfolio_return": 0.1,
"initial_balance": 2000,
"accumulation_horizon": 3,
"decumulation_horizon": 2,
"annuity_amount": 3000,
"annuity_frequency_interval": "year",
"inflation_rate": 0.02,
"tax_rate": 0.25
}' "https://api.hydrogenplatform.com/proton/v1/annuity_calculator/deposit_amount"
ARGUMENTS
Parameter | Description |
---|---|
portfolio_return float, required |
The annualized rate of return of the portfolio. |
initial_balance float, required |
The starting balance in the annuity plan, prior to any periodic contributions. |
accumulation_horizon integer, required |
The number of years until the commencement of annuity payments. |
decumulation_horizon integer, required |
The number of years that annuity payments last. |
annuity_amount float, required |
The amount of the annuity, represented in today’s dollars. |
annuity_frequency_interval string |
The period interval that relates to annuity_amount . Must be one of the following: year , quarter , month , week . Defaults to year . |
inflation_rate float |
The annualized inflation rate to apply to portfolio_return . Defaults to 0 . |
tax_rate float |
The tax rate to apply to annuity_amount . Defaults to 0 . |
Example Response
{
"deposit_amount": 1415.9726942384018,
"deposit_frequency_interval": "year",
"cumulative_annuity_amount": 8574.56,
"return_details": {
"0": {
"period_contribution": 0,
"cumulative_contributions": 0,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 0,
"cumulative_earnings": 0,
"ending_balance": 2000
},
"1": {
"period_contribution": 1415.97,
"cumulative_contributions": 1415.97,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 200,
"cumulative_earnings": 200,
"ending_balance": 3615.97
},
"2": {
"period_contribution": 1444.29,
"cumulative_contributions": 2860.26,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 361.6,
"cumulative_earnings": 561.6,
"ending_balance": 5421.86
},
"3": {
"period_contribution": 1473.18,
"cumulative_contributions": 4333.44,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 542.19,
"cumulative_earnings": 1103.78,
"ending_balance": 7437.23
},
"4": {
"period_contribution": 0,
"cumulative_contributions": 4333.44,
"period_withdrawal": 4244.83,
"cumulative_withdrawals": 4244.83,
"period_tax": 1414.94,
"cumulative_tax": 1414.94,
"period_earnings": 743.72,
"cumulative_earnings": 1847.51,
"ending_balance": 3936.12
},
"5": {
"period_contribution": 0,
"cumulative_contributions": 4333.44,
"period_withdrawal": 4329.73,
"cumulative_withdrawals": 8574.56,
"period_tax": 1443.24,
"cumulative_tax": 2858.19,
"period_earnings": 393.61,
"cumulative_earnings": 2241.12,
"ending_balance": 0
}
}
}
RESPONSE
Field | Description |
---|---|
deposit_amount |
The amount to be deposited per period. |
deposit_frequency_interval |
The period interval to be used in relation to the deposit_amount . Defaults to year . |
cumulative_annuity_amount |
The total amount received from the annuity over the course of the plan. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_contribution |
The deposit made for this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
period_tax |
The tax amount for this period. |
cumulative_tax |
The cumulative taxes up to and including this period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions are made. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Decumulation Horizon
This service helps determine the time horizon over which an annuity can persist, based on the details provided.
HTTP REQUEST
POST /annuity_calculator/decumulation_horizon
Example Request
curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
-H "Content-Type: application/json" \
-d '{
"portfolio_return": 0.1,
"initial_balance": 2000,
"accumulation_horizon": 3,
"annuity_amount": 3000,
"annuity_frequency_interval": "year",
"inflation_rate": 0.02,
"tax_rate": 0.25,
"deposit_schedule": {
"deposit_amount": 500,
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
}
}' "https://api.hydrogenplatform.com/proton/v1/annuity_calculator/decumulation_horizon"
ARGUMENTS
Parameter | Description |
---|---|
portfolio_return float, required |
The annualized rate of return of the portfolio. |
initial_balance float, required |
The starting balance in the annuity plan, prior to any periodic contributions. |
accumulation_horizon integer, required |
The number of years until the commencement of annuity payments. |
annuity_amount float, required |
The amount of the annuity, represented in today’s dollars. |
annuity_frequency_interval string |
The period interval that relates to annuity_amount . Must be one of the following: year , quarter , month , week . Defaults to year . |
inflation_rate float |
The annualized inflation rate to apply to portfolio_return . Defaults to 0 . |
tax_rate float |
The tax rate to apply to annuity_amount . Defaults to 0 . |
deposit_schedule map |
The schedule of deposits to be made during the accumulation_horizon . Includes the fields shown below. |
deposit_amount string |
The amount deposited per a given period and number of intervals. Deposits are assumed to end at the end of the accumulation_horizon . Defaults to 0 . |
deposit_frequency_interval string |
The period interval to be used in relation to the deposit_amount . Defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposit_amount will be increased by inflation_rate . Defaults to true . |
Example Response
{
"decumulation_horizon": {
"years": 1,
"months": 1,
"days": 12
},
"cumulative_annuity_amount": 4790.14,
"return_details": {
"0": {
"period_contribution": 0,
"cumulative_contributions": 0,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 0,
"cumulative_earnings": 0,
"ending_balance": 2000
},
"1": {
"period_contribution": 500,
"cumulative_contributions": 500,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 200,
"cumulative_earnings": 200,
"ending_balance": 2700
},
"2": {
"period_contribution": 510,
"cumulative_contributions": 1010,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 270,
"cumulative_earnings": 470,
"ending_balance": 3480
},
"3": {
"period_contribution": 520.2,
"cumulative_contributions": 1530.2,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 348,
"cumulative_earnings": 818,
"ending_balance": 4348.2
},
"4": {
"period_contribution": 0,
"cumulative_contributions": 1530.2,
"period_withdrawal": 4244.83,
"cumulative_withdrawals": 4244.83,
"period_tax": 1414.94,
"cumulative_tax": 1414.94,
"period_earnings": 434.82,
"cumulative_earnings": 1252.82,
"ending_balance": 538.19
},
"5": {
"period_contribution": 0,
"cumulative_contributions": 1530.2,
"period_withdrawal": 545.31,
"cumulative_withdrawals": 4790.14,
"period_tax": 181.77,
"cumulative_tax": 1596.71,
"period_earnings": 7.12,
"cumulative_earnings": 1259.94,
"ending_balance": 0
}
}
}
RESPONSE
Field | Description |
---|---|
decumulation_horizon |
The time horizon over which annuity payments persist. |
years |
The number of years in the decumulation horizon. |
months |
The number of months in the decumulation horizon. |
days |
The number of days in the decumulation horizon. |
cumulative_annuity_amount |
The total amount received from the annuity over the course of the plan. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_contribution |
The deposit made for this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
period_tax |
The tax amount for this period. |
cumulative_tax |
The cumulative taxes up to and including this period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions are made. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Accumulation Horizon
This services helps determine the accumulation horizon (i.e. the time period until annuity payments begin) that is needed in order to satisfy the annuity details provided.
HTTP REQUEST
POST /annuity_calculator/accumulation_horizon
Example Request
curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
-H "Content-Type: application/json" \
-d '{
"portfolio_return": 0.1,
"initial_balance": 2000,
"decumulation_horizon": 2,
"annuity_amount": 3000,
"annuity_frequency_interval": "year",
"inflation_rate": 0.02,
"tax_rate": 0.25,
"deposit_schedule": {
"deposit_amount": 500,
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
}
}' "https://api.hydrogenplatform.com/proton/v1/annuity_calculator/accumulation_horizon"
ARGUMENTS
Parameter | Description |
---|---|
portfolio_return float, required |
The annualized rate of return of the portfolio. |
initial_balance float, required |
The starting balance in the annuity plan, prior to any periodic contributions. |
decumulation_horizon integer, required |
The number of years that annuity payments last. |
annuity_amount float, required |
The amount of the annuity, represented in today’s dollars. |
annuity_frequency_interval string |
The period interval that relates to annuity_amount . Must be one of the following: year , quarter , month , week . Defaults to year . |
inflation_rate float |
The annualized inflation rate to apply to portfolio_return . Defaults to 0 . |
tax_rate float |
The tax rate to apply to annuity_amount . Defaults to 0 . |
deposit_schedule map |
The schedule of deposits to be made during the accumulation_horizon . Includes the fields shown below. |
deposit_amount string |
The amount deposited per a given period & number of intervals. Deposits are assumed to end at the end of the accumulation_horizon . Defaults to 0 . |
deposit_frequency_interval string |
The period interval to be used in relation to the deposit_amount . Defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposit_amount will be increased by inflation_rate . Defaults to true . |
Example Response
{
"accumulation_horizon": {
"years": 6,
"months": 0,
"days": 0
},
"cumulative_annuity_amount": 9100.11,
"return_details": {
"0": {
"period_contribution": 0,
"cumulative_contributions": 0,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 0,
"cumulative_earnings": 0,
"ending_balance": 2000
},
"1": {
"period_contribution": 500,
"cumulative_contributions": 500,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 200,
"cumulative_earnings": 200,
"ending_balance": 2700
},
"2": {
"period_contribution": 510,
"cumulative_contributions": 1010,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 270,
"cumulative_earnings": 470,
"ending_balance": 3480
},
"3": {
"period_contribution": 520.2,
"cumulative_contributions": 1530.2,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 348,
"cumulative_earnings": 818,
"ending_balance": 4348.2
},
"4": {
"period_contribution": 530.6,
"cumulative_contributions": 2060.8,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 434.82,
"cumulative_earnings": 1252.82,
"ending_balance": 5313.62
},
"5": {
"period_contribution": 541.22,
"cumulative_contributions": 2602.02,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 531.36,
"cumulative_earnings": 1784.18,
"ending_balance": 6386.2
},
"6": {
"period_contribution": 552.04,
"cumulative_contributions": 3154.06,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 638.62,
"cumulative_earnings": 2422.8,
"ending_balance": 7576.86
},
"7": {
"period_contribution": 313.19,
"cumulative_contributions": 3467.25,
"period_withdrawal": 0,
"cumulative_withdrawals": 0,
"period_tax": 0,
"cumulative_tax": 0,
"period_earnings": 3.01,
"cumulative_earnings": 2425.81,
"ending_balance": 7893.06
},
"8": {
"period_contribution": 0,
"cumulative_contributions": 3467.25,
"period_withdrawal": 4505,
"cumulative_withdrawals": 4505,
"period_tax": 1501.67,
"cumulative_tax": 1501.67,
"period_earnings": 789.31,
"cumulative_earnings": 3215.12,
"ending_balance": 4177.37
},
"9": {
"period_contribution": 0,
"cumulative_contributions": 3467.25,
"period_withdrawal": 4595.1,
"cumulative_withdrawals": 9100.11,
"period_tax": 1531.7,
"cumulative_tax": 3033.37,
"period_earnings": 417.74,
"cumulative_earnings": 3632.85,
"ending_balance": 0
}
}
}
RESPONSE
Field | Description |
---|---|
accumulation_horizon |
The time horizon until the commencement of annuity payments. |
years |
The number of years in the accumulation horizon. |
months |
The number of months in the accumulation horizon. |
days |
The number of days in the accumulation horizon. |
cumulative_annuity_amount |
The total amount received from the annuity over the course of the plan. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_contribution |
The deposit made for this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
period_tax |
The tax amount for this period. |
cumulative_tax |
The cumulative taxes up to and including this period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions are made. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Life Insurance
Life Insurance Needs Calculator
When deciding to purchase life insurance, users face a common question: how much life insurance do I need? While some in the industry rely on broad rules of thumb (such as a multiple of household income), this calculator uses a discounted cash flow approach. Once the user provides expense and other pertinent information, the calculator returns the life insurance need, a breakdown of expenses by category, and return details broken down by period.
HTTP REQUEST
POST /life_insurance/needs_calculator
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"mortgage_balance": 200000,
"other_debt": 100000,
"interest_rate": 0.06,
"end_of_life_expenses": 10000,
"existing_life_insurance": 50000,
"liquid_assets": 400000,
"general_inflation_rate": 0.02,
"education_inflation_rate": 0.05,
"tax_rate": 0.25,
"benefit_amount_rounding": 6,
"margin_of_error": 0.05,
"children_education_config":
[
{
"current_age": 17,
"education_config":
[
{
"start_age": 18,
"end_age": 22,
"total_annual_cost": 40000
}
]
}
],
"income_config":
[
{
"annual_net_take_home_pay": 50000,
"percentage_of_income_covered": 1,
"income_benefit_duration": 5
}
],
"beneficiary_bequest_config":
[
{
"years_until_bequest": 1,
"bequest_amount": 10000,
"bequest_duration": 5
}
]
}' "https://api.hydrogenplatform.com/proton/v1/life_insurance/needs_calculator"
ARGUMENTS
Parameter | Description |
---|---|
mortgage_balance float, required |
The user’s outstanding mortgage balance. |
other_debt integer, required |
Other outstanding debt. |
interest_rate float, required |
The annual interest rate earned once the benefit amount is received. |
end_of_life_expenses float |
Burial, funeral, and other end-of-life expenses to be paid at the first period. If excluded, defaults to 0 . |
existing_life_insurance float |
Existing life insurance currently held by the insuree. If excluded, defaults to 0 . |
liquid_assets float |
Current liquid assets owned by the insuree and beneficiary. If excluded, defaults to 0 . |
general_inflation_rate float |
The inflation rate to be applied to the benefit_amount and annual_net_take_home_pay . If excluded, defaults to 0 . |
education_inflation_rate float |
The inflation rate to be applied to all tuition. If excluded, defaults to 0 . |
tax_rate float |
The tax rate to be applied to investment earnings from the interest_rate . Life insurance benefits are assumed to be tax-free. If excluded, defaults to 0 . |
benefit_amount_rounding integer |
A parameter to round the benefit amount up to a configurable number of digits. This parameter should be utilized if a firm will not underwrite exact life insurance amounts, but will round to the nearest amount. 0 : round to the hundredth, 1 : round to the tenth, 2 : round to a single digit, 3 : round to two digits, etc. If excluded, defaults to 0 . |
margin_of_error float |
The margin of error to apply to the life insurance needed, before rounding. A margin_of_error of 0.10 would return 110% of the total insurance needed. If excluded, defaults to 0 . |
children_education_config map |
Benefit information to provide for a child’s primary, secondary and college education. |
current_age integer, required |
The child’s age as of the first period. |
education_config map, required |
A configuration of the child’s education cost. |
start_age integer, required |
The child’s age at the beginning of the first education year. |
end_age integer, required |
The child’s age at the beginning of the last education year. |
total_annual_cost float, required |
The total annual cost of the child’s education. |
income_config map |
Information on replacement income for beneficiaries. Income is assumed to increase with the rate of inflation. |
annual_net_take_home_pay float, required |
The policy owner’s annual after-tax income. |
percentage_of_income_covered float |
The percentage of annual_net_take_home_pay needed by beneficiaries. If excluded, defaults to 1 . |
income_benefit_duration float |
The number of years needed to provide replacement income to beneficiaries, starting at the first period. If excluded, defaults to 10 . |
beneficiary_bequest_config map |
Information on additional benefits needed by beneficiaries. |
bequest_amount float, required |
The amount of the benefit, paid annually. |
years_until_bequest integer |
The number of years until the benefit is needed. A value of 0 indicates the benefit would be needed immediately (the first period). If excluded, defaults to 0 . |
bequest_duration integer |
The amount of years to repeat the benefit_amount . If excluded, defaults to 10 . |
Example Response
{
"life_insurance_needed": 370000,
"total_life_insurance_needed": 420000,
"life_insurance_needs_breakdown": {
"mortgage": 200000,
"other": 100000,
"education": 202889.19,
"income_replacement": 238321.04,
"beneficiary_bequest": 46523.92,
"end_of_life": 10000
},
"return_details": {
"0": {
"period_earnings": 0,
"period_withdrawal": 0,
"cumulative_earnings": 0,
"cumulative_withdrawals": 0,
"ending_balance": 820000
},
"1": {
"period_earnings": 0,
"period_withdrawal": 360000,
"cumulative_earnings": 0,
"cumulative_withdrawals": 360000,
"ending_balance": 460000
},
"2": {
"period_earnings": 20700,
"period_withdrawal": 103200,
"cumulative_earnings": 20700,
"cumulative_withdrawals": 463200,
"ending_balance": 377500
},
"3": {
"period_earnings": 16987.5,
"period_withdrawal": 106524,
"cumulative_earnings": 37687.5,
"cumulative_withdrawals": 569724,
"ending_balance": 287963.5
},
"4": {
"period_earnings": 12958.36,
"period_withdrawal": 109977.48,
"cumulative_earnings": 50645.86,
"cumulative_withdrawals": 679701.48,
"ending_balance": 190944.38
},
"5": {
"period_earnings": 8592.5,
"period_withdrawal": 113566.18,
"cumulative_earnings": 59238.35,
"cumulative_withdrawals": 793267.66,
"ending_balance": 85970.69
},
"6": {
"period_earnings": 3868.68,
"period_withdrawal": 62092.07,
"cumulative_earnings": 63107.04,
"cumulative_withdrawals": 855359.73,
"ending_balance": 27747.31
}
}
}
RESPONSE
Field | Description |
---|---|
life_insurance_needed |
The supplemental life insurance needed by the user. |
total_life_insurance_needed |
The total life insurance needed by the user, including the current life insurance. |
life_insurance_needs_breakdown |
A breakdown of what the life insurance proceeds will be used for. |
mortgage |
Insurance required to cover existing mortgage balance, paid immediately. |
other |
Insurance required to cover other debt. |
education |
Insurance required to cover future education expenses. |
income_replacement |
Insurance required to cover loss of income. |
beneficiary_bequest |
Insurance required to cover amount being bequested. |
end_of_life |
Insurance required to cover end of life expenses. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_withdrawal |
The withdrawal made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Wellness
Financial Planning
Education Planning Calculator
When planning for a future education expense, users face common questions when deciding where or when to attend. This tool helps in the decision process with three different endpoints to solve for the following parameters: deposit amount, percent of costs covered, and total annual cost. With these calculators, the user will be able to determine how much needs to be saved to attend a particular school, or what schools would be affordable given their financial circumstances. For all calculators, deposits are assumed to continue through the decumulation phase.
Deposit Amount
A calculator to help plan for an education goal by showing the user the amount that needs to be deposited for a given period.
HTTP REQUEST
POST /education_calculator/deposit_amount
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"initial_balance": 5000,
"accumulation_horizon": 3,
"decumulation_horizon": 4,
"total_annual_cost": 40000,
"portfolio_return": 0.06,
"percent_of_costs_covered": 0.78,
"education_inflation_rate": 0.05,
"general_inflation_rate": 0.02,
"tax_rate": 0.33,
"deposit_schedule": {
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
}
}' "https://api.hydrogenplatform.com/proton/v1/education_calculator/deposit_amount"
ARGUMENTS
Parameter | Description |
---|---|
initial_balance float, required |
The amount currently saved for the education goal. |
accumulation_horizon integer, required |
The amount of years until funds are needed to pay for an education expense. |
decumulation_horizon integer, required |
The number of years to pay the total_annual_cost . |
total_annual_cost float, required |
The total cost paid per year for the education goal, represented in today’s dollars. |
portfolio_return float, required |
The portfolio return for the length of the accumulation_horizon and decumulation_horizon . |
percent_of_costs_covered float |
The percentage of total_annual_cost to be paid for. If excluded, defaults to 1 . |
education_inflation_rate float |
The inflation rate attributed to total_annual_cost . If excluded, defaults to 0.05 . |
general_inflation_rate float |
The rate used to increase deposits for inflation. If excluded, defaults to 0.02 . |
tax_rate float |
The tax rate to apply to investments upon removal from the portfolio. If excluded, defaults to 0 . |
deposit_schedule map |
The deposit schedule for the education goal. |
deposit_frequency_interval string |
The period interval to be used in relation to the deposit_amount . The value may be one of the following: year , quarter , month , or week . If excluded, defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposits should be increased over time with the rate of inflation. If excluded, defaults to true . |
Example Response
{
"deposit_amount": 29114.25,
"deposit_frequency_interval": "year",
"total_cost": 109515.72099999998,
"return_details": {
"0": {
"period_earnings": 0,
"period_contribution": 0,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 0,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 5000
},
"1": {
"period_earnings": 300,
"period_contribution": 29114.25,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 300,
"cumulative_contributions": 29114.25,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 34414.25
},
"2": {
"period_earnings": 2064.86,
"period_contribution": 29696.54,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 2364.86,
"cumulative_contributions": 58810.79,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 66175.64
},
"3": {
"period_earnings": 3970.54,
"period_contribution": 30290.47,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 6335.39,
"cumulative_contributions": 89101.25,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 100436.65
},
"4": {
"period_earnings": 6026.2,
"period_contribution": 30896.28,
"period_withdrawal": -37923.8,
"period_taxes": -18678.88,
"cumulative_earnings": 12361.59,
"cumulative_contributions": 119997.53,
"cumulative_withdrawals": -37923.8,
"cumulative_taxes": -18678.88,
"ending_balance": 99435.33
},
"5": {
"period_earnings": 5966.12,
"period_contribution": 31514.2,
"period_withdrawal": -39819.98,
"period_taxes": -19612.83,
"cumulative_earnings": 18327.71,
"cumulative_contributions": 151511.73,
"cumulative_withdrawals": -77743.78,
"cumulative_taxes": -38291.71,
"ending_balance": 97095.67
},
"6": {
"period_earnings": 5825.74,
"period_contribution": 32144.49,
"period_withdrawal": -41810.98,
"period_taxes": -20593.47,
"cumulative_earnings": 24153.45,
"cumulative_contributions": 183656.22,
"cumulative_withdrawals": -119554.76,
"cumulative_taxes": -58885.18,
"ending_balance": 93254.91
},
"7": {
"period_earnings": 5595.29,
"period_contribution": 32787.38,
"period_withdrawal": -43901.53,
"period_taxes": -21623.14,
"cumulative_earnings": 29748.75,
"cumulative_contributions": 216443.6,
"cumulative_withdrawals": -163456.3,
"cumulative_taxes": -80508.33,
"ending_balance": 87736.04
}
}
}
RESPONSE
Field | Description |
---|---|
deposit_amount |
The deposit amount to meet the education goal. |
deposit_frequency_interval |
The period interval to be used in relation to deposit_duration. The value may be one of the following: year, quarter, month, week. If excluded, defaults to year. |
total_cost |
The total cost of education over the decumulation horizon, represented in future dollars. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_contribution |
The deposit made for this period. |
period_withdrawal |
The withdrawal made for this period. |
period_taxes |
The taxes paid during this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
cumulative_taxes |
The cumulative taxes paid up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Percent of Costs Covered
A calculator to help plan for an education goal by solving for the percentage of the total cost that the user can afford.
HTTP REQUEST
POST /education_calculator/percent_covered
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"initial_balance": 5000,
"accumulation_horizon": 3,
"decumulation_horizon": 4,
"total_annual_cost": 40000,
"portfolio_return": 0.06,
"education_inflation_rate": 0.05,
"general_inflation_rate": 0.02,
"tax_rate": 0.33,
"deposit_schedule": {
"deposit_amount": 4000,
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
}
}' "https://api.hydrogenplatform.com/proton/v1/education_calculator/percent_covered"
ARGUMENTS
Parameter | Description |
---|---|
initial_balance float, required |
The amount currently saved for the education goal. |
accumulation_horizon integer, required |
The amount of years until funds are needed to pay for an education expense. |
decumulation_horizon integer, required |
The number of years to pay the total_annual_cost . |
total_annual_cost float, required |
The total cost paid per year for the education goal, represented in today’s dollars. |
portfolio_return float, required |
The portfolio return for the length of the accumulation_horizon and decumulation_horizon . |
education_inflation_rate float |
The inflation rate attributed to total_annual_cost . If excluded, defaults to 0.05 . |
general_inflation_rate float |
The rate used to increase deposits for inflation. If excluded, defaults to 0.02 . |
tax_rate float |
The tax rate to apply to investments upon removal from the portfolio. If excluded, defaults to 0 . |
deposit_schedule map |
The deposit schedule for the education goal. |
deposit_amount string |
The amount deposited per a given period & number of intervals. Deposits are assumed to continue through the length of accumulation_horizon and decumulation_horizon . If excluded, defaults to 0 . |
deposit_frequency_interval string |
The period interval to be used in relation to the deposit_amount . The value may be one of the following: year , quarter , month , or week . If excluded, defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposits should be increased over time with the rate of inflation. If excluded, defaults to true . |
Example Response
{
"percent_of_costs_covered": 0.1262,
"total_cost": 26444.38,
"return_details": {
"0": {
"period_earnings": 0,
"period_contribution": 0,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 0,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 5000
},
"1": {
"period_earnings": 300,
"period_contribution": 4000,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 300,
"cumulative_contributions": 4000,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 9300
},
"2": {
"period_earnings": 558,
"period_contribution": 4080,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 858,
"cumulative_contributions": 8080,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 13938
},
"3": {
"period_earnings": 836.28,
"period_contribution": 4161.6,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 1694.28,
"cumulative_contributions": 12241.6,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 18935.88
},
"4": {
"period_earnings": 1136.15,
"period_contribution": 4244.83,
"period_withdrawal": -9157.33,
"period_taxes": -4510.32,
"cumulative_earnings": 2830.43,
"cumulative_contributions": 16486.43,
"cumulative_withdrawals": -9157.33,
"cumulative_taxes": -4510.32,
"ending_balance": 15159.54
},
"5": {
"period_earnings": 909.57,
"period_contribution": 4329.73,
"period_withdrawal": -9615.19,
"period_taxes": -4735.84,
"cumulative_earnings": 3740.01,
"cumulative_contributions": 20816.16,
"cumulative_withdrawals": -18772.52,
"cumulative_taxes": -9246.17,
"ending_balance": 10783.65
},
"6": {
"period_earnings": 647.02,
"period_contribution": 4416.32,
"period_withdrawal": -10095.95,
"period_taxes": -4972.63,
"cumulative_earnings": 4387.02,
"cumulative_contributions": 25232.48,
"cumulative_withdrawals": -28868.47,
"cumulative_taxes": -14218.8,
"ending_balance": 5751.04
},
"7": {
"period_earnings": 345.06,
"period_contribution": 4504.65,
"period_withdrawal": -10600.75,
"period_taxes": -5221.26,
"cumulative_earnings": 4732.09,
"cumulative_contributions": 29737.13,
"cumulative_withdrawals": -39469.22,
"cumulative_taxes": -19440.06,
"ending_balance": 0
}
}
}
RESPONSE
Field | Description |
---|---|
percent_of_costs_covered |
The percentage of total_annual_cost that can be paid for, given the other inputs provided by the user. |
total_cost |
The total cost of education over the decumulation horizon, represented in future dollars. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_contribution |
The deposit made for this period. |
period_withdrawal |
The withdrawal made for this period. |
period_taxes |
The taxes paid during this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
cumulative_taxes |
The cumulative taxes paid up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Total Annual Cost
A calculator to help plan for an education goal by solving for the total annual cost that a user could afford.
HTTP REQUEST
POST /education_calculator/annual_cost
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"initial_balance": 5000,
"accumulation_horizon": 3,
"decumulation_horizon": 4,
"portfolio_return": 0.06,
"percent_of_costs_covered": 1,
"education_inflation_rate": 0.05,
"general_inflation_rate": 0.02,
"tax_rate": 0.33,
"deposit_schedule": {
"deposit_amount": 4000,
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
}
}' "https://api.hydrogenplatform.com/proton/v1/education_calculator/annual_cost"
ARGUMENTS
Parameter | Description |
---|---|
initial_balance float, required |
The amount currently saved for the education goal. |
accumulation_horizon integer, required |
The amount of years until funds are needed to pay for an education expense. |
decumulation_horizon integer, required |
The number of years to pay the total_annual_cost . |
portfolio_return float, required |
The portfolio return for the length of the accumulation_horizon and decumulation_horizon . |
percent_of_costs_covered float |
The percentage of total_annual_cost to be paid for. If excluded, defaults to 1 . |
education_inflation_rate float |
The inflation rate attributed to total_annual_cost . If excluded, defaults to 0.05 . |
general_inflation_rate float |
The rate used to increase deposits for inflation. If excluded, defaults to 0.02 . |
tax_rate float |
The tax rate to apply to investments upon removal from the portfolio. If excluded, defaults to 0 . |
deposit_schedule map |
The deposit schedule for the education goal. |
deposit_amount string |
The amount deposited per a given period & number of intervals. Deposits are assumed to continue through the length of accumulation_horizon and decumulation_horizon . If excluded, defaults to 0 . |
deposit_frequency_interval string |
The period interval to be used in relation to the deposit_amount . The value may be one of the following: year , quarter , month , or week . If excluded, defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposits should be increased over time with the rate of inflation. If excluded, defaults to true . |
Example Response
{
"total_annual_cost": 5047.62,
"total_cost": 26444.377399999998,
"return_details": {
"0": {
"period_earnings": 0,
"period_contribution": 0,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 0,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 5000
},
"1": {
"period_earnings": 300,
"period_contribution": 4000,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 300,
"cumulative_contributions": 4000,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 9300
},
"2": {
"period_earnings": 558,
"period_contribution": 4080,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 858,
"cumulative_contributions": 8080,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 13938
},
"3": {
"period_earnings": 836.28,
"period_contribution": 4161.6,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 1694.28,
"cumulative_contributions": 12241.6,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 18935.88
},
"4": {
"period_earnings": 1136.15,
"period_contribution": 4244.83,
"period_withdrawal": -9157.33,
"period_taxes": -4510.32,
"cumulative_earnings": 2830.43,
"cumulative_contributions": 16486.43,
"cumulative_withdrawals": -9157.33,
"cumulative_taxes": -4510.32,
"ending_balance": 15159.54
},
"5": {
"period_earnings": 909.57,
"period_contribution": 4329.73,
"period_withdrawal": -9615.19,
"period_taxes": -4735.84,
"cumulative_earnings": 3740.01,
"cumulative_contributions": 20816.16,
"cumulative_withdrawals": -18772.52,
"cumulative_taxes": -9246.17,
"ending_balance": 10783.65
},
"6": {
"period_earnings": 647.02,
"period_contribution": 4416.32,
"period_withdrawal": -10095.95,
"period_taxes": -4972.63,
"cumulative_earnings": 4387.02,
"cumulative_contributions": 25232.48,
"cumulative_withdrawals": -28868.47,
"cumulative_taxes": -14218.8,
"ending_balance": 5751.04
},
"7": {
"period_earnings": 345.06,
"period_contribution": 4504.65,
"period_withdrawal": -10600.75,
"period_taxes": -5221.26,
"cumulative_earnings": 4732.09,
"cumulative_contributions": 29737.13,
"cumulative_withdrawals": -39469.22,
"cumulative_taxes": -19440.06,
"ending_balance": 0
}
}
}
RESPONSE
Field | Description |
---|---|
total_annual_cost |
The total education cost per year that can be afforded, represented in today’s dollars. |
total_cost |
The total cost of education over the decumulation horizon, represented in future dollars. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_contribution |
The deposit made for this period. |
period_withdrawal |
The withdrawal made for this period. |
period_taxes |
The taxes paid during this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
cumulative_taxes |
The cumulative taxes paid up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Major Purchase Calculator
When planning to make a major purchase, such as a down payment on a home/car, investors need to determine how much is needed and how to stay on track. After collecting information about the user’s major purchase, this tool solves for three different parameters: deposit amount, purchase amount, and purchase horizon.
Deposit Amount
A calculator to help determine the deposit amount needed to meet the major purchase goal.
HTTP REQUEST
POST /purchase_calculator/deposit_amount
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"purchase_horizon": 5,
"purchase_amount": 50000,
"portfolio_return": 0.06,
"horizon_frequency_interval": "year",
"current_savings": 0,
"deposit_schedule": {
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
},
"inflation_rate": 0.02,
"investment_tax": 0.25
}' "https://api.hydrogenplatform.com/proton/v1/purchase_calculator/deposit_amount"
ARGUMENTS
Parameter | Description |
---|---|
purchase_horizon integer, required |
The amount of time until the major purchase is made. |
purchase_amount float, required |
The amount of the major purchase. |
portfolio_return float, required |
The portfolio’s return, calculated on an annual basis. |
horizon_frequency_interval string |
The interval at which to measure the purchase horizon. The value may be one of the following: year , quarter , month , or week . Earnings are calculated at the same frequency as horizon_frequency_interval . If excluded, defaults to year . |
current_savings float |
The current amount of savings earmarked for the goal. If excluded, defaults to 0 . |
deposit_schedule map |
The deposit schedule for the major purchase goal. |
deposit_frequency_interval string |
The period interval to be used in relation to the deposit_amount . The value may be one of the following: year , quarter , month , or week . If excluded, defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposits are increased over time with the rate of inflation. If excluded, defaults to true . |
inflation_rate float |
The annual inflation rate of the purchase_amount . If excluded, defaults to 0 . |
investment_tax float |
The tax on the investments used to pay for the major purchase. If excluded, defaults to 0 . |
Example Response
{
"deposit_amount": 12801.3,
"deposit_frequency_interval": "year",
"projected_savings_at_purchase_horizon": 50000,
"return_details": {
"0": {
"period_earnings": 0,
"period_contribution": 0,
"cumulative_earnings": 0,
"cumulative_contributions": 0,
"ending_balance": 0
},
"1": {
"period_earnings": 0,
"period_contribution": 12801.3,
"cumulative_earnings": 0,
"cumulative_contributions": 12801.3,
"ending_balance": 12801.3
},
"2": {
"period_earnings": 768.08,
"period_contribution": 12801.3,
"cumulative_earnings": 768.08,
"cumulative_contributions": 25602.61,
"ending_balance": 26370.69
},
"3": {
"period_earnings": 1582.24,
"period_contribution": 12801.3,
"cumulative_earnings": 2350.32,
"cumulative_contributions": 38403.91,
"ending_balance": 40754.23
},
"4": {
"period_earnings": 2445.25,
"period_contribution": 12801.3,
"cumulative_earnings": 4795.57,
"cumulative_contributions": 51205.22,
"ending_balance": 56000.79
},
"5": {
"period_earnings": 3360.05,
"period_contribution": 12801.3,
"cumulative_earnings": 8155.62,
"cumulative_contributions": 64006.52,
"ending_balance": 72162.14
}
}
}
RESPONSE
Field | Description |
---|---|
deposit_amount |
The amount to deposit in order to meet the purchase goal. |
deposit_frequency_interval |
The frequency interval of the deposit. |
projected_savings_at_purchase_horizon |
The total amount of savings that are projected to be available at the final horizon, expressed in today’s dollars. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions are made. |
period_contribution |
The deposit made for this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Purchase Amount
A calculator to help determine the amount that the user could afford for the major purchase, given the other inputs.
HTTP REQUEST
POST /purchase_calculator/amount
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"purchase_horizon": 6,
"portfolio_return": 0.06,
"horizon_frequency_interval": "year",
"current_savings": 0,
"deposit_schedule": {
"deposit_amount": 10000,
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
},
"inflation_rate": 0.0,
"investment_tax": 0.0
}' "https://api.hydrogenplatform.com/proton/v1/purchase_calculator/amount"
ARGUMENTS
Parameter | Description |
---|---|
purchase_horizon integer, required |
The amount of time until the major purchase is made. |
portfolio_return float, required |
The portfolio’s return, calculated on an annual basis. |
horizon_frequency_interval string |
The interval at which to measure the purchase_horizon . The value may be one of the following: year , quarter , month , or week . Earnings are calculated at the same frequency as horizon_frequency_interval . If excluded, defaults to year . |
current_savings float |
The current amount of savings earmarked for the goal. If excluded, defaults to 0 . |
deposit_schedule map |
The deposit schedule for the major purchase goal. |
deposit_amount float |
The periodic additions to the major purchase goal. If excluded, defaults to 0 . |
deposit_frequency_interval string |
The period interval to be used in relation to the deposit_amount . The value may be one of the following: year , quarter , month , or week . If excluded, defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposits are increased over time with the rate of inflation. If excluded, defaults to true . |
inflation_rate float |
The annual inflation rate of the purchase_amount . If excluded, defaults to 0 . |
investment_tax float |
The tax on the investments used to pay for the major purchase. If excluded, defaults to 0 . |
Example Response
{
"purchase_amount": 69753.19,
"projected_savings_at_purchase_horizon": 69753.19,
"return_details": {
"0": {
"period_earnings": 0,
"period_contribution": 0,
"cumulative_earnings": 0,
"cumulative_contributions": 0,
"ending_balance": 0
},
"1": {
"period_earnings": 0,
"period_contribution": 10000,
"cumulative_earnings": 0,
"cumulative_contributions": 10000,
"ending_balance": 10000
},
"2": {
"period_earnings": 600,
"period_contribution": 10000,
"cumulative_earnings": 600,
"cumulative_contributions": 20000,
"ending_balance": 20600
},
"3": {
"period_earnings": 1236,
"period_contribution": 10000,
"cumulative_earnings": 1836,
"cumulative_contributions": 30000,
"ending_balance": 31836
},
"4": {
"period_earnings": 1910.16,
"period_contribution": 10000,
"cumulative_earnings": 3746.16,
"cumulative_contributions": 40000,
"ending_balance": 43746.16
},
"5": {
"period_earnings": 2624.77,
"period_contribution": 10000,
"cumulative_earnings": 6370.93,
"cumulative_contributions": 50000,
"ending_balance": 56370.93
},
"6": {
"period_earnings": 3382.26,
"period_contribution": 10000,
"cumulative_earnings": 9753.19,
"cumulative_contributions": 60000,
"ending_balance": 69753.19
}
}
}
RESPONSE
Field | Description |
---|---|
purchase_amount |
The amount of the major purchase. |
projected_savings_at_purchase horizon |
The total amount of savings that are projected to be available at purchase_horizon , expressed in today’s dollars. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The earnings for this period. Earnings are calculated at the beginning of each period, before contributions are made. |
period_contribution |
The deposit made for this period. |
cumulative_earnings |
The cumulative earnings made up to and including this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Purchase Horizon
A calculator to help determine the amount of years needed to save for a major purchase.
HTTP REQUEST
POST /purchase_calculator/horizon
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"purchase_amount": 50000,
"portfolio_return": 0.06,
"horizon_frequency_interval": "year",
"current_savings": 0,
"deposit_schedule": {
"deposit_amount": 10000,
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
},
"inflation_rate": 0.02,
"investment_tax": 0.25
}' "https://api.hydrogenplatform.com/proton/v1/purchase_calculator/horizon"
ARGUMENTS
Parameter | Description |
---|---|
purchase_amount float, required |
The amount of the major purchase. |
portfolio_return float, required |
The portfolio’s return, calculated on an annual basis. |
horizon_frequency_interval string |
The interval at which to measure the purchase horizon. The value may be one of the following: year , quarter , month , or week . Earnings are calculated at the same frequency as horizon_frequency_interval . If excluded, defaults to year . |
current_savings float |
The current amount of savings earmarked for the goal. If excluded, defaults to 0 . |
deposit_schedule map |
The deposit schedule for the major purchase goal. |
deposit_amount float |
The periodic additions to the major purchase goal. If excluded, defaults to 0 . |
deposit_frequency_interval string |
The period interval to be used in relation to the deposit_amount . The value may be one of the following: year , quarter , month , or week . If excluded, defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposits are increased over time with the rate of inflation. If excluded, defaults to true . |
inflation_rate float |
The annual inflation rate of the purchase_amount . If excluded, defaults to 0 . |
investment_tax float |
The tax on the investments used to pay for the major purchase. If excluded, defaults to 0 . |
Example Response
{
"purchase_horizon": 7,
"projected_savings_at_purchase_horizon": 55901.16,
"return_details": {
"0": {
"period_earnings": 0,
"period_contribution": 0,
"cumulative_earnings": 0,
"cumulative_contributions": 0,
"ending_balance": 0
},
"1": {
"period_earnings": 0,
"period_contribution": 10000,
"cumulative_earnings": 0,
"cumulative_contributions": 10000,
"ending_balance": 10000
},
"2": {
"period_earnings": 600,
"period_contribution": 10000,
"cumulative_earnings": 600,
"cumulative_contributions": 20000,
"ending_balance": 20600
},
"3": {
"period_earnings": 1236,
"period_contribution": 10000,
"cumulative_earnings": 1836,
"cumulative_contributions": 30000,
"ending_balance": 31836
},
"4": {
"period_earnings": 1910.16,
"period_contribution": 10000,
"cumulative_earnings": 3746.16,
"cumulative_contributions": 40000,
"ending_balance": 43746.16
},
"5": {
"period_earnings": 2624.77,
"period_contribution": 10000,
"cumulative_earnings": 6370.93,
"cumulative_contributions": 50000,
"ending_balance": 56370.93
},
"6": {
"period_earnings": 3382.26,
"period_contribution": 10000,
"cumulative_earnings": 9753.19,
"cumulative_contributions": 60000,
"ending_balance": 69753.19
},
"7": {
"period_earnings": 4185.19,
"period_contribution": 10000,
"cumulative_earnings": 13938.38,
"cumulative_contributions": 70000,
"ending_balance": 83938.38
}
}
}
RESPONSE
Field | Description |
---|---|
purchase_horizon |
The number of periods needed in order to meet the major purchase goal. |
projected_savings_at_purchase_horizon |
The total amount of savings that are projected to be available at the major purchase date, expressed in today’s dollars. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The earnings for this period. Earnings are calculated at the beginning of each period, before contributions are made. |
period_contribution |
The deposit made for this period. |
cumulative_earnings |
The cumulative earnings made up to and including this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Mortgage Calculator
Many users face the question of how much a mortgage may cost when deciding to buy a property. This tool simplifies the parameters to five components: the mortgage interest rate, mortgage term, home price, down payment, and the periodic (monthly) payment. Of those five parameters, this mortgage calculator provides three different endpoints to solve for the following parameters: a periodic (monthly) payment, down payment and total home price.
Down Payment
This calculator helps a user solve for the down payment they will need to pay, given the other factors in their home purchase.
HTTP REQUEST
POST /mortgage_calculator/down_payment
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"home_price": 100000,
"periodic_payment": 8000,
"interest_rate": 0.04,
"mortgage_term": 6
}' "https://api.hydrogenplatform.com/proton/v1/mortgage_calculator/down_payment"
ARGUMENTS
Parameter | Description |
---|---|
home_price float, required |
The total cost of the home, including down payments but excluding transactional costs of purchasing the home (e.g. insurance, legal fees, closing costs, etc.) |
periodic_payment float, required |
The periodic monthly payment for the mortgage. |
interest_rate float |
The annualized interest rate charged on the balance of the mortgage. If excluded, defaults to 0.0 . |
mortgage_term integer |
The length of time the mortgage will take place, as expressed in months. If excluded, defaults to 360 . |
Example Response
{
"down_payment": 52545.22,
"schedule": {
"0": {
"Payment": 0,
"Principal": 0,
"Interest": 0,
"Cumulative_Payment": 0,
"Cumulative_Principal": 0,
"Cumulative_Interest": 0,
"Balance": 47454.78
},
"1": {
"Payment": 8000,
"Principal": 7844.65,
"Interest": 155.35,
"Cumulative_Payment": 8000,
"Cumulative_Principal": 7844.65,
"Cumulative_Interest": 155.35,
"Balance": 39610.13
},
"2": {
"Payment": 8000,
"Principal": 7870.33,
"Interest": 129.67,
"Cumulative_Payment": 16000,
"Cumulative_Principal": 15714.97,
"Cumulative_Interest": 285.03,
"Balance": 31739.81
},
"3": {
"Payment": 8000,
"Principal": 7896.09,
"Interest": 103.91,
"Cumulative_Payment": 24000,
"Cumulative_Principal": 23611.06,
"Cumulative_Interest": 388.94,
"Balance": 23843.71
},
"4": {
"Payment": 8000,
"Principal": 7921.94,
"Interest": 78.06,
"Cumulative_Payment": 32000,
"Cumulative_Principal": 31533.01,
"Cumulative_Interest": 466.99,
"Balance": 15921.77
},
"5": {
"Payment": 8000,
"Principal": 7947.88,
"Interest": 52.12,
"Cumulative_Payment": 40000,
"Cumulative_Principal": 39480.88,
"Cumulative_Interest": 519.12,
"Balance": 7973.9
},
"6": {
"Payment": 8000,
"Principal": 7973.9,
"Interest": 26.1,
"Cumulative_Payment": 48000,
"Cumulative_Principal": 47454.78,
"Cumulative_Interest": 545.22,
"Balance": 0
}
}
}
RESPONSE
Field | Description |
---|---|
down_payment |
The payment due upfront when buying a home, given the other inputs provided by the user. |
schedule |
Details for the mortgage payment, broken down by period. |
Payment |
The total payment made for this period, consisting of interest and principal. |
Principal |
The principal payment made for this period. |
Interest |
The interest payment made for this period. |
Cumulative_Payment |
The cumulative total payment made up to and including this period. |
Cumulative_Principal |
The cumulative principal payment made up to and including this period. |
Cumulative_Interest |
The cumulative interest payment made up to and including this period. |
Balance |
The remaining mortgage balance at the end of the period. |
Home Price
This calculator helps a user solve for the total home price they can afford, given the other factors related to their home purchase.
HTTP REQUEST
POST /mortgage_calculator/home_price
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"down_payment": 50000,
"periodic_payment": 8000,
"interest_rate": 0.04,
"mortgage_term": 6
}' "https://api.hydrogenplatform.com/proton/v1/mortgage_calculator/home_price"
ARGUMENTS
Parameter | Description |
---|---|
down_payment float, required |
The payment due upfront when buying a home. |
periodic_payment float, required |
The periodic monthly payment for the mortgage. |
interest_rate float |
The annualized interest rate charged on the balance of the mortgage. If excluded, defaults to 0.0 . |
mortgage_term integer |
The length of time the mortgage will take place, as expressed in months. If excluded, defaults to 360 . |
Example Response
{
"home_price": 97454.78,
"schedule": {
"0": {
"Payment": 0,
"Principal": 0,
"Interest": 0,
"Cumulative_Payment": 0,
"Cumulative_Principal": 0,
"Cumulative_Interest": 0,
"Balance": 47454.78
},
"1": {
"Payment": 8000,
"Principal": 7844.65,
"Interest": 155.35,
"Cumulative_Payment": 8000,
"Cumulative_Principal": 7844.65,
"Cumulative_Interest": 155.35,
"Balance": 39610.13
},
"2": {
"Payment": 8000,
"Principal": 7870.33,
"Interest": 129.67,
"Cumulative_Payment": 16000,
"Cumulative_Principal": 15714.97,
"Cumulative_Interest": 285.03,
"Balance": 31739.81
},
"3": {
"Payment": 8000,
"Principal": 7896.09,
"Interest": 103.91,
"Cumulative_Payment": 24000,
"Cumulative_Principal": 23611.06,
"Cumulative_Interest": 388.94,
"Balance": 23843.71
},
"4": {
"Payment": 8000,
"Principal": 7921.94,
"Interest": 78.06,
"Cumulative_Payment": 32000,
"Cumulative_Principal": 31533.01,
"Cumulative_Interest": 466.99,
"Balance": 15921.77
},
"5": {
"Payment": 8000,
"Principal": 7947.88,
"Interest": 52.12,
"Cumulative_Payment": 40000,
"Cumulative_Principal": 39480.88,
"Cumulative_Interest": 519.12,
"Balance": 7973.9
},
"6": {
"Payment": 8000,
"Principal": 7973.9,
"Interest": 26.1,
"Cumulative_Payment": 48000,
"Cumulative_Principal": 47454.78,
"Cumulative_Interest": 545.22,
"Balance": 0
}
}
}
RESPONSE
Field | Description |
---|---|
home_price |
The total cost of the home that can be afforded, given the other inputs provided by the user. |
schedule |
Details for the mortgage payment, broken down by period. |
Payment |
The total payment made for this period, consisting of interest and principal. |
Principal |
The principal payment made for this period. |
Interest |
The interest payment made for this period. |
Cumulative_Payment |
The cumulative total payment made up to and including this period. |
Cumulative_Principal |
The cumulative principal payment made up to and including this period. |
Cumulative_Interest |
The cumulative interest payment made up to and including this period. |
Balance |
The remaining mortgage balance at the end of the period. |
Periodic Payment
This calculator helps a user solve for the monthly mortgage payment, given the other factors in their home purchase.
HTTP REQUEST
POST /mortgage_calculator/periodic_payment
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"home_price": 100000,
"down_payment": 50000,
"interest_rate": 0.04,
"mortgage_term": 6
}' "https://api.hydrogenplatform.com/proton/v1/mortgage_calculator/periodic_payment"
ARGUMENTS
Parameter | Description |
---|---|
home_price float, required |
The total cost of the home, including down payments but excluding transactional costs of purchasing the home (e.g. insurance, legal fees, closing costs, etc.) |
down_payment float, required |
The payment due upfront when buying a home. |
interest_rate float |
The annualized interest rate charged on the balance of the mortgage. If excluded, defaults to 0.0 . |
mortgage_term integer |
The length of time the mortgage will take place, as expressed in months. If excluded, defaults to 360 . |
Example Response
{
"periodic_payment": 8429.08,
"schedule": {
"0": {
"Payment": 0,
"Principal": 0,
"Interest": 0,
"Cumulative_Payment": 0,
"Cumulative_Principal": 0,
"Cumulative_Interest": 0,
"Balance": 50000
},
"1": {
"Payment": 8429.08,
"Principal": 8265.39,
"Interest": 163.69,
"Cumulative_Payment": 8429.08,
"Cumulative_Principal": 8265.39,
"Cumulative_Interest": 163.69,
"Balance": 41734.61
},
"2": {
"Payment": 8429.08,
"Principal": 8292.45,
"Interest": 136.63,
"Cumulative_Payment": 16858.15,
"Cumulative_Principal": 16557.84,
"Cumulative_Interest": 300.32,
"Balance": 33442.16
},
"3": {
"Payment": 8429.08,
"Principal": 8319.6,
"Interest": 109.48,
"Cumulative_Payment": 25287.23,
"Cumulative_Principal": 24877.44,
"Cumulative_Interest": 409.8,
"Balance": 25122.56
},
"4": {
"Payment": 8429.08,
"Principal": 8346.83,
"Interest": 82.24,
"Cumulative_Payment": 33716.31,
"Cumulative_Principal": 33224.27,
"Cumulative_Interest": 492.04,
"Balance": 16775.73
},
"5": {
"Payment": 8429.08,
"Principal": 8374.16,
"Interest": 54.92,
"Cumulative_Payment": 42145.39,
"Cumulative_Principal": 41598.43,
"Cumulative_Interest": 546.96,
"Balance": 8401.57
},
"6": {
"Payment": 8429.08,
"Principal": 8401.57,
"Interest": 27.5,
"Cumulative_Payment": 50574.46,
"Cumulative_Principal": 50000,
"Cumulative_Interest": 574.46,
"Balance": 0
}
}
}
RESPONSE
Field | Description |
---|---|
periodic_payment |
The periodic monthly payment for the mortgage, given the other inputs provided by the user. |
schedule |
Details for the mortgage payment, broken down by period. |
Payment |
The total payment made for this period, consisting of interest and principal. |
Principal |
The principal payment made for this period. |
Interest |
The interest payment made for this period. |
Cumulative_Payment |
The cumulative total payment made up to and including this period. |
Cumulative_Principal |
The cumulative principal payment made up to and including this period. |
Cumulative_Interest |
The cumulative interest payment made up to and including this period. |
Balance |
The remaining mortgage balance at the end of the period. |
Retirement Calculator
When planning for retirement, investors need to determine how much is needed and how to bridge any gaps in their financial plan. After collecting information about the user’s financial situation and desired retirement lifestyle, this tool solves for three different parameters: deposit amount, retirement lifestyle, and retirement expenses.
Deposit Amount
A calculator to help plan for the deposit amount needed to retire comfortably.
HTTP REQUEST
POST /retirement_calculator/deposit_amount
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{{
"current_age": 70,
"death_age": 78,
"retirement_expenses": 70000,
"portfolio_return": 0.06,
"retirement_age":75,
"percent_of_expenses_covered": 0.25,
"retirement_savings": 50000,
"retirement_income": 5000,
"deposit_schedule": {
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
},
"inflation_rate": 0.02,
"retirement_tax": 0.25
}' "https://api.hydrogenplatform.com/proton/v1/retirement_calculator/deposit_amount"
ARGUMENTS
Parameter | Description |
---|---|
current_age integer, required |
The user’s current age. This will be used when determining the amount of years to accumulate funds. |
death_age integer, required |
The user’s death age. This age will be used when determining the amount of years that retirement_expenses will be needed. |
retirement_expenses float, required |
The expenses needed per year in retirement. |
portfolio_return float, required |
The portfolio’s annualized return. |
retirement_age integer |
The age the user will retire. This is the age that the user will cease adding to their retirement assets and begin drawing down funds to meet retirement_expenses . If excluded, defaults to 65 . |
percent_of_expenses_covered float |
The percentage of current expenses needed in retirement. If excluded, defaults to 0.70 . |
retirement_savings float |
The current amount of retirement savings. If excluded, defaults to 0 . |
retirement_income float |
The amount of an income stream that will be available in retirement, expressed in today’s dollars. If excluded, defaults to 0 . |
deposit_schedule map |
The deposit schedule for the retirement goal. |
deposit_frequency_interval string |
The frequency at which to make additions to retirement_savings in the periods before retirement. The value may be one of the following: year , quarter , month , or week . If excluded, defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposit_amount will be increased by the inflation_rate . If excluded, defaults to true . |
inflation_rate float |
The annual inflation rate of retirement_expenses . If excluded, defaults to 0 . |
retirement_tax float |
The tax on assets in retirement. This tax rate will be applied to the assets that are needed for retirement_expenses . If excluded, defaults to 0 . |
Example Response
{
"deposit_amount": 0,
"deposit_frequency_interval": "year",
"projected_savings_at_retirement": 60603.61,
"return_details": {
"0": {
"period_earnings": 0,
"period_contribution": 0,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 0,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 50000
},
"1": {
"period_earnings": 3000,
"period_contribution": 0,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 3000,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 53000
},
"2": {
"period_earnings": 3180,
"period_contribution": 0,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 6180,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 56180
},
"3": {
"period_earnings": 3370.8,
"period_contribution": 0,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 9550.8,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 59550.8
},
"4": {
"period_earnings": 3573.05,
"period_contribution": 0,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 13123.85,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 63123.85
},
"5": {
"period_earnings": 3787.43,
"period_contribution": 0,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 16911.28,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 66911.28
},
"6": {
"period_earnings": 4014.68,
"period_contribution": 0,
"period_withdrawal": -15181.11,
"period_taxes": -5060.37,
"cumulative_earnings": 20925.96,
"cumulative_contributions": 0,
"cumulative_withdrawals": -15181.11,
"cumulative_taxes": -5060.37,
"ending_balance": 55744.84
},
"7": {
"period_earnings": 3344.69,
"period_contribution": 0,
"period_withdrawal": -15484.73,
"period_taxes": -5161.58,
"cumulative_earnings": 24270.65,
"cumulative_contributions": 0,
"cumulative_withdrawals": -30665.84,
"cumulative_taxes": -10221.95,
"ending_balance": 43604.8
},
"8": {
"period_earnings": 2616.29,
"period_contribution": 0,
"period_withdrawal": -15794.43,
"period_taxes": -5264.81,
"cumulative_earnings": 26886.93,
"cumulative_contributions": 0,
"cumulative_withdrawals": -46460.27,
"cumulative_taxes": -15486.76,
"ending_balance": 30426.66
}
}
}
RESPONSE
Field | Description |
---|---|
deposit_amount |
The amount to deposit in order to meet the retirement goal. |
deposit_frequency_interval |
The frequency interval of the deposit. |
projected_savings_at_retirement |
The total amount of savings projected to be available at retirement, expressed in today’s dollars. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_contribution |
The deposit made for this period. |
period_withdrawal |
The withdrawal made for this period. |
period_taxes |
The taxes paid during this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
cumulative_taxes |
The cumulative taxes paid up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Percent of Costs Covered
A calculator to help determine the percentage of the retirement lifestyle that can be afforded.
HTTP REQUEST
POST /retirement_calculator/percent_covered
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"current_age": 50,
"death_age": 57,
"retirement_expenses": 40000,
"portfolio_return": 0.06,
"retirement_age": 55,
"retirement_savings": 50000,
"retirement_income": 5000,
"deposit_schedule": {
"deposit_amount": 10000,
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
},
"inflation_rate": 0.02,
"retirement_tax": 0.25
}' "https://api.hydrogenplatform.com/proton/v1/retirement_calculator/percent_covered"
ARGUMENTS
Parameter | Description |
---|---|
current_age integer, required |
The user’s current age. This will be used when determining the amount of years to accumulate funds. |
death_age integer, required |
The user’s death age. This age will be used when determining the amount of years that retirement_expenses will be needed. |
retirement_expenses float, required |
The expenses needed per year in retirement. |
portfolio_return float, required |
The portfolio’s annualized return. |
retirement_age integer |
The age the user will retire. This is the age that the user will cease adding to their retirement assets and begin drawing down funds to meet retirement_expenses . If excluded, defaults to 65 . |
retirement_savings float |
The current amount of retirement savings. If excluded, defaults to 0 . |
retirement_income float |
The amount of an income stream that will be available in retirement, expressed in today’s dollars. If excluded, defaults to 0 . |
deposit_schedule map |
The deposit schedule for the retirement goal. |
deposit_amount float |
The periodic additions to retirement savings in the period before retirement. If excluded, defaults to 0 . |
deposit_frequency_interval string |
The frequency at which to make additions to retirement savings in the periods before retirement. The value may be one of the following: year , quarter , month , or week . If excluded, defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposit_amount will be increased by the inflation_rate . If excluded, defaults to true . |
inflation_rate float |
The annual inflation rate of retirement_expenses . If excluded, defaults to 0 . |
retirement_tax float |
The tax on assets in retirement. This tax rate will be applied to the assets that are needed for retirement_expenses . If excluded, defaults to 0 . |
Example Response
{
"percent_of_expenses_covered": 1,
"projected_savings_at_retirement": 113621.64,
"return_details": {
"0": {
"period_earnings": 0,
"period_contribution": 0,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 0,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 50000
},
"1": {
"period_earnings": 3000,
"period_contribution": 10000,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 3000,
"cumulative_contributions": 10000,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 63000
},
"2": {
"period_earnings": 3780,
"period_contribution": 10200,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 6780,
"cumulative_contributions": 20200,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 76980
},
"3": {
"period_earnings": 4618.8,
"period_contribution": 10404,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 11398.8,
"cumulative_contributions": 30604,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 92002.8
},
"4": {
"period_earnings": 5520.17,
"period_contribution": 10612.08,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 16918.97,
"cumulative_contributions": 41216.08,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 108135.05
},
"5": {
"period_earnings": 6488.1,
"period_contribution": 10824.32,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 23407.07,
"cumulative_contributions": 52040.4,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 125447.47
},
"6": {
"period_earnings": 7526.85,
"period_contribution": 0,
"period_withdrawal": -40022.93,
"period_taxes": -13340.98,
"cumulative_earnings": 30933.92,
"cumulative_contributions": 52040.4,
"cumulative_withdrawals": -40022.93,
"cumulative_taxes": -13340.98,
"ending_balance": 92951.39
},
"7": {
"period_earnings": 5577.08,
"period_contribution": 0,
"period_withdrawal": -40823.39,
"period_taxes": -13607.8,
"cumulative_earnings": 36511,
"cumulative_contributions": 52040.4,
"cumulative_withdrawals": -80846.32,
"cumulative_taxes": -26948.77,
"ending_balance": 57705.09
}
}
}
RESPONSE
Field | Description |
---|---|
percent_of_expenses_covered |
The percentage of expenses covered, given the other user inputs. |
projected_savings_at_retirement |
The total amount of savings that are projected to be available at retirement, expressed in today’s dollars. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_contribution |
The deposit made for this period. |
period_withdrawal |
The withdrawal made for this period. |
period_taxes |
The taxes paid during this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
cumulative_taxes |
The cumulative taxes paid up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Retirement Expenses
A calculator to help plan for the amount of expenses that will be incurred in retirement.
HTTP REQUEST
POST /retirement_calculator/expenses
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"current_age": 50,
"death_age": 57,
"portfolio_return": 0.06,
"retirement_age": 55,
"percent_of_expenses_covered": 0.25,
"retirement_savings": 50000,
"retirement_income": 5000,
"deposit_schedule": {
"deposit_amount": 10000,
"deposit_frequency_interval": "year",
"adjust_deposit_for_inflation": true
},
"inflation_rate": 0.02,
"retirement_tax": 0.25
}' "https://api.hydrogenplatform.com/proton/v1/retirement_calculator/expenses"
ARGUMENTS
Parameter | Description |
---|---|
current_age integer, required |
The user’s current age. This will be used when determining the amount of years to accumulate funds. |
death_age integer, required |
The user’s death age. This age will be used when determining the amount of years that retirement_expenses will be needed. |
portfolio_return float, required |
The portfolio’s annualized return. |
retirement_age integer |
The age the user will retire. This is the age that the user will cease adding to their retirement assets and begin drawing down funds to meet retirement_expenses . If excluded, defaults to 65 . |
percent_of_expenses_covered float |
The percentage of current expenses needed in retirement. If excluded, defaults to 0.70 . |
retirement_savings float |
The current amount of retirement savings. If excluded, defaults to 0 . |
retirement_income float |
The amount of an income stream that will be available in retirement, expressed in today’s dollars. If excluded, defaults to 0 . |
deposit_schedule map |
The deposit schedule for the retirement goal. |
deposit_amount float |
The periodic additions to retirement savings in the period before retirement. If excluded, defaults to 0 . |
deposit_frequency_interval string |
The frequency at which to make additions to retirement savings in the periods before retirement. The value may be one of the following: year , quarter , month , or week . If excluded, defaults to year . |
adjust_deposit_for_inflation boolean |
If true , the deposit_amount will be increased by the inflation_rate . If excluded, defaults to true . |
inflation_rate float |
The annual inflation rate of retirement_expenses . If excluded, defaults to 0 . |
retirement_tax float |
The tax on assets in retirement. This tax rate will be applied to the assets that are needed for retirement_expenses . If excluded, defaults to 0 . |
Example Response
{
"projected_retirement_expenses": 50130.545,
"projected_savings_at_retirement": 113621.64,
"return_details": {
"0": {
"period_earnings": 0,
"period_contribution": 0,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 0,
"cumulative_contributions": 0,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 50000
},
"1": {
"period_earnings": 3000,
"period_contribution": 10000,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 3000,
"cumulative_contributions": 10000,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 63000
},
"2": {
"period_earnings": 3780,
"period_contribution": 10200,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 6780,
"cumulative_contributions": 20200,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 76980
},
"3": {
"period_earnings": 4618.8,
"period_contribution": 10404,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 11398.8,
"cumulative_contributions": 30604,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 92002.8
},
"4": {
"period_earnings": 5520.17,
"period_contribution": 10612.08,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 16918.97,
"cumulative_contributions": 41216.08,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 108135.05
},
"5": {
"period_earnings": 6488.1,
"period_contribution": 10824.32,
"period_withdrawal": 0,
"period_taxes": 0,
"cumulative_earnings": 23407.07,
"cumulative_contributions": 52040.4,
"cumulative_withdrawals": 0,
"cumulative_taxes": 0,
"ending_balance": 125447.47
},
"6": {
"period_earnings": 7526.85,
"period_contribution": 0,
"period_withdrawal": -67765.76,
"period_taxes": -22588.59,
"cumulative_earnings": 30933.92,
"cumulative_contributions": 52040.4,
"cumulative_withdrawals": -67765.76,
"cumulative_taxes": -22588.59,
"ending_balance": 65208.56
},
"7": {
"period_earnings": 3912.51,
"period_contribution": 0,
"period_withdrawal": -69121.07,
"period_taxes": -23040.36,
"cumulative_earnings": 34846.43,
"cumulative_contributions": 52040.4,
"cumulative_withdrawals": -136886.83,
"cumulative_taxes": -45628.94,
"ending_balance": 0
}
}
}
RESPONSE
Field | Description |
---|---|
projected_retirement_expenses |
The after-tax retirement expenses available expressed in today’s dollars. |
projected_savings_at_retirement |
The total amount of savings that are projected to be available at retirement, expressed in today’s dollars. |
return_details |
Portfolio return information over the length of the horizon, broken down by period. |
period_earnings |
The investment earnings for this period. Earnings are calculated at the beginning of each period, before contributions or withdrawals are made. |
period_contribution |
The deposit made for this period. |
period_withdrawal |
The withdrawal made for this period. |
period_taxes |
The taxes paid during this period. |
cumulative_earnings |
The cumulative investment earnings made up to and including this period. |
cumulative_contributions |
The cumulative deposits made up to and including this period. |
cumulative_withdrawals |
The cumulative withdrawals made up to and including this period. |
cumulative_taxes |
The cumulative taxes paid up to and including this period. |
ending_balance |
The ending balance, inclusive of earnings and contributions for the current period. |
Financial Health
Emergency Fund Calculator
An emergency fund refers to a pool of money a user can rely on if they experience a loss of income. This fund should be able to cover all necessary expenses that the user would have to continue paying. The tool allows for the flexibility to use pre-set expense fields, or utilize an area for custom expenses. After specifying the number of months of expenses the emergency fund should cover, the calculator returns a total recommendation along with a plan to save for the total recommended amount in a variety of horizon intervals.
HTTP REQUEST
POST /emergency_fund_calculator
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"emergency_fund_duration": 12,
"housing_cost": 1650,
"utility_payments": 60,
"telecom_payments": 50,
"insurance_payments": 0,
"debt_payments": 0,
"transportation_costs": 150,
"food_costs": 1500,
"other_expenses":
{
"entertainment": 50,
"daycare": 150
},
"current_emergency_fund_balance": 15000,
"interest_rate": 0.015,
"savings_horizon": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24],
"frequency_unit": "month"
}' "https://api.hydrogenplatform.com/proton/v1/emergency_fund_calculator"
ARGUMENTS
Parameter | Description |
---|---|
emergency_fund_duration integer, required |
The number of periods (defined in frequency_unit ) that the emergency fund will last. |
housing_cost float |
The user’s housing costs, such as payments for rent, mortgage, maintenance, etc. If excluded, defaults to 0 . |
utility_payments float |
The user’s utility payments, such as electricity, water, gas, etc. If excluded, defaults to 0 . |
telecom_payments float |
The user’s telecom payments, such as internet, cell phone, cable, etc. If excluded, defaults to 0 . |
insurance_payments float |
The user’s payments for insurance, such as auto, home, motorcycle, etc. If excluded, defaults to 0 . |
debt_payments float |
The user’s debt payments, such as credit cards and loans. If excluded, defaults to 0 . |
transportation_costs float |
The user’s transportation costs, such as gasoline, car payments, etc. If excluded, defaults to 0 . |
food_costs float |
The user’s food costs, such as groceries, restaurants, etc. If excluded, defaults to 0 . |
other_expenses map |
A field to add any other expense type to be included in the emergency fund. If excluded, no additional expenses are included in the calculation. |
category_name string, required |
The category name for each additional expense. |
amount float, required |
The user’s total expense for each given category_name . |
current_emergency_fund_balance float |
The user’s current balance of their emergency fund. If excluded, defaults to 0 . |
interest_rate float |
The annualized interest rate earned on the current_emergency_fund_balance used to calculate the recommended savings amount. The interest_rate is converted from annual rate to the appropriate frequency defined in frequency_unit . If excluded, defaults to 0 . |
savings_horizon array |
The periods in the savings horizon to be used in the recommended savings schedule. The period frequency is defined by frequency_unit . If excluded, defaults to [3, 6, 9, 12, 15, 18, 21, 24] . |
frequency_unit string |
The frequency unit that applies to emergency_fund_duration , all expenses, savings_horizon and saving_schedule . The value may be one of the following: year , six_months , quarter , month , two_weeks or week . If excluded, defaults to month . |
Example Response
{
"emergency_fund_recommendation": 43320,
"savings_schedule": {
"1": 28320.0,
"2": 14151.22,
"3": 9428.29,
"4": 7066.83,
"5": 5649.95,
"6": 4705.37,
"7": 4030.67,
"8": 3524.65,
"9": 3131.07,
"10": 2816.21,
"11": 2558.6,
"12": 2343.93,
"13": 2162.28,
"14": 2006.58,
"15": 1871.65,
"16": 1753.58,
"17": 1649.4,
"18": 1556.8,
"19": 1473.94,
"20": 1399.37,
"21": 1331.91,
"22": 1270.57,
"23": 1214.57,
"24": 1163.24
}
}
RESPONSE
Field | Description |
---|---|
emergency_fund_recommendation |
The total amount recommended for the user’s emergency fund. |
savings_schedule |
The amount the user would need to save in order to achieve their emergency fund goal in a predefined amount of time. |
Portfolio Optimization Score
This service assesses the relative health of a portfolio, as compared to a mean-variance optimized portfolio. The comparison is done on the basis of return-to-risk ratio, producing a score on a 0 to 100 scale, in which 100 represents the optimized portfolio. A portfolio optimization score defines how far a portfolio is away from the mean-variance efficient frontier in order to identify any improvement potential.
HTTP REQUEST
POST /portfolio_optimization_score
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"portfolio_tickers": ["AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
"portfolio_weights": [0.1, 0.1, 0.1, 0.6, 0.1],
"opt_config": {
"tickers": ["AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
"min_assets": 5,
"w_asset_config": {
"US_Equities": 1.0,
"Fixed_Income": 1.0
},
"w_config": {
"w_min_major": 0.05,
"w_max_major": 1.0,
"w_min_minor": 0.05,
"w_max_minor": 1.0,
"cash_amount": 0.0
},
"sec_types": ["minor", "minor", "minor", "minor", "minor"],
"start_date": "2016-01-01",
"end_date": "2017-01-01"
}
}' "https://api.hydrogenplatform.com/proton/v1/portfolio_optimization_score"
ARGUMENTS
Parameter | Description |
---|---|
portfolio_tickers array, required |
Current portfolio tickers, referencing securities defined in the Nucleus API. |
portfolio_weights array, required |
Current portfolio weights, corresponding to portfolio_tickers . |
opt_config map |
Settings for portfolio optimization. Includes the fields shown below. |
tickers array |
Security tickers to consider during the optimization process. Defaults to portfolio_tickers . |
min_assets integer |
Minimum number of assets included in the optimized portfolio. Defaults to 1 . |
w_asset_config map |
Weight constraints for asset classes. Stipulates a maximum weight for the asset classes represented in tickers . If an asset class is represented in tickers but not found in w_asset_config , the weight for that asset class will not be constrained. |
w_config map |
Weight constraints for security types, includes the fields shown below. |
w_min_minor float |
Minimum weight for “minor” securities. Defaults to 0.05 . |
w_max_minor float |
Maximum weight for “minor” securities. Defaults to 1 . |
w_min_major float |
Minimum weight for “major” securities. Defaults to 0.05 . |
w_max_major float |
Maximum weight for “major” securities. Defaults to 1 . |
cash_amount float |
Constant weight for “cash” securities. Defaults to 0 . |
sec_types array |
Security types, corresponding to tickers. May be minor , major , or cash . Defaults to minor for all tickers . |
start_date date |
Start date used for ticker price history. Defaults to earliest common date among ticker prices. |
end_date date |
End date used for ticker price history. Defaults to latest common date among ticker prices. |
Example Response
{
"current_portfolio": {
"tickers": [
"AGG",
"AMZN",
"CMCSA",
"XOM",
"GOOGL"
],
"weights": [
0.1,
0.1,
0.1,
0.1,
0.6
],
"return": 0.1586,
"risk": 0.1414
},
"optimized_portfolio": {
"tickers": [
"GOOGL",
"AGG",
"AMZN",
"XOM",
"CMCSA"
],
"weights": [
0.05,
0.05,
0.1105,
0.1025,
0.687
],
"return": 0.2029,
"risk": 0.1414
},
"optimization_score": 78
}
RESPONSE
Field | Description |
---|---|
current_portfolio |
Details on the current portfolio. Includes the fields shown below. |
tickers |
Tickers in the portfolio. |
weights |
Weights in the current portfolio, corresponding to tickers . |
return |
The annualized mean return. |
risk |
The annualized standard deviation of returns. |
optimized_portfolio |
Details on the optimized portfolio. Includes the fields shown below. |
tickers |
Tickers in the portfolio. |
weights |
Weights in the current portfolio, corresponding to tickers . |
return |
The annualized mean return. |
risk |
The annualized standard deviation of returns. |
optimization_score |
A score from 0 to 100 indicating the relative health of the current portfolio, 100 being the most optimal. |
NUCLEUS DATA DEPENDENCIES
1. Securities: POST /security
2. Security Prices: POST /security_price
Diversification Score
This service is a scoring engine to assess the level of diversification exhibited by an investor’s portfolio. The score compares the portfolio volatility to the volatility values of the underlying portfolio holdings, in order to derive a score from 0 to 100, where 0 indicates no diversification and 100 indicates the maximum theoretical diversification level.
HTTP REQUEST
POST /diversification_score
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"portfolio_tickers": [
"XOM",
"CMCSA",
"AMZN",
"GOOGL",
"AGG"
],
"portfolio_weights": [
0.6,
0.1,
0.1,
0.1,
0.1
]
}' "https://api.hydrogenplatform.com/proton/v1/diversification_score"
ARGUMENTS
Parameter | Description |
---|---|
portfolio_tickers array, required |
Current portfolio tickers, referencing securities defined in the Nucleus API. |
portfolio_weights array, required |
Current portfolio weights, corresponding to tickers. |
start_date date |
Start date used for ticker price history. Defaults to the earliest common date among portfolio_tickers prices. |
end_date date |
End date used for ticker price history. Defaults to the latest common date among portfolio_tickers prices. |
Example Response
{
"portfolio_standard_deviation": 0.15359097006164063,
"holdings_standard_deviation": {
"AGG": 0.03539292330703836,
"AMZN": 0.30441576222578853,
"CMCSA": 0.1830429265788811,
"GOOGL": 0.2389454994916491,
"XOM": 0.20299112408344339
},
"diversification_score": 23
}
RESPONSE
Field | Description |
---|---|
portfolio_standard_deviation |
The annualized standard deviation of the overall portfolio. |
holdings_standard_deviation |
The annualized standard deviations of the individual portfolio holdings. |
diversification_score |
A score from 0 to 100, in which 0 indicates no diversification and 100 indicates the maximum theoretical diversification level. |
NUCLEUS DATA DEPENDENCIES
1. Securities: POST /security
2. Security Prices: POST /security_price
Financial Health Check
It is important to assess the health of a client’s financial situation in order to provide them with recommendations and guidance. This tool provides a financial health check by generating a series of financial ratios. After collecting information about the user’s assets, liabilities, income, and expenses, this tool returns ratio results and indicates a pass or fail based on a rule of thumb measure. The rule of thumb can be the system default or be overridden.
HTTP REQUEST
POST /financial_health_check
Example Request
curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
-H "Content-Type: application/json" \
-d '{
"liquid_assets": 5000,
"non_liquid_assets": 10000,
"short_term_liabilities": 11000,
"total_liabilities": 14000,
"gross_annual_income": 60000,
"net_monthly_income": 3500,
"monthly_expenses": 3000,
"ratio_targets": {
"liquidity_ratio_expenses": 2.5,
"liquidity_ratio_liabilities": 0.1,
"current_ratio": 0.5,
"asset_allocation_ratio": 1.5,
"savings_ratio_gross": 0.1,
"savings_ratio_net": 0.1
}
}' "https://api.hydrogenplatform.com/proton/v1/financial_health_check"
ARGUMENTS
Parameter | Description |
---|---|
liquid_assets float |
Value for the sum of cash and cash equivalents, checking accounts, savings accounts, money market accounts, money market mutual funds, CDs with short maturities, and similar assets. |
non_liquid_assets float |
Value for non-money market investment accounts, vehicles, real estate, business interests, personal property, the cash value of insurance policies, and similar assets. |
short_term_liabilities float |
Value for all debt and credit obligations, charges, bills, and payments due within one year. |
total_liabilities float |
Value for total liabilities, examples include mortgages, car loans, credit card balances, and student loans. Includes short_term_liabilities . |
gross_annual_income float |
Total amount of income earned annually before taxes. |
net_monthly_income float |
Take-home monthly pay after taxes and other payroll deductions. |
monthly_expenses float |
Value for average monthly living expenses. |
ratio_targets map |
Target values for each of the available financial ratios. These values are used as a benchmark for the financial health check and determine pass or fail. More information for these ratios can be found in the Appendix . |
liquidity_ratio_expenses float |
Target ratio value for liquidity_ratio_expenses . Defaults to 2.5 . The ratio value is calculated as liquid_assets / monthly_expenses . |
liquidity_ratio_liabilities float |
Target ratio value for liquidity_ratio_liabilities . Defaults to 0.1 . The ratio value is calculated as liquid_assets / total_liabilities . |
current_ratio float |
Target ratio value for current_ratio . Defaults to 0.5 . The ratio value is calculated as liquid_assets / short_term_liabilities . |
asset_allocation_ratio float |
Target ratio value for asset_allocation_ratio . Defaults to 1.5 . The ratio value is calculated as liquid_assets / net_worth . |
savings_ratio_gross float |
Target ratio value for savings_ratio_gross . Defaults to 0.1 . The ratio value is calculated as monthly_surplus / gross_monthly_income . |
savings_ratio_net float |
Target ratio value for savings_ratio_net . Defaults to 0.1 . The ratio value is calculated as monthly_surplus / net_monthly_income . |
Example Response
{
"liquidity_ratio_expenses": {
"ratio_result": 1.6667,
"pass": false,
"percentile_grade": 66
},
"liquidity_ratio_liabilities": {
"ratio_result": 0.3571,
"pass": true,
"percentile_grade": 100
},
"current_ratio": {
"ratio_result": 0.4545,
"pass": false,
"percentile_grade": 90
},
"asset_allocation_ratio": {
"ratio_result": 5,
"pass": true,
"percentile_grade": 100
},
"savings_ratio_gross": {
"ratio_result": 0.1,
"pass": true,
"percentile_grade": 100
},
"savings_ratio_net": {
"ratio_result": 0.1429,
"pass": true,
"percentile_grade": 100
},
"total_assets": 15000,
"net_worth": 1000,
"gross_monthly_income": 5000,
"monthly_surplus": 500
}
RESPONSE
Field | Description |
---|---|
liquidity_ratio_expenses |
Ratio measuring available liquidity with respect to ongoing expenses. |
ratio_result |
The ratio value, calculated as liquid_assets / monthly_expenses . |
pass |
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding value from ratio_targets , then pass is true . |
percentile_grade |
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the relevant value in ratio_targets . |
liquidity_ratio_liabilities |
Ratio measuring available liquidity with respect to liabilities. |
ratio_result |
The ratio value, calculated as liquid_assets / total_liabilities . |
pass |
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding value from ratio_targets , then pass is true . |
percentile_grade |
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the relevant value in ratio_targets . |
current_ratio |
Ratio measuring available liquidity with respect to short-term liabilities. |
ratio_result |
The ratio value, calculated as liquid_assets / short_term_liabilities . |
pass |
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding value from ratio_targets , then pass is true . |
percentile_grade |
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the relevant value in ratio_targets . |
asset_allocation_ratio |
Ratio measuring available liquidity with respect to net worth. |
ratio_result |
The ratio value, calculated as liquid_assets / net_worth . |
pass |
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding value from ratio_targets , then pass is true . |
percentile_grade |
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the relevant value in ratio_targets . |
savings_ratio_gross |
Ratio measuring savings potential with respect to gross income. |
ratio_result |
The ratio value, calculated as monthly_surplus / gross_monthly_income . |
pass |
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding value from ratio_targets , then pass is true . |
percentile_grade |
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the relevant value in ratio_targets . |
savings_ratio_net |
Ratio measuring savings potential with respect to net income. |
ratio_result |
The ratio value, calculated as monthly_surplus / net_monthly_income . |
pass |
A boolean indicating if ratio_result is sufficiently high. If ratio_result is greater than or equal to the corresponding value from ratio_targets , then pass is true . |
percentile_grade |
A linear percentile score for ratio_result on a scale from 0 to 100, where 100 represents the relevant value in ratio_targets . |
total_assets |
Total assets, calculated as liquid_assets + non_liquid_assets . |
net_worth |
Net worth, calculated as total_assets - total_liabilities . |
gross_monthly_income |
Gross monthly income, calculated as gross_annual_income / 12. |
monthly_surplus |
Net monthly surplus, calculated as net_monthly_income - monthly_expenses . |
Appendix
This appendix contains additional information to elaborate on the underlying algorithm methodology.
Financial Health
Financial Health Check
Applicable Proton Services
POST /financial_health_check
Methodology
The Financial Ratio Calculation results are compared to the Ideal Ratio. If the Financial Ratio is the Ideal Ratio Result or higher, the Ratio Test Result is marked as Pass. If the Financial Ratio is outside of the Ideal Ratio Result or lower, the Ratio Test Result is marked as Fail.
The Percentile Scale is calculated in the following way:
- If a Calculation Result is the Ideal Result or higher, the Percentile Scale returns 100
- If a Calculation Result is less than the the Ideal Result, the Percentile Scale returns = “Calculation Result” / “Ideal Result”
Notes & Considerations
Ideal Results & Ideal Direction of Outputs:
liquidity_ratio_expenses
: x >= 250% , Higherliquidity_ratio_liabilities
: x >= 10%, Highercurrent_ratio
: x >= 50% , Highersavings_ratio_gross
: x >= 10% , Highersavings_ratio_net
: x >= 10% , Higherasset_allocation_ratio
: x >= 15% , Higher
References
i. https://pdfs.semanticscholar.org/269d/5f90e8ce1951d74c61e2a3f8ed116c4eb021.pdf
ii. https://www.afcpe.org/assets/journals/vol_13.pdf
Goals
Goals Framework
Goals are described in terms of net purchasing power. This means that certain variables, including monetary inflation and taxes paid on the redemption of capital, are accounted for explicitly. For example, a target goal of 100 may correspond to an implied outcome of 125 if the capital is assumed to be taxed at a rate of 20% upon redemption. The purpose of this mechanism is to better reflect real-world purchasing power through the culmination of the goal horizon. Principal is assumed to be taken out first, followed by investment earnings. Separate tax rates can be specified for both principal and earnings.
All goals are classified as either accumulation or decumulation. Accumulation goals are defined by a target amount of capital in the future, assumed to be redeemed in full upon termination of the goal horizon. Decumulation goals are defined by redeeming a target amount of capital periodically over a horizon, which may also include an accumulation phase.
Configurations that involve contributions of capital (via an initial investment sum or an ongoing recurring deposit, for example) will prioritize a minimization of the present value of cash outlays. This built-in engine assumes that goal achievement with minimal cash expenditure is most desirable, ceteris paribus.
Goal achievement probabilities are extrapolated via Monte Carlo analysis. For more information on the Monte Carlo methodology, refer to the Monte Carlo Appendix section of this appendix. The distribution of outcomes generated by this process allows for an assessment of the likelihood that a goal will be attained. Please note that such goal probabilities are uncertain by nature, and repeating this type of simulation-based analysis may not yield precisely the same results.
Simulation results generated in the goals framework are returned on a yearly basis. The first item always indicates the investment value at t0, such that each simulation result for a 10-year goal horizon will contain 11 observations (t0 plus one observation for each year in the goal horizon).
Goal achievement indicators are derived from the relationship between goal achievement probability and a desired confidence target. Confidence targets serve as the basis for a percentile analysis of Monte Carlo outcomes, in which outcomes below the ((1 – c) * 100)th percentile, where c is the confidence target on a scale from 0 to 1, are excluded as a left-tail margin. If the confidence target is not satisfied, this is reflected by a goal probability that is less than the confidence target.
Because individual outcomes are binary in nature, the framework supports optional goal deviation thresholds in order to promote robustness. Thresholds may be set on an absolute basis or a percentage basis, and serve as an acceptable error margin on the nominal goal amount. For example, a goal of 10,000 modified with a 0.50% acceptable deviation threshold indicates that outcomes as low as 9,950 will be considered affirmative for goal achievement.
For decumulation goals, deposits are assumed to stop at the end of the accumulation horizon.
Goal Allocation Appendix
Applicable Proton Services
POST /goal_accumulation/allocation
POST /goal_decumulation/allocation
Methodology
For the “risk” allocation_priority, the chosen portfolio is based on the defined risk_score (see Risk Allocation for more information). For the “goal” allocation_priority, the engine searches through a series of potential goal plan configurations in which the portfolio risk and return change while the initial investment amount, periodic deposit amount, goal horizon, and target goal amount are held constant. The lowest risk portfolio that projects to meet the goal confidence target is chosen.
Notes & Considerations
- For a “goal” allocation_priority, the minimal risk portfolio that satisfies the goal will be chosen, but the risk_score parameter is not considered explicitly. This may lead to an investor being allocated to a portfolio that is riskier than suitable for a given risk appetite.
- For a “risk” allocation_priority, risk appetite is the driving factor, and this may lead to a goal not being successfully achieved.
Goal Recommendation Appendix
Applicable Proton Services
POST /goal_accumulation/recommendation
POST /goal_decumulation/recommendation
POST /goal_accumulation/status
POST /goal_decumulation/status
POST /goal_accumulation/allocation
POST /goal_decumulation/allocation
Methodology
The process of generating a recommendation entails constructing a set of potential new goal plans by changing specific plan components and holding others constant. The engine determines a minimum viable outcome by searching through the universe of potential goal plans.
“Recurring” recommendations leverage the introduction of a new periodic recurring deposit, without altering the initial investment amount, the goal horizon, the portfolio attributes, or the target goal amount. An available domain is constructed based on the dep_min and dep_max parameters, and discrete values in the domain serve as the basis of a new goal plan universe. The smallest periodic deposit that projects to meet the goal confidence target is recommended.
“One-time” recommendations leverage the introduction of a new one-time deposit, without altering the periodic deposit amount, the goal horizon, the portfolio attributes, or the target goal amount. One-time deposits are attributed at time zero, effectively increasing the initial investment amount component of the goal plan. An available domain is constructed based on the inv_min and inv_max parameters, and discrete values in the domain serve as the basis for a new goal plan universe. The smallest one-time deposit that projects to meet the goal confidence target is recommended.
“Combo” recommendations leverage the introduction of a new one-time deposit as well as a new periodic deposit, without altering the goal horizon, the portfolio attributes, or the target goal amount. One-time deposits are attributed at time zero, effectively increasing the initial investment amount component of the goal plan. An available domain is constructed based on the dep_min, dep_max, inv_min, and inv_max parameters. The permutation of a one-time deposit and recurring deposit with the smallest present value that projects to meet the goal confidence target is recommended.
“Horizon” recommendations leverage the introduction of a new accumulation horizon, without altering the initial investment amount, the periodic deposit amount, the portfolio attributes, or the target goal amount. An available domain is constructed by incrementing the original goal accumulation horizon forward, up to a maximum of 32 years above the original value. The shortest accumulation horizon that projects to meet the goal confidence target is recommended.
Notes & Considerations
- “Combo” recommendations, the domain of potential goal plans consists of all permutations of the potential one-time deposits and the potential recurring deposits.
Goal Tracking Appendix
Applicable Proton Services
POST /goal_accumulation/status
POST /goal_decumulation/status
Methodology
The current goal plan configuration is first used to execute a Monte Carlo simulation (see Monte Carlo Appendix section for more information). The result determines whether or not the goal is currently on track. For accumulation goals, in which the goal is defined by a total accumulation amount at the end of the accumulation horizon, final outcomes from the simulations must be greater than or equal to the target goal amount in order to be considered successful. For decumulation goals, in which the goal is defined by a periodic withdrawal amount over the course of the decumulation horizon, final outcomes from the simulations must be greater than zero in order to be considered successful. The goal probability (p) is computed as:
p = number of successes / number of simulations
The boolean tracking status is reported as true if p is greater than or equal to the user-defined confidence target, and reported as false if p is less than the user-defined confidence target.
Goal achievement scores are calculated by comparing p to the confidence target:
goal achievement score = p / confidence target
Goal progress is determined by comparing the current amount in the goal configuration to the target goal amount. For accumulation goals, this is defined as:
goal progress = current investment amount / target accumulation amount
For decumulation goals, a feasible decumulation amount is first estimated by lowering the target goal amount until the confidence target is satisfied. This answers the question: “If the decumulation horizon started today, what amount could be successfully withdrawn from the current balance over the desired decumulation horizon?” This value is used as the basis of the goal progress calculation, as follows:
goal progress = feasible decumulation amount / target decumulation amount
Notes & Considerations
- Goal achievement scores are normalized onto a 0-100 scale, where 0 indicates minimal likelihood of goal achievement and 100 coincides with an affirmative tracking status.
- If the recommend parameter is true, a recommendation will only be generated if the tracking status is negative.
Portfolio Construction
Mean-Variance Optimization Appendix
Applicable Proton Services
POST /mvo
POST /risk_allocation
POST /goal_accumulation/allocation
POST /goal_decumulation/allocation
Methodology
The model consumes an expected return for each security and the covariance relationships among all securities, which are derived directly from the security price data. Expected return is defined as the mean of a given security’s price distribution across the available data, while the covariance relationship between securities y and z is defined standardly as:
cov(y,z) = i=1n(y - y)(z - z)n - 1
The optimization process leverages a standard convex optimization protocol that solves problems via Second Order Cone Programming (SOCP)^{i}. Problems are structured with three primary elements: an Objective, a Variable, and Constraints. Here, the Objective is defined as a maximization of the portfolio mean return or a minimization of portfolio variance, the Variable is defined as an array of security weights, and the Constraints change based upon user input but include an upper or lower bound restriction on the portfolio’s return or variance. Other user-defined constraints include:
- w_config - A series of weight constraints by security type:
- Major securities are intended to be securities with more lenient weight thresholds.
- Minor securities are intended to be securities with tighter weight thresholds.
- Cash securities are constrained to a constant weight.
- w_asset_config - A series of weight constraints by security asset class:
- Asset class constraints set a maximum weight threshold that applies to the cumulative sum of weights across securities of a given asset class.
- min_assets - The minimum number of securities to be included in an optimized portfolio (formally defined as the number of non-zero weights, excluding cash).
For efficient frontier optimization, a series of problems is solved in the following order:
- A problem with an Objective to minimize portfolio variance.
- This derives the portfolio with the lowest possible risk, which serves as the frontier domain’s lower bound.
- A problem with an Objective to maximize portfolio return.
- This derives the portfolio with the highest possible return, which serves as the frontier domain’s upper bound.
- A problem with an Objective to maximize portfolio return for each risk value in the frontier domain, in ascending order.
- Variance values are chosen along a logarithmic path between the variance derived from (1) and the variance derived from (2).
- For each problem, the chosen variance is issued as an upper bound Constraint.
- To maintain integrity of the frontier shape, new ascending solutions are only recorded if the optimal portfolio return is higher than previous portfolio returns.
For target portfolio optimization, a single problem is configured as follows:
- When targeting a risk value, the objective is set to maximize portfolio return and an upper bound constraint is placed on the portfolio variance.
- When targeting a return value, the objective is set to minimize portfolio variance and a lower bound constraint is placed on the portfolio return.
Notes & Considerations
- Problem convexity is enforced via Disciplined Convex Programming (DCP) criteria^{ii}.
- Minimum weight constraints are joined with zero to form a binary constraint. Hence, the weight w is allowable if w = 0 or w ≥ min, but not if 0 < w < min.
- An error will be raised if the problem cannot be solved. This commonly occurs in two cases:
- When the security price data input into the model is incorrect or contains a very small amount of data points
- When the user-defined constraints are too restrictive
- A maximum of 30 portfolios will be generated on the efficient frontier.
References
i. https://web.stanford.edu/~boyd/cvxbook/bv_cvxbook.pdf
ii. http://dcp.stanford.edu/
Portfolio Management
Rebalancing Appendix
Applicable Proton Services
POST /rebalancing_signal
Methodology
This service generates trade signals to strategically rebalance a model portfolio, with support for three types of rebalancing: period-based, drift-based, and Downside Protection. Period-based rebalancing generates signals at the beginning of each time period with predefined frequency. Drift-based rebalancing generates signals when a portfolio holding deviates from its strategic target by a predefined amount. Downside Protection generates signals based on the observed risk of portfolio holdings, driven by Hydrogen’s proprietary risk management algorithm.
Hydrogen’s Downside Protection algorithm has four main goals:
- Limit drawdowns^{i}
- Reduce volatility and beta
- Track benchmarks on the upside
- Achieve superior risk-adjusted returns over the long-term
The primary driver of Downside Protection is dynamic asset allocation^{ii}, defined as a rules-based allocation strategy that includes responsiveness to market environments. Dynamic asset allocation differs from a passive or indexing strategy, which is static and not responsive (periodic or period-based rebalancing notwithstanding). Rebalancing within a dynamic framework is conditional rather than pre-determined. This also differs from an active strategy that uses forward-looking positions to try to take advantage of future market conditions. Dynamic allocations as described here are reactive and not predictive.
Hydrogen’s methodology utilizes a time-varying version of the CPPI^{iii} framework (called TPPI^{iv}). The time-varying portion is the level set for the floor, which changes based on market conditions and governs how rebalancing occurs. Based on quantitative risk measures looked at daily in the portfolio, the algorithm moves between risky and safe assets. The risky asset is weighted on a scale that ranges from 100% to 0% – meaning that the portfolio can be fully invested or fully protected at any given time, and can move up or down from each level in between. This allows the algorithm to ladder out of a position as it becomes riskier, and ladder in as it becomes less risky, in order to achieve an optimal mix for end-users.
The framework is extended for entire portfolios rather than for a single risky asset. Instead of looking at the portfolio as a whole, the algorithm assesses each holding individually to apply risk management, on a daily basis. This aims to achieve three objectives:
- Set optimal risk thresholds for each asset class. Commodities are much riskier than bonds, so different risk thresholds should apply.
- Limit transactions and transaction costs. By separating a portfolio into buckets, the algorithm avoids unnecessary transaction costs and maximizes the benefit of every trade.
- Maintain portfolio integrity. Each asset class has a strategic weight that acts as an anchor, so a given portfolio doesn’t get riskier than intended (only less risky, when necessary) and no leverage is ever used.
Trades are triggered by the ongoing risk of each security in the model portfolio. Risk is assessed based upon the moving average current drawdown of a security and standardized onto a 0-100 scale. Downside trading occurs in 3 levels, each of which is triggered when the risk assessment value moves across predefined thresholds on the risk scale. Each level is associated with a given amount of exposure, which is defined on a relative basis as a percentage of the security’s strategic weight. For example, a security may have levels of 75%, 50%, and 25% exposure triggered at 70, 80, and 90 risk assessment values. If the risk value moves from 69 to 71 for a given security, the security in question will be rebalanced to 75% of its original strategic weight. If the risk values drop from 71 back to 69, the security will be rebalanced to 100% of its strategic weight.
This framework can be applied to any type of portfolio – conservative or aggressive, diversified or concentrated, ETF-based or stock-based. Please note, using securities that have low liquidity may impede portfolio return through higher bid-ask spreads.
Notes & Considerations
- Each signal has an indicator for the applicable type of rebalancing:
- 1 = period-based rebalancing signal
- 2 = drift-based rebalancing signal
- 4 = Downside Protection rebalancing signal
- One portfolio may have multiple rebalancing types activated.
References
i. “Optimal Investment Strategies for Controlling Drawdowns” published in Mathematical Finance, July 1993, by Dr. Sanford Grossman and Dr. Zhongquan Zhou, professors at The Wharton School, University of Pennsylvania.
ii. “Dynamic Strategies for Asset Allocation” published in 1988 by Andre Perold of Harvard Business School and Nobel Prize winner William Sharpe.
iii. “CPPI – constant proportion portfolio insurance: protection with dynamic allocation control” published in 2006 by Martin Ermini from BNP Paribas. “Enhanced Balanced Portfolios With CPPI Methodologies” published in 2008 by Francesco Rossi of Pioneer Investments.
iv. “A Time-varying Proportion Portfolio Insurance Strategy Based on a CAViaR Approach” published in 2008 by Benjamin Hamidi, Bertrand Maillet, Jean-Luc Prigent, prominent financial academics in France.
Risk Scoring
Risk Score Appendix
Applicable Proton Services
POST /risk_score
Methodology
Answer values are normalized onto a [0,100] scale based on their relationship to the corresponding max_answers values. These transformed answer values (x) contribute to the weighted average (wa) as:
wax = w1x1 + w2x2 … wnxn
Notes & Considerations
- Higher answer values and max_answers values are assumed to indicate more appetite for risk.
- Weights default to be equally weighted.
Dimensional Risk Score Appendix
Applicable Proton Services
POST /dimensional_risk_score
Methodology
Answer values are first grouped by dimension, and then are normalized onto a [0,100] scale based on their relationship to the corresponding max_answers values. These transformed answer values (x) contribute to a series of dimensional scores (ds) based on answer weights (aw) as:
dsx = aw1x1 + aw2x2 … awnxn
These dimensional scores are then combined to compute the total weighted score (tws) based on dimensional weights (dw) as:
tws = dw1ds1 + dw2 ds2 … dwndsn
Notes & Considerations
- The framework can handle any number of distinct dimensions.
- Individual answers may be mapped to one or multiple risk dimensions.
- When more than one question map to a given dimension, proportional relationships between various answer weights serve as the basis for weighting answers within that dimension.
- If a given dimension has no answers mapped to it, it is dropped from consideration and any remaining values are re-normalized.
Risk Allocation Appendix
Applicable Proton Services
POST /risk_allocation
POST /goal_accumulation/allocation
POST /goal_decumulation/allocation
Methodology
The risk_score parameter, which is scaled from 0 to 100, is used to conduct a percentile analysis of the predefined portfolio risk values. When the target percentile falls between two portfolios, the risk value that is closer to the ideal percentile value on an absolute basis is chosen.
For the “create” allocation method, an efficient frontier domain is constructed based on the constraints defined in the opt_config parameter. The risk_score parameter, which is scaled from 0 to 100, is used to conduct a percentile analysis within the domain. A portfolio is then optimized, using the percentile value within the risk domain as a risk target (see the Mean-Variance Optimization Appendix section for more information).
Notes & Considerations
- The parameters
performance
andvolatility
must be defined in/allocation
if “select” is chosen. - For “select”, the portfolio with the closest match to the risk score will be selected.
Simulations
Backtest Appendix
Applicable Proton Services
POST /rebalancing_signal
POST /backtest
Methodology
At the beginning of each period during the backtest period, the time series data for each security of the portfolio model is incremented up to the current date of the analysis. Weights are adjusted based on the periodic performance of each security in the portfolio, and asset size updates are computed with a simple weighted average of positional performance. Trades are determined via the model’s rebalancing type, with the trading logic as follows:
For period-based rebalancing, the current date in the time series is analyzed on an absolute calendar basis. Annual period rebalancing to the model strategic weights is triggered if the date passes December 31st of a given year. Semiannual period rebalancing to the model strategic weights is triggered if the date passes June 30th of a given year. Quarterly period rebalancing to the model strategic weights is triggered if the date passes March 31st, June 30th, September 30th, or December 31st of a given year. Monthly period rebalancing to the model’s strategic weights is triggered if the current date’s month is greater than the previous date’s month.
For drift-based rebalancing, rebalancing to the model’s strategic weights is triggered if any security deviates from its strategic weight by a relative amount greater than its user-defined drift threshold. For example, a 10% drift factor applied to a security with a 20% strategic weight is triggered if the floating weight of the security falls below 18% or rises above 22%. When drift-based rebalancing is triggered, all securities in the portfolio are rebalanced to their respective strategic weights. For more information on downside protection, please see the Rebalancing Appendix section.
Notes & Considerations
- Drift thresholds are defined on a positional basis, and each portfolio security may have a unique drift factor.
- For Downside protection rebalancing, when the risk of a security triggers a trade, proceeds from any sale are shifted into a designated “safe” security. This safe security is assumed to be something with less risk than non-safe securities.
Monte Carlo Appendix
Applicable Proton Services
POST /monte_carlo
POST /goal_accumulation/recommendation
POST /goal_decumulation/recommendation
POST /goal_accumulation/status
POST /goal_decumulation/status
POST /goal_accumulation/allocation
POST /goal_decumulation/allocation
Methodology
- For each period in the Monte Carlo simulation, the initial balance is applied at time zero. For each subsequent period, the following process occurs:
- A return is sampled from a normal distribution with mu and sigma attributes defined by the user
- The ret_mod value is applied to the sampled return to derive a modified return
- The modified return is used to calculate a current balance from the previous balance
- The applicable periodic cash flow is applied to the calculated balance to get the resulting balance for the period
- If remove_outliers is true, an outlier analysis is performed on a median absolute deviation (MAD) basis, at the standard 2.5 threshold