Update Wallet Whitelists

Overview

You can update a wallet whitelist if the wallet policy is unlocked. Whitelist policies for self-custody wallets lock 48 hours after creation. Use this time to test and make changes to the whitelist and the policy. If you need to update a whitelist once the policy locks, request to unlock it by contacting [email protected].

Prerequisites

1. Update Whitelist

The following example adds an additional address to the whitelist.

Endpoint: Update Wallet-Policy Rule

export COIN="<ASSET_ID>"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ID="<NAME_OF_WHITELIST>"
export ITEM="<ADDRESS_TO_WHITELIST>"

curl -X PUT \
  "https://app.bitgo-test.com/api/v2/$COIN/wallet/$WALLET_ID/policy/rule" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "coin": "'"$COIN"'",
  "id": "'"$ID"'",
  "type": "advancedWhitelist",
  "condition": {
    "add": {
      "type": "address",
      "item": "'"$ITEM"'"
    }
  },
  "action": {
    "type": "deny"
  }
}'

const BitGoJS = require('bitgo');
const bitgo = new BitGoJS.BitGo({ env: 'test' });
const promise = require('bluebird');

// Set your access token here
const accessToken = '<YOUR_ACCESS_TOKEN>';
// Set your coin of choice here
const coin = '<ASSET_ID>';
// Set your wallet Id here
const walletId ='<YOUR_WALLET_ID>';

promise.coroutine(function *() {
  bitgo.authenticateWithAccessToken({ accessToken });

  const wallet = yield bitgo.coin(coin).wallets().get({ id: walletId });

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

  const policy = {
    action: {
      type: 'deny'
    },
    condition: {
      add: { // OR remove
      item: '<ADDRESS_TO_WHITELIST>',
      type: 'address',
      metaData: {
        label: "Recipient Wallet"
      }
     },
    },
    id: 'Test Policy',
    type: 'advancedWhitelist'
  };

  const result = yield wallet.setPolicyRule(policy);
  console.dir(result);
})();

Step Result

If updating the whitelist doesn't require approval, the update is now in effect.

{
  "id": "66e9f4bb549f6c3957f8977fe3ed6ab4",
  "users": [
    {
      "user": "62ab90e06dfda30007974f0a52a12995",
      "permissions": ["admin", "spend", "view"]
    }
  ],
  "coin": "tbtc4",
  "label": "Policy Wallet 2",
  "m": 2,
  "n": 3,
  "keys": [
    "66e9f4ac6bfc0956265268311208afd7",
    "66e9f4ac9231837dc9c945a6c4a725d0",
    "66e9f4adbfe06bac12b54a93d22b6dfc"
  ],
  "keySignatures": {},
  "enterprise": "62c5ae8174ac860007aff138a2d74df7",
  "bitgoOrg": "BitGo Trust",
  "tags": [
    "66e9f4bb549f6c3957f8977fe3ed6ab4",
    "62c5ae8174ac860007aff138a2d74df7"
  ],
  "disableTransactionNotifications": false,
  "freeze": {},
  "deleted": false,
  "approvalsRequired": 1,
  "isCold": false,
  "coinSpecific": {},
  "admin": {
    "policy": {
      "date": "2024-09-18T22:16:50.522Z",
      "id": "66e9f4bb549f6c3957f897824915d45f",
      "label": "default",
      "rules": [
        {
          "id": "My First Wallet Policy for a Whitelist",
          "lockDate": "2025-09-18T22:05:21.219Z",
          "coin": "tbtc4",
          "type": "advancedWhitelist",
          "action": { "type": "deny", "userIds": [] },
          "condition": {
            "entries": [
              {
                "item": "2N6CWMMYXdufJyBa16KNorHs8AakXcqyHhf",
                "type": "address"
              },
              {
                "item": "2N4MTidamwHgzcgVnvWeSSW2s7jfszB7SNu",
                "type": "address"
              }
            ]
          }
        }
      ],
      "version": 6,
      "latest": true
    }
  },
  "clientFlags": [],
  "walletFlags": [],
  "allowBackupKeySigning": false,
  "startDate": "2024-09-17T21:29:31.000Z",
  "type": "hot",
  "buildDefaults": {},
  "customChangeKeySignatures": {},
  "hasLargeNumberOfAddresses": false,
  "multisigType": "onchain",
  "hasReceiveTransferPolicy": false,
  "config": {}
}

