Atom Quickstart Guide

Follow the guide below to learn the Hydrogen Atom APIs and build your first application



Atom Overview


Introduction

Hydrogen Atom is a suite of APIs that allow developers to build investing, savings, wellness, and insurance applications with ease. All Hydrogen APIs are built on REST principles, with resource oriented URLs and HTTP response codes. All API responses are returned in JSON format. Additional features of the API include filtering, pagination, and data caching. A free sandbox may be utilized by developers to build a test application before going into production.

The following APIs are all part of the Atom product:

Nucleus

Nucleus provides the core digital infrastructure you will need to build your financial application. This includes the base functionality to onboard clients and accounts, and store and process data which all other APIs in the Atom will utilize. View the online documentation here.

Sandbox Base URL: https://sandbox.hydrogenplatform.com/nucleus/v1
Production Base URL: https://api.hydrogenplatform.com/nucleus/v1

Proton

Proton provides financial engineering functionality on top of the core Nucleus data within the Atom platform. Proton offers analytical tools, scoring, calculators, recommendations, and simulations. There is no data storage in Proton. View the online documentation here.

Sandbox Base URL: https://sandbox.hydrogenplatform.com/proton/v1
Production Base URL: https://api.hydrogenplatform.com/proton/v1

Electron

Electron is designed to compliment the core Nucleus API within the Hydrogen Atom platform. Electron provides additional functionality to help you manage and grow your business such as frameworks for marketing, support, and document management. View the online documentation here.

Sandbox Base URL: https://sandbox.hydrogenplatform.com/electron/v1
Production Base URL: https://api.hydrogenplatform.com/electron/v1


Key Entities

Client

A client is a unique user on the platform. It may be identified based on a unique identifier, such as a government issued ID (e.g. social security number in US). A client can have multiple accounts, models, allocations and goals.

Account

An account represents a legal account owned by a client at a financial institution such as a savings or investment 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.

Aggregation Account

An aggregation account is a held away account outside of your firm, including banking, credit card, loan, or mortgage.

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.

Decision Tree

Decision trees are designed to guide your users in determining the best course of action for them based on their objectives. For example, a decision tree can be used to determine the most suitable allocation for a client’s investment portfolio according to a goal, time horizon, risk profile etc.

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.

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.

Goal

A desired financial outcome in the future, defined by time and monetary value. Examples include Retirement, Education, Major Purchase, Build Wealth.

Order

Instructions to purchase or sell investment securities through an execution platform.

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.

Holdings

A list of financial instruments contained in an investment account such as stocks, bonds, mutual funds, or ETFs.

Transactions

A list of transactions in a financial account including investment instrument buys/sells, credit card purchases, bank transfers, and mortgage payments.


Authentication

The first step is to properly authenticate your application. Hydrogen uses OAuth 2.0 to facilitate authorization on the API, an industry standard framework for authorization. There are two grant types supported by Hydrogen:

  • Client Credentials: The Client Credentials grant is used by your application to obtain permission to act on its own behalf. A call will be made to our OAuth server to exchange your client_id, client_secret, and grant_type=client_credentials for an access_token, which can then be used to make calls to Hydrogen on behalf of the application.
  • Password: The Password grant is used by your application to authenticate an end user with their login credentials. This grant should be used if you are storing the login credentials within the Hydrogen A call will be made to our OAuth server to exchange your client_id, client_secret, and grant_type=password along with the user’s username and password login credentials for an access_token, which can then be used to make calls to Hydrogen on behalf of the application.

Before authenticating, you must receive your API credentials. To do so, please follow these steps:

  1. Sign up as a developer
  2. Request access to the Atom API on the dashboard
  3. If your request is approved you will receive a welcome email
  4. Log in and sign our sandbox agreement which will generate your client_id and client_secret used for OAuth 2.0 authorization

For both grant types, you must Base 64 encode your API credentials in the format client_id:client_secret and pass them into the authorization header using HTTP Basic authentication.

Example Request

Client Credentials Grant

curl -X POST https://sandbox.hydrogenplatform.com/authorization/v1/oauth/token?grant_type=client_credentials \
          -H "Authorization: Basic aHlkcm9nZW5faWQ6aHlkcm9nZW5fc2VjcmV0"

Password Grant

If you will be storing username and password login credentials for clients in Hydrogen, please refer to the client signup section below.

