NAV
curl python javascript

Introduction

Sandbox Base URL

https://sandbox.hydrogenplatform.com/molecule/v1

Production Base URL

https://api.hydrogenplatform.com/molecule/v1

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.

Authentication

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

Fields

IDS

All Object IDs are represented in universally unique identifier (UUID) format. A UUID is a string of 32 alphanumeric characters in the format 8-4-4-4-12. An example would be efa289b2-3565-42e6-850b-8dad25727e99.

DATES

All dates are represented in ISO 8601 format YYYY-MM-DD. An example would be 2018-01-10.

TIMESTAMPS

All object responses will include a create_date and update_date in timestamp format. All timestamps are represented in ISO 8601 format YYYY-MM-DDThh:mm:ssTZD. The “T” appears before the time element and the TZD before the time zone. An example would be 2018-01-10T16:00:30+01:00.

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, incorrect ID, or empty result.
405 Not Allowed. Occurs when you try to make a request which is not allowed on an endpoint.
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.
204 No Content. The request was successful but there is no additional content to send in the response body. This will occur on a successful DELETE.

Versioning

The Molecule 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

Date Change Description
2020-02-25 addition Added Wallet Permission endpoint.
2020-02-28 addition Added ability to Mint and Burn tokens. Added new service to update a Currency Balance.
2019-12-27 update Changed query parameters section to Filters for a better reading experience.
2019-12-27 addition Added new fields and methods to Token endpoint.
2019-12-26 addition Added Currency endpoint.
2019-11-04 addition Added Transaction Status endpoint.
2019-10-30 addition Added information about Event Handlers.
2019-10-28 addition Decoupled crowdsale functions from tokenization. Added Crowdsale endpoint.
2019-10-16 addition Added Currency Balance endpoint.
2019-10-10 addition Added Currency Transfer endpoint.
2019-10-03 addition Added Token Transfer endpoint.
2019-09-24 update Converted balance and supply related token, token_balance and total_supply integer fields to double.
2019-09-18 addition Initial commit. Added Wallet, Wallet Key, Balance, Token, and Token Supply endpoints.

Pagination

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/wallet?page=0&size=25&order_by=update_date&ascending=false"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
page = 0
size = 25
order_by = 'update_date'
ascending = false

try:
    api_response = api_instance.get_wallets(page=page, size=size, order_by=order_by, ascending=ascending)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_wallets: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var opts = {
  'page': 0,
  'size': 25,
  'orderBy': "update_date",
  'ascending': false
};

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

Example Response

{
    "content": [
        {
            "id": "eb32c593-a452-41ff-8c5e-807d106c6486",
            "wallet_key_id": "94707d27-7aae-4cc8-b925-afe519c00537",
            "name": "Armando Withaker",
            "type": "individual",
            "is_active": true,
            "secondary_id": null,
            "create_date": "2019-09-12T21:42:33.000Z",
            "update_date": "2019-09-12T21:43:23.000Z",
            "clients": [
                {
                    "nucleus_client_id": "afefc951-a53b-44c7-907b-2b26ccf589e3",
                    "client_wallet_association_type": "owner",
                    "is_primary": true
                }
            ],
            "metadata": {},
            "token_whitelists": [
                {
                    "token_id": "1b8cc79d-b409-4d35-94e9-a902ab1683e6",
                    "role": "owner",
                    "sell_restriction_date": null,
                    "buy_restriction_date": null
                },
                {
                    "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
                    "role": null,
                    "sell_restriction_date": null,
                    "buy_restriction_date": null
                }
            ]
        },
        {
            "id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
            "wallet_key_id": "a82a5ee3-55ba-405a-b202-4bf0402614d3",
            "name": "Jong LLC",
            "type": "business",
            "is_active": true,
            "secondary_id": null,
            "create_date": "2019-09-12T21:38:21.000Z",
            "update_date": "2019-09-12T21:39:56.000Z",
            "clients": [
                {
                    "nucleus_client_id": "dd707c48-599c-4edd-8055-04682e583483",
                    "client_wallet_association_type": "admin",
                    "is_primary": true
                },
                {
                    "nucleus_client_id": "b5f3abe9-bea2-4b31-9416-1080041efac2",
                    "client_wallet_association_type": "owner",
                    "is_primary": true
                }
            ],
            "metadata": {},
            "token_whitelists": [
                {
                    "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
                    "role": "owner",
                    "sell_restriction_date": null,
                    "buy_restriction_date": null
                }
            ]
        },
        {
            "id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
            "wallet_key_id": "00c00c35-8a6c-47a7-a15e-ef297475d212",
            "name": "Amanda Kirby",
            "type": "individual",
            "is_active": true,
            "secondary_id": null,
            "create_date": "2019-09-12T21:38:34.000Z",
            "update_date": "2019-09-12T21:39:21.000Z",
            "clients": [
                {
                    "nucleus_client_id": "23bb0389-aa37-4be5-9dc5-07f21a8f4d32",
                    "client_wallet_association_type": "owner",
                    "is_primary": true
                }
            ],
            "metadata": {},
            "token_whitelists": [
                {
                    "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
                    "role": null,
                    "sell_restriction_date": null,
                    "buy_restriction_date": null
                },
                {
                    "token_id": "1b8cc79d-b409-4d35-94e9-a902ab1683e6",
                    "role": null,
                    "sell_restriction_date": null,
                    "buy_restriction_date": null
                }
            ]
        }
    ],
    "total_pages": 1,
    "total_elements": 3,
    "last": true,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "update_date",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": false,
            "descending": true
        }
    ],
    "number_of_elements": 3,
    "size": 25,
    "number": 0
}

For API resources that return a large volume of results you may use pagination. When using these “List all” API methods, rather than returning an extensive list of results, the results will be paginated by default.

ARGUMENTS

Parameter Type Description
page
optional
integer 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 the 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
optional
integer The number or records to be included per page. The default is 25. There is no max value.
order_by
optional
string The field in the response body to order the list by. For example, if ‘order by’ is specified as ID, then the response returned will be organized based on the value of their ID. No default is set.
ascending
optional
boolean 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

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token_balance?wallet_id=2b96275a-8051-455a-9d37-2dfcfe282bf6&token_id=f213717a-0385-4c3b-8813-11df6247afda&get_latest=true"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

wallet_id = "2b96275a-8051-455a-9d37-2dfcfe282bf6"
token_id = "f213717a-0385-4c3b-8813-11df6247afda"
get_latest = True

try:
    api_response = api_instance.get_token_balances(wallet_id=wallet_id, token_id=token_id, get_latest=get_latest)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_token_balances: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var params = {
  walletId: "2b96275a-8051-455a-9d37-2dfcfe282bf6",
  tokenId: "f213717a-0385-4c3b-8813-11df6247afda",
  getLatest: true
};

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

Example Response

{
  "content": [
    {
      "id": "4d421d3d-9c18-4486-b98a-f66c5040dc3b",
      "balance": 1400000,
      "wallet_id": "2b96275a-8051-455a-9d37-2dfcfe282bf6",
      "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
      "create_date": "2019-09-12T22:04:12.000Z",
      "update_date": "2019-09-12T22:04:12.000Z"
    }
  ],
  "total_pages": 7,
  "total_elements": 7,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "DESC",
      "property": "update_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "number_of_elements": 1,
  "size": 25,
  "number": 0
}

Some fields within an object using the GET method can be filtered using query parameters. Filtering is especially useful for calls that return many different fields.

The basic construct for a filtering query is as follows:

/<endpoint>?<query_parameter>=<query>

Different parameters in an endpoint can be combined using an & operator.

/<endpoint>?<query_parameter_1>=<query_1>&<query_parameter_2>=<query_2>

Metadata

Many objects support optional metadata fields, as denoted in the documentation. Metadata is intended to allow developers to extend our API and store custom information that is relevant to their business. Some examples may include:

Metadata may consist of any key-value pair you define such as “Age”: “35” or “City”: “New York”

All metadata that is entered will be returned in the JSON and may consist of up to 255 alphanumeric, string, integer, and boolean characters for each key and each value.

Event Handlers

Molecule APIs monitor the blockchain for changes to your smart contracts.

Some examples of events you may want to monitor include:

In Ethereum, when a transaction is mined, smart contracts can emit events and write logs to the blockchain that the other parts of an app can then process. Molecule APIs use three main smart contracts; GlobalWhitelist, SecurityToken, and OfferingSettings, and all of them are designed to emit an event for specific methods.

Whitelist Admin Added

An owner’s wallet before token deployment

{
  "token_whitelists": []
}

An owner’s wallet after token deployment

{
  "token_whitelists": [
    {
      "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
      "role": "owner",
      "sell_restriction_date": null,
      "buy_restriction_date": null
    }
  ]
}

This event type is emitted when a token or crowdsale contract is deployed on the blockchain. It indicates that the deployment was successful, and that the owner of the wallet is added to token’s GlobalWhitelist as an admin. Upon hearing this event, Molecule Event Handlers will modify the owner’s wallet, and add the token_id to wallet’s token_whitelist array. This array will be later used to track which wallet is in which token’s whitelist.

Whitelisted Added

An investor’s wallet before whitelisting

{
  "token_whitelists": []
}

An investors’s wallet after whitelisting

{
  "token_whitelists": [
    {
      "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
      "role": null,
      "sell_restriction_date": null,
      "buy_restriction_date": null
    }
  ]
}

This event type is emitted when a wallet is whitelisted for a particular SecurityToken. It indicates that the wallet passed all Know Your Customer checks successfully, and been added to a token’s whitelist. When a wallet gets whitelisted for a token, it will be allowed to purchase, store, send, and receive that SecurityToken. Upon hearing this event, Molecule Event Handlers will modify the investor’s wallet, and add the token_id to wallet’s token_whitelist array. This array will be later used to track which wallet is in which token’s whitelist.

Transfer

This event type is emitted when a SecurityToken or currency transfer operation occurs. It indicates that the requested transfer was successful. Upon hearing these events, Molecule Event Handlers will create new entries in one of the following tables.

Token Balance

Token Balance example

{
  "id": "4d421d3d-9c18-4486-b98a-f66c5040dc3b",
  "balance": 1400000,
  "wallet_id": "2b96275a-8051-455a-9d37-2dfcfe282bf6",
  "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
  "create_date": "2019-09-12T22:04:12.000Z",
  "update_date": "2019-09-12T22:04:12.000Z"
}

The transfer event of the following methods will contain information about a user wallet and a SecurityToken, and a new Token Balance entry will be created to record it.

  1. token/deploy: After getting deployed on the blockchain, all newly minted SecurityTokens will be transferred to the owner’s wallet.
  2. crowdsale/fund: After sending some of its tokens to fund the crowdsale, the balance of the owner’s wallet will decrease.
  3. crowdsale/purchase: After purchasing some tokens from the crowdsale, the balance of the investor’s wallet will increase.
  4. token_transfer: After transferring tokens, both receiver and sender wallet’s token balance will change.

Token Supply

Token Supply example

{
  "id": "cb239351-3ad2-47ae-be2f-29f87a6bba4c",
  "available_supply": 3525000,
  "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
  "create_date": "2019-09-12T22:04:12.000Z",
  "update_date": "2019-09-12T22:04:12.000Z"
}

The transfer event of the following methods will contain information about a SecurityToken and its Crowdsale contract, and a new Token Supply entry will be created to record it.

  1. crowdsale/fund: After receiving some tokens from the owner, the supply of the crowdsale will increase.
  2. crowdsale/purchase: After sending some tokens to the investor, the supply of the crowdsale will decrease.

Currency Balance

Currency Balance example

{
  "id": "0aef13fc-b0b0-4daf-8c02-3327a7575958",
  "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
  "balance": 13.73,
  "create_date": "2019-10-10T16:06:18.103Z",
  "update_date": "2019-10-10T16:06:18.103Z"
}

The transfer event of the following methods will contain information about a user wallet and a crypto currency (such as Ether), and a new Currency Balance entry will be created to record it.

  1. currency_transfer: After transferring currencies, both receiver and sender wallet’s currency balance will change.
  2. crowdsale/purchase: After buying some tokens from the crowdsale contract, the investors currency balance will decrease and owners currency balance will increase.

Token and Currency Transfer Receipts

Token Transfer example

{
  "id": "d5e4c992-46b3-4e14-86b5-7817dc54982c",
  "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  "amount": "10000",
  "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
  "transaction_hash": "0xca7fae11fdd2280d97c94543aafadcbb6eb20ff9d7e1cc6dbe6e81f071c5a3ff",
  "create_date": "2019-10-03T17:40:22.431Z",
  "update_date": "2019-10-03T17:40:22.431Z"
}

Currency Transfer example

{
  "id": "43646089-6a2b-4d9f-81c8-bdfbeac4461c",
  "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  "amount": "10",
  "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
  "transaction_hash": "0xf8674b1296c237752e9632798c15dd0a7011cdb97e055b6ee769476a43c47320",
  "create_date": "2019-10-10T16:01:58.005Z",
  "update_date": "2019-10-10T16:01:58.005Z"
}

The transfer event of the following methods will contain information about two user wallets and a SecurityToken, or a currency. A new Token Transfer or Currency Transfer entry will be created to record the receipt.

  1. token_transfer: Two wallets transfer SecurityTokens in between.
  2. currency_transfer: Two wallets transfer Currency in between.

Token Circulating Supply

The circulating_supply of a token is calculated by subtracting the owners (issuer) token balance from the total supply of a token. If the token owner is involved in a transaction, the event handlers will update that tokens circulating_supply automatically.

Webhooks

Since transactions in Ethereum take anywhere between 5 seconds to a couple of minutes to be processed, Molecule offers webhooks to notify its users about changes that have occurred.

Depending on your molecule_service settings, Molecule will send a payload to the url of your choice.

Webhook Management

You can use the webhook endpoint to manage your active webhook, and what services you want to get notified about.

Field Type Description
id UUID The id of the webhook
url string The url you want to receive the payloads to
molecule_service array The array of molecule services for a webhook to notify
is_active boolean Indicates if this webhook is active

The list of all available molecule services are as follows:

Molecule Service
whitelist_admin
whitelisted
token_transfer
token_balance
token_supply_balance
currency_transfer
currency_balance
transaction

List all webhooks

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/molecule/v1/webhook"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_webhooks()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_webhooks: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
  "content": [
    {
      "id": "0bd304f4-9996-4676-9c59-dedf486a7f72",
      "url": "https://www.hydrogenplatform.com",
      "is_active": true,
      "molecule_service": [
        "whitelist_admin",
        "whitelisted",
        "token_transfer",
        "token_balance",
        "token_supply_balance",
        "currency_transfer",
        "currency_balance",
        "transaction"
      ],
      "create_date": "2019-11-14T16:34:49.262Z",
      "update_date": "2019-11-14T18:52:44.950Z"
    },
    {
      "id": "1f6f3345-737a-400f-b5b8-bdb15382f803",
      "url": "https://www.hydrogenplatform.com",
      "is_active": false,
      "molecule_service": ["transaction"],
      "create_date": "2019-11-14T17:20:21.076Z",
      "update_date": "2019-11-14T18:52:44.941Z"
    }
  ],
  "total_pages": 1,
  "total_elements": 2,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "ASC",
      "property": "create_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": true,
      "descending": false
    }
  ],
  "number_of_elements": 2,
  "size": 25,
  "number": 0
}

