NAV

Nucleus  Proton  Electron

curl

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:

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:

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

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

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:

Notes & Considerations

Ideal Results & Ideal Direction of Outputs:

  1. liquidity_ratio_expenses: x >= 250% , Higher
  2. liquidity_ratio_liabilities: x >= 10%, Higher
  3. current_ratio: x >= 50% , Higher
  4. savings_ratio_gross: x >= 10% , Higher
  5. savings_ratio_net: x >= 10% , Higher
  6. asset_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

Goal Allocation Appendix

Applicable Proton Services

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

Goal Recommendation Appendix

Applicable Proton Services

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

Goal Tracking Appendix

Applicable Proton Services

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

Portfolio Construction

Mean-Variance Optimization Appendix

Applicable Proton Services

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:

For efficient frontier optimization, a series of problems is solved in the following order:

  1. 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.
  2. 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.
  3. 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:

Notes & Considerations

References

i. https://web.stanford.edu/~boyd/cvxbook/bv_cvxbook.pdf
ii. http://dcp.stanford.edu/

Portfolio Management

Rebalancing Appendix

Applicable Proton Services

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:

The primary driver of Downside Protection is dynamic asset allocationii, 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 CPPIiii framework (called TPPIiv). 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:

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

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

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

Dimensional Risk Score Appendix

Applicable Proton Services

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

Risk Allocation Appendix

Applicable Proton Services

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

Simulations

Backtest Appendix

Applicable Proton Services

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

Monte Carlo Appendix

Applicable Proton Services

Methodology