Manage Deposits at Scale

Documentation Index

Fetch the complete documentation index at: https://developers.fireblocks.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

One of the most important processes for a business is the ability to handle deposits made by clients. To facilitate this, each client needs their own wallet for the asset they want to deposit. This requirement applies to both scenarios: deposits made by clients from external sources and on-ramp processes such as purchasing crypto and storing it in their address. Both flows result in the creation of a new wallet for the specific user. Businesses serving hundreds of thousands or even millions of users need to create and manage these addresses and the deposited funds in the most operationally and cost-effective ways. In this guide, we will outline the recommended workflows for Fireblocks clients to achieve an efficient setup for processing user deposits. The topics covered include:

• Setting up the correct wallet structure for your use case
• Receiving notifications on incoming transfers
• Processing UTXO and Tag/Memo-based asset deposits
• Processing account-based asset deposits
• Best practices for generating deposit addresses
• Validating wallet balances
• Maintaining an internal ledger

​

Setup the Wallet Structure

The wallet structure, or as we call it in Fireblocks, the vault structure, that you set up will directly impact the capabilities, efficiency, and operational load of your business. Fireblocks recommends one of the following two setups, depending on the type of your operation:

• Segregated Vault Structure: Ideal for customers running a B2B business. This setup is recommended for those who want full segregation of their clients’ funds.
• Omnibus Vault Structure: Ideal for customers running a B2C business. This setup is recommended for those who want to create a dedicated wallet for each user and then sweep the funds into a single Treasury wallet.

​

Get Notifications for Incoming Transactions

To receive notifications about incoming transactions to your Fireblocks wallets, we recommend using the Webhook service. Webhooks are push notifications sent by Fireblocks to a URL specified by the customer. This service sends notifications about various events in your Workspace, including incoming funds. Each incoming transaction triggers a series of events, starting with an alert that a new transaction has been identified, followed by subsequent notifications about the transaction’s completion status.

​

Process UTXO and Tag/Memo Based Assets Deposits

Customers who find the Omnibus structure suitable for their business needs and work with UTXO-based assets will notice that all such assets (e.g., BTC, BCH, LTC, DOGE, ADA) are deposited into a single “Deposit” vault account. Each user has their own deposit address identified by the description parameter. Processing these funds is straightforward in terms of address generation and management, but it introduces some potential challenges that should be considered during the integration phase. When running a retail-facing business and processing a large volume of UTXO-based asset deposits, customers may find that their deposit vault account accumulates a significant number of unspent transaction outputs (UTXOs) for a specific asset. Efficiently managing these UTXOs is crucial for the following reasons:

1. Creating Outgoing Transactions: Customers might want to move deposited funds (or part of them) to different venues such as exchange accounts, withdrawal vaults, or even a cold wallet. The number of UTXOs that can be selected for a transaction is limited to 250 UTXOs per transaction. This limitation could prevent customers from moving the desired amount if the selected 250 UTXOs do not add up to the intended amount. This depends on the UTXO selection mechanism in your Fireblocks wallet, which by default chooses the smallest confirmed UTXOs first. The selection mechanism can be adjusted to select the largest confirmed UTXOs first, based on customer preference.
2. Fee Efficiency: If a wallet has many small UTXOs, creating outgoing transactions will require selecting more UTXOs to reach the required amount. This results in larger transaction sizes and higher fees, making the transaction more attractive to miners/validators.

To overcome the mentioned in the above, customer should implement a UTXO consolidation logic as described in the following section.

​

Unique deposit addresses via shared wallets

For UTXO-based chains, we recommend a similar approach to memo-based chains. Calling the Create a new deposit address endpoint generates a new deposit address under the same wallet. Each end user receives a unique deposit address while funds are still received into a shared wallet. End-user deposits are identified by the receiving address included in the transaction notification, eliminating the need to create separate wallets per user.

​

UTXO Consolidation

UTXO-based transactions in Fireblocks have a limit of 250 inputs (UTXOs) per transaction. Additionally, there must be a logic to select the inputs for a transaction, which Fireblocks implements as follows:

1. DEFAULT Selection Mechanism: By default, Fireblocks selects the first 250 smallest confirmed inputs available for a specified vault account. This helps customers use up small UTXOs and reduce the number of available UTXOs in their vault account.
2. Configurable Selection Mechanism: Fireblocks can be configured to select the 250 largest confirmed inputs first. This configuration requires opening a request with our support team.

This consolidation transaction is typically made from the Deposits vault account to one of the Withdrawals vault accounts to maintain a sufficient asset balance for user withdrawals. However, the transaction can also be executed with multiple destinations, such as different vault accounts, exchange accounts, external addresses, or even a cold wallet. The trigger for the consolidation process can be based on the number of deposits made into the Deposits vault account. For instance, customers can decide that after every 250 deposits (tracked by an internal counting logic), the system will automatically create the consolidation transaction. Others may choose to execute this transaction based on current network fees to save on transaction costs. Fireblocks provides two important endpoints to help clients build their UTXO consolidation logic:

1. Get Maximum Spendable Amount in a Single Transaction: This endpoint returns the maximum amount of a particular asset that can be spent in a single transaction from a specified vault account.
2. Create Transaction: This endpoint creates a transaction with the specified amount returned from the endpoint above.

Additionally, clients who want to trigger the consolidation transaction based on the number of deposits made into their Deposits vault account can use the Fireblocks Webhook service to get notifications on completed incoming transfers.

​

Process Account Based Asset Deposits