Get information for all webhooks defined for your firm.

HTTP REQUEST

GET /webhook

Create a webhook

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://www.hydrogenplatform.com",
        "molecule_service": ["transaction"]
    }' "https://api.hydrogenplatform.com/molecule/v1/webhook"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.WebhookCreatePayload(
    url="https://www.hydrogenplatform.com",
    molecule_service=["transaction"]
)

try:
    api_response = api_instance.post_webhook(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_webhook: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.WebhookCreatePayload();
payload.url = "https://www.hydrogenplatform.com";
payload.molecule_service = ["transaction"];

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

Example Response

{
  "id": "1f6f3345-737a-400f-b5b8-bdb15382f803",
  "url": "https://www.hydrogenplatform.com",
  "is_active": true,
  "molecule_service": ["transaction"],
  "update_date": "2019-11-14T17:20:21.076Z",
  "create_date": "2019-11-14T17:20:21.076Z"
}

One active webhook is allowed at all times. If there already is an active webhook at the time of creating a new active webhook, the old webhook will be deactivated.

HTTP REQUEST

POST /webhook

ARGUMENTS

Parameter Type Required Description
url string required The url you want to receive the payloads to. Only http:// or https:// urls allowed
molecule_service array required The array of molecule services for a webhook to notify
is_active boolean optional Indicates if this webhook is active. Defaults to true

Retrieve a webhook

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/molecule/v1/webhook/1f6f3345-737a-400f-b5b8-bdb15382f803"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
webhook_id = '1f6f3345-737a-400f-b5b8-bdb15382f803'

try:
    api_response = api_instance.get_webhook(webhook_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_webhook: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var webhookId = "1f6f3345-737a-400f-b5b8-bdb15382f803";

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

Example Response

{
  "id": "1f6f3345-737a-400f-b5b8-bdb15382f803",
  "url": "https://www.hydrogenplatform.com",
  "is_active": true,
  "molecule_service": ["transaction"],
  "create_date": "2019-11-14T17:20:21.076Z",
  "update_date": "2019-11-14T17:20:21.076Z"
}

Retrieve the information for a specific webhook. The webhook_id must be provided.

The endpoint returns the webhook_id and the details for the webhook specified.

HTTP REQUEST

GET /webhook/{webhook_id}

Update a webhook

Example Request

curl -X PUT -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
-H "Content-Type: application/json" \
-d '{
        "is_active": false
    }' "https://api.hydrogenplatform.com/molecule/v1/webhook/1f6f3345-737a-400f-b5b8-bdb15382f803"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

webhook_id = '1f6f3345-737a-400f-b5b8-bdb15382f803'

payload = molecule_api.WebhookUpdatePayload(
    is_active=False
)

try:
    api_response = api_instance.update_webhook(webhook_id, payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->update_webhook: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var webhookId = "1f6f3345-737a-400f-b5b8-bdb15382f803";

var payload = new molecule_api.WebhookUpdatePayload();
payload.is_active = false;

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

Example Response

{
  "id": "1f6f3345-737a-400f-b5b8-bdb15382f803",
  "url": "https://www.hydrogenplatform.com",
  "is_active": false,
  "molecule_service": ["transaction"],
  "create_date": "2019-11-14T17:20:21.076Z",
  "update_date": "2019-11-14T18:52:44.941Z"
}

Update a webhook for your firm. The webhook_id must be provided. To obtain the appropriate webhook_id, use the GET /webhook endpoint to view all of the webhooks for your firm and their current information.

If there is an active webhook, and if you are trying to activate another one, the current webhook will be deactivated.

HTTP REQUEST

PUT /webhook/{webhook_id}

Delete a webhook

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/molecule/v1/webhook/1f6f3345-737a-400f-b5b8-bdb15382f803"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
webhook_id = '1f6f3345-737a-400f-b5b8-bdb15382f803'

try:
    api_instance.delete_webhook(webhook_id)
except ApiException as e:
    print("Exception when calling MoleculeApi->delete_webhook: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var webhookId = "1f6f3345-737a-400f-b5b8-bdb15382f803";

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log("API called successfully.");
  }
};
apiInstance.deleteWebhook(webhookId, callback);

Response (204 No Content)

Permanently delete a webhook for your firm. The webhook_id must be provided. To obtain the appropriate webhook_id, use the GET /webhook endpoint to view all of the webhooks for your firm. This deletes the webhook_id and the details for the webhook record.

HTTP REQUEST

DELETE /webhook/{webhook_id}

Molecule Services

whitelist_admin

A whitelist_admin webhook payload

{
  "token_id": "ad79d3fa-5a13-4af3-b226-67f296c7cb9d",
  "wallet_id": "f25886ab-09f3-478d-8310-f7c0f319f377",
  "molecule_service": "whitelist_admin",
  "webhook_type": "EVENTS"
}

Add molecule_service: [ "whitelist_admin" ] to your active webhook.

The webhook will send a payload to the url you specified after a successful POST token/deploy request to notify you about the successful deployment of a SecurityToken and addition of the token owner (issuer) as the whitelist admin.

whitelisted

A whitelisted webhook payload

{
  "molecule_service": "whitelisted",
  "transaction_id": "8e478f86-6237-404c-8c41-ec4bdb05bc41",
  "token_id": "41cf2b62-8a56-4af4-a88d-80cb5a6f9f17",
  "wallet_id": "1818b14b-147c-4806-a02f-7dcd72f73919",
  "webhook_type": "EVENTS"
}

Add molecule_service: [ "whitelisted" ] to your active webhook.

The webhook will send a payload to the url you specified after a successful POST token/whitelist request to notify you about the successful whitelisting of a wallet for a particular SecurityToken.

token_transfer

A token_transfer webhook payload

{
  "molecule_service": "token_transfer",
  "transaction_id": "72a8db68-c484-464c-aa8f-cd90b9fa2796",
  "sender_wallet_id": "f25886ab-09f3-478d-8310-f7c0f319f377",
  "receiver_wallet_id": "1818b14b-147c-4806-a02f-7dcd72f73919",
  "token_id": "41cf2b62-8a56-4af4-a88d-80cb5a6f9f17",
  "amount": 5,
  "webhook_type": "EVENTS"
}

Add molecule_service: [ "token_transfer" ] to your active webhook.

The webhook will send a payload to the url you specified after below successful requests to notify you about:

token_balance

A token_balance webhook payload

{
  "token_id": "41cf2b62-8a56-4af4-a88d-80cb5a6f9f17",
  "wallet_id": "1818b14b-147c-4806-a02f-7dcd72f73919",
  "balance": "5021",
  "molecule_service": "token_balance",
  "webhook_type": "EVENTS"
}

Add molecule_service: [ "token_balance" ] to your active webhook.

The webhook will send a payload to the url you specified after below successful requests to notify you about:

token_supply_balance

A token_supply_balance webhook payload

{
  "token_id": "41cf2b62-8a56-4af4-a88d-80cb5a6f9f17",
  "balance": "250000",
  "molecule_service": "token_supply_balance",
  "webhook_type": "EVENTS"
}

Add molecule_service: [ "token_supply_balance" ] to your active webhook.

The webhook will send a payload to the url you specified after below successful requests to notify you about:

currency_transfer

A currency_transfer webhook payload

{
  "molecule_service": "currency_transfer",
  "transaction_id": "df5c64af-abb9-43f8-9111-afda2b1ea7ca",
  "sender_wallet_id": "f25886ab-09f3-478d-8310-f7c0f319f377",
  "receiver_wallet_id": "1818b14b-147c-4806-a02f-7dcd72f73919",
  "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
  "amount": 1.25,
  "webhook_type": "EVENTS"
}

Add molecule_service: [ "currency_transfer" ] to your active webhook.

The webhook will send a payload to the url you specified after a successful POST currency_transfer request to notify you about the successful transfer of the currency from one wallet to another.

currency_balance

A currency_balance webhook payload

{
  "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
  "wallet_id": "f25886ab-09f3-478d-8310-f7c0f319f377",
  "balance": "0.475991841710001302",
  "molecule_service": "currency_balance",
  "webhook_type": "EVENTS"
}

Add molecule_service: [ "currency_balance" ] to your active webhook.

The webhook will send a payload to the url you specified after below successful requests to notify you about:

transaction

A transaction webhook payload

{
  "molecule_service": "transaction",
  "transaction_id": "7e3b9a3f-3070-4885-83e5-705972862840",
  "token_id": "ad79d3fa-5a13-4af3-b226-67f296c7cb9d",
  "webhook_type": "EVENTS"
}

Add molecule_service: [ "transaction" ] to your active webhook.

The webhook will send a payload to the url you specified after below successful requests to notify you about:

Identity

Wallet

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 SecurityTokens and crypto currencies.

Personally identifiable data included but not limited to name, surname, and email of a user will be stored under Nucleus Client and will be associated with a wallet using the nucleus_client_id field.

Field Type Description
id UUID The id for the wallet
wallet_key_id UUID The id of the wallet key generated for the wallet
name string Name of the wallet
type string Type of the wallet. Can be individual, business, trust, or contract
clients array List of nucleus clients associated with the wallet and their association type
      nucleus_client_id UUID The id of a nucleus client associated with the wallet
      client_wallet_association_type string The role of the client as it relates to the wallet defined by your firm. Can be joint, owner, trustee, viewer, admin
      is_primary boolean Determines if the wallet is the primary wallet of the client. Defaults to true. One primary wallet is allowed per client
token_whitelists array List of tokens where the wallet is whitelisted
      token_id UUID The id of the token
      role string The role of the wallet over the token such as owner, investor, advisor etc.
      sell_restriction_date timestamp The date when resale restrictions should be lifted for this wallet
      buy_restriction_date timestamp The date when the buy restrictions should be lifted for this wallet
is_active boolean Indicates if this wallet is active. Defaults to true which indicates it is active and available to be used
metadata map Custom information associated with the wallet in the format key:value
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all wallets

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/molecule/v1/wallet"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_wallets()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_wallets: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
  "content": [
    {
      "id": "eb32c593-a452-41ff-8c5e-807d106c6486",
      "wallet_key_id": "94707d27-7aae-4cc8-b925-afe519c00537",
      "name": "Armando Withaker",
      "type": "individual",
      "is_active": true,
      "secondary_id": null,
      "create_date": "2019-09-12T21:42:33.000Z",
      "update_date": "2019-09-12T21:43:23.000Z",
      "clients": [
        {
          "nucleus_client_id": "afefc951-a53b-44c7-907b-2b26ccf589e3",
          "client_wallet_association_type": "owner",
          "is_primary": true
        }
      ],
      "metadata": {},
      "token_whitelists": [
        {
          "token_id": "1b8cc79d-b409-4d35-94e9-a902ab1683e6",
          "role": "owner",
          "sell_restriction_date": null,
          "buy_restriction_date": null
        },
        {
          "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
          "role": "investor",
          "sell_restriction_date": null,
          "buy_restriction_date": null
        }
      ]
    },
    {
      "id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "wallet_key_id": "a82a5ee3-55ba-405a-b202-4bf0402614d3",
      "name": "Jong LLC",
      "type": "business",
      "is_active": true,
      "secondary_id": null,
      "create_date": "2019-09-12T21:38:21.000Z",
      "update_date": "2019-09-12T21:39:56.000Z",
      "clients": [
        {
          "nucleus_client_id": "dd707c48-599c-4edd-8055-04682e583483",
          "client_wallet_association_type": "admin",
          "is_primary": true
        },
        {
          "nucleus_client_id": "b5f3abe9-bea2-4b31-9416-1080041efac2",
          "client_wallet_association_type": "owner",
          "is_primary": true
        }
      ],
      "metadata": {},
      "token_whitelists": [
        {
          "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
          "role": "owner",
          "sell_restriction_date": null,
          "buy_restriction_date": null
        }
      ]
    },
    {
      "id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
      "wallet_key_id": "00c00c35-8a6c-47a7-a15e-ef297475d212",
      "name": "Amanda Kirby",
      "type": "individual",
      "is_active": true,
      "secondary_id": null,
      "create_date": "2019-09-12T21:38:34.000Z",
      "update_date": "2019-09-12T21:39:21.000Z",
      "clients": [
        {
          "nucleus_client_id": "23bb0389-aa37-4be5-9dc5-07f21a8f4d32",
          "client_wallet_association_type": "owner",
          "is_primary": true
        }
      ],
      "metadata": {},
      "token_whitelists": [
        {
          "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
          "role": "investor",
          "sell_restriction_date": null,
          "buy_restriction_date": null
        },
        {
          "token_id": "1b8cc79d-b409-4d35-94e9-a902ab1683e6",
          "role": "investor",
          "sell_restriction_date": null,
          "buy_restriction_date": null
        }
      ]
    }
  ],
  "total_pages": 1,
  "total_elements": 3,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "DESC",
      "property": "update_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "number_of_elements": 3,
  "size": 25,
  "number": 0
}

Get information for all wallets defined for your firm. Optionally, you can pass nucleus_client_id and is_primary as query parameters to retrieve wallets of specific clients.

HTTP REQUEST

GET /wallet

FILTERS

Parameter Type Description
nucleus_client_id UUID Retrieve all the wallets belonging to a Nucleus Client
is_primary boolean Retrieve primary wallets

Create a wallet

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
  -H "Content-Type: application/json" \
  -d '{
          "name": "Jong LLC",
          "type": "business",
          "clients": [
              {
                  "nucleus_client_id": "2b5a865c-9932-45b9-8a28-81b214fc187f",
                  "client_wallet_association_type": "owner"
              },
              {
                  "nucleus_client_id": "70b354f8-4eb6-4d65-8d00-4ee690dd99e4",
                  "client_wallet_association_type": "admin"
              }
          ]
      }' "https://api.hydrogenplatform.com/molecule/v1/wallet"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

client_1 = molecule_api.WalletCreateClient(
    nucleus_client_id="2b5a865c-9932-45b9-8a28-81b214fc187f",
    client_wallet_association_type="owner"
)

client_2 = molecule_api.WalletCreateClient(
    nucleus_client_id="70b354f8-4eb6-4d65-8d00-4ee690dd99e4",
    client_wallet_association_type="admin"
)

payload = molecule_api.WalletCreatePayload(
    name="Jong LLC",
    type="business",
    clients=[client_1,client_2]
)

