Custody Starter Architecture: Create Whitelists (Custody-Standby)

Create bidirectional whitelists between custody and standby wallets. See the Guide.

Add the standby wallet address to the custody wallet whitelist. This ensures funds from the custody wallet can only go to the standby wallet. The whitelist policy is now active on the custody wallet. BitGo automatically denies any withdrawal attempt to an address not on the whitelist.

For self-custody wallets, new whitelist policies lock 48 hours after creation and can only be unlocked by BitGo support. Custody wallets have different lock periods managed by BitGo.

API Reference
Add the custody wallet address to the standby wallet whitelist. This allows funds to flow back from the standby wallet to the custody wallet.

You add the deposit/withdraw wallet address to the standby wallet whitelist in the Standby-Deposit cookbook.

API Reference

// 1. Create Whitelist on Custody Wallet
export COIN="<ASSET_ID>"
export CUSTODY_WALLET_ID="<CUSTODY_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export STANDBY_WALLET_ADDRESS="<STANDBY_WALLET_ADDRESS>"

curl -X POST \
  "https://app.bitgo-test.com/api/v2/$COIN/wallet/$CUSTODY_WALLET_ID/policy/rule" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "coin": "'"$COIN"'",
  "id": "Custody to Standby Whitelist",
  "type": "advancedWhitelist",
  "condition": {
    "add": {
      "type": "address",
      "item": "'"$STANDBY_WALLET_ADDRESS"'",
      "metaData": {
        "label": "Standby Wallet"
      }
    }
  },
  "action": {
    "type": "deny"
  }
}'
// 2. Create Whitelist on Standby Wallet (to Custody)
export STANDBY_WALLET_ID="<STANDBY_WALLET_ID>"
export CUSTODY_WALLET_ADDRESS="<CUSTODY_WALLET_ADDRESS>"

curl -X POST \
  "https://app.bitgo-test.com/api/v2/$COIN/wallet/$STANDBY_WALLET_ID/policy/rule" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "coin": "'"$COIN"'",
  "id": "Standby to Custody Whitelist",
  "type": "advancedWhitelist",
  "condition": {
    "add": {
      "type": "address",
      "item": "'"$CUSTODY_WALLET_ADDRESS"'",
      "metaData": {
        "label": "Custody Wallet"
      }
    }
  },
  "action": {
    "type": "deny"
  }
}'

// 1. Create Whitelist on Custody Wallet
const BitGoJS = require('bitgo');
const bitgo = new BitGoJS.BitGo({ env: 'prod' });

const accessToken = '<YOUR_ACCESS_TOKEN>';
const coin = '<ASSET_ID>';
const custodyWalletId = '<CUSTODY_WALLET_ID>';
const standbyWalletAddress = '<STANDBY_WALLET_ADDRESS>';

async function createCustodyWhitelist() {
  bitgo.authenticateWithAccessToken({ accessToken });

  const wallet = await bitgo.coin(coin).wallets().get({ id: custodyWalletId });

  console.log(`Setting whitelist policy on custody wallet ${wallet.label()}`);

  const policy = {
    action: {
      type: 'deny'
    },
    condition: {
      add: {
        item: standbyWalletAddress,
        type: 'address',
        metaData: {
          label: 'Standby Wallet'
        }
      }
    },
    id: 'Custody to Standby Whitelist',
    type: 'advancedWhitelist'
  };

  const result = await wallet.createPolicyRule(policy);
  console.log('Whitelist created:', result);
}

createCustodyWhitelist();
// 2. Create Whitelist on Standby Wallet (to Custody)
const standbyWalletId = '<STANDBY_WALLET_ID>';
const custodyWalletAddress = '<CUSTODY_WALLET_ADDRESS>';

async function createStandbyToCustodyWhitelist() {
  bitgo.authenticateWithAccessToken({ accessToken });

  const wallet = await bitgo.coin(coin).wallets().get({ id: standbyWalletId });

  console.log(`Setting whitelist policy on standby wallet ${wallet.label()}`);

  const policy = {
    action: {
      type: 'deny'
    },
    condition: {
      add: {
        item: custodyWalletAddress,
        type: 'address',
        metaData: {
          label: 'Custody Wallet'
        }
      }
    },
    id: 'Standby to Custody Whitelist',
    type: 'advancedWhitelist'
  };

  const result = await wallet.createPolicyRule(policy);
  console.log('Whitelist created:', result);
}

createStandbyToCustodyWhitelist();

Response

// 1. Create Whitelist on Custody Wallet Response
{
  "id": "66e9f4bb549f6c3957f8977fe3ed6ab4",
  "coin": "btc",
  "label": "Custody Wallet - Cold Storage",
  "admin": {
    "policy": {
      "rules": [
        {
          "id": "Custody to Standby Whitelist",
          "lockDate": "2025-09-18T22:05:21.219Z",
          "coin": "btc",
          "type": "advancedWhitelist",
          "action": { "type": "deny", "userIds": [] },
          "condition": {
            "entries": [
              {
                "item": "bc1p...",
                "type": "address",
                "metaData": {
                  "label": "Standby Wallet"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

// 2. Create Whitelist on Standby Wallet (to Custody) Response
{
  "id": "6849948ac0623f81f74f63dbd8351d4f",
  "coin": "btc",
  "label": "Standby Wallet - Hot",
  "admin": {
    "policy": {
      "rules": [
        {
          "id": "Standby to Custody Whitelist",
          "lockDate": "2025-09-18T22:05:21.219Z",
          "coin": "btc",
          "type": "advancedWhitelist",
          "action": { "type": "deny", "userIds": [] },
          "condition": {
            "entries": [
              {
                "item": "bc1q...",
                "type": "address",
                "metaData": {
                  "label": "Custody Wallet"
                }
              }
            ]
          }
        }
      ]
    }
  }
}