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
2019-09-24 change 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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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"
                }
            ],
            "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"
                },
                {
                    "nucleus_client_id": "b5f3abe9-bea2-4b31-9416-1080041efac2",
                    "client_wallet_association_type": "owner"
                }
            ],
            "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"
                }
            ],
            "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.

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.

Identity

Wallet

A wallet is where you can access the keys of your clients to sign blockchain transactions, and store the security tokens they purchase.

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
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"
                }
            ],
            "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"
                },
                {
                    "nucleus_client_id": "b5f3abe9-bea2-4b31-9416-1080041efac2",
                    "client_wallet_association_type": "owner"
                }
            ],
            "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"
                }
            ],
            "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.

HTTP REQUEST

GET /wallet

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"
        },
        {
            "nucleus_client_id": "dd707c48-599c-4edd-8055-04682e583483",
            "client_wallet_association_type": "admin"
        }
    ],
    "metadata": {},
    "update_date": "2019-09-12T19:47:38.972Z",
    "create_date": "2019-09-12T19:47:38.972Z"
}

Create a wallet under your firm. name, and type of the wallet must be provided. If associating multiple nucleus_clients, one client must have the owner association type. The endpoint returns a unique wallet_id that is used to manage the specific wallet and referenced in other endpoints.

A wallet_key_id can only be associated with a wallet through POST /wallet_key. It is not allowed to create a wallet_key_id through POST /wallet.

See Create a Client and a Wallet for an example workflow.

HTTP REQUEST

POST /wallet

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 optional 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
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"
        },
        {
            "nucleus_client_id": "dd707c48-599c-4edd-8055-04682e583483",
            "client_wallet_association_type": "admin"
        }
    ],
    "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"
        },
        {
            "nucleus_client_id": "dd707c48-599c-4edd-8055-04682e583483",
            "client_wallet_association_type": "admin"
        }
    ],
    "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.

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, you can 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
metadata map Custom information associated with the wallet key 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 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 callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.getWalletKeys(callback);

Example Response

{
    "content": [
        {
            "id": "a82a5ee3-55ba-405a-b202-4bf0402614d3",
            "key_id": "edee6ed820bf487e886253179278bc51",
            "key_server": "azure",
            "address": "0x7b51ada4de0e188bf3f2f42b54266eee495353c5",
            "private_key": null,
            "secondary_id": null,
            "create_date": "2019-09-12T19:55:31.000Z",
            "update_date": "2019-09-12T19:55:31.000Z",
            "metadata": {}
        },
        {
            "id": "00c00c35-8a6c-47a7-a15e-ef297475d212",
            "key_id": "a61c38a397e6474894fb9bfec2eb7bed",
            "key_server": "azure",
            "address": "0xdc6e90ca52e92f16437e6b5ae9aa76da4f964745",
            "private_key": null,
            "secondary_id": null,
            "create_date": "2019-09-12T20:08:33.000Z",
            "update_date": "2019-09-12T20:08:33.000Z",
            "metadata": {}
        },
        {
            "id": "94707d27-7aae-4cc8-b925-afe519c00537",
            "key_id": "f2eb062c446f48d0be8d07e796583935",
            "key_server": "azure",
            "address": "0xca94e93d1e99cd7756f2f243af717e7e067f5b8c",
            "private_key": null,
            "secondary_id": null,
            "create_date": "2019-09-12T20:09:19.000Z",
            "update_date": "2019-09-12T20:09:19.000Z",
            "metadata": {}
        }
    ],
    "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",
    "metadata": {},
    "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",
    "metadata": {},
    "update_date": "2019-09-12T20:02:19.805Z",
    "create_date": "2019-09-12T20:02:19.805Z"
}

If your firm chooses to generate private and public key pairs for its clients, you can use this endpoint.

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

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",
    "metadata": {},
    "update_date": "2019-09-12T20:02:21.723Z",
    "create_date": "2019-09-12T20:02:21.723Z"
}

