What Is BIP-329? The Simple Guide to Bitcoin Wallet Labels

by

If you’ve ever used a Bitcoin wallet, you’ve probably seen labels such as “Salary,” “Exchange,” “Savings,” or “Cold Storage.” These labels help you understand what your transactions and addresses represent. But what happens when you switch wallets?

This is the problem BIP-329 tries to solve.

BIP-329, formally called the Wallet Labels Export Format, proposes a standardized way for Bitcoin wallets to export and import labels and related wallet metadata. Instead of keeping this information trapped inside one wallet application, users could move it between compatible wallets using a common format.

What Is BIP-329?

BIP-329 is a Bitcoin Improvement Proposal that defines a format for exporting wallet labels.

The proposal was assigned on August 23, 2022, and its current status is Draft. It is an Informational BIP in the Applications layer.

The basic idea is simple:

Your Bitcoin wallet contains more information than just private keys and addresses.

It may also contain descriptions and metadata that help you understand your funds.

For example, your wallet might label:

  • A transaction as “Bitcoin purchase”
  • An address as “My savings”
  • An output as “Cold storage”
  • A public key as “Hardware wallet”
  • An xpub as “Multisig signer”
  • A Silent Payments scan key with a useful description

Without a standard, these labels may remain locked inside the wallet application that created them.

BIP-329 provides a common format for moving them.

Why Do Bitcoin Wallets Need Labels?

Bitcoin transactions are made from technical data.

A normal transaction does not automatically tell you:

“This was money you received from your friend.”

Instead, your wallet sees things such as transaction IDs, addresses, inputs, outputs, public keys, and UTXOs.

As your wallet becomes more active, remembering what everything represents can become difficult.

Imagine receiving Bitcoin from several sources.

You might have:

  • 0.01 BTC from an exchange
  • 0.03 BTC from a client
  • 0.005 BTC from a friend
  • 0.02 BTC moved from your savings wallet

Your wallet can identify the transactions, but labels can help you identify their purpose.

For example:

Transaction → “Payment from client”

Address → “Exchange withdrawal”

Output → “Long-term savings”

These descriptions can become particularly useful when deciding which coins to spend.

Why Are Labels Important With Bitcoin’s UTXO Model?

Bitcoin doesn’t work like a traditional bank account.

Instead, Bitcoin uses unspent transaction outputs, commonly called UTXOs.

Each UTXO represents a specific amount of Bitcoin that your wallet can potentially spend.

That means a wallet may need to decide which individual coins or outputs to use when creating a transaction.

Labels can provide useful context.

For example, imagine your wallet contains three UTXOs:

  • UTXO A — “Salary”
  • UTXO B — “Exchange withdrawal”
  • UTXO C — “Private savings”

If you spend UTXO C, you may unintentionally reveal information about your savings strategy or connect transactions that you would rather keep separate.

BIP-329’s motivation specifically highlights the usefulness of labels in Bitcoin’s UTXO model because labels can indicate where funds came from or whether an output represents change from another transaction.

So labels aren’t simply cosmetic notes.

They can help users make better spending and privacy decisions.

The Problem: Wallet Lock-In

Now imagine you have used Wallet A for several years.

You’ve carefully labeled hundreds of transactions and addresses.

Then you decide to move to Wallet B.

You can often move important wallet information using established standards.

For example, Bitcoin has standards covering things such as:

  • Seed phrases
  • Hierarchical deterministic wallets
  • Derivation paths
  • Addresses
  • Wallet structures

However, your personal labels are a different matter.

Your old wallet might know:

“Transaction X = salary payment”

while your new wallet only sees:

Transaction X = f91d...

The Bitcoin transaction itself hasn’t changed.

You’ve simply lost the useful human-readable context.

BIP-329 addresses this problem by creating a standardized way to export and import labels. Its stated goal includes reducing lock-in to a particular wallet application.

BIP-329 Is Not a Wallet Backup

This distinction is extremely important.

BIP-329 is not intended to replace your wallet backup.

It does not export your private keys.

Instead, it focuses on labels and related metadata.

Think of the difference like this:

Wallet Backup

A wallet backup helps you recover access to your Bitcoin.

It may contain information needed to reconstruct your wallet and control your funds.

BIP-329 Export

A BIP-329 export helps preserve the descriptions and metadata surrounding your wallet activity.

You could think of it as moving your wallet’s notes and organizational information rather than moving the keys themselves.

This distinction makes BIP-329 particularly interesting for people who use multiple wallet applications.

