Block and Unblock Funds from an 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.

Blockages affect the available balance of the account. Every new blockage has its unique identifier and details, like its type or custom description.

Virtual Accounts have two types of balance:

1. Account balance - a sum of all funds that are present in the account
2. Available balance - a sum of all funds that are available for spending

Blocking Funds

1. Block Funds from a Virtual Account

To block funds in an account, the account ID, amount, and type are required parameters.

• Block amount - v3 REST API endpoint

Request Example:

The response is the identifier of the blockage.

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."
}'
//Response:
{
    "id": "5fbe2b9b99166cb792cba6f2"
}

2. Verify the blocked amount in the Account

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

• Get Account by ID - v3 REST API endpoint

Request Example:

The response will contain the details of the virtual account associated with the specified account ID.

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": "-4.999999"
    },
    "accountCode": null,
    "accountNumber": null,
    "frozen": false,
    "xpub": "tpubDF1sYuDKCJr6mGietaVzqGmF2dqdKVBa1DtLJGBX8HXhtHZPv5UBz3WNWU22tiVAYSjqfvfFxMnDs3vM11iQrKej6dq33UCevhiPW9EQAS2",
    "accountingCurrency": "EUR",
    "id": "5fbaca3001421166273b3779"
}

3. Get all block logs from an 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.

• Get blocked amounts from an Account - v3 REST API endpoint

Request Example:

The response will contain a list of all current blockages for the account ID.

curl --location --request GET 'https://api.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"
    }
]

Unblocking Funds

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.

1. Unblock Funds from a transaction

Let's unblock a blockage without a transaction. You will need to pass the ID of the specific blockage you want to unblock.

• Delete blocked amount - v3 REST API endpoint

Request Example:

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.

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

2. Verify the amount was unblocked in the Account

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

• Get Account by ID - v3 REST API endpoint

Request Example:

The response will contain the details of the virtual account associated with the specified account ID.

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"
}

Good to Know

• 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.