Consolidate Unspents

Overview

You can consolidate unspents by taking multiple, smaller unspents and combining them into a single, larger unspent. This is useful for reducing the number of individual unspents that you need to manage. Additionally, some assets limit to the total number of unspents in a single transaction. Consolidating unspents can also reduce transaction fees, since the transaction size of single larger unspent is less than that of many smaller unspents. The opposite of consolidating unspents is to Fan Out Unspents.

Consolidation transactions follow the normal transaction flow, requiring signatures, approvals, and sending, as outlined in Wallets Overview.

All consolidation transactions for bitcoin automatically opt-in to acceleration using Replace-By-Fee (RBF). Should the transaction become stuck, you can follow up with an RBF transaction that includes a higher fee.

Note: Consolidating unspents is only available for self-custody wallets. To consolidate unspents for custody wallets, you can withdraw the maximum spendable balance to another one of your addresses, or you can use the web app to select up to 200 unspents to withdraw in one transaction.

Simple or Advanced

Similar to withdrawing, consolidating has 2 different flows that you can use depending on your use case. The simple flow uses either Express or the the JavaScript SDK. In the simple flow, you build, sign, and send the the consolidation transaction all in 1 step. The advanced flow uses either REST endpoints or the JavaScript SDK to build the consolidation transaction, and then sign and send it in separate calls.

This page documents both flows. Select the button bellow for the flow that works best for you:

Copy code block
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
export BITGO_EXPRESS_HOST="<YOUR_LOCAL_HOST>"
export COIN="<ASSET_ID>"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export WALLET_PASSPHRASE="<WALLET_PASSPHRASE>"
export XPRV="<YOUR_PRIVATE_KEY>"
export TARGET_ADDRESS="<DESIRED_TARGET_ADDRESS>"

curl -X POST \
  http://$BITGO_EXPRESS_HOST:3080/api/v2/$COIN/wallet/$WALLET_ID/consolidateunspents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "walletPassphrase": "'"$WALLET_PASSPHRASE"'",
    "xprv": "'"$XPRV"'",
    "feeRate": null,
    "maxFeeRate": null,
    "maxFeePercentage": 0,
    "feeTxConfirmTarget": 0,
    "bulk": true,
    "minValue": "2000000",
    "maxValue": "2000000",
    "minHeight": 0,
    "minConfirms": 0,
    "enforceMinConfirmsForChange": true,
    "limit": 0,
    "numUnspentsToMake": 0,
    "targetAddress": "'"$TARGET_ADDRESS"'",
    "txFormat": "legacy"
}'

Next

See Also

API Reference: Consolidate Unspents