What Information Can BIP-329 Describe?

The format can identify several types of Bitcoin wallet records.

The core specification defines these types:

  • tx — transaction
  • addr — Bitcoin address
  • pubkey — public key
  • input — transaction input
  • output — transaction output
  • xpub — extended public key
  • spscan — Silent Payments scan key expression

Each record can then contain information such as a reference and an optional label.

For example, a wallet could associate a transaction with a label such as:

“Payment from client”

Or an address could be labeled:

“Personal savings address”

The important part is that the receiving wallet can understand what kind of record the label belongs to.

What Is JSON Lines?

You may have never heard of JSON Lines before.

Don’t worry. The concept is simpler than it sounds.

JSON is a common format for representing structured information.

JSON Lines, sometimes called newline-delimited JSON, puts one JSON object on each line.

So instead of creating one enormous document containing everything, BIP-329 uses a sequence of individual records.

Conceptually, it looks like this:

Record 1

Transaction information

Record 2

Address information

Record 3

Public-key information

Record 4

Output information

Each line contains its own valid JSON object.

According to the BIP, the export is a UTF-8 text file with one JSON object per line. The format makes the data lightweight, human-readable, streamable, and easier to process incrementally.

That makes sense for wallet software because a large wallet export can contain many records.

Why BIP-329 Matters

At first glance, wallet labels may sound like a minor feature.

However, they become much more important as Bitcoin wallets become more sophisticated.

Modern wallets can manage:

  • Multiple accounts
  • Many addresses
  • Hundreds of UTXOs
  • Multisignature setups
  • Hardware-wallet connections
  • Extended public keys
  • Silent Payments
  • Complex transaction histories

The more complicated the wallet becomes, the more valuable good organization becomes.

BIP-329 attempts to make that organization portable.

Instead of saying:

“Your labels belong to this wallet application.”

the idea is:

“Your labels are your wallet data, and compatible applications should be able to understand them.”

That is the bigger idea behind BIP-329.

How Does a BIP-329 Record Work?

Every BIP-329 record uses a few important fields.

The two essential fields are:

  • type
  • ref

A label can then describe that reference.

For example, a simplified record could look like this:

{
  "type": "tx",
  "ref": "abc123...",
  "label": "Payment for laptop"
}

Here, type tells the wallet what kind of object the record describes.

The ref identifies the specific object.

The label tells the user what that object means.

This simple structure allows different wallets to understand the same exported information.

The type Field

The type field is one of the most important parts of BIP-329.

The specification currently defines seven types:

  • tx
  • addr
  • pubkey
  • input
  • output
  • xpub
  • spscan

Let’s look at each one.

1. tx — Transaction

The tx type refers to a Bitcoin transaction.

Its reference is the transaction ID, also called the transaction hash.

For example, you might label a transaction:

“Salary — September”

or:

“Payment for computer”

This can make your transaction history much easier to understand later.

Instead of seeing only a long transaction ID, your wallet can associate that transaction with a meaningful description.

2. addr — Bitcoin Address

The addr type refers to a Bitcoin address.

For example, you might label an address:

“Emergency savings”

or:

“Cold wallet deposit address”

This becomes particularly useful when a wallet contains many addresses.

Bitcoin wallets can generate new addresses over time, so users may otherwise forget why a particular address exists.

BIP-329 gives wallets a standardized way to move those labels between compatible applications.

3. pubkey — Public Key

BIP-329 can also attach labels to public keys.

A public key is a cryptographic key used by Bitcoin wallets and scripts.

You might label a public key according to its purpose or the person or device associated with it.

This becomes especially useful in more advanced wallet setups where multiple keys are involved.

Wallet software can also use imported public-key records to help match derived addresses with known wallet data.

4. input — Transaction Input

Bitcoin transactions contain inputs that reference previous transaction outputs.

BIP-329 can label individual inputs.

An input reference combines:

Transaction ID + input index

For example:

transaction-id:0

The 0 identifies the first input.

This allows a wallet to attach information to a specific input rather than only labeling the entire transaction.

That distinction can matter when a transaction combines several different UTXOs.

5. output — Transaction Output

BIP-329 can also label individual transaction outputs.

This is particularly important because Bitcoin uses the UTXO model.

An output can represent Bitcoin that remains available to spend later.

You might label an output:

“Business savings”

“Customer payment”

or:

“Change from laptop purchase”

BIP-329 also allows an output record to include the spendable field.

For example:

