Overview

To improve the security of transactions from your workspace, we recommend whitelisting destination addresses.

Whitelisting addresses is a general security best practice that helps prevent potential loss of funds. It protects against issues such as malicious address manipulation or human error, like copying and pasting the wrong address and inadvertently sending funds to an unintended recipient.

Each whitelisting request needs approval from the Admin Quorum before funds can be transferred to that address. If any admin rejects the request, the address will not be whitelisted. However, you can submit a new request to whitelist the same address, which can be approved by the Admin Quorum at any time.

In Fireblocks, there are three types of whitelisted address entities, each capable of holding different asset addresses:

• External Wallets
• Internal Wallets
• Contracts

👍

Best Practice

If you interact with a specific address multiple times, it should be added to the whitelisted addresses in your workspace.

🚧

Default Behavior

By default, to send funds to an address outside of Fireblocks, the address must be whitelisted first. If you want to permit transactions to non-whitelisted addresses, you should enable the One Time Address (OTA) feature in your workspace. [link to OTA section]

Whitelisted Addresses Types

External Wallets

External Wallets are entities that hold addresses external to your Fireblocks workspace and are not under your ownership. These addresses belong to your clients or counterparties. If you intend to whitelist an address that is not under your control, it should be added to the External Wallet entity. Note that External Wallet addresses do not display the on-chain balance of the whitelisted address.

Internal Wallets

Internal Wallets are entities that hold addresses external to your Fireblocks workspace but are under your ownership. These addresses belong to your other wallets outside of Fireblocks. If you intend to whitelist an address of your own wallet that is outside of Fireblocks and under your control, it should be added to the Internal Wallet entity.

Contracts

Contract Wallets are entities that hold whitelisted contract addresses. If you interact with smart contracts and want to restrict the approved list of contracts, you should whitelist the contract addresses under the Contract Wallet entity.

Whitelisting at Scale

For businesses with a high volume of outgoing transactions in their fully automated workflows, whitelisting every external address can be cumbersome and disrupt the automation. To address this while maintaining high security standards, you can use one of the following approaches:

1. API Key with Admin Permissions: Create an API Key with admin permissions and set the required admin quorum for the whitelisting operation to 1.
   Pair the API Key with an API Cosigner and create a Cosigner Callback Handler server on your end, connecting it to your Cosigner.
   In this setup, you can call the whitelisting address APIs before each transaction while the approval will be fully automated by the API Key acting as part of the admin quorum.
   Additionally, each request will be sent to your callback handler, allowing you to programmatically decide whether the address should be whitelisted.

2. Fireblocks One Time Address Feature: Utilize the Fireblocks One Time Address (OTA) feature to send funds to a non-whitelisted address. This can be done by combining the appropriate Transaction Authorization Policy (TAP) rules and potentially implementing internal validations on your callback handler.

Work with One Time Addresses

The One-Time Address (OTA) feature allows you to transfer assets to non-whitelisted addresses in your Fireblocks workspace.

In contrast to whitelist addresses, each one-time address does not require approval by the Admin Quorum in order to transfer funds to it. However, enabling the feature requires approval by the workspace Owner and the Admin Quorum.

🚧

This feature poses security risks! We recommend:

Setting up a strict Transaction Authorization Policy (TAP) before enabling it. You can set a variety of such TAP protective limitations, such as:

• Restricting one-time address transfers only to certain preselected users or groups
• Requiring approval for one-time address transfers above a certain threshold

📘

Enable One Time Address feature:

1. Learn more on how to enable the One Time Address feature via the Fireblocks Console here
2. Check out the One Time Address API endpoints here