NAV

Nucleus  Proton  Electron

curl java python ruby javascript

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

All Atom APIs use the same authentication and authorization. Please refer to the Nucleus API for detailed documentation.

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:

Changelog

Changes and updated versions will be outlined here. Stick around for version 2.0!

Date Change Description
2019-08-22 update Fixed a series of bugs: Enabled Financial Health Check to properly handle cases where the ratio denominator is 0. Updated Sensitivity Analysis & Scenario Analysis to manually override t-stat to None/null when it comes back as NaN. Updated Education Calculator & Retirement Calculator to prevent excess cash to be left in deposit_schedule at the end of the time horizon when an inflation rate was applied. Changed the order of fields in return_details within Annuity Calculator to be consistent with other endpoints, additionally, fixed a bug that sometimes prevented a successful analysis. Changed lag parameter in Sensitivity Analysis to be optional and default to 0. Finally, updated select error responses to be in proper JSON format.
2019-08-22 update Updated Emergency Fund Calculator to remove a restriction from the interest_rate parameter. Updated Savings Calculator to remove the constraint on the length of the return_schedule array. Added a series of new parameters to the Monte Carlo simulation. Added use_proxy_data to the following endpoints Mean-Variance Optimization, Event Study, Sensitivity Analysis, Scenario Analysis, Portfolio What If, Diversification Score, Portfolio Optimization Score, Goal Decumulation, Goal Accumulation, Risk Allocation, Variable Annuity. Added new response fields to the Financial Planning and Annuity Calculators to better summarize the output.
2019-08-22 addition Added three new services to the Personal Financial Management module: Budget Calculator, Cash Flow Analysis, and Financial Picture. The Cash Flow Analysis Tool displays trends related to the users spending and cash flow, allowing them to determine where they can cut down their spending and save money. The Financial Picture Tool runs analytics on all held-away accounts that have been aggregated so that the user may see a total picture of their financial life. The Budget Calculator pulls in the user’s spending and budget information from Nucleus, which is then used to generate insightful information about their budget by category and merchant. Finally, we added an additional service to the Annuities module: Variable Annuity; this service helps to evaluate potential outcomes and get a better understanding of how a variable annuity product may behave.
2019-03-26 update Fixed a bug in which certain Backtest requests would fail based on fluctuating model securities. Fixed a bug in which the impact of inflation was reflected inconsistently across Financial Planning calculators. Fixed a bug in which rates of return were incorrectly annualized in Portfolio Optimization Score. Fixed a bug in which the Mean-Variance Optimization service would not return frontier portfolios when one frontier point encountered an error. Fixed a bug in which Mean-Variance Optimization would fail based on the absence of optional security asset class data. Fixed a bug in which the arithmetic mean return was used instead of the geometric mean in Goals allocation services.
2019-03-26 update Introduced two new parameters to all services in the Goals module, adjust_for_compounding and compounding_rate, which help to approximate a compounding effect on deposits for specific request configurations.
2019-03-26 addition Added three new services to the Simulations module: Sensitivity Analysis, Scenario Analysis, and Portfolio What-If. These tools offer the ability to better understand an investment portfolio by simulating its behavior under a variety of circumstances. The former two services simulate the impact of external changes, while the latter considers changes within the portfolio itself.
2019-01-24 update Fixed a bug in the Goals module in which portfolio risk was improperly calculated when converting between certain time frequencies. Added handling for Mortgage Calculator cases in which down_payment could be negative.
2018-12-07 update Included new response fields for the Backtest service to summarize the risk and return of the backtested model.
2018-12-07 addition Added the Event Study service to the Simulations module, which simulates a portfolio’s behavior during key historical events. Added the Financial Health Check service to the Financial Health module, which offers the ability to assess an individual’s status through a series of financial ratios.
2018-11-12 addition Added two services to the Financial Health module: Portfolio Optimization Score, which evaluates a portfolio against its optimal counterpart, and Diversification Score, which assesses the level of diversification found in an investor’s portfolio. Added an Annuity module with five Annuity Calculator services for the analysis of fixed annuity streams.
2018-08-08 update Enhanced all services in the Goals module, making the framework more robust by allowing for greater levels of customization and the ability to handle a wider array of goal configurations.
2018-07-02 addition Added a suite of financial calculators, including Education, Mortgage, Life Insurance Needs, Major Purchase, Retirement, and Savings.

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,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0,
        "use_proxy_data": false
    }' "https://api.hydrogenplatform.com/proton/v1/goal_accumulation/allocation"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))

w_config = atom_api.GoalWeightConfig(w_min_major=0.05,
   w_max_major=1,
   w_min_minor=0.05,
   w_max_minor=0.1,
   cash_amount=0.0)