curl -X POST https://sandbox.hydrogenplatform.com/authorization/v1/oauth/token?grant_type=password&username=<username>&password=<password> \
          -H "Authorization: Basic aHlkcm9nZW5faWQ6aHlkcm9nZW5fc2VjcmV0

In the response for both grant types, you will receive an access_token which you must use in any future request by passing into the authorization header as a Bearer token.

Example Request

url -X GET https://sandbox.hydrogenplatform.com/nucleus/v1/account \
          -H "Authorization: Bearer <access_token>"



Onboarding


Client Signup

Let’s sign up our first user and create a Client in Nucleus with their personal information. These details would be collected in a signup form such as a site signup or account application.

Let’s assume we have collected the following information from the user as part of a signup process:

  • First Name
  • Last Name
  • Email
  • Phone Number
  • Address

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "email": "[email protected]",
            "username": "[email protected]",
            "client_type": "individual",
            "first_name": "Jane",
            "last_name": "Doe",
            "phone_number": "987-765-1244",
            "address": [
                {
                    "address_line1": "3 Downtown Street",
                    "address_line2": "",
                    "city": "New York",
                    "type": "Home",
                    "postalcode": "01191",
                    "country": "US",
                    "state": "NY"
                }
            ]
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/client"

If you are using Hydrogen for your client authentication, you can store the username and password of the user in the Hydrogen admin module. The username in this service should match the username in the POST /client service, which will often be the email address. It’s important to always keep these in sync. The password will be encrypted using the bcrypt algorithm. This endpoint also supports PUT and GET. In the case that GET is used, the password would have to be decrypted using the same algorithm to be viewed.

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "username": "[email protected]",
            "password": "password",
            "is_account_non_expired": true,
            "is_account_non_locked": true,
            "is_credentials_non_expired": true,
            "is_enabled": true,
            "authorities": "ROLE_CLIENT"
        }' "https://sandbox.hydrogenplatform.com/admin/v1/client"

Account Setup

Create an Account Type

Before we can create an account, we must load account types into the API that a client may open. In this example we will add two simple account types:

  • Savings
  • Investment

Example Requests

curl -X POST -H "Authorization: Bearer <access_token>" \
-d '{
        "name": "Savings"
    }' "https://sandbox.hydrogenplatform.com/nucleus/v1/account_type"

curl -X POST -H "Authorization: Bearer <access_token>" \
-d '{
        "name": "Investment"
    }' "https://sandbox.hydrogenplatform.com/nucleus/v1/account_type"

Create an Account

Let’s create an investment account and assign it to the client created above. This could be done after the client fills out an account application.

Example Requests

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "name": "Investment Account",
            "account_type_id":"<Investment account_type_id>",
            "clients": [
               {
                 "client_id": "<client_id>",
                 "client_account_association_type": "owner"
               }
            ]
      }' "https://sandbox.hydrogenplatform.com/nucleus/v1/account"



Savings & Investing


In this section we’ll create a client onboarding and analytics dashboard for a savings or investment application. Assets for prototyping UIs to use in conjunction with this guide can be found in the Element UI Kit. React components for this kit are currently in development and scheduled to be released in Q2 2019.

Investment Profile

Questionnaire

To assess the client’s investment profile, we will set up a simple questionnaire comprised of 4 questions and a decision tree that will allocate the client to an allocation based on their answers to each question.

  • Age (open ended)
  • Asset Size (open ended)
  • Time Horizon
    • Less than 10 years
    • 10-20 years
    • Greater than 20 years
  • Risk Profile
    • Conservative
    • Moderate
    • Aggressive

Example Request

curl -X POST -H "Authorization: Bearer <access_token>"
     -H "Content-Type: application/json"
     -d '{
            "name": "Investment Profile Questionnaire",
            "description": "Determine the investment profile for a client.",
            "questions": [
                {
                    "category": "Investor Profile",
                    "title": "What is your age?",
                    "question_type": "text",
                    "order_index": "1"
                },
                {
                    "category": "Investor Profile",
                    "title": "How much will you be investing?",
                    "question_type": "monetary",
                    "order_index": "2"
                },
                {
                    "category": "Investor Profile",
                    "title": "What is your time horizon?",
                    "question_type": "radio",
                    "order_index": "3",
                    "answers": [
                      {
                        "value": "<10 years",
                        "label": "Less than 10 years"
                      },
                      {
                        "value": "10-20 years",
                        "label": "10-20 years"
                      },
                      {
                        "value": ">20 years",
                        "label": "Greater than 20 years"
                      }
                    ]
                },
                {
                    "category": "Risk Profile",
                    "title": "What is your risk profile?",
                    "question_type": "radio",
                    "order_index": "4",
                    "answers": [
                      {
                        "value": "conservative",
                        "label": "Conservative"
                      },
                      {
                        "value": "moderate",
                        "label": "Moderate"
                      },
                      {
                        "value": "aggressive",
                        "label": "Aggressive"
                      }
                    ]
                  }
            ]
      }'
