Custody Starter Architecture: Set Up Custody Wallet (Multisig)

Create a multisignature custody wallet for cold storage. See the Guide.

Create a custody wallet using the Add Wallet endpoint. BitGo automatically creates and manages all keys for custody wallets. 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.

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 COIN="<ASSET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export LABEL="<YOUR_DESIRED_WALLET_NAME>"

curl -X POST \
  https://app.bitgo-test.com/api/v2/$COIN/wallet/add \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "enterprise": "'"$ENTERPRISE_ID"'",
    "label": "'"$LABEL"'",
    "isCustodial": true
}'

// 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,
    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": "btc",
  "label": "Custody Wallet - Cold Storage",
  "m": 2,
  "n": 3,
  "keys": [
    "62f03dee8d13be0007894b41f63bc504",
    "62f03dee8d13be0007894b43cb0f65d0",
    "62f03dee8d13be0007894b3f8024e0e8"
  ],
  "enterprise": "62c5ae8174ac860007aff138a2d74df7",
  "approvalsRequired": 1,
  "isCold": true,
  "type": "custodial",
  "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": "bc1q..."
  }
}