Ctrl+K

Set Up External-Signing Mode

Overview

If you're using self-custody hot wallets with BitGo Express, you can configure an additional instance of your Express server on an air-gapped machine where you store all your private user key and sign transactions. External signing is the most secure way to implement BitGo Express, because it enables signers with restricted access or network connectivity to sign transactions.

Note: ECDSA MPC wallets aren't currently compatible with external-signer mode.

Cryptocurrency ATM

Prerequisites

Steps

1. Configure External-Signing URL

In your external-signing instance of BitGo Express:

  • Create a JSON file that contains your private keys.
  • Configure the signerMode and signerFileSystemPath options to point to this JSON file.

In your standard instance of BitGo Express, configure the externalSignerUrl option to point to the URL of your external-signing instance of BitGo Express.

Note: If BitGo Express encounters an ECONNREFUSED error when requesting an external signer's signature, BitGo continues retrying the request for up to 15 seconds.

2. Format Private-Key Encryption

The JSON file that contains your unencrypted private keys must be in the following format:

"<walletId>": "<encryptedPrivateKey>"

In order to parse the encryptedPrivateKey option correctly, you must use wrap keys and values in double quotation marks (").

The following is an example JSON file that contains 2 wallet IDs and their corresponding encrypted private keys with escape characters:

  • API
1
2
3
4
{
"61f039aad587c2000745c687373e0fa9":"{\"iv\":\"+1u1Y9cvsYuRMeyH2slnXQ==\",\"v\":1,\"iter\":10000,\"ks\":256,\"ts\":64,\"mode\":\"ccm\",\"adata\":\"\",\"cipher\":\"aes\",\"salt\":\"54kOXTqJ9mc=\",\"ct\":\"JF5wQ82wa1dYyFxFlbHCvK4a+A6MTHdhOqc5uXsz2icWhkY2Lin/3Ab8ZwvwDaR1JYKmC/g1gXIGwVZEOl1M/bRHY420h7sDtmTS6Ebse5NWbF0ItfUJlk6HVATGa+C6mkbaVxJ4kQW/ehnT3riqzU069ATPz8E=\"}",
"61fb21819c54dd000755f8de3a18e46f":"{\"iv\":\"ULAkh1Ia2B2oJbVWRt+xMw==\",\"v\":1,\"iter\":10000,\"ks\":256,\"ts\":64,\"mode\":\"ccm\",\"adata\":\"\",\"cipher\":\"aes\",\"salt\":\"SVkVei5M1qU=\",\"ct\":\"NxfG1HQWGcrwCHkQh8DKeMaZrRic+SSBQHtuOSsSJzW5MDOpwqDta8PDdh52lp9eqtaY+CGN6rPhaGbeZDrEyV2PoBGeb48GicMTVAehkyoF9mr8edtsWDCxcmmde+1zv3czy2n/bgXYNGvX39D30GDRpfovSYc=\"}"
}

To help you create your JSON file, BitGo provides a tool that fetches your encrypted private keys from BitGo and produces the JSON file in the correct format, including the escape characters. You can access this tool from our GitHub repo. To use this tool, you need to provide a valid accessToken and a list of walletIds, grouped by the cryptocurrency. We provide an example within the file.

Use the following command to create the file:

  • CLI
1
yarn ts-node <path/to/fetchEncryptedPrivKeys.ts>

3. Configure Wallet-Passphrase Environment Variable

To enable your external-signing instance of BitGo Express to decrypt your private keys, configure your wallet passphrases as an environment variable in the following format:

WALLET_<walletId>_PASSPHRASE

Note: You must set a passphrase for each of your wallets.

Use the export option to set the environment variable. For example:

  • CLI
1
2
export WALLET_61f039aad587c2000745c687373e0fa9_PASSPHRASE=wDX058%c4plL1@pP
export WALLET_61fb21819c54dd000755f8de3a18e46f_PASSPHRASE=wDX058%c4plL1@pP

Next

To start an instance of BitGo Express using an external signer, initiate BitGo Express with --externalSignerUrl=<externalSignerUrl>.

To start an external-signing instance of BitGo Express that has access to encrypted private keys and wallet passphrases, initiate BitGo Express with --signerMode --signerFileSystemPath=<encryptedPrivateKeysJson>.

See Also

See all configuration parameters in the Reference.