Custody Starter Architecture: Set Up Standby Wallet (Multisig)

Create a multisignature standby wallet as intermediate buffer. See the Guide.

Generate a self-custody wallet using BitGo Express or the SDK. This creates the wallet and keys in one step. The standby wallet is a self-custody wallet that serves as an intermediate buffer between your custody wallet (cold storage) and your deposit/withdraw wallet (daily operations).

This response contains critical key material. Save the backup keychain in a secure place. Save the wallet ID and backup keychain from the response. You need the wallet ID to configure whitelist policies.

API Reference

// 1. Create Standby Wallet
export BITGO_EXPRESS_HOST="<YOUR_LOCAL_HOST>"
export COIN="<ASSET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export WALLET_PASSPHRASE="<YOUR_WALLET_PASSPHRASE>"
export LABEL="<YOUR_DESIRED_WALLET_NAME>"

curl -X POST \
  http://$BITGO_EXPRESS_HOST/api/v2/$COIN/wallet/generate \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "enterprise": "'"$ENTERPRISE_ID"'",
    "passphrase": "'"$WALLET_PASSPHRASE"'",
    "label": "'"$LABEL"'",
    "multisigType": "onchain",
    "type": "hot"
}'

// 1. Create Standby Wallet
const { BitGo } = require('bitgo');

const accessToken = '<YOUR_ACCESS_TOKEN>';

const bitgo = new BitGo({
  accessToken: accessToken,
  env: 'prod',
});

async function createStandbyWallet() {
  const newWallet = await bitgo.coin('<ASSET_ID>').wallets().generateWallet({
    label: 'Standby Wallet - Hot',
    passphrase: '<YOUR_WALLET_PASSPHRASE>',
    enterprise: '<YOUR_ENTERPRISE_ID>',
    multisigType: 'onchain',
    type: 'hot'
  });

  console.log('Standby Wallet Created:');
  console.log('Wallet ID:', newWallet.wallet.id());
  console.log('Receive Address:', newWallet.wallet.receiveAddress());

  // IMPORTANT: Save the backup keychain securely
  console.log('Backup Keychain (SAVE SECURELY):', newWallet.backupKeychain);
}

createStandbyWallet();

Response

// 1. Create Standby Wallet Response
{
  "wallet": {
    "id": "6849948ac0623f81f74f63dbd8351d4f",
    "users": [
      {
        "user": "62ab90e06dfda30007974f0a52a12995",
        "permissions": ["admin", "spend", "view"]
      }
    ],
    "coin": "btc",
    "label": "Standby Wallet - Hot",
    "m": 2,
    "n": 3,
    "keys": [
      "68499487e6c77351bd3bbf04281fa8bb",
      "68499487cd07fc57de18f6481baa1903",
      "6849948902be620840a384c148d19979"
    ],
    "keySignatures": {
      "backupPub": "1f3e104ba1012c25478032bd2f287dc3...",
      "bitgoPub": "1f90c12ff7107b76e220f75ed834069b..."
    },
    "enterprise": "62c5ae8174ac860007aff138a2d74df7",
    "organization": "62c5ae8174ac860007aff1395e2b19da",
    "bitgoOrg": "BitGo Trust",
    "tags": [
      "6849948ac0623f81f74f63dbd8351d4f",
      "62c5ae8174ac860007aff138a2d74df7"
    ],
    "disableTransactionNotifications": false,
    "freeze": {},
    "deleted": false,
    "approvalsRequired": 1,
    "isCold": false,
    "coinSpecific": {},
    "admin": {
      "policy": {
        "date": "2024-01-15T10:30:00.000Z",
        "id": "6849948ac0623f81f74f63dcd8351d50",
        "label": "default",
        "rules": [],
        "version": 0,
        "latest": true
      }
    },
    "clientFlags": [],
    "walletFlags": [],
    "allowBackupKeySigning": false,
    "recoverable": false,
    "startDate": "2024-01-15T10:30:00.000Z",
    "type": "hot",
    "buildDefaults": {},
    "customChangeKeySignatures": {},
    "hasLargeNumberOfAddresses": false,
    "multisigType": "onchain",
    "hasReceiveTransferPolicy": false,
    "creator": "62ab90e06dfda30007974f0a52a12995",
    "walletFullyCreated": true,
    "config": {},
    "balance": 0,
    "balanceString": "0",
    "rbfBalance": 0,
    "rbfBalanceString": "0",
    "confirmedBalance": 0,
    "confirmedBalanceString": "0",
    "spendableBalance": 0,
    "spendableBalanceString": "0",
    "unspentCount": 0,
    "receiveAddress": {
      "id": "6849948ac0623f81f74f63dfd8351d51",
      "address": "bc1p...",
      "chain": 20,
      "index": 0,
      "coin": "btc",
      "wallet": "6849948ac0623f81f74f63dbd8351d4f",
      "coinSpecific": {
        "witnessScript": "5221..."
      }
    },
    "pendingApprovals": []
  },
  "userKeychain": {
    "id": "68499487e6c77351bd3bbf04281fa8bb",
    "pub": "xpub661MyMwAqRbc…M5v9wyFy",
    "ethAddress": "0x8eac7e29c5db7fe1046dfdeb3563fe97...",
    "source": "user",
    "type": "independent",
    "encryptedPrv": "{...}"
  },
  "backupKeychain": {
    "id": "68499487cd07fc57de18f6481baa1903",
    "pub": "xpub661MyMwAqRbc…Rq6NyLDV",
    "ethAddress": "0xd1644a559d48f346f719adadfe9c0ea0...",
    "source": "backup",
    "type": "independent",
    "encryptedPrv": "{...}"
  },
  "bitgoKeychain": {
    "id": "6849948902be620840a384c148d19979",
    "pub": "xpub661MyMwAqRbc…JXEJDdeo",
    "ethAddress": "0xe8aab88ba7e7aeeaeb6d6dc50250554f...",
    "source": "bitgo",
    "type": "independent",
    "isBitGo": true,
    "isTrust": false,
    "hsmType": "institutional"
  },
  "responseType": "WalletWithKeychains",
  "warning": "Be sure to backup the backup keychain -- it is not stored anywhere else!"
}