Validate Balances

Before you credit end users for incoming transactions, confirm that each deposit is reflected in the vault balance and on the blockchain. Webhooks give you everything you need for this check. Subscribe to these events:

• transaction.status.updated: transaction lifecycle. It includes the blockInfo object, with blockHeight and blockHash for the block that includes the transaction.
• vault_account.asset.balance_updated: balance changes. Each event carries the full balance (total, pending, frozen, lockedAmount, staked) and, when available, blockHeight and blockHash. See VaultAccountBalanceUpdate.

​

Reconcile before you credit

Reconcile every deposit against the blockchain before you credit end users. This independent check complements the accuracy controls Fireblocks applies to balance data. Follow these steps:

1. Wait for transaction.status.updated with status COMPLETED. Note blockInfo.blockHeight.
2. Wait for a vault_account.asset.balance_updated event for the same vault account and asset with a blockHeight equal to or greater than the transaction’s blockHeight.
3. Compare the balance with the blockchain state at that height. If they don’t match, don’t credit the end user until you investigate and resolve the difference.

blockHeight and blockHash can be missing for some asset types or in specific scenarios. In that case, order balance events by their createdAt timestamp and rely on the check against the blockchain in step 3. For some assets, such as TRX and SOL, a balance event may not follow a completed transaction. See When to poll. The diagram shows this flow:

​

Handle balance event ordering

For general webhook handling, see:

• Best practices for webhooks for duplicate events and delivery order.
• Responses and retries for delivery and retry behavior.
• Validating webhooks for signature verification.

Balance events need two extra rules:

• Each balance event contains the full balance, not a delta. Replace your stored balance with the latest event and ignore events at a lower blockHeight.
• Several balance events can share a blockHeight (for example, when funds are locked or unlocked). Compare blockHash as well, because a reorg can change the hash at the same height.

​

When to poll

Polling is a fallback, not the default. Use it only in the cases below, and keep requests low to stay within your rate limit tier.

• Assets that complete without a pending state (for example, TRX and SOL). The transaction reaches COMPLETED, but a balance event may not follow when the balance didn’t change. After the COMPLETED webhook, call Get the asset balance for a vault account (GET /vault/accounts/{vaultAccountId}/{assetId}) once and apply step 3 of Reconcile before you credit.
• Startup and catch-up. Read the current balance when a consumer starts, after downtime, or when you add a subscription. Webhooks only carry changes.

The balance endpoint returns the same fields as the balance webhook. Use it to fetch state, not as an independent verification. Validate against the blockchain.