Skip to main content

How to label bitcoin UTXOs (BIP329 and Sparrow)

Label every coin by where it came from, so coins that would tie your identities together never end up in the same transaction. Origin prefixes, the rules they imply, a BIP329 example file and the steps in Sparrow.

Labeling recommendations

A label is a private note a wallet keeps next to each coin. Written the same way every time, labels tell which coins can be spent together without tying your identities together. Wallets exchange them as BIP329 files (in Sparrow: Export Wallet and Import Wallet, Labels), and the am-i.exposed wallet scan reads them to mark coins and to guide the coin selector.

Best practice: one account per origin

Keep separate wallets or accounts for KYC, no-KYC and post-CoinJoin coins, and an accidental merge becomes impossible. Labels then only need the observer and the detail, and the wallet-level origin setting in the wallet scan ("This wallet holds") covers the rest. Prefixes matter most when origins share one wallet.

Format, in this order:

[KYC|noKYC|CJ] observer · platform or reason · fiat value at the time

The observer is whoever can link the coin to you (the counterparty, the exchange); it can differ from the platform. Every part after the prefix is optional.

For example: [noKYC] Juan · RoboSats purchase · 250 EUR (73,600 EUR/BTC), [KYC] Bitstamp · withdrawal · 1,000 EUR

Origin prefixes

  • [KYC]KYCBought or withdrawn with your identity: an exchange or a broker that verified you.
  • [noKYC]no-KYCAcquired without identity: peer-to-peer trades (Bisq, RoboSats, Hodl Hodl), mining, work paid in bitcoin.
  • [CJ]CoinJoinA CoinJoin output (Whirlpool, WabiSabi, JoinMarket).
  • [toxic] / [tóxico]ToxicDust, CoinJoin change or coins from a doubtful source.
  • [person] / [persona]PersonPaid by someone who knows who you are: a friend, a client, an employer.

Case does not matter, and the English and Spanish words are both recognized.

Change needs no prefix: the wallet already marks it (Sparrow adds "(change)"), and it inherits the origin of the coins it came from.

What each label says

  • -Address labels say whom the address was given to.
  • -Output labels say where the coin came from and its state.
  • -Transaction labels say the purpose and the counterparty.
  • -Mark dust, toxic coins and coins to keep as not spendable (spendable: false, "freeze" in Sparrow).

Spending rules

  1. Never merge [KYC] coins with [noKYC] coins.
  2. Do not merge [CJ] coins with coins that are not [CJ]: spend them one by one, ideally with no change.
  3. Prefer merging coins with the same origin, or coins already linked on-chain. When a payment needs a merge across origins, accept it (spending checklist, rules 4 and 5).
  4. Change inherits the origin of its parent coins.
  5. Toxic coins: freeze them, or remix them alone.
  6. Spend change on its own when an observer can tell it is change: never merge such a coin (change a change-detection rule points at, change sent back to or reusing an address, CoinJoin change) with other coins. Change is identifiable when a rule (round amount, address type, value disparity, an unnecessary input) or the address gives it away; when the outputs of its transaction look alike, it is ambiguous and merging it only adds a probable link. Never spend both outputs of one transaction together. Spend identifiable change alone, without change if possible, or move it with a Lightning swap.

With labels loaded, the coin selection advisor ranks plans that break rules 1, 2, 5 or 6 below every plan that respects them, warns about rule 3, and leaves frozen coins out unless asked. Rule 6 needs no labels.

In Sparrow

  1. Label in the Transactions tab: double-click the Label column of a transaction. Sparrow copies the label to that transaction's coins in the UTXOs tab, adding "(received)" or "(change)", and to the address when it has no label. A label typed in the UTXOs tab is not copied back to the transaction.
  2. Give a coin its own label in the UTXOs tab (Label column) only when it needs one: for example one of several outputs of the same transaction with a different origin.
  3. The Addresses tab has a Label column too: label a receive address with whom it was given to before the payment arrives.
  4. Freeze a coin: in the UTXOs tab, right-click it and choose Freeze UTXO (Unfreeze UTXO undoes it). A frozen coin is exported as spendable: false.
  5. Export: File menu, Export Wallet..., then Labels. The result is a BIP329 .jsonl file; load it in the wallet scan with Import file in the Labels panel.
  6. Import into Sparrow: open the wallet, then File menu, Import Wallet..., then Labels.

A few made-up testnet records in this convention, shaped like a Sparrow export. They match no real wallet.