Molecule Quickstart Guide

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

Molecule Overview


The Hydrogen Molecule API is designed to add financial blockchain components to any Hydrogen application. On-chain components in Molecule can easily be complimented by off-chain components built with Hydrogen Atom APIs. All on-chain functionality in Molecule is built on the public Ethereum blockchain. The Hydrogen Sandbox interacts with the Ethereum Testnet so there will be no additional costs for performing blockchain operations. Once your app is in production and you wish to utilize the Ethereum Mainnet, gas costs will be included in your Hydrogen license. Molecule is built on REST principles, with resource oriented URLs and HTTP response codes. All API responses are returned in JSON format.

Sandbox Base URL:
Production Base URL:

Key Entities


In Molecule, client accounts are called wallets. A wallet is where you can access the keys of your clients to sign blockchain transactions. The wallet is used to receive, store, and send security tokens and cryptocurrencies. All Molecule wallets are linked to a Nucleus Client.

Wallet Key

A wallet key is used to store the public and private key pair associated with a wallet. There are two possible ways of storing this pair, which depends on your firm’s Key Management Server (KMS) integration setup. See the documentation for more information.

Security Token

A token is a digital representation of a real world asset, such as a stock, real estate, art etc. Token owners (issuers) are allowed to create a whitelist of individuals who can receive, store, and send their tokens by enforcing various restrictions such as minimum age, minimum annual income etc.


A crowdsale is a type of crowdfunding that issues security tokens that are stored in an investor's wallet. The tokens function like a share of stock and can be purchased by the investors. Crowdsale methods can be used to deploy, fund, and purchase from a crowdsale contract.


A currency is a store of value. This can either be a fiat hard currency offered by a government's central bank or a cryptocurrency which is offered by decentralized entities as a digital asset.


Now that we are all caught up on basic terminology, the first step is to properly authenticate our application. All Hydrogen APIs use OAuth 2.0 to facilitate authorization on the API, an industry standard framework for authorization. Please follow the Authentication Guide in the Hydrogen Atom Quickstart.


Create Wallet

Once you've obtained your access_token, you're ready to start making authenticated requests to the Hydrogen Atom and Molecule APIs.

If this is your first time using Hydrogen, you must first create a Nucleus Client in Hydrogen Atom. All users in Molecule are associated to a Nucleus Client. You'll reference the Nucleus Client that you'd like to associate with your Molecule Wallet in the request below.

Pro-tip: Here's the data hierarchy of account entities in Hydrogen.

  • Client Admin (POST /admin/v1/client)
    • Nucleus Client (POST /nucleus/v1/client)
      • Nucleus Account (POST /nucleus/v1/account)
      • Molecule Wallet (POST /molecule/v1/wallet)
        • Molecule Wallet Key (POST /wallet_key/generator)

In Molecule, client accounts are called wallets, and each wallet possesses a key pair, referenced through the wallet_key entity. To create a wallet, we'll need to pass the following information into the API:

  • name - name for our wallet
  • type- the type of wallet (individual, business, trust, or contract)
  • clients - Nucleus Client ID and the relationship of the client to the wallet (joint, owner, trustee, viewer, or admin)

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Test Wallet",
  "type": "individual",
  "clients": [
      "nucleus_client_id": "<client_id>",
      "client_wallet_association_type": "owner"
}' ""

Create Key Pair

Next, we'll create a blockchain key pair for our newly created Molecule wallet. If you have enabled the Azure KMS integration the key pair will be automatically generated and stored in Azure. If you have generated a key pair on your own and wish to store it in Molecule, you can use the POST /wallet_key method instead. In the example below, we will have Molecule automatically generate a key pair for us, and then store it in Molecule using POST /wallet_key/generator.

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "wallet_id": "<wallet_id>"
}' ""

Hooray! Now your Molecule wallet is setup, and you're ready to start creating transactions. Let's take a look at how this is done.


Add Currencies

Molecule lets you send and receive Ethereum or any ERC-20 compatible Ethereum token. Let's call a service to create the currencies that we want to allow our users to transact in. To do this, we just need to send the contract address to POST /currency. In the example below, we will add Ethereum as our currency. Since there is no address for Ethereum, we can add it by simply typing in the name "Ethereum" as the address. We'll reference the ID that gets created in our transaction in the next step.

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "address": "Ethereum"
}' ""

Send Crypto Payment

Now, let's make a transaction to send Ether (Ethereum's currency) to another Molecule wallet by using the id that we received in the response of the previous step. We'll need to include the following fields in our request. If you're building a wallet app, you'll want to capture these inputs from your users in the UI.

  • sender_wallet_id - the ID of the wallet sending the currency
  • receiver_wallet_id - the ID of the wallet you are sending the currency to. Create a wallet for another client by using the method POST /wallet
  • currency_id - the ID of the currency. In this case it will be for Ether
  • amount - the amount of Ether you wish to send

You'll notice that we're sending Ether, but we haven't funded our account yet. Fortunately, each Molecule wallet in Sandbox is awarded an initial Ether balance to cover test transactions. If we make a transaction with ~.099 Ether, our transaction will go through and our counter-party will receive their Ether.

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "sender_wallet_id": "<wallet_id> of sender",
  "receiver_wallet_id": "<wallet_id> of receiver",
  "currency_id": "<currency_id> of Ether",
  "amount": "<amount> to send"
}' ""

View Transactions

Let's retrieve the list of our transactions to determine if the transaction was successful. You'll notice that we add a size parameter to our query in order to return up to 5,000 records from the database. Learn more about sorting here.

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \

You should now see your transaction in the list returned from GET /currency_transfer. As you can see, Molecule makes it easy to interact with the blockchain without the pain of tracking account states or creating raw transactions using the low-level blockchain APIs that exist today.

We have now seamlessly created wallets and sent cryptocurrency within the Molecule ecosystem. These are foundational elements to dozens of powerful solutions you can augment with blockchain technology on Atom. Using Molecule, you can extend this functionality to build your own cryptocurrency applications. We're excited to see what you build!

Interested in building your own blockchain-powered app using Molecule? Reach out to our sales team to schedule a demo!


Coming soon...

  • Create tamper-proof documents, tracked on the blockchain.
By using this site, you agree to our use of cookies, and you acknowledge that you have read and understand our Privacy Policy and Terms of Use   Continue