try:
    api_response = api_instance.post_wallet(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_wallet: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var client1 = new molecule_api.WalletCreateClient();
client1.nucleus_client_id = "2b5a865c-9932-45b9-8a28-81b214fc187f";
client1.client_wallet_association_type = "owner";

var client2 = new molecule_api.WalletCreateClient();
client2.nucleus_client_id = "70b354f8-4eb6-4d65-8d00-4ee690dd99e4";
client2.client_wallet_association_type = "admin";

var payload = new molecule_api.WalletCreatePayload();
payload.name = "Jong LLC";
payload.type = "business";
payload.clients = [client1, client2];

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

Example Response

{
  "id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "is_active": true,
  "name": "Jong LLC",
  "type": "business",
  "clients": [
    {
      "nucleus_client_id": "b5f3abe9-bea2-4b31-9416-1080041efac2",
      "client_wallet_association_type": "owner",
      "is_primary": true
    },
    {
      "nucleus_client_id": "dd707c48-599c-4edd-8055-04682e583483",
      "client_wallet_association_type": "admin",
      "is_primary": true
    }
  ],
  "metadata": {},
  "update_date": "2019-09-12T19:47:38.972Z",
  "create_date": "2019-09-12T19:47:38.972Z"
}

Create a wallet under your firm. name, type, and clients of the wallet must be provided. Every wallet requires an owner client to be associated. The endpoint returns a unique wallet_id that is used to manage the specific wallet and referenced in other endpoints.

If there already is a primary wallet for a client at the time of creating a new primary wallet, the old wallet will be deprioritized.

Use POST /wallet_key or POST /wallet_key/generator to create and assign a wallet_key_id to a wallet.

HTTP REQUEST

POST /wallet

SAMPLE WORKFLOW

Identity

ARGUMENTS

Parameter Type Required Description
name string required Name of the wallet
type string required Type of the wallet. Can be individual, business, trust, or contract
clients array required List of nucleus clients associated with the wallet and their association type
      nucleus_client_id UUID required The id of a nucleus client associated with the wallet
      client_wallet_association_type string required The role of the client as it relates to the account defined by your firm. Can be joint, owner, trustee, viewer, admin
      is_primary boolean optional Determines if the wallet is the primary wallet of the client. Defaults to true. One primary wallet is allowed per client
token_whitelists array optional List of tokens where the wallet is whitelisted
      token_id UUID required The id of the token
      role string optional The role of the wallet over the token such as issuer, investor, advisor etc.
      sell_restriction_date timestamp optional The date when resale restrictions should be lifted for this wallet
      buy_restriction_date timestamp optional The date when the buy restrictions should be lifted for this wallet
is_active boolean optional Indicates if this wallet is active. Defaults to true which indicates it is active and available to be used
metadata map optional Custom information associated with the wallet in the format key:value
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a wallet

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/molecule/v1/wallet/e1711964-8e98-4a33-a4bf-ce9775b4c3b6"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
wallet_id = 'e1711964-8e98-4a33-a4bf-ce9775b4c3b6'

try:
    api_response = api_instance.get_wallet(wallet_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_wallet: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var walletId = "e1711964-8e98-4a33-a4bf-ce9775b4c3b6";

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

Example Response

{
  "id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "wallet_key_id": null,
  "name": "Jong LLC",
  "type": "business",
  "is_active": true,
  "secondary_id": null,
  "create_date": "2019-09-12T19:47:38.000Z",
  "update_date": "2019-09-12T19:47:38.000Z",
  "clients": [
    {
      "nucleus_client_id": "b5f3abe9-bea2-4b31-9416-1080041efac2",
      "client_wallet_association_type": "owner",
      "is_primary": true
    },
    {
      "nucleus_client_id": "dd707c48-599c-4edd-8055-04682e583483",
      "client_wallet_association_type": "admin",
      "is_primary": true
    }
  ],
  "metadata": {},
  "token_whitelists": []
}

Retrieve the information for a specific wallet. The unique wallet_id must be provided. The endpoint returns the wallet_id and details for the wallet specified.

HTTP REQUEST

GET /wallet/{wallet_id}

Update a wallet

Example Request

curl -X PUT \ -H 'Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900' \
  -H 'Content-Type: application/json' \
  -d '{
         "is_active": false
      }' "https://api.hydrogenplatform.com/molecule/v1/wallet/e1711964-8e98-4a33-a4bf-ce9775b4c3b6"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
wallet_id = 'e1711964-8e98-4a33-a4bf-ce9775b4c3b6'
payload = molecule_api.WalletUpdatePayload(
    is_active=False,
)

try:
    api_response = api_instance.update_wallet(wallet_id, payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->update_wallet: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var walletId = "e1711964-8e98-4a33-a4bf-ce9775b4c3b6";

var payload = new molecule_api.WalletUpdatePayload();
payload.is_active = false;

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

Example Response

{
  "id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "wallet_key_id": null,
  "name": "Jong LLC",
  "type": "business",
  "is_active": false,
  "secondary_id": null,
  "create_date": "2019-09-12T19:47:38.000Z",
  "update_date": "2019-09-12T19:50:01.281Z",
  "clients": [
    {
      "nucleus_client_id": "b5f3abe9-bea2-4b31-9416-1080041efac2",
      "client_wallet_association_type": "owner",
      "is_primary": true
    },
    {
      "nucleus_client_id": "dd707c48-599c-4edd-8055-04682e583483",
      "client_wallet_association_type": "admin",
      "is_primary": true
    }
  ],
  "metadata": {},
  "token_whitelists": []
}

Update the information for a wallet. The unique wallet_id must be provided. To obtain the appropriate wallet_id, use the GET /wallet endpoint to view all wallets defined for your firm and their current information. The details to be updated must also be provided.

If there is a primary wallet for a client, and if you are trying to make another wallet the primary wallet, the current primary wallet will be deprioritized.

HTTP REQUEST

PUT /wallet/{wallet_id}

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.

If your firm has a KMS integration

If your firm has a KMS integration, the key_id, the key_server, and the address will be stored under the wallet key. Using this key_id and key_server combination, Molecule will retrieve a wallet’s securely held private key from the KMS and sign transactions.

If your firm does not have a KMS integration

If your firm does not have a KMS integration enabled through Hydrogen, the private_key and the address of a wallet will be stored directly under the wallet key.

Field Type Description
id UUID The id for the wallet key
key_id string The id of the associated key within the Key Server
key_server string Name of Key Server in use by the client
address string The public address of the associated key
private_key string The private key of the associated key

List all wallet keys

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/molecule/v1/wallet_key"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_wallet_keys()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_wallet_keys: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
    "content": [
        {
            "id": "a82a5ee3-55ba-405a-b202-4bf0402614d3",
            "key_id": "edee6ed820bf487e886253179278bc51",
            "key_server": "azure",
            "address": "0x7b51ada4de0e188bf3f2f42b54266eee495353c5",
            "private_key": null,
            "create_date": "2019-09-12T19:55:31.000Z",
            "update_date": "2019-09-12T19:55:31.000Z"
        },
        {
            "id": "00c00c35-8a6c-47a7-a15e-ef297475d212",
            "key_id": "a61c38a397e6474894fb9bfec2eb7bed",
            "key_server": "azure",
            "address": "0xdc6e90ca52e92f16437e6b5ae9aa76da4f964745",
            "private_key": null,
            "create_date": "2019-09-12T20:08:33.000Z",
            "update_date": "2019-09-12T20:08:33.000Z"
        },
        {
            "id": "94707d27-7aae-4cc8-b925-afe519c00537",
            "key_id": "f2eb062c446f48d0be8d07e796583935",
            "key_server": "azure",
            "address": "0xca94e93d1e99cd7756f2f243af717e7e067f5b8c",
            "private_key": null,
            "create_date": "2019-09-12T20:09:19.000Z",
            "update_date": "2019-09-12T20:09:19.000Z"
        }
    ],
    "total_pages": 1,
    "total_elements": 3,
    "last": true,
    "first": true,
    "sort": [
        {
            "direction": "ASC",
            "property": "create_date",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": true,
            "descending": false
        }
    ],
    "number_of_elements": 3,
    "size": 25,
    "number": 0
}

Get all wallet keys associated with wallets defined for your firm.

HTTP REQUEST

GET /wallet_key

Generate and store a key

Example Request (with KMS)

curl -X POST \
  https://api.hydrogenplatform.com/molecule/v1/wallet_key/generator \
  -H 'Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900' \
  -H 'Content-Type: application/json' \
  -d '{
           "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6"
      }'
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.WalletKeyGeneratorPayload(
    wallet_id="e1711964-8e98-4a33-a4bf-ce9775b4c3b6"
)

try:
    api_response = api_instance.post_wallet_key_generator(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_wallet_key_generator: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.WalletKeyGeneratorPayload();
payload.wallet_id="e1711964-8e98-4a33-a4bf-ce9775b4c3b6"

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

Example Response (If your firm has a KMS integration enabled through Hydrogen)

{
    "id": "a82a5ee3-55ba-405a-b202-4bf0402614d3",
    "key_id": "edee6ed820bf487e886253179278bc51",
    "key_server": "azure",
    "address": "0x7b51ada4de0e188bf3f2f42b54266eee495353c5",
    "update_date": "2019-09-12T19:55:31.049Z",
    "create_date": "2019-09-12T19:55:31.049Z"
}

Example Response - (If your firm does not have a KMS integration enabled through Hydrogen)

{
    "id": "10a78f43-4b78-4a4f-8f1a-4569d8c1e72d",
    "address": "0xbEd07049af528cA40889661d44C8a9b63875677F",
    "private_key": "0x44a21e18b2b50cd2ae0b15d65830ef3b552ebeddaf7260e29851336a60be8f29",
    "update_date": "2019-09-12T20:02:19.805Z",
    "create_date": "2019-09-12T20:02:19.805Z"
}

Use this endpoint if your firm chooses to generate private and public key pairs for its clients.

If your firm has Microsoft Azure as its KMS provider enabled through Hydrogen’s integration service, the private/public key pair will be generated and stored in the Azure server.

If your firm uses another KMS provider, or does not use one at all, the private/public key will be generated by Molecule and stored in the KMS or in Molecule.

See Generate and Assign a Wallet Key for an example workflow.

HTTP REQUEST

POST /wallet_key/generator

SAMPLE WORKFLOW

Identity

ARGUMENTS

Parameter Type Required Description
wallet_id UUID required The id of the wallet you are generating the keys for

Store an existing key

Example Request

curl -X POST \
  https://api.hydrogenplatform.com/molecule/v1/wallet_key \
  -H 'Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900' \
  -H 'Content-Type: application/json' \
  -d '{
        "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
        "private_key": "0xb45c13802c694c01acb00ce7a6891c85e09ad78999dd2a54bab0a07e26c20190",
        "address": "0x8C0A68F8159F40652319Cf90c0BDE0F7d55763bB"
      }'
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.WalletKeyCreatePayload(
    wallet_id="e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  private_key="0xb45c13802c694c01acb00ce7a6891c85e09ad78999dd2a54bab0a07e26c20190",
  address="0x8C0A68F8159F40652319Cf90c0BDE0F7d55763bB"
)

try:
    api_response = api_instance.post_wallet_key(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_wallet_key: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.WalletKeyCreatePayload();
payload.wallet_id="e1711964-8e98-4a33-a4bf-ce9775b4c3b6";
payload.private_key="0xb45c13802c694c01acb00ce7a6891c85e09ad78999dd2a54bab0a07e26c20190";
payload.address="0x8C0A68F8159F40652319Cf90c0BDE0F7d55763bB";

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

Example Response

{
    "id": "be70e33f-86d6-488f-8dc4-9a2a1bdea42e",
    "address": "0x8C0A68F8159F40652319Cf90c0BDE0F7d55763bB",
    "private_key": "0xb45c13802c694c01acb00ce7a6891c85e09ad78999dd2a54bab0a07e26c20190",
    "update_date": "2019-09-12T20:02:21.723Z",
    "create_date": "2019-09-12T20:02:21.723Z"
}

Use this endpoint if your firm chooses to store existing private and public address pairs for its clients that haven’t been generated through Hydrogen.

HTTP REQUEST

POST /wallet_key

ARGUMENTS

Parameter Type Required Description
wallet_id UUID required UUID of the wallet you are generating the keys for
address string required Public address of the wallet you are storing
private_key array required Private key of the wallet you are storing

Retrieve a wallet key

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/molecule/v1/wallet_key/a82a5ee3-55ba-405a-b202-4bf0402614d3"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
wallet_key_id = 'a82a5ee3-55ba-405a-b202-4bf0402614d3'

try:
    api_response = api_instance.get_wallet_key(wallet_key_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_wallet_key: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var walletKeyId = "a82a5ee3-55ba-405a-b202-4bf0402614d3";

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

Example Response

{
    "id": "a82a5ee3-55ba-405a-b202-4bf0402614d3",
    "key_id": "edee6ed820bf487e886253179278bc51",
    "key_server": "azure",
    "address": "0x7b51ada4de0e188bf3f2f42b54266eee495353c5",
    "private_key": null,
    "create_date": "2019-09-12T19:55:31.000Z",
    "update_date": "2019-09-12T19:55:31.000Z"
}

Get a specific wallet key. The wallet_key_id must be provided.

HTTP REQUEST

GET /wallet_key/{wallet_key_id}

Wallet Permission

The Wallet Permission endpoints vary slightly from other Molecule endpoints as they are not used to manage specific objects, but rather to manage the permission type of a client to a wallet. Initial permissions will be assigned to clients automatically by the time of creating the wallet, depending on the client_wallet_association_type assigned to the nucleus_client_id;

If the association type is set to owner, trustee, joint, or admin, the nucleus_client_id will be assigned FULL_AUTHORITY

If the association type is set to viewer, the nucleus_client_id will be assigned INQUIRY_ACCESS

Field Type Description
wallet_id UUID The id of the wallet being granted permissions
clients array List of nucleus clients mapped to the wallet and their permission type
      nucleus_client_id UUID The id of the nucleus client being granted permissions to the account. Must also be included in the clients.client_id field of the wallet
      permission_type string The permission type for the client. Available values are INQUIRY_ACCESS, LIMITED_AUTHORITY, FULL_AUTHORITY, and POWER_OF_ATTORNEY. Please view the Permission Types resource for more information on each authority.

List all wallet permissions

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/molecule/v1/wallet_permission"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_wallet_permissions()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_wallet_permissions: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
  "content": [
    {
      "wallet_id": "b85410d1-d0d6-4d5c-80c1-eca2b97f22ad",
      "clients": [
        {
          "nucleus_client_id": "530d7687-1f25-42aa-96e0-86dbd61e3efe",
          "permission_type": "FULL_AUTHORITY",
          "client_wallet_association_type": "owner",
          "is_primary": true
        }
      ]
    },
    {
      "wallet_id": "b89ff2af-2fa9-4579-9538-809416e15467",
      "clients": [
        {
          "nucleus_client_id": "6164fcc1-32c9-4fd1-952b-172695d8d4ec",
          "permission_type": "INQUIRY_ACCESS",
          "client_wallet_association_type": "viewer",
          "is_primary": false
        },
        {
          "nucleus_client_id": "a587554c-7832-4841-af5a-3932335156ef",
          "permission_type": "FULL_AUTHORITY",
          "client_wallet_association_type": "owner",
          "is_primary": false
        }
      ]
    },
    {
      "wallet_id": "fe2db143-ce1e-41bb-902c-65f3d819e46e",
      "clients": [
        {
          "nucleus_client_id": "a587554c-7832-4841-af5a-3932335156ef",
          "permission_type": "FULL_AUTHORITY",
          "client_wallet_association_type": "owner",
          "is_primary": true
        },
        {
          "nucleus_client_id": "6164fcc1-32c9-4fd1-952b-172695d8d4ec",
          "permission_type": "LIMITED_AUTHORITY",
          "client_wallet_association_type": "admin",
          "is_primary": false
        }
      ]
    }
  ],
  "total_pages": 1,
  "total_elements": 3,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "ASC",
      "property": "create_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": true,
      "descending": false
    }
  ],
  "number_of_elements": 3,
  "size": 25,
  "number": 0
}