If your firm chooses to store existing private and public address pairs for its clients that haven’t been generated through Hydrogen, you can use this endpoint.

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,
    "secondary_id": null,
    "create_date": "2019-09-12T19:55:31.000Z",
    "update_date": "2019-09-12T19:55:31.000Z",
    "metadata": []
}

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

HTTP REQUEST

GET /wallet_key/{wallet_key_id}

Balance

Token Balance

This endpoint keeps track of wallet token balances. A new entry will be generated automatically every time the blockchain event listeners hear about a Transfer event.

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
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 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 callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.getTokenBalances(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.

HTTP REQUEST

GET /token_balance

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}

Tokenization

Token

Tokenization is the practice of digitally representing real world assets, such as real estate, art, stocks etc. By adding various Know Your Customer (KYC) restrictions on a token and its crowdsale process, Molecule allows token issuers to create security tokens. The token endpoint is used to store the blockchain (on-chain) data of a token in a traditional (off-chain) database.

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
total_supply double The total supply of the security token
circulating_supply double The amount of tokens in circulation
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
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
create_date timestamp Timestamp for the date and time that the document was created
update_date timestamp Timestamp for the date and time that the that the document was last updated

Off-Chain Operations

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

List all tokens

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.getTokens(callback);

Example Response

{
    "content": [
        {
            "id": "1b8cc79d-b409-4d35-94e9-a902ab1683e6",
            "name": "MAAG Token",
            "symbol": "MAAG",
            "total_supply": 1000000,
            "circulating_supply": 250000,
            "nucleus_model_id": "8aff8394-ff73-4436-b1eb-3cfedb1a490f",
            "owner_wallet_id": "eb32c593-a452-41ff-8c5e-807d106c6486",
            "contract_address": "0x655893A8F050C7Fa40Aaf46E19Fd94a08cd1C824",
            "crowdsale_address": "0xe1219f5E3E2d42B103C44Db265aBd3eddF1CAC67",
            "restrictions": {
                "min_age": 21,
                "kyc_required": true
            },
            "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",
            "total_supply": 92000000,
            "circulating_supply": 5000000,
            "nucleus_model_id": "1f80f04f-4ea6-4231-bef4-d7c0098d6d30",
            "owner_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
            "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
  -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://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",
    "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.

See Create Securities & Models for an example workflow.

In order to create a token, the model must already be present in Nucleus. To identify the appropriate nucleus_model_id, use the GET /nucleus/v1/model endpoint to see all models for your firm.

The rate determines the exchange rate of the token during the token offering. It shows how many tokens will be sent to the investor for every 1 ETH; e.g. in the provided TCT example, the rate is set to 1000. If an investor were to invest 1 ETH in this token offering, the investor would receive 1000 TCT.

See Create and Deploy a Token for an example workflow.

HTTP REQUEST

POST /token

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
circulating_supply double optional The amount of tokens in circulation. Defaults to 0
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
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 required 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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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",
    "total_supply": 920000,
    "circulating_supply": 0,
    "nucleus_model_id": "1f80f04f-4ea6-4231-bef4-d7c0098d6d30",
    "owner_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
    "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
-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://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",
    "total_supply": "92000000",
    "circulating_supply": 0,
    "nucleus_model_id": "1f80f04f-4ea6-4231-bef4-d7c0098d6d30",
    "owner_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
    "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.

HTTP REQUEST

PUT /token/{token_id}

Delete a token

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 endpoints that interact with the blockchain. Most of these endpoints will trigger events, which will trigger listeners to create new entries in your off-chain database.

Deploy a token

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
  -H "Content-Type: application/json" \
  -d '{
        "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c"
      }' "https://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": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
    "name": "2802 Claflin Avenue",
    "symbol": "28CA",
    "total_supply": 92000000,
    "circulating_supply": 0,
    "nucleus_model_id": "1f80f04f-4ea6-4231-bef4-d7c0098d6d30",
    "owner_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
    "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:46:27.509Z",
    "offering_settings": {
        "start_date": null,
        "end_date": null,
        "rate": 36000
    },
    "metadata": []
}

Deploys a token on the Ethereum blockchain. The token_id must be provided. The contract_address and crowdsale_address of the provided token must be null, and the provided token must have a rate defined.

After being notified about the deployment event, the event listeners will update the contract_address and crowdsale_address of the token with the newly generated smart contract addresses, and create a new token_balance entry for the owner reflecting its new balance.

If the token has a circulating_supply defined at the time of deployment, this request will internally call the POST /token/crowdsale method, and transfer the selected circulating_supply to the tokens crowdsale address.

After the contracts are deployed, the token_id of the token will be added to token_whitelists array of the owner.

See Create and Deploy a Token for an example workflow.

HTTP Request

POST /token/deploy

ARGUMENTS

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

Crowdsale a token

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
  -H "Content-Type: application/json" \
  -d '{
        "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
        "supply": "5000000"
      }' "https://api.hydrogenplatform.com/molecule/v1/token/crowdsale"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

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

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