"https://sandbox.hydrogenplatform.com/nucleus/v1/questionnaire"

Decision Tree

A Decision Tree will be utilized to recommend an allocation to users based on answers to the Investment Profile onboarding.

We will first create the Decision Tree entity for the Investment Profile.

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
              "name": "Investment Profile Decision Tree",
              "description": "Decision tree which allocates investors based on their investment profile."
          }' "https://sandbox.hydrogenplatform.com/nucleus/v1/decision_tree"

Nodes and Node Relationships

Next, we will create decision paths, by establishing Nodes that map to questions from the questionnaire above. Nodes are linked together via Node Relationships, which map to answers and eventually lead to a corresponding portfolio Allocation.

  • <10 yr time horizon, Conservative risk profile->Conservative Allocation
  • <10 yr time horizon, Moderate risk profile->Moderate Allocation
  • <10 yr time horizon, Aggressive risk profile->Moderate-Aggressive Allocation
  • 10-20 yr time horizon, Conservative risk profile->Conservative Allocation
  • 10-20 yr time horizon, Moderate risk profile->Moderate-Aggressive Allocation
  • 10-20 yr time horizon, Aggressive risk profile->Aggressive Allocation
  • >20 yr time horizon, Conservative risk profile->Moderate Allocation
  • >20 yr time horizon, Moderate risk profile->Moderate-Aggressive Allocation
  • >20 yr time horizon, Aggressive risk profile->Aggressive Allocation

Example Requests

As an example, we will create one decision path for an investor who has a <10 yr time horizon, and Conservative risk profile.

curl -X POST -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
              "name": "Time horizon question",
              "question_id": "<Time horizon question id>",
              "is_first": true
          }' "https://sandbox.hydrogenplatform.com/nucleus/v1/node"

curl -X POST -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
              "name": "<10yrs, risk question",
              "question_id": "<Risk profile question id>",
              "is_first": false
          }' "https://sandbox.hydrogenplatform.com/nucleus/v1/node"

curl -X POST -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
              "name": "<10yrs, conservative",
              "question_id": "<Risk profile question id>",
              "is_first": false
          }' "https://sandbox.hydrogenplatform.com/nucleus/v1/node"

curl -X POST -H "Authorization: Bearer <access_token> \
      -H "Content-Type: application/json" \
      -d '{
              "node_parent_id": "<Time horizon node id>",
              "node_child_id": "<<10yrs, risk question node id>",
              "answer_id": "<<10 years answer id>",
              "value": "<10 years",
              "is_leaf": false,
              "decision_tree_id": "<decision tree id>"
          }' "https://sandbox.hydrogenplatform.com/nucleus/v1/node_relationship"

curl -X POST -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
              "node_parent_id": "<<10yrs, risk question node id>",
              "node_child_id": "<<10yrs, conservative node id>",
              "answer_id": "<conservative answer id>",
              "value": "conservative",
              "is_leaf": true,
              "decision_tree_id": "<decision tree id>"
          }' "https://sandbox.hydrogenplatform.com/nucleus/v1/node_relationship"

The child node in the final node relationship (that has the is_leaf = true attribute) will have an allocation mapped to it via a field called node_map. This is found in the next section regarding Investment Models and Allocations.

Investing Instruments

Securities

Each model is made up of a collection of securities, which may be ETFs, stocks, mutual funds, or other financial instruments. We will create two Vanguard ETFs, one stock fund and one bond fund, which will be used in each model.

  • VTI- Vanguard Total Stock Market ETF
  • BND- Vanguard Total Bond Market ETF

Example Requests