Get the clients and permission types for all wallets defined for your firm. Account permissions control the actions that a client can take on a wallet.

HTTP REQUEST

GET /wallet_permission

Retrieve a wallet’s permissions

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/molecule/v1/wallet_permission/b89ff2af-2fa9-4579-9538-809416e15467"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
wallet_id = 'b89ff2af-2fa9-4579-9538-809416e15467'

try:
    api_response = api_instance.get_wallet_permission(wallet_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_wallet_permission: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var walletId = "b89ff2af-2fa9-4579-9538-809416e15467";

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

Example Response

{
  "wallet_id": "b89ff2af-2fa9-4579-9538-809416e15467",
  "clients": [
    {
      "nucleus_client_id": "6164fcc1-32c9-4fd1-952b-172695d8d4ec",
      "permission_type": "INQUIRY_ACCESS",
      "client_wallet_association_type": "viewer",
      "is_primary": false
    },
    {
      "nucleus_client_id": "a587554c-7832-4841-af5a-3932335156ef",
      "permission_type": "FULL_AUTHORITY",
      "client_wallet_association_type": "owner",
      "is_primary": false
    }
  ]
}

Retrieve all the clients and their permission type for a specific account.

HTTP REQUEST

GET /wallet_permission/{wallet_id}

Update a wallet’s permissions

Example Request

curl -X PUT \ -H 'Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900' \
  -H 'Content-Type: application/json' \
  -d '{
    "nucleus_client_id"="6164fcc1-32c9-4fd1-952b-172695d8d4ec",
  "permission_type"="LIMITED_AUTHORITY"
}' "https://api.hydrogenplatform.com/molecule/v1/wallet_permission/fe2db143-ce1e-41bb-902c-65f3d819e46e"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
wallet_id = 'fe2db143-ce1e-41bb-902c-65f3d819e46e'
payload = molecule_api.WalletPermissionUpdatePayload(
    nucleus_client_id='6164fcc1-32c9-4fd1-952b-172695d8d4ec',
  permission_type='LIMITED_AUTHORITY'
)

try:
    api_response = api_instance.update_wallet_permission(wallet_id, payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->update_wallet_permission: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var walletId = "fe2db143-ce1e-41bb-902c-65f3d819e46e";

var payload = new molecule_api.WalletPermissionUpdatePayload();
payload.nucleus_client_id = "6164fcc1-32c9-4fd1-952b-172695d8d4ec";
payload.permission_type = "LIMITED_AUTHORITY";

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

Example Response

{
  "wallet_id": "fe2db143-ce1e-41bb-902c-65f3d819e46e",
  "clients": [
    {
      "nucleus_client_id": "a587554c-7832-4841-af5a-3932335156ef",
      "permission_type": "FULL_AUTHORITY",
      "client_wallet_association_type": "owner",
      "is_primary": true
    },
    {
      "nucleus_client_id": "6164fcc1-32c9-4fd1-952b-172695d8d4ec",
      "permission_type": "LIMITED_AUTHORITY",
      "client_wallet_association_type": "admin",
      "is_primary": false
    }
  ]
}

Update the permission type of a client for a wallet. The wallet_id is specified in the URL, and the client_id and the updated permission_type must be provided in the request body.

HTTP REQUEST

PUT /wallet_permission/{wallet_id}

Security Tokens

Tokenization

Tokenization is the practice of digitally representing real world assets, such as stocks, 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. This endpoint is capable of performing both on-chain (blockchain) and off-chain (database) operations.

Field Type Description
id UUID The id of the security token
symbol string The symbol of the security token. Can be 3 or 4 characters long
name string The name of the security token
is_mintable boolean Determines if the security token is mintable or not. Defaults to false
is_burnable boolean Determines if the security token is burnable or not. Defaults to false
total_supply double The total supply of the security token
circulating_supply double The amount of tokens in circulation. Calculated automatically by the Event Handlers
nucleus_model_id UUID The id of the associated Nucleus Model for this security token
owner_wallet_id UUID The wallet id of the token owner. This wallet has the privileges to do on-chain modifications
whitelist_address string The global whitelist address of the security token on the Ethereum blockchain
contract_address string The contract address of the security token on the Ethereum blockchain
crowdsale_address string The crowdsale address of the security token on the Ethereum blockchain
restrictions map KYC restrictions to be applied on the token in the format key: value. See resources for available restriction types
offering_settings map The array of security token offering settings applied on this token
      rate integer The exchange rate of the token during the token offering. If an investor were to invest 1 ETH, they would receive rate amount of tokens.
      start_date timestamp The date the security token offering will go live
      end_date timestamp The date the security token offering will end
metadata map Custom information associated with the document in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id

Off-Chain Operations

Token methods that interact with off-chain databases. These methods will not interact with the blockchain.

List all tokens

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_tokens()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_tokens: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
  "content": [
    {
      "id": "1b8cc79d-b409-4d35-94e9-a902ab1683e6",
      "name": "MAAG Token",
      "symbol": "MAAG",
      "is_mintable": false,
      "is_burnable": false,
      "total_supply": 1000000,
      "circulating_supply": 250000,
      "nucleus_model_id": "8aff8394-ff73-4436-b1eb-3cfedb1a490f",
      "owner_wallet_id": "eb32c593-a452-41ff-8c5e-807d106c6486",
      "whitelist_address": "0x94bB939d345AFAcc7fADaeDaa752BdB59aFBcbD8",
      "contract_address": "0x655893A8F050C7Fa40Aaf46E19Fd94a08cd1C824",
      "crowdsale_address": null,
      "restrictions": {
        "min_age": 21,
        "kyc_required": true,
        "include_country": ["US", "CA"]
      },
      "secondary_id": null,
      "create_date": "2019-09-12T21:45:56.000Z",
      "update_date": "2019-09-12T21:56:35.000Z",
      "offering_settings": {
        "start_date": "2019-09-12T00:00:00.000Z",
        "end_date": "2020-09-09T00:00:00.000Z",
        "rate": 6200
      },
      "metadata": {}
    },
    {
      "id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
      "name": "2802 Claflin Avenue",
      "symbol": "28CA",
      "is_mintable": false,
      "is_burnable": false,
      "total_supply": 92000000,
      "circulating_supply": 5000000,
      "nucleus_model_id": "1f80f04f-4ea6-4231-bef4-d7c0098d6d30",
      "owner_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "whitelist_address": "0x1F206417C2652C2AB0dB5Ed208B4c7FAFb1900fd",
      "contract_address": "0x5F705f1B3BeD495f6B2D23585f8bE908B0E4Ff24",
      "crowdsale_address": "0x03A8eBe1197e55822ECdDB96f17A35552781Ebd2",
      "restrictions": {
        "min_age": 21,
        "min_annual_income": 150000,
        "kyc_required": true
      },
      "secondary_id": null,
      "create_date": "2019-09-12T21:44:02.000Z",
      "update_date": "2019-09-12T21:53:51.000Z",
      "offering_settings": {
        "start_date": null,
        "end_date": null,
        "rate": 36000
      },
      "metadata": {}
    }
  ],
  "total_pages": 1,
  "total_elements": 2,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "DESC",
      "property": "update_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "number_of_elements": 2,
  "size": 25,
  "number": 0
}

Get information for all tokens defined for your firm.

HTTP REQUEST

GET /token

Create a token

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "symbol": "28CA",
        "name": "2802 Claflin Token",
        "total_supply": "920000",
        "nucleus_model_id": "13ee1d48-15cb-4a1e-8cde-c7191813fa51",
        "owner_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
        "restrictions": {
          "min_age": "21",
            "min_annual_income": "150000",
            "accreditation_required": "true",
            "kyc_required": "true"
        },
        "offering_settings": {
          "start_date": "2019-09-09",
          "end_date": "2020-09-09",
          "rate": "360"
        }
    }' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

token_offering_settings = molecule_api.OfferingSettingsCreatePayload(
    rate="360",
    start_date="2019-09-09",
    end_date="2020-09-09"
)

token_restrictions = molecule_api.TokenRestrictionsPayload(
    min_age="21",
    min_annual_income="150000",
    accreditation_required="true",
    kyc_required="true"
)

payload = molecule_api.TokenCreatePayload(
    symbol="28CA",
    name="2802 Claflin Token",
    total_supply="920000",
    nucleus_model_id="13ee1d48-15cb-4a1e-8cde-c7191813fa51",
    owner_wallet_id="e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
    restrictions=token_restrictions,
    offering_settings=token_offering_settings
)

try:
    api_response = api_instance.post_token(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_token: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var tokenOfferingSettings = new molecule_api.OfferingSettingsCreatePayload();
tokenOfferingSettings.rate = "360";
tokenOfferingSettings.start_date = "2019-09-09";
tokenOfferingSettings.end_date = "2020-09-09";

var tokenRestrictions = new molecule_api.TokenRestrictionsPayload();
tokenRestrictions.min_age = "21";
tokenRestrictions.min_annual_income = "150000";
tokenRestrictions.accreditation_required = true;
tokenRestrictions.kyc_required = true;

var payload = new molecule_api.TokenCreatePayload();
payload.symbol = "28CA";
payload.name = "2802 Claflin Token";
payload.total_supply = "920000";
payload.nucleus_model_id = "13ee1d48-15cb-4a1e-8cde-c7191813fa51";
payload.owner_wallet_id = "e1711964-8e98-4a33-a4bf-ce9775b4c3b6";
payload.restrictions = tokenRestrictions;
payload.offering_settings = tokenOfferingSettings;

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

Example Response

{
  "id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
  "circulating_supply": 0,
  "symbol": "28CA",
  "name": "2802 Claflin Avenue",
  "is_mintable": false,
  "is_burnable": false,
  "total_supply": "920000",
  "owner_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "nucleus_model_id": "1f80f04f-4ea6-4231-bef4-d7c0098d6d30",
  "restrictions": {
    "min_age": 21,
    "min_annual_income": 150000,
    "accreditation_required": true,
    "kyc_required": true
  },
  "offering_settings": {
    "start_date": "2019-09-09T00:00:00.000Z",
    "end_date": "2020-09-09T00:00:00.000Z",
    "rate": "360"
  },
  "metadata": {},
  "update_date": "2019-09-12T20:39:50.812Z",
  "create_date": "2019-09-12T20:39:50.812Z"
}

Create a token using a Nucleus Model.

Details of the real world asset, such as address, category, type etc. will be stored under Nucleus Model and will be associated with a token using the nucleus_model_id field. Use the GET /nucleus/v1/model endpoint to see all models for your firm.

Note that the circulating_supply of a token gets updated automatically by the Event Handlers. It is not allowed to define a circulating_supply while creating a token.

HTTP REQUEST

POST /token

SAMPLE WORKFLOW

Tokenization

ARGUMENTS

Parameter Type Required Description
symbol string required The symbol of the security token. Could be 3 or 4 characters long
name string required The name of the security token
total_supply double required The total supply of the security token
nucleus_model_id UUID required The id of the associated Nucleus Model for this security token
owner_wallet_id UUID required The wallet id of the token owner. This wallet has the privileges to do on-chain modifications
is_mintable boolean optional Determines if the security token is mintable or not. Defaults to false
is_burnable boolean optional Determines if the security token is burnable or not. Defaults to false
contract_address string optional The contract address of the security token on the Ethereum blockchain
crowdsale_address string optional The crowdsale address of the security token on the Ethereum blockchain
restrictions map optional KYC restrictions to be applied on the token in the format key: value. See resources for available restriction types
offering_settings map optional The array of security token offering settings applied on this token
      rate integer optional The exchange rate of the token during the token offering
      start_date timestamp optional The date the security token offering will go live
      end_date timestamp optional The date the security token offering will end
metadata map optional Custom information associated with the document in the format key:value
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a token

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token/f995efbb-106f-4bc9-a43f-967e11cbbe2c"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
token_id = 'f995efbb-106f-4bc9-a43f-967e11cbbe2c'

try:
    api_response = api_instance.get_token(token_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_token: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var tokenId = "f995efbb-106f-4bc9-a43f-967e11cbbe2c";

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

Example Response

{
  "id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
  "name": "2802 Claflin Avenue",
  "symbol": "28CA",
  "is_mintable": false,
  "is_burnable": false,
  "total_supply": 920000,
  "circulating_supply": 0,
  "nucleus_model_id": "1f80f04f-4ea6-4231-bef4-d7c0098d6d30",
  "owner_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "whitelist_address": null,
  "contract_address": null,
  "crowdsale_address": null,
  "restrictions": {
    "min_age": 21,
    "min_annual_income": 150000,
    "accreditation_required": true,
    "kyc_required": true
  },
  "secondary_id": null,
  "create_date": "2019-09-12T20:39:50.000Z",
  "update_date": "2019-09-12T20:39:50.000Z",
  "offering_settings": {
    "start_date": "2019-09-09T00:00:00.000Z",
    "end_date": "2020-09-09T00:00:00.000Z",
    "rate": 360
  },
  "metadata": {}
}

Retrieve the information for a specific token. The token_id must be provided.

The endpoint returns the token_id and the details for the token specified. Note that the information for the metadata is stored as a nested object within the token object.

HTTP REQUEST

GET /token/{token_id}

Update a token

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
        "total_supply": "92000000",
        "restrictions": {
          "min_age": "21",
            "min_annual_income": "150000",
            "kyc_required": "true"
        }
        "offering_settings": {
            "rate": "36000"
        }
    }' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token/f995efbb-106f-4bc9-a43f-967e11cbbe2c"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

token_id = 'f995efbb-106f-4bc9-a43f-967e11cbbe2c'

new_offering_settings = molecule_api.OfferingSettingsCreatePayload(
    rate="36000"
)

new_restrictions = molecule_api.TokenRestrictionsPayload(
    min_age="21",
    min_annual_income="150000",
    kyc_required="true"
)

payload = molecule_api.TokenUpdatePayload(
    total_supply="92000000",
    restrictions=new_restrictions,
    offering_settings=new_offering_settings
)

try:
    api_response = api_instance.update_token(token_id, payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->update_token: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var tokenId = "f995efbb-106f-4bc9-a43f-967e11cbbe2c";

var newOfferingSettings = new molecule_api.OfferingSettingsCreatePayload();
newOfferingSettings.rate = "36000";

var newRestrictions = new molecule_api.TokenRestrictionsPayload();
newRestrictions.min_age = "21";
newRestrictions.min_annual_income = "150000";
newRestrictions.kyc_required = "true";

var payload = new molecule_api.TokenUpdatePayload();
payload.total_supply = "92000000";
payload.restrictions = newRestrictions;
payload.offering_settings = newOfferingSettings;

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

Example Response

{
  "id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
  "name": "2802 Claflin Avenue",
  "symbol": "28CA",
  "is_mintable": false,
  "is_burnable": false,
  "total_supply": "92000000",
  "circulating_supply": 0,
  "nucleus_model_id": "1f80f04f-4ea6-4231-bef4-d7c0098d6d30",
  "owner_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "whitelist_address": null,
  "contract_address": null,
  "crowdsale_address": null,
  "restrictions": {
    "min_age": "21",
    "min_annual_income": "150000",
    "kyc_required": "true"
  },
  "secondary_id": null,
  "create_date": "2019-09-12T20:39:50.000Z",
  "update_date": "2019-09-12T20:42:25.345Z",
  "offering_settings": {
    "rate": 36000
  },
  "metadata": {}
}

Update a token for your firm. The token_id must be provided. To obtain the appropriate token_id, use the GET /token endpoint to view all of the tokens for your firm and their current information.

It is not allowed to update the circulating_supply of a token, as this field gets updated automatically by the Event Handlers.

If a token is already deployed on the blockchain, only restrictions, offering_settings, metadata, and secondary_id fields will be allowed to update. If a token has an ongoing crowdsale, updating the rate field will not be allowed.

HTTP REQUEST

PUT /token/{token_id}

Delete a token

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token/27130922-f6cb-4662-9e74-b2c6051eecdc"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
token_id = '27130922-f6cb-4662-9e74-b2c6051eecdc'

try:
    api_instance.delete_token(token_id)
except ApiException as e:
    print("Exception when calling MoleculeApi->delete_token: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var tokenId = "27130922-f6cb-4662-9e74-b2c6051eecdc";

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log("API called successfully.");
  }
};
apiInstance.deleteToken(tokenId, callback);

Response (204 No Content)

Permanently delete a token for your firm. The token_id must be provided. To obtain the appropriate token_id, use the GET /token endpoint to view all of the tokens for your firm. This deletes the token_id and the details for the token record.

HTTP REQUEST

DELETE /token/{token_id}

On-Chain Operations

Token methods that interact with the blockchain. These methods will emit events to be processed by the event handlers.

All on-chain methods are processed in an asynchronous fashion, and their response will be a transaction_status with a Pending status. You can use GET /transaction_status method to track the status of your pending transactions.

Deploy a token

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c"
      }' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token/deploy"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.TokenDeployPayload(
    token_id="f995efbb-106f-4bc9-a43f-967e11cbbe2c"
)

