Introducing OST Ledger & Balance APIs to Integrate Branded Token Balances and Transaction Histories into Token Economies

In OST Alpha II from April to May 2018, our Partner Companies and developer teams involved in the OST Alpha II POC Challenge were able to mint their own Branded Tokens with OST technology and integrate it into their apps to execute token transfers triggered by in-app actions.

A missing piece in OST Alpha II was the ability to create unique wallet-interfaces for each end-user and to show user balances and transaction histories.

Today, in preparation for OST Alpha III, we have released the OST Ledger and Balance APIs. These APIs enable developers to begin to create and customize embedded wallets within their apps and services, show user’s token balances, and display transaction histories.

Here’s a quick breakdown of both APIs:

• Ledger API: This API enables developers to create a transaction overview dashboard for its end-users. Read how to list user transactions in the Ledger User Guide: https://dev.ost.com/docs/api_ledger.html
• Balance API: This API allows developers to embed a simplified, current token balance overview for its end-users.

Here’s an example of how to utilize the Balance API to retrieve user balances. The full documentation can be found in the OST developer resource center.

Getting User Balances

To get a user’s balance, you can use the /balance/{user_id} API.

ost_balance_object = ost_sdk.services.balances # initializes the balance object
ost_balance_object.get({id: 'd66a40d0-b2fa-4915-b6d2-46bbe644278a'}).to_json   # Fetch the user's balance

This API returns a balance object. The balance details in the object are in (BT) your Branded Tokens.

Example Balance Response Body

{
  "success": true,
  "data": {  
      "result_type": "balance",
      "balance":  {  
         "available_balance": "800.243366506781137",
         "airdropped_balance": "140.231683253390568746",
         "token_balance": "660.011683253390568746"
      }
   }
}

Fiat and OST Equivalents
In order to display OST and USD equivalent of these Branded Tokens, you can use the Token Details API.

ost_token_object = ost_sdk.services.token  #initializes the token object
ost_token_object.get({}).to_json    # fetches the token economy details

The conversion_factor in response to a GET to /token refers to the factor you chose at the time of the Token Economy set up in OST KIT. Multiplying this number with the available_balance in balance object will give you the OST equivalents values of the Token balances.

Multiplying the result with price_points that we get in /token response will give you the USD equivalent value.

Example Token Response Body

{
  "success": true,
  "data": {
    "result_type": "token",
    "token": {
      "company_uuid": 1028,
      "name": "Happy Token",
      "symbol": "HAP",
      "symbol_icon": "token_icon_1",
      "conversion_factor": "14.86660",
      "token_erc20_address": "0x546d41730B98a24F2dCfcdbE15637aD1939Bf38b",
      "simple_stake_contract_address": "0x54eF67a54d8b77C091B6599F1A462Ec7b4dFc648",
      "total_supply": "92701.9999941",
      "ost_utility_balance": [
        [
          "1409",
          "87.982677084999999996"
        ]
      ]
    },
    "price_points": {
      "OST": {
        "USD": "0.177892"
      }
    }
  }
}

Alice Likes Jason
To execute the Like action, you will need Alice and Jason’s IDs. They were returned when you created Alice and Jason. And you would need the action ID that was returned when you created the action.

ost_transaction_object = ost_sdk.services.transactions  #initializes transaction module.
ost_transaction_object.execute({from_user_id:'d66a40d0-b2fa-4915-b6d2-46bbe644278a', to_user_id:'df7153f1-c1cf-4ae2-b980-f04df1e68bb3', action_id:'22613'})
 # returns object with ID of executed transaction

This user-flow shows you what you could tell (and show) your users about this action:

Now, to display Alice’s user balance, you can call the Balance API just like you did earlier- using her user_id.

Basic Wallet Setup Guide

In addition to the documentation above, we created a Setup Guide to help developers quickly get up to speed on developing wallet-like features for their website/app. The Basic Wallet Setup Guide walks you through the initial setup, how to airdrop tokens to new users, how to retrieve user balances and how to show user transactions. You can find the Setup Guide in our developer center: https://dev.ost.com/docs/guide_wallet_setup.html.

Both Ledger and Balance APIs are fully compatible with our Ruby, JavaScript, PHP, and Java SDKs. An overview of all available documentation for our APIs and SDKs can be found at https://dev.ost.com; where you can also view the updated changelog.

Note: The Ledger and Balance APIs do not yet support key-management, signing of transactions, or buy-in and cash-out. Those features remain under development for future versions.

In addition to the new APIs released today, this release also includes upgrades to support scalability and flexibility for all of our APIs. Specifically, we moved OST KIT action tasks triggered by the API — to execute on-chain events — from MySQL to DynamoDB. This allows us to implement horizontal scaling for OST KIT actions in preparation of multi-chain capabilities.

—

A big thank you to the developer community for their continuous feedback and we look forward to seeing the new Ledger and Balance APIs put to use in the upcoming OST Alpha III, which we will be announcing shortly.

About OST
OST is building the complete blockchain infrastructure and toolkit for business. We strive to be the blockchain technology partner of choice for businesses of all sizes and levels of technical sophistication, enabling any business to create, launch, and manage their own branded digital token economy powered by OpenST protocols and OST blockchain management software. The OpenST protocol enables companies to launch branded token economies on highly scalable, open, cryptographically auditable side blockchains. OST has offices in Berlin, New York, Hong Kong, and Pune India. For more information, please visit: https://ost.com/