Custody Starter Architecture: Set Up Custody Wallet (MPC)

Create an MPC custody wallet for cold storage. See the Guide.

Create an MPC custody wallet using BitGo Express. The custody wallet serves as your cold storage for the majority of your assets. BitGo manages all keys for custody wallets, providing the highest level of security. Withdrawals from custody wallets require video verification with a BitGo operator.

Use walletVersion: 5 for ECDSA assets such as ETH and MATIC. Save the wallet ID from the response. You need this to configure whitelist policies and to reference this wallet in subsequent steps.

API Reference

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

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

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

const accessToken = '<YOUR_ACCESS_TOKEN>';

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

async function createCustodyWallet() {
  const options = {
    label: 'Custody Wallet - Cold Storage',
    isCustodial: true,
    multisigType: 'tss',
    enterprise: '<YOUR_ENTERPRISE_ID>'
  };

  const newWallet = await bitgo.coin('<ASSET_ID>').wallets().add(options);
  console.log('Custody Wallet Created:');
  console.log('Wallet ID:', newWallet.id());
  console.log('Receive Address:', newWallet.receiveAddress());
}

createCustodyWallet();

Response

// 1. Create Custody Wallet Response
{
  "id": "62f03dee8d13be0007894b3dbc21be17",
  "users": [
    {
      "user": "62ab90e06dfda30007974f0a52a12995",
      "permissions": ["admin", "view", "spend"]
    }
  ],
  "coin": "eth",
  "label": "Custody Wallet - Cold Storage",
  "m": 2,
  "n": 3,
  "keys": [
    "62f03dee8d13be0007894b41f63bc504",
    "62f03dee8d13be0007894b43cb0f65d0",
    "62f03dee8d13be0007894b3f8024e0e8"
  ],
  "enterprise": "62c5ae8174ac860007aff138a2d74df7",
  "approvalsRequired": 1,
  "isCold": true,
  "type": "custodial",
  "multisigType": "tss",
  "admin": {
    "policy": {
      "rules": [
        {
          "id": "Custody Wallet Transaction Custodian Approval",
          "mutabilityConstraint": "permanent",
          "type": "allTx",
          "action": {
            "type": "getCustodianApproval"
          }
        },
        {
          "id": "Custody Wallet Whitelist",
          "mutabilityConstraint": "managed",
          "type": "advancedWhitelist",
          "action": {
            "type": "deny"
          },
          "condition": {
            "entries": []
          }
        }
      ]
    }
  },
  "receiveAddress": {
    "address": "0x..."
  }
}