Bitcoin Core listaddressgroupings RPC: Privacy Guide

This guide explains Bitcoin Core listaddressgroupings RPC in plain English. It shows what the command does, what its result means and what it cannot prove.

Common-input heuristic

Spending multiple inputs together publicly links their controlling signatures in one transaction and commonly suggests joint ownership. Collaborative transactions and shared custody can violate the assumption, so present grouping as evidence to review, not certain identity.

Change inference

Wallet-created change can link a new internal destination back to input clusters. Exact inference depends on wallet construction and history. Coin control and transaction design can limit future linkage but cannot erase links already published on-chain.

Nested result shape

The RPC returns groups containing address entries with BTC amount and optional deprecated account. Parse variable nesting and missing third fields defensively. Convert amounts to satoshis and never use account as a custody boundary.

Current amounts versus history

The amount beside an address is a wallet balance observation, while grouping arises from historical transactions. A zero-balance address may remain privacy-linked. Do not delete it from analysis merely because its current amount is zero.

Sensitive operational data

Clusters can expose treasury structure, payout flows and customer relationships. Restrict RPC, encrypt retained evidence, minimise access and redact addresses and labels from general monitoring. Aggregate metrics are usually enough.

Heuristic limits

CoinJoin-like collaboration, payjoin, shared wallets and imported data can produce false ownership conclusions; incomplete rescans can omit links. State confidence and corroborate with internal transaction provenance before acting.

How specialists test it

Operators test the command on a non-production node first. They check a normal reply, an invalid request, a timeout and a restart. This shows what the response means and prevents one local result from being mistaken for a network-wide outcome.

Conclusion

listaddressgroupings makes wallet privacy leakage visible, but its clusters are heuristic and sensitive. Use them for controlled diagnosis, not public identity claims or automatic customer linkage.