---
title: "Add wallet-policy rule"
method: POST
path: "/api/v2/{coin}/wallet/{walletId}/policy/rule"
tags: ["Wallet Policy"]
---

# Add wallet-policy rule

`POST /api/v2/{coin}/wallet/{walletId}/policy/rule`

Adds a rule to a wallet's policy. An email notification is sent to wallet users when
the policy is updated (except the first time a policy is added).

## Path parameters

- `coin` string, required — A cryptocurrency symbol or token ticker symbol
- `walletId` string, required

## Request body

- object — Request body for adding a rule to a wallet policy. Defines the rule id, trigger type, action, and optional condition updates. Plain field map for `h.httpRequest` — not a codec. Use {@link CreateWalletPolicyRuleBodyCodec} to decode.
  - `coin` string — If set, the rule applies only to the given coin or ERC20 token in an Ethereum wallet. Generally not recommended for advancedWhitelist, allTx, coinAddressWhitelist, coinAddressBlacklist, or webhook rules.
  - `id` string, required — Caller-defined rule identifier, unique within the policy
  - `type` 'advancedWhitelist' | 'allTx' | 'allTxNoFiat' | 'coinAddressWhitelist' | 'coinAddressBlacklist' | 'velocityLimit' | 'webhook', required — Rule trigger types accepted on POST (create). Intentionally differs from {@link UpdateRemovePolicyRuleType}: create exposes newer names (e.g. `allTxNoFiat`, `coinAddressWhitelist`) while update/delete must accept legacy type strings stored on existing rules (e.g. `bitcoinAddressWhitelist`, `transactionLimit`).
  - `condition` union — Parameters for the rule type (e.g. whitelist add/remove)
    - object
      - `add` WalletPolicyRuleAdvancedListRuleEntry, required — `AdvancedListRuleEntry` in platform.yaml (Json-safe).
        - `item` string, required — A valid blockchain address, wallet ID, enterprise ID, or organization ID
        - `type` 'address' | 'walletId' | 'enterpriseId', required — `ListRuleEntryType` in platform.yaml
        - `metaData` WalletPolicyRuleAdvancedListRuleEntryMetaData — OpenAPI `additionalProperties: true` — arbitrary JSON metadata values.
          - `label` string — A client-specified label for this entry. Label must be unique or not set.
          - `owner` string — The legal owner of the address, wallet, enterprise, or organization.
          - `address` string — The address of the receiver wallet if the whitelist is of type 'walletId'.
        - `verificationState` 'unverified' | 'verified'
        - `verifiedBy` 'unverifiedRule' | 'fastWithdrawal'
    - object
      - `add` string, required — Address to add to the list
      - `metaData` WalletPolicyRuleWhitelistAddMetaData — OpenAPI `additionalProperties: true` — arbitrary JSON metadata values.
        - `addedBy` string — Text indicating who added this address to the whitelist
    - object
      - `remove` union, required — Address to remove from the list
        - string
        - WalletPolicyRuleAdvancedListRuleEntry — `AdvancedListRuleEntry` in platform.yaml (Json-safe).
          - `item` string, required — A valid blockchain address, wallet ID, enterprise ID, or organization ID
          - `type` 'address' | 'walletId' | 'enterpriseId', required — `ListRuleEntryType` in platform.yaml
          - `metaData` WalletPolicyRuleAdvancedListRuleEntryMetaData — OpenAPI `additionalProperties: true` — arbitrary JSON metadata values.
            - `label` string — A client-specified label for this entry. Label must be unique or not set.
            - `owner` string — The legal owner of the address, wallet, enterprise, or organization.
            - `address` string — The address of the receiver wallet if the whitelist is of type 'walletId'.
          - `verificationState` 'unverified' | 'verified'
          - `verifiedBy` 'unverifiedRule' | 'fastWithdrawal'
    - object
  - `action` WalletPolicyRuleAction, required — Json-compatible policy rule action (PolicyRuleAction uses h.optionalized, which is not Json-safe).
    - `type` 'deny' | 'getApproval' | 'getFinalApproval' | 'getCustodianApproval' | 'getIdVerification', required — Policy rule action type (`PolicyRuleActions.type` in platform.yaml).
    - `userIds` string[]
  - `lockDate` string, date-time — The time at which this rule becomes immutable
  - `generatePolicy` boolean — When true or omitted, generates a policy enforcing the whitelist after creation. When false, no policy is generated.

