Creating Vaults and Wallets
Prerequisites
Overview
Your Fireblocks workspace utilizes a hierarchy of vault accounts as part of its Object Model. This hierarchy allows you to segregate funds belonging to different business units or deposited by different users.
A Vault account can hold multiple assets. To transfer to or from vault accounts, your source or destination targets must be provided with both their vault ID and asset ID. Fireblocks handles address generation differently when dealing with account-based assets or with UTXO-based assets.
For each asset wallet, there are one or more deposit addresses. For UTXO-based assets, such as Bitcoin, a single asset wallet may generate one or more deposit addresses. For account-based assets, there are two address-generation options.
Bulk operation
This guide describes an example of vault account batch creation. Batch creation is recommended when demand for a large number of vault accounts and wallets is anticipated. Creating the vault accounts and generating new deposit addresses for associated asset wallets is a time consuming action. Create vault accounts and asset wallets in advance instead of in real time to avoid delays when your end users request wallets and deposit addresses.
Address generation
Account-based wallets
For account-based assets, there are two address-generation options:
- Account-based assets without tag/memo/note support, such as ETH, can only generate one deposit address, making each vault account unique per asset wallet. This allows you to manage one deposit address per asset, per vault account. This requires you to create additional vault accounts when more than one deposit address of the same asset is required.
- Account-based assets with tag/memo/note support, such as XRP, can generate one or more deposit addresses. Each deposit address has the same on-chain address. However, they are differentiated by their tag/memo.
UTXO wallets
UTXO-based assets, such as Bitcoin, can hold multiple wallet addresses.
This allows you to manage deposits in a single vault account. The asset wallet can generate one or more deposit addresses.
How to create your vault account hierarchy
- Use the Create a new vault account API call to create a new vault account that will hold your UTXO or account-based wallets.
- Use the Create a new wallet API call to create a wallet in a specific vault account by passing a
vaultAccountId
and theassetId
. - For UTXO-based assets or account-based assets that support tag/memo, use the Create new asset deposit address API call to create a new deposit address in a specific vault passing its
vaultAccountId
and theassetId
.
Example
Using the code below, create a batch of vault accounts and add asset wallets under each.
- The
createVaultAccounts
function takes the number of vault accounts that you'd like to create, in this example, we're creating 3. - We're also specifying the asset ID, in this case, ETH, and the vault account name prefix, in this case,
END-USER#
.
With these parameters, the createVaultAccounts
function will run three times and:
- Create a vault account named using the
vaultAccountNamePrefix
parameter;END-USER#1
,END-USER#2
,END-USER#3
- Create the ETH asset wallet in the vault account
To test, add this function to the code language of your choice from the Developing with Fireblocks section.
const createVaultAccounts = async (
amountOfVaultAccounts: number,
assetId: string,
vaultAccountNamePrefix: string
): Promise<Array<{}> | undefined> => {
const result: Array<{}> = [];
try {
for (let i = 1; i <= amountOfVaultAccounts; i++) {
const vaultAccountResponse = await fireblocks.vaults.createVaultAccount(
{
createVaultAccountRequest:
{
name: vaultAccountNamePrefix.toString() + i.toString()
}
}
);
let vaultWalletAddress = await fireblocks.vaults.createVaultAccountAsset(
{
vaultAccountId: vaultAccountResponse.data.id as string,
assetId
}
);
result.push({
"Vault Account Name": vaultAccountResponse.data.name,
"Vault Account ID": vaultAccountResponse.data.id,
"Asset ID": assetId,
"Address": vaultWalletAddress.data.address
})
console.log("Vault Account Details: ", result);
}
return result;
}
catch (error) {
console.error(error);
}
}
createVaultAccounts(2, "ETH_TEST6", "END-USER#22223");
async function createVaultAccounts(amountOfVaultAccounts, assetId, vaultAccountNamePrefix){
let vaultRes;
let vault;
let vaultWallet;
for (let i = 1; i <= amountOfVaultAccounts; i++){
vaultRes = await fireblocks.createVaultAccount(vaultAccountNamePrefix.toString()+i.toString());
vault = {
vaultName: vaultRes.name,
vaultID: vaultRes.id
};
vaultWallet = await fireblocks.createVaultAsset(vault.vaultID, assetId);
console.log("Vault Account Details:", vault);
console.log("Wallet Asset Details for ", vault.vaultName,":", vaultWallet);
}
}
createVaultAccounts(3, "ETH","END-USER#");
def create_vault_accounts(amount_of_vault_accounts: int, asset: str, vault_account_name_prefix: str):
for i in range(amount_of_vault_accounts):
vault = fireblocks.create_vault_account(vault_account_name_prefix + str(i))
vault_dict = {"vaultName": vault["name"], "vaultId": vault["id"]}
vault_asset = fireblocks.create_vault_asset(vault["id"], asset)
print("Vault Account Details:", vault_dict)
print("Wallet Asset Details for", vault_dict["vaultName"] + ":", vault_asset)
create_vault_accounts(3, "ETH", "END-USER#")
Optional parameters
When creating wallets, some blockchains have different technicalities, handled using optional parameters.
See all optional parameters available for each Fireblocks API call.
See additional optional parameters for the `createVaultAccounts` function.
description
description
When generating new addresses for UTXO wallets, this body parameter helps you later identify the address so you'll be able to associate it with any of your backend processes.
It can be updated later using the Update address description API call.
hiddenOnUI
hiddenOnUI
Set to true
by default, hides this vault account from appearing in the Fireblocks Console.
This is the best practice when creating intermediate deposit vault accounts for your users as it helps reduce visual clutter and improves UI loading time.
The best practice is configuring this setting so that only your omnibus account and another operational vault account (or multiple) are visible in the Fireblocks Console.
autoFuel
autoFuel
If the Gas Station service is enabled on your workspace, this flag needs to be set to true
if you wish to monitor and fuel this account's Ethereum address upon detected balance refresh events, such as when deposits of ERC20 tokens occur.
Updated 4 months ago