{
  "type": "output",
  "ref": "abc123...:1",
  "label": "Do not spend",
  "spendable": false
}

This tells the importing wallet that the output should not be treated as spendable.

The specification limits the spendable field to output records.

6. xpub — Extended Public Key

The xpub type refers to an extended public key defined by BIP-32.

An extended public key can allow wallet software to derive public addresses without having access to the corresponding private keys.

This can be useful when moving wallet metadata between applications.

It can also help wallets match extended public keys with signers in setups such as multisig.

Importantly, an xpub does not give someone the ability to spend your Bitcoin.

However, sharing public wallet information can still have privacy implications because it can reveal relationships between addresses.

7. spscan — Silent Payments Scan Key

The spscan type is designed for Silent Payments scan-key information.

This connects BIP-329 with newer Bitcoin privacy technologies.

A wallet can use this record to preserve a label associated with a Silent Payments scan-key expression.

You don’t need to understand Silent Payments to understand the basic purpose here:

BIP-329 gives wallet software a standardized place to store and move the label associated with that information.

What Is the origin Field?

Another important BIP-329 field is origin.

It is optional.

The origin field provides information about the wallet associated with a label.

This becomes useful when multiple accounts or wallets use related key material.

For example, imagine a wallet contains:

  • Personal account
  • Business account
  • Savings account

A transaction label such as “Payment” may not be enough to determine which account it belongs to.

Origin information can help the importing wallet distinguish between them.

BIP-329 uses abbreviated output-descriptor information for this purpose.

Why Is origin Important?

Imagine you export labels from two accounts derived from the same seed.

Both accounts might contain transactions with similar labels.

Without additional information, an importing wallet could have difficulty determining which wallet or account a label belongs to.

The origin field helps solve that problem.

In other words:

label tells you what something means.

origin can help identify where that wallet data came from.

BIP-329 Is More Than Just Labels

The core format focuses on labels, but the specification also allows additional wallet information.

For transactions, optional information can include:

  • Block height
  • Timestamp
  • Transaction fee
  • Bitcoin value
  • Exchange-rate information

For addresses, inputs, and outputs, additional information can include key-path data.

Inputs and outputs can also contain value and fair-market-value information.

This means a wallet export can preserve useful context that another wallet might otherwise have difficulty reconstructing.

However, these additional fields are optional.

The basic goal remains portable wallet metadata.

Why This Matters for Bitcoin Users

Imagine you have used Wallet A for several years.

You’ve carefully labeled hundreds of transactions and addresses.

Then you decide that Wallet B has better features.

Without a standardized label format, moving your Bitcoin may be possible while leaving all your carefully organized metadata behind.

BIP-329 aims to separate those two things.

Your Bitcoin can remain on the blockchain.

Your wallet keys can remain under your control.

And your labels and related metadata can potentially move with you.

That is the real purpose of BIP-329.

One Important Warning: Labels Can Reveal a Lot

There is an important privacy issue.

A label such as:

“Salary from ABC Company”

can reveal information about your financial activity.

Likewise:

“Payment to John”

or:

“Business savings”

can expose relationships that you may not want other people to see.

BIP-329 therefore warns users to treat exports as privacy-sensitive information.

The specification recommends encryption when transferring exports over untrusted networks and recommends considering encryption at rest.

Unencrypted exports should also be deleted as soon as possible.

This is important because a BIP-329 file does not need to contain private keys to be sensitive.

Your financial metadata can still reveal a great deal about how you use Bitcoin.

What Are the Advantages of BIP-329?

BIP-329 solves a problem that can easily be overlooked.

Bitcoin wallets can hold years of transaction history, addresses, UTXOs, and other information. Without a common label format, moving between wallet applications can mean losing the context that makes that information useful.

Here are some of the biggest advantages.

1. Easier Wallet Migration

One of the main goals of BIP-329 is reducing wallet lock-in.

Imagine you’ve used one wallet for several years and carefully labeled your transactions.

You later switch to another wallet.

Your Bitcoin can move with your keys, but your labels may not automatically move with you.

BIP-329 provides a standardized format for exporting and importing that metadata.

This makes switching between compatible wallets much easier.

2. Better UTXO Management

Bitcoin uses the UTXO model.

That means your wallet doesn’t simply contain one balance. Instead, it tracks individual unspent transaction outputs.

Labels can help you understand where those UTXOs came from.

For example:

  • Customer payment
  • Salary
  • Savings
  • Change
  • Donation
  • Business funds

This context can help you make better spending decisions.

