Migration Runbook

The migration runs in four steps: prepare the destination environment, switch the integration to the Fireblocks Adapter, transfer assets, and validate before cutover. See Before You Begin for who owns each step.

Step 1: Prepare the Destination Environment

Configure governance before any funds arrive: nothing should be transferred to a wallet that is not yet governed.

1. Register signers and approvers. Register your server signers (your own or hosted by The Vault) and enrol the mobile signer devices of all approvers (see Mobile App Setup). Key shares are created at this stage and never leave the devices and signers that hold them.
2. Create wallet groups. Recreate the structure you use in Fireblocks — for example, treasury, hot, settlement and per-client groups. Both user roles and API keys are scoped to wallet groups (see Users & Access).
3. Configure policies. Set up initiator and approver separation, amount thresholds that require a second approver, and destination whitelists (see Policy Engine). Policies are enforced on every transfer, whether it is initiated from the console, the native API or the adapter.
4. Populate the address book. Whitelist your current external destinations and the Fireblocks addresses you are going to drain, so that the migration transfers also run under policy.
5. Rehearse on testnet. Run the full configuration on a testnet profile before mainnet.

Step 2: Configure the Fireblocks Adapter

Enable the Adapter

The adapter is enabled per profile by The Vault. Request it from your account manager. Once it is enabled, a Fireblocks Adapter tab appears under Settings.

Create an API Key

1. Go to Settings → API Keys and click Add API Key.
2. Enter a name (for example, “Fireblocks integration, production”) and an optional description.
3. Copy the secret. It is displayed only once and cannot be shown again.
4. Open the key’s Wallet groups dialog and select the groups the integration is allowed to operate.

Configure the Fireblocks Adapter Tab

Go to Settings → Fireblocks Adapter. The header shows four indicators; configuration is complete when all four are green.

API identity. The adapter authenticates with the linked identity’s keys and acts as that identity downstream, so the identity’s wallet groups determine which vault accounts the adapter can reach. Keys can be rotated at any time; the identity, and therefore the adapter configuration, remains unchanged.

Webhook. The Recent deliveries table lists each event with its status and attempt count. Hover over a row to see the last error.

Wallet group. Changing the default group affects only vault accounts created afterwards. Existing wallets keep their groups.

Vault accounts. The table at the bottom of the tab shows each Fireblocks vault account ID mapped to a Vault wallet, with the wallet name and the date the mapping was created. Use it during the pilot to confirm that the integration writes to the expected wallets.

Repoint the Integration

1. In your Fireblocks client, set the base URL to the adapter endpoint for your environment (see Adapter Reference).
2. Add the X-API-Key header with the key you created.
3. Point the webhook to your existing consumer and send a test event.
4. Let the integration create its vault accounts and activate assets as it does today. The resulting addresses are your migration destinations.

Existing calls and the existing webhook consumer continue to work without code changes.

Step 3: Transfer Assets

1. Whitelist the new addresses in Fireblocks under your existing TAP rules.
2. Run a pilot. Send a small amount of each asset class. Confirm arrival on chain, confirm that the transaction.created event reached your consumer, and confirm the balance in the console.
3. Transfer in tranches according to your change calendar, wallet by wallet or group by group. Each step is a normal withdrawal on one side and a normal deposit on the other. No step is irreversible and none requires downtime.
4. Rotate addresses with counterparties. Provide exchanges, partners and users with the new deposit addresses on your schedule. Keep Fireblocks open in read-only mode until the last old address has gone quiet.
5. Sweep, reconcile and retire. Bring Fireblocks balances to zero, reconcile against block explorers and the console, revoke the Fireblocks API keys, and archive the workspace according to your retention policy.

Step 4: Validate Before Cutover

Before cutover, a joint validation session with The Vault team covers:

• Balance reconciliation across Fireblocks statements, block explorers and the console.
• One complete transfer through the adapter — from request, through mobile approval, to the confirmed status event.
• One deposit detected on a vault account created through the adapter.
• Policy behaviour at, above and outside the configured thresholds.
• A delivery log with no outstanding failures.

Timeline