Let’s create both securities in Nucleus:

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "name": "Vanguard Total Stock Market ETF",
            "security_class": "ETF",
            "ticker": "VTI",
            "asset_class": "US Equities"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/security"

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "name": "Vanguard Total Bond Market ETF",
            "security_class": "ETF",
            "ticker": "BND",
            "asset_class": "US Fixed Income"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/security"

Models

A model is made up of a collection of securities. We will create four models for various risk levels:

  • Conservative
  • Moderate
  • Moderate-Aggressive
  • Aggressive

Example Requests

Let’s create all three Models in Nucleus:

curl -X POST -H "Authorization: Bearer <access_token>" \
       -H "Content-Type: application/json" \
       -d '{
              "name": "Conservative",
              "description": "Investment model for an investor with a conservative risk profile."
          }' "https://sandbox.hydrogenplatform.com/nucleus/v1/model"

curl -X POST -H "Authorization: Bearer <access_token>" \
       -H "Content-Type: application/json" \
       -d '{
              "name": "Moderate",
              "description": "Investment model for an investor with a moderate risk profile."
          }' "https://sandbox.hydrogenplatform.com/nucleus/v1/model"

curl -X POST -H "Authorization: Bearer <access_token>" \
       -H "Content-Type: application/json" \
       -d '{
              "name": "Moderate-Aggressive",
              "description": "Investment model for an investor with a moderate-aggressive risk profile."
          }' "https://sandbox.hydrogenplatform.com/nucleus/v1/model"

curl -X POST -H "Authorization: Bearer <access_token>" \
       -H "Content-Type: application/json" \
       -d '{
              "name": "Aggressive",
              "description": "Investment model for an investor with a aggressive risk profile."
          }' "https://sandbox.hydrogenplatform.com/nucleus/v1/model"

Model Holdings

Each model will have a group of holdings. Each holding may have a current weight (based on current price) and strategic weight (target holding). However, there is no price movement yet in this model, so both weights will be the same. You may update the current weight over time to represent any drift from the strategic weight.

  • Conservative
    • 20% VTI
    • 80% BND
  • Moderate
    • 40% VTI
    • 60% BND
  • Moderate-Aggressive
    • 60% VTI
    • 40% BND
  • Aggressive
    • 80% VTI
    • 20% BND

Let’s use the Conservative Model as an example and then you can copy for the other three. To update the holdings we will need to get the following UUIDs first:

  • Conservative model_id
  • BND security_id
  • VTI security_id

Example Requests

Once we have the IDs above, we can create holdings for the Conservative Model Holdings:

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "current_weight": 80,
            "strategic_weight": 80,
            "date": "2019-01-01",
            "model_id": "<Conservative model_id>",
            "security_id": "<BND security_id>"
      }' "https://sandbox.hydrogenplatform.com/nucleus/v1/model_holding"

 curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "current_weight": 20,
            "strategic_weight": 20,
            "date": "2019-01-01",
            "model_id": "<Conservative model_id>",
            "security_id": "<VTI security_id>"
      }' "https://sandbox.hydrogenplatform.com/nucleus/v1/model_holding"

Allocations

An Allocation is made up of one or more models. An Account will be allocated to an Allocation, not a model, so it’s necessary to create allocations even if every allocation is only made up of one model.

  • Conservative
  • Moderate
  • Moderate-Aggressive
  • Aggressive

We will also load in historical volatility and performance data for the allocation which will come in handy to run simulations such as projected performance on the portfolio for clients. You may also attach it to the leaf node in a decision tree if it is part of a recommendation. Below you will find an example of the conservative allocation.

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -d '{
     "name": "Conservative",
            "description": "Allocation for an investor with a conservative risk profile.",
            "volatility": 0.03,
            "performance": 0.04,
            "node_map": [
                {
                    "node_id": "<decision tree leaf node id>"
                }
            ],
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/allocation"

Allocation Composition

In this simple example each allocation will be composed of a model with 100% weight. However, the composition could be comprised of many models of varying weights.

  • Conservative
    • 100% Conservative
  • Moderate
    • 100% Moderate
  • Moderate-Aggressive
    • 100% Moderate-Aggressive
  • Aggressive
    • 100% Aggressive

Let’s use the Conservative Allocation as an example and then you can copy for the other two. To update the composition we will need to get the following UUIDs first:

  • Conservative model_id
  • Conservative allocation_id

