How to block amounts in a ledger 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 ledger 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.

Blocking funds in an account

To block funds in an account, the account ID, amount, and type are required parameters. The response is the identifier of the blockage.

Request
Response
Request
curl --location --request POST 'https://api-eu1.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."
}'
Response
{
"id": "5fbe2b9b99166cb792cba6f2"
}

Getting an account's details

You can now get details about the account where we made the blockage to see what has happened with the balance.

Request
Response
Request
curl --location --request GET 'https://api-eu1.tatum.io/v3/ledger/account/5fbaca3001421166273b3779' \
--header 'x-api-key: YOUR_API_KEY'
Response
{
"currency": "BTC",
"active": true,
"balance": {
"accountBalance": "0.000001",
"availableBalance": "-4.999999"
},
"accountCode": null,
"accountNumber": null,
"frozen": false,
"xpub": "tpubDF1sYuDKCJr6mGietaVzqGmF2dqdKVBa1DtLJGBX8HXhtHZPv5UBz3WNWU22tiVAYSjqfvfFxMnDs3vM11iQrKej6dq33UCevhiPW9EQAS2",
"accountingCurrency": "EUR",
"id": "5fbaca3001421166273b3779"
}

Getting all blockages in the account

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.

Request
Response
Request
curl --location --request GET 'https://api-eu1.tatum.io/v3/ledger/account/block/5fbaca3001421166273b3779?pageSize=50' \
--header 'x-api-key: YOUR_API_KEY'
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 ledger 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.

Unblocking an amount 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.

Request
Request
curl --location --request DELETE 'https://api-eu1.tatum.io/v3/ledger/account/block/5fbe2b9b99166cb792cba6f2' \
--header 'x-api-key: YOUR_API_KEY'

There would be an empty response if the request were successful. When you check the account's detail, you will see the available balance is the same as the account balance.

Request
Response
Request
curl --location --request GET 'https://api-eu1.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.