Atom Fintech API Quickstart Guide

Atom API Overview

All apps on Hydrogen should be built using our no-code app library. We offer APIs that can be used on top of these apps for developers to perform operational tasks, subscribe to events, automate back office processes, and sync user data.

Introduction

Hydrogen Atom is a suite of APIs that connect into data on the Hydrogen no-code platform. 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, idempotency, and webhooks.

The following APIs are part of Hydrogen Atom:

Nucleus

Nucleus provides the data model for all Hydrogen applications. This includes the base functionality to onboard clients and accounts, and store and process data which all other APIs in Atom will utilize. View the online documentation here.

Base URL: https://api.hydrogenplatform.com/nucleus/v1

Proton

Proton provides business logic on top of the core Nucleus data within the Atom APIs. Proton offers analytical tools, scoring, calculators, recommendations, and simulations. All client facing no-code apps utilize these APIs in a pre-approved, compliant manner, but these APIs can be used standalone in select enterprise use-cases. There is no data storage in Proton. View the online documentation here.

Base URL: https://api.hydrogenplatform.com/proton/v1

Electron

Electron provides back office bank connectivity on top of the core Nucleus data within the Atom APIs. This API requires additional permissions. All functionality housed within Electron can be accomplished via a no-code app or through our app portal. View the online documentation here.

Base URL: https://api.hydrogenplatform.com/electron/v1

Key Entities

General

The following entities are used in all products on the platform:

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. An account can hold n-number of portfolios.

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.

Business

A business represents a corporate entity where collections of clients are employed. It may be identified based on a unique identifier, such as a government issued ID (e.g. EIN in US). A business can have one primary owner, and be comprised of many clients.

Budget

A budget allows a user to track their spending in categories over a specified time period.

Funding

Funding requests are utilized throughout Hydrogen Atom to create deposits and withdrawals into accounts, and track their status. Bank links can also be stored to submit ACH and wires.

Household

A household is a collection of clients in the same family to view their finances in aggregate.

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.

Debit

The following entities are used in the Debit product:

Card

Debit cards issued through Hydrogen's banking partners on the Visa or Mastercard network that can be used to purchase goods.

Spending Control

Spending controls can be added at a client level for all cards associated with the client. These controls will restrict purchases and ATM withdrawal amounts, as well as spending within a category or at a specific merchant.

Entity Activity

The following entities are used in all our products to provide :

Asset Size

The aggregate monetary value of a financial account based on the balance of the banking account, or aggregate value of underlying positions for an investment account. The asset size changes as securities fluctuate or monies/securities are deposited/withdrawn.

Transaction

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

Whitelisting

API security is paramount to Hydrogen. We enforce some key security protocols to protect our clients and their end users. One of these important security measures is IP Whitelisting.

You must follow this whitelisting guide before hitting the Hydrogen APIs or embedding any no-code applications into your platform:

Whitelisting Guide

API Features

Client Libraries

Client libraries are available in major coding languages to help software developers easily work with our APIs. Sample requests in all languages are available on the API reference. We offer the following SDKs:

Nucleus

Proton

Authentication

Before authenticating, you must receive your API credentials. To do so, please go to the "API Keys & Whitelists" page on the Hydrogen portal.

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, also known as "Resource Owner Password," is used by your application to authenticate an end user with their login credentials. This grant should be used if you are storing the user's password in 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. All white label web and mobile apps will automatically manage usernames and passwords. For embedded web components this is optional, and a Custom Client Token can be generated instead. Please read our no-code guide for more details.

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://api.hydrogenplatform.com/authorization/v1/oauth/token?grant_type=client_credentials \
-H "Authorization: Basic <Base64 encoded client_id:client_secret>"

Password Grant

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

curl -X POST https://api.hydrogenplatform.com/authorization/v1/oauth/token?grant_type=password&username=<username>&password=<password> \
-H "Authorization: Basic <Base64 encoded client_id:client_secret>"

In the response for both grant types, you will receive an access_token which is required for future requests by passing into the authorization header as a Bearer token. If you want to persist the access_token in your application we like using the localStorage() function to store in our browser's key value store.

Example Request

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

Access Controls

Data is permissioned in Nucleus through an Access Controls List (ACL). When clients are signed up in the Nucleus Client through POST /nucleus/v1/client, they will be assigned one or more of the authorities listed below. Depending on the authority, the user will be able to access certain data within the tenant, as explained in this guide.