Example Request

Once we have the IDs above, we can create holdings for the Conservative Allocation Composition:

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "current_weight": 100,
            "strategic_weight": 100,
            "date": "2019-01-01",
            "model_id": "<Conservative model_id>",
            "allocation_id": "<Conservative allocation_id>"
      }' "https://sandbox.hydrogenplatform.com/nucleus/v1/model_holding"

Goals Based Investing/Savings

If you are building a goals based investing or savings application, you may use the following guide. If not, please skip ahead to the next section.

Firm Goals

We will be using the same goals for every client that signs up. You may also create client specific goals by adding the client_id into the request for each POST /goal

  • Retirement (decumulation)
  • Education (decumulation)
  • Build Wealth (accumulation)
  • Major Purchase (accumulation)
    • Home
    • Car
    • Wedding

A decumulation goal will first accumulate the assets and then withdraw a sum over a period of time until there are no assets remaining. An accumulation goal will accumulate assets until the target goal is reached and then withdraw in one lump sum to purchase the goal.

Example Requests

Let’s add a decumulation goal first as an example. You may optionally include the questionnaire_id that was created in the section above, if you wish to allow users to choose a goal during the onboarding process.

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "name": "Retirement",
            "questionnaire_id":"<questionnaire_id>",
            "is_decumulation": true
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/goal"

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "name": "Education",
            "questionnaire_id":"<questionnaire_id>",
            "is_decumulation": true
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/goal"

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "name": "Build Wealth",
            "questionnaire_id":"<questionnaire_id>",
            "is_decumulation": false
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/goal"

Now let’s see how a goal with subgoals would work. First we will add the main goal.

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "name": "Major Purchase",
            "questionnaire_id":"<questionnaire_id>",
            "is_decumulation": false
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/goal"

After inserting the Major Purchase goal, we will retrieve the id from the response and use it as the parent_goal_id for the car goal.

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "name": "Car",
            "Questionnaire_id": "<questionnaire_id>",
            "parent_goal_id": "<Major Purchase goal_id>",
            "is_decumulation": false
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/goal"

You can now insert the remaining sub-goals for Major Purchase using this same format. On a signup form, you can retrieve the goals to display by calling GET /goal. If you wish to display goal images or configure the order, you can add those properties in the metadata for each goal and define in the frontend code.

Assign Accounts to Goals

Now that you have firmwide goals in the API a user can customize the goal parameters after choosing a goal. These will be used later in the guide to perform goals tracking and recommendations.

Example Request

We will be updating the same account that was previously created and adding the goals data for the client. You may also create a new account if you haven’t yet done so in the client onboarding.

curl -X PUT -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
      "goals": [
        {
            "goal_id": "Build Wealth <goal_id>",
            "goal_amount": 40000,
            "accumulation_horizon": 5
        }
      ]
    }' "https://sandbox.hydrogenplatform.com/nucleus/v1/account/<account_id>"

Portfolio Recommendation

Now that we have created a questionnaire, decision tree, and investment models and allocations, we can put them all together into a recommendation like the screenshot above.

Let’s rebuild the screen above for a user that filled out their investment profile and was recommended an allocation based on the answers provided.

Feature Endpoints Used
1

After the user answers each question in the investment profile, you can traverse through the nodes in the decision tree to find the last is_leaf node. This node_id may now be used to find the corresponding allocation.

GET /nucleus/v1/allocation/{allocation_id}?filter=node_map.node_id=={node_id}
"id"
"name"
"volatility"
"performance"

2

Based on the allocation chosen in #1, use the volatility and performance to run a Monte Carlo simulation. The investment amount entered by the user in the questionnaire may now be multiplied by the last value in the simulation (or you may want to show the estimated growth of $10,000)

GET /nucleus/v1/allocation/{allocation_id}/performance?stat=monte_carlo

3 Pull from the name of the model or allocation in #1
4

Retrieve the model_ids in the allocation composition.

GET /nucleus/v1/allocation_composition?filter=allocation_id=={allocation_id}
"model_id"
"current_weight"

For each model_id you can now retrieve data to fill in the table and pie chart. If you wish to group by asset class, you can go one level down to all the security holdings within each model and aggregate the weights.

GET /nucleus/v1/security?filter=id=in=({security_ids})
"ticker"
"asset_class"
"name"

Subscribe Account