var payload = new molecule_api.TokenCrowdsalePayload();
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.postTokenCrowdsale(payload, callback);

Example Response

{
    "id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
    "name": "2802 Claflin Avenue",
    "symbol": "28CA",
    "total_supply": 92000000,
    "circulating_supply": "5000000",
    "nucleus_model_id": "1f80f04f-4ea6-4231-bef4-d7c0098d6d30",
    "owner_wallet_id": "e1711964-8e98-4a33-a4bf-ce9775b4c3b6",
    "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.984Z",
    "offering_settings": {
        "start_date": null,
        "end_date": null,
        "rate": 36000
    },
    "metadata": []
}

Transfers the specified supply to the crowdsale address of the token so that investors can buy them. A token should be deployed on the blockchain before making this call. The supply provided in the request body can’t be greater than the token’s non-circulating supply (token_supply - circulating_supply).

The transfer of the tokens will emit an event. Upon hearing it, the listeners will create one token_balance and one token_supply entry.

token_balance: The new, reduced token balance for the owner. As the owner transfers some of their supply to the crowdsale contract, they will have a lower token balance.

token_supply: The new, increased token supply for the crowdsale contract. As the crowdsale contract will receive tokens from the owner, it will have a higher available token supply.

See Crowdsale a Token for an example workflow.

HTTP Request

POST /token/crowdsale

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.

Whitelist an investor

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
  -H "Content-Type: application/json" \
  -d '{
        "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
        "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de"
      }' "https://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)

{
    "message": "User whitelisted successfully.",
}

Whitelists the specified wallet_id for the specified token_id.

The whitelisting operation will emit an event. Upon hearing the event, the listener will add the token_id to the whitelisted wallet’s token_whitelists array.

See Whitelist and Purchase a Token for an example workflow.

HTTP Request

POST /token/whitelist

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.

Purchase a token

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
  -H "Content-Type: application/json" \
  -d '{
        "token_id": "f995efbb-106f-4bc9-a43f-967e11cbbe2c",
        "wallet_id": "cffc54ca-9f4d-40a2-a62b-ebd6dccf37de",
        "amount": "750000"
      }' "https://api.hydrogenplatform.com/molecule/v1/token/purchase"
api_instance = molecule_api.MoleculeApi(molecule_api.ApiClient(configuration))

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

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

var payload = new molecule_api.TokenPurchasePayload();
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.postTokenPurchase(payload, callback);

Example Response (200)

{
    "message": "750000 tokens purchased successfully.",
}

This endpoint first calculates 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_id has enough ETH balance, this endpoint will transfer the investor’s ETH to the issuer, and transfer the equivalent amount of tokens from the token’s crowdsale contract to the investor.

The transfer of the tokens will emit an event. Upon hearing it, the listeners will create one token_balance and one token_supply entry.

token_balance: Investor’s new token balance.

token_supply: The new, decreased token supply for the crowdsale contract. As the crowdsale contract will send some of its tokens to the investor, it will have a lower available token supply.

See Whitelist and Purchase a Token for an example workflow.

HTTP Request

POST /token/purchase

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.

Token Supply