Customers who want to generate a unique address for each of their end-users need to create a new intermediary vault account for each user and then the required vault wallet within this newly generated vault account. This is necessary because account-based assets do not support the generation of multiple addresses under the same wallet. Once the generated address is shared with the end-user and the end-user makes a deposit into that vault account, most customers will want to perform a sweeping operation. This operation consolidates all deposited funds from the intermediary vault accounts into a single treasury management vault account for various business purposes. Sweeping funds involves moving assets from address A to address B. It is important to note that this is an on-chain operation and includes transaction fee payments. While sweeping base assets like ETH is straightforward, sweeping deposited ERC20 tokens presents a challenge. This is because the transaction fee must be paid in the network’s base asset, which end-users might not have in their wallets. To address this issue, Fireblocks recommends using the Fireblocks Gas Station feature.

​

Memo and tag-based deposit identification

For account-based chains, we recommend creating a dedicated vault account for each end user and managing all of their associated wallets within that account. Some chains, such as Stellar and Ripple, support deposit identification using a memo or tag (see the full list here). On these chains, you can assign each end user a unique memo or tag to identify their deposits using the Create a new deposit address endpoint. This allows multiple users to deposit into a shared wallet without needing a separate vault account or wallet per end user. Deposits are credited by matching the memo or tag field included in the transaction. This shared-wallet approach reduces operational overhead and fees by eliminating the need for sweeping funds and allowing reconciliation through a single or small number of transactions. However, it is still considered good practice to separate vault accounts by function. For example, cold storage, warm wallets, deposits, withdrawals, and treasury.

​

Create Deposit Addresses Best Practices

Customers serving hundreds of thousands or even millions of users will eventually need to create a corresponding number of deposit addresses within a single vault account (for UTXO deposits) and/or intermediate vault accounts (for Account Based assets) in their workspace. A basic implementation is to create a new deposit address or vault account for the end-user whenever the user registers for the service or requests a deposit address for a specific coin. In this setup, customers make a real-time API call to Fireblocks to generate a new deposit address or create a new vault account with a vault wallet for the requested asset, triggered by the end-user request. While this approach is acceptable, the best practice we recommend is to create these deposit addresses or intermediate vault accounts proactively. Fireblocks customers should run a service that continuously creates addresses, vault accounts, and vault wallets, regardless of user requests. This proactive approach means maintaining a pool of pre-generated vault accounts and addresses. When a user requests a new deposit address, customers can quickly assign a pre-generated address instead of making a real-time API call to Fireblocks. This reduces the risk of encountering API errors in real-time and significantly decreases the waiting time for users to receive a new address, thereby enhancing the user experience and providing a near real-time service.

​

Pre-creating vault accounts

We recommend pre-creating vault accounts in advance. When an end user requests access, you can create the required wallets later and assign them to one of the pre-created vault accounts. To manage scale efficiently, you can maintain either high or low vault account thresholds — once the number of available accounts reaches a low threshold, resume creating accounts until the required threshold is met. When a wallet is created for an end user, assign it to the appropriate pre-created vault account and update the assignment in your internal systems.

​

Resource identification

To map resources to the correct end users, we recommend using the following fields:

• Vault account: use the name field
• Wallet: use the description field

Assign these fields at resource creation time and use them internally for end-user assignment.

​

Vault account visibility

When creating deposit vault accounts, set the hiddenOnUi flag to true. This helps ensure proper management of important vault accounts in the Fireblocks Console.

​

Wallets requiring on-chain creation

Some wallets require an on-chain operation to be created, including:

• SPL tokens (Solana)
• Ripple tokens
• Stellar tokens
• HBAR
• EOS

For SPL tokens, Associated Token Accounts (ATAs) can be created by receiving a token transfer from an external source. The account creation fee is included as part of that transfer. While SPL, Ripple, and Stellar tokens use fees taken from the wallet itself, EOS wallets are currently funded by Fireblocks treasury and are expected to be used reasonably. In the future, the funding for these wallets will transition to a self-bootstrapped model. To associate the pre-generated address with the end-user, during the assigning process on the customer’s side, the following APIs should be called to synchronize both Fireblocks and the customer’s internal system with the user reference:

1. UTXO and Tag/Memo Based Assets: When assigning a new UTXO-based asset deposit address within your Deposit vault account for a new user, call the Update Address Description API endpoint with the newly assigned user reference as the description.
2. Account-Based Assets: When assigning a new intermediate vault account for an end-user, call the Rename a Vault Account API endpoint with the newly assigned user reference as the vault account name. Ensure that the vault account name does not contain any PII data.

​

Validate Balances

Fireblocks allows you to receive notifications about incoming transactions to your Fireblocks vault accounts. A common setup for Fireblocks customers is to subscribe to the webhook service and get notified whenever a new deposit is made into a vault account. When an event for an incoming transaction is triggered, followed by an event confirming the deposit’s completion, the typical setup on the customer’s end will automatically update the internal ledger and adjust the balance of the user associated with the deposited vault account. While this approach is generally correct, Fireblocks recommends implementing additional validation steps before crediting the end user with the deposited amount to avoid potential loss of funds.

​

Maintain an Internal Ledger

An internal ledger is a fundamental component to consider when building a retail-facing solution. Essentially, it records incoming transfers and balances for your users. Maintaining this ledger is crucial because funds deposited by users into their accounts are often swept or moved to a different account, as described in the sweeping mechanism section. You need to accurately track how much each user has deposited and what balance should be displayed in your system. Fireblocks does not provide a built-in component or feature for this specific need, so customers can implement it in any way they see fit. However, Fireblocks offers all the necessary utility tools and features to effectively maintain such a ledger. This includes APIs for validation and reconciliation processes and a webhook service that allows you to create an event-driven system triggered by various events in your Fireblocks workspace.