Validate Balances

Fireblocks customers can create automated mechanisms to notify their organization about incoming transactions using the following methods:

• Webhook notifications
• Pulling the transaction history log using the Fireblocks API

When monitoring notifications through these methods, only consider incoming transactions for reconciliation after receiving a notification that the transaction’s status has been updated to COMPLETED and the VAULT_BALANCE_UPDATE webhook has been received.

Fireblocks provides additional information to help clients validate and reconcile their balances according to the blockchain state. This information includes:

• The TRANSACTION_STATUS_UPDATED webhook event contains the blockInfo object, which includes:
  • blockHeight: The block height where the transaction was included
  • blockHash: The block hash where the transaction was included
• The VAULT_BALANCE_UPDATE webhook event contains the blockHeight and blockHash properties
• The GET /vault/accounts/{vaultAccountId}/{assetId} endpoint returns the balance of an asset in a vault account and includes the blockHeight and blockHash properties
• The GET /transactions/{txId} endpoint returns the transaction by its Fireblocks ID and includes the blockInfo object with the blockHeight and blockHash properties

Before crediting the end-user, customers need to run a reconciliation process to ensure that the incoming balance is accurately reflected and up to date according to the same blockHeight provided in the transaction notification object. If the balance is not up to date with the network state and the same height value, customers should not credit their clients until the issue is inspected and resolved.

Fireblocks strongly recommends checking the wallet’s balance using the Fireblocks API to verify that the deposit is included and the balance is up to date. This is crucial to prevent potential loss of funds from crediting end-clients before the balance is truly updated. While Fireblocks takes extensive measures to ensure the accuracy and reliability of its services, it is important for customers to implement all necessary validations and follow best practices to avoid any potential issues.

Below is a sequence diagram for additional reference: