Prerequisites

• Introduction
• Fireblocks Object Model
• Quickstart guide or Developer Sandbox Quickstart
• API / SDK Overview

Overview

Whitelisted addresses are deposit addresses that exist outside of your Fireblocks Vault. Your Fireblocks workspace utilizes a hierarchy of containers such as Vault accounts and Internal or External wallets as well as Contract wallets, as part of its Object Model.

You can perform transactions from your workspace by whitelisting addresses for any supported blockchain or fiat account.

• Vault account addresses are in your control using the Fireblocks Console and don't require whitelisting.
• Internal wallet addresses are those in your control but outside of Fireblocks.
• External wallet addresses can hold multiple assets and are managed by clients and counterparties.
• Contract wallet addresses are smart contracts that you want to interact with. Contract wallet addresses only apply to smart contracts on EVM-compatible blockchains.

This wallet hierarchy lets you segregate funds belonging to different business units or deposited by different users.

📘

Transfering assets to an External wallet

To transfer to an external wallet, you must provide your destination target's wallet ID (walletId) and asset ID (assetId).

Creating an External wallet

Creating an External wallet requires you to provide its name (as a string) that is used to identify the wallet and its addresses throughout your workspace.

Unlike Vault accounts, External wallets can hold only one asset wallet address for either Account-based or UTXO wallets.

🚧

Wallet naming is permanent

Wallet names can't be changed after they're created.

An optional customerRefId string can also be passed as the ID that AML providers may use to associate the owner of funds with transactions.

createExternalWallet function

const createExternalWallet = async (
	name: string
):Promise<UnmanagedWallet | undefined> => {
  try {
    const transactionResponse = await fireblocks.externalWallets.createExternalWallet(
      {
				createWalletRequest:
				{
					name
        }
      }
		);
    console.log(JSON.stringify(transactionResponse.data, null, 2));
    return transactionResponse.data;
  }
	catch(error) {
  	console.error(error);
  }
};
createExternalWallet("Counter-Party Wallet #1")

async function createExternalWallet(name){
    const externalWallet = await fireblocks.createExternalWallet(name);
    console.log(JSON.stringify(externalWallet, null, 2));
}
createExternalWallet("Counter-Party Wallet #1");

def create_external_wallet(name: str, customer_ref_id="") -> str:
    external_wallet = fireblocks.create_external_wallet(name, customer_ref_id)
    pprint(external_wallet)

create_external_wallet("Counter-Party Wallet #1")

Adding assets to an External wallet

To add the address of an asset to your External wallet, provide the External wallet's ID, the asset ID, and the specific destination address you wish to whitelist.

The External wallet's ID is shown in the Console after running the createExternalWallet function above or by calling the List external wallets endpoint.

The asset ID is used by Fireblocks to represent the specific supported asset (such as ETH, BTC, USDC etc.) by its ID . You can get all supported asset IDs by calling the Supported assets endpoint. The id value will display them as a short string.

The address you provide should be a string with the valid address existing on the network for that specific asset.

The tag string parameter sent with this function represents the tags, memos, or notes that are coupled with the addresses of XRP, EOS, HBAR, XDB, XLM, and ALGO networks.

• For XRP wallets, use the address's destination tag;
• For ATOM, EOS, HBAR, LUNA, LUNC, XDB, XEM, use the address's memo.
• For XLM, use the address's memo_text
• For ALGO, use the address's note

const createExternalWalletAsset = async (
  walletId: string,
  assetId: string,
  address: string,
  tag: string,
): Promise<FireblocksResponse<ExternalWalletAsset> | undefined> => {
  try {
    const transactionResponse =
      await fireblocks.externalWallets.addAssetToExternalWallet({
        walletId: walletId,
        assetId: assetId,
        addAssetToExternalWalletRequest: {
          address,
          tag,
        },
      });
    console.log(JSON.stringify(transactionResponse.data, null, 2));
    return transactionResponse;
  } catch (error) {
    console.error(error);
  }
};

createExternalWalletAsset(
  "5023b722-0cd5-402d-b1f9-94723b28237a",
  "ETH_TEST5",
  "0xEA6A3E367e96521fD9E8296425a44EFa6aee82da",
  "test",
);

async function createExternalWalletAsset(walletContainerId, assetId, address, tag){
    const externalWalletAsset = await fireblocks.createExternalWalletAsset(walletContainerId, assetId, address, tag);
    console.log(JSON.stringify(externalWalletAsset, null, 2));
}

createExternalWalletAsset("d01b9b9f-4c3b-425c-8f8b-78b3f5734549", "ETH", "0xEA6A3E367e96521fD9E8296425a44EFa6aee82da", "test");

def add_internal_wallet(walletId: str, assetId: str, address: str, tag="") -> str:
    internalWalletAsset = fireblocks.create_internal_wallet_asset(walletId, assetId, address, tag)
    pprint(internalWalletAsset)
    
add_internal_wallet("02ec0271-95c9-36e0-fa55-b3a9a6562531","ETH_TEST","EA6A3E367e96521fD9E8296425a44EFa6aee82da")

📘

Admin Quorum approval required to whitelist.

The Admin Quorum must approve the new whitelisted address before transfers may be sent to it from your workspace.