If the user agrees to the recommendation, you may subscribe their account_id to the allocation, which will create a portfolio for the client. You may subscribe the user to the recommended allocation_id, and for goals based investing applications, the goal_id. The values and weights of both of these fields may now be tracked over time using the /account_allocation service, should the user change their allocation or goal.

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d ' {
            "current_weight" : "100",
            "strategic_weight": "100",
            "date": "2019-01-01",
            "allocation_id": "<allocation_id>",  
            "goal_id": "<goal_id>"
         }' "https://sandbox.hydrogenplatform.com/nucleus/v1/account/<aaccount_id>/subscribe"

Account Funding

For the purpose of the quickstart guide, we will not be funding an account. However, if you wish to simulate funding an account from a bank transfer, you can following the workflow below:

Create a Bank Link

Fund an Account From a Bank Link

To simulate funding an account from an account transfer such as another brokerage firm, you can following the workflow below:

Transfer an External Account


Investing an Account

Transaction Codes

Before submitting orders to execute a client’s account, you must set up transaction codes for your firm. Depending on your broker, there may be multiple codes used to distinguish transactions such as cash deposits, security purchases, and dividends.

Example Requests

We will create one transaction code for a BUY and one for a SELL.

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "category": "Security Purchases",
            "is_buy": true,
            "transaction_code": "BUY",
            "transaction_code_description": "Buy Security"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/transaction_code"

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "category": "Security Sales",
            "is_buy": false,
            "transaction_code": "SELL",
            "transaction_code_description": "Sell Security"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/transaction_code"

Order Generation

For the purpose of the quickstart guide, we will not be generating orders for a portfolio. However, if you wish to simulate generating and submitting orders, you may follow the workflow below:

Generating Orders

Portfolio Holdings

Once you have filled the orders you will create transactions for the orders, and the initial holdings for the portfolio. These holdings may be updated ongoing as the portfolio changes.

Previously in the guide, the user was allocated to a simple portfolio that consisted of two ETFS: 60% VTI (US Equities) and 40% BND (US Fixed Income). For simplicity sake, we will assume that $100 was invested and the price of each ETF is $10. In the real world, you would receive these details from the order fill after execution.

Example Requests

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d ' {
            "amount": 60,
            "shares": 6,
            "date": "2019-01-02",
            "weight": 60,
            "security_id": "<VTI security_id>",
            "portfolio_id": "<portfolio_id>"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/portfolio_holding"

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d ' {
            "amount": 40,
            "shares": 4,
            "date": "2019-01-02",
            "weight": 40,
            "security_id": "<BND security_id>",
            "portfolio_id": "<portfolio_id>"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/portfolio_holding"

Portfolio Transactions

To display historical transactions of security buys and sells to users, you may also update the Portfolio Transactions for the client. Please use the Transaction Codes entered for your firm to distinguish buys and sells.

Example Requests

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d ' {  
            "date": "2019-01-02",
            "price": 10,
            "quantity": 6,
            "security_id": "<VTI security_id>",
            "transaction_code_id": "<BUY transaction_code_id>",
            "portfolio_id": "<portfolio_id>",
            "account_id": "<account_id>",
            "model_id": "<model_id>"
        }’ "https://sandbox.hydrogenplatform.com/nucleus/v1/portfolio_transaction"

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d ' {  
            "date": "2019-01-02",
            "price": 10,
            "quantity": 4,
            "security_id": "<BND security_id>",
            "transaction_code_id": "<BUY transaction_code_id>",
            "portfolio_id": "<portfolio_id>",
            "account_id": "<account_id>",
            "model_id": "<model_id>"
        }’ "https://sandbox.hydrogenplatform.com/nucleus/v1/portfolio_transaction"

Investment Reporting

Portfolio Update

Assuming the accounts for the client have been funded and invested, you may update the portfolio asset sizes to track the portfolio and display analytics.

Example Requests

