How to Adjust the BitBoxApp Gap Limit

Table of Contents

When should I adjust the gap limit? Before you start How to Adjust the Gap Limit Windows macOS Linux Frequently Asked Questions (FAQ) What number should I use instead of 50? Is this process safe? Will it mess up my wallet? The command is not working. What should I do?

This guide provides advanced instructions on how to temporarily increase the address gap limit in the BitBoxApp. This procedure can help the app find funds if it is showing an incorrect balance, which can happen after restoring a wallet that used addresses non-sequentially.

When should I adjust the gap limit?

You should only perform this action if your BitBoxApp is showing an incorrect balance or missing transactions. This can happen if you've received funds on addresses generated far down your address list, for example, from a different wallet app that doesn't follow the standard gap limit.

By increasing the gap limit, you tell the BitBoxApp to scan further along the blockchain to discover these "hidden" funds and correct your balance.

Before you start

Important: Make sure the BitBoxApp is completely closed before you begin.
The change is temporary and only lasts for the current session. When you restart the BitBoxApp normally, the limit will reset to the default of 20.
This is intentional. The default limit ensures your wallet remains compatible with other software. This feature is meant for recovery, not for regular use.

How to Adjust the Gap Limit

The following instructions use your computer's command line or terminal. In the examples, we set the limit to 50, but you can change this value if needed.

Windows

Open the Start Menu, type Command Prompt, and open it.
Navigate to the BitBoxApp installation folder by typing cd "C:\Program Files\BitBox" and pressing Enter.
Run one of the commands below to launch the app with the new limit:
1. To set only the receive address limit:
```
.\BitBox.exe --gap-limit-receive 50
```
2. To set only the change address limit:
```
.\BitBox.exe --gap-limit-change 50
```
3. To set both limits:
```
.\BitBox.exe --gap-limit-receive 50 --gap-limit-change 50
```

macOS

Open the Terminal app (you can find it in Applications > Utilities).

Run one of the commands below:

To set the receive address limit:

open -a BitBox --args --gap-limit-receive 50

To set the change address limit:

open -a BitBox --args --gap-limit-change 50

To set both limits:

open -a BitBox --args --gap-limit-receive 50 --gap-limit-change 50

Linux

The command depends on how you installed the BitBoxApp.

Package installation (.deb, .rpm):

If you installed BitBoxApp via a package manager, the command-line tool is usually BitBox and available in your system's PATH.

To set the receive address gap limit:

BitBox -gapLimitReceive 50

To set the change address gap limit:

BitBox -gapLimitChange 50

To set both limits:

BitBox -gapLimitReceive 50 -gapLimitChange 50

If the BitBox command doesn't work, find its full path using which BitBox or whereis BitBox. It's often in /usr/bin or /usr/local/bin. For example, on Ubuntu/Debian:

$ which BitBox
/usr/bin/BitBox
$ /usr/bin/BitBox -gapLimitReceive 50

AppImage:

If you're using an AppImage:

First, make the AppImage file executable (if you haven't already):

chmod +x BitBox-[version]-x86_64.AppImage

(Replace BitBox-[version]-x86_64.AppImage with your actual file name)

To set the receive address gap limit:

./BitBox-[version]-x86_64.AppImage -gapLimitReceive 50

To set the change address gap limit:

./BitBox-[version]-x86_64.AppImage -gapLimitChange 50

To set both limits:

./BitBox-[version]-x86_64.AppImage -gapLimitReceive 50 -gapLimitChange 50

After running the correct command, the BitBoxApp will launch and automatically rescan your accounts with the increased limit. Your correct balance should now be displayed.

Frequently Asked Questions (FAQ)

What number should I use instead of 50?

Starting with 50 is a good choice. If your balance is still incorrect after the rescan, close the app and repeat the process with a higher number, such as 100.

Is this process safe? Will it mess up my wallet?

Yes, this process is safe. It is a temporary, read-only action. It only changes how far the BitBoxApp looks for your existing funds on the blockchain; it does not alter your keys or transactions in any way.

The command is not working. What should I do?

First, double-check that the BitBoxApp is completely closed. Then, verify you are in the correct directory (for Windows) or are using the correct AppImage file name (for Linux). Finally, ensure there are no typos in the command you are entering.