Guides
Start typing to search…

Consolidate Account Balance

Overview

For account-based assets, the spendable balance of a wallet is the balance of the assets in the root address. In order to enable the maximum withdrawal from a wallet with multiple receive addresses, you must consolidate the balance by sweeping assets to the root address. The confirmed balance of a wallet is the balance of the root address plus all the receive addresses.

Some blockchains require a minimum balance in a receive address. When you consolidate a wallet, the minimum balance remains in the receive addresses. This results in your spendable balance being slightly less than your confirmed balance.

Consolidation refers to flushing assets from receive addresses to the root address of a given wallet. A single consolidation request can consolidate a fixed number of addresses, which is a maximum limit set per coin. For instance, most coins allow up to 750 addresses per request, whereas Solana has a limit of 25 addresses. Each address that's being consolidated as part of a single consolidation request will have a unique transaction. As an example: If 10 addresses are being consolidated, 10 transactions would be created as part of a single consolidation request. For more comprehensive information, please refer to the coin-specific documentation.

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:

Prerequisites

1. (Optional) Check Consolidation Requirements

Determine if your wallet requires consolidations.

Endpoint: Get Wallet by ID

export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X GET \
  https://app.bitgo-test.com/api/v2/wallet/$WALLET_ID \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \

Step Result

The response shows either "needsConsolidation": true or "needsConsolidation": false.

{
  "allowBackupKeySigning": true,
  "approvalsRequired": 1,
  "coin": "tbtc4",
  ...
  ...
  ...
    "needsConsolidation": true,
    "tokenConsolidationState": null,
    "tokenAddress": null
  }

2. Build, Sign, and Send Consolidation

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

Endpoint: Consolidate Account (Simple)

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>"

curl -X POST \
  http://$BITGO_EXPRESS_HOST/api/v2/$COIN/wallet/$WALLET_ID/consolidateAccount \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "walletPassphrase": "'"$WALLET_PASSPHRASE"'"
}'
const BitGoJS = require('bitgo');
const Promise = require('bluebird');

const bitgo = new BitGoJS.BitGo({ env: 'test' });

const coin = 'talgo';

// Set your wallet id
const walletId = '';

// Set your wallet passphrase
const walletPassphrase = '';

// Set OTP code
const otp = '000000';

// Set your access token here
  bitgo.authenticateWithAccessToken({ accessToken });

  const wallet = await bitgo.coin(coin).wallets().get({ id: walletId });
  // Wallet's base address - only address in the wallet that can send assets to other accounts
  console.log('Base Address:', wallet.coinSpecific().baseAddress);
  // Confirmed balance - sum of the balance of all the wallet's addresses
  console.log('Confirmed Balance:', wallet.confirmedBalanceString());
  // Spendable balance - balance of the base address
  console.log('Spendable Balance:', wallet.spendableBalanceString());

  // unlock the session for sending assets
  const unlock = await bitgo.unlock({ otp, duration: 3600 });
  if (!unlock) {
    throw new Error('error unlocking session');
  }

  const consolidationTxes = await wallet.buildAccountConsolidations();

  try {
    for (const unsignedConsolidation of consolidationTxes) {
      const res = await wallet.sendAccountConsolidation({ walletPassphrase, prebuildTx: unsignedConsolidation });
      console.dir(res, { depth: 6 });
    }
  } catch (e) {
    console.error(e);
  }
);

Step Result

You receive a calendar invitation by email to schedule video verification with a BitGo operator.

Next

  1. If the transaction requires admin approval, it remains in a pending approval status until receiving final approval.
  2. Open the email from BitGo and select a date and time for video verification with a BitGo operator.

After verification, BitGo signs and broadcasts the transaction to the network for confirmation.

See Also

Updated 22 days ago