Guides
  1. Task Guides
  2. Wallets

Consolidate Account Balance

Overview

A consolidation is a transaction that transfers assets from receive addresses to the base address of a wallet.

For account-based assets, the spendable balance of a wallet is the balance of the assets in the base address. The spendable balance is the total amount available for withdrawal. The confirmed balance is the balance of the base address plus all the receive addresses. If a wallet has multiple receive addresses, you can obtain the maximum withdrawal amount by consolidating the balances from the receive addresses to the base address.

Manual consolidations are required for account based assets that aren't on Ethereum Virtual Machine (EVM) blockchains. For EVM wallets, BitGo can enable automatic consolidations. To learn about automatic consolidations for EVM wallets, see Consolidations.

How it Works

Consolidations are a type of transaction request. A single consolidation request can consolidate multiple receive addresses. Most networks can consolidate up to 750 addresses per consolidation request.

Each receive address that's consolidated in a consolidation request creates a unique transaction. For example, if you consolidate a wallet with 10 receive addresses in a single consolidation request, BitGo creates 10 on-chain transactions.

Consolidations are also single asset transactions. If a wallet has a variety of assets in the receive addresses, you must consolidate each asset in a separate consolidation request.

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.

Note: Solana stands out from other blockchains in how it handles consolidations. For Solana wallets, consolidations are limited to just 25 receive addresses per consolidation. However, Solana wallets are capable of consolidating up to eight different assets from a receive address in a consolidation request, significantly reducing transaction costs.

The fee for a consolidation transaction is paid by either the gas tank or the receive address. You can view the fee source for each asset in Consolidations. You can learn more about asset-specific requirements for consolidations in the Blockchain References.

Simple or Manual

Similar to withdrawing, consolidating has two 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 manual 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

If the transaction requires admin approval, it remains in a pending approval status until receiving final approval. If approval isn't required, you receive a calendar invitation by email to schedule video ID verification with a BitGo operator.

Next

You can confirm the increased spendable balance for the wallet in BitGo or using the Get Wallet by Coin and ID endpoint. You can also view the consolidation transaction on a blockchain explorer.

See Also

Updated 4 months ago

Did this page help you?