try:
    api_response = api_instance.post_token_deploy(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_token_deploy: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.TokenDeployPayload();
payload.token_id = "f995efbb-106f-4bc9-a43f-967e11cbbe2c";

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

Example Response

{
  "id": "e4fa28ba-46dc-4fe0-9100-0a2531bd9d83",
  "hash": "pending",
  "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "status": "pending",
  "update_date": "2019-09-12T21:44:02.000Z",
  "create_date": "2019-09-12T21:44:02.000Z"
}

Deploys a token and its whitelist contract on the Ethereum blockchain. The token_id must be provided.

Will emit a Whitelist Admin Added and a Transfer event.

You can subscribe to whitelist_admin, token_balance, and transaction webhook codes for notifications.

HTTP REQUEST

POST /token/deploy

SAMPLE WORKFLOW

Tokenization

ARGUMENTS

Parameter Type Required Description
token_id UUID required The id of the security token being deployed to the blockchain

Whitelist a wallet

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
        "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de"
      }' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token/whitelist"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.TokenWhitelistPayload(
    token_id="f995efbb-106f-4bc9-a43f-967e11cbbe2c",
    wallet_id="cffc54ca-9f4d-40a2-a62b-ebd6dccf37de"
)

try:
    api_instance.post_token_whitelist(payload)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_token_whitelist: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.TokenWhitelistPayload();
payload.token_id = "f995efbb-106f-4bc9-a43f-967e11cbbe2c";
payload.wallet_id = "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de";

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log("API called successfully.");
  }
};

apiInstance.postTokenWhitelist(payload, callback);

Example Response (200)

{
  "id": "4cd888d1-15b4-4770-a23f-cff4b79bc835",
  "hash": "pending",
  "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "status": "pending",
  "update_date": "2019-09-12T21:44:02.000Z",
  "create_date": "2019-09-12T21:44:02.000Z"
}

Whitelists the specified wallet_id for the specified token_id.

Will emit a Whitelisted Added event.

You can subscribe to whitelisted webhook code for notifications.

HTTP REQUEST

POST /token/whitelist

SAMPLE WORKFLOW

Tokenization

ARGUMENTS

Parameter Type Required Description
token_id UUID required The id of the security token the investor being whitelisted
wallet_id UUID required The id of the wallet being whitelisted.

Mint tokens

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
    "receiver_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
    "amount": 10000
  }' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token/mint"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.TokenMintPayload(
  token_id="f995efbb-106f-4bc9-a43f-967e11cbbe2c",
  receiver_wallet_id="e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  amount=10000
)

try:
    api_instance.post_token_mint(payload)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_token_mint: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.TokenMintPayload();
payload.token_id = "f995efbb-106f-4bc9-a43f-967e11cbbe2c";
payload.receiver_wallet_id = "e1711964-8e98-4a33-a4bf-ce9775b4c3b6";
payload.amount = 10000;

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log("API called successfully.");
  }
};

apiInstance.postTokenMint(payload, callback);

Example Response (200)

{
  "id": "380af6e9-4fd8-4273-9732-d924facf4d0f",
  "hash": "pending",
  "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "status": "pending",
  "update_date": "2020-01-07T18:32:41.000Z",
  "create_date": "2020-01-07T18:32:41.000Z"
}

Mints specified amount of tokens and sends to the receiver_wallet_id.

Will emit a Transfer event.

You can subscribe to token_balance, and transaction webhook codes for notifications.

HTTP REQUEST

POST /token/mint

ARGUMENTS

Parameter Type Required Description
token_id UUID required The id of the security token being minted
receiver_wallet_id UUID required The id of the wallet which will receieve the minted tokens
amount double required The amount of tokens to be minted

Burn tokens

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
    "amount": 10000
  }' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token/burn"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.TokenBurnPayload(
  token_id="f995efbb-106f-4bc9-a43f-967e11cbbe2c",
  amount=10000
)

try:
    api_instance.post_token_burn(payload)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_token_burn: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.TokenBurnPayload();
payload.token_id = "f995efbb-106f-4bc9-a43f-967e11cbbe2c";
payload.amount = 10000;

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log("API called successfully.");
  }
};

apiInstance.postTokenBurn(payload, callback);

Example Response (200)

{
  "id": "2ddeefa5-76a0-495e-bb13-5fc843ee75e6",
  "hash": "pending",
  "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "status": "pending",
  "update_date": "2020-01-07T18:35:23.000Z",
  "create_date": "2020-01-07T18:35:23.000Z"
}

Burns specified amount of tokens from the token owner’s holdings.

Will emit a Transfer event.

You can subscribe to token_balance, and transaction webhook codes for notifications.

HTTP REQUEST

POST /token/burn

ARGUMENTS

Parameter Type Required Description
token_id UUID required The id of the security token being burned
amount double required The amount of tokens to be burned

Crowdsale

Crowdsale is a type of crowdfunding that issues SecurityTokens 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.

All crowdsale methods are processed in an asynchronous fashion, and their response will be a transaction_status with a Pending status. You can use GET /transaction_status method to track the status of your pending transactions.

Deploy a crowdsale

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c"
      }' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/crowdsale/deploy"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.CrowdsaleDeployPayload(
    token_id="f995efbb-106f-4bc9-a43f-967e11cbbe2c"
)

try:
    api_response = api_instance.post_crowdsale_deploy(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_crowdsale_deploy: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.CrowdsaleDeployPayload();
payload.token_id = "f995efbb-106f-4bc9-a43f-967e11cbbe2c";

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

Example Response

{
  "id": "7232a390-4ba5-4c55-baa9-bc7d0514581c",
  "hash": "pending",
  "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "status": "pending",
  "update_date": "2019-09-12T21:44:02.000Z",
  "create_date": "2019-09-12T21:44:02.000Z"
}

Deploys and starts a crowdsale for a SecurityToken on the Ethereum blockchain.

The rate field determines the exchange rate of the crowdsale. It indicates how many tokens will be sent to the investor for every 1 ETH they invest. e.g. If the rate is set to 1000, an investor will receive 1000 Tokens in return for their 1 ETH purchase.

The rate field of the token’s offering_settings can’t be zero. Use the PUT /token method to update its rate before starting the crowdsale. The request will be rejected if the token already has an ongoing crowdsale or has a rate of 0.

As soon as the crowdsale contract is deployed, Molecule will update the crowdsale_address of the token with the newly generated smart contract addresses.

You can subscribe to transaction webhook code for notifications.

HTTP REQUEST

POST /crowdsale/deploy

SAMPLE WORKFLOW

Crowdselling

ARGUMENTS

Parameter Type Required Description
token_id UUID required The id of the security token being crowdsaled

Fund a crowdsale

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
         "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
         "supply": "5000000"
      }' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/crowdsale/fund"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.CrowdsaleFundPayload(
    token_id="f995efbb-106f-4bc9-a43f-967e11cbbe2c",
    supply="5000000"
)

try:
    api_response = api_instance.post_crowdsale_fund(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_crowdsale_fund: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.CrowdsaleFundPayload();
payload.token_id = "f995efbb-106f-4bc9-a43f-967e11cbbe2c";
payload.supply = "5000000";

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

Example Response

{
  "id": "175d646a-e01a-4edb-b3e6-809c2d7be27b",
  "hash": "pending",
  "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "status": "pending",
  "update_date": "2019-09-12T21:44:02.000Z",
  "create_date": "2019-09-12T21:44:02.000Z"
}

Funds a token’s crowdsale by transferring the specified supply. The supply provided in the request body can’t be greater than the owner’s token balance.

Will emit a Transfer event. A Token Balance and a Token Supply entry will be created by the event listeners.

You can subscribe to token_balance, token_supply_balance, and transaction webhook codes for notifications.

HTTP REQUEST

POST /crowdsale/fund

SAMPLE WORKFLOW

Crowdselling

ARGUMENTS

Parameter Type Required Description
token_id UUID required The id of the security token being crowdsaled
supply double required The number of tokens to be transferred to the crowdsale contract for the offering.

Purchase from a crowdsale

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
         "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
         "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
         "amount": "750000"
      }' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/crowdsale/purchase"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.CrowdsalePurchasePayload(
    token_id="f995efbb-106f-4bc9-a43f-967e11cbbe2c",
    wallet_id="cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
    amount="750000"
)

try:
    api_instance.post_crowdsale_purchase(payload)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_crowdsale_purchase: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.CrowdsalePurchasePayload();
payload.token_id = "f995efbb-106f-4bc9-a43f-967e11cbbe2c";
payload.wallet_id = "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de";
payload.amount = "750000";

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log("API called successfully.");
  }
};

apiInstance.postCrowdsalePurchase(payload, callback);

Example Response (200)

{
  "id": "06891e8b-07e6-4956-ab8e-7f42f9c118e7",
  "hash": "pending",
  "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  "status": "pending",
  "update_date": "2019-09-12T21:44:02.000Z",
  "create_date": "2019-09-12T21:44:02.000Z"
}

This method will first calculate the required ETH amount needed to purchase the specified amount of tokens from the crowdsale contract.

Required ETH = amount / token.offering_settings.rate

If the investor’s wallet has enough ETH balance, this method will transfer the investor’s ETH to the token owner, and transfer the equivalent amount of tokens from the token’s crowdsale contract to the investor.

Will emit a Transfer event. A Token Balance, a Token Supply, and two Currency Balance entries will be created by the event listeners.

You can subscribe to token_transfer, token_balance, token_supply_balance, and currency_balance webhook codes for notifications.

HTTP REQUEST

POST /crowdsale/purchase

SAMPLE WORKFLOW

Crowdselling

ARGUMENTS

Parameter Type Required Description
token_id UUID required The id of the security token the investor is investing in
wallet_id UUID required The id of the investor’s wallet
amount double required The number of tokens the investor wants to purchase.

Payments

Token Transfer

This endpoint transfers SecurityTokens between two wallets.

Field Type Description
id UUID The id for the token transfer
sender_wallet_id UUID The id of the sender wallet
receiver_wallet_id UUID The id of the receiver wallet
token_id UUID The id of the token being transferred
amount double Amount of tokens being transferred

List all token transfer receipts

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token_transfer"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_token_transfers()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_token_transfers: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
  "content": [
    {
      "id": "d5e4c992-46b3-4e14-86b5-7817dc54982c",
      "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
      "amount": "10000",
      "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
      "transaction_hash": "0xca7fae11fdd2280d97c94543aafadcbb6eb20ff9d7e1cc6dbe6e81f071c5a3ff",
      "create_date": "2019-10-03T17:40:22.431Z",
      "update_date": "2019-10-03T17:40:22.431Z"
    },
    {
      "id": "69d4880d-5a1f-44a7-8a0a-2d3fb879dbd6",
      "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
      "amount": "5000",
      "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
      "transaction_hash": "0x27ecc18843424fcf6ce608b99b7c35eea54c1463e0469eb05738a8231fc28c5f",
      "create_date": "2019-10-03T17:40:54.166Z",
      "update_date": "2019-10-03T17:40:54.166Z"
    }
  ],
  "total_pages": 1,
  "total_elements": 2,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "ASC",
      "property": "create_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": true,
      "descending": false
    }
  ],
  "number_of_elements": 2,
  "size": 25,
  "number": 0
}