Some wallets also allow users to freeze outputs. BIP-329 includes the spendable field so that this kind of wallet metadata can also be preserved for outputs.

3. Useful for Multisig Wallets

BIP-329 can also help with more advanced wallet setups.

Extended public keys can identify signers, while public-key records can help wallets match derived addresses with known keys.

That can be useful when managing multisignature wallets where several keys or participants are involved.

Instead of treating every address as an isolated piece of information, wallet software can preserve more of the organizational context.

4. Human-Readable Organization

Bitcoin addresses and transaction IDs are difficult for humans to remember.

A label such as:

“Emergency Savings”

is much easier to recognize than a long hexadecimal transaction ID.

BIP-329 doesn’t change the Bitcoin blockchain.

Instead, it helps wallets attach human-readable context to the information they already manage.

What Are the Disadvantages of BIP-329?

BIP-329 is useful, but it isn’t perfect.

1. Wallet Support Is Required

A standardized format only becomes useful when wallet software supports it.

If Wallet A exports BIP-329 data but Wallet B doesn’t understand the format, the metadata cannot magically become useful.

Fortunately, support is growing. For example, BTCPay Server added BIP-329 label importing in July 2026, allowing compatible label files to be mapped to transaction, address, and UTXO information.

However, support can still vary between applications.

2. Imported Labels May Not Be Perfect

Different wallets don’t necessarily store information in exactly the same way.

The BIP allows an importing wallet to ignore records it doesn’t store.

It may also truncate labels if they exceed the wallet’s supported length.

Therefore, exporting your labels does not guarantee that every detail will appear exactly the same after importing them into another application.

3. BIP-329 Is Not a Wallet Backup

This is one of the most important points.

BIP-329 does not replace:

  • Your seed phrase
  • Your private keys
  • Your wallet backup
  • Your hardware-wallet backup

The format is designed for wallet labels and related metadata.

It is not designed to give you control over your Bitcoin.

If you lose your private keys, a BIP-329 label file won’t restore access to your funds.

Is BIP-329 a Privacy Risk?

Yes, it can be.

This is one of the most important things to understand before exporting your labels.

Imagine an exported file containing labels such as:

“Salary — Company ABC”

“Payment to John”

“Business savings”

“Cold storage”

Those labels could reveal relationships between transactions, people, addresses, and financial activity.

Even without private keys, that information can be sensitive.

The BIP-329 specification specifically warns about the privacy-sensitive nature of these exports. It recommends encryption when sending them across untrusted networks and recommends considering encryption at rest. It also says unencrypted exports should be deleted as soon as possible.

Can a BIP-329 File Contain Private Keys?

No private-key record type is defined by BIP-329.

That is intentional.

The format focuses on metadata rather than spending credentials.

For example, it can contain information about:

  • Transactions
  • Addresses
  • Public keys
  • Inputs
  • Outputs
  • Extended public keys
  • Silent Payments scan-key expressions

But that doesn’t mean the file is harmless.

An xpub or detailed transaction metadata can still expose useful information about a wallet.

So you should treat a BIP-329 export as sensitive wallet information, even though it isn’t a seed phrase or private-key backup.

BIP-329 vs a Seed Phrase

These two things serve completely different purposes.

Seed Phrase

A seed phrase helps a compatible wallet recover the keys needed to control funds.

BIP-329 Export

A BIP-329 export preserves labels and related wallet metadata.

Think of it this way:

Seed phrase = control

BIP-329 = organization

You should never confuse the two.

Who Can Benefit From BIP-329?

BIP-329 can be especially useful for people who manage Bitcoin across multiple wallets.

Long-Term Bitcoin Holders

If you’ve accumulated years of transactions, labels can make your wallet history much easier to understand.

Businesses

Businesses can use labels to organize customer payments, operational funds, expenses, and other Bitcoin activity.

Multisig Users

Multisig setups can involve multiple keys and participants, making metadata and key identification particularly useful.

Wallet Developers

Developers can use a common format rather than inventing another wallet-specific label export system.

People Switching Wallets

This is perhaps the simplest use case.

If you want to move from one compatible wallet application to another, BIP-329 can help preserve your existing organization.

How Should You Handle a BIP-329 Export?

Treat it like sensitive financial data.

1. Don’t Upload It Publicly

Never post your wallet-label export on a public forum, social media account, or public file-sharing service.

2. Encrypt It When Appropriate

If you’re transferring the file across an untrusted network, encryption can reduce the risk of exposing its contents.

3. Delete Unencrypted Copies