This endpoint keeps track of the available supply in crowdsale contracts. A new entry will be generated automatically every time the blockchain event listeners hear about a Transfer event involving a crowdsale contract.

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
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 token supplies

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.getTokenSupplies(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.

HTTP REQUEST

GET /token_supply

Retrieve a token supply

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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. We have included many of the most common workflows below for your reference.

Onboarding

Create a Client and a Wallet

Step 1: Create Client

{
    "id": "f40c3796-bfaa-4c16-a81e-34ebf9252364",
    "secondary_id": null,
    "create_date": "2019-09-12T01:23:31.000+0000",
    "update_date": "2019-09-12T01:23:31.000+0000",
    "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,
    "is_active": 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
}

Step 2: Create Wallet

{
    "id": "8248dfc1-b30c-4c64-b3e0-996d80e7bd2f",
    "name": "Armando Whitaker",
    "type": "individual",
    "is_active": true,
    "secondary_id": null,
    "create_date": "2019-09-18T13:45:31.000Z",
    "update_date": "2019-09-18T13:46:51.000Z",
    "clients": [
        {
            "nucleus_client_id": "f40c3796-bfaa-4c16-a81e-34ebf9252364",
            "client_wallet_association_type": "owner"
        }
    ],
    "metadata": {},
    "token_whitelists": []
}
  1. Create a Nucleus Client using POST /nucleus/v1/client. Returns a client_id.

  2. Create a Wallet using POST /wallet. Returns a wallet_id.
      2a. Assign the client to the account by providing the nucleus_client_id from step 1 in the clients field.
      2b. Assign the role of the client using client_wallet_association_type in the clients field.

Generate and Assign a Wallet Key

Step 1: Generate Wallet Key

{
    "id": "25e18e5a-4575-4358-acc1-975ec6c0a0e9",
    "key_id": "88a85bca483a4f709b386bea57e6499a",
    "key_server": "azure",
    "address": "0x0c330b9f9f2e1231fbff8f253fab7545ce481976",
    "metadata": {},
    "update_date": "2019-09-18T13:46:51.952Z",
    "create_date": "2019-09-18T13:46:51.952Z"
}

Updated Wallet

{
    "id": "8248dfc1-b30c-4c64-b3e0-996d80e7bd2f",
    "wallet_key_id": "25e18e5a-4575-4358-acc1-975ec6c0a0e9",
    "name": "Armando Whitaker",
    "type": "individual",
    "is_active": true,
    "secondary_id": null,
    "create_date": "2019-09-18T13:45:31.000Z",
    "update_date": "2019-09-18T13:46:51.000Z",
    "clients": [
        {
            "nucleus_client_id": "f40c3796-bfaa-4c16-a81e-34ebf9252364",
            "client_wallet_association_type": "owner"
        }
    ],
    "metadata": {},
    "token_whitelists": []
}
  1. Generate a Wallet Key for a Wallet using POST /wallet_key/generator. Creates a wallet_key_id and assigns to the wallet.
      1a. Pass the wallet_id from step 2 of Create a Client and a Wallet in the request body.

The id of the generated wallet key will be automatically assigned to the wallet via the wallet_key_id field.

Tokenization

Create Securities and a Model

Three Nucleus endpoints are used to store the details of a real-world assets being tokenized.

Example: Security

{
    "id": "5f660ed3-a4b3-49bf-bc4d-a888fca3d8c4",
    "name": "2802 Claflin Avenue",
    "ticker": "28CA"
}

Example: Model

{
    "id": "13ee1d48-15cb-4a1e-8cde-c7191813fa51",
    "category": "Real Estate",
    "description": "100 2802 Claflin Avenue",
    "name": "2802 Claflin Token"
}

Example: Model Holding

{
  "id": "7960419c-c098-4450-8cc5-866b7385230b",
  "current_weight": 100,
  "strategic_weight": 100,
  "date": "2019-09-09",
  "model_id": "13ee1d48-15cb-4a1e-8cde-c7191813fa51",
  "security_id": "5f660ed3-a4b3-49bf-bc4d-a888fca3d8c4"
}
  1. Create a Security (or multiple securities if you are tokenizing a basket of assets) using POST /nucleus/v1/security. Returns a security_id for each security.

  2. Create a Model using POST /nucleus/v1/model. This model will be a wrapper around your securities, and will be used to determine the weight of the assets composed within it. Returns a model_id.

  3. Assign securities to a model using POST /nucleus/v1/model_holding. Model Holdings will determine the weights of the securities in a model. If a model is representing a single asset and not a basket, set the weight to 100 for the only security. Returns a model_holding_id for each security assigned.

Create and Deploy a Token

Example: Token after Create

{
    "id": "cb34121f-6333-44fc-aa04-3234fe472eba",
    "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"
    },
    "metadata": {},
    "update_date": "2019-09-18T14:02:17.299Z",
    "create_date": "2019-09-18T14:02:17.299Z"
}