{
  "pendingApproval": {
    "id": "66edb40bacdd0951e73c4211711fc126", # admin who approves the wallet policy needs this ID
    "coin": "tbtc4",
    "wallet": "66e9aba320e050e4334b23285bfe3b2e",
    "wallets": [],
    "enterprise": "62c5ae8174ac860007aff138a2d74df7",
    "bitgoOrg": "BitGo Trust",
    "creator": "62ab90e06dfda30007974f0a52a12995",
    "createDate": "2024-09-20T17:42:35.026Z",
    "info": {
      "type": "policyRuleRequest",
      "policyRuleRequest": {
        "action": "update",
        "update": {
          "id": "My First Wallet Policy for a Whitelist",
          "type": "advancedWhitelist",
          "action": { "type": "deny", "userIds": [] },
          "condition": {
            "add": {
              "type": "address",
              "item": "2N4MTidamwHgzcgVnvWeSSW2s7jfszB7SNu"
            }
          },
          "coin": "tbtc4"
        }
      }
    },
    "approvers": [],
    "state": "pending",
    "scope": "wallet",
    "userIds": [
      "62ab90e06dfda30007974f0a52a12995",
      "627ff9325a5c1b0007c05a40d15e1522"
    ],
    "approvalsRequired": 1,
    "singleRunResults": [],
    "resolvers": [],
    "actions": [],
    "resolutionOrder": []
  }
}

2. Approve Whitelist (Optional)

Note: If updating your wallet policy requires approval, another admin must approve it.

Endpoint: Update Pending Approval

export APPROVAL_ID="<APPROVAL_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export OTP="<YOUR_OTP>"

curl -X PUT \
  https://app.bitgo-test.com/api/v2/pendingApprovals/$APPROVAL_ID \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "state": "approved",
    "otp": "'"$OTP"'"
  }'

const baseCoin = this.bitgoSDK.coin(initialPendingApproval.coin);
const pendingApproval = await baseCoin.pendingApprovals().get({ id: initialPendingApproval.id });
const result = await pendingApproval.approve(params);

Step Result

Your wallet policy is approved and your whitelist is now in effect.

{
  "id": "66edb40bacdd0951e73c4211711fc126",
  "coin": "tbtc4",
  "wallet": "66e9aba320e050e4334b23285bfe3b2e",
  "wallets": [],
  "enterprise": "62c5ae8174ac860007aff138a2d74df7",
  "bitgoOrg": "BitGo Trust",
  "creator": "62ab90e06dfda30007974f0a52a12995",
  "createDate": "2024-09-20T17:42:35.026Z",
  "approvedDate": "2024-09-20T17:48:29.296Z",
  "info": {
    "type": "policyRuleRequest",
    "policyRuleRequest": {
      "action": "update",
      "update": {
        "id": "My First Wallet Policy for a Whitelist",
        "type": "advancedWhitelist",
        "action": { "type": "deny", "userIds": [] },
        "condition": {
          "add": {
            "type": "address",
            "item": "2N4MTidamwHgzcgVnvWeSSW2s7jfszB7SNu"
          }
        },
        "coin": "tbtc4"
      }
    }
  },
  "approvers": [],
  "state": "approved",
  "scope": "wallet",
  "userIds": [
    "62ab90e06dfda30007974f0a52a12995",
    "627ff9325a5c1b0007c05a40d15e1522"
  ],
  "approvalsRequired": 1,
  "singleRunResults": [],
  "resolvers": [
    {
      "user": "627ff9325a5c1b0007c05a40d15e1522",
      "date": "2024-09-20T17:48:29.193Z",
      "resolutionType": "pending",
      "resolutionAction": "approve"
    }
  ],
  "actions": [],
  "resolutionOrder": []
}

Next

You can view whitelists and wallet policies using the Get Wallet by Coin and ID endpoint.

See Also

API Reference: Update Wallet-Policy Rule

Updated 14 days ago