Introducing the Tokenized SDK

Back in March, we revealed the Tokenized REST API, the first step towards our vision of a world of groundbreaking financial applications powered by the Tokenized Protocol and the blockchain. The API empowers our customers to take advantage of all the features of our platform, like blockchain-backed smart contracts and a range of standard asset types. It’s great and you should check it out, but we know that harnessing the power of a rich REST API directly can be a lot of work: managing multifactor authentication, data fetching and refreshing, formatting of assets and currency amounts, and more…Wouldn’t it be great if this work was done for you by the experts who designed the API, and you could focus on building the next financial revolution?

Today we’re introducing the Tokenized JavaScript SDK, an easy-to-use NPM library that you can integrate straight into any JavaScript web, mobile, or desktop app. Plug in your Tokenized Platform API key (talk to us now about becoming an early partner), and the library handles all the details of interacting with our REST API for you, meaning integrating a Tokenized feature is, in many cases, just a single line of code. We’re supporting React as our recommended UI framework at first — take a look at the example web app we’ve built on GitHub, where you can also find the SDK documentation. If you’re used to working on React UIs, you’ll find the minimal code pretty easy to follow. Here’s the demo app in action, handling MFA sign in and displaying my account’s testing assets:

Tutorial

So let’s dive in and do some actual coding with the SDK. I’ll take you step-by-step through adding a new view of the user’s assets, and show you how easy it is to work with Tokenized Platform data using the new SDK. For reference, all the code below is available in the blog-tutorial-2021-06-02 branch on GitHub.

Let’s start by getting our bearings in the SDK’s example app code. The startup code for the app, in index.js, creates a new TokenizedApi session manager object, passing in a configuration object, which selects the default Tokenized platform API key. The TokenizedApi object is then passed into the <TokenizedApiProvider> component, which supplies it as context to all the SDK hooks in the child component tree. Refer to the authenticated routing inApp.js, and the sign-in form inLoginScreen.js, if you want to know more about how sign in works. For this tutorial though, we’ll let the existing code do its thing establishing the session, and move straight to adding something new.

Step 1: Create a new page to work in

The “Activity” page in the example app is currently a placeholder. In this preview release of the SDK, many features are still to be implemented — we plan to fill in the gaps rapidly in due course, but for the purposes of this tutorial, this blank page can serve as a convenient sandbox. Create an empty <TutorialPage> component in a new file, TutorialPage.js, like this (I’ll leave the details of how to add it to the /activity route in App.js up to you):

That gives us a new page with a simple title in the app:

Step 2: Asset summary UI design

Let’s suppose we want to create a compact summary view of the user’s assets and liabilities — perhaps to be used as one tile in an overview screen for the user’s whole profile. The example app’s UI is built with the Bulma CSS framework, which provides a nice multi-line tag element that looks good for this purpose. Let’s copy their example HTML into the new component, adding a box as a container, and a title:

Step 3: Querying the assets with the SDK

OK, that looks pretty good. Time to hook it up to the actual list of Tokenized assets. To do that, we need the useFilteredBalances() hook from the SDK. It provides a lot of information about each asset, but for now we’ll just pull out the asset name, and either its value or its issuedLiability, formatted in the display currency:

So with just a few lines of easy-to-follow code, we’ve been able to assemble a lot of information from the API, pull what we wanted out of it, and format it in a natural way. Here are some things to notice about the code, and what the SDK is doing for us behind the scenes:

• The useFilteredBalances data includes NumberFormatOptions objects for every currency quantity, which can be passed straight into the Intl.NumberFormat constructor, taking care of finding the right currency symbol, outputting the correct number of decimal places, and formatting the number in the correct format for the user’s locale.
• The SDK makes it easy to display quantities in the user’s display currency (my display currency is set to GBP), by performing the exchange rate conversions behind the scenes for you. Every quantity is also provided as an unconverted token count, and in the natural currency of each asset as appropriate. Simply pick out the formatting you need for each quantity you render.

• If you watch what’s going on in the browser’s network debugger, you’ll see that loading the new page sets off a complex sequence of more than 70 requests to the REST API, as the SDK checks asset and currency information, and looks up exchange rates. It’s all done efficiently in a few seconds, and the results are checked, cached, and combined into a form that’s easy for you to render, as we’ve seen.
• If you leave the network debugger open, you’ll see that every minute one more REST request is sent to the main balances endpoint. This is the SDK checking for updates to any of the data we’ve queried, at a rate that’s appropriate for the type of data. So if someone transfers some tokens to you, the UI we’ve just built will update automatically shortly afterwards, without us having to write any code to handle that.

Step 4: Finishing touches

Just for fun, let’s see how much extra information we can pack into this list, by using more of the data the SDK is providing with some conditional formatting:

The result is probably a bit much to be honest, but it serves to illustrate how our SDK takes away the hard work and complexity of finding the data you need, and frees you to concentrate on the details of your UI:

So that’s the Tokenized JavaScript SDK. Harness the power of our platform in your app, with almost no effort. As of now, the SDK is available to selected partners to try out — contact us if you’d like to be included. It’s early days for the product, but you’ve seen how well it already works for displaying users’ assets: maximum flexibility with minimum complexity. In due course we plan to offer SDK support for every Tokenized feature in the same way.