Get information for all token transfer receipts. Optionally, you can pass sender_wallet_id, receiver_wallet_id, token_id, or wallet_id as query parameter to filter the response. wallet_id will filter currency transfers where the id provided is either the sender or the receiver.

HTTP REQUEST

GET /token_transfer

FILTERS

Parameter Type Description
token_id UUID Retrieve only the transfers for a certain token
wallet_id UUID Retrieve all the transfers of a wallet
sender_wallet_id UUID Retrieve the transfers where the wallet was the sender
receiver_wallet_id UUID Retrieve the transfers where the wallet was the receiver

Transfer a token

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
        "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
        "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
        "amount": "10000"
      }' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token_transfer"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.TokenTransferPayload(
    sender_wallet_id="e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  receiver_wallet_id="cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  token_id="f995efbb-106f-4bc9-a43f-967e11cbbe2c",
    amount="10000"
)

try:
    api_instance.post_token_transfer(payload)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_token_transfer: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.TokenTransferPayload();
payload.sender_wallet_id = "e1711964-8e98-4a33-a4bf-ce9775b4c3b6";
payload.receiver_wallet_id = "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de";
payload.token_id = "f995efbb-106f-4bc9-a43f-967e11cbbe2c";
payload.amount = "10000";

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log("API called successfully.");
  }
};

apiInstance.postTokenTransfer(payload, callback);

Example Response (200)

{
  "id": "ce83a540-7d93-492a-a8bb-7843a5930993",
  "hash": "pending",
  "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "status": "pending",
  "update_date": "2019-10-03T17:40:22.431Z",
  "create_date": "2019-10-03T17:40:22.431Z"
}

If the sender has sufficient token balance, this method will create an Ethereum transaction to transfer tokens to the specified receiver_wallet_id.

The token transfer method is processed in an asynchronous fashion, and its response will be a transaction_status with a Pending status. You can use GET /transaction_status method to track the status of your pending transactions.

Will emit a Transfer event. A Token Transfer Receipt and two Token Balance entries will be created automatically by the Event Handlers.

You can subscribe to token_transfer, and token_balance webhook codes for notifications.

HTTP Request

POST /token_transfer

SAMPLE WORKFLOW

P2P Payments

ARGUMENTS

Parameter Type Required Description
sender_wallet_id UUID required The id of the sender wallet
receiver_wallet_id UUID required The id of the receiver wallet
token_id UUID required The id of the security token being transferred
amount double required Amount of tokens being transferred

Retrieve a token transfer receipt

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token_transfer/d5e4c992-46b3-4e14-86b5-7817dc54982c"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
token_transfer_id = 'd5e4c992-46b3-4e14-86b5-7817dc54982c'

try:
    api_response = api_instance.get_token_transfer(token_transfer_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_token_transfer: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var tokenTransferId = "d5e4c992-46b3-4e14-86b5-7817dc54982c";

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

Example Response

{
  "id": "d5e4c992-46b3-4e14-86b5-7817dc54982c",
  "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  "amount": "10000",
  "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
  "transaction_hash": "0xca7fae11fdd2280d97c94543aafadcbb6eb20ff9d7e1cc6dbe6e81f071c5a3ff",
  "create_date": "2019-10-03T17:40:22.431Z",
  "update_date": "2019-10-03T17:40:22.431Z"
}

Retrieve information for a specific token transfer receipt. The unique token_transfer_id must be provided. This method returns details for the token transfer specified including the transaction_hash.

HTTP REQUEST

GET /token_transfer/{token_transfer_id}

Currency

Use this endpoint to retrieve details on available currencies, add support for new ERC-20 based currencies and disallow usage on existing currencies.

Field Type Description
id UUID The id for the currency
name string The name of the currency
decimal_points integer Decimal points of the currency
symbol string Symbol of the currency
address string The smart contract address of the currency on the blockchain.
logo string The url for the currency logo
network string The network the currency is available on. Can be mainnet, ropsten etc.
is_allowed boolean Determines if the currency is allowed for usage. Defaults to true

List all currencies

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/currency"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_currencies()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_currencies: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
  "content": [
    {
      "id": "0747ad4d-8de5-43a0-b38e-441bae051589",
      "name": "Wrapped BTC",
      "decimal_points": 8,
      "symbol": "WBTC",
      "address": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
      "logo": null,
      "network": "mainnet",
      "is_allowed": true,
      "create_date": "2019-12-26T21:13:18.228Z",
      "update_date": "2019-12-26T21:13:18.228Z"
    },
    {
      "id": "2f1397ff-0529-4964-a99e-d2b36d447794",
      "name": "Augur",
      "decimal_points": 18,
      "symbol": "REP",
      "address": "0x1985365e9f78359a9B6AD760e32412f4a445E862",
      "logo": null,
      "network": "mainnet",
      "is_allowed": true,
      "create_date": "2019-12-26T21:13:18.228Z",
      "update_date": "2019-12-26T21:13:18.228Z"
    },
    {
      "id": "55620ee5-0a95-4bd2-8d02-aa934cff93a5",
      "name": "USDC Stable Coin",
      "decimal_points": 6,
      "symbol": "USDC",
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "logo": null,
      "network": "mainnet",
      "is_allowed": true,
      "create_date": "2019-12-26T21:13:18.228Z",
      "update_date": "2019-12-26T21:13:18.228Z"
    },
    {
      "id": "8020c96b-8f92-4e5a-8033-f25ccf3e9ce5",
      "name": "Dai Stable Coin",
      "decimal_points": 18,
      "symbol": "DAI",
      "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "logo": null,
      "network": "mainnet",
      "is_allowed": true,
      "create_date": "2019-12-26T21:13:18.228Z",
      "update_date": "2019-12-26T21:13:18.228Z"
    },
    {
      "id": "91047b59-63b0-4543-97aa-87c0e2a12874",
      "name": "0x",
      "decimal_points": 18,
      "symbol": "ZRX",
      "address": "0xe41d2489571d322189246dafa5ebde1f4699f498",
      "logo": null,
      "network": "mainnet",
      "is_allowed": true,
      "create_date": "2019-12-26T21:13:18.228Z",
      "update_date": "2019-12-26T21:13:18.228Z"
    },
    {
      "id": "9e57c2bc-f74d-4d38-831b-64fdc2a50b47",
      "name": "Basic Attention Token",
      "decimal_points": 18,
      "symbol": "BAT",
      "address": "0x0d8775f648430679a709e98d2b0cb6250d2887ef",
      "logo": "https://upload.wikimedia.org/wikipedia/commons/thumb/a/ac/Brave_Basic_Attention_Token_%28BAT%29_Logo.svg/134px-Brave_Basic_Attention_Token_%28BAT%29_Logo.svg.png",
      "network": "mainnet",
      "is_allowed": true,
      "create_date": "2019-12-26T21:13:18.228Z",
      "update_date": "2019-12-26T21:13:18.228Z"
    },
    {
      "id": "ba43fb82-0ddf-420c-a9f8-9164424cbe06",
      "name": "Hydro",
      "decimal_points": 18,
      "symbol": "HYDRO",
      "address": "0xebbdf302c940c6bfd49c6b165f457fdb324649bc",
      "logo": null,
      "network": "mainnet",
      "is_allowed": true,
      "create_date": "2019-12-26T21:13:18.228Z",
      "update_date": "2019-12-26T21:13:18.228Z"
    },
    {
      "id": "da0ac8a6-724e-4e2d-9d14-1b58329688a3",
      "name": "Single-Collateral Dai",
      "decimal_points": 18,
      "symbol": "SAI",
      "address": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
      "logo": null,
      "network": "mainnet",
      "is_allowed": true,
      "create_date": "2019-12-26T21:13:18.228Z",
      "update_date": "2019-12-26T21:13:18.228Z"
    },
    {
      "id": "e6fe599e-cc17-4176-83fb-1d3043af1f67",
      "name": "Ether",
      "decimal_points": 18,
      "symbol": "ETH",
      "address": null,
      "logo": "https://upload.wikimedia.org/wikipedia/commons/0/05/Ethereum_logo_2014.svg",
      "network": "mainnet",
      "is_allowed": true,
      "create_date": "2019-12-26T21:13:18.228Z",
      "update_date": "2019-12-26T21:13:18.228Z"
    },
    {
      "id": "b6583d0e-4a54-4608-a0ba-a7fcf1cd9ffa",
      "name": "OMGToken",
      "decimal_points": 18,
      "symbol": "OMG",
      "address": "0xd26114cd6EE289AccF82350c8d8487fedB8A0C07",
      "logo": null,
      "network": "mainnet",
      "is_allowed": false,
      "create_date": "2019-12-26T21:13:52.521Z",
      "update_date": "2019-12-26T21:13:58.975Z"
    }
  ],
  "total_pages": 1,
  "total_elements": 10,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "ASC",
      "property": "create_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": true,
      "descending": false
    }
  ],
  "number_of_elements": 10,
  "size": 25,
  "number": 0
}

Get information for all currencies defined for your firm. Optionally, you can pass symbol as a query parameter to retrieve details for a specific curency.

HTTP REQUEST

GET /currency

FILTERS

Parameter Type Description
symbol string Retrieve the currency matching a certain symbol

Add a currency

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xd26114cd6EE289AccF82350c8d8487fedB8A0C07"
}' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/currency"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.CurrencyCreatePayload(
    address="0xd26114cd6EE289AccF82350c8d8487fedB8A0C07"
)

try:
    api_response = api_instance.post_currency(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_currency: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.CurrencyCreatePayload();
payload.address = "0xd26114cd6EE289AccF82350c8d8487fedB8A0C07";

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

Example Response

{
  "id": "b6583d0e-4a54-4608-a0ba-a7fcf1cd9ffa",
  "is_allowed": true,
  "address": "0xd26114cd6EE289AccF82350c8d8487fedB8A0C07",
  "decimal_points": "18",
  "name": "OMGToken",
  "symbol": "OMG",
  "network": "mainnet",
  "update_date": "2019-12-26T21:13:52.521Z",
  "create_date": "2019-12-26T21:13:52.521Z"
}

Add support for Ether or any ERC-20 based cryptocurrency. address of the currency must be provided. Molecule will retrieve the name, symbol, and decimal_points information of the currency from the blockchain.

If there already is a currency with using the same address the request will be rejected.

HTTP REQUEST

POST /currency

ARGUMENTS

Parameter Type Required Description
address string required The smart contract address of the currency on the blockchain
logo string optional The URL for the currency logo

Retrieve a currency

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/currency/e733187e-47c8-4d17-9575-fefe7b3493fe"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
currency_id = 'e733187e-47c8-4d17-9575-fefe7b3493fe'

try:
    api_response = api_instance.get_currency(currency_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_currency: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var currencyId = "e733187e-47c8-4d17-9575-fefe7b3493fe";

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

Example Response

{
  "id": "e733187e-47c8-4d17-9575-fefe7b3493fe",
  "name": "Basic Attention Token",
  "decimal_points": 18,
  "symbol": "BAT",
  "address": "0x0d8775f648430679a709e98d2b0cb6250d2887ef",
  "logo": null,
  "network": "mainnet",
  "create_date": "2019-11-21T16:54:29.502Z",
  "update_date": "2019-11-21T16:54:29.502Z"
}

Retrieve the information for a specific currency. The unique currency_id must be provided. The endpoint returns the currency_id and details for the currency specified.

HTTP REQUEST

GET /currency/{currency_id}

Update a currency

Example Request

curl -X PUT \ -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "is_allowed": false
}' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/currency/b6583d0e-4a54-4608-a0ba-a7fcf1cd9ffa"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
currency_id = 'b6583d0e-4a54-4608-a0ba-a7fcf1cd9ffa'
payload = molecule_api.CurrencyUpdatePayload(
    is_allowed=False,
)

try:
    api_response = api_instance.update_currency(currency_id, payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->update_currency: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var currencyId = "b6583d0e-4a54-4608-a0ba-a7fcf1cd9ffa";

var payload = new molecule_api.CurrencyUpdatePayload();
payload.is_allowed = false;

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

Example Response

{
  "id": "b6583d0e-4a54-4608-a0ba-a7fcf1cd9ffa",
  "name": "OMGToken",
  "decimal_points": 18,
  "symbol": "OMG",
  "address": "0xd26114cd6EE289AccF82350c8d8487fedB8A0C07",
  "logo": null,
  "network": "mainnet",
  "is_allowed": false,
  "create_date": "2019-12-26T21:13:52.521Z",
  "update_date": "2019-12-26T21:13:58.975Z"
}

Update the logo and allowance information for a currency. The unique currency_id must be provided. To obtain the appropriate currency_id, use the GET /currency endpoint to view all currencies defined for your firm and their current information.

HTTP REQUEST

PUT /currency/{currency_id}

Currency Transfer

This endpoint transfers currencies between two wallets. Use currency endpoint to see the list of currencies supported by your firm, and to add support for new ones.

Field Type Description
id UUID The id for the currency transfer
sender_wallet_id UUID The id of the sender wallet
receiver_wallet_id UUID The id of the receiver wallet
currency_id UUID The id of the currency being transferred.
amount double Amount of currency being transferred

List all currency transfer receipts

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/currency_transfer"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_currency_transfers()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_currency_transfers: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
  "content": [
    {
      "id": "3d1ab759-8fd0-4458-823b-ef929c2aa7c6",
      "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
      "amount": "100",
      "currency_id": "423299ca-5d1b-4311-bb5d-d02e421ff155",
      "transaction_hash": "0x7454aea084570d402c2f515311df4b3bbb7168d9afc7f5c5862a6e8502b31d05",
      "is_active": true,
      "create_date": "2019-11-04T15:52:34.987Z",
      "update_date": "2019-11-04T15:52:34.987Z"
    },
    {
      "id": "d596b6bf-f472-4fea-85dd-d65ef6ec07bc",
      "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
      "amount": "1500",
      "currency_id": "e733187e-47c8-4d17-9575-fefe7b3493fe",
      "transaction_hash": "0x158db8e1d9f75c3d97a97cb01cdca658e4e30700f93123a84fb5280f6caf65c5",
      "is_active": true,
      "create_date": "2019-11-04T15:52:02.849Z",
      "update_date": "2019-11-04T15:52:02.849Z"
    },
    {
      "id": "43646089-6a2b-4d9f-81c8-bdfbeac4461c",
      "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
      "amount": "10",
      "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
      "transaction_hash": "0xf8674b1296c237752e9632798c15dd0a7011cdb97e055b6ee769476a43c47320",
      "create_date": "2019-10-10T16:01:58.005Z",
      "update_date": "2019-10-10T16:01:58.005Z"
    },
    {
      "id": "d1be30ad-6e28-482d-b12d-88e62be76254",
      "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
      "amount": "3.73",
      "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
      "transaction_hash": "0xa932203ca4ab289d36c28add805c3e1df75f49da400d4b7d9b95a7c8b96a130a",
      "create_date": "2019-10-10T16:06:17.682Z",
      "update_date": "2019-10-10T16:06:17.682Z"
    }
  ],
  "total_pages": 1,
  "total_elements": 4,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "ASC",
      "property": "create_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": true,
      "descending": false
    }
  ],
  "number_of_elements": 2,
  "size": 25,
  "number": 0
}

