Tutorial: Omnibus wallet custody with Tangany Settlement API

The Tangany Settlement API offers you the opportunity of storing digital assets as collective custody, also known as “omnibus wallets”. The goal is to leverage only one or a few crypto wallets for all of your customers. This helps in avoiding unnecessary network fees and also increases transaction speeds. But it requires an additional accounting system that would manage the account balances of individual customers, the Tangany Settlement API.

This tutorial follows a very simple setup that might be different from the real-world setups where assets will be transferred to the omnibus wallet after they have already been booked in transactions in the Settlement API.

Duration: 15 minutes

Level: Intermediate

Content:

• Creating accounts

• Depositing & transferring funds

• Retrieving balances

• Retrieving transactions

Requirements

1. You should already be familiar with the Tangany Custody API

2. You should already be familiar with the Tangany Customers API

3. Demo account: contact Tangany’s sales & support team to obtain a free demo account to use the Tangany Settlement API, if you don’t have one already.

4. Postman: visit our public postman collection. I recommend using a Postman desktop client to avoid cross-browser request issues.

Authentication

Before you can start calling the Tangany Customers API you need to ensure you’re authenticated. Open your Postman client with your already imported Tangany Settlement API collection. Tangany provides an environment variable preset called Default (public) which can be found in the upper right on Postman. Edit this environment preset and fill in the subscription you received from Tangany’s sales team.

tangany-subscription

Head over to your imported Postman Collection “Tangany Settlement API”. We will start with an easy task. First, let’s get a list of your currently existing ledgers by calling

GET /ledgers

The result should be an empty list:

List all ledgers

Great! Your client is working, so now we can start using the Tangany Settlement API!

Creating your first ledger

The first step is to create a ledger. A ledger is a workspace for your transactions. It can be also thought of as a book in accounting or as a separate virtual blockchain. We recommend using one ledger per omnibus wallet.

Head over to the “Create ledger” endpoint to create your first ledger:

Create ledger

Creating accounts

The second step is to create accounts. Accounts represent actors who can send and receive funds on a ledger.

Every account should be linked to a customer previously created in the Customers API via the owners property.

The exception here is special purpose accounts, which do not require a customer ID.

First, we’re going to create a special-purpose account called bankroll which will act like a broker. We will transfer from and to this account to represent asset trades.

Create bankroll account

We will also create a customer account for our first customer, John Smith and link it to a customer entity in the Customers API via the owners property:

Create customer account

Transferring funds

After creating our accounts we can now transfer funds between accounts.

However, we still don’t have anything to transfer.

Let’s fund the bankroll account with some bitcoin.

For this we will use a special purpose transaction, referred to as a Funding transaction.

The first step is to transfer the value to the omnibus wallet on the blockchain. After the transaction is mined, you can create a virtual mirror transaction by providing the hash of the blockchain transaction.

Head over to the Create deposits request and mirror your blockchain transaction:

Fund bankroll account

As you can see the recipient of this deposit is the bankroll account. We also need to provide the value of the deposit and the actual transaction hash of the transfer.

After sending the transaction we can check the balance of the bankroll account with the Get account balance request:

Check the bankroll account balance

Great! We now have 1 BTC to transfer.

We can also get the total balance of the assets in the system, head over to the get asset balances endpoint to get a list of asset balances. Those balances should match the real blockchain balances of the omnibus wallet.

As you can see, this endpoint also returns 1 BTC which we just deposited:

We can also list all deposits via the List deposits endpoint:

List deposits

Now that the bankroll account is funded we assume that our customer, John Smith has bought 0.05 bitcoin. To track this value in our virtual ledger we are going to transfer the coins from the bankroll account to John`s account.

Head over to the create transactions request.

Our sender is the bankroll account and the recipient is John:

Transfer funds from the bankroll account to the customer account

Let's check the bankroll balance once again:

Check the bankroll account balance

And here’s John`s balance:

Check customer account balance

As you can see, we have successfully transferred the bitcoins and the system is now aware that 0.05 BTC of the total 1 BTC on the omnibus wallet belongs to John.

Notice that the balance of the assets (get asset balances) has not changed after this transfer, since we still have 1 real bitcoin on the omnibus wallet.

Now let's assume that John wants to sell back some of his bitcoins:

We will represent it with a similar but reversed transaction, from John to the bankroll account:

Transfer funds from the customer account to the bankroll account

Withdrawals

We can also withdraw funds from the system, by first transferring the funds on the blockchain and then mirroring the transaction with the create withdrawals request, just like with deposits.

Great job! That’s it!

You successfully walked through most of the core features of the Tangany Settlement API by creating a ledger and transferring bitcoin between two accounts.