opt_config = atom_api.GoalOptConfig(tickers=["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
    min_assets=6,
    w_config=w_config,
    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")
deposit_config = atom_api.GoalDepositConfig(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 = atom_api.GoalConfig(goal_amount=25000,
    goal_inflation=0.0)
recommendation_config = atom_api.GoalRecommendationConfigStatus(recommend=True,
    inv_min=0,
    inv_max=1000,
    dep_min=0,
    dep_max=1000,
    horizon_min=1,
    horizon_max=10,
    recommended_inflation=0.0)
payload = atom_api.GoalAccumulationAllocation(
    allocation_method='create',
    allocation_priority='goal',
    allocations=["406ec16e-ebae-4130-a6c0-1cacb72569a2",
       "740f6466-3300-4122-927d-4a691359fa32",
       "0a02058f-4046-48de-b3d2-aeefd6d4efac"],
    opt_config=opt_config,
    risk_score=77,
    trading_days_per_year=252,
    horizon=5,
    horizon_frequency='year',
    deposit_config=[deposit_config],
    goal_config=goal_config,
    recommendation_config=recommendation_config,
    curr_inv=10000,
    recommend_type='recurring',
    conf_tgt=0.9,
    n=1000,
    remove_outliers=True,
    thresh_type='perc',
    thresh=0,
    withdrawal_tax=0.0,
    adjust_for_compounding=False,
    compounding_rate=0.0
)

try:
    # Goal accumulation allocation
    api_response = api_instance.goal_accumulation_allocation(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->goal_accumulation_allocation: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::GoalAccumulationAllocation.new
payload.allocation_method = "create"
payload.allocation_priority = "goal"
payload.allocations = ["406ec16e-ebae-4130-a6c0-1cacb72569a2",
   "740f6466-3300-4122-927d-4a691359fa32",
   "0a02058f-4046-48de-b3d2-aeefd6d4efac"]

opt_config = AtomApi::GoalOptConfig.new
opt_config.tickers = ["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"]
opt_config.min_assets = 6

w_config = AtomApi::GoalWeightConfig.new
w_config.w_min_major = 0.05
w_config.w_max_major = 1
w_config.w_min_minor = 0.05
w_config.w_max_minor = 0.1
w_config.cash_amount = 0.0
opt_config.w_config = w_config

opt_config.w_asset_config = {US_Equities => 1.0,
   Fixed_Income => 1.0,
   Intl_Equities => 1.0,
   EM_Equities => 1.0,
   Commodities => 1.0}
opt_config.sec_types = ["minor", "major", "minor", "minor", "minor", "minor"]
opt_config.start_date = "2016-01-01"
opt_config.end_date = "2017-01-01"

payload.opt_config = opt_config
payload.risk_score = 77
payload.trading_days_per_year = 252
payload.horizon = 5
payload.horizon_frequency = "year"

deposit_config = AtomApi::GoalDepositConfig.new
deposit_config.dep_start_reference = "a_start"
deposit_config.dep_start_period = 0
deposit_config.dep_end_reference = "a_start"
deposit_config.dep_end_period = 3
deposit_config.dep_amount = 2000
deposit_config.dep_frequency = "year"
deposit_config.dep_inflation = 0.0

payload.deposit_config = [deposit_config]

goal_config = AtomApi::GoalConfig.new
goal_config.goal_amount = 25000
goal_config.goal_inflation = 0.0
payload.goal_config = goal_config

recommendation_config = AtomApi::GoalRecommendationConfigStatus.new
recommendation_config.recommend = true
recommendation_config.inv_min = 0
recommendation_config.inv_max = 1000
recommendation_config.dep_min = 0
recommendation_config.dep_max = 1000
recommendation_config.horizon_min = 1
recommendation_config.horizon_max = 10
recommendation_config.recommended_inflation = 0.0

payload.recommendation_config = recommendation_config
payload.curr_inv = 10000
payload.recommend_type = "recurring"
payload.conf_tgt = 0.9
payload.n = 1000
payload.remove_outliers = true
payload.thresh_type = "perc"
payload.thresh = 0
payload.withdrawal_tax = 0.0
payload.adjust_for_compounding = false
payload.compounding_rate = 0.0

begin
  #Goal accumulation allocation
  result = api_instance.goal_accumulation_allocation(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->goal_accumulation_allocation: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

GoalWeightConfig wConfig = new GoalWeightConfig(wMinMajor=0.05,
    wMaxMajor=1,
    wMinMinor=0.05,
    wMaxMinor=0.1,
    cashAmount=0.0);

GoalOptConfig optConfig = new GoalOptConfig(tickers=["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
    minAssets=6,
    wConfig=wConfig,
    wAssetConfig={"US_Equities": 1.0,
      "Fixed_Income": 1.0,
      "Intl_Equities": 1.0,
      "EM_Equities": 1.0,
      "Commodities": 1.0},
    secTypes=["minor", "major", "minor", "minor", "minor", "minor"],
    startDate="2016-01-01",
    endDate="2017-01-01");

GoalDepositConfig depositConfig = new GoalDepositConfig(depStartReference="a_start",
    depStartPeriod=0,
    depEndPeriod=3,
    depAmount=2000,
    depFrequency="year",
    depInflation=0.0);

GoalConfig goalConfig = new GoalConfig(goalAmount=25000, goalInflation=0.0);

GoalRecommendationConfigStatus recommendationConfig = new GoalRecommendationConfigStatus(recommend=true,
   invMin=0,
   invMax=1000,
   depMin=0,
   depMax=1000,
   horizonMin=1,
   horizonMax=10,
   recommendedInflation=0.0);

GoalAccumulationAllocation payload = new GoalAccumulationAllocation(allocationMethod="create",
    allocationPriority="goal",
    allocations=["406ec16e-ebae-4130-a6c0-1cacb72569a2",
       "740f6466-3300-4122-927d-4a691359fa32",
       "0a02058f-4046-48de-b3d2-aeefd6d4efac"],
    optConfig=optConfig,
    riskScore=77,
    tradingDaysPerYear=252,
    horizon=5,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    goalConfig={"goal_amount": 25000, "goal_inflation": 0.0},
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
    compoundingRate=0.0);
try {
    GoalAllocationResponse result = apiInstance.goalAccumulationAllocation(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#goalAccumulationAllocation");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var wConfig = new atom_api.GoalWeightConfig(wMinMajor=0.05,
    wMaxMajor=1,
    wMinMinor=0.05,
    wMaxMinor=0.1,
    cashAmount=0.0)

var optConfig = new atom_api.GoalOptConfig(tickers=["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
     minAssets=6,
     wConfig=wConfig,
     wAssetConfig={"US_Equities": 1.0,
       "Fixed_Income": 1.0,
       "Intl_Equities": 1.0,
       "EM_Equities": 1.0,
       "Commodities": 1.0},
     secTypes=["minor", "major", "minor", "minor", "minor", "minor"],
     startDate="2016-01-01",
     endDate="2017-01-01")

var depositConfig = new atom_api.GoalDepositConfig(depStartReference="a_start",
   depStartPeriod=0,
   depEndPeriod=3,
   depAmount=2000,
   depFrequency="year",
   depInflation=0.0)

var goalConfig = new atom_api.GoalConfig(goalAmount=25000,
  goalInflation=0.0)

var recommendationConfig = new atom_api.GoalRecommendationConfigStatus(recommend=true,
   invMin=0,
   invMax=1000,
   depMin=0,
   depMax=1000,
   horizonMin=1,
   horizonMax=10,
   recommendedInflation=0.0)

var payload = new atom_api.GoalAccumulationAllocation(allocationMethod="create",
    allocationPriority="goal",
    allocations=["406ec16e-ebae-4130-a6c0-1cacb72569a2",
       "740f6466-3300-4122-927d-4a691359fa32",
       "0a02058f-4046-48de-b3d2-aeefd6d4efac"],
    optConfig=optConfig,
    riskScore=77,
    tradingDaysPerYear=252,
    horizon=5,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    goalConfig=goalConfig,
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
    compoundingRate=0.0);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.goalAccumulationAllocation(payload, callback);

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
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.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.

Example Response

{
    "current_status": {
        "on_track": false,
        "progress": 0.4,
        "goal_probability": 0.5937,
        "goal_achievement_score": 66,
        "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": 353.71,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 353.71,
                "cumulative_deposits": 2000,
                "cumulative_withdrawals": 0,
                "ending_balance": 12353.71
            },
            "2": {
                "period_earnings": 853.48,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 1207.19,
                "cumulative_deposits": 4000,
                "cumulative_withdrawals": 0,
                "ending_balance": 15207.19
            },
            "3": {
                "period_earnings": 1417.59,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 2624.78,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 18624.78
            },
            "4": {
                "period_earnings": 1569.72,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 4194.5,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 20194.5
            },
            "5": {
                "period_earnings": 1914.63,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 6109.14,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 22109.14
            }
        },
        "adjusted_goal_amount": 25000,
        "final_balance": 22109.14
    },
    "recommended_status": {
        "on_track": true,
        "progress": 0.4,
        "goal_probability": 0.9019,
        "goal_achievement_score": 100,
        "action": [
            {
                "value": 500,
                "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": 382.47,
                "period_deposit": 2500,
                "period_withdrawal": 0,
                "cumulative_earnings": 382.47,
                "cumulative_deposits": 2500,
                "cumulative_withdrawals": 0,
                "ending_balance": 12882.47
            },
            "2": {
                "period_earnings": 957.58,
                "period_deposit": 2500,
                "period_withdrawal": 0,
                "cumulative_earnings": 1340.05,
                "cumulative_deposits": 5000,
                "cumulative_withdrawals": 0,
                "ending_balance": 16340.05
            },
            "3": {
                "period_earnings": 1404.76,
                "period_deposit": 2500,
                "period_withdrawal": 0,
                "cumulative_earnings": 2744.81,
                "cumulative_deposits": 7500,
                "cumulative_withdrawals": 0,
                "ending_balance": 20244.81
            },
            "4": {
                "period_earnings": 1802.08,
                "period_deposit": 500,
                "period_withdrawal": 0,
                "cumulative_earnings": 4546.89,
                "cumulative_deposits": 8000,
                "cumulative_withdrawals": 0,
                "ending_balance": 22546.89
            },
            "5": {
                "period_earnings": 1993.62,
                "period_deposit": 500,
                "period_withdrawal": 0,
                "cumulative_earnings": 6540.5,
                "cumulative_deposits": 8500,
                "cumulative_withdrawals": 0,
                "ending_balance": 25040.5
            }
        },
        "adjusted_goal_amount": 25000,
        "final_balance": 25040.5
    },
    "allocation": {
        "ret": 0.1177,
        "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.
      final_balance The projected final balance from return_details.
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.
      final_balance The projected final balance from return_details.
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,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0
    }' "https://api.hydrogenplatform.com/proton/v1/goal_accumulation/recommendation"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_config = atom_api.GoalDepositConfig(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 = atom_api.GoalConfig(goal_amount=25000, goal_inflation=0.0)
recommendation_config = atom_api.GoalRecommendationConfigRec(inv_min=0,
     inv_max=1000,
     dep_min=0,
     dep_max=1000,
     horizon_min=1,
     horizon_max=10,
     recommended_inflation=0.0)
payload = atom_api.GoalAccumulationRecommendation(p_ret=[0.09],
    p_risk=[0.05],
    trading_days_per_year=252,
    horizon=5,
    horizon_frequency="year",
    deposit_config=[deposit_config],
    goal_config=goal_config,
    recommendation_config=recommendation_config,
    curr_inv=10000,
    recommend_type="recurring",
    conf_tgt=0.9,
    n=1000,
    remove_outliers=True,
    thresh_type="perc",
    thresh=0,
    withdrawal_tax=0.0,
    adjust_for_compounding=False,
    compounding_rate=0.0)

try:
    # Goal accumulation recommendation
    api_response = api_instance.goal_accumulation_recommendation(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->goal_accumulation_recommendation: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::GoalAccumulationRecommendation.new
payload.p_ret = [0.09]
payload.p_risk = [0.05]
payload.trading_days_per_year = 252
payload.horizon = 5
payload.horizon_frequency = "year"

deposit = AtomApi::GoalDepositConfig.new
deposit.dep_start_reference = "a_start"
deposit.dep_start_period = 0
deposit.dep_end_reference = "a_start"
deposit.dep_end_period = 3
deposit.dep_amount = 2000
deposit.dep_frequency = "year"
deposit.dep_inflation = 0.0

payload.deposit_config = [deposit]

goal_config = AtomApi::GoalConfig.new
goal_config.goal_amount = 25000
goal_config.goal_inflation = 0.0
payload.goal_config = goal_config

recommendation_config = AtomApi::GoalRecommendationConfigStatus.new
recommendation_config.recommend = true
recommendation_config.inv_min = 0
recommendation_config.inv_max = 1000
recommendation_config.dep_min = 0
recommendation_config.dep_max = 1000
recommendation_config.horizon_min = 1
recommendation_config.horizon_max = 10
recommendation_config.recommended_inflation = 0.0
payload.recommendation_config = recommendation_config
payload.curr_inv = 10000
payload.recommend_type = "recurring"
payload.conf_tgt = 0.9
payload.n = 1000
payload.remove_outliers = true
payload.thresh_type = "perc"
payload.thresh = 0
payload.withdrawal_tax = 0.0
payload.adjust_for_compounding = false
payload.compounding_rate = 0.0

begin
  #Goal accumulation recommendation
  result = api_instance.goal_accumulation_recommendation(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->goal_accumulation_recommendation: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

GoalDepositConfig depositConfig = new GoalDepositConfig(depStartReference="a_start",
    depStartPeriod=0,
    depEndPeriod=3,
    depAmount=2000,
    depFrequency="year",
    depInflation=0.0);

GoalConfig goalConfig = new GoalConfig(goalAmount=25000, goalInflation=0.0);

GoalRecommendationConfigRec recommendationConfig = new GoalRecommendationConfigRec(invMin=0,
   invMax=1000,
   depMin=0,
   depMax=1000,
   horizonMin=1,
   horizonMax=10,
   recommendedInflation=0.0);

GoalAccumulationRecommendation payload = new GoalAccumulationRecommendation(pRet=[0.09],
    pRisk=[0.05],
    tradingDaysPerYear=252,
    horizon=5,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    goalConfig=goalConfig,
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
    compoundingRate=0.0);
try {
    GoalRecommendationResponse result = apiInstance.goalAccumulationRecommendation(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#goalAccumulationRecommendation");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositConfig = new atom_api.GoalDepositConfig(depStartReference="a_start",
   depStartPeriod=0,
   depEndPeriod=3,
   depAmount=2000,
   depFrequency="year",
   depInflation=0.0)

var goalConfig = new atom_api.GoalConfig(goalAmount=25000, goalInflation=0.0)

var recommendationConfig = new atom_api.GoalRecommendationConfigRec(invMin=0,
    invMax=1000,
    depMin=0,
    depMax=1000,
    horizonMin=1,
    horizonMax=10,
    recommendedInflation=0.0)

var payload = new atom_api.GoalAccumulationRecommendation(pRet=[0.09],
    pRisk=[0.05],
    tradingDaysPerYear=252,
    horizon=5,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    goalConfig=goalConfig,
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
    compoundingRate=0.0);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.goalAccumulationRecommendation(payload, callback);

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.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.

Example Response

{
    "on_track": true,
    "progress": 0.4,
    "goal_probability": 0.915,
    "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": 271.88,
            "period_deposit": 2796.88,
            "period_withdrawal": 0,
            "cumulative_earnings": 271.88,
            "cumulative_deposits": 2796.88,
            "cumulative_withdrawals": 0,
            "ending_balance": 13068.75
        },
        "2": {
            "period_earnings": 813.47,
            "period_deposit": 2796.88,
            "period_withdrawal": 0,
            "cumulative_earnings": 1085.35,
            "cumulative_deposits": 5593.75,
            "cumulative_withdrawals": 0,
            "ending_balance": 16679.1
        },
        "3": {
            "period_earnings": 1057.48,
            "period_deposit": 2796.88,
            "period_withdrawal": 0,
            "cumulative_earnings": 2142.83,
            "cumulative_deposits": 8390.62,
            "cumulative_withdrawals": 0,
            "ending_balance": 20533.46
        },
        "4": {
            "period_earnings": 1364.75,
            "period_deposit": 796.88,
            "period_withdrawal": 0,
            "cumulative_earnings": 3507.59,
            "cumulative_deposits": 9187.5,
            "cumulative_withdrawals": 0,
            "ending_balance": 22695.09
        },
        "5": {
            "period_earnings": 1735.93,
            "period_deposit": 796.88,
            "period_withdrawal": 0,
            "cumulative_earnings": 5243.52,
            "cumulative_deposits": 9984.38,
            "cumulative_withdrawals": 0,
            "ending_balance": 25227.89
        }
    },
    "adjusted_goal_amount": 25000,
    "final_balance": 25227.89
}

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.
final_balance The projected final balance from return_details.

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,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0
    }' "https://api.hydrogenplatform.com/proton/v1/goal_accumulation/status"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_config = atom_api.GoalDepositConfig(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 = atom_api.GoalConfig(goal_amount=25000, goal_inflation=0.0)
recommendation_config = atom_api.GoalRecommendationConfigStatus(recommend=True,
    inv_min=0,
    inv_max=1000,
    dep_min=0,
    dep_max=1000,
    horizon_min=1,
    horizon_max=10,
    recommended_inflation=0.0)
payload = atom_api.GoalAccumulationStatus(p_ret=[0.09],
    p_risk=[0.05],
    trading_days_per_year=252,
    horizon=5,
    horizon_frequency="year",
    deposit_config=[deposit_config],
    goal_config=goal_config,
    recommendation_config=recommendation_config,
    curr_inv=10000,
    recommend_type="recurring",
    conf_tgt=0.9,
    n=1000,
    remove_outliers=True,
    thresh_type="perc",
    thresh=0,
    withdrawal_tax=0.0,
    adjust_for_compounding=False,
    compounding_rate=0.0)

try:
    # Goal accumulation status
    api_response = api_instance.goal_accumulation_status(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->goal_accumulation_status: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::GoalAccumulationStatus.new
payload.p_ret = [0.09]
payload.p_risk = [0.05]
payload.trading_days_per_year = 252
payload.horizon = 5
payload.horizon_frequency = "year"

deposit_config = AtomApi::GoalDepositConfig.new
deposit_config.dep_start_reference = "a_start"
deposit_config.dep_start_period = 0
deposit_config.dep_end_reference = "a_start"
deposit_config.dep_end_period = 3
deposit_config.dep_amount = 2000
deposit_config.dep_frequency = "year"
deposit_config.dep_inflation = 0.0

payload.deposit_config = [deposit_config]

goal_config = AtomApi::GoalConfig.new
goal_config.goal_amount = 25000
goal_config.goal_inflation = 0.0
payload.goal_config = goal_config

recommendation_config = AtomApi::GoalRecommendationConfigStatus.new
recommendation_config.recommend = true
recommendation_config.inv_min = 0
recommendation_config.inv_max = 1000
recommendation_config.dep_min = 0
recommendation_config.dep_max = 1000
recommendation_config.horizon_min = 1
recommendation_config.horizon_max = 10
recommendation_config.recommended_inflation = 0.0

payload.recommendation_config = recommendation_config
payload.curr_inv = 10000
payload.recommend_type = "recurring"
payload.conf_tgt => 0.9
payload.n = 1000
payload.remove_outliers = true
payload.thresh_type = "perc"
payload.thresh = 0
payload.withdrawal_tax = 0.0
payload.adjust_for_compounding = false
payload.compounding_rate = 0.0

begin
  #Goal accumulation status
  result = api_instance.goal_accumulation_status(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->goal_accumulation_status: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

GoalDepositConfig depositConfig = new GoalDepositConfig(depStartReference="a_start",
    depStartPeriod=0,
    depEndPeriod=3,
    depAmount=2000,
    depFrequency="year",
    depInflation=0.0);

GoalConfig goalConfig = new GoalConfig(goalAmount=25000, goalInflation=0.0);

GoalRecommendationConfigStatus recommendationConfig = new GoalRecommendationConfigStatus(recommend=true,
   invMin=0,
   invMax=1000,
   depMin=0,
   depMax=1000,
   horizonMin=1,
   horizonMax=10,
   recommendedInflation=0.0);

GoalAccumulationStatus payload = new GoalAccumulationStatus(pRet=[0.09],
    pRisk=[0.05],
    tradingDaysPerYear=252,
    horizon=5,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    goalConfig=goalConfig,
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendedType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
    compoundingRate=0.0);
try {
    GoalStatusResponse result = apiInstance.goalAccumulationStatus(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#goalAccumulationStatus");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositConfig = new atom_api.GoalDepositConfig(depStartReference="a_start",
   depStartPeriod=0,
   depEndReference="a_start",
   depEndPeriod=3,
   depAmount=2000,
   depFrequency="year",
   depInflation=0.0)

var goalConfig = new atom_api.GoalConfig(goalAmount=25000, goalInflation=0.0)

var recommendationConfig = new atom_api.GoalRecommendationConfigStatus(recommend=true,
   invMin=0,
   invMax=1000,
   depMin=0,
   depMax=1000,
   horizonMin=1,
   horizonMax=10,
   recommendedInflation=0.0)

var payload = new atom_api.GoalAccumulationStatus(pRet=[0.09],
    pRisk=[0.05],
    tradingDaysPerYear=252,
    horizon=5,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    goalConfig=goalConfig,
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendedType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
    compoundingRate=0.0);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.goalAccumulationStatus(payload, callback);

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.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.

Example Response

{
    "current_status": {
        "on_track": false,
        "progress": 0.4,
        "goal_probability": 0.1638,
        "goal_achievement_score": 18,
        "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": 274.26,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 274.26,
                "cumulative_deposits": 2000,
                "cumulative_withdrawals": 0,
                "ending_balance": 12274.26
            },
            "2": {
                "period_earnings": 665.94,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 940.19,
                "cumulative_deposits": 4000,
                "cumulative_withdrawals": 0,
                "ending_balance": 14940.19
            },
            "3": {
                "period_earnings": 954.05,
                "period_deposit": 2000,
                "period_withdrawal": 0,
                "cumulative_earnings": 1894.25,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 17894.25
            },
            "4": {
                "period_earnings": 1068.64,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 2962.89,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 18962.89
            },
            "5": {
                "period_earnings": 1479.72,
                "period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 4442.61,
                "cumulative_deposits": 6000,
                "cumulative_withdrawals": 0,
                "ending_balance": 20442.61
            }
        },
        "adjusted_goal_amount": 25000,
        "final_balance": 20442.61
    },
    "recommended_status": {
        "on_track": true,
        "progress": 0.4,
        "goal_probability": 0.9025,
        "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": 302.11,
                "period_deposit": 2781.25,
                "period_withdrawal": 0,
                "cumulative_earnings": 302.11,
                "cumulative_deposits": 2781.25,
                "cumulative_withdrawals": 0,
                "ending_balance": 13083.36
            },
            "2": {
                "period_earnings": 749.04,
                "period_deposit": 2781.25,
                "period_withdrawal": 0,
                "cumulative_earnings": 1051.14,
                "cumulative_deposits": 5562.5,
                "cumulative_withdrawals": 0,
                "ending_balance": 16613.64
            },
            "3": {
                "period_earnings": 1059.19,
                "period_deposit": 2781.25,
                "period_withdrawal": 0,
                "cumulative_earnings": 2110.34,
                "cumulative_deposits": 8343.75,
                "cumulative_withdrawals": 0,
                "ending_balance": 20454.09
            },
            "4": {
                "period_earnings": 1443.06,
                "period_deposit": 781.25,
                "period_withdrawal": 0,
                "cumulative_earnings": 3553.4,
                "cumulative_deposits": 9125,
                "cumulative_withdrawals": 0,
                "ending_balance": 22678.4
            },
            "5": {
                "period_earnings": 1579.8,
                "period_deposit": 781.25,
                "period_withdrawal": 0,
                "cumulative_earnings": 5133.2,
                "cumulative_deposits": 9906.25,
                "cumulative_withdrawals": 0,
                "ending_balance": 25039.45
            }
        },
        "adjusted_goal_amount": 25000,
        "final_balance": 25039.45
    }
}

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.
      final_balance The projected final balance from return_details.
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.
      final_balance The projected final balance from return_details.

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,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0,
        "use_proxy_data": false
    }' "https://api.hydrogenplatform.com/proton/v1/goal_decumulation/allocation"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
w_config = atom_api.GoalWeightConfig(w_min_major=0.05,
   w_max_major=1,
   w_min_minor=0.05,
   w_max_minor=0.1,
   cash_amount=0.0)
opt_config = atom_api.GoalOptConfig(tickers=["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
    min_assets=6,
    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")
deposit_config = atom_api.GoalDepositConfig(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 = atom_api.GoalWithdrawalConfig(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 = atom_api.GoalRecommendationConfigStatus(recommend=True,
    inv_min=0,
    inv_max=1000,
    dep_min=0,
    dep_max=1000,
    horizon_min=1,
    horizon_max=10,
    recommended_inflation=0.0)
payload = atom_api.GoalDecumulationAllocation(allocation_method="create",
    allocation_priority="goal",
    allocations=[
        "406ec16e-ebae-4130-a6c0-1cacb72569a2",
        "740f6466-3300-4122-927d-4a691359fa32",
        "0a02058f-4046-48de-b3d2-aeefd6d4efac"
    ],
    opt_config=opt_config,
    risk_score=77,
    trading_days_per_year=252,
    a_horizon=3,
    d_horizon=2,
    horizon_frequency="year",
    deposit_config=[deposit_config],
    withdrawal_config=[withdrawal_config],
    recommendation_config=recommendation_config,
    curr_inv=10000,
    recommend_type="recurring",
    conf_tgt=0.9,
    n=1000,
    remove_outliers=True,
    thresh_type="perc",
    thresh=0,
    withdrawal_tax=0.0,
    adjust_for_compounding=False,
    compounding_rate=0.0)

try:
    # Goal decumulation allocation
    api_response = api_instance.goal_decumulation_allocation(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->goal_decumulation_allocation: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::GoalDecumulationAllocation.new
payload.allocation_method = "create"
payload.allocation_priority = "goal"
payload.allocations = ["406ec16e-ebae-4130-a6c0-1cacb72569a2",
   "740f6466-3300-4122-927d-4a691359fa32",
   "0a02058f-4046-48de-b3d2-aeefd6d4efac"]

opt_config = AtomApi::GoalOptConfig.new
opt_config.tickers = ["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"]
opt_config.min_assets = 6

w_config = AtomApi::GoalWeightConfig.new
w_config.w_min_major = 0.05
w_config.w_max_major = 1
w_config.w_min_minor = 0.05
w_config.w_max_minor = 0.1
w_config.cash_amount = 0.0
opt_config.w_config = w_config

opt_config.w_asset_config = {US_Equities => 1.0,
   Fixed_Income => 1.0,
   Intl_Equities => 1.0,
   EM_Equities => 1.0,
   Commodities => 1.0}
opt_config.sec_types = ["minor", "major", "minor", "minor", "minor", "minor"]
opt_config.start_date = "2016-01-01"
opt_config.end_date = "2017-01-01"

payload.opt_config = opt_config

deposit_config = AtomApi::GoalDepositConfig.new
deposit_config.dep_start_reference = "a_start"
deposit_config.dep_start_period = 0
deposit_config.dep_end_reference = "a_start"
deposit_config.dep_end_period = 3
deposit_config.dep_amount = 2000
deposit_config.dep_frequency = "year"
deposit_config.dep_inflation = 0.0

payload.deposit_config = [deposit_config]

goal_config = AtomApi::GoalConfig.new
goal_config.goal_amount = 25000
goal_config.goal_inflation = 0.0
payload.goal_config = goal_config

recommendation_config = AtomApi::GoalRecommendationConfigStatus.new
recommendation_config.recommend = true
recommendation_config.inv_min = 0
recommendation_config.inv_max = 1000
recommendation_config.dep_min = 0
recommendation_config.dep_max = 1000
recommendation_config.horizon_min = 1
recommendation_config.horizon_max = 10
recommendation_config.recommended_inlation = 0.0

payload.risk_score = 77
payload.trading_days_per_year = 252
payload.a_horizon = 3
payload.d_horizon = 2
payload.horizon_frequency = "year"

withdrawal_config = AtomApi::GoalWithdrawalConfig.new
withdrawal_config.with_amount = 11000
withdrawal_config.with_start_reference = "a_end"
withdrawal_config.with_start_period = 0
withdrawal_config.with_end_reference = "d_end"
withdrawal_config.with_end_period = 0
withdrawal_config.with_frequency = "year"
withdrawal_config.with_inflation = 0.0
payload.withdrawal_config = [withdrawal_config]
payload.curr_inv = 10000
payload.recommend_type = "recurring"
payload.conf_tgt = 0.9
payload.n = 1000
payload.remove_outliers = true
payload.thresh_type = "perc"
payload.thresh = 0
payload.withdrawal_tax = 0.0
payload.adjust_for_compounding = false
payload.compounding_rate = 0.0

begin
  #Goal decumulation allocation
  result = api_instance.goal_decumulation_allocation(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->goal_decumulation_allocation: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

GoalWeightConfig wConfig = new GoalWeightConfig(wMinMajor=0.05,
    wMaxMajor=1,
    wMinMinor=0.05,
    wMaxMinor=0.1,
    cashAmount=0.0);

GoalOptConfig optConfig = new GoalOptConfig(tickers=["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
      minAssets=6,
      wConfig=wConfig,
      wAssetConfig={"US_Equities": 1.0,
        "Fixed_Income": 1.0,
        "Intl_Equities": 1.0,
        "EM_Equities": 1.0,
        "Commodities": 1.0},
      secTypes=["minor", "major", "minor", "minor", "minor", "minor"],
      startDate="2016-01-01",
      endDate="2017-01-01");

GoalDepositConfig depositConfig = new GoalDepositConfig(depStartReference="a_start",
    depStartPeriod=0,
    depEndPeriod=3,
    depAmount=2000,
    depFrequency="year",
    depInflation=0.0);

GoalWithdrawalConfig withdrawalConfig = new GoalWithdrawalConfig(withAmount=11000,
   withStartReference="a_end",
   withStartPeriod=0,
   withEndReference="d_end",
   withEndPeriod=0,
   withFrequency="year",
   withInflation=0.0);

GoalRecommendationConfigStatus recommendationConfig = new GoalRecommendationConfigStatus(recommend=true,
   invMin=0,
   invMax=1000,
   depMin=0,
   depMax=1000,
   horizonMin=1,
   horizonMax=10,
   recommendedInflation=0.0);

GoalDecumulationAllocation payload = new GoalDecumulationAllocation(allocationMethod="create",
    allocationPriority="goal",
    allocations=["406ec16e-ebae-4130-a6c0-1cacb72569a2",
       "740f6466-3300-4122-927d-4a691359fa32",
       "0a02058f-4046-48de-b3d2-aeefd6d4efac"],
    optConfig=optConfig,
    riskScore=77,
    tradingDaysPerYear=252,
    aHorizon=3,
    dHorizon=2,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    withdrawalConfig=[withdrawalConfig],
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
      compoundingRate=0.0);
try {
    GoalAllocationResponse result = apiInstance.goalDecumulationAllocation(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#goalDecumulationAllocation");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var wConfig = new atom_api.GoalWeightConfig(wMinMajor=0.05,
    wMaxMajor=1,
    wMinMinor=0.05,
    wMaxMinor=0.1,
    cashAmount=0.0)

var optConfig = new atom_api.GoalOptConfig(tickers=["KHC", "AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
   minAssets=6,
   wAssetConfig={"US_Equities": 1.0,
       "Fixed_Income": 1.0,
       "Intl_Equities": 1.0,
       "EM_Equities": 1.0,
       "Commodities": 1.0},
   secTypes=["minor", "major","minor", "minor", "minor", "minor"],
   startDate="2016-01-01",
   endDate="2017-01-01")

var depositConfig = new atom_api.GoalDepositConfig(depStartReference="a_start",
   depStartPeriod=0,
   depEndReference="a_start",
   depEndPeriod=3,
   depAmount=2000,
   depFrequency="year",
   depInflation=0.0)

var withdrawalConfig = new atom_api.GoalWithdrawalConfig(withAmount=11000,
   withStartReference="a_end",
   withStartPeriod=0,
   withEndReference="d_end",
   withEndPeriod=0,
   withFrequency="year",
   withInflation=0.0)

var recommendationConfig = new atom_api.GoalRecommendationConfigStatus(recommend=true,
   invMin=0,
   invMax=1000,
   depMin=0,
   depMax=1000,
   horizonMin=1,
   horizonMax=10,
   recommendedInflation=0.0)

var payload = new atom_api.GoalDecumulationAllocation(allocationMethod="create",
    allocationPriority="goal",
    allocations=["406ec16e-ebae-4130-a6c0-1cacb72569a2",
       "740f6466-3300-4122-927d-4a691359fa32",
       "0a02058f-4046-48de-b3d2-aeefd6d4efac"],
    optConfig=optConfig,
    riskScore=77,
    tradingDaysPerYear=252,
    aHorizon=3,
    dHorizon=2,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    withdrawalConfig=[withdrawalConfig],
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
    compoundingRate=0.0);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.goalDecumulationAllocation(payload, callback);

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
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.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.

Example Response

{
    "current_status": {
        "on_track": false,
        "progress": 0.4545,
        "goal_probability": 0.8342,
        "goal_achievement_score": 93,
        "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": 326.32,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 326.32,
                "accumulation_cumulative_deposit": 2000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 12326.32
            },
            "2": {
                "period_earnings": 1033.7,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 1360.02,
                "accumulation_cumulative_deposit": 4000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 15360.02
            },
            "3": {
                "period_earnings": 1245.48,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 2605.5,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 18605.5
            },
            "4": {
                "period_earnings": 1669.58,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 4275.09,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 11000,
                "ending_balance": 9275.09
            },
            "5": {
                "period_earnings": 0,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 9275.09,
                "cumulative_earnings": 4275.09,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 20275.09,
                "ending_balance": 0
            }
        },
        "accumulation_balance": 18605.5
    },
    "recommended_status": {
        "on_track": true,
        "progress": 0.4545,
        "goal_probability": 0.9065,
        "goal_achievement_score": 100,
        "action": [
            {
                "value": 218.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": 355.11,
                "accumulation_period_deposit": 2218.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 355.11,
                "accumulation_cumulative_deposit": 2218.75,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 12573.86
            },
            "2": {
                "period_earnings": 1040.96,
                "accumulation_period_deposit": 2218.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 1396.07,
                "accumulation_cumulative_deposit": 4437.5,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 15833.57
            },
            "3": {
                "period_earnings": 1230.63,
                "accumulation_period_deposit": 2218.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 2626.7,
                "accumulation_cumulative_deposit": 6656.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 19282.95
            },
            "4": {
                "period_earnings": 1864.12,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 4490.82,
                "accumulation_cumulative_deposit": 6656.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 11000,
                "ending_balance": 10147.07
            },
            "5": {
                "period_earnings": 988.6,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 5479.43,
                "accumulation_cumulative_deposit": 6656.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 22000,
                "ending_balance": 135.68
            }
        },
        "accumulation_balance": 19282.95
    },
    "allocation": {
        "ret": 0.1177,
        "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.
      accumulation_balance The projected balance at the end of the accumulation horizon.
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.
      accumulation_balance The projected balance at the end of the accumulation horizon.
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,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0
    }' "https://api.hydrogenplatform.com/proton/v1/goal_decumulation/recommendation"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_config = atom_api.GoalDepositConfig(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 = atom_api.GoalWithdrawalConfig(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 = atom_api.GoalRecommendationConfigRec(inv_min=0,
   inv_max=1000,
   dep_min=0,
   dep_max=1000,
   horizon_min=1,
   horizon_max=10,
   recommended_inflation=0.0)
payload = atom_api.GoalDecumulationRecommendation(p_ret=[0.09],
    p_risk=[0.05],
    trading_days_per_year=252,
    a_horizon=3,
    d_horizon=2,
    horizon_frequency="year",
    deposit_config=[deposit_config],
    withdrawal_config=[withdrawal_config],
    recommendation_config=recommendation_config,
    curr_inv=10000,
    recommend_type="recurring",
    conf_tgt=0.9,
    n=1000,
    remove_outliers=True,
    thresh_type="perc",
    thresh=0,
    withdrawal_tax=0.0,
    adjust_for_compounding=False,
    compounding_rate=0.0)

try:
    # Goal decumulation recommendation
    api_response = api_instance.goal_decumulation_recommendation(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->goal_decumulation_recommendation: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::GoalDecumulationRecommendation.new
payload.p_ret = [0.09]
payload.p_risk = [0.05]
payload.trading_days_per_year = 252
payload.a_horizon = 3
payload.d_horizon = 2
payload.horizon_frequency = "year"

deposit_config = AtomApi::GoalDepositConfig.new
deposit_config.dep_start_reference = "a_start"
deposit_config.dep_start_period = 0
deposit_config.dep_end_reference = "a_start"
deposit_config.dep_end_period = 3
deposit_config.dep_amount = 2000
deposit_config.dep_frequency = "year"
deposit_config.dep_inflation = 0.0
payload.deposit_config = [deposit_config]

withdrawal_config = AtomApi::GoalWithdrawalConfig.new
withdrawal_config.with_amount = 11000
withdrawal_config.with_start_reference = "a_end"
withdrawal_config.with_start_period = 0
withdrawal_config.with_end_reference = "d_end"
withdrawal_config.with_end_period = 0
withdrawal_config.with_frequency = "year"
withdrawal_config.with_inflation = 0.0
payload.withdrawal_config = [withdrawal_config]

recommendation_config = AtomApi::GoalRecommendationConfigRec.new
recommendation_config.inv_min = 0
recommendation_config.inv_max = 1000
recommendation_config.dep_min = 0
recommendation_config.dep_max = 1000
recommendation_config.horizon_min = 1
recommendation_config.horizon_max = 10
recommendation_config.recommended_inflation = 0.0
payload.recommendation_config = recommendation_config
payload.curr_inv = 10000
payload.recommend_type = "recurring"
payload.conf_tgt = 0.9
payload.n = 1000
payload.remove_outliers = true
payload.thresh_type = "perc"
payload.thresh = 0
payload.withdrawal_tax = 0.0
payload.adjust_for_compounding = false
payload.compounding_rate = 0.0

begin
  #Goal decumulation recommendation
  result = api_instance.goal_decumulation_recommendation(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->goal_decumulation_recommendation: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

GoalDepositConfig depositConfig = new GoalDepositConfig(depStartReference="a_start",
    depStartPeriod=0,
    depEndReference="a_start",
    depEndPeriod=3,
    depAmount=2000,
    depFrequency="year",
    depInflation=0.0);

GoalWithdrawalConfig withdrawalConfig = new GoalWithdrawalConfig(withAmount=11000,
     withStartReference="a_end",
     withStartPeriod=0,
     withEndReference="d_end",
     withEndPeriod=0,
     withFrequency="year",
     withInflation=0.0);

GoalRecommendationConfigRec recommendationConfig = new GoalRecommendationConfigRec(invMin=0,
     invMax=1000,
     depMin=0,
     depMax=1000,
     horizonMin=1,
     horizonMax=10,
     recommendedInflation=0.0);

GoalDecumulationRecommendation payload = new GoalDecumulationRecommendation(pRet=[0.09],
    pRisk=[0.05],
    tradingDaysPerYear=252,
    aHorizon=3,
    dHorizon=2,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    withdrawalConfig=[withdrawalConfig],
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
    compoundingRate=0.0);
try {
    GoalRecommendationResponse result = apiInstance.goalDecumulationRecommendation(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#goalDecumulationRecommendation");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositConfig = new atom_api.GoalDepositConfig(depStartReference="a_start",
   depStartPeriod=0,
   depEndReference="a_start",
   depEndPeriod=3,
   depAmount=2000,
   depFrequency="year",
   depInflation=0.0)

var withdrawalConfig = new atom_api.GoalWithdrawalConfig(withAmount=11000,
   withStartReference="a_end",
   withStartPeriod=0,
   withEndReference="d_end",
   withEndPeriod=0,
   withFrequency="year",
   withInflation=0.0)

var recommendationConfig = new atom_api.GoalRecommendationConfigRec(invMin=0,
    invMax=1000,
    depMin=0,
    depMax=1000,
    horizonMin=1,
    horizonMax=10,
    recommendedInflation=0.0)

var payload = new atom_api.GoalDecumulationRecommendation(pRet=[0.09],
    pRisk=[0.05],
    tradingDaysPerYear=252,
    aHorizon=3,
    dHorizon=2,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    withdrawalConfig=[withdrawalConfig],
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
    compoundingRate=0.0);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.goalDecumulationRecommendation(payload, callback);

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.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.

Example Response

{
    "on_track": true,
    "progress": 0.4545,
    "goal_probability": 0.9127,
    "goal_achievement_score": 100,
    "action": [
        {
            "value": 625,
            "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": 261.03,
            "accumulation_period_deposit": 2625,
            "decumulation_period_deposit": 0,
            "period_withdrawal": 0,
            "cumulative_earnings": 261.03,
            "accumulation_cumulative_deposit": 2625,
            "decumulation_cumulative_deposit": 0,
            "cumulative_withdrawals": 0,
            "ending_balance": 12886.03
        },
        "2": {
            "period_earnings": 819.01,
            "accumulation_period_deposit": 2625,
            "decumulation_period_deposit": 0,
            "period_withdrawal": 0,
            "cumulative_earnings": 1080.04,
            "accumulation_cumulative_deposit": 5250,
            "decumulation_cumulative_deposit": 0,
            "cumulative_withdrawals": 0,
            "ending_balance": 16330.04
        },
        "3": {
            "period_earnings": 1006.41,
            "accumulation_period_deposit": 2625,
            "decumulation_period_deposit": 0,
            "period_withdrawal": 0,
            "cumulative_earnings": 2086.45,
            "accumulation_cumulative_deposit": 7875,
            "decumulation_cumulative_deposit": 0,
            "cumulative_withdrawals": 0,
            "ending_balance": 19961.45
        },
        "4": {
            "period_earnings": 1358.01,
            "accumulation_period_deposit": 0,
            "decumulation_period_deposit": 0,
            "period_withdrawal": 11000,
            "cumulative_earnings": 3444.47,
            "accumulation_cumulative_deposit": 7875,
            "decumulation_cumulative_deposit": 0,
            "cumulative_withdrawals": 11000,
            "ending_balance": 10319.47
        },
        "5": {
            "period_earnings": 832.18,
            "accumulation_period_deposit": 0,
            "decumulation_period_deposit": 0,
            "period_withdrawal": 11000,
            "cumulative_earnings": 4276.65,
            "accumulation_cumulative_deposit": 7875,
            "decumulation_cumulative_deposit": 0,
            "cumulative_withdrawals": 22000,
            "ending_balance": 151.65
        }
    },
    "accumulation_balance": 19961.45
}

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.
accumulation_balance The projected balance at the end of the accumulation horizon.

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,
        "adjust_for_compounding": false,
        "compounding_rate": 0.0
    }' "https://api.hydrogenplatform.com/proton/v1/goal_decumulation/status"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_config = atom_api.GoalDepositConfig(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 = atom_api.GoalWithdrawalConfig(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 = atom_api.GoalRecommendationConfigStatus(recommend=True,
    inv_min=0,
    inv_max=1000,
    dep_min=0,
    dep_max=1000,
    horizon_min=1,
    horizon_max=10,
    recommended_inflation=0.0)
payload = atom_api.GoalDecumulationStatus(p_ret=[0.09],
    p_risk=[0.05],
    trading_days_per_year=252,
    a_horizon=3,
    d_horizon=2,
    horizon_frequency="year",
    deposit_config=[deposit_config],
    withdrawal_config=[withdrawal_config],
    recommendation_config=recommendation_config,
    curr_inv=10000,
    recommend_type="recurring",
    conf_tgt=0.9,
    n=1000,
    remove_outliers=True,
    thresh_type="perc",
    thresh=0,
    withdrawal_tax=0.0,
    adjust_for_compounding=False,
    compounding_rate=0.0)

try:
    # Goal decumulation status
    api_response = api_instance.goal_decumulation_status(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->goal_decumulation_status: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::GoalDecumulationStatus.new
payload.p_ret = [0.09]
payload.p_risk = [0.05]
payload.trading_days_per_year = 252
payload.a_horizon = 3
payload.d_horizon = 2
payload.horizon_frequency = "year"

deposit_config = AtomApi::GoalDepositConfig.new
deposit_config.dep_start_reference = "a_start"
deposit_config.dep_start_period = 0
deposit_config.dep_end_reference = "a_start"
deposit_config.dep_end_period = 3
deposit_config.dep_amount = 2000
deposit_config.dep_frequency = "year"
deposit_config.dep_inflation = 0.0
payload.deposit_config = [deposit_config]

withdrawal_config = AtomApi::GoalWithdrawalConfig.new
withdrawal_config.with_amount = 11000
withdrawal_config.with_start_reference = "a_end"
withdrawal_config.with_start_period = 0
withdrawal_config.with_end_reference = "d_end"
withdrawal_config.with_end_period = 0
withdrawal_config.with_frequency = "year"
withdrawal_config.with_inflation = 0.0
payload.withdrawal_config = [withdrawal_config]

recommendation_config = AtomApi::GoalRecommendationConfigRec.new
recommendation_config.inv_min = 0
recommendation_config.inv_max = 1000
recommendation_config.dep_min = 0
recommendation_config.dep_max = 1000
recommendation_config.horizon_min = 1
recommendation_config.horizon_max = 10
recommendation_config.recommended_inflation = 0.0
payload.recommendation_config = recommendation_config

payload.curr_inv = 10000
payload.recommend_type = "recurring"
payload.conf_tgt = 0.9
payload.n = 1000
payload.remove_outliers = true
payload.thresh_type = "perc"
payload.thresh = 0
payload.withdrawal_tax = 0.0
payload.adjust_for_compounding = false
payload.compounding_rate = 0.0

begin
  #Goal decumulation status
  result = api_instance.goal_decumulation_status(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->goal_decumulation_status: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

GoalDepositConfig depositConfig = new GoalDepositConfig(depStartReference="a_start",
    depStartPeriod=0,
    depEndReference="a_start",
    depEndPeriod=3,
    depAmount=2000,
    depFrequency="year",
    depInflation=0.0);

GoalWithdrawalConfig withdrawalConfig = new GoalWithdrawalConfig(withAmount=11000,
   withStartReference="a_end",
   withStartPeriod=0,
   withEndReference="d_end",
   withEndPeirod=0,
   withFrequency="year",
   withInflation=0.0);

GoalRecommendationConfigStatus recommendationConfig = new GoalRecommendationConfigStatus(recommend=True,
   invMin=0,
   invMax=1000,
   depMin=0,
   depMax=1000,
   horizonMin=1,
   horizonMax=10,
   recommendedInflation=0.0);

GoalDecumulationStatus payload = new GoalDecumulationStatus(pRet=[0.09],
    pRisk=[0.05],
    tradingDaysPerYear=252,
    aHorizon=3,
    dHorizon=2,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    withdrawalConfig=[withdrawalConfig],
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
    compoundingRate=0.0);
try {
    GoalStatusResponse result = apiInstance.goalDecumulationStatus(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#goalDecumulationStatus");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositConfig = new atom_api.GoalDepositConfig(depStartReference="a_start",
   depStartPeriod=0,
   depEndReference="a_start",
   depEndPeriod=3,
   depAmount=2000,
   depFrequency="year",
   depInflation=0.0)

var withdrawalConfig = new atom_api.GoalWithdrawalConfig(withAmount=11000,
   withStartReference="a_end",
   withStartPeriod=0,
   withEndReference="d_end",
   wthEndPeriod=0,
   withFrequency="year",
   withInflation=0.0)

var recommendationConfig = new atom_api.GoalRecommendationConfigStatus(recommend=true,
   invMin=0,
   invMax=1000,
   depMin=0,
   depMax=1000,
   horizonMin=1,
   horizonMax=10,
   recommendedInflation=0.0)

var payload = new atom_api.GoalDecumulationStatus(pRet=[0.09],
    pRisk=[0.05],
    tradingDaysPerYear=252,
    aHorizon=3,
    dHorizon=2,
    horizonFrequency="year",
    depositConfig=[depositConfig],
    withdrawalConfig=[withdrawalConfig],
    recommendationConfig=recommendationConfig,
    currInv=10000,
    recommendType="recurring",
    confTgt=0.9,
    n=1000,
    removeOutliers=true,
    threshType="perc",
    thresh=0,
    withdrawalTax=0.0,
    adjustForCompounding=false,
    compoundingRate=0.0);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.goalDecumulationStatus(payload, callback);

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.
adjust_for_compounding
boolean
If true, adjust periodic deposit amounts for compounding based on compounding_rate. This applies when a deposit’s dep_frequency is shorter than horizon_frequency, as deposits are conformed to horizon_frequency during the analysis. Defaults to false.
compounding_rate
float
The annualized rate to use when approximating a compounding effect on deposits. This value must be defined and adjust_for_compounding must be true in order to activate compounding adjustment. Defaults to 0.

Example Response

{
    "current_status": {
        "on_track": false,
        "progress": 0.4545,
        "goal_probability": 0.5298,
        "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": 302.11,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 302.11,
                "accumulation_cumulative_deposit": 2000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 12302.11
            },
            "2": {
                "period_earnings": 722.99,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 1025.1,
                "accumulation_cumulative_deposit": 4000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 15025.1
            },
            "3": {
                "period_earnings": 971.45,
                "accumulation_period_deposit": 2000,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 1996.55,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 17996.55
            },
            "4": {
                "period_earnings": 1275.95,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 3272.5,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 11000,
                "ending_balance": 8272.5
            },
            "5": {
                "period_earnings": 0,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 8272.5,
                "cumulative_earnings": 3272.5,
                "accumulation_cumulative_deposit": 6000,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 19272.5,
                "ending_balance": 0
            }
        },
        "accumulation_balance": 17996.55
    },
    "recommended_status": {
        "on_track": true,
        "progress": 0.4545,
        "goal_probability": 0.9043,
        "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": 280.94,
                "accumulation_period_deposit": 2593.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 280.94,
                "accumulation_cumulative_deposit": 2593.75,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 12874.69
            },
            "2": {
                "period_earnings": 700.92,
                "accumulation_period_deposit": 2593.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 981.86,
                "accumulation_cumulative_deposit": 5187.5,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 16169.36
            },
            "3": {
                "period_earnings": 1125.06,
                "accumulation_period_deposit": 2593.75,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 0,
                "cumulative_earnings": 2106.92,
                "accumulation_cumulative_deposit": 7781.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 0,
                "ending_balance": 19888.17
            },
            "4": {
                "period_earnings": 1284.08,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 3391,
                "accumulation_cumulative_deposit": 7781.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 11000,
                "ending_balance": 10172.25
            },
            "5": {
                "period_earnings": 888.86,
                "accumulation_period_deposit": 0,
                "decumulation_period_deposit": 0,
                "period_withdrawal": 11000,
                "cumulative_earnings": 4279.86,
                "accumulation_cumulative_deposit": 7781.25,
                "decumulation_cumulative_deposit": 0,
                "cumulative_withdrawals": 22000,
                "ending_balance": 61.11
            }
        },
        "accumulation_balance": 19888.17
    }
}

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.
      accumulation_balance The projected balance at the end of the accumulation horizon.
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.
      accumulation_balance The projected balance at the end of the accumulation horizon.

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",
        "use_proxy_data": false
      }' "https://api.hydrogenplatform.com/proton/v1/mvo"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))

w_config = atom_api.WConfigPortfolio(w_min_major=0.05,
     w_max_major=0.7,
     w_min_minor=0.05,
     w_max_minor=0.3,
     cash_amount=0.03)

payload = atom_api.OptConfigPortfolio(tickers=["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"],
    min_assets=2,
    w_config=w_config,
    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")

try:
    # Mean-variance optimization
    api_response = api_instance.mvo(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->mvo: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::OptConfigPortfolio.new
payload.tickers = ["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"]
payload.min_assets = 2

w_config = AtomApi::WConfigPortfolio.new
w_config.w_min_major = 0.05
w_config.w_max_major = 0.7
w_config.w_min_minor = 0.05
w_config.w_max_minor = 0.3
w_config.cash_amount = 0.03
payload.w_config = w_config
payload.w_asset_config = {US_Equities => 1.0,
  Fixed_Income => 1.0,
  Intl_Equities => 1.0,
  EM_Equities => 1.0,
  Commodities => 1.0}
payload.sec_types = ["major", "major", "minor", "minor", "minor", "Cash"]
payload.tgt_type = "risk"
payload.tgt_val = 0.09
payload.start_date = "2015-01-01"
payload.end_date = "2017-01-01"

begin
  #Mean-variance optimization
  result = api_instance.mvo(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->mvo: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

WConfigPortfolio wConfig = new WConfigPortfolio(wMinMajor=0.05,
  wMaxMajor=0.7,
  wMinMinor=0.05,
  wMaxMinor=0.3,
  cashAmount=0.03);

OptConfigPortfolio payload = new OptConfigPortfolio(tickers=["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"],
    minAssets=2,
    wConfig=wConfig,
    wAssetConfig={"US_Equities": 1.0,
      "Fixed_Income": 1.0,
      "Intl_Equities": 1.0,
      "EM_Equities": 1.0,
      "Commodities": 1.0},
    secTypes=["major", "major", "minor", "minor", "minor", "Cash"],
    tgtType="risk",
    tgtVal=0.09,
    startDate="2015-01-01",
    endDate="2017-01-01");
try {
    MvoResponse result = apiInstance.mvo(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#mvo");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var wConfigPortfolio = new atom_api.WConfigPortfolio(wMinMajor=0.05,
   wMaxMajor=0.7,
   wMinMinor=0.3,
   wMaxMinor=0.3,
   cashAmount=0.03)

var payload = new atom_api.OptConfigPortfolio(tickers=["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"],
    minAssets=2,
    wConfig=wConfigPortfolio,
    wAssetConfig={"US_Equities": 1.0,
      "Fixed_Income": 1.0,
      "Intl_Equities": 1.0,
      "EM_Equities": 1.0,
      "Commodities": 1.0},
    secTypes=["major", "major", "minor", "minor", "minor", "Cash"],
    tgtType="risk",
    tgtVal=0.09,
    startDate="2015-01-01",
    endDate="2017-01-01");

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.mvo(payload, callback);

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
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.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.

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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
payload = atom_api.Rebalance(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
      })

try:
    # Rebalancing
    api_response = api_instance.rebalancing_signal(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->rebalancing_signal: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::Rebalance.new
payload.model_id = "a83fd921-11ab-4003-a340-9bca9d3e01bd"
payload.start_date = "2016-12-01"
payload.end_date = "2017-12-08"
payload.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}

begin
  #Rebalancing
  result = api_instance.rebalancing_signal(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->rebalancing_signal: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
Rebalance payload = new Rebalance(modelId="a83fd921-11ab-4003-a340-9bca9d3e01bd",
    startDate="2016-12-01",
    endDate="2017-12-08",
    initialWeights={"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});
try {
    RebalanceResponse result = apiInstance.rebalancingSignal(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#rebalancingSignal");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.Rebalance(modelId="a83fd921-11ab-4003-a340-9bca9d3e01bd",
     startDate="2016-12-01",
     endDate="2017-12-08",
     initialWeights={"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});

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.rebalancingSignal(payload, callback);

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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))

payload = atom_api.RiskScore(
    answers=[10, 400, 3, 9],
    max_answers=[10, 1000, 4, 10],
    weights=[0.25, 0.25, 0.25, 0.25]
)

try:
    # Risk score
    api_response = api_instance.risk_score(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->risk_score: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::RiskScore.new
payload.answers = [10, 400, 3, 9]
payload.max_answers = [10, 1000, 4, 10]
payload.weights = [0.25, 0.25, 0.25, 0.25]

begin
  #Risk score
  result = api_instance.risk_score(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->risk_score: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
RiskScore payload = new RiskScore(answers=[10, 400, 3, 9],
    maxAnswers=[10, 1000, 4, 10],
    weights=[0.25, 0.25, 0.25, 0.25]);
try {
    RiskScoreResponse result = apiInstance.riskScore(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#riskScore");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.RiskScore(answers=[10, 400, 3, 9],
   maxAnswers=[10, 1000, 4, 10],
   weights=[0.25, 0.25, 0.25, 0.25]);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.riskScore(payload, callback);

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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
payload = atom_api.DimensionalRiskScore(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])

try:
    # Dimensional risk score
    api_response = api_instance.dimensional_risk_score(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->dimensional_risk_score: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::DimensionalRiskScore.new
payload.answers = [10, 400, 3, 9]
payload.max_answers = [10, 1000, 4, 10]
payload.answer_dims = [["dim1"], ["dim2"], ["dim3"], ["dim4"]]
payload.dims = ["dim1", "dim2", "dim3", "dim4"]
payload.dim_weights = [0.25, 0.25, 0.25, 0.25]
payload.answer_weights = [0.25, 0.25, 0.25, 0.25]

begin
  #Dimensional risk score
  result = api_instance.dimensional_risk_score(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->dimensional_risk_score: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
DimensionalRiskScore payload = new DimensionalRiskScore(answers=[10, 400, 3, 9],
    maxAnswers=[10, 1000, 4, 10],
    answerDims=[["dim1"], ["dim2"], ["dim3"], ["dim4"]],
    dims=["dim1", "dim2", "dim3", "dim4"],
    dimWeights=[0.25, 0.25, 0.25, 0.25],
    answerWeights=[0.25, 0.25, 0.25, 0.25]);
try {
    DimRiskScoreResponse result = apiInstance.dimensionalRiskScore(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#dimensionalRiskScore");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.DimensionalRiskScore(answers=[10, 400, 3, 9],
    maxAnswers=[10, 1000, 4, 10],
    answerDims=[["dim1"], ["dim2"], ["dim3"], ["dim4"]],
    dims=["dim1", "dim2", "dim3", "dim4"],
    dimWeights=[0.25, 0.25, 0.25, 0.25],
    answerWeights=[0.25, 0.25, 0.25, 0.25]);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.dimensionalRiskScore(payload, callback);

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"],
        "use_proxy_data": false
    }' "https://api.hydrogenplatform.com/proton/v1/risk_allocation"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))

w_config = atom_api.RiskScoreOptConfigModelWConfig(w_min_major=0.05,
   w_max_major=1,
   w_min_minor=0.05,
   w_max_minor=1,
   cash_amount=0.03)
opt_config = atom_api.RiskScoreOptConfigModel(tickers=["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"],
      min_assets=1,
      w_config=w_config,
      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")

payload = atom_api.RiskAllocation(risk_score=49,
    allocation_method="create",
    opt_config=opt_config,
    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"
    ])

try:
    # Risk allocation
    api_response = api_instance.risk_allocation(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->risk_allocation: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::RiskAllocation.new
payload.risk_score = 49
payload.allocation_method = "create"

opt_config = AtomApi::RiskScoreOptConfigModel.new
opt_config.tickers = ["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"]
opt_config.min_assets = 1

w_config = AtomApi::RiskScoreOptConfigModelWConfig.new
w_config.w_min_major = 0.05
w_config.w_max_major = 1
w_config.w_min_minor = 0.05
w_config.w_max_minor = 1
w_config.cash_amount = 0.03
opt_config.w_config = w_config
opt_config.w_asset_config = {US_Equities => 1.0,
                             Fixed_Income => 1.0,
                             Intl_Equities => 1.0,
                             EM_Equities => 1.0,
                             Commodities => 1.0}
opt_config.sec_types = ["major", "major", "minor", "minor", "minor", "Cash"]
opt_config.start_date = "2016-01-01"
opt_config.end_date = "2017-01-01"
payload.opt_config = opt_config
payload.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"]

begin
  #Risk allocation
  result = api_instance.risk_allocation(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->risk_allocation: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

RiskScoreOptConfigModelWConfig wConfig = new RiskScoreOptConfigModelWConfig(wMinMajor=0.05,
    wMaxMajor=1,
    wMinMinor=0.05,
    wMaxMinor=1,
    cashAmount=0.03);

RiskScoreOptConfigModel optConfig = new RiskScoreOptConfigModel(tickers=["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"],
    minAssets=1,
    wConfig=wConfig,
    wAssetConfig={"US_Equities": 1.0,
                  "Fixed_Income": 1.0,
                  "Intl_Equities": 1.0,
                  "EM_Equities": 1.0,
                  "Commodities": 1.0},
    secTypes=["major", "major", "minor", "minor", "minor", "Cash"],
    startDate="2016-01-01",
    endDate="2017-01-01");

RiskAllocation payload = new RiskAllocation(riskScore=49,
    allocationMethod="create",
    optConfig=optConfig,
    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"]);
try {
    RiskAllocationResponse result = apiInstance.riskAllocation(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#riskAllocation");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var wConfig = new atom_api.RiskScoreOptConfigModelWConfig(wMinMajor=0.05,
    wMaxMajor=1,
    wMinMinor=0.05,
    wMaxMinor=1,
    cashAmount=0.03)

var optConfig = new atom_api.RiskScoreOptConfigModel(tickers=["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"],
     minAssets=1,
     wConfig=wConfig,
     wAssetConfig={"US_Equities": 1.0,
                   "Fixed_Income": 1.0,
                   "Intl_Equities": 1.0,
                   "EM_Equities": 1.0,
                   "Commodities": 1.0},
     secTypes=["major", "major", "minor", "minor", "minor", "Cash"],
     startDate="2016-01-01",
     endDate="2017-01-01")

var payload = new atom_api.RiskAllocation(riskScore=49,
    allocationMethod="create",
    optConfig=optConfig,
    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"]);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.riskAllocation(payload, callback);

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
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.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.

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

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"
        ],
        "use_proxy_data": false
      }' "https://api.hydrogenplatform.com/proton/v1/event_study"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
payload = atom_api.EventStudy(portfolio_tickers=["CVX", "PFE", "JNJ"],
      portfolio_weights=[0.3, 0.4, 0.3],
      events=["2008_financial_crisis"])

try:
    # Event study
    api_response = api_instance.event_study(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->event_study: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::EventStudy.new
payload.portfolio_tickers = ["CVX", "PFE", "JNJ"]
payload.portfolio_weights = [0.3, 0.4, 0.3]
payload.events = ["2008_financial_crisis"]

begin
  #Event study
  result = api_instance.event_study(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->event_study: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
EventStudy payload = new EventStudy(portfolioTickers=["CVX", "PFE", "JNJ"],
    portfolioWeights=[0.3, 0.4, 0.3],
    events=["2008_financial_crisis"]);
try {
    EventStudyResponse result = apiInstance.eventStudy(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#eventStudy");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.EventStudy(portfolioTickers=["CVX", "PFE", "JNJ"],
      portfolioWeights=[0.3, 0.4, 0.3],
      events=["2008_financial_crisis"]);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.eventStudy(payload, callback);

ARGUMENTS

Parameter Description
portfolio_tickers
array, required
Portfolio tickers, referencing securities defined in the Nucleus API.
portfolio_weights
array, required
Portfolio weights, corresponding to portfolio_tickers. Must sum to 1.0.
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.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.

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

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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
payload = atom_api.Backtest(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)

try:
    # Model backtest
    api_response = api_instance.model_backtest(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->model_backtest: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::Backtest.new
payload.model_id = "9aad12e8-25dc-421d-a041-1b157fff7738"
payload.start_date = "2016-12-01"
payload.end_date = "2016-12-05"
payload.initial_weights = {GOOGL => 0.25, CSCO => 0.25, MCD => 0.25, WMT => 0.25}
payload.asset_size = 1000
payload.asset_sizes = true
payload.trades = true
payload.holdings = true
payload.stats = true

begin
  #Model backtest
  result = api_instance.model_backtest(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->model_backtest: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
Backtest payload = new Backtest(modelId="9aad12e8-25dc-421d-a041-1b157fff7738",
    startDate="2016-12-01",
    endDate="2016-12-05",
    initialWeights={"GOOGL": 0.25, "CSCO": 0.25, "MCD": 0.25, "WMT": 0.25},
    assetSize=1000,
    assetSizes=true,
    trades=true,
    holdings=true,
    stats=true);
try {
    BacktestResponse result = apiInstance.modelBacktest(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#modelBacktest");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.Backtest(modelId="9aad12e8-25dc-421d-a041-1b157fff7738",
    startDate="2016-12-01",
    endDate="2016-12-05",
    initialWeights={"GOOGL": 0.25, "CSCO": 0.25, "MCD": 0.25, "WMT": 0.25},
    assetSize=1000,
    assetSizes=true,
    trades=true,
    holdings=true,
    stats=true);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.modelBacktest(payload, callback);

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

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 '{
        "cf": [[100,10]],
        "init_bal": 1000,
        "ret_mod": [0],
        "mu": [0.05],
        "sigma": [0.06],
        "n": 1000,
        "remove_outliers": false,
        "result_type": "median",
        "p": [50],
        "min_bal": [0],
        "max_bal": [4000],
        "min_sample": [0],
        "max_sample": [0.15]
      }' "https://api.hydrogenplatform.com/proton/v1/monte_carlo"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
payload = atom_api.MonteCarlo(n=5,
      mu=[0.06],
      sigma=[0.06],
      cf=[[100, 3]],
      ret_mod=[0],
      init_bal=1000,
      result_type="raw",
      remove_outliers=False)

try:
    # Monte Carlo
    api_response = api_instance.monte_carlo(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->monte_carlo: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::MonteCarlo.new
payload.n = 5
payload.mu = [0.06]
payload.sigma = [0.06]
payload.cf = [[100, 3]]
payload.ret_mod = [0]
payload.init_bal = 1000
payload.result_type = "raw"
payload.remove_outliers = false

begin
  #Monte Carlo
  result = api_instance.monte_carlo(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->monte_carlo: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
MonteCarlo payload = new MonteCarlo(n=5,
    mu=[0.06],
    sigma=[0.06],
    cf=[[100, 3]],
    retMod=[0],
    initBal=1000,
    resultType="raw",
    removeOutliers=false);
try {
    MonteCarloResponse result = apiInstance.monteCarlo(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#monteCarlo");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.MonteCarlo(n=5,
      mu=[0.06],
      sigma=[0.06],
      cf=[[100, 3]],
      retMod=[0],
      initBal=1000,
      resultType="raw",
      removeOutliers=false);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.monteCarlo(payload, callback);

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, tens, or custom. raw returns all simulation results; mean returns the average simulation result; median returns the median simulation result; tens 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].
min_bal
array
A lower bound to enforce on the periodic balance. Each item in the array corresponds to a period in the simulation. If the length of the array is less than the number of simulation periods, it is conformed to the appropriate length by persisting the final value in the array.
max_bal
array
An upper bound to enforce on the periodic balance. Each item in the array corresponds to a period in the simulation. If the length of the array is less than the number of simulation periods, it is conformed to the appropriate length by persisting the final value in the array.
min_sample
array
A lower bound to enforce on the randomly sampled periodic return. Each item in the array corresponds to a period in the simulation. If the length of the array is less than the number of simulation periods, it is conformed to the appropriate length by persisting the final value in the array.
max_sample
array
An upper bound to enforce on the randomly sampled periodic return. Each item in the array corresponds to a period in the simulation. If the length of the array is less than the number of simulation periods, it is conformed to the appropriate length by persisting the final value in the array.

Example Response

{
    "sims": [
        [
            1000,
            1150.7407772024958,
            1323.0962376032248,
            1490.070327954984,
            1672.015451231377,
            1863.3772622510578,
            2066.324013845525,
            2275.2452616749324,
            2501.7737472360695,
            2744.753718748225,
            2993.112513070986
        ]
    ]
}

RESPONSE

Field Description
sims A collection of Monte Carlo results. If result_type = raw, this returns multiple sets of results, defined by n. If result_type = custom, this returns the results in the order defined by p. If result_type = tens, this returns the results in the order of 10, 20, 30, 40, 50, 60, 70, 80, 90. If result_type = mean or median only one array of results will be returned.

Portfolio What-If

As clients’ wants and needs change, it is useful to evaluate shifts in a portfolio’s makeup. This tool considers the effect of “what-if” portfolio composition changes such as adding, removing, reducing, or increasing various positions in a portfolio. This can help a client make decisions around which securities to buy or sell, or help a wealth manager assess portfolio composition over time. The analysis between the current and altered portfolios is done on the basis annualized historical return and annualized historical standard deviation.

HTTP REQUEST

POST /portfolio_what_if

Example Request

curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
  -H "Content-Type: application/json" \
  -d '{
        "current_portfolio_tickers": [
          "CVX",
          "PFE",
          "JNJ"
        ],
        "current_portfolio_weights": [
          0.20,
          0.20,
          0.60
        ],
        "altered_portfolio_tickers": [
          "CVX",
          "PFE",
          "JNJ"
        ],
        "altered_portfolio_weights": [
          0.30,
          0.30,
          0.40
        ],
        "start_date": "2017-01-01",
        "end_date": "2018-12-31",
        "use_proxy_data": false
      }' "https://api.hydrogenplatform.com/proton/v1/portfolio_what_if"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
payload = atom_api.WhatIfPortfolio(current_portfolio_tickers=["CVX", "PFE", "JNJ"],
   current_portfolio_weights=[0.20, 0.20, 0.60],
   altered_portfolio_tickers=["CVX", "PFE", "JNJ"],
   altered_portfolio_weights=[0.30, 0.30, 0.40],
   start_date="2017-01-01",
   end_date="2018-12-31")

try:
    # Portfolio what-if
    api_response = api_instance.portfolio_what_if(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->portfolio_what_if: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::WhatIfPortfolio.new
payload.current_portfolio_tickers = ["CVX", "PFE", "JNJ"]
payload.current_portfolio_weights = [0.20, 0.20, 0.60]
payload.altered_portfolio_tickers = ["CVX", "PFE", "JNJ"]
payload.altered_portfolio_weights = [0.30, 0.30, 0.40]
payload.start_date = "2017-01-01"
payload.end_date = "2018-12-31"

begin
  #Portfolio what-if
  result = api_instance.portfolio_what_if(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->portfolio_what_if: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
WhatIfPortfolio payload = new WhatIfPortfolio(currentPortfolioTickers=["CVX", "PFE", "JNJ"],
  currentPortfolioWeights=[0.20, 0.20, 0.60],
  alteredPortfolioTickers=["CVX", "PFE", "JNJ"],
  alteredPortfolioWeights=[0.30, 0.30, 0.40],
  startDate="2017-01-01",
  endDate="2018-12-31");
try {
    PortfolioWhatIfResponse result = apiInstance.portfolioWhatIf(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#portfolioWhatIf");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.WhatIfPortfolio(currentPortfolioTickers=["CVX", "PFE", "JNJ"],
   currentPortfolioWeights=[0.20, 0.20, 0.60],
   alteredPortfolioTickers=["CVX", "PFE", "JNJ"],
   alteredPortfolioWeights=[0.30, 0.30, 0.40],
   startDate="2017-01-01",
   endDate="2018-12-31");

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.portfolioWhatIf(payload, callback);

ARGUMENTS

Parameter Description
current_portfolio_tickers
array, required
Current portfolio tickers, referencing securities defined in the Nucleus API.
current_portfolio_weights
array, required
Current portfolio weights, corresponding to current_portfolio_tickers. Must sum to 1.0.
altered_portfolio_tickers
array
Altered portfolio tickers, referencing securities defined in the Nucleus API. Defaults to current_portfolio_tickers.
altered_portfolio_weights
array, required
Altered portfolio weights, corresponding to altered_portfolio_tickers. Must sum to 1.0.
start_date
date
Start date used for ticker price history. Defaults to earliest common date among current_portfolio_tickers and altered_portfolio_tickers prices.
end_date
date
End date used for ticker price history. Defaults to latest common date among portfolio_tickers and altered_portfolio_tickers prices.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.

Example Response

{
    "annualized_return": {
        "current_portfolio": 0.158543872616828,
        "altered_portfolio": 0.13392921668177515,
        "delta": -0.024614655935052854
    },
    "annualized_volatility": {
        "current_portfolio": 0.005478420111416463,
        "altered_portfolio": 0.005193612691605431,
        "delta": -0.00028480741981103206
    }
}

RESPONSE

Field Description
annualized_return Annualized return information for the current and altered portfolios.
      current_portfolio
      
Current portfolio’s annualized return.
      altered_portfolio
      
Altered portfolio’s annualized return.
      delta
      
Raw difference in annualized return between the current and altered portfolios.
annualized_volatility Annualized portfolio standard deviation.
      current_portfolio
      
Current portfolio’s annualized standard deviation.
      altered_portfolio
      
Altered portfolio’s annualized standard deviation.
      delta
      
Raw difference in annualized standard deviation between the current and altered portfolios.

NUCLEUS DATA DEPENDENCIES

          1. Securities: POST /security
          2. Security Prices: POST /security_price

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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))

deposit_one = atom_api.DepositSchedule(deposit_amount=100,
   deposit_frequency_interval="month",
   deposit_duration=120,
   adjust_deposit_for_inflation=True)
deposit_two = atom_api.DepositSchedule(deposit_amount=2000,
   deposit_frequency_interval="year",
   deposit_duration=10,
   adjust_deposit_for_inflation=True)

payload = atom_api.SimpleSavingsCalculator(initial_balance=10000,
    horizon=5,
    return_schedule=[0.02, 0.025, 0.025, 0.025, 0.03],
    horizon_frequency_interval="year",
    deposit_schedule=[deposit_one, deposit_two],
    tax_rate=0.33,
    inflation_rate=0.02)

try:
    # Savings calculator
    api_response = api_instance.savings_calculator(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->savings_calculator: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::SimpleSavingsCalculator.new
payload.initial_balance = 10000
payload.horizon = 5
payload.return_schedule = [0.02, 0.025, 0.025, 0.025, 0.03]
payload.horizon_frequency_interval = "year"

deposit_schedule_one = AtomApi::DepositSchedule.new
deposit_schedule_one.deposit_amount = 100
deposit_schedule_one.deposit_frequency_interval = "month"
deposit_schedule_one.deposit_duration = 120
deposit_schedule_one.adjust_deposit_for_inflation = true

deposit_schedule_two = AtomApi::DepositSchedule.new
deposit_schedule_two.deposit_amount = 2000
deposit_schedule_two.deposit_frequency_interval = "month"
deposit_schedule_two.deposit_duration = 10
deposit_schedule_two.adjust_deposit_for_inflation = true

payload.deposit_schedule = [deposit_schedule_one,
                            deposit_schedule_two]
payload.tax_rate = 0.33
payload.inflation_rate = 0.02

begin
  #Savings calculator
  result = api_instance.savings_calculator(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->savings_calculator: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

DepositSchedule depositOne = new DepositSchedule(depositAmount=100,
      depositFrequencyInterval="month",
      depositDuration=120,
      adjustDepositForInflation=true);
DepositSchedule depositTwo = new DepositSchedule(depositAmount=2000,
      depositFrequencyInterval="year",
      depositDuration=10,
      adjustDepositForInflation=true);

SimpleSavingsCalculator payload = new SimpleSavingsCalculator(initialBalance=10000,
      horizon=5,
      returnSchedule=[0.02, 0.025, 0.025, 0.025, 0.03],
      horizonFrequencyInterval="year",
      depositSchedule=[depositOne,
         depositTwo],
      taxRate=0.33,
      inflationRate=0.02);
try {
    SavingsCalculatorResponse result = apiInstance.savingsCalculator(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#savingsCalculator");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositOne = new atom_api.DepositSchedule(depositAmount=100,
       depositFrequencyInterval="month",
       depositDuration=120,
       adjustDepositForInflation=true);

var depositTwo = new atom_api.DepositSchedule(depositAmount=100,
       depositFrequencyInterval="month",
       depositDuration=120,
       adjustDepositForInflation=true);

var payload = new atom_api.SimpleSavingsCalculator(initialBalance=10000,
       horizon=5,
       returnSchedule=[0.02, 0.025, 0.025, 0.025, 0.03],
       horizonFrequencyInterval="year",
       depositSchedule=[depositOne,
          depositTwo],
        taxRate=0.33,
        inflationRate=0.02);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.savingsCalculator(payload, callback);

ARGUMENTS

Parameter Description
initial_balance
float, required
The initial balance of the investment.
horizon
integer, required
The number of time periods in the savings horizon, where each period represents horizon_frequency_interval.
return_schedule
array, required
The rate of return per period. Providing an array of length 1, such as [0.04], will apply the value to each period in horizon.
horizon_frequency_interval
string
The frequency interval for horizon. Must be one of year, quarter, month, week, or day. 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. Must be one of year, quarter, month, week, or day. 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": 28465.18,
    "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": 3264,
            "period_withdrawal": 0,
            "cumulative_earnings": 134,
            "cumulative_contributions": 3264,
            "cumulative_withdrawals": 0,
            "ending_balance": 13398
        },
        "2": {
            "period_earnings": 224.42,
            "period_contribution": 3329.28,
            "period_withdrawal": 0,
            "cumulative_earnings": 358.42,
            "cumulative_contributions": 6593.28,
            "cumulative_withdrawals": 0,
            "ending_balance": 16951.7
        },
        "3": {
            "period_earnings": 283.94,
            "period_contribution": 3395.87,
            "period_withdrawal": 0,
            "cumulative_earnings": 642.36,
            "cumulative_contributions": 9989.15,
            "cumulative_withdrawals": 0,
            "ending_balance": 20631.5
        },
        "4": {
            "period_earnings": 345.58,
            "period_contribution": 3463.78,
            "period_withdrawal": 0,
            "cumulative_earnings": 987.94,
            "cumulative_contributions": 13452.93,
            "cumulative_withdrawals": 0,
            "ending_balance": 24440.86
        },
        "5": {
            "period_earnings": 491.26,
            "period_contribution": 3533.06,
            "period_withdrawal": 0,
            "cumulative_earnings": 1479.2,
            "cumulative_contributions": 16985.99,
            "cumulative_withdrawals": 0,
            "ending_balance": 28465.18
        }
    }
}

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.

Scenario Analysis

When assessing a portfolio, it is useful to simulate its response to a series of external factors. Scenario Analysis provides a statistical estimate of the impact that a combination of external movements may have on a portfolio’s rate of return, based on a multivariate regression model that considers historical price behavior. In order to support many types of real-world situations, this tool accounts for the magnitude, direction, and duration of a given change (e.g. a 10% upward movement over a period of 2 weeks). It also supports the ability to reflect a lag between the movement of each factor and the portfolio (e.g. the portfolio is impacted 3 days after the factor movement). The resulting analysis can be helpful in comparing the economic exposures of different portfolios.

HTTP REQUEST

POST /scenario_analysis

Example Request

curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
  -H "Content-Type: application/json" \
  -d '{
        "portfolio_tickers": [
          "HD",
          "PG",
          "EBAY",
          "NVDA"
        ],
        "portfolio_weights": [
          0.25,
          0.25,
          0.25,
          0.25
        ],
        "frequency_interval": "month",
        "scenario": [
          {
            "ticker": "VNQ",
            "change_amount": 0.02,
            "change_duration": 1,
            "lag": 0
          },
          {
            "ticker": "GLD",
            "change_amount": -0.05,
            "change_duration": 3,
            "lag": 1
          }
        ],
        "start_date": "2015-08-11",
        "end_date": "2016-12-31",
        "trading_days_per_year": 252,
        "use_proxy_data": false
      }' "https://api.hydrogenplatform.com/proton/v1/scenario_analysis"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))

factor_one = atom_api.SensitivityFactor(ticker="VNQ",
    change_amount=0.02,
    change_duration=1,
    lag=0)
factor_two = atom_api.SensitivityFactor(ticker="GLD",
    change_amount=-0.05,
    change_duration=3,
    lag=1)

payload = atom_api.ScenarioAnalysis(portfolio_tickers=["HD", "PG", "EBAY", "NVDA"],
    portfolio_weights=[0.25, 0.25, 0.25, 0.25],
    frequency_interval="month",
    scenario=[factor_one, factor_two],
    start_date="2015-08-11",
    end_date="2016-12-31",
    trading_days_per_year=252)

try:
    # Scenario analysis
    api_response = api_instance.scenario_analysis(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->scenario_analysis: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::ScenarioAnalysis.new
payload.portfolio_tickers = ["HD", "PG", "EBAY", "NVDA"]
payload.portfolio_weights = [0.25, 0.25, 0.25, 0.25]
payload.frequency_interval = "month"

factor_one = AtomApi.SensitivityFactor.new
factor_one.ticker = "VNQ"
factor_one.change_amount = 0.02
factor_one.change_duration = 1
factor_one.lag = 0

factor_two = AtomApi.SensitivityFactor.new
factor_two.ticker = "GLD"
factor_two.change_amount = -0.05
factor_two.change_duration = 3
factor_two.lag = 1

payload.scenario = [factor_one,
                    factor_two]
payload.start_date = "2015-08-11"
payload.end_date = "2016-12-31"
payload.trading_days_per_year = 252

begin
  #Scenario analysis
  result = api_instance.scenario_analysis(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->scenario_analysis: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

SensitivityFactor factorOne = new SensitivityFactor(ticker="VNQ",
    changeAmount=0.02,
    changeDuration=1,
    lag=0);
SensitivityFactor factorTwo = new SensitivityFactor(ticker="GLD",
    changeAmount=-0.05,
    changeDuration=3,
    lag=1);

ScenarioAnalysis payload = new ScenarioAnalysis(portfolioTickers=["HD", "PG", "EBAY", "NVDA"],
    portfolioWeights=[0.25, 0.25, 0.25, 0.25],
    frequencyInterval="month",
    scenario=[factorOne, factorTwo],
    startDate="2015-08-11",
    endDate="2016-12-31",
    tradingDaysPerYear=252);
try {
    ScenarioAnalysisResponse result = apiInstance.scenarioAnalysis(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#scenarioAnalysis");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var factor_one = new atom_api.SensitivityFactor(ticker="VNQ",
    changeAmount=0.02,
    changeDuration=1,
    lag=0)
var factor_two = new atom_api.SensitivityFactor(ticker="GLD",
    changeAmount=-0.05,
    changeDuration=3,
    lag=1)

var payload = new atom_api.ScenarioAnalysis(portfolioTickers=["HD", "PG", "EBAY", "NVDA"],
    portfolioWeights=[0.25, 0.25, 0.25, 0.25],
    frequencyInterval="month",
    scenario=[factor_one,
              factor_two],
    startDate="2015-08-11",
    endDate="2016-12-31",
    tradingDaysPerYear=252);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.scenarioAnalysis(payload, callback);

ARGUMENTS

Parameter Description
portfolio_tickers
array, required
Portfolio tickers, referencing securities defined in the Nucleus API.
portfolio_weights
array, required
Portfolio weights, corresponding to portfolio_tickers. Must sum to 1.0.
frequency_interval
float, required
Unit of time associated with change_duration and lag. Must be one of year, quarter, month, week, or day.
scenario
map, required
A scenario to analyze, defined as a series of hypothetical price movements for securities, indices, or other instruments.
      ticker
      string, required
Ticker representing the factor, referencing a security defined in the Nucleus API.
      change_amount
      float, required
A percentage price change, represented in decimal format. Value can be positive or negative.
      change_duration
      integer, required
Number of time periods over which change_amount is to take place, where each period represents frequency_interval.
      lag
      integer, required
Number of time periods between the factor signal and the portfolio’s response to that signal, where each period represents frequency_interval. For example, a value of 3 indicates that the portfolio responds 3 periods after the factor moves. Value cannot be negative.
start_date
date
Start date used for ticker price history. Defaults to earliest common date among portfolio_tickers and scenario ticker prices.
end_date
date
End date used for ticker price history. Defaults to latest common date among portfolio_tickers and scenario ticker prices.
trading_days_per_year
integer
The number of days per year for which a portfolio is subject to market fluctuation. Defaults to 252.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.

Example Response

{
    "portfolio_impact": 0.010304645392564492,
    "scenario_results": [
        {
            "ticker": "VNQ",
            "t_statistic": 4.770856786757572,
            "regression_coefficient": 0.8023214304210411
        },
        {
            "ticker": "GLD",
            "t_statistic": 0.6448259002724069,
            "regression_coefficient": 0.1148356643171266
        }
    ]
}

RESPONSE

Field Description
portfolio_impact Expected impact of scenario factors on the portfolio’s return. The associated unit of time is the base unit indicated by frequency_interval in the request (for example, week = 1 week).
scenario_results Underlying results for each scenario factor, including the fields shown below.
      ticker Ticker to indicate the factor.
      t_statistic Raw t-statistic from the regression analysis, typically used to determine statistical significance of regression_coefficient.
      regression_coefficient Statistical relationship between the ticker return and the portfolio return.

NUCLEUS DATA DEPENDENCIES

          1. Securities: POST /security
          2. Security Prices: POST /security_price

Sensitivity Analysis

When assessing a portfolio, simulating its response to an external factor can give greater insight into the portfolio’s exposure. Sensitivity Analysis provides a statistical estimate of the impact that an external movement may have on a portfolio’s rate of return, based on an ordinary-least-squares linear regression model that considers historical price behavior. In order to support many types of real-world situations, this tool accounts for the magnitude, direction, and duration of a given change (e.g. a 10% upward movement over a period of 2 weeks). It also supports the ability to reflect a lag between the movement of the factor and the portfolio (e.g. the portfolio is impacted 3 days after the factor movement). The resulting analysis can be helpful in comparing the economic and risk exposures of different portfolios.

HTTP REQUEST

POST /sensitivity_analysis

Example Request

curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
  -H "Content-Type: application/json" \
  -d '{
        "portfolio_tickers": [
            "HD",
            "PG",
            "EBAY",
            "NVDA"
        ],
        "portfolio_weights": [
            0.25,
            0.25,
            0.25,
            0.25
        ],
        "frequency_interval": "day",
        "sensitivity_factor": {
            "ticker": "AGG",
             "change_amount": -0.05,
             "change_duration": 3,
             "lag": 0
        },
        "start_date": "2015-08-11",
        "end_date": "2016-12-31",
        "trading_days_per_year": 252,
        "use_proxy_data": false
      }' "https://api.hydrogenplatform.com/proton/v1/sensitivity_analysis"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))

factor = atom_api.SensitivityFactor(ticker="AGG",
    change_amount=-0.05,
    change_duration=3,
    lag=0)
payload = atom_api.SensitivityAnalysis(portfolio_tickers=["HD", "PG", "EBAY", "NVDA"],
   portfolio_weights=[0.25, 0.25, 0.25, 0.25],
   frequency_interval="day",
   sensitivity_factor=factor,
   start_date="2015-08-11",
   end_date="2016-12-31",
   trading_days_per_year=252)

try:
    # Sensitivity analysis
    api_response = api_instance.sensitivity_analysis(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->sensitivity_analysis: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::SensitivityAnalysis.new
payload.portfolio_tickers = ["HD", "PG", "EBAY", "NVDA"]
payload.portfolio_weights = [0.25, 0.25, 0.25, 0.25]
payload.frequency_interval = "day"

sensitivity_factor = AtomApi::SensitivityFactor.new
sensitivity_factor.ticker = "AGG"
sensitivity_factor.change_amount = -0.05
sensitivity_factor.change_duration = 3
sensitivity_factor.lag = 0
payload.sensitivity_factor = sensitivity_factor
payload.start_date = "2015-08-11"
payload.end_date = "2016-12-31"
payload.trading_days_per_year = 252

begin
  #Sensitivity analysis
  result = api_instance.sensitivity_analysis(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->sensitivity_analysis: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

SensitivityFactor factor = new SensitivityFactor(ticker="AGG",
     changeAmount=-0.05,
     changeDuration=3,
     lag=0);

SensitivityAnalysis payload = new SensitivityAnalysis(portfolioTickers=["HD", "PG", "EBAY", "NVDA"],
      portfolioWeights=[0.25, 0.25, 0.25, 0.25],
      frequencyInterval="day",
      sensitivityFactor=factor,
      startDate="2015-08-11",
      endDate="2016-12-31",
      tradingDaysPerYear=252);
try {
    SensitivityAnalysisResponse result = apiInstance.sensitivityAnalysis(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#sensitivityAnalysis");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var factor = new atom_api.SensitivityFactor(ticker="AGG",
    changeAmount=-0.05,
    changeDuration=3,
    lag=0)

var payload = new atom_api.SensitivityAnalysis(portfolioTickers=["HD", "PG", "EBAY", "NVDA"],
   portfolioWeights=[0.25, 0.25, 0.25, 0.25],
   frequencyInterval="day",
   sensitivityFactor=factor,
   startDate="2015-08-11",
   endDate="2016-12-31",
   tradingDaysPerYear=252);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.sensitivityAnalysis(payload, callback);

ARGUMENTS

Parameter Description
portfolio_tickers
array, required
Portfolio tickers, referencing securities defined in the Nucleus API.
portfolio_weights
array, required
Portfolio weights, corresponding to portfolio_tickers. Must sum to 1.0.
frequency_interval
string, required
Unit of time associated with change_duration and lag. Must be one of year, quarter, month, week, or day.
sensitivity_factor
map, required
A factor to analyze, defined as a hypothetical price movement for a security, index, or other instrument.
      ticker
      string, required
Ticker representing the factor, referencing a security defined in the Nucleus API.
      change_amount
      float, required
A percentage price change, represented in decimal format. Can be positive or negative.
      change_duration
      integer, required
Number of time periods over which change_amount is to take place, where each period represents frequency_interval.
      lag
      integer
Number of time periods between the factor signal and the portfolio’s response to that signal, where each period represents frequency_interval. For example, a value of 3 indicates that the portfolio responds 3 periods after the factor moves. Defaults to 0, and cannot be negative.
start_date
date
Start date used for ticker price history. Defaults to earliest common date among portfolio_tickers and sensitivity_factor ticker prices.
end_date
date
End date used for ticker price history. Defaults to latest common date among portfolio_tickers and sensitivity_factor ticker prices.
trading_days_per_year
integer
The number of days per year for which a portfolio is subject to market fluctuation. Defaults to 252.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.

Example Response

{
    "portfolio_impact": 0.03466700648259927,
    "t_statistic": -2.401636667959841,
    "margin_of_error": 0.02829157510133723
}

RESPONSE

Field Description
portfolio_impact Expected impact of sensitivity_factor on the portfolio’s return. The associated unit of time is the base unit indicated by frequency_interval in the request (for example, week = 1 week).
t_statistic Raw t-statistic from the regression analysis, typically used to determine statistical significance of the regression coefficient.
margin_of_error Estimated margin of error pertaining to portfolio_impact at a 95% confidence level.

NUCLEUS DATA DEPENDENCIES

          1. Securities: POST /security
          2. Security Prices: POST /security_price

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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.AnnuityDepositSchedule(deposit_amount=500,
   deposit_frequency_interval="year",
   adjust_deposit_for_inflation=True)
payload = atom_api.AnnuityCalculatorAnnuityAmount(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_schedule)

try:
    # Annuity calculator - annuity amount
    api_response = api_instance.annuity_calculator_annuity_amount(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->annuity_calculator_annuity_amount: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::AnnuityCalculatorAnnuityAmount.new
payload.portfolio_return = 0.1
payload.initial_balance = 2000
payload.accumulation_horizon = 3
payload.decumulation_horizon = 2
payload.annuity_frequency_interval = "year"
payload.inflation_rate = 0.02
payload.tax_rate = 0.25

deposit_schedule = AtomApi::AnnuityDepositSchedule.new
deposit_schedule.deposit_amount = 500
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Annuity calculator - annuity amount
  result = api_instance.annuity_calculator_annuity_amount(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->annuity_calculator_annuity_amount: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

AnnuityDepositSchedule depositSchedule = new AnnuityDepositSchedule(depositAmount=500,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true);

AnnuityCalculatorAnnuityAmount payload = new AnnuityCalculatorAnnuityAmount(portfolioReturn=0.1,
    initialBalance=2000,
    accumulationHorizon=3,
    decumulationHorizon=2,
    annuityFrequencyInterval="year",
    inflationRate=0.02,
    taxRate=0.25,
    depositSchedule=depositSchedule);
try {
    AnnuityAmountResponse result = apiInstance.annuityCalculatorAnnuityAmount(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#annuityCalculatorAnnuityAmount");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.AnnuityDepositSchedule(depositAmount=500,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true)

var payload = new atom_api.AnnuityCalculatorAnnuityAmount(portfolioReturn=0.1,
    initialBalance=2000,
    accumulationHorizon=3,
    decumulationHorizon=2,
    annuityFrequencyInterval="year",
    inflationRate=0.02,
    taxRate=0.25,
    depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.annuityCalculatorAnnuityAmount(payload, callback);

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 year, quarter, month, week, or day. 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 ongoing deposits to be made during the accumulation_horizon. Includes the fields shown below.
      deposit_amount
      number
The periodic value of the deposit. Must be greater than or equal to 0. Defaults to 0.
      deposit_frequency_interval
      string
The unit of time associated with deposit_amount. Must be one of year, quarter, month, week, or day. Defaults to year.

Example Response

{
    "annuity_amount": 1753.96,
    "annuity_frequency_interval": "year",
    "total_earnings": 1482.95,
    "total_contributions": 1530.2,
    "cumulative_annuity_amount": 5013.15,
    "total_taxes": 1671.05,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 2000
        },
        "1": {
            "period_earnings": 200,
            "period_contribution": 500,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 200,
            "cumulative_contributions": 500,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 2700
        },
        "2": {
            "period_earnings": 270,
            "period_contribution": 510,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 470,
            "cumulative_contributions": 1010,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 3480
        },
        "3": {
            "period_earnings": 348,
            "period_contribution": 520.2,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 818,
            "cumulative_contributions": 1530.2,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 4348.2
        },
        "4": {
            "period_earnings": 434.82,
            "period_contribution": 0,
            "period_withdrawal": 2481.76,
            "period_tax": 827.25,
            "cumulative_earnings": 1252.82,
            "cumulative_contributions": 1530.2,
            "cumulative_withdrawals": 2481.76,
            "cumulative_tax": 827.25,
            "ending_balance": 2301.26
        },
        "5": {
            "period_earnings": 230.13,
            "period_contribution": 0,
            "period_withdrawal": 2531.39,
            "period_tax": 843.8,
            "cumulative_earnings": 1482.95,
            "cumulative_contributions": 1530.2,
            "cumulative_withdrawals": 5013.15,
            "cumulative_tax": 1671.05,
            "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.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
cumulative_annuity_amount The total amount received from the annuity over the course of the plan.
total_taxes The total taxes paid on annuity payments over decumulation_horizon.
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.
      period_withdrawal
      
The withdrawal made for this period.
      period_tax
      
The tax amount 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.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      cumulative_tax
      
The cumulative taxes 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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.AnnuityDepositSchedule(deposit_amount=500,
   deposit_frequency_interval="year",
   adjust_deposit_for_inflation=True)
payload = atom_api.AnnuityCalculatorInitialBalance(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_schedule)

try:
    # Annuity calculator - initial balance
    api_response = api_instance.annuity_calculator_initial_balance(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->annuity_calculator_initial_balance: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::AnnuityCalculatorInitialBalance.new
payload.portfolio_return = 0.1
payload.accumulation_horizon = 3
payload.decumulation_horizon = 2
payload.annuity_amount = 3000
payload.annuity_frequency_interval = "year"
payload.inflation_rate = 0.02
payload.tax_rate = 0.25

deposit_schedule = AtomApi::AnnuityDepositSchedule.new
deposit_schedule.deposit_amount = 500
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Annuity calculator - initial balance
  result = api_instance.annuity_calculator_initial_balance(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->annuity_calculator_initial_balance: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

AnnuityDepositSchedule depositSchedule = new AnnuityDepositSchedule(depositAmount=500,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true);

AnnuityCalculatorInitialBalance payload = new AnnuityCalculatorInitialBalance(portfolioReturn=0.1,
    accumulationHorizon=3,
    decumulationHorizon=2,
    annuityAmount=3000,
    annuityFrequencyInterval="year",
    inflationRate=0.02,
    taxRate=0.25,
    depositSchedule=depositSchedule);
try {
    AnnuityInitialbalanceResponse result = apiInstance.annuityCalculatorInitialBalance(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#annuityCalculatorInitialBalance");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.AnnuityDepositSchedule(depositAmount=500,
  depositFrequencyInterval="year",
  adjustDepositForInflation=true)

var payload = new atom_api.AnnuityCalculatorInitialBalance(portfolioReturn=0.1,
   accumulationHorizon=3,
   decumulationHorizon=2,
   annuityAmount=3000,
   annuityFrequencyInterval="year",
   inflationRate=0.02,
   taxRate=0.25,
   depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.annuityCalculatorInitialBalance(payload, callback);

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 year, quarter, month, week, or day. 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 ongoing deposits to be made during the accumulation_horizon. Includes the fields shown below.
      deposit_amount
      number
The periodic value of the deposit. Must be greater than or equal to 0. Defaults to 0.
      deposit_frequency_interval
      string
The unit of time associated with deposit_amount. Must be one of year, quarter, month, week, or day. Defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, deposit_amount will be adjusted over time based on inflation_rate. Defaults to true.

Example Response

{
    "initial_balance": 4320.83,
    "total_earnings": 2723.53,
    "total_contributions": 1530.2,
    "cumulative_annuity_amount": 8574.56,
    "total_taxes": 2858.19,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 4320.83
        },
        "1": {
            "period_earnings": 432.08,
            "period_contribution": 500,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 432.08,
            "cumulative_contributions": 500,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 5252.91
        },
        "2": {
            "period_earnings": 525.29,
            "period_contribution": 510,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 957.37,
            "cumulative_contributions": 1010,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 6288.21
        },
        "3": {
            "period_earnings": 628.82,
            "period_contribution": 520.2,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 1586.2,
            "cumulative_contributions": 1530.2,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 7437.23
        },
        "4": {
            "period_earnings": 743.72,
            "period_contribution": 0,
            "period_withdrawal": 4244.83,
            "period_tax": 1414.94,
            "cumulative_earnings": 2329.92,
            "cumulative_contributions": 1530.2,
            "cumulative_withdrawals": 4244.83,
            "cumulative_tax": 1414.94,
            "ending_balance": 3936.12
        },
        "5": {
            "period_earnings": 393.61,
            "period_contribution": 0,
            "period_withdrawal": 4329.73,
            "period_tax": 1443.24,
            "cumulative_earnings": 2723.53,
            "cumulative_contributions": 1530.2,
            "cumulative_withdrawals": 8574.56,
            "cumulative_tax": 2858.19,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
initial_balance The starting balance in the annuity plan, prior to any periodic contributions.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
cumulative_annuity_amount The total amount received from the annuity over the course of the plan.
total_taxes The total taxes paid on annuity payments over decumulation_horizon.
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.
      period_withdrawal
      
The withdrawal made for this period.
      period_tax
      
The tax amount 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.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      cumulative_tax
      
The cumulative taxes 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,
        "deposit_schedule": {
            "deposit_frequency_interval": "year",
            "adjust_deposit_for_inflation": true
        }
    }' "https://api.hydrogenplatform.com/proton/v1/annuity_calculator/deposit_amount"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.AnnuityDepositSchedule(deposit_frequency_interval=<span class="string">"year"</span>,
   adjust_deposit_for_inflation=<span class="keyword">True</span>)
payload = atom_api.AnnuityCalculatorDepositAmount(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,
    deposit_schedule=deposit_schedule);

try:
    # Annuity calculator - deposit amount
    api_response = api_instance.annuity_calculator_deposit_amount(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->annuity_calculator_deposit_amount: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::AnnuityCalculatorDepositAmount.new
payload.portfolio_return = 0.1
payload.initial_balance = 2000
payload.accumulation_horizon = 3
payload.decumulation_horizon = 2
payload.annuity_amount = 3000
payload.annuity_frequency_interval = "year"
payload.inflation_rate = 0.02
payload.tax_rate = 0.25

deposit_schedule = AtomApi::AnnuityDepositSchedule.new
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Annuity calculator - deposit amount
  result = api_instance.annuity_calculator_deposit_amount(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->annuity_calculator_deposit_amount: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
AnnuityDepositSchedule depositSchedule = new AnnuityDepositSchedule(depositFrequencyInterval="year",
    adjustDepositForInflation=true);
AnnuityCalculatorDepositAmount payload = new AnnuityCalculatorDepositAmount(portfolioReturn=0.1,
    initialBalance=2000,
    accumulationHorizon=3,
    decumulationHorizon=2,
    annuityAmount=3000,
    annuityFrequencyInterval="year",
    inflationRate=0.02,
    taxRate=0.25,
    depositSchedule=depositSchedule);
try {
    AnnuityDepositamountResponse result = apiInstance.annuityCalculatorDepositAmount(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#annuityCalculatorDepositAmount");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.AnnuityDepositSchedule(depositFrequencyInterval="year",
  adjustDepositForInflation=true)

var payload = new atom_api.AnnuityCalculatorDepositAmount(portfolioReturn=0.1,
    initialBalance=2000,
    accumulationHorizon=3,
    decumulationHorizon=2,
    annuityAmount=3000,
    annuityFrequencyInterval="year",
    inflationRate=0.02,
    taxRate=0.25,
    deposit_schedule=deposit_schedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.annuityCalculatorDepositAmount(payload, callback);

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 year, quarter, month, week, or day. 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_frequency_interval
      string
The period interval to be used in relation to the deposit_amount. Must be one of year, quarter, month, week, or day. Defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, the deposit_amount will be increased by inflation_rate. Defaults to true.

Example Response

{
    "deposit_amount": 1415.97,
    "deposit_frequency_interval": "year",
    "total_earnings": 2241.12,
    "total_contributions": 4333.44,
    "cumulative_annuity_amount": 8574.56,
    "total_taxes": 2858.19,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 2000
        },
        "1": {
            "period_earnings": 200,
            "period_contribution": 1415.97,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 200,
            "cumulative_contributions": 1415.97,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 3615.97
        },
        "2": {
            "period_earnings": 361.6,
            "period_contribution": 1444.29,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 561.6,
            "cumulative_contributions": 2860.26,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 5421.86
        },
        "3": {
            "period_earnings": 542.19,
            "period_contribution": 1473.18,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 1103.78,
            "cumulative_contributions": 4333.44,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 7437.23
        },
        "4": {
            "period_earnings": 743.72,
            "period_contribution": 0,
            "period_withdrawal": 4244.83,
            "period_tax": 1414.94,
            "cumulative_earnings": 1847.51,
            "cumulative_contributions": 4333.44,
            "cumulative_withdrawals": 4244.83,
            "cumulative_tax": 1414.94,
            "ending_balance": 3936.12
        },
        "5": {
            "period_earnings": 393.61,
            "period_contribution": 0,
            "period_withdrawal": 4329.73,
            "period_tax": 1443.24,
            "cumulative_earnings": 2241.12,
            "cumulative_contributions": 4333.44,
            "cumulative_withdrawals": 8574.56,
            "cumulative_tax": 2858.19,
            "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.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
cumulative_annuity_amount The total amount received from the annuity over the course of the plan.
total_taxes The total taxes paid on annuity payments over decumulation_horizon.
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.
      period_withdrawal
      
The withdrawal made for this period.
      period_tax
      
The tax amount for 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_tax
      
The cumulative taxes 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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.AnnuityDepositSchedule(deposit_amount=500,
   deposit_frequency_interval="year",
   adjust_deposit_for_inflation=True)
payload = atom_api.AnnuityCalculatorDecumulationHorizon(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_schedule)

try:
    # Annuity calculator - decumulation horizon
    api_response = api_instance.annuity_calculator_decumulation_horizon(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->annuity_calculator_decumulation_horizon: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::AnnuityCalculatorDecumulationHorizon.new
payload.portfolio_return = 0.1
payload.initial_balance = 2000
payload.accumulation_horizon = 3
payload.annuity_amount = 3000
payload.annuity_frequency_interval = "year"
payload.inflation_rate = 0.02
payload.tax_rate = 0.25

deposit_schedule = AtomApi::AnnuityDepositSchedule.new
deposit_schedule.deposit_amount = 500
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Annuity calculator - decumulation horizon
  result = api_instance.annuity_calculator_decumulation_horizon(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->annuity_calculator_decumulation_horizon: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

AnnuityDepositSchedule depositSchedule = new AnnuityDepositSchedule(depositAmount=500,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true);

AnnuityCalculatorDecumulationHorizon payload = new AnnuityCalculatorAccumulationHorizon(portfolioReturn=0.1,
    initialBalance=2000,
    accumulationHorizon=3,
    annuityAmount=3000,
    annuityFrequencyInterval="year",
    inflationRate=0.02,
    taxRate=0.25,
    depositSchedule=depositSchedule);
try {
    AnnuityDecumulationResponse result = apiInstance.annuityCalculatorDecumulationHorizon(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#annuityCalculatorDecumulationHorizon");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.AnnuityDepositSchedule(depositAmount=500,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true)

var payload = new atom_api.AnnuityCalculatorDecumulationHorizon(portfolioReturn=0.1,
    initialBalance=2000,
    accumulationHorizon=3,
    annuityAmount=3000,
    annuityFrequencyInterval="year",
    inflationRate=0.02,
    taxRate=0.25,
    depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.annuityCalculatorDecumulationHorizon(payload, callback);

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 year, quarter, month, week, or day. 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 ongoing deposits to be made during the accumulation_horizon. Includes the fields shown below.
      deposit_amount
      number
The periodic value of the deposit. Must be greater than or equal to 0. Defaults to 0.
      deposit_frequency_interval
      string
The unit of time associated with deposit_amount. Must be one of year, quarter, month, week, or day. Defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, deposit_amount will be adjusted over time based on inflation_rate. Defaults to true.

Example Response

{
    "decumulation_horizon": {
        "years": 1,
        "months": 1,
        "days": 12
    },
    "total_earnings": 1259.94,
    "total_contributions": 1530.2,
    "cumulative_annuity_amount": 4790.14,
    "total_taxes": 1596.71,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 2000
        },
        "1": {
            "period_earnings": 200,
            "period_contribution": 500,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 200,
            "cumulative_contributions": 500,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 2700
        },
        "2": {
            "period_earnings": 270,
            "period_contribution": 510,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 470,
            "cumulative_contributions": 1010,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 3480
        },
        "3": {
            "period_earnings": 348,
            "period_contribution": 520.2,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 818,
            "cumulative_contributions": 1530.2,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 4348.2
        },
        "4": {
            "period_earnings": 434.82,
            "period_contribution": 0,
            "period_withdrawal": 4244.83,
            "period_tax": 1414.94,
            "cumulative_earnings": 1252.82,
            "cumulative_contributions": 1530.2,
            "cumulative_withdrawals": 4244.83,
            "cumulative_tax": 1414.94,
            "ending_balance": 538.19
        },
        "5": {
            "period_earnings": 7.12,
            "period_contribution": 0,
            "period_withdrawal": 545.31,
            "period_tax": 181.77,
            "cumulative_earnings": 1259.94,
            "cumulative_contributions": 1530.2,
            "cumulative_withdrawals": 4790.14,
            "cumulative_tax": 1596.71,
            "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.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
cumulative_annuity_amount The total amount received from the annuity over the course of the plan.
total_taxes The total taxes paid on annuity payments over decumulation_horizon.
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.
      period_withdrawal
      
The withdrawal made for this period.
      period_tax
      
The tax amount 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.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      cumulative_tax
      
The cumulative taxes up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

Accumulation Horizon

This service 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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.AnnuityDepositSchedule(deposit_amount=500,
   deposit_frequency_interval="year",
   adjust_deposit_for_inflation=True)
payload = atom_api.AnnuityCalculatorAccumulationHorizon(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_schedule)

try:
    # Annuity calculator - accumulation horizon
    api_response = api_instance.annuity_calculator_accumulation_horizon(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->annuity_calculator_accumulation_horizon: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::AnnuityCalculatorAccumulationHorizon.new
payload.portfolio_return = 0.1
payload.initial_balance = 2000
payload.decumulation_horizon = 2
payload.annuity_amount = 3000
payload.annuity_frequency_interval = "year"
payload.inflation_rate = 0.02
payload.tax_rate = 0.25

deposit_schedule = AtomApi::AnnuityDepositSchedule.new
deposit_schedule.deposit_amount = 500
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Annuity calculator - accumulation horizon
  result = api_instance.annuity_calculator_accumulation_horizon(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->annuity_calculator_accumulation_horizon: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

AnnuityDepositSchedule depositSchedule = new AnnuityDepositSchedule(depositAmount=500,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true);

AnnuityCalculatorAccumulationHorizon payload = new AnnuityCalculatorAccumulationHorizon(portfolioReturn=0.1,
      initialBalance=2000,
      decumulationHorizon=2,
      annuityAmount=3000,
      annuityFrequencyInterval="year",
      inflationRate=0.02,
      taxRate=0.25,
      depositSchedule=depositSchedule);
try {
    AnnuityAccumulationResponse result = apiInstance.annuityCalculatorAccumulationHorizon(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#annuityCalculatorAccumulationHorizon");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.AnnuityDepositSchedule(depositAmount=500,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true)

var payload = new atom_api.AnnuityCalculatorAccumulationHorizon(portfolioReturn=0.1,
    initialBalance=2000,
    decumulationHorizon=2,
    annuityAmount=3000,
    annuityFrequencyInterval="year",
    inflationRate=0.02,
    taxRate=0.25,
    depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.annuityCalculatorAccumulationHorizon(payload, callback);

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 ongoing deposits to be made during the accumulation_horizon. Includes the fields shown below.
      deposit_amount
      number
The periodic value of the deposit. Must be greater than or equal to 0. Defaults to 0.
      deposit_frequency_interval
      string
The unit of time associated with deposit_amount. Must be one of year, quarter, month, week, or day. Defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, deposit_amount will be adjusted over time based on inflation_rate. Defaults to true.

Example Response

{
    "accumulation_horizon": {
        "years": 6,
        "months": 0,
        "days": 0
    },
    "total_earnings": 3632.85,
    "total_contributions": 3467.25,
    "cumulative_annuity_amount": 9100.11,
    "total_taxes": 3033.37,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 2000
        },
        "1": {
            "period_earnings": 200,
            "period_contribution": 500,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 200,
            "cumulative_contributions": 500,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 2700
        },
        "2": {
            "period_earnings": 270,
            "period_contribution": 510,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 470,
            "cumulative_contributions": 1010,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 3480
        },
        "3": {
            "period_earnings": 348,
            "period_contribution": 520.2,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 818,
            "cumulative_contributions": 1530.2,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 4348.2
        },
        "4": {
            "period_earnings": 434.82,
            "period_contribution": 530.6,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 1252.82,
            "cumulative_contributions": 2060.8,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 5313.62
        },
        "5": {
            "period_earnings": 531.36,
            "period_contribution": 541.22,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 1784.18,
            "cumulative_contributions": 2602.02,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 6386.2
        },
        "6": {
            "period_earnings": 638.62,
            "period_contribution": 552.04,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 2422.8,
            "cumulative_contributions": 3154.06,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 7576.86
        },
        "7": {
            "period_earnings": 3.01,
            "period_contribution": 313.19,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 2425.81,
            "cumulative_contributions": 3467.25,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 7893.06
        },
        "8": {
            "period_earnings": 789.31,
            "period_contribution": 0,
            "period_withdrawal": 4505,
            "period_tax": 1501.67,
            "cumulative_earnings": 3215.12,
            "cumulative_contributions": 3467.25,
            "cumulative_withdrawals": 4505,
            "cumulative_tax": 1501.67,
            "ending_balance": 4177.37
        },
        "9": {
            "period_earnings": 417.74,
            "period_contribution": 0,
            "period_withdrawal": 4595.1,
            "period_tax": 1531.7,
            "cumulative_earnings": 3632.85,
            "cumulative_contributions": 3467.25,
            "cumulative_withdrawals": 9100.11,
            "cumulative_tax": 3033.37,
            "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.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
cumulative_annuity_amount The total amount received from the annuity over the course of the plan.
total_taxes The total taxes paid on annuity payments over decumulation_horizon.
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.
      period_withdrawal
      
The withdrawal made for this period.
      period_tax
      
The tax amount 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.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      cumulative_tax
      
The cumulative taxes up to and including this period.
      ending_balance
      
The ending balance, inclusive of earnings and contributions for the current period.

Variable Annuity

When planning for retirement or other financial outcomes, this service projects a variable annuity plan that is tied to a group of underlying investments. The Monte Carlo-based projection can help to evaluate potential annuity results and get a better understanding of how a variable annuity product may behave through both the accumulation phase and the payout phase.

HTTP REQUEST

POST /variable_annuity

Example Request

curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
  -H "Content-Type: application/json" \
  -d '{
        "portfolio_tickers": [
            "HD",
            "CVX",
            "JNJ"
        ],
        "portfolio_weights": [
            0.3,
            0.3,
            0.4
        ],
        "accumulation_horizon": 4,
        "decumulation_horizon": 3,
        "initial_balance": 25000,
        "frequency_interval": "year",
        "deposit_schedule": {
            "deposit_amount": 1000    ,
            "deposit_frequency_interval": "year",
            "adjust_deposit_for_inflation": true
        },
        "inflation_rate": 0.01,
        "tax_rate": 0.2,
        "annuitization_rate": 0.05,
        "guaranteed_rate_benefit": [
            {
                "start": 1,
                "end": 7,
                "min_rate": 0.0,
                "max_rate": 0.15
            }
        ],
        "guaranteed_accumulation_benefit": 40000,
        "n": 1000,
        "result_type": "median",
        "p": 50,
        "remove_outliers": true,
        "start_date": "2016-01-01",
        "end_date": "2018-01-01",
        "trading_days_per_year": 252,
        "use_proxy_data": false
}' "https://api.hydrogenplatform.com/proton/v1/variable_annuity"

ARGUMENTS

Parameter Description
portfolio_tickers
array, required
Portfolio tickers, referencing securities defined in the Nucleus API.
portfolio_weights
array, required
Portfolio weights, corresponding to portfolio_tickers. Must sum to 1.0. Must be the same length as portfolio_tickers.
accumulation_horizon
integer, required
The number of time periods until the payout phase begins.
decumulation_horizon
integer, required
The number of time periods in the payout or decumulation phase.
initial_balance
number, required
The starting balance in the annuity plan, prior to any ongoing contributions. Must be greater than or equal to 0.
frequency_interval
string
Unit of time associated with accumulation_horizon, decumulation_horizon, start, end, and annuity payments. Value may be one of: year, quarter, month, week, day.
deposit_schedule
map
The schedule of ongoing deposits to be made during the accumulation_horizon. Includes the fields shown below.
      deposit_amount
      number
The periodic value of the deposit. Must be greater than or equal to 0. Defaults to 0.
      deposit_frequency_interval
      string
The period interval to be used in relation to deposit_amount. Must be one of year, quarter, month, week, or day. Defaults to year.
      adjust_deposit_for_inflation
      boolean
If true, deposit_amount will be adjusted over time based on inflation_rate. Defaults to true.
inflation_rate
float
The annualized rate of inflation. Defaults to 0.
tax_rate
float
The tax rate applied to annuity payouts. Defaults to 0.
annuitization_rate
float
The discount rate used to calculate annuity payout amounts during decumulation_horizon. Defaults to 0.
guaranteed_rate_benefit
array
Boundaries enforced on the plan’s rate of return. Each underlying map includes the fields below.
      start
      integer
The starting period for the guarantee, where 1 indicates the first period in accumulation_horizon. Must be greater than or equal to 1. Defaults to 1.
      end
      integer
The ending period for the guarantee. Must be less than or equal to the sum of accumulation_horizon and decumulation_horizon. Defaults to the sum of accumulation_horizon and decumulation_horizon.
      min_rate
      float
The minimum allowable rate. Must be less than or equal to max_rate.
      max_rate
      float
The maximum allowable rate. Must be greater than or equal to min_rate.
guaranteed_accumulation_benefit
number
A guaranteed lower bound for the plan balance at the end of accumulation_horizon.
n
integer
The number of Monte Carlo simulations to run. Defaults to 1000.
result_type
string
The type of Monte Carlo result to consider. Must be one of mean, median, or custom. Defaults to median.
p
number
A Monte Carlo result percentile to consider, applicable when result_type is custom. Must be between 0 and 100 inclusive. Defaults to 50.
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. Defaults to false.
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.
trading_days_per_year
integer
The number of days per year for which a portfolio is subject to market fluctuation. Defaults to 252.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.

Example Response

{
    "accumulation_balance": 46331.26,
    "total_earnings": 29635.08,
    "total_contributions": 4101.01,
    "total_withdrawals": 46988.87,
    "total_taxes": 11747.22,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 25000
        },
        "1": {
            "period_earnings": 3750,
            "period_contribution": 1010,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 3750,
            "cumulative_contributions": 1010,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 29760
        },
        "2": {
            "period_earnings": 4244.4,
            "period_contribution": 1020.1,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 7994.4,
            "cumulative_contributions": 2030.1,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 35024.5
        },
        "3": {
            "period_earnings": 4120.74,
            "period_contribution": 1030.3,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 12115.14,
            "cumulative_contributions": 3060.4,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 40175.54
        },
        "4": {
            "period_earnings": 5115.12,
            "period_contribution": 1040.6,
            "period_withdrawal": 0,
            "period_tax": 0,
            "cumulative_earnings": 17230.26,
            "cumulative_contributions": 4101.01,
            "cumulative_withdrawals": 0,
            "cumulative_tax": 0,
            "ending_balance": 46331.26
        },
        "5": {
            "period_earnings": 5696.16,
            "period_contribution": 0,
            "period_withdrawal": 14556.13,
            "period_tax": 3639.03,
            "cumulative_earnings": 22926.42,
            "cumulative_contributions": 4101.01,
            "cumulative_withdrawals": 14556.13,
            "cumulative_tax": 3639.03,
            "ending_balance": 33832.27
        },
        "6": {
            "period_earnings": 4395.9,
            "period_contribution": 0,
            "period_withdrawal": 15664.22,
            "period_tax": 3916.06,
            "cumulative_earnings": 27322.31,
            "cumulative_contributions": 4101.01,
            "cumulative_withdrawals": 30220.35,
            "cumulative_tax": 7555.09,
            "ending_balance": 18647.88
        },
        "7": {
            "period_earnings": 2312.76,
            "period_contribution": 0,
            "period_withdrawal": 16768.52,
            "period_tax": 4192.13,
            "cumulative_earnings": 29635.08,
            "cumulative_contributions": 4101.01,
            "cumulative_withdrawals": 46988.87,
            "cumulative_tax": 11747.22,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
accumulation_balance The balance at the end of accumulation_horizon, before annuity payments occur.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_withdrawals The total amount of annuity payments over decumulation_horizon.
total_taxes The total taxes paid on annuity payments over decumulation_horizon.
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.
      period_withdrawal
      
The withdrawal made for this period.
      period_tax
      
The tax amount 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.
      cumulative_withdrawals
      
The cumulative withdrawals made up to and including this period.
      cumulative_tax
      
The cumulative taxes 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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))

education_config = atom_api.EducationConfig(start_age=18, end_age=22, total_annual_cost=40000)
children_education_config = atom_api.ChildrenEducationConfig(current_age=17,
  education_config=[education_config])

income_config = atom_api.IncomeConfig(annual_net_take_home_pay=50000,
  percentage_of_income_covered=1,
  income_benefit_duration=5)

beneficiary_bequest_config = atom_api.BeneficiaryBequestConfig(years_until_bequest=1,
   bequest_amount=10000,
   bequest_duration=5)

payload = atom_api.LifeInsuranceCalculator(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=[children_education_config],
   income_config=[income_config],
   beneficiary_bequest_config=[beneficiary_bequest_config])

try:
    # Life insurance needs calculator
    api_response = api_instance.life_insurance_needs_calculator(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->life_insurance_needs_calculator: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::LifeInsuranceCalculator.new
payload.mortgage_balance = 200000
payload.other_debt = 100000
payload.interest_rate = 0.06
payload.end_of_life_expenses = 10000
payload.existing_life_insurance = 50000
payload.liquid_assets = 400000
payload.general_inflation_rate = 0.02
payload.education_inflation_rate = 0.05
payload.tax_rate = 0.25
payload.benefit_amount_rounding = 6
payload.margin_of_error = 0.05

children_education_config = AtomApi::ChildrenEducationConfig.new
children_education_config.current_age = 17
education_config = AtomApi::EducationConfig.new
education_config.start_age = 18
education_config.end_age = 22
education_config.total_annual_cost = 40000
children_education_config.education_config = education_config

payload.children_education_config = [children_education_config]

income_config = AtomApi::IncomeConfig.new
income_config.annual_net_take_home_pay = 50000
income_config.percentage_of_income_covered = 1
income_config.income_benefit_duration = 5
payload.income_config = [income_config]

beneficiary_bequest_config = AtomApi::BeneficiaryBequestConfig.new
beneficiary_bequest_config.years_until_bequest = 1
beneficiary_bequest_config.bequest_amount = 10000
beneficiary_bequest_config.bequest_duration = 5
payload.beneficiary_bequest_config = [beneficiary_bequest_config]

begin
  #Life insurance needs calculator
  result = api_instance.life_insurance_needs_calculator(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->life_insurance_needs_calculator: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

EducationConfig educationConfig = new EducationConfig(startAge=18,
  endAge=22,
  totalAnnualCost=40000);
ChildrenEducationConfig childrenEducationConfig = new ChildrenEducationConfig(currentAge=17,
  educationConfig=[educationConfig]);

IncomeConfig incomeConfig = new IncomeConfig(annualNetTakeHomePay=50000,
   percentageOfIncomeCovered=1,
   incomeBenefitDuration=5);

BeneficiaryBequestConfig bequest = new BeneficiaryBequestConfig(yearsUntilBequest=1,
  bequestAmount=10000,
  bequestDuration=5);

LifeInsuranceCalculator payload = new LifeInsuranceCalculator(mortgageBalance=200000,
    otherDebt=100000,
    interestRate=0.06,
    endOfLifeExpenses=10000,
    existingLifeInsurance=50000,
    liquidAssets=400000,
    generalInflationRate=0.02,
    educationInflationRate=0.05,
    taxRate=0.25,
    benefitAmountRounding=6,
    marginOfError=0.05,
    childrenEducationConfig=[childrenEducationConfig],
    incomeConfig=[incomeConfig],
    beneficiaryBequestConfig=[bequest);
try {
    LifeInsuranceNeedsResponse result = apiInstance.lifeInsuranceNeedsCalculator(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#lifeInsuranceNeedsCalculator");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var educationConig = new atom_api.EducationConfig(startAge=18,
    endAge=22,
    totalAnnualCost=40000)

var childrenEducationConfig = new atom_api.ChildrenEducationConfig(currentAge=17,
    educationConfig=[educationConfig])

var incomeConfig = new atom_api.IncomeConfig(annualNetTakeHomePay=50000,
   percentageOfIncomeCovered=1,
   incomeBenefitDuration=5)

var beneficiaryBequestConfig = new atom_api.BeneficiaryBequestConfig(yearsUntilBequest=1,
   bequestAmount=10000,
   bequestDuration=5)

var payload = new atom_api.LifeInsuranceCalculator(mortgageBalance=200000,
   otherDebt=100000,
   interestRate=0.06,
   endOfLifeExpenses=10000,
   existingLifeInsurance=50000,
   liquidAssets=400000,
   generalInflationRate=0.02,
   educationInflationRate=0.05,
   taxRate=0.25,
   benefitAmountRounding=6,
   marginOfError=0.05,
   childrenEducationConfig=[childrenEducationConfig],
   incomeConfig=[incomeConfig],
   beneficiaryBequestConfig=[beneficiaryBequestConfig]);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.lifeInsuranceNeedsCalculator(payload, callback);

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": 390000,
    "total_life_insurance_needed": 440000,
    "life_insurance_needs_breakdown": {
        "mortgage": 200000,
        "other": 100000,
        "education": 213033.65,
        "income_replacement": 243087.46,
        "beneficiary_bequest": 47454.39,
        "end_of_life": 10000
    },
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_withdrawal": 0,
            "cumulative_earnings": 0,
            "cumulative_withdrawals": 0,
            "ending_balance": 840000
        },
        "1": {
            "period_earnings": 0,
            "period_withdrawal": 361000,
            "cumulative_earnings": 0,
            "cumulative_withdrawals": 361000,
            "ending_balance": 479000
        },
        "2": {
            "period_earnings": 21555,
            "period_withdrawal": 106524,
            "cumulative_earnings": 21555,
            "cumulative_withdrawals": 467524,
            "ending_balance": 394031
        },
        "3": {
            "period_earnings": 17731.39,
            "period_withdrawal": 109977.48,
            "cumulative_earnings": 39286.39,
            "cumulative_withdrawals": 577501.48,
            "ending_balance": 301784.91
        },
        "4": {
            "period_earnings": 13580.32,
            "period_withdrawal": 113566.18,
            "cumulative_earnings": 52866.72,
            "cumulative_withdrawals": 691067.66,
            "ending_balance": 201799.06
        },
        "5": {
            "period_earnings": 9080.96,
            "period_withdrawal": 117296.11,
            "cumulative_earnings": 61947.67,
            "cumulative_withdrawals": 808363.77,
            "ending_balance": 93583.9
        },
        "6": {
            "period_earnings": 4211.28,
            "period_withdrawal": 64865.45,
            "cumulative_earnings": 66158.95,
            "cumulative_withdrawals": 873229.22,
            "ending_balance": 32929.73
        }
    }
}

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 0 represents the assets available including the calculated insurance payment. Period 1 reflects any immediate expenses, and the remaining balance is drawn down starting with period 2 to cover ongoing expenses.
      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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.EducationCalculatorDepositScheduleNoDepAmt(deposit_frequency_interval="year",
   adjust_deposit_for_inflation=True)
payload = atom_api.EducationCalculatorDepositAmount(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_schedule)

try:
    # Education calculator - deposit amount
    api_response = api_instance.education_calculator_deposit_amount(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->education_calculator_deposit_amount: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::EducationCalculatorDepositAmount.new
payload.initial_balance = 5000
payload.accumulation_horizon = 3
payload.decumulation_horizon = 4
payload.total_annual_cost = 40000
payload.portfolio_return = 0.06
payload.percent_of_costs_covered = 0.78
payload.education_inflation_rate = 0.05
payload.general_inflation_rate = 0.02
payload.tax_rate = 0.33

deposit_schedule = AtomApi::EducationCalculatorDepositScheduleNoDepAmt.new
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Education calculator - deposit amount
  result = api_instance.education_calculator_deposit_amount(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->education_calculator_deposit_amount: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

EducationCalculatorDepositScheduleNoDepAmt depositSchedule = new EducationCalculatorDepositScheduleNoDepAmt(depositFrequencyInterval="year",
 adjustDepositForInflation=true);

EducationCalculatorDepositAmount payload = new EducationCalculatorDepositAmount(initialBalance=5000,
    accumulationHorizon=3,
    decumulationHorizon=4,
    totalAnnualCost=40000,
    portfolioReturn=0.06,
    percentOfCostsCovered=0.78,
    educationInflationRate=0.05,
    generalInflationRate=0.02,
    taxRate=0.33,
    depositSchedule=depositSchedule);
try {
    EducationCalculatorDepositamountResponse result = apiInstance.educationCalculatorDepositAmount(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#educationCalculatorDepositAmount");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.EducationCalculatorDepositScheduleNoDepAmt(depositFrequencyInterval="year",
    adjustDepositForInflation=true)

var payload = new atom_api.EducationCalculatorDepositAmount(initialBalance=5000,
    accumulationHorizon=3,
    decumulationHorizon=4,
    totalAnnualCost=40000,
    portfolioReturn=0.06,
    percentOfCostsCovered=0.78,
    educationInflationRate=0.05,
    generalInflationRate=0.02,
    taxRate=0.33,
    depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.educationCalculatorDepositAmount(payload, callback);

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": 37564.93,
    "deposit_frequency_interval": "year",
    "projected_accumulation_savings": 127860.79,
    "total_earnings": 28506.82,
    "total_contributions": 279268.34,
    "total_cost": 209559.36,
    "total_taxes": 103215.8,
    "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": 37564.93,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 300,
            "cumulative_contributions": 37564.93,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 42864.93
        },
        "2": {
            "period_earnings": 2571.9,
            "period_contribution": 38316.23,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 2871.9,
            "cumulative_contributions": 75881.16,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 83753.06
        },
        "3": {
            "period_earnings": 5025.18,
            "period_contribution": 39082.55,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 7897.08,
            "cumulative_contributions": 114963.71,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 127860.79
        },
        "4": {
            "period_earnings": 7671.65,
            "period_contribution": 39864.2,
            "period_withdrawal": -48620.25,
            "period_taxes": -23947.29,
            "cumulative_earnings": 15568.73,
            "cumulative_contributions": 154827.92,
            "cumulative_withdrawals": -48620.25,
            "cumulative_taxes": -23947.29,
            "ending_balance": 102829.11
        },
        "5": {
            "period_earnings": 6169.75,
            "period_contribution": 40661.49,
            "period_withdrawal": -51051.26,
            "period_taxes": -25144.65,
            "cumulative_earnings": 21738.47,
            "cumulative_contributions": 195489.41,
            "cumulative_withdrawals": -99671.51,
            "cumulative_taxes": -49091.94,
            "ending_balance": 73464.43
        },
        "6": {
            "period_earnings": 4407.87,
            "period_contribution": 41474.72,
            "period_withdrawal": -53603.83,
            "period_taxes": -26401.88,
            "cumulative_earnings": 26146.34,
            "cumulative_contributions": 236964.13,
            "cumulative_withdrawals": -153275.34,
            "cumulative_taxes": -75493.82,
            "ending_balance": 39341.3
        },
        "7": {
            "period_earnings": 2360.48,
            "period_contribution": 42304.21,
            "period_withdrawal": -56284.02,
            "period_taxes": -27721.98,
            "cumulative_earnings": 28506.82,
            "cumulative_contributions": 279268.34,
            "cumulative_withdrawals": -209559.36,
            "cumulative_taxes": -103215.8,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
deposit_amount The deposit amount to meet the education goal.
deposit_frequency_interval The period interval associated with deposit_amount.
projected_accumulation_savings The projected balance at the end of accumulation_horizon.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_cost The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.EducationCalculatorDepositScheduleDepAmt(deposit_amount=4000,
     deposit_frequency_interval="year",
     adjust_deposit_for_inflation=True)
payload = atom_api.EducationCalculatorPercentCovered(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_schedule)

try:
    # Education calculator - percent covered
    api_response = api_instance.education_calculator_percent_covered(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->education_calculator_percent_covered: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::EducationCalculatorPercentCovered.new
payload.initial_balance = 5000
payload.accumulation_horizon = 3
payload.decumulation_horizon = 4
payload.total_annual_cost = 40000
payload.portfolio_return = 0.06
payload.education_inflation_rate = 0.05
payload.general_inflation_rate = 0.02
payload.tax_rate = 0.33

deposit_schedule = AtomApi::EducationCalculatorDepositScheduleDepAmt.new
deposit_schedule.deposit_amount = 4000
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Education calculator - percent covered
  result = api_instance.education_calculator_percent_covered(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->education_calculator_percent_covered: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

EducationCalculatorDepositScheduleDepAmt depositSchedule = new EducationCalculatorDepositScheduleDepAmt(depositAmount=4000,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true);

EducationCalculatorPercentCovered payload = new EducationCalculatorPercentCovered(initialBalance=5000,
    accumulationHorizon=3,
    decumulationHorizon=4,
    totalAnnualCost=40000,
    portfolioReturn=0.06,
    educationInflationRate=0.05,
    generalInflationRate=0.02,
    taxRate=0.33,
    depositSchedule=depositSchedule);
try {
    EducationCalculatorPctcoveredResponse result = apiInstance.educationCalculatorPercentCovered(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#educationCalculatorPercentCovered");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.EducationCalculatorDepositScheduleDepAmt(depositAmount=4000,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true)

var payload = new atom_api.EducationCalculatorPercentCovered(initialBalance=5000,
     accumulationHorizon=3,
     decumulationHorizon=4,
     totalAnnualCost=40000,
     portfolioReturn=0.06,
     educationInflationRate=0.05,
     generalInflationRate=0.02,
     taxRate=0.33,
     depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.educationCalculatorPercentCovered(payload, callback);

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

{
    "achievable_cost": 5047.62,
    "target_cost": 40000,
    "percent_of_costs_covered": 0.1262,
    "projected_accumulation_savings": 18935.88,
    "total_earnings": 4732.09,
    "total_contributions": 29737.13,
    "total_cost": 26444.38,
    "total_taxes": 13024.84,
    "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": -6135.41,
            "period_taxes": -3021.92,
            "cumulative_earnings": 2830.43,
            "cumulative_contributions": 16486.43,
            "cumulative_withdrawals": -6135.41,
            "cumulative_taxes": -3021.92,
            "ending_balance": 15159.54
        },
        "5": {
            "period_earnings": 909.57,
            "period_contribution": 4329.73,
            "period_withdrawal": -6442.18,
            "period_taxes": -3173.01,
            "cumulative_earnings": 3740.01,
            "cumulative_contributions": 20816.16,
            "cumulative_withdrawals": -12577.59,
            "cumulative_taxes": -6194.93,
            "ending_balance": 10783.65
        },
        "6": {
            "period_earnings": 647.02,
            "period_contribution": 4416.32,
            "period_withdrawal": -6764.29,
            "period_taxes": -3331.66,
            "cumulative_earnings": 4387.02,
            "cumulative_contributions": 25232.48,
            "cumulative_withdrawals": -19341.88,
            "cumulative_taxes": -9526.6,
            "ending_balance": 5751.04
        },
        "7": {
            "period_earnings": 345.06,
            "period_contribution": 4504.65,
            "period_withdrawal": -7102.5,
            "period_taxes": -3498.25,
            "cumulative_earnings": 4732.09,
            "cumulative_contributions": 29737.13,
            "cumulative_withdrawals": -26444.38,
            "cumulative_taxes": -13024.84,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
achievable_cost The annual cost that can be covered, expressed in today’s dollars.
target_cost The total_annual_cost input representing the target annual goal amount.
percent_of_costs_covered The percentage of target_cost that can be covered.
projected_accumulation_savings The projected balance at the end of accumulation_horizon.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_cost The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.EducationCalculatorDepositScheduleDepAmt(deposit_amount=4000,
   deposit_frequency_interval="year",
   adjust_deposit_for_inflation=True)
payload = atom_api.EducationCalculatorAnnualCost(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_schedule)

try:
    # Education calculator - total annual cost
    api_response = api_instance.education_calculator_annual_cost(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->education_calculator_annual_cost: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::EducationCalculatorAnnualCost.new
payload.initial_balance = 5000
payload.accumulation_horizon = 3
payload.decumulation_horizon = 4
payload.portfolio_return = 0.06
payload.percent_of_costs_covered = 1
payload.education_inflation_rate = 0.02
payload.tax_rate = 0.33

deposit_schedule = AtomApi::EducationCalculatorDepositScheduleDepAmt.new
deposit_schedule.deposit_amount = 4000
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Education calculator - total annual cost
  result = api_instance.education_calculator_annual_cost(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->education_calculator_annual_cost: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

EducationCalculatorDepositScheduleDepAmt depositSchedule = new EducationCalculatorDepositScheduleDepAmt(depositAmount=4000,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true);

EducationCalculatorAnnualCost payload = new EducationCalculatorAnnualCost(initialBalance=5000,
    accumulationHorizon=3,
    decumulationHorizon=4,
    portfolioReturn=0.06,
    percentOfCostsCovered=1,
    educationInflationRate=0.02,
    taxRate=0.33,
    depositSchedule=depositSchedule);
try {
    EducationCalculatorAnnualcostResponse result = apiInstance.educationCalculatorAnnualCost(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#educationCalculatorAnnualCost");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.EducationCalculatorDepositScheduleDepAmt(depositAmount=4000,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true)

var payload = new atom_api.EducationCalculatorAnnualCost(initialBalance=5000,
     accumulationHorizon=3,
     decumulationHorizon=4,
     portfolioReturn=0.06,
     percentOfCostsCovered=1,
     educationInflationRate=0.02,
     taxRate=0.33,
     depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.educationCalculatorAnnualCost(payload, callback);

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
      float
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": 6135.41,
    "total_annual_cost_adjusted": 5047.62,
    "projected_accumulation_savings": 18935.88,
    "total_earnings": 4732.09,
    "total_contributions": 29737.13,
    "total_cost": 26444.38,
    "total_taxes": 13024.84,
    "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": -6135.41,
            "period_taxes": -3021.92,
            "cumulative_earnings": 2830.43,
            "cumulative_contributions": 16486.43,
            "cumulative_withdrawals": -6135.41,
            "cumulative_taxes": -3021.92,
            "ending_balance": 15159.54
        },
        "5": {
            "period_earnings": 909.57,
            "period_contribution": 4329.73,
            "period_withdrawal": -6442.18,
            "period_taxes": -3173.01,
            "cumulative_earnings": 3740.01,
            "cumulative_contributions": 20816.16,
            "cumulative_withdrawals": -12577.59,
            "cumulative_taxes": -6194.93,
            "ending_balance": 10783.65
        },
        "6": {
            "period_earnings": 647.02,
            "period_contribution": 4416.32,
            "period_withdrawal": -6764.29,
            "period_taxes": -3331.66,
            "cumulative_earnings": 4387.02,
            "cumulative_contributions": 25232.48,
            "cumulative_withdrawals": -19341.88,
            "cumulative_taxes": -9526.6,
            "ending_balance": 5751.04
        },
        "7": {
            "period_earnings": 345.06,
            "period_contribution": 4504.65,
            "period_withdrawal": -7102.5,
            "period_taxes": -3498.25,
            "cumulative_earnings": 4732.09,
            "cumulative_contributions": 29737.13,
            "cumulative_withdrawals": -26444.38,
            "cumulative_taxes": -13024.84,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
total_annual_cost The total education cost per year that can be afforded.
total_annual_cost_adjusted The total education cost per year that can be afforded, represented in today’s dollars.
projected_accumulation_savings The projected balance at the end of accumulation_horizon.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_cost The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.DepositScheduleMajorPurchaseNoDepAmt(deposit_frequency_interval="year",
  adjust_deposit_for_inflation=True)
payload = atom_api.PurchaseCalculatorDepositAmount(purchase_horizon=5,
   purchase_amount=50000,
   portfolio_return=0.06,
   horizon_frequency_interval="year",
   current_savings=0,
   deposit_schedule=deposit_schedule,
   inflation_rate=0.02,
   investment_tax=0.25)

try:
    # Purchase calculator - deposit amount
    api_response = api_instance.purchase_calculator_deposit_amount(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->purchase_calculator_deposit_amount: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::PurchaseCalculatorDepositAmount.new
payload.purchase_horizon = 5
payload.purchase_amount = 50000
payload.portfolio_return = 0.06
payload.horizon_frequency_interval = "year"
payload.current_savings = 0

deposit_schedule = AtomApi::DepositScheduleMajorPurchaseNoDepAmt.new
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Purchase calculator - deposit amount
  result = api_instance.purchase_calculator_deposit_amount(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->purchase_calculator_deposit_amount: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

DepositScheduleMajorPurchaseNoDepAmt depositSchedule = new DepositScheduleMajorPurchaseNoDepAmt(depositFrequencyInterval="year",
    adjustDepositForInflation=true);

PurchaseCalculatorDepositAmount payload = new PurchaseCalculatorDepositAmount(purchaseHorizon=5,
    purchaseAmount=50000,
    portfolioReturn=0.06,
    horizonFrequencyInterval="year",
    currentSavings=0,
    depositSchedule=depositSchedule);
try {
    PurchaseCalculatorDepositamountResponse result = apiInstance.purchaseCalculatorDepositAmount(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#purchaseCalculatorDepositAmount");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.DepositScheduleMajorPurchaseNoDepAmt(depositFrequencyInterval="year",
     adjustDepositForInflation=true)

var payload = new atom_api.PurchaseCalculatorDepositAmount(purchaseHorizon=5,
   purchaseAmount=50000,
   portfolioReturn=0.06,
   horizonFrequencyInterval="year",
   currentSavings=0,
   depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.purchaseCalculatorDepositAmount(payload, callback);

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": 12574.34,
    "deposit_frequency_interval": "year",
    "adjusted_goal_amount": 73605.39,
    "projected_savings_at_purchase_horizon": 73605.39,
    "total_earnings": 8168.03,
    "total_contributions": 65437.36,
    "return_details": {
        "0": {
            "period_earnings": 0,
            "period_contribution": 0,
            "cumulative_earnings": 0,
            "cumulative_contributions": 0,
            "ending_balance": 0
        },
        "1": {
            "period_earnings": 0,
            "period_contribution": 12574.34,
            "cumulative_earnings": 0,
            "cumulative_contributions": 12574.34,
            "ending_balance": 12574.34
        },
        "2": {
            "period_earnings": 754.46,
            "period_contribution": 12825.82,
            "cumulative_earnings": 754.46,
            "cumulative_contributions": 25400.16,
            "ending_balance": 26154.62
        },
        "3": {
            "period_earnings": 1569.28,
            "period_contribution": 13082.34,
            "cumulative_earnings": 2323.74,
            "cumulative_contributions": 38482.5,
            "ending_balance": 40806.24
        },
        "4": {
            "period_earnings": 2448.37,
            "period_contribution": 13343.99,
            "cumulative_earnings": 4772.11,
            "cumulative_contributions": 51826.49,
            "ending_balance": 56598.6
        },
        "5": {
            "period_earnings": 3395.92,
            "period_contribution": 13610.87,
            "cumulative_earnings": 8168.03,
            "cumulative_contributions": 65437.36,
            "ending_balance": 73605.39
        }
    }
}

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.
adjusted_goal_amount The effective goal target amount, adjusted for taxes and inflation.
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.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
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.01,
        "investment_tax": 0.2
    }' "https://api.hydrogenplatform.com/proton/v1/purchase_calculator/amount"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.DepositScheduleMajorPurchaseDepAmt(deposit_amount=10000,
   deposit_frequency_interval="year",
   adjust_deposit_for_inflation=True)
payload = atom_api.PurchaseCalculatorAmount(purchase_horizon=6,
    portfolio_return=0.06,
    horizon_frequency_interval="year",
    current_savings=0,
    deposit_schedule=deposit_schedule,
    inflation_rate=0.0,
    investment_tax=0.0)

try:
    # Purchase calculator - purchase amount
    api_response = api_instance.purchase_calculator_purchase_amount(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->purchase_calculator_purchase_amount: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::PurchaseCalculatorAmount.new
payload.purchase_horizon = 6
payload.portfolio_return = 0.06
payload.horizon_frequency_interval = "year"
payload.current_savings = 0

deposit_schedule = AtomApi::DepositScheduleMajorPurchaseDepAmt.new
deposit_schedule.deposit_amount = 1000
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule
payload.inflation_rate = 0.0
payload.investment_tax = 0.0

begin
  #Purchase calculator - purchase amount
  result = api_instance.purchase_calculator_purchase_amount(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->purchase_calculator_purchase_amount: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

DepositScheduleMajorPurchaseDepAmt depositSchedule = new DepositScheduleMajorPurchaseDepAmt(depositAmount=10000,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true);

PurchaseCalculatorAmount payload = new PurchaseCalculatorAmount(purchaseHorizon=6,
    portfolioReturn=0.06,
    horizonFrequencyInterval="year",
    currentSavings=0,
    depositSchedule=depositSchedule,
    inflationRate=0.0,
    investmentTax=0.0);
try {
    PurchaseCalculatorPurchaseamountResponse result = apiInstance.purchaseCalculatorPurchaseAmount(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#purchaseCalculatorPurchaseAmount");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.DepositScheduleMajorPurchaseDepAmt(depositAmount=10000,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true)

var payload = new atom_api.PurchaseCalculatorAmount(purchaseHorizon=6,
    portfolioReturn=0.06,
    horizonFrequencyInterval="year",
    currentSavings=0,
    depositSchedule=depositSchedule,
    inflationRate=0.0,
    investmentTax=0.0);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.purchaseCalculatorPurchaseAmount(payload, callback);

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": 57119.83,
    "purchase_amount_adjusted": 53809.47,
    "projected_savings_at_purchase_horizon": 71399.79,
    "total_earnings": 9879.64,
    "total_contributions": 61520.15,
    "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": 10100,
            "cumulative_earnings": 600,
            "cumulative_contributions": 20100,
            "ending_balance": 20700
        },
        "3": {
            "period_earnings": 1242,
            "period_contribution": 10201,
            "cumulative_earnings": 1842,
            "cumulative_contributions": 30301,
            "ending_balance": 32143
        },
        "4": {
            "period_earnings": 1928.58,
            "period_contribution": 10303.01,
            "cumulative_earnings": 3770.58,
            "cumulative_contributions": 40604.01,
            "ending_balance": 44374.59
        },
        "5": {
            "period_earnings": 2662.48,
            "period_contribution": 10406.04,
            "cumulative_earnings": 6433.06,
            "cumulative_contributions": 51010.05,
            "ending_balance": 57443.11
        },
        "6": {
            "period_earnings": 3446.59,
            "period_contribution": 10510.1,
            "cumulative_earnings": 9879.64,
            "cumulative_contributions": 61520.15,
            "ending_balance": 71399.79
        }
    }
}

RESPONSE

Field Description
purchase_amount The amount of the major purchase.
purchase_amount_adjusted The amount of the major purchase, represented in today’s dollars.
projected_savings_at_purchase horizon The total amount of savings that are projected to be available at purchase_horizon, expressed in today’s dollars.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.DepositScheduleMajorPurchaseDepAmt(deposit_amount=10000,
     deposit_frequency_interval="year",
     adjust_deposit_for_inflation=True)
payload = atom_api.PurchaseCalculatorHorizon(purchase_amount=50000,
     portfolio_return=0.06,
     horizon_frequency_interval="year",
     current_savings=0,
     deposit_schedule=deposit_schedule,
     inflation_rate=0.02,
     investment_tax=0.25)

try:
    # Purchase calculator - horizon
    api_response = api_instance.purchase_calculator_horizon(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->purchase_calculator_horizon: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::PurchaseCalculatorHorizon.new
payload.purchase_amount = 50000
payload.portfolio_return = 0.06
payload.horizon_frequency_interval = "year"
payload.current_savings = 0

deposit_schedule = AtomApi::DepositScheduleMajorPurchaseDepAmt.new
deposit_schedule.deposit_amount = 1000
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Purchase calculator - horizon
  result = api_instance.purchase_calculator_horizon(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->purchase_calculator_horizon: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

DepositScheduleMajorPurchaseDepAmt depositSchedule = new DepositScheduleMajorPurchaseDepAmt(depositAmount=10000,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true);

PurchaseCalculatorHorizon payload = new PurchaseCalculatorHorizon(purchaseAmount=50000,
    portfolioReturn=0.06,
    horizonFrequencyInterval="year",
    currentSavings=0,
    depositSchedule=depositSchedule);
try {
    PurchaseCalculatorPurchasehorizonResponse result = apiInstance.purchaseCalculatorHorizon(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#purchaseCalculatorHorizon");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.DepositScheduleMajorPurchaseDepAmt(depositAmount=10000,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true)

var payload = new atom_api.PurchaseCalculatorHorizon(purchaseAmount=50000,
   portfolioReturn=0.06,
   horizonFrequencyInterval="year",
   currentSavings=0,
   depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.purchaseCalculatorHorizon(payload, callback);

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,
    "purchase_horizon_frequency_interval": "year",
    "adjusted_goal_amount": 76579.04,
    "projected_savings_at_purchase_horizon": 88736.15,
    "total_earnings": 14393.31,
    "total_contributions": 74342.83,
    "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": 10200,
            "cumulative_earnings": 600,
            "cumulative_contributions": 20200,
            "ending_balance": 20800
        },
        "3": {
            "period_earnings": 1248,
            "period_contribution": 10404,
            "cumulative_earnings": 1848,
            "cumulative_contributions": 30604,
            "ending_balance": 32452
        },
        "4": {
            "period_earnings": 1947.12,
            "period_contribution": 10612.08,
            "cumulative_earnings": 3795.12,
            "cumulative_contributions": 41216.08,
            "ending_balance": 45011.2
        },
        "5": {
            "period_earnings": 2700.67,
            "period_contribution": 10824.32,
            "cumulative_earnings": 6495.79,
            "cumulative_contributions": 52040.4,
            "ending_balance": 58536.19
        },
        "6": {
            "period_earnings": 3512.17,
            "period_contribution": 11040.81,
            "cumulative_earnings": 10007.96,
            "cumulative_contributions": 63081.21,
            "ending_balance": 73089.17
        },
        "7": {
            "period_earnings": 4385.35,
            "period_contribution": 11261.62,
            "cumulative_earnings": 14393.31,
            "cumulative_contributions": 74342.83,
            "ending_balance": 88736.15
        }
    }
}

RESPONSE

Field Description
purchase_horizon The number of periods needed in order to meet the major purchase goal.
purchase_horizon_frequency_interval The unit of time associated with purchase_horizon.
adjusted_goal_amount The effective goal target amount, adjusted for taxes and inflation.
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.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
payload = atom_api.MortgageCalculatorDownPayment(home_price=100000,
   periodic_payment=8000,
   interest_rate=0.04,
   mortgage_term=6)

try:
    # Mortgage calculator - down payment
    api_response = api_instance.mortgage_calculator_down_payment(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->mortgage_calculator_down_payment: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::MortgageCalculatorDownPayment.new
payload.home_price = 100000
payload.periodic_payment = 8000
payload.interest_rate = 0.04
payload.mortgage_term = 6

begin
  #Mortgage calculator - down payment
  result = api_instance.mortgage_calculator_down_payment(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->mortgage_calculator_down_payment: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
MortgageCalculatorDownPayment payload = new MortgageCalculatorDownPayment(homePrice=100000,
    periodicPayment=8000,
    interestRate=0.04,
    mortgageTerm=6);
try {
    MortgageCalculatorDownpaymentResponse result = apiInstance.mortgageCalculatorDownPayment(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#mortgageCalculatorDownPayment");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.MortgageCalculatorDownPayment(homePrice=100000,
   periodicPayment=8000,
   interestRate=0.04,
   mortgageTerm=6);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.mortgageCalculatorDownPayment(payload, callback);

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,
    "total_payment": 48000,
    "total_principal": 47454.78,
    "total_interest": 545.22,
    "total_home_cost": 100545.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.
total_payment The total mortgage payments made over mortgage_term.
total_principal The total amount that went toward the mortgage principal.
total_interest The total amount that went toward the mortgage interest.
total_home_cost The total cost of the home, including down payment and all mortgage payments. This value is greater than home_price when interest_rate is greater than 0.
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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
payload = atom_api.MortgageCalculatorHomePrice(down_payment=50000,
   periodic_payment=8000,
   interest_rate=0.04,
   mortgage_term=6)

try:
    # Mortgage calculator - home price
    api_response = api_instance.mortgage_calculator_home_price(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->mortgage_calculator_home_price: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::MortgageCalculatorHomePrice.new
payload.down_payment = 50000
payload.periodic_payment = 8000
payload.interest_rate = 0.04
payload.mortgage_term = 6

begin
  #Mortgage calculator - home price
  result = api_instance.mortgage_calculator_home_price(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->mortgage_calculator_home_price: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
MortgageCalculatorHomePrice payload = new MortgageCalculatorHomePrice(downPayment=50000,
    periodicPayment=8000,
    interestRate=0.04,
    mortgageTerm=6);
try {
    MortgageCalculatorHomepriceResponse result = apiInstance.mortgageCalculatorHomePrice(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#mortgageCalculatorHomePrice");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.MortgageCalculatorHomePrice(downPayment=50000,
   periodicPayment=8000,
   interestRate=0.04,
   mortgageTerm=6);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.mortgageCalculatorHomePrice(payload, callback);

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,
    "total_payment": 48000,
    "total_principal": 47454.78,
    "total_interest": 545.22,
    "total_home_cost": 98000,
    "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.
total_payment The total mortgage payments made over mortgage_term.
total_principal The total amount that went toward the mortgage principal.
total_interest The total amount that went toward the mortgage interest.
total_home_cost The total cost of the home, including down payment and all mortgage payments. This value is greater than home_price when interest_rate is greater than 0.
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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
payload = atom_api.MortgageCalculatorPeriodicPayment(home_price=100000,
     down_payment=50000,
     interest_rate=0.04,
     mortgage_term=6)

try:
    # Mortgage calculator - periodic payment
    api_response = api_instance.mortgage_calculator_periodic_payment(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->mortgage_calculator_periodic_payment: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::MortgageCalculatorPeriodicPayment.new
payload.home_price = 100000
payload.down_payment = 50000
payload.interest_rate = 0.04
payload.mortgage_term = 6

begin
  #Mortgage calculator - periodic payment
  result = api_instance.mortgage_calculator_periodic_payment(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->mortgage_calculator_periodic_payment: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
MortgageCalculatorHomePrice payload = new MortgageCalculatorHomePrice(homePrice=100000,
    downPayment=50000,
    interestRate=0.04,
    mortgageTerm=6);
try {
    MortgageCalculatorHomepriceResponse result = apiInstance.mortgageCalculatorHomePrice(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#mortgageCalculatorHomePrice");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.MortgageCalculatorPeriodicPayment(homePrice=100000,
     downPayment=50000,
     interestRate=0.04,
     mortgageTerm=6);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.mortgageCalculatorPeriodicPayment(payload, callback);

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,
    "total_payment": 50574.46,
    "total_principal": 50000,
    "total_interest": 574.46,
    "total_home_cost": 100574.46,
    "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.
total_payment The total mortgage payments made over mortgage_term.
total_principal The total amount that went toward the mortgage principal.
total_interest The total amount that went toward the mortgage interest.
total_home_cost The total cost of the home, including down payment and all mortgage payments. This value is greater than home_price when interest_rate is greater than 0.
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": 40000,
        "portfolio_return": 0.06,
        "retirement_age":75,
        "percent_of_expenses_covered": 0.25,
        "retirement_savings": 5000,
        "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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.DepositSchedule(deposit_frequency_interval="year",
  adjust_deposit_for_inflation=True)
payload = atom_api.RetirementCalculatorDepositAmount(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_schedule,
   inflation_rate=0.02,
   retirement_tax=0.25)

try:
    # Retirement calculator - deposit amount
    api_response = api_instance.retirement_calculator_deposit_amount(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->retirement_calculator_deposit_amount: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::RetirementCalculatorDepositAmount.new
payload.current_age = 70
payload.death_age = 78
payload.retirement_expenses = 70000
payload.portfolio_return = 0.06
payload.retirement_age = 75
payload.percent_of_expenses_covered = 0.25
payload.retirement_savings = 50000
payload.retirement_income = 5000

deposit_schedule = AtomApi::DepositSchedule.new
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Retirement calculator - deposit amount
  result = api_instance.retirement_calculator_deposit_amount(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->retirement_calculator_deposit_amount: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

DepositSchedule depositSchedule = new DepositSchedule(depositFrequencyInterval="year",
    adjustDepositForInflation=true);

RetirementCalculatorDepositAmount payload = new RetirementCalculatorDepositAmount(currentAge=70,
    deathAge=78,
    retirementExpenses=70000,
    portfolioReturn=0.06,
    retirementAge=75,
    percentOfExpensesCovered=0.25,
    retirementSavings=50000,
    retirementIncome=5000,
    depositSchedule=depositSchedule);
try {
    RetirementCalculatorDepositamountResponse result = apiInstance.retirementCalculatorDepositAmount(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#retirementCalculatorDepositAmount");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.DepositSchedule(depositFrequencyInterval="year",
  adjustDepositForInflation=true)

var payload = new atom_api.RetirementCalculatorDepositAmount(currentAge=70,
   deathAge=78,
   retirementExpenses=70000,
   portfolioReturn=0.06,
   retirementAge=75,
   percentOfExpensesCovered=0.25,
   retirementSavings=50000,
   retirementIncome=5000,
   depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.retirementCalculatorDepositAmount(payload, callback);

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": 2351.62,
    "deposit_frequency_interval": "year",
    "projected_savings_at_retirement": 20456.61,
    "total_earnings": 5738.8,
    "total_contributions": 12237.92,
    "total_withdrawals": 17232.54,
    "total_taxes": 5744.18,
    "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": 2351.62,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 300,
            "cumulative_contributions": 2351.62,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 7651.62
        },
        "2": {
            "period_earnings": 459.1,
            "period_contribution": 2398.65,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 759.1,
            "cumulative_contributions": 4750.27,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 10509.37
        },
        "3": {
            "period_earnings": 630.56,
            "period_contribution": 2446.62,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 1389.66,
            "cumulative_contributions": 7196.89,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 13586.55
        },
        "4": {
            "period_earnings": 815.19,
            "period_contribution": 2495.56,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 2204.85,
            "cumulative_contributions": 9692.45,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 16897.3
        },
        "5": {
            "period_earnings": 1013.84,
            "period_contribution": 2545.47,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 3218.69,
            "cumulative_contributions": 12237.92,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 20456.61
        },
        "6": {
            "period_earnings": 1227.4,
            "period_contribution": 0,
            "period_withdrawal": -5630.81,
            "period_taxes": -1876.94,
            "cumulative_earnings": 4446.09,
            "cumulative_contributions": 12237.92,
            "cumulative_withdrawals": -5630.81,
            "cumulative_taxes": -1876.94,
            "ending_balance": 14176.26
        },
        "7": {
            "period_earnings": 850.58,
            "period_contribution": 0,
            "period_withdrawal": -5743.43,
            "period_taxes": -1914.48,
            "cumulative_earnings": 5296.66,
            "cumulative_contributions": 12237.92,
            "cumulative_withdrawals": -11374.24,
            "cumulative_taxes": -3791.41,
            "ending_balance": 7368.93
        },
        "8": {
            "period_earnings": 442.14,
            "period_contribution": 0,
            "period_withdrawal": -5858.3,
            "period_taxes": -1952.77,
            "cumulative_earnings": 5738.8,
            "cumulative_contributions": 12237.92,
            "cumulative_withdrawals": -17232.54,
            "cumulative_taxes": -5744.18,
            "ending_balance": 0
        }
    }
}

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.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_withdrawals The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
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": 5000,
        "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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.DepositSchedule(deposit_amount=10000,
    deposit_frequency_interval="year",
    adjust_deposit_for_inflation=True)
payload = atom_api.RetirementCalculatorPercentCovered(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_schedule,
    inflation_rate=0.02,
    retirement_tax=0.25)

try:
    # Retirement calculator - percent of costs covered
    api_response = api_instance.retirement_calculator_percent_covered(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->retirement_calculator_percent_covered: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::RetirementCalculatorPercentCovered.new
payload.current_age = 50
payload.death_age = 57
payload.retirement_expenses = 40000
payload.portfolio_return = 0.06
payload.retirement_age = 55
payload.retirement_savings = 50000
payload.retirement_income = 5000

deposit_schedule = AtomApi::DepositSchedule.new
deposit_schedule.deposit_amount = 10000
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Retirement calculator - percent of costs covered
  result = api_instance.retirement_calculator_percent_covered(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->retirement_calculator_percent_covered: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

DepositSchedule depositSchedule = new DepositSchedule(depositAmount=10000,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true);

RetirementCalculatorPercentCovered payload = new RetirementCalculatorPercentCovered(currentAge=50,
    deathAge=57,
    retirementExpenses=40000,
    portfolioReturn=0.06,
    retirementAge=55,
    retirementSavings=50000,
    retirementIncome=5000,
    depositSchedule=depositSchedule);
try {
    RetirementCalculatorPctcoveredResponse result = apiInstance.retirementCalculatorPercentCovered(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#retirementCalculatorPercentCovered");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.DepositSchedule(depositAmount=10000,
     depositFrequencyInterval="year",
     adjustDepositForInflation=true)

var payload = new atom_api.RetirementCalculatorPercentCovered(currentAge=50,
    deathAge=57,
    retirementExpenses=40000,
    portfolioReturn=0.06,
    retirementAge=55,
    retirementSavings=50000,
    retirementIncome=5000,
    depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.retirementCalculatorPercentCovered(payload, callback);

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

{
    "achievable_expenses": 23465.95,
    "target_expenses": 35000,
    "percent_of_expenses_covered": 0.6705,
    "projected_savings_at_retirement": 65227.32,
    "total_earnings": 14134.9,
    "total_contributions": 52040.4,
    "total_withdrawals": 53381.48,
    "total_taxes": 17793.83,
    "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": 10000,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 300,
            "cumulative_contributions": 10000,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 15300
        },
        "2": {
            "period_earnings": 918,
            "period_contribution": 10200,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 1218,
            "cumulative_contributions": 20200,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 26418
        },
        "3": {
            "period_earnings": 1585.08,
            "period_contribution": 10404,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 2803.08,
            "cumulative_contributions": 30604,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 38407.08
        },
        "4": {
            "period_earnings": 2304.42,
            "period_contribution": 10612.08,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 5107.5,
            "cumulative_contributions": 41216.08,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 51323.58
        },
        "5": {
            "period_earnings": 3079.42,
            "period_contribution": 10824.32,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 8186.92,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 65227.32
        },
        "6": {
            "period_earnings": 3913.64,
            "period_contribution": 0,
            "period_withdrawal": -26426.47,
            "period_taxes": -8808.82,
            "cumulative_earnings": 12100.56,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": -26426.47,
            "cumulative_taxes": -8808.82,
            "ending_balance": 33905.66
        },
        "7": {
            "period_earnings": 2034.34,
            "period_contribution": 0,
            "period_withdrawal": -26955,
            "period_taxes": -8985,
            "cumulative_earnings": 14134.9,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": -53381.48,
            "cumulative_taxes": -17793.83,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
achievable_expenses The annual retirement expenses that can be covered, expressed in today’s dollars.
target_expenses The retirement_expenses input representing the target annual goal amount.
percent_of_expenses_covered The percentage of target_expenses that can be covered.
projected_savings_at_retirement The total amount of savings that are projected to be available at retirement, expressed in today’s dollars.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_withdrawals The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
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": 5000,
        "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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
deposit_schedule = atom_api.DepositSchedule(deposit_amount=10000,
    deposit_frequency_interval="year",
    adjust_deposit_for_inflation=True)
payload = atom_api.RetirementCalculatorExpenses(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_schedule,
    inflation_rate=0.02,
    retirement_tax=0.25)

try:
    # Retirement calculator - expenses
    api_response = api_instance.retirement_calculator_expenses(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->retirement_calculator_expenses: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::RetirementCalculatorExpenses.new
payload.current_age = 50
payload.death_age = 57
payload.portfolio_return = 0.06
payload.retirement_age = 55
payload.percent_of_expenses_covered = 0.25
payload.retirement_savings = 50000
payload.retirement_income = 5000

deposit_schedule = AtomApi::DepositSchedule.new
deposit_schedule.deposit_amount = 10000
deposit_schedule.deposit_frequency_interval = "year"
deposit_schedule.adjust_deposit_for_inflation = true
payload.deposit_schedule = deposit_schedule

begin
  #Retirement calculator - expenses
  result = api_instance.retirement_calculator_expenses(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->retirement_calculator_expenses: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

DepositSchedule depositSchedule = new DepositSchedule(depositAmount=10000,
    depositFrequencyInterval="year",
    adjustDepositForInflation=true);

RetirementCalculatorExpenses payload = new RetirementCalculatorExpenses(currentAge=50,
    deathAge=57,
    portfolioReturn=0.06,
    retirementAge=55,
    percentOfExpensesCovered=0.25,
    retirementSavings=50000,
    retirementIncome=5000,
    depositSchedule=depositSchedule);
try {
    RetirementCalculatorExpensesResponse result = apiInstance.retirementCalculatorExpenses(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#retirementCalculatorExpenses");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var depositSchedule = new atom_api.DepositSchedule(depositAmount=10000,
   depositFrequencyInterval="year",
   adjustDepositForInflation=true)

var payload = new atom_api.RetirementCalculatorExpenses(currentAge=50,
    deathAge=57,
    portfolioReturn=0.06,
    retirementAge=55,
    percentOfExpensesCovered=0.25,
    retirementSavings=50000,
    retirementIncome=5000,
    depositSchedule=depositSchedule);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.retirementCalculatorExpenses(payload, callback);

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": 111336.69,
    "projected_retirement_expenses_adjusted": 98863.8,
    "projected_savings_at_retirement": 65227.32,
    "total_earnings": 14134.9,
    "total_contributions": 52040.4,
    "total_withdrawals": 53381.48,
    "total_taxes": 17793.83,
    "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": 10000,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 300,
            "cumulative_contributions": 10000,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 15300
        },
        "2": {
            "period_earnings": 918,
            "period_contribution": 10200,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 1218,
            "cumulative_contributions": 20200,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 26418
        },
        "3": {
            "period_earnings": 1585.08,
            "period_contribution": 10404,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 2803.08,
            "cumulative_contributions": 30604,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 38407.08
        },
        "4": {
            "period_earnings": 2304.42,
            "period_contribution": 10612.08,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 5107.5,
            "cumulative_contributions": 41216.08,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 51323.58
        },
        "5": {
            "period_earnings": 3079.42,
            "period_contribution": 10824.32,
            "period_withdrawal": 0,
            "period_taxes": 0,
            "cumulative_earnings": 8186.92,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": 0,
            "cumulative_taxes": 0,
            "ending_balance": 65227.32
        },
        "6": {
            "period_earnings": 3913.64,
            "period_contribution": 0,
            "period_withdrawal": -26426.47,
            "period_taxes": -8808.82,
            "cumulative_earnings": 12100.56,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": -26426.47,
            "cumulative_taxes": -8808.82,
            "ending_balance": 33905.66
        },
        "7": {
            "period_earnings": 2034.34,
            "period_contribution": 0,
            "period_withdrawal": -26955,
            "period_taxes": -8985,
            "cumulative_earnings": 14134.9,
            "cumulative_contributions": 52040.4,
            "cumulative_withdrawals": -53381.48,
            "cumulative_taxes": -17793.83,
            "ending_balance": 0
        }
    }
}

RESPONSE

Field Description
projected_retirement_expenses The after-tax retirement expenses available.
projected_retirement_expenses_adjusted 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.
total_earnings The total earnings generated over the horizon.
total_contributions The total contributions added over the horizon.
total_withdrawals The total amount of withdrawals taken over decumulation_horizon.
total_taxes The total taxes paid on withdrawals over decumulation_horizon.
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

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
        ],
        "use_proxy_data": false
    }' "https://api.hydrogenplatform.com/proton/v1/diversification_score"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
payload = atom_api.DiversificationScore(portfolio_tickers=["XOM", "CMCSA", "AMZN", "GOOGL", "AGG"],
  portfolio_weights=[0.6, 0.1, 0.1, 0.1, 0.1])

try:
    # Portfolio diversification score
    api_response = api_instance.portfolio_diversification_score(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->portfolio_diversification_score: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::DiversificationScore.new
payload.portfolio_tickers = ["XOM", "CMCSA", "AMZN", "GOOGL", "AGG"]
payload.portfolio_weights = [0.6, 0.1, 0.1, 0.1, 0.1]

begin
  #Portfolio diversification score
  result = api_instance.portfolio_diversification_score(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->portfolio_diversification_score: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
DiversificationScore payload = new DiversificationScore(portfolioTickers=["XOM", "CMCSA", "AMZN", "GOOGL", "AGG"],
    portfolioWeights=[0.6, 0.1, 0.1, 0.1, 0.1]);
try {
    PfloDiversificationScoreResponse result = apiInstance.portfolioDiversificationScore(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#portfolioDiversificationScore");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.DiversificationScore(portfolioTickers=["XOM", "CMCSA", "AMZN", "GOOGL", "AGG"],
    portfolioWeights=[0.6, 0.1, 0.1, 0.1, 0.1]);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.portfolioDiversificationScore(payload, callback);

ARGUMENTS

Parameter Description
portfolio_tickers
array, required
Portfolio tickers, referencing securities defined in the Nucleus API.
portfolio_weights
array, required
Portfolio weights, corresponding to portfolio_tickers. Must sum to 1.0.
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.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.

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

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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
payload = atom_api.EmergencyFundCalculator(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")

try:
    # Emergency fund calculator
    api_response = api_instance.emergency_fund_calculator(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->emergency_fund_calculator: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::EmergencyFundCalculator.new
payload.emergency_fund_duration = 12
payload.housing_cost = 1650
payload.utility_payments = 60
payload.telecom_payments = 50
payload.insurance_payments = 0
payload.debt_payments = 0
payload.transportation_costs = 150
payload.food_costs = 1500
payload.other_expenses = {entertainment => 50, daycare => 150}
payload.current_emergency_fund_balance = 15000
payload.interest_rate = 0.015
payload.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]
payload.frequency_unit = "month"

begin
  #Emergency fund calculator
  result = api_instance.emergency_fund_calculator(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->emergency_fund_calculator: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
EmergencyFundCalculator payload = new EmergencyFundCalculator(emergencyFundDuration=12,
      housingCost=1650,
      utilityPayments=60,
      telecomPayments=50,
      insurancePayments=0,
      debtPayments=0,
      transportationCosts=150,
      foodCosts=1500,
      otherExpenses={"entertainment": 50, "daycare": 150},
      currentEmergencyFundBalance=15000,
      interestRate=0.015,
      savingsHorizon=[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24],
      frequencyUnit="month");
try {
    EmergencyFundResponse result = apiInstance.emergencyFundCalculator(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#emergencyFundCalculator");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var payload = new atom_api.EmergencyFundCalculator(emergencyFundDuration=12,
     housingCost=1650,
     utilityPayments=60,
     telecomPayments=50,
     insurancePayments=0,
     debtPayments=0,
     transportationCosts=150,
     foodCosts=1500,
     otherExpenses={"entertainment": 50, "daycare": 150},
     currentEmergencyFundBalance=15000,
     interestRate=0.015,
     savingsHorizon=[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24],
     frequencyUnit="month"});

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.emergencyFundCalculator(payload, callback);

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.

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"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
ratio_targets = atom_api.RatioTargets(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)
payload = atom_api.FinancialHealthCheck(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=ratio_targets)

try:
    # Financial health check
    api_response = api_instance.financial_health_check(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->financial_health_check: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::FinancialHealthCheck.new
payload.liquid_assets = 5000
payload.non_liquid_assets = 10000
payload.short_term_liabilities = 11000
payload.total_liabilities = 14000
payload.gross_annual_income = 60000
payload.net_monthly_income = 3500
payload.monthly_expenses = 3000

ratio_targets = AtomApi::RatioTargets
ratio_targets.liquidity_ratio_expenses = 2.5
ratio_targets.liquidity_ratio_liabilities = 0.1
ratio_targets.current_ratio = 0.5
ratio_targets.asset_allocation_ratio = 1.5
ratio_targets.savings_ratio_gross = 0.1
ratio_targets.savings_ratio_net = 0.1

payload.ratio_targets = ratio_targets

begin
  #Financial health check
  result = api_instance.financial_health_check(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->financial_health_check: #{e}"
end
ProtonApi apiInstance = new ProtonApi();
RatioTargets ratioTargets = new RatioTargets(liquidityRatioExpenses=2.5,
   liquidityRatioLiabilities=0.1,
   currentRatio=0.5,
   assetAllocationRatio=1.5,
   savingsRatioGross=0.1,
   savingsRatioNet=0.1);
FinancialHealthCheck payload = new FinancialHealthCheck(liquidAssets=5000,
    nonLiquidAssets=10000,
    shortTermLiabilities=11000,
    totalLiabilities=14000,
    grossAnnualIncome=60000,
    netMonthlyIncome=3500,
    monthlyExpenses=3000,
    ratioTargets=ratioTargets);
try {
    HealthCheckResponse result = apiInstance.financialHealthCheck(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#financialHealthCheck");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var ratioTargets = new atom_api.RatioTargets(liquidityRatioExpenses=2.5,
   liquidityRatioLiabilities=0.1,
   currentRatio=0.5,
   assetAllocationRatio=1.5,
   savingsRatioGross=0.1,
   savingsRatioNet=0.1)

var payload = new atom_api.FinancialHealthCheck(liquidAssets=5000,
    nonLiquidAssets=10000,
    shortTermLiabilities=11000,
    totalLiabilities=14000,
    grossAnnualIncome=60000,
    netMonthlyIncome=3500,
    monthlyExpenses=3000,
    ratioTargets=ratioTargets);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.financialHealthCheck(payload, callback);

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.

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", "AAPL", "CHTR", "PFE", "NVDA"],
        "portfolio_weights": [0.1, 0.1, 0.1, 0.6, 0.1],
        "opt_config": {
            "tickers": ["AGG", "AAPL", "CHTR", "PFE", "NVDA"],
            "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"
        },
        "use_proxy_data": false
    }' "https://api.hydrogenplatform.com/proton/v1/portfolio_optimization_score"
api_instance = atom_api.ProtonApi(atom_api.ApiClient(configuration))
w_config = atom_api.WConfigPortfolio(w_min_major=0.05,
   w_max_major=1.0,
   w_min_minor=0.05,
   w_max_minor=1.0,
   cash_amount=0.0)
opt_config = atom_api.OptConfig(tickers=["AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
    min_assets=5,
    w_asset_config={"US_Equities": 1.0,
      "Fixed_Income": 1.0},
    w_config=w_config,
    sec_types=["minor", "minor", "minor", "minor", "minor"],
    start_date="2016-01-01",
    end_date="2017-01-01")
payload = atom_api.OptimizationScore(portfolio_tickers=["AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
   portfolio_weights=[0.1, 0.1, 0.1, 0.6, 0.1],
   opt_config=opt_config)

try:
    # Portfolio optimization score
    api_response = api_instance.portfolio_optimization_score(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ProtonApi->portfolio_optimization_score: %s\n" % e)
api_instance = AtomApi::ProtonApi.new

payload = AtomApi::OptimizationScore.new
payload.portfolio_tickers = ["AGG", "AMZN", "CMCSA", "XOM", "GOOGL"]
payload.portfolio_weights = [0.1, 0.1, 0.1, 0.6, 0.1]

opt_config = AtomApi::OptConfig
opt_config.tickers = ["AGG", "AMZN", "CMCSA", "XOM", "GOOGL"]
opt_config.min_assets = 5
opt_config.w_asset_config = {US_Equities => 1.0, Fixed_Income => 1.0}

w_config = AtomApi::WConfigPortfolio
w_config.w_min_major = 0.05
w_config.w_max_major = 1.0
w_config.w_min_minor = 0.05
w_config.w_max_minor = 1.0
w_config.cash_amount = 0.0
opt_config.w_config = w_config
opt_config.sec_types = ["minor", "minor", "minor", "minor", "minor"]
opt_config.start_date = "2016-01-01"
opt_config.end_date = "2017-01-01"
payload.opt_config = opt_config

begin
  #Portfolio optimization score
  result = api_instance.portfolio_optimization_score(payload)
  p result
rescue AtomApi::ApiError => e
  puts "Exception when calling ProtonApi->portfolio_optimization_score: #{e}"
end
ProtonApi apiInstance = new ProtonApi();

WConfigPortfolio wConfig = new WConfigPortfolio(wMinMajor=0.05,
    wMaxMajor=1.0,
    wMinMinor=0.05,
    wMaxMinor=1.0,
    cashAmount=0.0);

OptConfig optConfig = new OptConfig(tickers=["AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
    minAssets=5,
    wAssetConfig={"US_Equities": 1.0, "Fixed_Income": 1.0},
    wConfig=wConfig,
    secTypes=["minor", "minor", "minor", "minor", "minor"],
    startDate="2016-01-01",
    endDate="2017-01-01");
OptimizationScore payload = new OptimizationScore(portfolioTickers=["AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
    portfolioWeights=[0.1, 0.1, 0.1, 0.6, 0.1],
    optConfig=optConfig);
try {
    PfloOptimizationScoreResponse result = apiInstance.portfolioOptimizationScore(payload);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ProtonApi#portfolioOptimizationScore");
    e.printStackTrace();
}
var apiInstance = new atom_api.ProtonApi();

var wConfig = new atom_api.WConfigPortfolio(w_min_major=0.05,
    w_max_major=1.0,
    w_min_minor=0.05,
    w_max_minor=1.0,
    cash_amount=0.0)

var optConfig = new atom_api.OptConfig(tickers=["AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
     minAssets=5,
     wAssetConfig={"US_Equities": 1.0, "Fixed_Income": 1.0},
     wConfig=wConfig,
     secTypes=["minor", "minor", "minor", "minor", "minor"],
     startDate="2016-01-01",
     endDate="2017-01-01")

var payload = new atom_api.OptimizationScore(portfolioTickers=["AGG", "AMZN", "CMCSA", "XOM", "GOOGL"],
     portfolioWeights=[0.1, 0.1, 0.1, 0.6, 0.1],
     optConfig=optConfig);

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.portfolioOptimizationScore(payload, callback);

ARGUMENTS

Parameter Description
portfolio_tickers
array, required
Portfolio tickers, referencing securities defined in the Nucleus API.
portfolio_weights
array, required
Portfolio weights, corresponding to portfolio_tickers. Must sum to 1.0.
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_major
            float
Minimum weight for “major” securities. Defaults to 0.05.
            w_max_major
            float
Maximum weight for “major” securities. Defaults to 1.
            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.
            cash_amount
            float
Constant weight for “cash” securities. Defaults to 0.
      sec_types
      array
Security types, corresponding to tickers. May be major, minor, or cash. Defaults to minor for all tickers.
      start_date
      date
Start date used for ticker price history. Defaults to earliest common date among tickers prices.
      end_date
      date
End date used for ticker price history. Defaults to latest common date among tickers prices.
use_proxy_data
boolean
If true, incorporate proxy price data as defined at the Security level in the Nucleus API. Proxy data is merged with base security data to form a continuous price history. Defaults to false.

Example Response

{
    "current_portfolio": {
        "tickers": [
            "AGG",
            "AAPL",
            "CHTR",
            "PFE",
            "NVDA"
        ],
        "weights": [
            0.1,
            0.1,
            0.1,
            0.1,
            0.6
        ],
        "return": 1.3377,
        "risk": 0.3009
    },
    "optimized_portfolio": {
        "tickers": [
            "AAPL",
            "PFE",
            "CHTR",
            "AGG",
            "NVDA"
        ],
        "weights": [
            0.05,
            0.05,
            0.1634,
            0.1389,
            0.5976
        ],
        "return": 1.705,
        "risk": 0.3009
    },
    "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

Personal Financial Management

Budget Calculator

The Budget Calculator analyzes a client’s spending patterns against pre-defined budgets over time. This is useful to gain a deeper understanding of how closely a client follows a particular budget. A breakdown of each underlying budget item also provides helpful data to aid clients in staying on track and achieving their budgetary goals.

HTTP REQUEST

POST /budget_calculator

Example Request

curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
  -H "Content-Type: application/json" \
  -d '{
          "budget_id": "790c936b-015d-4d8a-82ed-434a4bbc13e8",
          "as_of_date": "2016-12-22",
          "lookback_periods": 3,
          "relative_lookback": true
      }' "https://api.hydrogenplatform.com/proton/v1/budget_calculator"

ARGUMENTS

Parameter Description
budget_id
UUID, required
The ID of a Nucleus budget.
as_of_date
date
Reference date of the analysis. Calculations will run through the earlier of this date and budget.end_date as defined in Nucleus. Defaults to today’s date.
lookback_periods
integer
Number of lookback periods to analyze. Each period length is defined by the combination of budget.frequency and budget.frequency_unit as defined in Nucleus. Defaults to 1.
relative_lookback
integer
An indicator for how to determine the first lookback period, with regard to as_of_date. For example, when as_of_date is 2016-12-22 and the budget has a frequency and frequency_unit of 1 and month, respectively: If relative_lookback is false, 1 month means an entire month in absolute terms (i.e. 2016-11-23 to 2016-12-22). If relative_lookback is true, 1 month means the pertinent calendar month (i.e. 2016-12-01 to 2016-12-22). Defaults to true.

Example Response

{
    "currency_code": "USD",
    "budget_track": [
        {
            "period_start": "2016-10-01",
            "period_end": "2016-10-31",
            "total_funds_budgeted": 100.0,
            "total_funds_spent": 56.51,
            "total_funds_remaining": 43.49,
            "budget_components": [
                {
                    "category": "Food & Dining",
                    "subcategory": "Alcohol & Bars",
                    "funds_budgeted": 50.0,
                    "funds_spent": 0,
                    "funds_remaining": 50.0
                },
                {
                    "category": "Health & Fitness",
                    "subcategory": "Sports",
                    "funds_budgeted": 50.0,
                    "funds_spent": 56.51,
                    "funds_remaining": -6.51
                }
            ]
        },
        {
            "period_start": "2016-11-01",
            "period_end": "2016-11-30",
            "total_funds_budgeted": 100.0,
            "total_funds_spent": 0,
            "total_funds_remaining": 100.0,
            "budget_components": [
                {
                    "category": "Food & Dining",
                    "subcategory": "Alcohol & Bars",
                    "funds_budgeted": 50.0,
                    "funds_spent": 0,
                    "funds_remaining": 50.0
                },
                {
                    "category": "Health & Fitness",
                    "subcategory": "Sports",
                    "funds_budgeted": 50.0,
                    "funds_spent": 0,
                    "funds_remaining": 50.0
                }
            ]
        },
        {
            "period_start": "2016-12-01",
            "period_end": "2016-12-22",
            "total_funds_budgeted": 100.0,
            "total_funds_spent": 284.77,
            "total_funds_remaining": -184.77,
            "budget_components": [
                {
                    "category": "Food & Dining",
                    "subcategory": "Alcohol & Bars",
                    "funds_budgeted": 50.0,
                    "funds_spent": 284.77,
                    "funds_remaining": -234.77
                },
                {
                    "category": "Health & Fitness",
                    "subcategory": "Sports",
                    "funds_budgeted": 50.0,
                    "funds_spent": 0,
                    "funds_remaining": 50.0
                }
            ]
        }
    ]
}

RESPONSE

Field Description
currency_code Currency code associated with monetary response values.
budget_track Analysis of spending versus budget for each budget period
      period_start Start date of the budget period.
      period_end End date of the budget period.
      total_funds_budgeted Total amount of funds originally budgeted.
      total_funds_spent Total amount of funds spent.
      total_funds_remaining Total amount of funds remaining, i.e. the delta between total_funds_budgeted and total_funds_spent.
      budget_components Details for each item defined under the budget.
            category
      
The budget component’s spending category.
            subcategory
      
The budget component’s spending subcategory.
            funds_budgeted
      
Amount of funds originally budgeted.
            funds_spent
      
Amount of funds spent.
            funds_remaining
      
Amount of funds remaining, i.e. the delta between funds_budgeted and funds_spent.

NUCLEUS DATA DEPENDENCIES

          1. Client: POST /client
          2. Aggregation Account: POST /aggregation_account
          3. Aggregation Account Transaction: POST /aggregation_account_transaction
          4. Budget: POST /budget

Cash Flow Analysis

The cash flow analysis provides a benchmarked view of a client’s cash flows over time, including income, spending, and net cash flow values. This tool is useful for charting cash flows trends over time, as well as for displaying helpful details about a client’s spending habits. Tracking these cash flow values against a benchmark time period allows for insight into how the client’s cash flow situation is changing relative to previous behavior.

HTTP REQUEST

Example Request

POST /cash_flow_analysis

curl -X POST -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "a32a48f7-d30e-489b-9d2b-576a3939343f",
        "start_date": "2015-06-15",
        "end_date": "2015-06-17",
        "show_history": true,
        "show_spending_details": true,
        "currency_code": "USD"
      }' "https://api.hydrogenplatform.com/proton/v1/cash_flow_analysis"

ARGUMENTS

Parameter Description
client_id
UUID, required
The ID of a Nucleus client.
start_date
date
Start date of the analysis period. Defaults to the earliest available aggregation account transaction date.
end_date
date
End date of the analysis period. Defaults to the latest available aggregation account transaction date.
benchmark_start_date
date
Start date of the benchmark analysis period. Default values for benchmark_start_date and benchmark_end_date are based on the difference between start_date and end_date. For example, if start_date and end_date are 2016-06-15 and 2016-06-17, respectively, benchmark_start_date and benchmark_end_date default to 2016-06-12 and 2016-06-14, respectively.
benchmark_end_date
date
End date of the benchmark analysis period. Default values for benchmark_start_date and benchmark_end_date are based on the difference between start_date and end_date. For example, if start_date and end_date are 2016-06-15 and 2016-06-17, respectively, benchmark_start_date and benchmark_end_date default to 2016-06-12 and 2016-06-14, respectively.
show_history
boolean
If true, return a daily history of the client’s cash flow details within the specified date range. Defaults to false.
show_spending_details
boolean
If true, return advanced spending details including breakdowns by category and by merchant as well as any outlying expenditures. Outlier analysis is performed on a median absolute deviation (MAD) basis, at the 2.5 threshold. Defaults to false.
currency_code
string
The alphabetic currency code used to conduct the cash flow analysis, limited to 3 characters. Only aggregation account records with this currency code will be considered. Defaults to USD. See Currencies.

Example Response

{
    "currency_code": "USD",
    "income_summary": {
        "total": 0.0,
        "benchmark_total": 0.0,
        "change": {
            "value": 0.0,
            "percentage": null
        }
    },
    "spending_summary": {
        "total": 266.35,
        "benchmark_total": 460.96,
        "change": {
            "value": -194.61,
            "percentage": -0.4222
        }
    },
    "net_summary": {
        "total": -266.35,
        "benchmark_total": -460.96,
        "change": {
            "value": 194.61,
            "percentage": -0.4222
        }
    },
    "history": [
        {
            "date": "2015-06-15",
            "period_income": 0.0,
            "period_spending": 0.0,
            "period_net": 0.0,
            "cumulative_income": 0.0,
            "cumulative_spending": 0.0,
            "cumulative_net": 0.0
        },
        {
            "date": "2015-06-16",
            "period_income": 0.0,
            "period_spending": 0.0,
            "period_net": 0.0,
            "cumulative_income": 0.0,
            "cumulative_spending": 0.0,
            "cumulative_net": 0.0
        },
        {
            "date": "2015-06-17",
            "period_income": 0.0,
            "period_spending": 266.35,
            "period_net": -266.35,
            "cumulative_income": 0.0,
            "cumulative_spending": 266.35,
            "cumulative_net": -266.35
        }
    ],
    "benchmark_history": [
        {
            "date": "2015-06-12",
            "period_income": 0.0,
            "period_spending": 0.0,
            "period_net": 0.0,
            "cumulative_income": 0.0,
            "cumulative_spending": 0.0,
            "cumulative_net": 0.0
        },
        {
            "date": "2015-06-13",
            "period_income": 0.0,
            "period_spending": 270.96,
            "period_net": -270.96,
            "cumulative_income": 0.0,
            "cumulative_spending": 270.96,
            "cumulative_net": -270.96
        },
        {
            "date": "2015-06-14",
            "period_income": 0.0,
            "period_spending": 190.0,
            "period_net": -190.0,
            "cumulative_income": 0.0,
            "cumulative_spending": 460.96,
            "cumulative_net": -460.96
        }
    ],
    "spending_details": {
        "by_category": [
            {
                "category": "Food & Dining",
                "value": 266.35,
                "benchmark_value": 0.0,
                "change": {
                    "value": 266.35,
                    "percentage": null
                },
                "weight": 1.0,
                "benchmark_weight": 0.0,
                "subcategories": [
                    {
                        "subcategory": "Restaurants",
                        "value": 266.35,
                        "benchmark_value": 0.0,
                        "change": {
                            "value": 266.35,
                            "percentage": null
                        },
                        "weight": 1.0,
                        "benchmark_weight": 0.0
                    }
                ]
            },
            {
                "category": "Business Services",
                "value": 0.0,
                "benchmark_value": 270.96,
                "change": {
                    "value": -270.96,
                    "percentage": -1.0
                },
                "weight": 0.0,
                "benchmark_weight": 0.5878,
                "subcategories": [
                    {
                        "subcategory": "Legal",
                        "value": 0.0,
                        "benchmark_value": 270.96,
                        "change": {
                            "value": -270.96,
                            "percentage": -1.0
                        },
                        "weight": 0.0,
                        "benchmark_weight": 1.0
                    }
                ]
            },
            {
                "category": "Health & Fitness",
                "value": 0.0,
                "benchmark_value": 190.0,
                "change": {
                    "value": -190.0,
                    "percentage": -1.0
                },
                "weight": 0.0,
                "benchmark_weight": 0.4122,
                "subcategories": [
                    {
                        "subcategory": "Health Insurance",
                        "value": 0.0,
                        "benchmark_value": 190.0,
                        "change": {
                            "value": -190.0,
                            "percentage": -1.0
                        },
                        "weight": 0.0,
                        "benchmark_weight": 1.0
                    }
                ]
            }
        ],
        "by_merchant": [
            {
                "merchant": "Isdom",
                "value": 266.35,
                "benchmark_value": 0.0,
                "change": {
                    "value": 266.35,
                    "percentage": null
                },
                "weight": 1.0,
                "benchmark_weight": 0.0
            },
            {
                "merchant": "Blackzim",
                "value": 0.0,
                "benchmark_value": 270.96,
                "change": {
                    "value": -270.96,
                    "percentage": -1.0
                },
                "weight": 0.0,
                "benchmark_weight": 0.5878
            },
            {
                "merchant": "Geojaycare",
                "value": 0.0,
                "benchmark_value": 190.0,
                "change": {
                    "value": -190.0,
                    "percentage": -1.0
                },
                "weight": 0.0,
                "benchmark_weight": 0.4122
            }
        ],
        "outliers": []
    }
}

RESPONSE

Field Description
currency_code Currency code associated with monetary response values.
income_summary List of the total income values and the calculated delta between overall and benchmark.
      total Total cash inflows over the trend period.
      benchmark_total Total cash inflows over the benchmark trend period.
      change Difference in total cash inflows between the trend period and the benchmark trend period.
            value Value change as of the analysis end date.
            percentage Percentage change as of the analysis end date.
spending_summary List of the total spending values and the calculated delta between overall and benchmark.
      total Total cash outflows over the trend period.
      benchmark_total Total cash outflows over the benchmark trend period.
      change Difference in total cash outflows between the trend period and the benchmark trend period.
            value Value change as of the analysis end date.
            percentage Percentage change as of the analysis end date.
net_summary List of the total net values and the calculated delta between overall and benchmark.
      total Total net cash flows over the trend period.
      benchmark_total Total net cash flows over the benchmark trend period.
      change Difference in total net cash flows between the trend period and the benchmark trend period.
            value Value change as of the analysis end date.
            percentage Percentage change as of the analysis end date.
history List of income, spending and net values calculated by day.
      date Date of the spending history record.
      period_income Cash inflows during the period.
      period_spending Cash outflows during the period.
      period_net Net cash inflows (outflows) during the period.
      cumulative_income Cumulative cash inflows up to and including this period.
      cumulative_spending Cumulative cash outflows up to and including this period.
      cumulative_net Cumulative net cash inflows (outflows) up to and including this period.
benchmark_history List of benchmark income, spending and net values calculated by day.
      date Date of benchmark spending history record.
      period_income Cash inflows during the period.
      period_spending Cash outflows during the period.
      period_net Net cash inflows (outflows) during the period.
      cumulative_income Cumulative cash inflows up to and including this period.
      cumulative_spending Cumulative cash outflows up to and including this period.
      cumulative_net Cumulative net cash inflows (outflows) up to and including this period.
spending_details List of spending information separated by categories and merchants.
      by_category List of spending information separated by categories and their relative subcategories.
            category Spending category as defined in the Nucleus transactions.
            value Sum of all transactions over the period for the given category.
            benchmark_value Sum of all transactions over the benchmark period for the given category.
            change Difference in total net cash outflows per category between the trend period and the benchmark trend period.
                  value Value change as of the analysis end date.
                  percentage Percentage change as of the analysis end date.
            weight The proportion of all spending over the period related to this category.
            benchmark_weight The proportion of all spending over the benchmark period related to this category.
            subcategories List of spending subcategory as defined in the Nucleus transactions.
                  subcategory Spending category as defined in the Nucleus transactions.
                  value Sum of all transactions over the period for the given subcategory.
                  benchmark_value Sum of all transactions over the benchmark period for the given subcategory.
                  change Difference in total net cash outflows per subcategory between the trend period and the benchmark trend period.
                        value Value change as of the analysis end date.
                        percentage Percentage change as of the analysis end date.
                  weight The proportion of all spending over the period related to this subcategory.
                  benchmark_weight The proportion of all spending over the benchmark period related to this subcategory.
      by_merchant List of spending information separated by merchant.
            merchant Merchant name as defined in the Nucleus transactions.
            value Sum of all transactions over the period for the given merchant.
            benchmark_value Sum of all transactions over the benchmark period for the given merchant.
            change Difference in total net cash outflows per merchant between the trend period and the benchmark trend period.
                        value Value change as of the analysis end date.
                        percentage Percentage change as of the analysis end date.
            weight The proportion of all spending over the period related to this merchant.
            benchmark_weight The proportion of all spending over the benchmark period related to this merchant.
outliers List of transactions whose amount is beyond 2.5 median absolute deviations from the median of all transaction amounts.
      id The id for the aggregation account transaction record.
      tranaction_date The date the transaction took place.
      transaction_type Type of the transaction. Value may be a Debit or Credit.
      amount Amount of the transaction.
      merchant The merchant for the transaction such as the merchant posted for a credit card charge.
      category Category of the transaction.
      subcategory Subcategory of the transaction
      descrition Description of the transaction.
      memo Memo attached to the transaction.

NUCLEUS DATA DEPENDENCIES

          1. Client: POST /client
          2. Aggregation Account: POST /aggregation_account
          3. Aggregation Account Transaction : POST /aggregation_account_transaction

Financial Picture

The Financial Picture tool considers all of a client’s aggregation account information in order to provide a complete overview of the client’s financial situation in a specified currency and over a specified date range. For all requests, the snapshot response provides the client’s total assets, total liabilities, and net worth, along with a categorical breakdown of where the client’s wealth is positioned. The optional history and change responses provide a more detailed insight into how the client’s financial picture has changed over time.

HTTP REQUEST

POST /financial_picture

Example Request

curl -X POST -H "Authorization: Bearer 489f317e-6e3b-4902-b6bc-f875e2795ce6" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "1c92f054-e4a6-4e45-b29b-567587f34c27",
        "currency_code": "USD",
        "start_date": "2016-05-01",
        "end_date": "2016-05-02",
        "show_change": true,
        "show_history": true
      }' "https://api.hydrogenplatform.com/proton/v1/financial_picture"

ARGUMENTS

Parameter Description
client_id
UUID, required
The ID of a Nucleus client.
currency_code
string
The alphabetic currency code used to conduct the financial picture analysis, limited to 3 characters. Only aggregation account records with this currency code will be considered. Defaults to USD. See Currencies.
start_date
date
Start date of the financial picture analysis. Defaults to earliest date there is data.
end_date
date
End date of the financial picture analysis. Defaults to latest date there is data.
show_change
boolean
If true, return cumulative changes in the client’s total assets, total liabilities, and net worth over time within the specified date range. Defaults to false.
show_history
boolean
If true, return a daily history of the client’s financial picture within the specified date range. Defaults to false.

Example Response

{
    "currency_code": "USD",
    "snapshot": {
        "total_assets": {
            "balance": 239324.10499999998,
            "latest_balance_time_stamp": "2016-05-02T00:00:00.000+0000"
        },
        "total_liabilities": {
            "balance": 54180.8,
            "latest_balance_time_stamp": "2016-05-02T00:00:00.000+0000"
        },
        "net_worth": {
            "balance": 185143.305,
            "latest_balance_time_stamp": "2016-05-02T00:00:00.000+0000"
        },
        "by_category": [
            {
                "category": "Loan",
                "balance": 54180.8,
                "latest_balance_time_stamp": "2016-05-02T00:00:00.000+0000",
                "subcategories": [
                    {
                        "subcategory": "Mortgage",
                        "balance": 54180.8,
                        "latest_balance_time_stamp": "2016-05-02T00:00:00.000+0000"
                    }
                ]
            },
            {
                "category": "Property",
                "balance": 85435.855,
                "latest_balance_time_stamp": "2016-05-02T00:00:00.000+0000",
                "subcategories": [
                    {
                        "subcategory": "Residential",
                        "balance": 85435.855,
                        "latest_balance_time_stamp": "2016-05-02T00:00:00.000+0000"
                    }
                ]
            },
            {
                "category": "Banking",
                "balance": 153888.25,
                "latest_balance_time_stamp": "2016-05-02T00:00:00.000+0000",
                "subcategories": [
                    {
                        "subcategory": "Savings",
                        "balance": 72884.75,
                        "latest_balance_time_stamp": "2016-05-02T00:00:00.000+0000"
                    },
                    {
                        "subcategory": "Checking",
                        "balance": 81003.5,
                        "latest_balance_time_stamp": "2016-05-02T00:00:00.000+0000"
                    }
                ]
            }
        ]
    },
    "change": {
        "analysis_start": "2016-05-01",
        "analysis_end": "2016-05-02",
        "total_assets": {
            "1_day": {
                "value": 0,
                "percentage": 0
            },
            "total": {
                "value": 0,
                "percentage": 0
            }
        },
        "total_liabilities": {
            "1_day": {
                "value": 0,
                "percentage": 0
            },
            "total": {
                "value": 0,
                "percentage": 0
            }
        },
        "net_worth": {
            "1_day": {
                "value": 0,
                "percentage": 0
            },
            "total": {
                "value": 0,
                "percentage": 0
            }
        }
    },
    "history": [
        {
            "date": "2016-05-01",
            "total_assets": 239324.1,
            "total_liabilities": 54180.8,
            "net_worth": 185143.3,
            "by_category": [
                {
                    "category": "Loan",
                    "balance": 54180.8,
                    "subcategories": [
                        {
                            "subcategory": "Mortgage",
                            "balance": 54180.8
                        }
                    ]
                },
                {
                    "category": "Property",
                    "balance": 85435.86,
                    "subcategories": [
                        {
                            "subcategory": "Residential",
                            "balance": 85435.86
                        }
                    ]
                },
                {
                    "category": "Banking",
                    "balance": 153888.25,
                    "subcategories": [
                        {
                            "subcategory": "Savings",
                            "balance": 72884.75
                        },
                        {
                            "subcategory": "Checking",
                            "balance": 81003.5
                        }
                    ]
                }
            ]
        },
        {
            "date": "2016-05-02",
            "total_assets": 239324.1,
            "total_liabilities": 54180.8,
            "net_worth": 185143.3,
            "by_category": [
                {
                    "category": "Loan",
                    "balance": 54180.8,
                    "subcategories": [
                        {
                            "subcategory": "Mortgage",
                            "balance": 54180.8
                        }
                    ]
                },
                {
                    "category": "Property",
                    "balance": 85435.86,
                    "subcategories": [
                        {
                            "subcategory": "Residential",
                            "balance": 85435.86
                        }
                    ]
                },
                {
                    "category": "Banking",
                    "balance": 153888.25,
                    "subcategories": [
                        {
                            "subcategory": "Savings",
                            "balance": 72884.75
                        },
                        {
                            "subcategory": "Checking",
                            "balance": 81003.5
                        }
                    ]
                }
            ]
        }
    ]
}

RESPONSE

Field Description
currency_code Currency code associated with monetary response values.
snapshot A snapshot of the client’s financial picture as of the most recent available date within the date range.
      total_assets
      
Total assets of the client.
            balance
      
Value of the total assets.
            latest_balance_time_stamp
      
Date and time of the total assets record.
      total_liabilities
      
Total liabilities of the client.
            balance
      
Value of the total liabilities.
            latest_balance_time_stamp
      
Date and time of the total liabilities record.
      net_worth
      
Net worth of the client.
            balance
      
Value of the net worth.
            latest_balance_time_stamp
      
Date and time of the net worth record.
      by_category
      
List of all aggregation accounts and balances by category and subcategory.
            category
      
Category of the aggregation accounts. These accounts are dependent on the category field within the Nucleus Aggregation Account.
            balance
      
Total balance for this category.
            latest_balance_time_stamp
      
Date and time of the balance record for this category.
            subcategories
      
List of subcategories within the category and their respective balances.
                  subcategory
      
Subcategory of the aggregation accounts. These accounts are dependent on the subcategory fields within the Nucleus Aggregation Account.
                  balance
      
Total balance for this subcategory.
                  latest_balance_time_stamp
      
Date and time of the balance record for this subcategory.
change Change records of the client.
      analysis_start
      
Start date of available data used in the change analysis.
      analysis_end
      
End date of available data used in the change analysis.
      {total_assets,total_liabilities,net_worth}
      
A map of the below change records will be provided for each of the following: total_assets, total_liabilities, and net_worth.
            1-day
      
1-day change record as of the analysis end date.
                  value
      
1-day value change as of the analysis end date.
                  percentage
      
1-day percentage change as of the analysis end date.
            7-day
      
7-day change record as of the analysis end date.
                  value
      
7-day value change as of the analysis end date.
                  percentage
      
7-day percentage change as of the analysis end date.
            30-day
      
30-day change record as of the analysis end date.
                  value
      
30-day value change as of the analysis end date.
                  percentage
      
30-day percentage change as of the analysis end date.
            60-day
      
60-day change record as of the analysis end date.
                  value
      
60-day value change as of the analysis end date.
                  percentage
      
60-day percentage change as of the analysis end date.
            90-day
      
90-day change record as of the analysis end date.
                  value
      
90-day value change as of the analysis end date.
                  percentage
      
90-day percentage change as of the analysis end date.
            180-day
      
180-day change record as of the analysis end date.
                  value
      
180-day value change as of the analysis end date.
                  percentage
      
180-day percentage change as of the analysis end date.
            365-day
      
365-day change record as of the analysis end date.
                  value
      
365-day value change as of the analysis end date.
                  percentage
      
365-day percentage change as of the analysis end date.
            total
      
Change record over the entire analysis date range.
                  value
      
Total value change over the entire analysis date range.
                  percentage
      
Total percentage change over the entire analysis date range.
history A historical record of the client’s financials for each date within the date range. This is an array of maps, with each map corresponding to a date and containing the following fields:
      date
      
The date of the financial picture record.
      total_assets
      
Total assets of the client on this date.
      total_liabilities
      
Total liabilities of the client on this date.
      net_worth
      
Net worth of the client on this date.
      by_category
      
List of all aggregation accounts and balances on this date by category and subcategory.
            category
      
Category of the aggregation accounts. These accounts are dependent on the category field within the Nucleus Aggregation Account.
            balance
      
Total balance for this category on this date.
            subcategories
      
List of subcategories within the category and their respective balances on this date.
                  subcategory
      
Subcategory of the aggregation accounts. These accounts are dependent on the subcategory fields within the Nucleus Aggregation Account.
                  balance
      
Total balance for this subcategory on this date.

NUCLEUS DATA DEPENDENCIES

          1. Client: POST /client
          2. Aggregation Account: POST /aggregation_account
          3. Aggregation Account Balance: POST /aggregation_account_balance

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