Bitcoin API Balances

On this page we present the detailed information provided by the API and the User Interface for Bitcoin's account balance, as well as illustrating how status changes impact each balance, for inbound and outbound transactions.

Definition

  1. available : Equal to total - pending - worthless
  2. confirmed : Sum of confirmed UTXOs (more than 6 confirmations) not being involved in outbound pending transactions, in mempool, or under confirmation.
  3. mempool_change : Amount currently in the account's change outputs for transactions that are still in mempool. Change addresses are derived with dedicated derivation path, please avoid sending your change address as receive address and use the "receive" button instead, otherwise change balance will be overestimated.
  4. mempool_in : Inbounding amount, for inbound transactions that are still in mempool (0 confirmations).
  5. mempool_out : Outbounding amount, for outbound transactions that are still in mempool (0 confirmations).
  6. pending : Equal to the sum of all outbound pending transactions' amounts, change excluded and pending max fees included. An outbound transaction is considered pending as long as its status is between pending approval (included) and submitted (excluded).
  7. total : Equal to confirmed + mempool in + under confirmation in - mempool out - under confirmation out
  8. under_confirmation_change : Amount currently in the account's change outputs for transactions that are under confirmation (between 1 and 6 confirmation). Change addresses are derived with dedicated derivation path, please avoid sending your change address as receive address and use the "receive" button instead, otherwise change balance will be overestimated.
  9. under_confirmation_in : Inbounding amount, for inbound transactions that are under confirmation (1 to 6 confirmations).
  10. under_confirmation_out : Outbounding amount, for outbound transactions that are under confirmation (1 to 6 confirmations).
  11. worthless : sum of all UTXOs for which spending is more expensive in fees than their actual amount, due to their incompressibility in vBytes.

User Interface balances computed from API balances:

  1. Available balance = available
  2. Strictly available balance = confirmed - pending - worthless + mempool_change + under_confirmation_change
  3. Worthless and dust = worthless
  4. Pending balance = pending
  5. Total balance = total
  6. Incoming 0 = mempool_in
  7. Incoming 1 - 6 = under_confirmation_in
  8. Incoming 6+ = confirmed
  9. Outbounding 0 = mempool_out

Impact of outbound transactions statuses on balances:

  1. Pending approval : Increase pending by the outbound amount plus max_fees excluding change.
  2. Approved , Signed : No impact on balances.
  3. Submitted (0/6) : Decrease pending by the outbound amount plus max_fees excluding change, increase mempool_change by the change amount and mempool_out by outbound amount, decrease confirmed by change plus outbound amount plus final fees.
  4. Submitted (1+/6) : Decrease mempool_change by the change amount, decrease mempool_out by outbound amount, increase under_confirmation_change by the change amount and increase under_confirmation_out by outbound amount.
  5. Confirmed : Decrease under_confirmation_change by the change amount and decrease under_confirmation_out by outbound amount, increase confirmed by the change amount.
  6. Dropped : Increase confirmed by change plus outbound amount plus fees. Also decrease mempool_out and mempool_change or on under_confirmation_out and under_confirmation_change depending if the tx was dropped respectively while on mempool, or after an onchain reorganization.
  7. Failed_to_broadcast : Decrease pending by the outbound amount plus max_fees .

Impact of inbound transactions statuses on balances:

  1. Submitted (0/6) : Increase mempool_in by the incoming amount.
  2. Submitted (1+/6) : Decrease mempool_in by the incoming amount, Increase under_confirmation_in by the incoming amount.
  3. Dropped : Decrease mempool_in or under_confirmation_in by the incoming amount, depending if the tx was dropped respectively while on mempool, or after an onchain reorganization.
  4. Confirmed : Decrease under_confirmation_in by the incoming amount, Increase confirmed by the incoming amount.
Copyright © Ledger Enterprise Platform 2023. All right reserved.