We will create portfolio asset sizes for 5 days in our example. On the first day the account is invested, a cash_flow of the initial balance amount will be added. If there are any future additions or withdrawals to the account, you will also add that to the cash_flow field, to accurately track performance.

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "cash_flow": 100,
            "asset_size": 100,
            "date": "2019-01-02",
            "portfolio_id": "<portfolio_id>"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/portfolio_asset_size"

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "cash_flow": 0,
            "asset_size": 101,
            "date": "2019-01-03",
            "portfolio_id": "<portfolio_id>"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/portfolio_asset_size"

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "cash_flow": 0,
            "asset_size": 102,
            "date": "2019-01-04",
            "portfolio_id": "<portfolio_id>"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/portfolio_asset_size"

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "cash_flow": 0,
            "asset_size": 103,
            "date": "2019-01-07",
            "portfolio_id": "<portfolio_id>"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/portfolio_asset_size"

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "cash_flow": 0,
            "asset_size": 104,
            "date": "2019-01-08",
            "portfolio_id": "<portfolio_id>"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/portfolio_asset_size"

Once the portfolio asset sizes have been created, you may also choose to track the client’s allocation over time.

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
           "current_weight": 100,
           "date": "2019-01-02",
           "strategic_weight": 100,
           "allocation_id": "<allocation_id>",
           "goal_id": "<goal_id>",
           "account_id": "<account_id>"
        }' "https://sandbox.hydrogenplatform.com/nucleus/v1/account_allocation"

Investment Analytics

The screenshot above is an example of a portfolio analytics and holdings screen that you could display to users when they log into their account. Let’s rebuild this dashboard below:

Feature Endpoints Used
1

Retrieve the client_id and client details from the client that logs in based on their username or email. This client_id will be used for all other services.

GET /nucleus/v1/client?filter=email=={email}
"id"
"first_name"
"last_name"

Optional: If the client has more than one account and you wish to show the dashboard for only one account, and not aggregate across all client accounts, you can use the client_id to find all accounts the client owns.

GET /nucleus/v1/account?filter=clients.client_id=={client_id{
"id"

2

GET /nucleus/v1/client/{client_id}/asset_size
"value"

The last data point in the result will be the current balance

3 Same call as #2. The earnings can be calculated using the following logic: last asset size value - first asset_size value - SUM(additions)
4 GET /nucleus/v1/client/{client_id}/performance?stat=cum_return
5 GET /nucleus/v1/client/{client_id}/performance?stat=ann_vol
6 Same call as #2
7

Retrieve the latest portfolio holdings for the client ordered by date.

GET /nucleus/v1/client/{client_id}/holding?order_by=date
"date"
"security_id"
"weight"

For each security_id you can now retrieve data to fill in the table and pie chart. The balance for each security can be acheived by using the current balance retrieved in #2 and the weight for each security.

GET /nucleus/v1/security?filter=id=in=({security_ids})
"ticker"
"asset_class"
"name"


Goal Tracking

The screenshot above is an example of a tracking dashboard for a goals based investing application, that you could display to users when they log into their account.

Feature Endpoints Used
1

Retrieve the client_id and client details from the client that logs in based on their username or email. This client_id will be used for all other services.

GET /nucleus/v1/client/{client_id}
"first_name"
"last_name

2

Retrieve all the account and goals for a client

GET /nucleus/v1/account?filter=clients.client_id=={client_id}
"id"
"goal"
   "goal_id"
   "goal_amount"
   "accumulation_horizon"
   "decumulation_horizon"

For each goal_id you can now get the name and attributes of each goal

GET /nucleus/v1/goal/{goal_id}/asset_size?client_id={client_id}
"name"
"is_decumulation"

The current aggregate balance of all accounts within the goal can be retrieved.

GET /nucleus/v1/goal/{goal_id}/asset_size?client_id={client_id}

To see if the goal is on or off track, you can use the data collected to run the goal - p_ret, p_risk, curr_inv, horizon, horizon_frequency, goal_amount. The p_ret and p_risk of the holdings can be retrieved via the GET /goal/{goal_id}/performance service, or using historical market or backtested allocation data. If is_decumulation is set to true, you would run the goal_decumulation services instead.

POST /proton/v1/goal_accumulation/status
"on_track"

3 Same value as asset size retrieved in #2
4

GET /nucleus/v1/funding
"amount"

5 Same goal_amount, accumulation_horizon, decumulation_horizon (if is_decumulation is set to true in #2) retrieved in #2
6

Same goal decumulation or accumulation service called in #2.

POST /proton/v1/goal_decumulation/status
"current_status"
   "return_details




Financial Wellness

Coming soon...

  • Creating and tracking budgets
  • Aggregating held away accounts
  • Cash Flow analysis
  • Net Worth analysis