docs(express): consolidateUnspents V2

modules/express/src/typedRoutes/api/v2/consolidateunspents.ts

@@ -6,9 +6,9 @@ import { BitgoExpressError } from '../../schemas/error';
  * Request parameters for consolidating unspents in a wallet (v2)
  */
 export const ConsolidateUnspentsRequestParams = {
-  /** The coin identifier (e.g., 'btc', 'tbtc') */
+  /** A cryptocurrency or token ticker symbol */
   coin: t.string,
-  /** The ID of the wallet */
+  /** The wallet ID */
   id: t.string,
 } as const;
 
@@ -20,41 +20,41 @@ export const ConsolidateUnspentsRequestParams = {
  * combines them into fewer outputs to reduce the number of UTXOs in a wallet.
  */
 export const ConsolidateUnspentsRequestBody = {
-  /** The wallet passphrase to decrypt the user key */
+  /** Passphrase to decrypt the user key on the wallet */
   walletPassphrase: optional(t.string),
-  /** The extended private key (alternative to walletPassphrase) */
+  /** Private key in string form, if walletPassphrase is not available */
   xprv: optional(t.string),
-  /** Minimum value of unspents to use (in base units) */
+  /** Minimum value of unspents to use in base units (e.g. satoshis). Can be used to skip very small unspents when consolidating at higher fee rates. For doge, only string is allowed */
   minValue: optional(t.union([t.number, t.string])),
-  /** Maximum value of unspents to use (in base units) */
+  /** Maximum value of unspents to use in base units (e.g. satoshis). Should be used to prevent larger unspents from being consolidated needlessly, and that some funds remain available for spending while the consolidation transactions are in flight. For doge, only string is allowed */
   maxValue: optional(t.union([t.number, t.string])),
-  /** Minimum block height of unspents to use */
+  /** Minimum height of unspents on the block chain to use */
   minHeight: optional(t.number),
-  /** The number of new unspents to make (not applicable for bulk consolidation) */
+  /** Number of new unspents to make (not applicable for bulk consolidation) */
   numUnspentsToMake: optional(t.number),
-  /** Estimate fees to aim for first confirmation within this number of blocks */
+  /** Block target for fee estimation */
   feeTxConfirmTarget: optional(t.number),
   /** Maximum number of unspents to use in the transaction */
   limit: optional(t.number),
-  /** Minimum number of confirmations needed for an unspent to be included (defaults to 1) */
+  /** Minimum confirmation threshold for external inputs */
   minConfirms: optional(t.number),
-  /** If true, minConfirms also applies to change outputs */
+  /** Flag for enforcing minConfirms for change inputs */
   enforceMinConfirmsForChange: optional(t.boolean),
-  /** The desired fee rate for the transaction in satoshis/kB */
+  /** Custom fee rate (in base units) per kilobyte (or virtual kilobyte). For example, satoshis per kvByte */
   feeRate: optional(t.number),
-  /** The maximum limit for a fee rate in satoshis/kB */
+  /** (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` */
   maxFeeRate: optional(t.number),
-  /** The maximum proportion of value you're willing to lose to fees (as a decimal, e.g., 0.1 for 10%) */
+  /** Maximum relative portion that can be spent towards fees */
   maxFeePercentage: optional(t.number),
   /** Comment to attach to the transaction */
   comment: optional(t.string),
   /** One-time password for 2FA */
   otp: optional(t.string),
-  /** Target address for the consolidation outputs */
+  /** address to use for generated outputs. Must be wallet address */
   targetAddress: optional(t.string),
-  /** Transaction format type (e.g., 'legacy', 'psbt', 'psbt-lite') - controls output format */
+  /** [UTXO only] Format of the returned transaction hex serialization. `legacy` for serialized transaction in custom bitcoinjs-lib format. `psbt` for BIP174 serialized transaction */
   txFormat: optional(t.union([t.literal('legacy'), t.literal('psbt'), t.literal('psbt-lite')])),
-  /** If true, enables consolidation of large number of unspents by creating multiple transactions (200 unspents per tx) */
+  /** Build multiple transactions at the same time. This enables you to increase the maximum number of unspents on the `limit` parameter up to 2,000. If true, you must pass the `txFormat` as `psbt` and you can't pass the `targetAddress` or `numUnspentsToMake` parameters */
   bulk: optional(t.boolean),
 } as const;
 
@@ -98,21 +98,10 @@ export const ConsolidateUnspentsResponse = t.union([
 ]);
 
 /**
- * Consolidate unspents in a wallet (v2)
- *
- * This endpoint consolidates unspents in a wallet by creating a transaction that spends from
- * multiple inputs to create fewer outputs. This is useful for reducing the number of UTXOs in a wallet,
- * which can improve performance and reduce transaction fees for future transactions.
- *
- * The v2 API differs from v1 by:
- * - Requiring a coin parameter in the path
- * - Supporting the full set of SDK parameters for advanced UTXO management
- * - Using standard parameters like minValue/maxValue instead of minSize/maxSize
- * - Supporting bulk consolidation mode that creates multiple transactions
- * - Supporting additional parameters like limit, targetAddress, fee controls
+ * Builds, signs, and sends a transaction to consolidate unspents all in 1 call. Consolidating unspents is only for UTXO-based assets.
  *
  * @operationId express.v2.wallet.consolidateunspents
- * @tag express
+ * @tag Express
  */
 export const PostConsolidateUnspents = httpRoute({
   path: '/api/v2/{coin}/wallet/{id}/consolidateunspents',