## Response `200`

OK

- Wallet
  - `allowBackupKeySigning` boolean, required
  - `approvalsRequired` number, required
  - `coin` string, required — A cryptocurrency symbol or token ticker symbol
  - `coinSpecific` union, required
    - AdaWallet
      - `rootAddress` string, required
      - `addressCount` string, required
      - `pendingChainInitialization` boolean, required
      - `rewardAddress` string, required
      - `lastChainIndex` object
    - AlgorandWallet
      - `addressVersion` number, required
      - `rootAddress` string, required
      - `trustedTokens` object[]
        - `state` 'pending' | 'active'
        - `limit` string
        - `token` string
    - AtomWallet
      - `rootAddress` string, required
      - `lastMemoId` string, required
      - `lastChainIndex` unknown
      - `pendingEcdsaTssInitialization` boolean
    - AvaxPWallet
      - `unlockAddresses` string[], required
      - `threshold` number, required
    - UtxoWallet
      - `customChangeWalletId` string
      - `customChangeAddressType` string
      - `sendQueueInferredScriptTypes` string[]
      - `allowQuantumUnsafeAddresses` boolean
      - `freezeDepositsFromShielded` boolean
    - CasperWallet
      - `accountHash` string, required
      - `creationFailure` string[], required
      - `lastTransferId` string, required
      - `pendingChainInitialization` boolean, required
      - `rootAddress` string, required
    - DotWallet
      - `rootAddress` string, required
      - `pendingChainInitialization` boolean, required
      - `nonceAddress` string
    - EosWallet
      - `rootAddress` string, required
      - `pendingChainInitialization` boolean, required
      - `creationFailure` string[], required
      - `lastMemoId` string, required
    - EthereumWallet
      - `pendingChainInitialization` boolean, required
      - `creationFailure` string[], required
      - `gasPriceTier` string, required
      - `tokenFlushThresholds` object, required
      - `walletVersion` number, required
      - `pendingDeployment` boolean, required
      - `deployForwardersManually` boolean, required
      - `flushForwardersManually` boolean, required
      - `enableMMI` boolean, required
      - `enableNFT` boolean, required
      - `deployedInBlock` union
        - number
        - boolean
      - `deployTxHash` string
      - `lastChainIndex` unknown
      - `baseAddress` string
      - `feeAddress` string
      - `nonce` string
      - `token` string
      - `pendingEcdsaTssInitialization` boolean
      - `safeModeActivated` string
      - `lowPriorityFeeAddress` string
      - `salt` string
      - `evmKeyRingReferenceWalletId` string
    - Ethereum2Wallet
      - `pendingChainInitialization` boolean, required
      - `baseAddress` string
      - `feeAddress` string
    - FiatWallet
      - `backingBankAccountId` unknown, required
      - `backingSENBankAccountId` unknown, required
      - `lastUsedNonce` number, required
    - HederaWallet
      - `addressCount` number, required
      - `pendingChainInitialization` boolean, required
      - `creationFailure` string[], required
      - `trustedTokens` object[], required
        - `state` 'pending' | 'active'
        - `limit` string
        - `token` string
      - `deployTxHash` string
      - `baseAddress` string
      - `confirmedTransactionId` string
    - NearWallet
      - `nonceAddress` string, required
      - `lastNonce` number, required
      - `addressCount` number, required
      - `pendingChainInitialization` boolean, required
      - `rootAddrss` string
      - `lastChainIndex` object
    - Offchain
      - `needsKeyReshareAfterPasswordReset` boolean, required
      - `pendingSystemInitialization` boolean — If true, this wallet is waiting for the system to finish initializing. In this state, users cannot create addresses or initiate withdrawals.
    - StacksWallet
      - `baseAddress` string
      - `feeAddress` string
      - `lastNonce` number
      - `addressCount` number
    - TestcoinWallet
      - `lastChainIndex` number
    - TonWallet
      - `rootAddress` string, required
      - `memoId` string, required
      - `lastMemoId` string, required
      - `seqno` number, required
      - `lastChainIndex` object
      - `walletVersion` number
    - TronWallet
      - `rootAddress` string, required
      - `rootPub` string, required
      - `pendingChainInitialization` boolean, required
      - `creationFailure` string[], required
      - `minimumFunding` number, required
    - StellarWallet
      - `rootAddress` string, required
      - `pendingChainInitialization` boolean, required
      - `creationFailure` string[], required
      - `lastMemoId` string, required
      - `stellarUsername` string
      - `homeDomain` string
      - `stellarAddress` string
      - `trustedTokens` object[]
        - `state` 'pending' | 'active'
        - `limit` string
        - `token` string
    - XRPWallet
      - `rootAddress` string, required
      - `pendingChainInitialization` boolean, required
      - `creationFailure` string[], required
      - `trustedTokens` object[]
        - `state` 'pending' | 'active'
        - `limit` string
        - `token` string
    - TezosWallet
      - `pendingChainInitialization` boolean, required
      - `creationFailure` string[], required
      - `deployedInBlock` union
        - number
        - boolean
      - `deployTxHash` string
      - `lastChainIndex` unknown
      - `baseAddress` string
      - `feeAddress` string
      - `safeModeActivated` string
      - `lowPriorityFeeAddress` string
      - `delegate` string
    - SolWallet
      - `pendingChainInitialization` boolean, required
      - `minimumFunding` number, required
      - `trustedTokens` object[], required
        - `state` 'pending' | 'active'
        - `limit` string
        - `token` string
      - `rootAddress` string
      - `nonceAddress` string
      - `lastBlockHash` string
      - `lastChainIndex` unknown
      - `nonceExpiresAt` string, date
      - `nonceTxRequestId` string
    - LightningCoinWallet
      - `keys` string[], required
  - `deleted` boolean, required
  - `disableTransactionNotifications` boolean, required
  - `hasLargeNumberOfAddresses` boolean, nullable, required
  - `id` string, required
  - `isCold` boolean, required
  - `label` string, required
  - `startDate` string, date-time, required — Wallet creation time
  - `admin` object
    - `policy` Policy
      - `date` string, date-time, required
      - `id` string, required
      - `latest` boolean, required
      - `version` number, required
      - `enterpriseId` string
      - `label` string
      - `rules` object[]
        - `id` string, required
        - `type` 'advancedWhitelist' | 'coinAddressWhitelist' | 'coinAddressBlacklist', required
        - `action` PolicyRuleAction, required
          - `type` 'deny' | 'getApproval' | 'getEnterpriseUserApproval' | 'getUserRoleApproval' | 'getAnyApproval' | 'getFinalApproval' | 'getVideoApproval' | 'getIdVerification' | 'verifyWalletRebalance' | 'getCustodianApproval' | 'getCustodialSignature' | 'triggerWebhookNotification' | 'performLivenessVerification' | 'recommendBackingWalletRouting' | 'getManualTrustReview' | 'getManualSupportReview' | 'getSupportManagerApproval' | 'getVideoApprovalFromSupport' | 'evaluateFraudRisk', required
          - `userIds` string[]
        - `latest` boolean
        - `version` number
        - `lockDate` string, date-time — The time at which this rule becomes immutable
        - `mutabilityConstraint` 'permanent' | 'managed'
        - `coin` string — A cryptocurrency symbol or token ticker symbol
        - `condition` union
          - object
          - AddressListCondition
            - `addresses` string[], required
            - `metaData` object, required
          - AdvancedListCondition
            - `entries` object[], required
              - …
          - LimitRuleCondition
            - `amountString` string, required
            - `timeWindow` number, required — Time window in seconds for a velocity limit, between 1 and 30 days
            - `groupTags` string[]
            - `startDate` string, date-time
          - TxUsdThresholdRuleCondition
            - `lowerBound` string, required
            - `upperBound` string
          - WebhookRuleCondition
            - `url` string, required — The url to query for the webhook
        - `walletId` string — The ID of the wallet this rule originates from. Populated only when the rule is returned as part of an EVM keyring aggregated response (includeEvmKeyringWhitelist=true) for rules that belong to a derived wallet. Absent for rules on the main wallet itself.
      - `walletId` string
  - `billingEnterprise` string
  - `buildDefaults` object
    - `minFeeRate` number — (UTXO only) Wallet-level minimum fee rate that must be greater than or equal to the default of 1000 satoshis/kvByte. Per transaction, you can override "minFeeRate" with the "feeRate" parameter.
    - `maxFeeRate` number
    - `feeMultiplier` number, nullable
    - `changeAddressType` string, nullable
    - `autoReserveUnspentsOnBuildMins` number, nullable
  - `clientFlags` object[]
    - `name` string
    - `value` boolean
  - `config` object
    - `nodeId` unknown
  - `custodialWalletId` string
  - `customChangeKeySignatures` object
    - `user` string
    - `backup` string
    - `bitgo` string
  - `customerWalletId` string
  - `enterprise` string
  - `evmKeyRingReferenceWalletId` string — Reference wallet ID for EVM keyring wallets (child wallets only)
  - `isParent` boolean — Indicates if this wallet is a parent wallet in an EVM keyring setup
  - `enabledChildChains` string[]
  - `archivedChildChains` string[]
  - `organization` string
  - `bitgoOrg` string
  - `freeze` object
    - `time` string, date-time
    - `expires` string, date-time
    - `reason` 'TxIntentMismatch' | 'TxIntentMismatchRecipient' | 'TxIntentMismatchContract' | 'TxIntentMismatchApproval' | 'UserRequest' | 'AdminRequest'
    - `referenceId` string — An optional reference ID for tracking purposes
    - `adminOrUserId` string — The user who froze the wallet (could be a regular user or an admin)
  - `instantProvider` string
  - `keys` string[]
  - `keySignatures` object
    - `backupPub` string
    - `bitgoPub` string
  - `m` number — Number of signatures required. This value must be 2 for hot wallets, 1 for **ofc** wallets, and not specified for custodial wallets.
  - `migratedFrom` string
  - `multisigType` 'onchain' | 'tss'
  - `multisigTypeVersion` 'MPCv2'
  - `n` number — Number of keys provided. This value must be 3 for hot wallets, 1 for **ofc** wallets, and not specified for custodial wallets.
  - `recoverable` boolean
  - `tags` string[]
  - `type` 'backing' | 'cold' | 'custodial' | 'custodialPaired' | 'hot' | 'advanced' | 'trading'
  - `subType` 'distributedCustody' | 'pairedCustodial' | 'custodialHot' | 'custodialCold' | 'lightningCustody' | 'lightningSelfCustody' | 'onPrem'
  - `balanceString` string — The cleared balance of the address in base units (e.g. Satoshis). Guaranteed to not lose precision. The is only returned if the `expandBalance` query parameter is set to `true`.
  - `balance` number — The cleared balance of the address in base units (e.g. Satoshis). The is only returned if the `expandBalance` query parameter is set to `true`.
  - `confirmedBalanceString` string — The total balance of confirmed transactions in base units (e.g. Satoshis). The is only returned if the `expandBalance` query parameter is set to `true`. Guaranteed to not lose precision.
  - `confirmedBalance` number — The total balance of confirmed transactions in base units (e.g. Satoshis). The is only returned if the `expandBalance` query parameter is set to `true`.
  - `spendableBalanceString` string — The total balance in base units (e.g. Satoshis) which may be used as inputs for creating new transactions in string representation. Guaranteed to not lose precision. The is only returned if the `expandBalance` query parameter is set to `true`.
  - `spendableBalance` number — The total balance in base units (e.g. Satoshis) which may be used as inputs for creating new transactions in string representation. The is only returned if the `expandBalance` query parameter is set to `true`.
  - `stakingBalanceString` string — The staked balance in base units. Guaranteed to not lose precision. The is only returned if the `includeStakingBalances` query parameter is set to `true`.
  - `rewardBalanceString` string — The staking reward balance in base units. Guaranteed to not lose precision. The is only returned if the `includeStakingBalances` query parameter is set to `true`.
  - `withdrawHoldAmountUsdString` string — Total USD value (in cents) of active ACH-deposit related withdraw holds on this wallet. Only present for OFC wallets when `allTokens=true` is passed.
  - `offchain` OffChainWalletBalance
    - `inboundBalance` string, required — Inbound balance in millisatoshis (remote balance)
    - `inboundPendingBalance` string, required — Pending inbound balance in millisatoshis (pending open remote balance)
    - `inboundUnsettledBalance` string, required — Unsettled inbound balance in millisatoshis (unsettled remote balance)
    - `outboundBalance` string, required — Outbound balance in millisatoshis (local balance)
    - `outboundPendingBalance` string, required — Pending outbound balance in millisatoshis (pending open local balance)
    - `outboundUnsettledBalance` string, required — Unsettled outbound balance in millisatoshis (unsettled local balance)
    - `outboundLockedBalance` string, required — Locked (from pending force closed channels) outbound balance in millisatoshis (locked local balance)
    - `outboundReservedBalance` string, required — Total outbound reserved balance in millisatoshis (reserved local balance)
    - `outboundSpendableBalance` string, required — Total outbound spendable balance in millisatoshis (spendable local balance)
  - `users` object[]
    - `needsRecovery` boolean
    - `permissions` string[], required
    - `recoverable` boolean
    - `user` string
  - `walletFlags` object[]
    - `name` 'isStaking' | 'lightning' | 'ambossLightning' | 'musigKp' | 'trackingInscriptions' | 'rbf' | 'coldWalletStaking' | 'tokenizationToken' | 'oneClickStaking' | 'solOfcStaking' | 'suiOfcStaking' | 'enableWalletConnect' | 'enableSolCustomTx' | 'enableAptCustomTx', required
    - `value` string, required
  - `receiveAddress` WalletAddress
    - `coin` string, required — A cryptocurrency symbol or token ticker symbol
    - `wallet` string, required
    - `chain` 0 | 1 | 10 | 11 | 20 | 21 | 30 | 31 | 40 | 41, required
    - `index` number, required
    - `id` string — Platform public ID for an address
    - `address` string
    - `balance` TrimmedBalance
      - `balanceString` string, required — String representation of the balance. Guaranteed to not lose precision.
      - `confirmedBalanceString` string, required — The total balance of confirmed transactions for the address (in the chain's base unit). Guaranteed to not lose precision.
      - `spendableBalanceString` string, required — The total balance of the address (in the chain's base unit) which may be used as inputs for creating new transactions in string representation. Guaranteed to not lose precision.
      - `updated` union — The last time a transaction affected the balance of this address
        - string, date-time
        - string, date
      - `balance` number
      - `lockedBalanceString` string
      - `reservedBalanceString` string
      - `totalReceived` number — The total amount received on this address (in the chain's base unit)
      - `totalSent` number — The total amount sent from this address (in the chain's base unit)
      - `transferCount` number
      - `tokens` object
      - `nfts` object
      - `unsupportedNfts` object
      - `type` unknown
      - `metadata` unknown
    - `coinSpecific` union
      - AlgorandAddress
        - `rootAddress` string, required
        - `trustedTokens` object[]
          - `state` 'pending' | 'active'
          - `limit` string
          - `token` string
        - `addressVersion` number
        - `threshold` number
        - `bitgoKey` unknown
        - `bitgoPubKey` string
      - AtomAddress
        - `rootAddress` string, required
        - `memoId` string, required
      - AvaxPAddress
        - `threshold` number, required
        - `addresses` string[], required
      - UtxoAddress
        - `redeemScript` string
        - `witnessScript` string
      - BitcoinCashAddress
        - `format` 'cashaddr' | 'base58'
        - `redeemScript` string
        - `witnessScript` string
      - CasperAddress
        - `accountHash` string, required
        - `rootAddress` string, required
        - `transferId` string, required
      - DotAddress
        - `rootAddress` string, required
        - `nonceTracker` object, required
          - `lastReservedNonce` number, required
          - `lastExecutedNonce` number, required
          - `detectedMissingNonces` object[], required
            - `nonce` number, required
            - `isNonceLocked` boolean, required
            - `nonceLockExpireTime` string, date
          - `detecMissingNoncesData` object[], required
            - `nonce` number, required
            - `isNonceLocked` boolean, required
            - `nonceLockExpireTime` string, date
      - EosAddress
        - `rootAddress` string, required
        - `memoId` string, required
      - EthereumAddress
        - `creationFailure` string[], required
        - `forwarderVersion` number, required
        - `nonce` number, required
        - `feeAddress` string, required
        - `pendingChainInitialization` boolean, required
        - `pendingDeployment` boolean, required
        - `txCount` number, required
        - `updateTime` string, date, required
        - `hopTxid` string
        - `salt` string
        - `usdtBug` boolean
        - `isTss` boolean
        - `isNonceLocked` boolean
        - `nonceLockExpireTime` string, date
        - `previousLowBalanceEmailSentAt` string, date
      - Ethereum2Address
        - `feeAddress` string
      - FiatAddress
        - `bankAccountId` string
        - `faBankAccountId` string
        - `bankAccount` BankAccountJson
          - `accountNumber` string, required
          - `address1` string, required
          - `name` string, required
          - `owner` object, required
            - `name` string, required
            - `address1` string, required
            - `address2` string
            - `address3` string
          - `idHash` string, required
          - `verificationState` string, required
          - `address2` string
          - `address3` string
          - `enterpriseId` string
          - `id` string
          - `routingNumber` string
          - `shortCountryCode` string
          - `swiftCode` string
          - `type` string
      - HederaAddress
        - `baseAddress` string, required
        - `memoId` string, required
      - OffchainAddressSubdocument
      - SolAddress
        - `rootAddress` string, required
        - `minimumFunding` number, required
        - `pendingChainInitialization` boolean, required
        - `trustedTokens` object[], required
          - `state` 'pending' | 'active'
          - `limit` string
          - `token` string
        - `nonceExpiresAt` string, date
        - `nonceTxRequestid` string
        - `type` string
      - StacksAddress
        - `baseAddress` string, required
        - `memoId` string, required
      - StellarAddress
        - `memoId` string, required
        - `rootAddress` string, required
      - TestcoinAddress
      - TezosAddress
        - `counter` number, required
        - `updateTime` string, date, required
        - `txCount` number, required
        - `pendingChainInitialization` boolean, required
        - `pendingPublicKeyRevelation` boolean, required
        - `creationFailure` string[], required
        - `delegate` string
        - `previousLowBalanceEmailSentAt` string, date
      - TronAddress
        - `rootPub` string, required
      - XRPAddress
        - `nonceTracker` object, required
          - `detectedMissingNonces` object[], required
            - `nonce` number, required
            - `isNonceLocked` boolean, required
            - `nonceLockExpireTime` string, date
          - `detectedMissingNoncesData` object[], required
            - `nonce` number, required
            - `isNonceLocked` boolean, required
            - `nonceLockExpireTime` string, date
      - TonAddress
        - `addresses` string[], required
    - `label` string — A human-readable label for the address
    - `lastNonce` number
    - `token` string
    - `proof` string
    - `signature` string
    - `lastConsolidatedTime` string, date
    - `needsConsolidation` boolean
    - `tokenConsolidationState` unknown
    - `tokenAddress` unknown
  - `customTags` string[]
  - `safe` string — Public id of the safe that minted this wallet. Absent on non-safe wallets.

## Other responses

- `202` — Accepted
- `400` — Bad Request

---

[API](https://skmtc.net/bitgo/apis/bitgo-api.md) · [All operations](https://skmtc.net/bitgo/apis/bitgo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bitgo/bitgo-api/revisions/e445c15e5bee/schema)