You can export account names and transaction notes from the BitBoxApp as a BIP-329 .jsonl file. This separate label backup can later be imported into the BitBoxApp or another wallet that supports Bitcoin Improvement Proposal 329 (BIP-329).

In the BitBoxApp, wallet labels are managed through the Manage notes section.

Wallet labels are not included in your recovery words or microSD backup. Export them regularly if you rely on account names or transaction notes to organize your wallet.

If you first need to create or change labels, learn how to manage wallet labels in the BitBoxApp. 

Before exporting wallet labels

A BIP-329 export is human-readable and contains the information required to associate your labels with wallet data. Treat the exported file as confidential.

For a deeper explanation of the format, privacy considerations, and wallet interoperability, read the BitBox blog post about importing and exporting wallet labels with BIP-329.

Export wallet labels from the BitBoxApp

1. Open the BitBoxApp.
2. Connect your BitBox to your computer.
3. Unlock your BitBox. You can skip this step if Remember wallet is enabled.
4. Open Settings.
5. Select General.
6. Scroll to Manage notes.

7. Click Export notes.
8. Choose a file name and secure storage location.

9. Click Save.

The BitBoxApp creates a BIP-329 file with the .jsonl extension. Keep this file confidential and include the latest export in your regular backup routine.

Import wallet labels into the BitBoxApp

The BitBoxApp imports BIP-329 label exports in JSON Lines format. The file must use the .jsonl extension.

1. Open the BitBoxApp.
2. Connect your BitBox to your computer.
3. Unlock your BitBox. You can skip this step if Remember wallet is enabled.
4. Open Settings.
5. Select General.
6. Scroll to Manage notes.
7. Click Import notes.
8. Select the BIP-329 .jsonl file.
9. Click Open.

The imported account names and transaction notes are now available in the BitBoxApp.

Recover local note files after moving to a new Mac

If your previous BitBoxApp installation can still be opened, always use Export notes to create a standard BIP-329 .jsonl file instead of following this recovery procedure. Use the steps below only when the previous BitBoxApp installation is no longer accessible but its application data is still available, for example through a Time Machine backup. Because wallet labels are stored locally, connecting and unlocking the same BitBox on a new computer restores access to the wallet but does not restore account names or transaction notes. This workflow is specific to macOS; similar recovery may be possible on another operating system when its BitBoxApp application-data folder is available, but the folder location and required steps differ.

Copying local note files is an unofficial recovery method

The BitBoxApp cannot import these individual .json files through Import notes. Copying them into another BitBoxApp application-data folder may restore the labels, but this is not an officially supported import method and may stop working in a future version. Preserve an unchanged copy of the recovered files before continuing.

 

Locate the note files on your previous Mac or Time Machine backup

Restore or locate the previous BitBoxApp application-data folder on the old Mac or in your Time Machine backup.

1. In Finder, click Go in the menu bar.
2. Select Go to Folder....
3. Enter ~/Library/Application Support/bitbox/notes.
4. Press Return.

The folder contains individual .json working files for accounts that have locally stored labels. If the current path does not exist, an older BitBoxApp installation may use ~/Library/Application Support/BitBoxApp/notes.

Restore the recovered note files on your new Mac

1. Install and open the BitBoxApp on the new Mac.
2. Connect and unlock the same BitBox that you used on the previous computer.
3. Open the wallet once so the BitBoxApp creates its application-data folders.
4. Close the BitBoxApp completely.
5. Open ~/Library/Application Support/bitbox/notes on the new Mac.
6. Make a separate copy of any files already in the destination folder.
7. Copy the recovered .json note files into the destination folder.
8. Reopen the BitBoxApp and check whether the account names and transaction notes appear.
9. If the labels appear, immediately create a supported BIP-329 backup with Export notes.

Your account names and transaction notes have now been restored. Create a supported BIP-329 export to preserve them for future migrations.

If the BitBox is temporarily unavailable, preserve the recovered .json files unchanged until you can connect and unlock the same wallet again.

 

 

Frequently asked questions

Does importing wallet labels affect my funds?

No. Importing account names and transaction notes does not change your addresses, transactions, balances, private keys, or access to your funds.

Can I import the label file into another wallet?

Yes, if the other wallet supports BIP-329. Wallets do not synchronize labels in real time, so export and import a new file whenever you want to transfer later changes.

Is a BIP-329 label export safe to share?

No. The file can contain extended public keys, addresses, transaction IDs, account names, and transaction notes. Only provide it to a wallet or person you trust with this wallet metadata.

What happens if I lose my label export?

Your funds remain safe, but the exported account names and transaction notes cannot be restored from your recovery words or microSD backup. Create a new label export while the labels are still available in the BitBoxApp.