If you temporarily create an unencrypted export, remove it when you no longer need it.

4. Check the Destination Wallet

Before importing the file, confirm that the receiving wallet supports BIP-329 and understand what records it can actually import.

5. Keep Your Real Wallet Backup Separate

Your seed phrase and private keys should remain protected independently of your label export.

Is BIP-329 Part of the Bitcoin Blockchain?

No.

This distinction is important.

BIP-329 is an application-layer informational BIP.

It doesn’t change Bitcoin’s consensus rules.

It doesn’t create a new transaction type.

It doesn’t change how miners validate blocks.

It doesn’t change the supply of Bitcoin.

Instead, it defines a standardized way for wallet applications to exchange metadata.

The current BIP lists BIP-329 as Draft, meaning the proposal has not reached the Complete or Deployed status.

What Happens If BIP-329 Becomes Widely Supported?

The biggest benefit could be something users barely notice.

Wallet switching could become smoother.

You could export your wallet’s labels from one compatible application and import them into another without manually recreating years of notes.

That would make Bitcoin wallets feel less like isolated applications and more like interoperable tools.

The Bitcoin itself doesn’t need to move for the metadata to move.

That’s the key idea.

Frequently Asked Questions

What is BIP-329?

BIP-329 is a Bitcoin proposal that defines a standardized format for exporting and importing wallet labels and related metadata.

Is BIP-329 a Bitcoin protocol upgrade?

No. It is an application-layer informational BIP and does not change Bitcoin’s consensus rules.

Is BIP-329 complete?

No. The current specification lists BIP-329 as Draft.

What format does BIP-329 use?

BIP-329 uses UTF-8 encoded JSON Lines, with one valid JSON object per line.

What can BIP-329 label?

It defines records for transactions, addresses, public keys, inputs, outputs, extended public keys, and Silent Payments scan-key expressions.

Does BIP-329 contain private keys?

No private-key record type is defined.

Can BIP-329 replace my seed phrase?

No. A BIP-329 file is metadata, not a wallet recovery backup.

Why are Bitcoin wallet labels useful?

Labels help users understand transactions, addresses, inputs, outputs, and the source or purpose of funds.

Can BIP-329 help with wallet migration?

Yes. Its main goal is to make wallet labels portable between compatible applications.

Is a BIP-329 file private?

It can contain sensitive financial and wallet metadata. You should protect it accordingly.

Can BIP-329 label UTXOs?

Yes. Outputs can be labeled, and BIP-329 also defines the optional spendable field for outputs.

Does BIP-329 change Bitcoin transactions?

No. It describes wallet metadata and does not modify Bitcoin’s transaction or consensus rules.

Final Thoughts

BIP-329 may sound like a small technical standard, but it addresses a very practical Bitcoin wallet problem.

People don’t just accumulate Bitcoin.

They also accumulate context.

They may want to remember where funds came from, which address belongs to a particular purpose, which UTXOs should remain untouched, or which transactions belong to a business or personal account.

Without a common format, that information can become trapped inside a particular wallet application.

BIP-329 provides a standardized way to move that metadata.

Its basic idea is simple:

Your Bitcoin stays on the blockchain.

Your keys control your Bitcoin.

BIP-329 helps preserve the information that helps you understand and organize it.

The proposal is still Draft, so wallet support and implementation details can continue to evolve.

For ordinary Bitcoin users, you don’t need to understand every JSON field.

But if you manage a large wallet, use multiple applications, operate a multisig setup, or simply want your transaction labels to remain portable, BIP-329 is a useful standard to know about.

Most importantly, remember that wallet metadata can reveal sensitive financial information.

Protect your label exports just as you would protect other private information about your Bitcoin activity.

5 Key Takeaways

  1. BIP-329 standardizes Bitcoin wallet-label exports.
  2. It uses JSON Lines to organize wallet metadata.
  3. It can cover transactions, addresses, keys, inputs, outputs, xpubs, and Silent Payments scan information.
  4. It helps reduce wallet lock-in and makes metadata easier to migrate.
  5. It is not a replacement for a seed phrase or wallet backup.

Related posts:

Bitcoin Silent Payments Explained: How to Send Bitcoin Privately Without Revealing Your Address Bitcoin Payment Links & QR Codes: What Is a Bitcoin Payment URI? Bitcoin Payments Are Getting a Human Friendly Upgrade: What Is BIP 353? BIP 47 Explained: The Bitcoin Privacy Feature You Probably Haven’t Heard Of

Leave a Comment