Skip to content

Commit 7724041

Browse files
lokesh-bitgolokesh-bitgo
authored
docs(express): fanoutUnspentsV2 api definition
2 parents 4a0389e + 550612d commit 7724041

File tree

3 files changed

+34
-33
lines changed

3 files changed

+34
-33
lines changed

‎modules/express/src/clientRoutes.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -832,7 +832,7 @@ export async function handleV2ConsolidateAccount(
832832
* handle wallet fanout unspents
833833
* @param req
834834
*/
835-
async function handleV2FanOutUnspents(req: ExpressApiRouteRequest<'express.v2.wallet.fanoutunspents', 'post'>) {
835+
async function handleV2FanOutUnspents(req: ExpressApiRouteRequest<'express.wallet.fanoutunspents', 'post'>) {
836836
const bitgo = req.bitgo;
837837
const coin = bitgo.coin(req.decoded.coin);
838838
const wallet = await coin.wallets().get({ id: req.decoded.id });
@@ -1677,7 +1677,7 @@ export function setupAPIRoutes(app: express.Application, config: Config): void {
16771677
prepareBitGo(config),
16781678
typedPromiseWrapper(handleV2ConsolidateUnspents),
16791679
]);
1680-
router.post('express.v2.wallet.fanoutunspents', [prepareBitGo(config), typedPromiseWrapper(handleV2FanOutUnspents)]);
1680+
router.post('express.wallet.fanoutunspents', [prepareBitGo(config), typedPromiseWrapper(handleV2FanOutUnspents)]);
16811681

16821682
router.post('express.v2.wallet.sweep', [prepareBitGo(config), typedPromiseWrapper(handleV2Sweep)]);
16831683

‎modules/express/src/typedRoutes/api/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@ export const ExpressWalletFanoutUnspentsApiSpec = apiSpec({
172172
'express.v1.wallet.fanoutunspents': {
173173
put: PutFanoutUnspents,
174174
},
175-
'express.v2.wallet.fanoutunspents': {
175+
'express.wallet.fanoutunspents': {
176176
post: PostFanoutUnspents,
177177
},
178178
});

‎modules/express/src/typedRoutes/api/v2/fanoutUnspents.ts‎

Lines changed: 31 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -20,41 +20,51 @@ export const FanoutUnspentsRequestParams = {
2020
* creates a larger number of equally-sized outputs for improved transaction parallelization.
2121
*/
2222
export const FanoutUnspentsRequestBody = {
23-
/** The wallet passphrase to decrypt the user key */
23+
/** Passphrase to decrypt the user key on the wallet */
2424
walletPassphrase: optional(t.string),
25-
/** The extended private key (alternative to walletPassphrase) */
25+
/** Private key in string form, if walletPassphrase is not available */
2626
xprv: optional(t.string),
27-
/** The number of new unspents to create */
27+
/** Number of new unspents to make */
2828
numUnspentsToMake: optional(t.number),
29-
/** Minimum value of unspents to use (in base units) */
29+
/** Minimum value of unspents to use in base units (e.g. satoshis). For doge, only string is allowed. */
3030
minValue: optional(t.union([t.number, t.string])),
31-
/** Maximum value of unspents to use (in base units) */
31+
/** Maximum value of unspents to use in base units (e.g. satoshis). For doge, only string is allowed. */
3232
maxValue: optional(t.union([t.number, t.string])),
33-
/** Minimum block height of unspents to use */
33+
/** Minimum height of unspents on the block chain to use*/
3434
minHeight: optional(t.number),
35-
/** Minimum number of confirmations needed for an unspent to be included (defaults to 1) */
35+
/** Minimum confirmation threshold for external inputs */
3636
minConfirms: optional(t.number),
37-
/** If true, minConfirms also applies to change outputs */
37+
/** Flag for enforcing minConfirms for change inputs */
3838
enforceMinConfirmsForChange: optional(t.boolean),
39-
/** Maximum number of inputs to use in the transaction */
39+
/** Maximum number of unspents to use in the transaction. Mutually exclusive with unspents. */
4040
maxNumInputsToUse: optional(t.number),
41-
/** Array of specific unspent IDs to use */
41+
/** Unspents to fan out in the transaction. Mutually exclusive with maxNumInputsToUse. */
4242
unspents: optional(t.array(t.string)),
43-
/** The desired fee rate for the transaction in satoshis/kB */
43+
/**
44+
* Custom fee rate (in base units) per kilobyte (or virtual kilobyte). For example, satoshis per kvByte
45+
*
46+
* 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.
47+
*
48+
* Note: The feeRate overrides the maxFeeRate and minFeeRate.
49+
*/
4450
feeRate: optional(t.number),
45-
/** The maximum limit for a fee rate in satoshis/kB */
51+
/**
52+
* (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.
53+
*
54+
* Note: The feeRate overrides the maxFeeRate.
55+
*/
4656
maxFeeRate: optional(t.number),
47-
/** The maximum proportion of value you're willing to lose to fees (as a decimal, e.g., 0.1 for 10%) */
57+
/** Maximum relative portion that can be spent towards fees */
4858
maxFeePercentage: optional(t.number),
49-
/** Estimate fees to aim for first confirmation within this number of blocks */
59+
/** Block target for fee estimation */
5060
feeTxConfirmTarget: optional(t.number),
5161
/** Comment to attach to the transaction */
5262
comment: optional(t.string),
5363
/** One-time password for 2FA */
5464
otp: optional(t.string),
55-
/** Target address for the fanout outputs */
65+
/** Address to use for generated outputs. Must be wallet address. */
5666
targetAddress: optional(t.string),
57-
/** Transaction format type (e.g., 'legacy', 'psbt', 'psbt-lite') - controls output format */
67+
/** [UTXO only] Format of the returned transaction hex serialization. legacy for serialized transaction in custom bitcoinjs-lib format. psbt for BIP174 serialized transaction */
5868
txFormat: optional(t.union([t.literal('legacy'), t.literal('psbt'), t.literal('psbt-lite')])),
5969
/** If true, enables fanout of large number of unspents by creating multiple transactions (200 unspents per tx) */
6070
bulk: optional(t.boolean),
@@ -100,22 +110,13 @@ export const FanoutUnspentsResponse = t.union([
100110
]);
101111

102112
/**
103-
* Fan out unspents in a wallet (v2)
113+
* Fan out unspents on a wallet
104114
*
105-
* This endpoint fans out unspents in a wallet by creating a transaction that spends from
106-
* one or more inputs to create multiple equal-sized outputs. This is useful for increasing
107-
* the number of UTXOs in a wallet, which can improve transaction parallelization and allow
108-
* for concurrent spending operations.
115+
* Creates transactions that distribute existing unspents into more outputs, enabling parallel
116+
* transaction creation. Supports bulk mode to handle large fanouts across multiple transactions.
109117
*
110-
* The v2 API differs from v1 by:
111-
* - Requiring a coin parameter in the path
112-
* - Supporting the full set of SDK parameters for advanced UTXO management
113-
* - Using numUnspentsToMake instead of target (though both refer to output count)
114-
* - Supporting bulk fanout mode that creates multiple transactions
115-
* - Supporting additional parameters like maxNumInputsToUse, unspents array, bulk, fee controls
116-
*
117-
* @operationId express.v2.wallet.fanoutunspents
118-
* @tag express
118+
* @operationId express.wallet.fanoutunspents
119+
* @tag Express
119120
*/
120121
export const PostFanoutUnspents = httpRoute({
121122
path: '/api/v2/{coin}/wallet/{id}/fanoutunspents',

0 commit comments

Comments
 (0)