Create an internal wallet policy rule

post/api/v2/internal/{coin}/wallet/{walletId}/policy/rule

Creates an advancedWhitelist policy rule on a wallet. The caller must already have enforced enterprise access. Only advancedWhitelist rules are accepted; other rule types are rejected.

Path Parameters

  • coinstringRequired
    Coin network identifier (e.g., "btc", "tsol", "eth").
    Example: btc
  • walletIdstringRequired
    Example: 59cd72485007a239fb00282ed480da1f
    Pattern: ^[0-9a-f]{32}$
    Min length: >= 1 characters

Request Body

id string required
Caller-defined rule identifier, unique within the policy
type string required
Only 'advancedWhitelist' is accepted by this endpoint
Allowed value: advancedWhitelist
action object required
What happens when this rule is triggered
type string required
The type of the action
Allowed values: deny getApproval getEnterpriseUserApproval getUserRoleApproval getAnyApproval getFinalApproval getVideoApproval getIdVerification verifyWalletRebalance getCustodianApproval getCustodialSignature triggerWebhookNotification performLivenessVerification recommendBackingWalletRouting getManualTrustReview getManualSupportReview getSupportManagerApproval getVideoApprovalFromSupport
userIds array[string]
The user IDs associated with the action
condition dictionary<string, any>
Rule condition; shape is validated server-side based on rule type
requestingUser string required
Public id of the wallet admin on whose behalf the rule is being created. Used as the pendingApproval `creator` and as `ctx.user` for audit/notification. MUST resolve to an active wallet admin; otherwise the request is rejected.
Min length: >= 1 characters
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
enterpriseId string
Enterprise the wallet must belong to; if provided, the endpoint verifies wallet.enterprise matches before mutating policy (defense-in-depth).
Min length: >= 1 characters
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$

200 Response

wallet object required
allowBackupKeySigning boolean required
approvalsRequired number required
Minimum: >= 1
Example: 1
coin string required
A cryptocurrency symbol or token ticker symbol
Example: btc
coinSpecificOne ofrequired
deleted boolean required
disableTransactionNotifications boolean required
hasLargeNumberOfAddresses
boolean or null
required
id string required
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
isCold boolean required
label string required
Example: My Wallet
startDate string <date-time>required
Wallet creation time
admin object
billingEnterprise string
buildDefaults object
clientFlags array[object]
config object
custodialWalletId string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
customChangeKeySignatures object
customerWalletId string
enterprise string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
evmKeyRingReferenceWalletId string
Reference wallet ID for EVM keyring wallets (child wallets only)
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
isParent boolean
Indicates if this wallet is a parent wallet in an EVM keyring setup
Example: true
enabledChildChains array[string]
Array of enabled child chain names for parent EVM keyring wallets
Example: ["tbsc","tpolygon"]
archivedChildChains array[string]
Array of archived child chain names for parent EVM keyring wallets (per-user)
Example: ["tbsc","tpolygon"]
organization string
bitgoOrg string
freeze object
instantProvider string
keys array[string]
Example: ["585951a5df8380e0e304a553","585951a5df8380e0e30d645c","585951a5df8380e0e30b6147"]
keySignatures object
m number
Number of signatures required. This value must be 2 for hot wallets, 1 for **ofc** wallets, and not specified for custodial wallets.
Example: 2
migratedFrom string
multisigType string
Allowed values: onchain tss
multisigTypeVersion string
Allowed value: 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.
Example: 3
recoverable boolean
tags array[string]
type string
The type describes who owns the keys to the wallet and how they are stored. "cold" wallets are wallets where the private key of the user key is stored exclusively outside of BitGo's system. "custodial" means that this wallet is a cold wallet where BitGo owns the keys. Only customers of the BitGo Trust can create this kind of wallet. "custodialPaired" means that this is a hot wallet that is owned by the customer but it will be linked to a cold (custodial) wallet where BitGo owns the keys. This option is only available to customers of BitGo Inc. BitGo stores an encrypted private key for the user key of "hot" wallets. "trading" wallets are trading accounts where the coin is "ofc". "distributedCustody" means You manage one key and another key agent manages the second key. BitGo manages the third key
Allowed values: backing cold custodial custodialPaired hot advanced trading
subType string
Allowed values: 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 object
Lightning Balances
users array[object]
walletFlags array[object]
receiveAddress object
userKeySigningRequired boolean deprecated

202 Response

