Tutorial: Omnibus wallet custody with Tangany Settlement API
Gracjan PawliszynSoftware Developer, Tangany
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
Depositing & transferring funds
You should already be familiar with the Tangany Custody API
You should already be familiar with the Tangany Customers API
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.
Postman: visit our public postman collection. I recommend using a Postman desktop client to avoid cross-browser request issues.
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.
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
The result should be an empty list:
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:
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
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.
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
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
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:
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:
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:
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:
Let's check the bankroll balance once again:
And here’s John`s 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:
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.
Keep learning and keep reading
Stay informed on the world of crypto regulation and read the latest about Tangany.