Import Keys

Many traders have locked positions in various wallets - that could be due to staking, holding specific tokens, or participating in certain smart contracts. Without the ability to import their private keys, traders would be forced to manage multiple wallets, complicating their asset management and paying for multiple solutions.

By supporting private key imports, Fordefi ensures that you maintain your positions and investments without having to unstake or move the funds. Moreover, supporting the import of a private key from another crypto wallet allows you to consolidate your assets into a single wallet solution or run another in parallel.

Using Fordefi's Import Key solution, you never need to reconstruct your key or run any scripts - you can upload the encrypted shares to Fordefi and decrypt the shares using the passphrase on your mobile device, keeping the integrity of the MPC protocol.

Important

For your own security, Fordefi always recommends migrating from a different wallet provider by first generating a fresh set of keys in a new Fordefi workspace and then transferring assets that you have elsewhere, on-chain. This is preferred over moving your keys from your old wallet solution to Fordefi, which is an action that carries a higher risk.

Supported private key types

Fordefi supports the import of private keys from two wallet types:

Fireblocks: You can migrate the existing wallets from your Fireblocks workspace into your Fordefi workspace by importing your Fireblocks key backup package.
Others (stand-alone): You can import a stand-alone private key that corresponds to a single wallet. For example, this could be the private key of a Metamask or Ledger wallet.

The import procedures for the two types differ slightly. See Dedicated Fordefi workspace.

The two types differ with respect to derivation:

Vault creation with imported Fireblocks keys requires key derivation. This also enables you to create multiple vaults that are all derived from the same master key.
In contrast, imported stand-alone keys do not support further derivation and each key corresponds to a single vault.

Dedicated Fordefi workspace

The import of existing keys requires a Fordefi workspace designated for key import. To tell if the workspace is suitable, click through to the Vaults screen and check that this banner appears:

Contact Fordefi Customer Support to create such a workspace, if you require one.

The workspace has a set of native keys, like any other Fordefi workspace, but it also allows importing existing keys. The result is that in the workspace, there is one native set of keys and any number of imported keys.

Before you start

To import keys successfully, you need:

An API User access token
Learn how to generate the token here.
A dedicated Fordefi workspace
See Dedicated Fordefi workspace.
(For stand-alone private keys) Fordefi recovery tool
Download it from the Fordefi documentation site.

Backup

It is recommended that you back up all the keys in the workspace - both native and imported - as soon as you onboard the workspace. Keys that were imported into the workspace after creating the backup, will automatically be backed up as well. The advantage of including all keys in the backup is that it affords you a single, integrated, managed backup solution.

Procedures

Repeat these steps for each key you wish to import.

For Fireblocks private keys

Upload encrypted key material:

To start the import process, you will need to gather the relevant key material which can include the encrypted shares package and decryption key. You can either:

Contact support to initiate the import process.
OR

Call the Import Keys API.
Here's a sample payload:

{  
"type": "fireblocks",
"key_name": "<THE NAME OF THE KEY TO IMPORT>",   
"backup_zip_content": "<BASE64 ENCODED CONTENT OF YOUR BACKUP ZIP FILE>",  
"rsa_pem": "<BASE64 ENCODED CONTENT OF YOUR BACKUP DECRYPTION KEY IN PEM FORMAT>",  
"rsa_pem_password": "<THE PASSWORD FOR THE BACKUP DECRYPTION KEY>"
}

You can upload the rsa_pem to be used to decrypt the enclave shares within the backup_zip_content.

Alternatively, you can use the following fixed public key to encrypt the shares, in which case you need to omit the rsa_pem and rsa_pem_password fields. The Fordefi enclave holds the corresponding private key.

The response contains a set of keys, with an ID for each key. Here's a sample response:

    {
      "keys": [
        {
          "key_id": "1e779c8a-6786-4c89-b7c3-a6666f5fd6b5",
          "key_name": "native-ecdsa",
          "key_type": "ecdsa_secp256k1",
          "key_origin": "native",
          "xpub": "xpub661MyMwAqRbcGE6Hjdqf5sQgNEAUAnghFLKBPQEGug3U1HG1sy4MLhEPLjUyyFfYvy45wMHQjAYEk7nHRznCwWSqi3WBQve7UWu1dXemXyv",
          "public_key_compressed": "A6YrN9ak58u3pOQHUossG2oFoVIPxvPP/b0fXkiMEJR8"
        }
      ]
    }