id string required
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
coin string
A cryptocurrency or token ticker symbol.
Example: btc
wallet string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
walletType string
walletSubType string
The subtype of the wallet (e.g., custodialHot)
wallets array[string]
The wallets of the pending approval
Example: 59cd72485007a239fb00282ed480da1f
enterprise string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
organization string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
organizationName string
The organization name
bitgoOrg string
The BitGo organization
creator string required
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
createDate string <date-time>required
The creation date of the pending approval
approvedDate string <date-time>
The date when the approval was granted
updatedAt string <date-time>
The date when the approval was last updated (any update, not just processing)
keyCurve string
The key curve of the coin attached to this pending approval
Allowed values: secp256k1 ed25519 bls12_381
info object required
Information about the pending approval
type string required
Allowed values: userChangeRequest transactionRequest transactionRequestFull policyRuleRequest updateApprovalsRequiredRequest updateEnterpriseRequest updateOrganizationRequest genericRequest enterpriseInviteRequest updateWalletSettingRequest
userChangeRequest object
transactionRequest object
transactionRequestFull object
policyRuleRequest object
updateApprovalsRequiredRequest object
updateEnterpriseRequest object
updateOrganizationRequest object
genericRequest object
enterpriseInviteRequest object
updateWalletSettingRequest object
stateOne ofrequired
The state of the pending approval
Allowed values: pending awaitingSignature pendingFinalApproval pendingCustodianApproval pendingVideoApproval pendingIdVerification pendingLivenessVerification pendingManualTrustReview pendingManualSupportReview pendingVideoApprovalFromSupport
scope string required
What kind of entity the Pending Approval is tied to
Allowed values: enterprise wallet organization global
userIds array[string]
All the Users who should see this Pending Approval
approvalsRequired number
Minimum: >= 1
Example: 1
walletLabel string
Label for the wallet
addressLabels array[object]
Address labels of recipients in this Pending Approval
address string required
Max length: <= 250 characters
Example: 2MvrwRYBAuRtPTiZ5MyKg42Ke55W3fZJfZS
label string required
The label
walletLabel string
The wallet label
resolvers array[object]
Resolvers for the pending approval
autoApproved boolean
Whether the resolution was auto approved
date string <date-time>
The date of resolution
resolutionAction string
Action taken during resolution
Allowed values: approve reject skip fail
resolutionMemo string
Memo regarding the resolution
resolutionType string required
The type of resolution
Allowed values: pending awaitingSignature pendingFinalApproval pendingCustodianApproval pendingVideoApproval pendingIdVerification pendingLivenessVerification pendingManualTrustReview pendingManualSupportReview pendingVideoApprovalFromSupport
user string
The user who resolved the approval
videoApprover string
The approver of the video resolution
videoException string
Exception details for the video
videoLink string
Link to the resolution video
approvers array[string]
List of approvers
singleRunResults array[object]
Results from single run checks
ruleId string
The rule ID
triggered boolean
Whether the rule was triggered
txRequestId string <uuid>
Transaction request ID
Example: 123e4567-e89b-12d3-a456-426614174000
videoId object
ID for the video related to the approval
date string <date-time>
The date of the video ID
user string
The user associated with the video ID
videoApprover string
The approver of the video
videoException string
The exception related to the video
videoLink string
The link to the video
version number
Version of the pending approval
policyEvaluationId string
ID for the policy evaluation
actions array[object]
List of actions taken
approvers array[string]
The approvers of the action
excludedApprovers array[string]
Users that are eligible approvers but cannot approve (e.g. already approved or the initiator)
id string required
The ID of the action
name string required
The name of the action
operator string
The operator of the action
Allowed values: AND OR
parameters object required
The parameters of the action
resolvers array[object]
The resolvers of the action
status string required
The status of the action
Allowed values: SKIPPED PENDING NOT_NEEDED COMPLETE CANCELLED FAILED AUTO_CANCELLED
resolutionOrder array[object]
Order of resolution
actions array[string] required
useLegacyPolicyEngine boolean
Flag to use legacy policy engine
videoCallId string
ID for the video call
lastUpdated string <date-time>
The last date the approval was processing
freeze object
The freeze state
actions array[object]
state string
Allowed values: frozen unFrozen
memo array[object]
Admin memos attached to this pending approval
text string required
The text of the memo
time string <date-time>required
The time the memo was created
userId string required
The user ID of the admin who created the memo
username string required
The username of the admin who created the memo
associatedInquiries array[object]
Associated inquiries
inquiryId string required
inquiryStatus string required
Allowed values: completed failed
inquirySubType string required
Allowed values: withdrawalLivenessCheck managePolicyLivenessCheck
inquiryType string required
Allowed value: livenessCheck

400 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id

401 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id

403 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id

404 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id

409 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id