--- title: "Initiate a transaction" method: POST path: "/api/v2/{coin}/wallet/{walletId}/tx/initiate" tags: ["Wallet"] --- # Initiate a transaction `POST /api/v2/{coin}/wallet/{walletId}/tx/initiate` Initiate an unsigned transaction to create a pending approval. This is useful to request funds to be sent from custodial wallets. Use only with custodial wallets. ## Path parameters - `coin` string, required — A cryptocurrency symbol or token ticker symbol - `walletId` string, required ## Request body - object — Request body for initiating a custodial wallet transaction. Combines BuildParams with recipients and optional video approvers. - `type` string — Required for transactions from MPC wallets. "acceleration" speeds up transactions with a certain nonce by adjusting the gas setting. "accountSet" is for XRP AccountSet transactions. "consolidate" combines multiple UTXO inputs into fewer outputs. "enabletoken" is for SOL. "fanout" splits UTXO inputs into many smaller outputs (UTXO coins only). "stakingLock" and "stakingUnlock" are for Stacks delegations. "transfer" is for native-asset transfers. "trustline" is for Stellar trustline transactions. Possible types include: [acceleration, accountSet, consolidate, enabletoken, fanout, stakingLock, stakingUnlock, transfer, transfertoken, trustline] For AVAX, possible types include: `addValidator`, `export`, and `import`. For XRP, possible types include: `payment` and `accountSet`. The default is `payment`. For STX, type is required. - `messages` object[] - `address` string, required — The address for which you're proving ownership. This address must belong to the wallet. - `message` string, required — Message that is being signed. - `numBlocks` number — (BTC only) The number of blocks required to confirm a transaction. You can use `numBlocks` to estimate the fee rate by targeting confirmation within a given number of blocks. If both `feeRate` and `numBlocks` are absent, the transaction defaults to 2 blocks for confirmation. Note: The `maxFeeRate` limits the fee rate generated by `numBlocks`. - `feeRate` number — Custom fee rate (in base units) per kilobyte (or virtual kilobyte). For example, satoshis per kvByte. If the `feeRate` is less than the minimum required network fee, then the minimum fee applies. For example, 1000 sat/kvByte, a flat 1000 microAlgos, or a flat 10 drops of xrp. For XRP, the actual fee is usually 4.5 times the open ledger fee. Note: The `feeRate` overrides the `maxFeeRate` and `minFeeRate`. - `maxFeeRate` number — (BTC only) The maximum fee rate (in base units) per kilobyte (or virtual kilobyte). For example, satoshis per kvByte. The `maxFeeRate` limits the fee rate generated by both `feeMultiplier` and `numBlocks`. Note: The `feeRate` overrides the `maxFeeRate`. - `feeMultiplier` union — (UTXO only) Custom multiplier to the `feeRate`. The resulting fee rate is limited by the `maxFeeRate`. For replace-by-fee (RBF) transactions (that include `rbfTxIds`), the `feeMultiplier` must be greater than 1, since it's an absolute fee multiplier to the transaction being replaced. Note: The `maxFeeRate` limits the fee rate generated by `feeMultiplier`. - number - string - `minConfirms` number — The unspent selection for the transaction will only consider unspents with at least this many confirmations to be used as inputs. Does not apply to change outputs unless used in combination with `enforceMinConfirmsForChange`. - `enforceMinConfirmsForChange` boolean — When set to true, will enforce minConfirms for change outputs. - `gasPrice` number — Custom gas price to be used for sending the transaction. Only for ETH and ERC20 tokens. - `eip1559` object — EIP-1559 transaction parameters. Only for ETH and ERC20 tokens. - `maxFeePerGas` number, required - `maxPriorityFeePerGas` number, required - `gasLimit` number — Custom gas limit to be used for sending the transaction. Only for ETH and ERC20 tokens. - `targetWalletUnspents` number — Specifies the minimum count of good-sized unspents to maintain in the wallet. Change splitting ceases when the wallet has `targetWalletUnspents` good-sized unspents. **Note**: Wallets that continuously send a high count of transactions will automatically split large change amounts into multiple good-sized change outputs while they have fewer than `targetWalletUnspents` good-sized unspents in their unspent pool. Breaking up large unspents helps to reduce the amount of unconfirmed funds in flight in future transactions, and helps to avoid long chains of unconfirmed transactions. This is especially useful for newly funded wallets or recently refilled send-only wallets. - `minValue` number — Ignore unspents smaller than this amount of base units (e.g. satoshis). For doge, only string is allowed. - `maxValue` number — Ignore unspents larger than this amount of base units (e.g. satoshis). For doge, only string is allowed. - `sequenceId` string — A `sequenceId` is a unique and arbitrary wallet identifier applied to transfers and transactions at creation. It is optional but highly recommended. With a `sequenceId` you can easily reference transfers and transactions—for example, to safely retry sending. Because the system only confirms one send request per `sequenceId` (and fails all subsequent attempts), you can retry sending without the risk of double spending. The `sequenceId` is only visible to users on the wallet and is not shared publicly. - `nonce` string — (DOT only) A nonce ID is a number used to protect private communications by preventing replay attacks. This is an advanced option where users can manually input a new nonce value in order to correct or fill in a missing nonce ID value. - `noSplitChange` boolean — Set `true` to disable automatic change splitting. Also see: `targetWalletUnspents` - `unspents` string[] - `changeAddress` string — Specifies a custom destination address for the transaction's change output(s) - `txFormat` 'legacy' | 'psbt' | 'psbt-lite' — [UTXO only] Format of the returned transaction hex serialization. `legacy` for serialized transaction in custom bitcoinjs-lib format. `psbt` for BIP174 serialized transaction - `instant` boolean — (DASH only) Specifies whether or not to use Dash's "InstantSend" feature when sending a transaction. - `memo` object — Extra transaction information for CSPR, EOS, HBAR, RUNE, STX, TON, XLM, and XRP. Required for XLM transactions. Note: For XRP this is the destination tag (DT), for CSPR this is the transfer ID and for ALGO this is the message field. - `type` string, required - `value` string, required - `comment` string — An optional memo for the transaction. - `destinationChain` string — (AVAXC and AVAXP only) Destination chain for an AVAX import/export transaction. One of [P, C]. - `sourceChain` string — (AVAXC and AVAXP only) Source chain for an AVAX import/export transaction. One of [P, C]. - `addressType` string — DEPRECATED - use `changeAddressType`. The type of address to create for change. One of `p2sh`, `p2shP2wsh`, `p2wsh`, or `p2tr`. - `changeAddressType` union — The address type for the change address. One of `p2sh`, `p2shP2wsh`, `p2wsh`, `p2tr` or `p2trMusig2`, or an ordered array of those address types (`ChangeAddressTypes`). - 'p2sh' | 'p2shP2wsh' | 'p2wsh' | 'p2tr' | 'p2trMusig2' — platform.yaml `components/schemas/AddressType` - string[] - `startTime` string — Unix timestamp in seconds.nanoseconds format, denoting the start of the validity window. Only for HBAR transactions. - `consolidateId` string — (ALGO/TEZOS only) Consolidation ID of this consolidation transaction. - `lastLedgerSequence` number — (XRP only) Absolute max ledger the transaction should be accepted in, whereafter it will be rejected - `ledgerSequenceDelta` number — (XRP only) Relative ledger height (in relation to the current ledger) that the transaction should be accepted in, whereafter it will be rejected - `cpfpTxIds` string[] - `cpfpFeeRate` number — The desired effective fee rate of the accelerated transaction in base units per kilobyte (e.g. satoshi/kB), the unconfirmed transactions it depends on, and the newly created Child-Pays-For-Parent transaction. Must be higher than the current effective fee rate of the target transaction. - `rbfTxIds` string[] - `isReplaceableByFee` boolean — It is used to mark an UTXO transaction eligible for Replace-By-Fee (RBF) later. - `maxFee` number — Limits the amount of satoshis that can be used for fees in a Child-Pays-For-Parent (CPFP) transaction. CPFP transactions accelerate the targeted transaction and all of the unconfirmed transactions the targeted transaction depends on. `maxFee` is required for all CPFP transactions as it allows users to set a safety net that will halt CPFP attempts that exceed the expected cost. - `strategy` string — Optional unspent selection strategy to use. One of `RANDOM`, `FIFO` or `BNB`. - `validFromBlock` number — Optional block this transaction is valid from - `validToBlock` number — Optional block this transaction is valid until - `trustlines` object[] - `action` 'add' | 'remove' - `limit` string — platform.yaml `components/schemas/IntegerString` - `token` string — One of the supported coin types for Stellar tokens listed in Coin-specific-implementation - `stakingOptions` union — Required object for staking. Only for CSPR and STX. - InitiateTransactionCSPRStakingOptions — CSPR staking options for delegate or undelegate transactions. - `amount` number, required - `validator` string, required - InitiateTransactionSTXStakingOptions — STX staking options for delegate or revoke-delegate transactions. - `contractName` string, required — The STX staking contract name. Use pox-3. - `functionName` string, required — STX staking contract function. - `functionArgs` union[], required - union — The 4 Objects are required and in the order expressed. - InitiateTransactionSTXStakingFunctionArgUint128 — STX staking function argument with type uint128. - `type` 'uint128', required — Type of argument. Use the default. - `val` string, required — Amount in micro-stx - InitiateTransactionSTXStakingFunctionArgPrincipal — STX staking function argument with type principal. - `type` 'principal', required — Type of argument. Use the default. - `val` string, required — Address of the validator - InitiateTransactionSTXStakingFunctionArgOptional — STX staking function argument with type optional. - `type` 'optional', required — Type of argument. Use the default. - `val` union, required — Value for an optional STX staking function argument. - … - `unstakingOptions` object — Options needed to unstake EOS assets - `from` string — The name or address of the account that originally staked assets - `receiver` string — The name or address of the account that had assets staked to - `unstakeCpuQuantity` string — The string amount of assets to unstake from CPU and asset symbol separated by a space (e.g. '100 EOS') - `unstakeNetQuantity` string — The string amount of assets to unstake from Net and asset symbol separated by a space (e.g. '100 EOS') - `refundOptions` object — Options needed to refund unstaked EOS assets if automatic refund fails - `address` string — The name or address of the account that originally unstaked assets - `messageKey` string — Optional parameter that takes a hexadecimal value to set `messagekey` for an XRP `accountSet` transaction. Recipients field should be empty when `messageKey` is set. - `reservation` object — Optional parameter for UTXO coins to automatically reserve the unspents that are used in the build. Useful for Cold wallets. If using, must set expireTime. - `expireTime` string, date-time, required — Required. The time that the unspent reservations should expire. - `recipients` object[] - `address` string, required - `amount` union, required — String representation of the amount to send in base units (satoshis/litoshis/zatoshis/duffs). For doge, only string is allowed. Passing in 'max' will send the recipient the maximum amount available, minus fees and amounts for other recipients. Only a single recipient with a 'max' amount is allowed. - number - 'max' | 'invoice' - `memo` union — A memo for this recipient. Accepts MemoString (Stacks only) or InitiateTransactionMemoObject (CSPR, EOS, HBAR, RUNE, STX, TON, XLM, XRP). MemoString: a memo for this specific transaction; this format is only available for Stacks. - string - object — Extra transaction information for CSPR, EOS, HBAR, RUNE, STX, TON, XLM, and XRP. Required for XLM transactions. Note: For XRP this is the destination tag (DT), for CSPR this is the transfer ID and for ALGO this is the message field. - `type` string, required - `value` string, required - `videoApprovers` string[] ## Response `202` Accepted - PendingApproval - `id` string, required - `coin` string — A cryptocurrency or token ticker symbol. - `wallet` string - `walletType` string - `walletSubType` string — The subtype of the wallet (e.g., custodialHot) - `wallets` string[] - `enterprise` string - `organization` string - `safeId` string — The safe the pending approval is scoped to - `organizationName` string — The organization name - `bitgoOrg` string — The BitGo organization - `creator` string, required - `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` 'secp256k1' | 'ed25519' | 'bls12_381' — The key curve of the coin attached to this pending approval - `info` PendingApprovalInfo, required - `type` 'userChangeRequest' | 'transactionRequest' | 'transactionRequestFull' | 'policyRuleRequest' | 'updateApprovalsRequiredRequest' | 'updateEnterpriseRequest' | 'updateOrganizationRequest' | 'genericRequest' | 'enterpriseInviteRequest' | 'updateWalletSettingRequest' | 'updateWalletTagsRequest', required - `userChangeRequest` object - `action` string — The action taken - `permissions` string[] - `userChanged` string — The user that changed - `transactionRequest` object - `buildParams` unknown - `coinSpecific` unknown - `comment` string, nullable — The comment for the transaction request - `fee` unknown - `isUnsigned` boolean, nullable — Indicates if the transaction is unsigned - `policyUniqueId` unknown - `recipients` object[] - `address` string — The address of the recipient - `amount` string — The amount to be transferred - `data` string — Additional data for the transaction - `requestedAmount` unknown - `sourceWallet` unknown - `triggeredPolicy` unknown - `validTransaction` string — Indicates if the transaction is valid - `validTransactionHash` string — The hash of the valid transaction - `verificationItems` string[], nullable — The verification items for the transaction - `verificationRuleId` string, nullable — The ID of the verification rule - `videoApprovers` unknown[] - unknown - `transactionRequestFull` object - `intent` union - object — ============================================================================ REUSABLE SCHEMA FRAGMENTS FOR ASSET-CONTAINING INTENTS ============================================================================ These schemas define reusable building blocks that concrete intent schemas can compose with. They serve multiple purposes: 1. **Schema Reuse**: Concrete intents can intersect with these fragments 2. **Pattern Matching**: getAssetsFromIntent utility matches against these 3. **Type Safety**: Ensures consistency across all asset-containing intents 4. **Documentation**: Clearly shows which intents handle which asset types By using the actual RecipientEntry and TokenRecipientEntry types, we ensure these patterns exactly match the structures used in concrete intents. - `intentType` 'payment', required — Must be "payment". - `sequenceId` string - `comment` string - `nonce` union — Override the on-chain nonce for this transaction. - string - number - `recipients` object[], required - `address` Address, required - … - `amount` Amount, required - … - `data` string - object — ============================================================================ REUSABLE SCHEMA FRAGMENTS FOR ASSET-CONTAINING INTENTS ============================================================================ These schemas define reusable building blocks that concrete intent schemas can compose with. They serve multiple purposes: 1. **Schema Reuse**: Concrete intents can intersect with these fragments 2. **Pattern Matching**: getAssetsFromIntent utility matches against these 3. **Type Safety**: Ensures consistency across all asset-containing intents 4. **Documentation**: Clearly shows which intents handle which asset types By using the actual RecipientEntry and TokenRecipientEntry types, we ensure these patterns exactly match the structures used in concrete intents. - `intentType` 'payment', required — Must be "payment". - `sequenceId` string - `comment` string - `nonce` union — Override the on-chain nonce for this transaction. - string - number - `recipients` object[], required - `address` Address, required - … - `amount` Amount, required - … - `data` string - `isTestTransaction` boolean, required — When true, marks this as a test transaction (not broadcast to the network). - `policyUniqueId` string — The unique ID for the policy - `txRequest` union — The transaction request details - TransactionRequestLite - `intent` union - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - object — The intent of the transaction request - … - `unsignedTxs` object[] - `parsedTx` ParsedTx, required - … - `serializedTxHex` string, required — The unsigned transaction as a hex string. - `signableHex` string, required — The portion of a transaction used to generate a signature (may or may not be the same as serializedTxHex) as a hex string. - `derivationPath` string — A bip32 path. - `coinSpecific` object — Coin specific information. - … - `feeInfo` object - … - `signatureShares` object[] - `vssProof` string — The VSS proof of the signature share - `privateShareProof` string — The private share proof - `publicShare` string — The public share - `from` 'user' | 'backup' | 'bitgo', required - `to` 'user' | 'backup' | 'bitgo', required - `share` string, required — The signature share - `commitmentShares` object[] - `type` 'commitment', required — The type of the commitment share - `from` 'user' | 'backup' | 'bitgo', required - `to` 'user' | 'backup' | 'bitgo', required - `share` string, required — The commitment share. - `txHashes` string[] - `apiVersion` 'lite' | 'full' — The API version of the transaction request - `txRequestId` string, uuid, required - `idempotencyKey` string — The idempotency key of the transaction request - `walletId` string, required - `walletType` 'backing' | 'cold' | 'custodial' | 'custodialPaired' | 'hot' | 'advanced' | 'trading' — The type describes who owns the keys to the wallet associated to the TxRequest. - `version` number, required — The version of the transaction request - `enterpriseId` string — If the wallet that owns the TxRequest is owned by an enterprise then this is the Id of said enterprise. - `organizationId` string — The id of the organization the TxRequest's wallet belongs to. - `state` 'pendingApproval' | 'canceled' | 'rejected' | 'initialized' | 'pendingDelivery' | 'delivered' | 'pendingUserSignature' | 'pendingUserCommitment' | 'pendingUserRShare' | 'pendingUserGShare' | 'readyToSend' | 'signed' | 'failed', required - `date` string, date-time, required — The date and time this version of the TxRequest document was created. - `createdDate` string, date-time, required — The date and time the version 1 TxRequest document was created. - `userId` string, required — The Id of the User that produced this version of the TxRequest document. Could have created a new document or updated an existing document. - `initiatedBy` string, required — The Id of the User that originally created the TxRequest document (initiated the TxRequest). - `updatedBy` string, required — The Id of the User that last updated the TxRequest document. This is an alias for the userId field. - `intents` unknown[], required - unknown - `pendingApprovalId` string — The id of the Pending Approval that was created for the TxRequest if one was required. - `policiesChecked` boolean - `latest` boolean, required — Indicates if this is the latest transaction request - `isCanceled` boolean — True, if the transaction request is canceled. - `cancelReason` string — The reason the transaction request was canceled, if applicable. - `initiatedByDAppClient` boolean — True when the txRequest was initiated by a dApp OAuth client (e.g. Narval). - `txChannel` object — Immutable DeFi / marketplace channel classification (DEFI-300). - `clientId` string — OAuth dApp client id (Narval). - `connector` 'narval' | 'walletconnect' — External entry connector (narval, walletconnect). Omitted for internal BitGo flows. - `defiAction` 'approve' | 'deposit' | 'withdraw' - `protocol` 'morpho' | 'aave' | 'concrete' — DeFi protocol (morpho, aave, concrete). - `source` 'internal' | 'external', required - `type` 'defi', required - `vaultId` string - `walletConnectRequestId` string — defi-service walletconnect_requests.id when supplied on the intent. - TransactionRequestFull - `transactions` object[] - `state` 'initialized' | 'pendingSignature' | 'eddsaPendingCommitment' | 'eddsaPendingRShare' | 'eddsaPendingGShare' | 'ecdsaMPCv2Round1' | 'ecdsaMPCv2Round2' | 'ecdsaMPCv2Round3' | 'eddsaMPCv2Round1' | 'eddsaMPCv2Round2' | 'eddsaMPCv2Round3' | 'readyToCombineShares' | 'signed' | 'held' | 'delivered' | 'invalidSignature' | 'rejected', required — If supplied, only transaction request transaction state changes from the provided list will trigger notifications. If not provided, all transaction request transaction state changes will trigger notifications. - `unsignedTx` UnsignedTransaction, required - … - `signatureShares` object[] - … - `commitmentShares` object[] - … - `txHash` string - `updatedDate` string, date-time - `createdDate` string, date-time - `messages` object[] - `state` 'initialized' | 'pendingSignature' | 'eddsaPendingCommitment' | 'eddsaPendingRShare' | 'eddsaPendingGShare' | 'ecdsaMPCv2Round1' | 'ecdsaMPCv2Round2' | 'ecdsaMPCv2Round3' | 'eddsaMPCv2Round1' | 'eddsaMPCv2Round2' | 'eddsaMPCv2Round3' | 'readyToCombineShares' | 'signed' | 'held' | 'delivered' | 'invalidSignature' | 'rejected', required — If supplied, only transaction request transaction state changes from the provided list will trigger notifications. If not provided, all transaction request transaction state changes will trigger notifications. - `messageRaw` string, required — The raw message to be signed - `signatureShares` object[] - … - `privateSignatureShares` object[] - … - `commitmentShares` object[] - … - `encryptedShares` object[] - … - `txHash` string — Transaction hash - `updatedDate` string, date-time — Date when the message was last updated - `createdDate` string, date-time — Date when the message was created - `messageEncoded` string — The encoded message - `messageBroadcastable` string — The broadcastable message - `messageStandardType` string — The encoded message - `derivationPath` string — Derivation path for the message - `combineSigShare` string — Combined signature share - `coin` string — Coin type for the message - `bitgoPaillierChallenge` unknown - `encryptedChallenge` string — BitGo's encrypted challenge for ECDSA with Range Proofs - `apiVersion` 'lite' | 'full' — The API version of the transaction request - `txRequestId` string, uuid, required - `idempotencyKey` string — The idempotency key of the transaction request - `walletId` string, required - `walletType` 'backing' | 'cold' | 'custodial' | 'custodialPaired' | 'hot' | 'advanced' | 'trading' — The type describes who owns the keys to the wallet associated to the TxRequest. - `version` number, required — The version of the transaction request - `enterpriseId` string — If the wallet that owns the TxRequest is owned by an enterprise then this is the Id of said enterprise. - `organizationId` string — The id of the organization the TxRequest's wallet belongs to. - `state` 'pendingApproval' | 'canceled' | 'rejected' | 'initialized' | 'pendingDelivery' | 'delivered' | 'pendingUserSignature' | 'pendingUserCommitment' | 'pendingUserRShare' | 'pendingUserGShare' | 'readyToSend' | 'signed' | 'failed', required - `date` string, date-time, required — The date and time this version of the TxRequest document was created. - `createdDate` string, date-time, required — The date and time the version 1 TxRequest document was created. - `userId` string, required — The Id of the User that produced this version of the TxRequest document. Could have created a new document or updated an existing document. - `initiatedBy` string, required — The Id of the User that originally created the TxRequest document (initiated the TxRequest). - `updatedBy` string, required — The Id of the User that last updated the TxRequest document. This is an alias for the userId field. - `intent` unknown - `intents` unknown[], required - unknown - `pendingApprovalId` string — The id of the Pending Approval that was created for the TxRequest if one was required. - `policiesChecked` boolean - `latest` boolean, required — Indicates if this is the latest transaction request - `isCanceled` boolean — True, if the transaction request is canceled. - `cancelReason` string — The reason the transaction request was canceled, if applicable. - `initiatedByDAppClient` boolean — True when the txRequest was initiated by a dApp OAuth client (e.g. Narval). - `txChannel` object — Immutable DeFi / marketplace channel classification (DEFI-300). - `clientId` string — OAuth dApp client id (Narval). - `connector` 'narval' | 'walletconnect' — External entry connector (narval, walletconnect). Omitted for internal BitGo flows. - `defiAction` 'approve' | 'deposit' | 'withdraw' - `protocol` 'morpho' | 'aave' | 'concrete' — DeFi protocol (morpho, aave, concrete). - `source` 'internal' | 'external', required - `type` 'defi', required - `vaultId` string - `walletConnectRequestId` string — defi-service walletconnect_requests.id when supplied on the intent. - `txRequestId` string, uuid, required - `verificationItems` string[] - `verificationRuleId` string — The ID of the verification rule - `videoApprovers` string[] - `walletRebalanceEventId` string — The ID of the wallet rebalance event - `policyRuleRequest` object - `action` string — The action of the policy rule request - `batch` object — Present when this approval is one batch of a split submission - `groupId` string, required - `index` number, required - `total` number, required - `update` object — The update details of the policy rule request (single-wallet) - `action` PolicyRuleAction - `type` 'deny' | 'getApproval' | 'getEnterpriseUserApproval' | 'getUserRoleApproval' | 'getAnyApproval' | 'getFinalApproval' | 'getVideoApproval' | 'getIdVerification' | 'verifyWalletRebalance' | 'getCustodianApproval' | 'getCustodialSignature' | 'triggerWebhookNotification' | 'performLivenessVerification' | 'recommendBackingWalletRouting' | 'getManualTrustReview' | 'getManualSupportReview' | 'getSupportManagerApproval' | 'getVideoApprovalFromSupport' | 'evaluateFraudRisk', required - `userIds` string[] - `coin` string — A cryptocurrency symbol or token ticker symbol - `condition` union - AddressListRuleUpdateCondition - `add` string - `remove` string - `metaData` object - AdvancedListRuleUpdateCondition - `add` AdvancedListRuleEntry - … - `remove` object - … - `verifyItems` object - … - TxUsdThresholdRuleCondition - `lowerBound` string, required - `upperBound` string - 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 - WebhookRuleCondition - `url` string, required — The url to query for the webhook - `generatePolicy` boolean — Should generate new whitelist policy when generatePolicy is undefined * - `id` string — The ID of the policy rule - `lockDate` string, date - `type` 'advancedWhitelist' | 'coinAddressWhitelist' | 'coinAddressBlacklist' - `walletId` string — Optional walletId field for multi-wallet updates - `updates` object[] - `action` PolicyRuleAction - `type` 'deny' | 'getApproval' | 'getEnterpriseUserApproval' | 'getUserRoleApproval' | 'getAnyApproval' | 'getFinalApproval' | 'getVideoApproval' | 'getIdVerification' | 'verifyWalletRebalance' | 'getCustodianApproval' | 'getCustodialSignature' | 'triggerWebhookNotification' | 'performLivenessVerification' | 'recommendBackingWalletRouting' | 'getManualTrustReview' | 'getManualSupportReview' | 'getSupportManagerApproval' | 'getVideoApprovalFromSupport' | 'evaluateFraudRisk', required - `userIds` string[] - `coin` string — A cryptocurrency symbol or token ticker symbol - `condition` union - AddressListRuleUpdateCondition - `add` string - `remove` string - `metaData` object - AdvancedListRuleUpdateCondition - `add` AdvancedListRuleEntry - … - `remove` object - … - `verifyItems` object - … - TxUsdThresholdRuleCondition - `lowerBound` string, required - `upperBound` string - 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 - WebhookRuleCondition - `url` string, required — The url to query for the webhook - `generatePolicy` boolean — Should generate new whitelist policy when generatePolicy is undefined * - `id` string — The ID of the policy rule - `lockDate` string, date - `type` 'advancedWhitelist' | 'coinAddressWhitelist' | 'coinAddressBlacklist' - `walletId` string — Optional walletId field for multi-wallet updates - `updateApprovalsRequiredRequest` object - `requestedApprovalsRequired` number — The number of requested approvals required - `updateEnterpriseRequest` object - `action` 'add' | 'update' | 'remove' - `email` string — The email of the user - `isVideoIdUser` boolean — Indicates if the user is a video ID user - `permissions` 'admin' | 'auditor' | 'wallet.create' — The permissions associated with the update - `userId` string — The ID of the user - `updateOrganizationRequest` object - `action` 'add' | 'update' | 'remove' - `email` string — The email of the user - `inviterInfo` object — CaaS org add-invite only (`POST /api/v2/organization/{orgId}/user`); UMS org user changes use `genericRequest`. - `email` string, required - `fullName` string, required - `id` string, required - `role` 'serviceUser' | 'admin' | 'member' | 'customer' — The role of the user in the organization - `userId` string — The ID of the user - `genericRequest` object - `anchors` object[] - `anchorType` 'policyRuleId' | 'settlementId' | 'crossChainRecoveryId', required - `key` string, required — The key of the anchor - `value` string, required — The value of the anchor - `changeType` 'create' | 'update' | 'delete' | 'unlock' | 'bulkUnlock' | 'bulkArchive' | 'duplicate' - `currentId` string — The current ID associated with the request - `description` string — The description of the request - `metadata` object — The metadata of the request - `proposedId` string — The proposed ID associated with the request - `resources` object[] - `currentId` string - `metadata` object - `proposedId` string - `resourceType` string — The resource type of the request - `enterpriseInviteRequest` object - `action` 'add' | 'update' | 'remove' - `email` string — The email of the user - `enterpriseInfo` object — Additional info used by the client accepting the invite - `id` string, required - `invitedBy` CaasOrganizationInviteInviterInfo, required — Inviter snapshot on CaaS org add-invite `inviterInfo` and enterprise invite `invitedBy`. Not used for UMS `genericRequest`. - `id` string, required - `email` string, required - `fullName` string, required - `name` string, required - `requiredVerificationStep` string, required - `userKycState` string - `isVideoIdUser` boolean — Indicates if the user is a video ID user - `permissions` 'admin' | 'auditor' | 'wallet.create' — The permissions associated with the invite - `userId` string — The ID of the user - `updateWalletSettingRequest` object - `userKeySigningRequired` object - `newValue` boolean, required - `oldValue` boolean, required - `updateWalletTagsRequest` object - `action` 'add' | 'remove', required - `customTags` string[], required - `state` union, required - 'pending' | 'awaitingSignature' | 'pendingFinalApproval' | 'pendingCustodianApproval' | 'pendingVideoApproval' | 'pendingIdVerification' | 'pendingLivenessVerification' | 'pendingManualTrustReview' | 'pendingManualSupportReview' | 'pendingVideoApprovalFromSupport' | 'pendingFraudRiskEvaluation' - 'approved' | 'processing' | 'rejected' - 'pendingVideoApproval' | 'pendingIdVerification' | 'awaitingSignature' | 'pendingCustodianApproval' | 'pendingManualTrustReview' | 'pendingFraudRiskEvaluation' - 'pendingVideoApproval' | 'pendingIdVerification' | 'awaitingSignature' | 'pendingCustodianApproval' | 'pendingManualTrustReview' | 'pendingFraudRiskEvaluation' - `scope` 'enterprise' | 'wallet' | 'organization' | 'global' | 'safe', required — What kind of entity the Pending Approval is tied to - `userIds` string[] - `approvalsRequired` number - `walletLabel` string — Label for the wallet - `addressLabels` object[] - `address` string, required - `label` string, required — The label - `walletLabel` string — The wallet label - `resolvers` object[] - `autoApproved` boolean — Whether the resolution was auto approved - `date` string, date-time — The date of resolution - `resolutionAction` 'approve' | 'reject' | 'skip' | 'fail' — Action taken during resolution - `resolutionMemo` string — Memo regarding the resolution - `resolutionType` 'pending' | 'awaitingSignature' | 'pendingFinalApproval' | 'pendingCustodianApproval' | 'pendingVideoApproval' | 'pendingIdVerification' | 'pendingLivenessVerification' | 'pendingManualTrustReview' | 'pendingManualSupportReview' | 'pendingVideoApprovalFromSupport' | 'pendingFraudRiskEvaluation', required - `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` string[] - `singleRunResults` object[] - `ruleId` string — The rule ID - `triggered` boolean — Whether the rule was triggered - `txRequestId` string, uuid — Transaction request ID - `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` object[] - `approvers` string[] - `excludedApprovers` string[] - `id` string, required — The ID of the action - `name` string, required — The name of the action - `operator` 'AND' | 'OR' — The operator of the action - `parameters` PolicyActionParameters, required - `minRequired` union - string - number - `userIds` string[] - `initiatorIsAllowedToApprove` boolean - `webhookURL` string - `livenessCheckUser` 'transactionInitiator' | 'walletAdmins' | 'videoIdUsers' | 'enterpriseAdmin' - `isFallback` boolean - `walletSubtype` 'custodialCold' | 'custodialHot' | 'lightningCustody' - `userRoleIds` string[] - `resolvers` object[] - `autoApproved` boolean — Whether the resolution was auto approved - `date` string, date-time — The date of resolution - `resolutionAction` 'approve' | 'reject' | 'skip' | 'fail' — Action taken during resolution - `resolutionMemo` string — Memo regarding the resolution - `resolutionType` 'pending' | 'awaitingSignature' | 'pendingFinalApproval' | 'pendingCustodianApproval' | 'pendingVideoApproval' | 'pendingIdVerification' | 'pendingLivenessVerification' | 'pendingManualTrustReview' | 'pendingManualSupportReview' | 'pendingVideoApprovalFromSupport' | 'pendingFraudRiskEvaluation', required - `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 - `status` 'SKIPPED' | 'PENDING' | 'NOT_NEEDED' | 'COMPLETE' | 'CANCELLED' | 'FAILED' | 'AUTO_CANCELLED', required - `resolutionOrder` object[] - `actions` 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` object[] - `reason` string - `state` 'frozen' | 'unFrozen' - `time` string, date-time - `userId` string - `username` string - `state` 'frozen' | 'unFrozen' - `memo` object[] - `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` object[] - `inquiryId` string, required - `inquiryStatus` 'completed' | 'failed', required - `inquirySubType` 'withdrawalLivenessCheck' | 'managePolicyLivenessCheck' | 'govIdSelfie', required - `inquiryType` 'livenessCheck', required - `securityControlEvents` object[] - `control` string — The security control that was evaluated - `date` string, date-time, required — The date the event was recorded - `ip` string — The IP address of the user - `message` string — Message from the security control - `result` 'allowed' | 'blocked', required — Whether the user was allowed or blocked - `user` string, required — The user who triggered the security control check ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found --- [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)