Get information for all currency transfer receipts. Optionally, you can pass sender_wallet_id, receiver_wallet_id, currency_id, or wallet_id as query parameter to filter the response. wallet_id will filter currency transfers where the id provided is either the sender or the receiver.

HTTP REQUEST

GET /currency_transfer

FILTERS

Parameter Type Description
currency_id UUID Retrieve only the transfers for a certain currency
wallet_id UUID Retrieve all the transfers of a wallet
sender_wallet_id UUID Retrieve the transfers where the wallet was the sender
receiver_wallet_id UUID Retrieve the transfers where the wallet was the receiver

Transfer a currency

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
        "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
        "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
        "amount": "10"
      }' "https://[sandbox][api].hydrogenplatform.com/molecule/v1/currency_transfer"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.CurrencyTransferPayload(
    sender_wallet_id="e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  receiver_wallet_id="cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  currency_id="3bdceb1d-8609-49fd-b765-703deaff8b89",
    amount="10"
)

try:
    api_instance.post_currency_transfer(payload)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_currency_transfer: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.CurrencyTransferPayload();
payload.sender_wallet_id = "e1711964-8e98-4a33-a4bf-ce9775b4c3b6";
payload.receiver_wallet_id = "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de";
payload.currency_id = "3bdceb1d-8609-49fd-b765-703deaff8b89";
payload.amount = "10";

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log("API called successfully.");
  }
};

apiInstance.postCurrencyTransfer(payload, callback);

Example Response (200)

{
  "id": "ae0aa793-91fc-4a8d-82ba-106e7c00456b",
  "hash": "pending",
  "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "status": "pending",
  "update_date": "2019-10-10T16:01:58.005Z",
  "create_date": "2019-10-10T16:01:58.005Z"
}

If the sender has sufficient currency balance, this method will create an Ethereum transaction to transfer currencies to the specified receiver_wallet_id.

The currency transfer method is processed in an asynchronous fashion, and its response will be a transaction_status with a Pending status. You can use GET /transaction_status method to track the status of your pending transactions.

Currency Transfer will emit a Transfer event. A Currency Transfer Receipt and two Currency Balance entries will be created automatically by the Event Handlers.

You can subscribe to currency_transfer, and currency_balance webhook codes for notifications.

HTTP Request

POST /currency_transfer

SAMPLE WORKFLOW

P2P Payments

ARGUMENTS

Parameter Type Required Description
sender_wallet_id UUID required The id of the sender wallet
receiver_wallet_id UUID required The id of the receiver wallet
currency_id UUID required The id of the currency being transferred
amount double required Amount of currency being transferred

Retrieve a currency transfer receipt

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/currency_transfer/43646089-6a2b-4d9f-81c8-bdfbeac4461c"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
currency_transfer_id = '43646089-6a2b-4d9f-81c8-bdfbeac4461c'

try:
    api_response = api_instance.get_currency_transfer(currency_transfer_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_currency_transfer: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var currencyTransferId = "43646089-6a2b-4d9f-81c8-bdfbeac4461c";

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

Example Response

{
  "id": "43646089-6a2b-4d9f-81c8-bdfbeac4461c",
  "sender_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  "amount": "10",
  "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
  "transaction_hash": "0xf8674b1296c237752e9632798c15dd0a7011cdb97e055b6ee769476a43c47320",
  "create_date": "2019-10-10T16:01:58.005Z",
  "update_date": "2019-10-10T16:01:58.005Z"
}

Retrieve information for a specific currency transfer receipt. The unique currency_transfer_id must be provided. This method returns details for the currency transfer specified including the transaction_hash returned from the network.

HTTP REQUEST

GET /currency_transfer/{currency_transfer_id}

Transaction Status

This endpoint tracks the statuses of on-chain transactions.

Field Type Description
id UUID The unique id for the transaction status
wallet_id UUID The id of the wallet sent out the transaction
hash string The unique hash of the transaction
status string The status of the transaction. Could be pending, processed, or failed

List all transaction statuses

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/transaction_status"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_transaction_statuses()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_transaction_statuses: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
  "content": [
    {
      "id": "e4fa28ba-46dc-4fe0-9100-0a2531bd9d83",
      "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "hash": "0xdd3f856251e6cdd61ed29623ae4118a32d41e40591e83be40dfbbdfa8befccb8",
      "status": "pending",
      "create_date": "2019-11-04T16:48:36.745Z",
      "update_date": "2019-11-04T16:48:36.838Z"
    },
    {
      "id": "bfe6a52e-0574-4e43-94c2-0a3ef877b9ca",
      "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "hash": "0x7454aea084570d402c2f515311df4b3bbb7168d9afc7f5c5862a6e8502b31d05",
      "status": "processed",
      "create_date": "2019-11-04T15:52:34.987Z",
      "update_date": "2019-11-04T15:53:13.181Z"
    },
    {
      "id": "19e5ff55-c72c-4eba-9353-d91d0b0319e9",
      "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "hash": "0x158db8e1d9f75c3d97a97cb01cdca658e4e30700f93123a84fb5280f6caf65c5",
      "status": "processed",
      "create_date": "2019-11-04T15:52:02.849Z",
      "update_date": "2019-11-04T15:52:06.527Z"
    },
    {
      "id": "81489f7a-612f-4389-a49f-9e12b8cf13e4",
      "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "hash": "0xc47ecca8141780ff9288c3bb28c90960d5ee8cc4db8d2ae0858cb602606f6020",
      "status": "processed",
      "create_date": "2019-11-04T15:31:28.530Z",
      "update_date": "2019-11-04T15:31:34.606Z"
    }
  ],
  "total_pages": 1,
  "total_elements": 4,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "DESC",
      "property": "create_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "number_of_elements": 8,
  "size": 25,
  "number": 0
}

Get information for all transaction statuses. Optionally, you can pass wallet_id, hash, or status as query parameters to filter the results.

HTTP REQUEST

GET /transaction_status

FILTERS

Parameter Type Description
wallet_id UUID Retrieve all the transaction statuses of a wallet
hash string Retrieve the status of a transaction matching a certain hash
status string Retrieve the transactions with a certain status

Retrieve a transaction status

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/transaction_status/e4fa28ba-46dc-4fe0-9100-0a2531bd9d83"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
transaction_status_id = 'e4fa28ba-46dc-4fe0-9100-0a2531bd9d83'

try:
    api_response = api_instance.get_transaction_status(transaction_status_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_transaction_status: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var transactionStatusId = "e4fa28ba-46dc-4fe0-9100-0a2531bd9d83";

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

Example Response

{
  "id": "e4fa28ba-46dc-4fe0-9100-0a2531bd9d83",
  "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
  "hash": "0xdd3f856251e6cdd61ed29623ae4118a32d41e40591e83be40dfbbdfa8befccb8",
  "status": "pending",
  "create_date": "2019-11-04T16:48:36.745Z",
  "update_date": "2019-11-04T16:48:36.838Z"
}

Retrieve status information for a specific transaction.

HTTP REQUEST

GET /transaction_status/{transaction_status_id}
GET /transaction_status?hash={hash}
GET /transaction_status?status=pending&wallet_id={wallet_id}

Balance

User Currency Balance

This endpoint keeps track of currency balances of wallets. Currency Balance entries are created automatically by the Event Handlers.

Use currency endpoint to see the list of currencies supported by your firm, and to add support for new ones.

Field Type Description
id UUID The id for the currency balance
wallet_id UUID The id of the associated wallet
currency_id UUID The id of the associated currency
balance double Amount of currencies owned by the wallet

List all currency balances

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/molecule/v1/currency_balance"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_currency_balances()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_currency_balances: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
  "content": [
    {
      "id": "0aef13fc-b0b0-4daf-8c02-3327a7575958",
      "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
      "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
      "balance": 13.73,
      "hash": "0xa932203ca4ab289d36c28add805c3e1df75f49da400d4b7d9b95a7c8b96a130a",
      "create_date": "2019-10-10T16:06:18.103Z",
      "update_date": "2019-10-10T16:06:18.103Z"
    },
    {
      "id": "190fae1a-614c-4563-a717-9e092a369986",
      "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
      "balance": 36.27,
      "hash": "0xa932203ca4ab289d36c28add805c3e1df75f49da400d4b7d9b95a7c8b96a130a",
      "create_date": "2019-10-10T16:06:17.821Z",
      "update_date": "2019-10-10T16:06:17.821Z"
    },
    {
      "id": "516ddf25-83f7-4882-9c2d-a884ef240e5b",
      "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
      "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
      "hash": "0xf8674b1296c237752e9632798c15dd0a7011cdb97e055b6ee769476a43c47320",
      "balance": 10,
      "create_date": "2019-10-10T16:01:58.649Z",
      "update_date": "2019-10-10T16:01:58.649Z"
    },
    {
      "id": "044e6f18-1db7-4dce-b659-6c64e4f0e5ed",
      "wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
      "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
      "hash": "0xf8674b1296c237752e9632798c15dd0a7011cdb97e055b6ee769476a43c47320",
      "balance": 40,
      "create_date": "2019-10-10T16:01:58.115Z",
      "update_date": "2019-10-10T16:01:58.115Z"
    }
  ],
  "total_pages": 1,
  "total_elements": 4,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "DESC",
      "property": "create_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "number_of_elements": 4,
  "size": 25,
  "number": 0
}

Get information for all currency balances stored in your application. Optionally, you can pass wallet_id as a query parameter to retrieve currency balance entries for a specific wallet.

HTTP REQUEST

GET /currency_balance

FILTERS

Parameter Type Description
currency_id UUID Retrieve the balances of a certain currency
wallet_id UUID Retrieve the balacnes of a certain wallet

Retrieve a currency balance

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/molecule/v1/currency_balance/0aef13fc-b0b0-4daf-8c02-3327a7575958"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
currency_balance_id = '0aef13fc-b0b0-4daf-8c02-3327a7575958'

try:
    api_response = api_instance.get_currency_balance(currency_balance_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_currency_balance: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var currencyBalanceId = "0aef13fc-b0b0-4daf-8c02-3327a7575958";

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

Example Response

{
  "id": "0aef13fc-b0b0-4daf-8c02-3327a7575958",
  "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
  "balance": 13.73,
  "hash": "0xa932203ca4ab289d36c28add805c3e1df75f49da400d4b7d9b95a7c8b96a130a",
  "create_date": "2019-10-10T16:06:18.103Z",
  "update_date": "2019-10-10T16:06:18.103Z"
}

Retrieve the information for a specific balance for a currency. The unique currency_balance_id must be provided. The endpoint returns the currency_balance_id and details for the currency balance specified.

HTTP REQUEST

GET /currency_balance/{currency_balance_id}

Currency balance update

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
  -H "Content-Type: application/json" \
  -d '{
        "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de"
      }' "https://api.hydrogenplatform.com/molecule/v1/currency_balance/update"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

payload = molecule_api.CurrencyBalanceUpdatePayload(
    wallet_id="cffc54ca-9f4d-40a2-a62b-ebd6dccf37de"
)

try:
    api_response = api_instance.post_currency_balance_update(payload)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->post_currency_balance_update: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var payload = new molecule_api.CurrencyBalanceUpdatePayload();
payload.wallet_id = "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de";

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

Example Response

{
  "id": "0aef13fc-b0b0-4daf-8c02-3327a7575958",
  "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
  "balance": 13.73,
  "hash": "0xa932203ca4ab289d36c28add805c3e1df75f49da400d4b7d9b95a7c8b96a130a",
  "create_date": "2019-10-10T16:06:18.103Z",
  "update_date": "2019-10-10T16:06:18.103Z"
}

Queries the most recent balance of a wallet for any currency, and updates the database in case it is not synchronized. If the currency balance retrieved from the blockchain is equal to the latest currency balance entry in the database, the most recent entry will be returned and no new entry will be created.

HTTP REQUEST

POST /currency_balance/update

ARGUMENTS

Parameter Type Required Description
wallet_id UUID required The id of the wallet for which the currency balance will be updated
currency_id UUID optional The id of the currency to be updated. Defaults to currency_id of ETH

User Token Balance

This endpoint keeps track of SecurityToken balances of wallets. Token Balance entries are created automatically by the Event Handlers.

Field Type Description
id UUID The id for the token balance
token_id UUID The id of the associated token
wallet_id UUID The id of the associated wallet
balance double Number of tokens owned by the wallet

List all token balances

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/molecule/v1/token_balance"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_token_balances()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_token_balances: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
  "content": [
    {
      "id": "4d421d3d-9c18-4486-b98a-f66c5040dc3b",
      "balance": 1400000,
      "wallet_id": "2b96275a-8051-455a-9d37-2dfcfe282bf6",
      "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
      "create_date": "2019-09-12T22:04:12.000Z",
      "update_date": "2019-09-12T22:04:12.000Z"
    },
    {
      "id": "532ca8a4-3baa-4b7c-afaf-d0c61d1d617d",
      "balance": 50000,
      "wallet_id": "29707a47-5298-428e-813c-8e3c410a0013",
      "token_id": "602e389f-ee2d-40c4-a5ef-ccd6c08e0d64",
      "create_date": "2019-09-12T22:01:23.000Z",
      "update_date": "2019-09-12T22:01:23.000Z"
    },
    {
      "id": "9ff312de-53fa-474a-a46d-8dfa82b12b76",
      "balance": 750000,
      "wallet_id": "29707a47-5298-428e-813c-8e3c410a0013",
      "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
      "create_date": "2019-09-12T21:59:37.000Z",
      "update_date": "2019-09-12T21:59:37.000Z"
    },
    {
      "id": "557cd772-74c4-47ba-911f-6890862fb476",
      "balance": 750000,
      "wallet_id": "2b96275a-8051-455a-9d37-2dfcfe282bf6",
      "token_id": "602e389f-ee2d-40c4-a5ef-ccd6c08e0d64",
      "create_date": "2019-09-12T21:56:35.000Z",
      "update_date": "2019-09-12T21:56:35.000Z"
    },
    {
      "id": "145cbfcc-c677-4f1c-a357-f6567f8910fb",
      "balance": 87000000,
      "wallet_id": "f6d7f183-18b1-440c-8bc2-6e1859e8091c",
      "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
      "create_date": "2019-09-12T21:53:52.000Z",
      "update_date": "2019-09-12T21:53:52.000Z"
    },
    {
      "id": "73fc2d86-7422-48c0-a10c-8562c7fc386e",
      "balance": 1000000,
      "wallet_id": "2b96275a-8051-455a-9d37-2dfcfe282bf6",
      "token_id": "602e389f-ee2d-40c4-a5ef-ccd6c08e0d64",
      "create_date": "2019-09-12T21:52:01.000Z",
      "update_date": "2019-09-12T21:52:01.000Z"
    },
    {
      "id": "8c02a5a9-2618-4c34-b4a4-c58d003011b9",
      "balance": 92000000,
      "wallet_id": "f6d7f183-18b1-440c-8bc2-6e1859e8091c",
      "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
      "create_date": "2019-09-12T21:46:27.000Z",
      "update_date": "2019-09-12T21:46:27.000Z"
    }
  ],
  "total_pages": 1,
  "total_elements": 7,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "DESC",
      "property": "create_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "number_of_elements": 7,
  "size": 25,
  "number": 0
}

