Ctrl+K

Internal consolidation build

post/api/v2/internal/{coin}/wallet/{walletId}/consolidateAccount/build

Builds consolidation transactions for a wallet and returns a structured per-address response. Unlike the client-facing endpoint, this always returns HTTP 200 with both successful transactions and per-address failure details. Internal callers (e.g. Go Accounts) should check summary.failedAddresses > 0 to detect failures and use errors for per-address details and alerting.

Path Parameters

  • coinstringRequired
    The coin type
    Example: btc
  • walletIdstringRequired
    The BitGo wallet ID
    Example: 59cd72485007a239fb00282ed480da1f
    Pattern: ^[0-9a-f]{32}$

Request Body

consolidateAddresses array[string]
Restrict consolidation to these specific addresses
preview boolean
Return a preview without building or storing transactions
nftCollectionId string
NFT collection ID (NFT consolidation only)
nftId string
NFT token ID (NFT consolidation only)
minValueOne of
Minimum unspent value to include (UTXO coins)
maxValueOne of
Maximum unspent value to include (UTXO coins)
numUnspentsToMake number
Number of target UTXOs to create (UTXO coins)
maxFeePercentage number
Maximum allowed fee as a percentage of the output value
feeRate number
Fee rate in satoshis per kilobyte
maxFeeRate number
Maximum acceptable fee rate
minConfirms number
Minimum confirmations required for inputs
feeTxConfirmTarget number
Block target for fee estimation
targetAddress string
Target address for the consolidation output
type string
Transaction type hint; use 'consolidate' for custodial wallets

200 Response

transactions array[object] required
Transactions that were successfully built
txRequestId string required
txHex string required
consolidateId string
errors dictionary<string, object> required
Per-address build failures keyed by address string (or a stable fallback key)
object
summary object required
totalAddresses number required
numSuccessfulAddresses number required
numFailedAddresses number required
numInflightAddresses number required
Addresses filtered before build by filterInFlightAddresses; 0 when in-flight tracking disabled
failureReasons dictionary<string, number> required
Count of failures by error type, e.g. { InsufficientBalance: 2 }

400 Response

One of
name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id

409 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id

500 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id