Example: Token after Deploy

{
    "id": "cb34121f-6333-44fc-aa04-3234fe472eba",
    "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",
    "contract_address": "0x1785fc4EC8ab9132b140108B328cd326CF87F060",
    "crowdsale_address": "0xc62e1e677C3eb35760e87D1B931Cb17429902A9D",
    "create_date": "2019-09-18T14:02:17.000Z",
    "update_date": "2019-09-18T14:23:53.161Z",
    "offering_settings": {
        "start_date": "2019-09-09T00:00:00.000Z",
        "end_date": "2020-09-09T00:00:00.000Z",
        "rate": 6200
    },
    "metadata": {},
    "restrictions": {
        "min_credit_score": "750",
        "accreditation_required": "true",
        "min_age": "21",
        "kyc_required": "true"
    }
}

Example: Token Balance of the Owner after Deploy

{
    "id": "b42a3197-8f66-4895-8699-587473eb5c93",
    "balance": 920000,
    "wallet_id": "8248dfc1-b30c-4c64-b3e0-996d80e7bd2f",
    "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba",
    "create_date": "2019-09-18T14:23:53.000Z",
    "update_date": "2019-09-18T14:23:53.000Z"
}
  1. Create a Token using POST /token. Returns a token_id.
      1a. Assign a model for the token using nucleus_model_id from step 2 of Create Securities and a Model.
      1b. Assign restrictions for the token using the restrictions object. See Restriction Types for the list of all available restrictions.
      1c. Set a rate, a start_date, and an end_date for the initial offering using offering_settings.

  2. Deploy the token on the blockchain using POST /token/deploy. Returns the details of the updated token after assigning newly generated contract_address and crowdsale_address.
      2a. Pass the token_id from step 1 in the request body.

After being deployed on the blockchain, the total_supply amount of tokens will be minted and transferred to the owner. A new Token Balance entry will be created to track the owner’s balance.

Crowdsale a Token

Example: The new Token Balance of the owner after Crowdsale

{
    "id": "e1ee01a5-2810-4611-a7e4-833fc05bf698",
    "balance": 670000,
    "wallet_id": "8248dfc1-b30c-4c64-b3e0-996d80e7bd2f",
    "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba",
    "create_date": "2019-09-18T15:29:26.000Z",
    "update_date": "2019-09-18T15:29:26.000Z"
}

Example: The new available Token Supply of the Token after Crowdsale

{
    "id": "04dda5c0-647a-4bf1-94c6-b272186987db",
    "available_supply": 250000,
    "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba",
    "create_date": "2019-09-18T15:29:26.000Z",
    "update_date": "2019-09-18T15:29:26.000Z"
}

Example: The Token after Crowdsale

{
    "id": "cb34121f-6333-44fc-aa04-3234fe472eba",
    "name": "2802 Claflin Token",
    "symbol": "28CA",
    "total_supply": 920000,
    "circulating_supply": 250000,
    "nucleus_model_id": "13ee1d48-15cb-4a1e-8cde-c7191813fa51",
    "owner_wallet_id": "8248dfc1-b30c-4c64-b3e0-996d80e7bd2f",
    "contract_address": "0x1785fc4EC8ab9132b140108B328cd326CF87F060",
    "crowdsale_address": "0xc62e1e677C3eb35760e87D1B931Cb17429902A9D",
    "secondary_id": null,
    "create_date": "2019-09-18T14:02:17.000Z",
    "update_date": "2019-09-18T15:29:26.833Z",
    "offering_settings": {
        "start_date": "2019-09-09T00:00:00.000Z",
        "end_date": "2020-09-09T00:00:00.000Z",
        "rate": 6200
    },
    "metadata": {},
    "restrictions": {
        "min_credit_score": "750",
        "accreditation_required": "true",
        "min_age": "21",
        "kyc_required": "true"
    }
}
  1. Transfer the selected amount (e.g. 250,000) of tokens to its crowdsale contract using POST /token/crowdsale.
      1a. Pass the token_id from step 1 of Create and Deploy a Token and the selected amount as supply in the request body.