Super Admin: ROLE_SUPER_ADMIN
Admin: ROLE_ADMIN
Portfolio Manager: ROLE_PORTFOLIO_MANAGER
Marketing Manager: ROLE_MARKETING_MANAGER
Operations Agent: ROLE_OPERATIONS
Support Agent: ROLE_SUPPORT
Business Owner: ROLE_BUSINESS_OWNER
Advisor: ROLE_ADVISOR
Client: ROLE_CLIENT

In addition to access controls on API data, we also offer more granular permissions on account access. When a client_id is included in the clients embedded object of a call to the POST /account and PUT /account/{account_id} endpoints, they will automatically be mapped to the account with a permission type based on the client_account_association_type granted to them. You may update the permissions using the PUT /account_permission/{account_id} service. Only clients with the authority of ROLE_SUPER_ADMIN, ROLE_ADMIN, ROLE_PORTFOLIO_MANAGER, ROLE_MARKETING_MANAGER, ROLE_OPERATIONS, ROLE_SUPPORT, or ROLE_ADVISOR can access this endpoint:

Inquiry Access: INQUIRY_ACCESS
Limited Authority: LIMITED_AUTHORITY
Full Authority: FULL_AUTHORITY
Power of Attorney: POWER_OF_ATTORNEY

Pagination & Filters

Pagination

For API resources that return a large volume of results you may use pagination. When using these “List all” API methods, rather than returning a large list of results, the results will be paginated by default. Please note that pagination is not available on some API resources, specified in the description of the resource.

The response container of a paginated GET request in Nucleus will display like below:

{
  "content": [
  ],
  "first": true,
  "last": false,
  "number_of_elements": 10,
  "total_elements": 29,
  "total_pages": 3,
  "size": 10,
  "number": 0,
  "sort": [
    {
      "direction": "ASC",
      "property": "id",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": true,
      "descending": false
    }
]

The following parameters can be appended to a GET request as a query string to paginate

page: page number for the page that should be returned as the starting page. For example, if this is specified as 0, then the first page of the results will be shown, if it is set as 3 then the third page of the results will be shown, and so on. The default is 0.
size: he number or records to be included per page. The default is 25. There is no max value.
order_by: The field in the response body to order the list by. Default is update_date.
ascending: If true, order the results in ascending order. For an alphabetical result this would be A-Z. If false, order the results in descending order. For an alphabetical result this would be Z-A. Default is false which would order by descending.

Filters

Every field within an object using the GET method in Nucleus (all Proton methods are POST) can be filtered except for fields stored under metadata. Filtering is especially useful for calls that return many different fields. We support the following filter operators:

AND: code>; or and
OR: , or or
Like: =like=
Equal to: ==
Not equal to: !=
Less than: =lt= or <
Less than or equal to: =le= or <=
Greater than: =gt= or >
Greater than or equal to: =ge= or >=
Is Null: =isnull=
In: =in=
Not in: =out=

The basic construct for a filtering query is as follows:

/?filter=query

To filter using a simple one word field within an object, the query would be as follows:

/?filter=fieldname==fieldvalue

To filter using a field with multiple words or special characters, URL encode the query string. The query would be as follows:

/?filter=fieldname==fieldvalue+fieldvalue

To filter using a field within an embedded object, the query would be as follows:

/?filter=objectname.fieldname==fieldvalue

To filter using the =like= operator, you may include an asterisk * as a wildcard before or after the value (same functionality as % in SQL):

/?filter=fieldname=like=*fieldvalue*

To filter using the =in= or =out= options, include a series of comma-separated values wrapped in parentheses, with no spaces between values. The query would be as follows:

/?filter==in=(fieldvalue,fieldvalue,fieldvalue)

Webhooks

Hydrogen Atom offers webhooks that you may subscribe to and consume 20+ events. Webhooks are useful for building your own alerts service for an application, triggering back office processes, or simply being informed when a new record is created or updated. For a list of webhooks, please see our Nucleus API reference.

After subscribing a URL to one of our webhook services through POST /webhook, you will receive a secret like the response below:

{
  "id": "1f6f3345-737a-400f-b5b8-bdb15382f803",
  "url": "https://www.hydrogenplatform.com/callback/budget",
  "secret":"cTMzZjNiMGYyZjlhYjk0OTQxY2QwODE4ZDc5aHQ5NDVjcmExMDU2Mg==",
  "is_active": true,
  "atom_service": ["budget"],
  "secondary_id": null,
  "update_date": "2019-11-14T17:20:21.000+0000",
  "create_date": "2019-11-14T17:20:21.000+0000"
}

To securely receive the webhook payload, you should verify that the request was made by Hydrogen. The headers of every payload will include an x-hydrogen-signature that includes a Base64 encoded signature of the following data, which has been HMAC SHA-256 hashed using the secret for the webhook. Each field should be separated by a space. The content will be the json payload of the response body that gets posted:

date content-type content-length content

Example Header Payload

{
  "content-length": "621",
  "accept": "application/json, application/*+json",
  "x-hydrogen-signature": "headers=date content-type content-length content,algorithm=HMAC_SHA_256,signature=YTE3ZjdjZGQ0NDc4MDQ5NmZiOGMyNDg0MzliZWI0MDhkNjU4OGVhZTkxMDM1ZTE4Y2M2MmYxZTM3OWNlODFlMg==",
  "x-hydrogen-service": "portfolio_transaction",
  "date": "2020-03-30 16:41:15",
  "content-type": "application/json",
  "user-agent": "Java/1.8.0_242"
}

Using the secret that was received when the webhook was created above, you will then create a Hash-based message authentication code (HMAC) with SHA-256 encryption. The result can then be Base64 encoded and compared to the signature in the header. If the two match then you have successfully verified the validity of the webhook.

Please see the following online resources to use HMAC-256 in the language of your choice:
Resource 1 | Resource 2

Idempotency

An API request is idempotent if it has the same result no matter how many times it is tried. Hydrogen supports idempotency in Nucleus to allow requests to be retried without risk of the operation being performed multiple times. This is useful for requests that involve critical such as payments or account creation to protect against network outages and you are unsure if a previous request had been processed successfully. If you ever have any doubt, always submit the request again with the same idempotency key in the request header to make sure you don’t duplicate the data.

To submit an idempotent request, simply submit any POST request with an Idempotency-Key in the Request Header. If you retry the same request body and endpoint with the Idempotency-Key you will receive a cached version of the original response if it was successfully submitted the first time.

To create a unique Idempotency-Key please one of the libraries below to generate a unique UUID in the language of your choice:

C#: Guid.NewGuid

Bulk Data

Bulk data entry is available on most POST, PUT, and DELETE services, up to 100 entries at a time. Requests will be sent into a messaging queue and processed asynchronously so you may still perform other processes while this is occurring. To submit a Bulk request, you would follow the format below:

POST /bulk/{entity}

PUT /bulk/{entity}

The {entity} listed above can be replaced with any major entity in Nucleus, such as account, client, security etc. After submitting the request, you will be given an id in the response. You will then be able to receive a status report of the bulk operation, by calling GET /bulk/status/{bulk_id} with the id generated above. If the bulk operation is done you will receive a status of "Complete."

Resources

Resources are lists of data that are used throughout the Nucleus data model, and are documented as reference for developers. They are also helpful if you need to dynamically pull in a large list of data into a select dropdown, and you want to make sure all the data is properly validated when submitted to Nucleus. For example, you may need to display a list of states or countries in an address form on an account onboarding, or a list of merchants in a card spending controls UI.

Authorities
Permission Types
Countries
States
Currencies
FX Rates
Account Categories
Merchants
Merchant Categories
Merchant Category Codes

User Onboarding

Our no-codes will handle client signups for each Hydrogen product offering. However, there are some use cases where you may need to use our APIs to sign up the client programatically. 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.

If you are using Hydrogen for your password authentication, the password will be encrypted with a unique salt and hashed using the bcrypt algorithm, an industry standard for bank-grade password encryption. This endpoint also supports PUT and GET. In the case that GET is used, you will never be able to view the plain text password once it's been encrypted and stored. To check the validity of a user's entered login credentials, you can simply POST to the OAuth service above using the password grant and check for a valid 200 response.

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]",
  "authorities": "ROLE_CLIENT",
  "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://api.hydrogenplatform.com/nucleus/v1/client"

Account Setup

Create an Account

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

Example Request

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

Create a Portfolio

After creating the account, you will need to now create one or more portfolios under the account if you want to track asset sizes/balances, holdings, and transactions. Accounts do not hold any of these values themselves.

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Debit Portfolio",
  "account_id":"<account_id>",
  "percentage":100
}' "https://api.hydrogenplatform.com/nucleus/v1/portfolio"

Capabilities

Platform

Atom Quickstart Guide

Atom API Overview

Introduction

Nucleus

Proton

Electron

Key Entities

General

Account

Client

Business

Budget

Funding

Household

Portfolio

Debit

Card

Spending Control

Entity Activity

Asset Size

Transaction

Whitelisting

API Features

Client Libraries

Nucleus

Proton

Authentication

Access Controls

Pagination & Filters

Pagination

Filters

Webhooks

Example Header Payload

Idempotency

Bulk Data

Resources

User Onboarding

Client Signup

Account Setup

Create an Account

Create a Portfolio