Transaction Confirmations

Bitcoin offers probabilistic, not instant, finality: a spend becomes harder to reverse with every block mined on top of it, because rewriting history would mean out-mining the network's proof-of-work from that point forward. The number of blocks stacked above a transaction — its confirmation count — is therefore the practical measure of how settled a payment is. Zero confirmations means the transaction is only in the mempool and could still be replaced or dropped; six confirmations means roughly an hour of accumulated work that no realistic attacker can undo. This guide gives developers a safe confirmation-counting flow against https://bitcoin.therpc.io/YOUR_API_KEY: how to read a transaction's confirmation count, how many to require for a given value, and how to notice when a chain reorganization pulls a confirmed transaction back into limbo.

Understanding Confirmations

• A confirmation is a block. A transaction has N confirmations when it sits in a block with N−1 blocks mined on top of it — so the block that first includes the transaction gives it one confirmation, the next block makes it two, and so on.
• The confirmations field is derived from the tip. On a verbose getrawtransaction the node computes confirmations as the current chain height minus the height of the containing block, plus one. A transaction still in the mempool has no containing block, so the field is absent (treat it as zero), which is why the example code uses tx.confirmations || 0.
• Confirmations accrue slowly. Bitcoin's difficulty adjustment targets a new block roughly every ten minutes, so six confirmations take about an hour on average — and intervals vary, sometimes much longer between blocks. Build flows that wait and poll rather than block on a fast response.
• Thresholds scale with value. A common pattern is 1 confirmation for small, low-risk payments, and 3 to 6 for higher-value settlements. More value means a bigger incentive for an attacker to attempt a reorg, so requiring more blocks raises the cost of reversing the payment beyond what the amount is worth.

Counting Confirmations

1// Read confirmations for a transaction
2const getConfirmations = async (txid) => {
3  const tx = await rpc('getrawtransaction', [txid, true]);
4  return tx.confirmations || 0;
5};
6 
7// Wait for a target number of confirmations
8const waitForConfirmations = async (txid, target = 6) => {
9  while ((await getConfirmations(txid)) < target) {
10    // Bitcoin blocks are ~10 minutes apart; poll on a coarse interval
11    await new Promise((resolve) => setTimeout(resolve, 30000));
12  }
13  return true;
14};

Security Considerations

• Choose thresholds by value at risk. Tie the required confirmations to the amount: accept tiny payments at 1 confirmation, hold mid-value deposits to 3, and wait for 6 on large settlements. The goal is to make the cost of reversing the transaction exceed the value an attacker could steal.
• Understand reorganizations. A chain reorg happens when a competing branch of greater cumulative proof-of-work overtakes the branch your transaction was in. The block holding your transaction is then orphaned, and the transaction drops back to the mempool — its confirmation count returns to zero until it is mined again on the new branch.
• Detect reorgs actively. Poll getbestblockhash to watch the tip, and use getchaintips to spot competing branches with valid-fork or valid-headers status. After a tip change, re-check that your transaction's blockhash still belongs to the active chain; if it no longer does, the transaction was reorged out and must re-confirm.
• Mempool is never final. A zero-confirmation transaction can be replaced or simply never mined, and this is true regardless of RBF flags — even a non-replaceable transaction can be dropped by a reorg or evicted from the mempool. Wait for your confirmation threshold before crediting any payment as settled.

See also

• getrawtransaction - Read a transaction's confirmation count
• getblockcount - Track the chain tip height
• getchaintips - Detect competing branches and reorgs