Ctrl+K

Consolidate Unspents

Overview

You can consolidate unspents by taking multiple, smaller UTXO and combining them into a single, larger UTXO. This is useful for reducing the number of individual UTXO that you need to manage. Additionally, some assets limit to the total number of UTXO in a single transaction. Consolidating unspents can also reduce transaction fees, since the transaction size of single larger UTXO is less than that of many smaller UTXO. 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.

Consolidation transactions for bitcoin automatically opt-in to acceleration using Replace-By-Fee (RBF). If the transaction gets stuck, you can follow up with an RBF transaction that includes a higher fee. To learn more, see Accelerate Bitcoin Transaction.

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 below for the flow that works best for you:

  • Simple
  • Advanced

Prerequisites

Build, Sign, and Send Consolidation

Modify the following code to build, sing, and send a consolidation transaction, all in 1 step.

Endpoint: Consolidate Unspents (Simple)

  • cURL
  • JavaScript
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"
}'

Step Result

The UTXOs consolidate to the target address you specified.

  • JSON
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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
  "transfer": {
    "coin": "btc",
    "id": "59cd72485007a239fb00282ed480da1f",
    "wallet": "59cd72485007a239fb00282ed480da1f",
    "enterprise": "59cd72485007a239fb00282ed480da1f",
    "txid": "b8a828b98dbf32d9fd1875cbace9640ceb8c82626716b4a64203fdc79bb46d26",
    "txidType": "transactionHash",
    "height": 0,
    "heightId": "string",
    "date": "2019-08-24T14:15:22Z",
    "confirmations": 0,
    "type": "send",
    "value": 0,
    "valueString": "2000000",
    "intendedValueString": "2000000",
    "baseValue": 0,
    "baseValueString": "2000000",
    "baseValueWithoutFees": 0,
    "baseValueWithoutFeesString": "2000000",
    "feeString": "string",
    "payGoFee": 0,
    "payGoFeeString": "string",
    "usd": 0,
    "usdRate": 0,
    "state": "confirmed",
    "tags": [
      "59cd72485007a239fb00282ed480da1f"
    ],
    "history": [
      {
        "date": "2019-08-24T14:15:22Z",
        "user": "59cd72485007a239fb00282ed480da1f",
        "action": "created",
        "comment": "string"
      }
    ],
    "comment": "string",
    "vSize": 0,
    "coinSpecific": {},
    "sequenceId": "string",
    "entries": [
      {
        "address": "2NAUwNgXaoFj2VVnSEvNLGuez8CfdU2UCMZ",
        "wallet": "string",
        "value": 0,
        "valueString": "string",
        "isChange": true,
        "isPayGo": true,
        "token": "omg",
        "label": "string",
        "failed": true
      }
    ],
    "usersNotified": true,
    "label": "string",
    "replaces": [
      "string"
    ],
    "replacedBy": [
      "string"
    ]
  },
  "txid": "string",
  "tx": "string",
  "status": "signed"
}

Next

You can view the consolidation transaction on a blockchain explorer.

See Also

API Reference: Consolidate Unspents