Get information for all token balances defined for your application. Optionally, you can pass wallet_id and/or token_id as a query parameter to retrieve token balance entries for a specific wallet and/or token.

HTTP REQUEST

GET /token_balance

FILTERS

Parameter Type Description
token_id UUID Retrieve the balances of a certain token
wallet_id UUID Retrieve the balacnes of a certain wallet

Retrieve a token balance

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/molecule/v1/token_balance/4d421d3d-9c18-4486-b98a-f66c5040dc3b"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
token_balance_id = '4d421d3d-9c18-4486-b98a-f66c5040dc3b'

try:
    api_response = api_instance.get_token_balance(token_balance_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_token_balance: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var tokenBalanceId = "4d421d3d-9c18-4486-b98a-f66c5040dc3b";

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

Example Response

{
  "id": "4d421d3d-9c18-4486-b98a-f66c5040dc3b",
  "balance": 1400000,
  "wallet_id": "2b96275a-8051-455a-9d37-2dfcfe282bf6",
  "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
  "create_date": "2019-09-12T22:04:12.000Z",
  "update_date": "2019-09-12T22:04:12.000Z"
}

Retrieve the information for a specific balance for a token. The unique token_balance_id must be provided. The endpoint returns the token_balance_id and details for the token balance specified.

HTTP REQUEST

GET /token_balance/{token_balance_id}

Crowdsale Token Supply

This endpoint keeps track of the available supply of crowdsale contracts. Token Supply entries are created automatically by the Event Handlers.

Field Type Description
id UUID The id for the token supply
token_id UUID The id of the associated token
available_supply double Number of tokens in circulation

List all token supplies

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token_supply"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

try:
    api_response = api_instance.get_token_supplies()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_token_supplies: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var paginationOpts = {};

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

Example Response

{
  "content": [
    {
      "id": "cb239351-3ad2-47ae-be2f-29f87a6bba4c",
      "available_supply": 3525000,
      "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
      "create_date": "2019-09-12T22:04:12.000Z",
      "update_date": "2019-09-12T22:04:12.000Z"
    },
    {
      "id": "9e97bef7-3538-4a92-948d-e76336959128",
      "available_supply": 200000,
      "token_id": "602e389f-ee2d-40c4-a5ef-ccd6c08e0d64",
      "create_date": "2019-09-12T22:01:23.000Z",
      "update_date": "2019-09-12T22:01:23.000Z"
    },
    {
      "id": "1fbf7bdd-44fa-438f-8a9d-464f014606b1",
      "available_supply": 4925000,
      "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
      "create_date": "2019-09-12T21:59:37.000Z",
      "update_date": "2019-09-12T21:59:37.000Z"
    },
    {
      "id": "b9d8f537-4800-4305-9c91-b52f65359c36",
      "available_supply": 250000,
      "token_id": "602e389f-ee2d-40c4-a5ef-ccd6c08e0d64",
      "create_date": "2019-09-12T21:56:35.000Z",
      "update_date": "2019-09-12T21:56:35.000Z"
    },
    {
      "id": "f3a66403-abe4-4f9c-9a25-d0c2a461741d",
      "available_supply": 5000000,
      "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
      "create_date": "2019-09-12T21:53:51.000Z",
      "update_date": "2019-09-12T21:53:51.000Z"
    }
  ],
  "total_pages": 1,
  "total_elements": 5,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "DESC",
      "property": "create_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "number_of_elements": 5,
  "size": 25,
  "number": 0
}

Get information for all token supplies defined for your application. Optionally, you can pass token_id as a query parameter to retrieve token supply entries for a specific token.

HTTP REQUEST

GET /token_supply

FILTERS

Parameter Type Description
token_id UUID Retrieve the token supply entries for a certain token

Retrieve a token supply

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/molecule/v1/token_supply/cb239351-3ad2-47ae-be2f-29f87a6bba4c"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))
token_supply_id = 'cb239351-3ad2-47ae-be2f-29f87a6bba4c'

try:
    api_response = api_instance.get_token_supply(token_supply_id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MoleculeApi->get_token_supply: %s\n" % e)
var apiInstance = new molecule_api.MoleculeApi();

var tokenSupplyId = "cb239351-3ad2-47ae-be2f-29f87a6bba4c";

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

Example Response

{
  "id": "cb239351-3ad2-47ae-be2f-29f87a6bba4c",
  "available_supply": 3525000,
  "token_id": "f213717a-0385-4c3b-8813-11df6247afda",
  "create_date": "2019-09-12T22:04:12.000Z",
  "update_date": "2019-09-12T22:04:12.000Z"
}

Retrieve information for a specific supply of a token. The unique token_supply_id must be provided. The endpoint returns details for the token supply specified including the available_supply and token_id.

HTTP REQUEST

GET /token_supply/{token_supply_id}

Workflows

Workflows are a set of API operations that when combined, allow you to accomplish a specific business case. Here are some of the most common workflows for your reference.

Blockchain Identity

1. Create a client

Nucleus Client Request Body

{
  "email": "[email protected]",
  "first_name": "Armando",
  "last_name": "Whitaker",
  "date_of_birth": "1982-03-21",
  "identification_number": "11223344",
  "phone_number": "185898658",
  "username": "[email protected]",
  "client_type": "individual",
  "is_verified": true,
  "metadata": {
    "credit_score": "850",
    "net_worth": "10000000",
    "occupation": "Business Owner",
    "accredited_investor": "true"
  },
  "address": [
    {
      "address_line1": "3725 Oak Drive",
      "address_line2": null,
      "city": "Tannersville",
      "postalcode": "12485",
      "country": "US",
      "state": "NY",
      "type": "Home"
    }
  ],
  "country_of_residence": "US",
  "income": 500000
}

Create a Nucleus Client to store personally identifiable data of a user.

POST /nucleus/v1/client.

Returns a client_id.
e.g. f40c3796-bfaa-4c16-a81e-34ebf9252364

2. Create a wallet

Create Wallet Request Body

{
  "name": "Armando Whitaker",
  "type": "individual",
  "clients": [
    {
      "nucleus_client_id": "f40c3796-bfaa-4c16-a81e-34ebf9252364",
      "client_wallet_association_type": "owner",
      "is_primary": true
    }
  ]
}

Create a Wallet for the client created in step 1.

POST /wallet - Pass the id of the client created in step 1 as the nucleus_client_id in the request body.

Returns a wallet_id.
e.g. 8248dfc1-b30c-4c64-b3e0-996d80e7bd2f

3. Generate and assign a key

Wallet Key Generator Request Body

{
  "wallet_id": "8248dfc1-b30c-4c64-b3e0-996d80e7bd2f"
}

Generate a Wallet Key for the wallet created in step 2.

POST /wallet_key/generator. - Pass the wallet_id from step 2 in the request body.

Creates a wallet_key_id and assigns to the wallet.

Security Tokenization

1. Create a Security

Create a Security Request Body

{
  "name": "2802 Claflin Avenue",
  "ticker": "28CA"
}

Create a Nucleus Security (or multiple securities if you are tokenizing a basket of assets) to store the details of your asset.

POST /nucleus/v1/security.

Returns a security_id for each security.
e.g. 5f660ed3-a4b3-49bf-bc4d-a888fca3d8c4

2. Create a Model

Create a Model Request Body

{
  "category": "Real Estate",
  "description": "100 2802 Claflin Avenue",
  "name": "2802 Claflin Token"
}

Create a Nucleus Model to store the details of your asset. This model will be a wrapper around your securities, and will be used to determine the weight of the assets composed within it.

POST /nucleus/v1/model.

Returns a model_id.
e.g. 13ee1d48-15cb-4a1e-8cde-c7191813fa51

3. Create a Model Holding

Create a Model Holding Request Body

{
  "model_id": "13ee1d48-15cb-4a1e-8cde-c7191813fa51",
  "security_id": "5f660ed3-a4b3-49bf-bc4d-a888fca3d8c4",
  "current_weight": 100,
  "strategic_weight": 100,
  "date": "2019-09-09"
}

Determine the weight of the assets composing a model using Nucleus Model Holdings. If a model is representing a single asset and not a basket, set the weight to 100 for the only security.

POST /nucleus/v1/model_holding. Returns a model_holding_id for each security assigned.

4. Create a Token

Create a Token Request Body

{
  "name": "2802 Claflin Token",
  "symbol": "28CA",
  "total_supply": 920000,
  "circulating_supply": 0,
  "nucleus_model_id": "13ee1d48-15cb-4a1e-8cde-c7191813fa51",
  "owner_wallet_id": "8248dfc1-b30c-4c64-b3e0-996d80e7bd2f",
  "offering_settings": {
    "start_date": "2019-09-09T00:00:00.000Z",
    "end_date": "2020-09-09T00:00:00.000Z",
    "rate": "6200"
  },
  "restrictions": {
    "min_age": 21,
    "min_credit_score": 750,
    "accreditation_required": "true",
    "kyc_required": "true"
  }
}

Create a SecurityToken.

If you haven’t created a wallet yet, follow the Identity workflow to create one.

POST /token - Pass the nucleus_model_id of the model you created in step 2 and the id of a wallet as the owner_wallet_id in the request body. If you plan on holding a crowdsale, include its settings as the rate, start_date, and end_date in the request body.

See resources for the list of all available restriction types.

Returns a token_id.
e.g. cb34121f-6333-44fc-aa04-3234fe472eba

5. Deploy a Token

Example: Token Deploy Request Body

{
  "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba"
}

Deploy the token on the blockchain. The whitelist_address and crowdsale_address of the token will be updated after a successful deployment.

POST /token/deploy - Pass the token_id from step 4 in the response body.

6. Whitelist another Wallet

Example: Token Whitelist Request Body

{
  "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba",
  "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de"
}

If you don’t have another wallet to whitelist to, create a new wallet using the Identity workflow. The Nucleus client associated with the new wallet should be passing all restriction requirements of the token to be whitelisted.

POST /token/whitelist - Pass the wallet_id of the new wallet you just created, and the token_id from step 4 in the response body.

Crowdselling

1. Deploy the Crowdsale Contract

Example: Crowdsale Deploy Request Body

{
  "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba"
}

Deploy the crowdsale conract of a token on the blockchain. The crowdsale_address of the token will be updated after a successful deployment.

If you haven’t created and deployed a SecurityToken yet, follow the Tokenization workflow to create and deploy one.

POST /crowdsale/deploy - Pass the token_id from the Tokenization workflow in the response body.

2. Fund the Crowdsale

Example: Crowdsale Fund Request Body

{
  "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba",
  "supply": 250000
}

Transfer a desired amount of tokens (e.g. 250,000) to its crowdsale contract.

POST /crowdsale/fund - Pass the token_id and desired amount as supply in the request body.

3. Purchase from the Crowdsale

Example: Crowdsale Fund Request Body

{
  "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba",
  "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  "amount": 1000
}

If you haven’t whitelisted the investor wallet yet, see step 6 of the Tokenization workflow.

Purchase a desired amount of tokens (e.g. 1,000) from a crowdsale.

POST /crowdsale/purchase - Pass the token_id, investor’s wallet_id and desired amount in the request body.

P2P Payments

Send Currency to Another Wallet

Example: Currency Transfer Request Body

{
  "sender_wallet_id": "8248dfc1-b30c-4c64-b3e0-996d80e7bd2f",
  "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  "currency_id": "3bdceb1d-8609-49fd-b765-703deaff8b89",
  "amount": 0.5
}

Transfer Ether from one wallet to another.

If you haven’t created any wallets, follow the Identity workflow.

POST /currency_transfer - Pass the sender_wallet_id, receiver_wallet_id, the currency_id for the desired currency and the desired amount in the request body.

See currency endpoint to see the list of currencies supported by your firm, and to add support for new ones.

Send SecurityToken to Another Wallet

Example: Currency Transfer Request Body

{
  "sender_wallet_id": "8248dfc1-b30c-4c64-b3e0-996d80e7bd2f",
  "receiver_wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
  "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba",
  "amount": 2500
}

Transfer a SecurityToken from one wallet to another.

If you haven’t created any wallets, follow the Identity workflow.
If you haven’t created any tokens, follow the Tokenization workflow.

POST /token_transfer - Pass the sender_wallet_id, receiver_wallet_id, the id for the desired token and the desired amount in the request body.

Resources

Restriction Types

You may set a value for each key below in the restrictions of a Token and it will be checked against the data stored in the Nucleus Client entity. For example, the key:value pair “min_annual_income”:”50000” will check the income field in the Nucleus Client entity to see if the value is greater than 50000.

Key Type Nucleus Client Field Description
min_age integer date_of_birth Investors older than this age will be allowed to invest
max_age integer date_of_birth Investors younger than this age will be allowed to invest
min_annual_income integer income Investors with an annual income higher than this number will be allowed to invest
max_annual_income integer income Investors with an annual income lower than this number will be allowed to invest
min_household_income integer metadata.household_income Investors with an household income higher than this number will be allowed to invest
max_household_income integer metadata.household_income Investors with an household income lower than this number will be allowed to invest
min_net_worth integer metadata.net_worth Investors with a net worth higher than this number will be allowed to invest
max_net_worth integer metadata.net_worth Investors with a net worth lower than this number will be allowed to invest
min_credit_score integer metadata.credit_score Investors with a credit score higher than this number will be allowed to invest
max_credit_score integer metadata.credit_score Investors with a credit score lower than this number will be allowed to invest
accreditation_required boolean metadata.accredited_investor Only accredited investors will be allowed to invest
kyc_required boolean is_verified Investors who are verified by a Know-Your-Customer vendor will be allowed to invest
include_country* [string] country_of_residence Only investors residing in these countries will be allowed to invest
exclude_country* [string] country_of_residence Investors residing outside of these countries will be allowed to invest

*Only ISO Alpha-2 country codes are allowed for include and exclude country restrictions. See Country Code reference table.