Decrypt and run the MPC protocol:
After you upload the key, one of the approvers must perform the following: when prompted by the Fordefi mobile application, enter the mobile passphrase that will decrypt the mobile share.
Fordefi then loads the MPC shares into its secure enclaves and mobile device to be used in the platform.

Create imported vaults (Fireblocks only)

To create a vault whose address is derived from an imported master key, pass the ID of the imported master key and the derivation path of the vault supplied by the external provider. Pass it in the Create Vault API call.

If required, Fordefi Support will create the vault for you.

For stand-alone private keys

Mac and Linux only

The following instructions are for Mac and Linux only. Contact Fordefi Support for procedures on Windows.

Copy your private key in hexadecimal format. Trim the 0x prefix if the private key includes one (that might be the case with Metamask).
Use the recovery-tool with the following command to create an import package. When prompted, choose a password of at least eight characters. This password will be used only for the import process. You will not need it once import has been completed (step 5).
./recovery-tool import-standalone-key -k PRIVATE_KEY -t secp256k1
Base64 encode your fordefi-import.zip package:
base64 -i ./fordefi-import.zip -o encoded_backup.txt

Call the Import Keys endpoint on your import organization to import the recovery package. Notice that the import type is standalone :

{ 
 "key_name": "<your_chosen_name>",
 "type":"standalone",
 "backup_zip_content":"<content_of_encoded_backup.txt>"
}

The response is something similar to:

    {
      "keys":[
        {
          "key_id":"60ebe771-b6d9-49f9-891e-23ebaa5c2f52",
          "key_name":"<your_chosen_name>",
          "key_type":"ecdsa_secp256k1",
          "key_origin":"imported","xpub":
          "xpub661MyMwAqRbcGQPhUBvp2tRt8SgUNnecmJHBLpuw5FsGzu7kyAiMuN7v36uzDmXpankZNDQDdbQCGmQxLpA4XhVbvh9x3RPNdSiPJiBHLtB","public_key_compressed":"Asik4W8bJMCCiHa8Dl0457DPetQDIiYhwM4cCnf1KJJO","supports_derivation":false
        }
      ]
    }

Open your Fordefi mobile app and interact with the Import keys shares prompt, click Continue, then enter the password you chose (in step 2) and tap Import Key to complete the import.
You can now find the new key and its ID in the response to a call to the List Keys endpoint.

Create imported vaults (stand-alone only)

To create a vault whose address is derived from an imported master key, pass the ID of the imported master key in the Create Vault. Don't provide a derivation path.

curl -X POST \
    -H "Authorization: Bearer $JWT" \
    -H "Content-Type: application/json" \
    -d '{"name": "<your_chosen_name>", "import_vault": {"key_id":"KEY_ID"}, "type":"evm"}' \
    "https://api.fordefi.com/api/v1/vaults"

If successful, the output looks something similar to:

{
  "id": "fab500a8-e645-4ea6-a848-ec21bd38f930",
  "created_at": "2025-05-05T18:36:09.401000Z",
  "modified_at": "2025-05-05T18:36:09.401000Z",
  "name": "Fantasy Vault",
  "created_by": {
    "id": "16b94846-2c83-4fb0-9b95-6ae1891df4b8",
    "user_type": "api_user",
    "name": "ImportKeyUser",
    "state": "active",
    "role": "trader"
  },
  "vault_group": {
    "id": "737a127e-bc5b-41ba-a310-b040beed6f02",
    "name": "Default",
    "vault_count": 13,
    "can_current_user_create_or_edit_vaults": true
  },
  "state": "active",
  "are_all_chains_disabled": false,
  "derivation_path": "m",
  "public_key_compressed": "Asik4W8bJMCCiHa8Dl0457DPetQDIiYhwM4cCnf1KJJO",
  "derivation_info": {
    "derivation_path": "m",
    "master_public_key": {
      "id": "60ebe771-b6d9-49f9-891e-23ebaa5c2f52",
      "xpub":   "xpub661MyMwAqRbcGQPhUBvp2tRt8SgUNnecmJHBLpuw5FsGzu7kyAiMuN7v36uzDmXpankZNDQDdbQCGmQxLpA4XhVbvh9x3RPNdSiPJiBHLtB"
    }
  },
  "keyset": {
    "id": "3e7b961c-381e-489b-97c1-e4fb70126632",
    "name": "default",
    "scope": "organization"
  },
  "origin_type": "imported",
  "type": "evm",
  "address": "0xCD4DB86268E8c15ebD4eCd6B21aB2d294B0Ee4f6"
}

After browser refresh, you should see the new imported vault in your Fordefi organization.