How to block amounts in a virtual account
Most blockchains do not allow the blocking or freezing of assets at blockchain addresses. But in real life, many applications must block blockchain assets before the actual transaction. It is the same as with a debit card and a real bank account. First, funds are blocked, and then the transaction is processed a couple of days later.
When you work with Tatum Virtual Accounts, there are two types of balances:
- account balance - a sum of all funds that are present in the account
- available balance - a sum of all funds that are available for spending
The available balance can even be negative when there are blockages in the account. When the balance is below zero, transactions cannot be performed, but new blockages can be made.
Blockages affect the available balance of the account. Every new blockage has its unique identifier and details, like its type or custom description.
JavaScript
cURL
import {blockAmount} from '@tatumio/tatum';
/**
* Blocks an amount in an account.
* Any number of distinct amounts can be blocked in one account.
* @param id - ledger account ID
* @param body - request body with blocked amount - https://apidoc.tatum.io/tag/Account/#operation/blockAmount
*/
const body = {
"amount": "5",
"type": "DEBIT_CARD_OP",
"description": "Card payment in the shop."
}
const txId = blockAmount("5fbaca3001421166273b3779", body);
curl --location --request POST 'https://api.tatum.io/v3/ledger/account/block/5fbaca3001421166273b3779' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": "5",
"type": "DEBIT_CARD_OP",
"description": "Card payment in the shop."
}'
The response is the identifier of the blockage.
Response
{
"id": "5fbe2b9b99166cb792cba6f2"
}
You can now get details about the account where we made the blockage to see what has happened with the balance.
JavaScript
cURL
import {getAccountById} from '@tatumio/tatum';
/**
* Gets active account by ID.
* Displays all information regarding the given account - https://apidoc.tatum.io/tag/Account/#operation/getAccountByAccountId
* @param id - ledger account ID
*/
const account = getAccountById("5fbaca3001421166273b3779");
curl --location --request GET 'https://api.tatum.io/v3/ledger/account/5fbaca3001421166273b3779' \
--header 'x-api-key: YOUR_API_KEY'
The response will contain the details of the virtual account associated with the specified account ID.
Response
{
"currency": "BTC",
"active": true,
"balance": {
"accountBalance": "0.000001",
"availableBalance": "-4.999999"
},
"accountCode": null,
"accountNumber": null,
"frozen": false,
"xpub": "tpubDF1sYuDKCJr6mGietaVzqGmF2dqdKVBa1DtLJGBX8HXhtHZPv5UBz3WNWU22tiVAYSjqfvfFxMnDs3vM11iQrKej6dq33UCevhiPW9EQAS2",
"accountingCurrency": "EUR",
"id": "5fbaca3001421166273b3779"
}
As you can see, there were 5 bitcoins blocked in the account, so the available balance is negative. Now you can get all blockages in the specific account.
JavaScript
cURL
import { getBlockedAmountsByAccountId } from '@tatumio/tatum';
/**
* Gets blocked amounts for an account.
* @param id - account ID
* @param pageSize - max number of items per page is 50
* @param offset - optional Offset to obtain next page of the data
* @returns - detail of blocked amounts - https://apidoc.tatum.io/tag/Account/#operation/getBlockAmount
*/
const amounts = getBlockedAmountsByAccountId("5fbaca3001421166273b3779?pageSize=50");
curl --location --request GET 'https://api.tatum.io/v3/ledger/account/block/5fbaca3001421166273b3779?pageSize=50' \
--header 'x-api-key: YOUR_API_KEY'
The response will contain a list of all current blockages for the account ID.
Response
[
{
"amount": "5",
"type": "DEBIT_CARD_OP",
"description": "Card payment in the shop.",
"accountId": "5fbaca3001421166273b3779",
"id": "5fbe2b9b99166cb792cba6f2"
}
]
When you want to unblock an amount from the account, you have several options:
- unblock a specific blockage - this will unblock the whole amount, and the account's available balance will be increased.
- unblock a blockage and perform a virtual account transaction - this will unblock the amount from the account and perform a transaction to a different account.
- unblock all blocked amounts in the account - this will unblock all blockages in the account.
Let's unblock a blockage without a transaction. You'll need to pass the ID of the specific blockage you want to unblock.
JavaScript
cURL
import {deleteBlockedAmount} from '@tatumio/tatum';
/**
* Unblocks a previously blocked amount in an account.
* Increases the available balance in the account where the amount was blocked.
* @param id - transaction ID of blocked amount
*/
const account = deleteBlockedAmount ("5fbe2b9b99166cb792cba6f2");
curl --location --request DELETE 'https://api.tatum.io/v3/ledger/account/block/5fbe2b9b99166cb792cba6f2' \
--header 'x-api-key: YOUR_API_KEY'
There will be an empty response if the request is successful. Now, when you check the details of the account, you will see the availableBalance is the same as the accountBalance.
JavaScript
cURL
import {getAccountById} from '@tatumio/tatum';
/**
* Gets active account by ID.
* Displays all information regarding the given account - https://apidoc.tatum.io/tag/Account/#operation/getAccountByAccountId
* @param id - ledger account ID
*/
const account = getAccountById("5fbaca3001421166273b3779");
curl --location --request GET 'https://api.tatum.io/v3/ledger/account/5fbaca3001421166273b3779' \
--header 'x-api-key: YOUR_API_KEY'
Response
{
"currency": "BTC",
"active": true,
"balance": {
"accountBalance": "0.000001",
"availableBalance": "0.000001"
},
"accountCode": null,
"accountNumber": null,
"frozen": false,
"xpub": "tpubDF1sYuDKCJr6mGietaVzqGmF2dqdKVBa1DtLJGBX8HXhtHZPv5UBz3WNWU22tiVAYSjqfvfFxMnDs3vM11iQrKej6dq33UCevhiPW9EQAS2",
"accountingCurrency": "EUR",
"id": "5fbaca3001421166273b3779"
}
You can test other unblocking methods or read more about the specific endpoints in the API Reference.