Prerequisites

• Introduction
• Fireblocks object model
• Quickstart guide
• API / SDK overview

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:

1. 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.
2. 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

1. Use the Create a new vault account API call to create a new vault account that will hold your UTXO or account-based wallets.
2. Use the Create a new wallet API call to create a wallet in a specific vault account by passing a vaultAccountId and the assetId.
3. 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 the assetId.

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:

1. Create a vault account named using the vaultAccountNamePrefix parameter; END-USER#1, END-USER#2, END-USER#3
2. 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.