After transferring the tokens to the crowdsale contract, a new Token Balance entry for the owner, and a new Token Supply entry for the token will be created. The token balance entry will reflect the new decreased balance of the owner as it transferred some of its tokens to the crowdsale contract. The token supply entry will reflect the new increased balance of the crowdsale contract of the token as it received new tokens from the owner.

The circulating_supply field of the token will also be updated. This field tracks the total amount of tokens the owner has transferred to the crowdsale contract and made available to the public for investing.

Whitelist and Purchase a Token

Example: Investor’s Wallet after getting whitelisted

{
    "id": "75a0757b-2e1a-4ee5-a000-dae7b755e095",
    "wallet_key_id": "94c48396-cfe5-48a5-9037-9a4c1417ba45",
    "name": "Jong LLC",
    "type": "business",
    "is_active": true,
    "secondary_id": null,
    "create_date": "2019-09-16T21:19:15.000Z",
    "update_date": "2019-09-18T15:41:36.000Z",
    "clients": [
        {
            "nucleus_client_id": "70b354f8-4eb6-4d65-8d00-4ee690dd99e4",
            "client_wallet_association_type": "admin"
        },
        {
            "nucleus_client_id": "2b5a865c-9932-45b9-8a28-81b214fc187f",
            "client_wallet_association_type": "owner"
        }
    ],
    "metadata": {},
    "token_whitelists": [
        {
            "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba",
            "role": null,
            "sell_restriction_date": null,
            "buy_restriction_date": null
        }
    ]
}

Example: The new Token Balance of the investor after Purchase

{
    "id": "66391e49-dcf9-4dc8-9928-868656cdcfb2",
    "balance": 100,
    "wallet_id": "75a0757b-2e1a-4ee5-a000-dae7b755e095",
    "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba",
    "create_date": "2019-09-18T15:52:43.000Z",
    "update_date": "2019-09-18T15:52:43.000Z"
}

Example: The new available Token Supply of the token after Purchase

{
    "id": "1ffea665-4c25-4034-a8ee-afd1c92ce380",
    "available_supply": 249900,
    "token_id": "cb34121f-6333-44fc-aa04-3234fe472eba",
    "create_date": "2019-09-18T15:52:43.000Z",
    "update_date": "2019-09-18T15:52:43.000Z"
}
  1. Whitelist a prospective investor by using POST /token/whitelist.
      1a. Create a wallet and wallet key for the investor by repeating the Onboarding workflow.
      1b. Pass the token_id from step 1 of Create and Deploy a Token and the wallet_id from step 1.

  2. Purchase the selected amount (e.g. 100) of tokens from the crowdsale contract by using POST /token/purchase.
      1a. Pass the token_id and wallet_id from step 1, and the selected amount as amount in request body.

If the Nucleus client associated with the investor’s wallet passes all restriction requirements of the token, the investor will be added to the token’s whitelist. The investor’s wallet will update to reflect the successful whitelisting operation. If there are multiple Nucleus clients associated with the investor’s wallet, the nucleus_client_id with the client_wallet_association_type = owner will be checked for restrictions.

After successfully purchasing the tokens, a new Token Balance entry for the investor, and a new Token Supply entry for the token will be created. The token balance entry will reflect the new increased balance of the investor as it purchased tokens from the crowdsale contract. The token supply entry will reflect the new decreased balance of the crowdsale contract of the token as it sent tokens to the investor.

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