Adjusting BitBoxApp Gap Limits

Table of Contents

Why adjust BitBoxApp gap limits? Important: How to adjust the gap limit Windows macOS Linux

Why adjust BitBoxApp gap limits?

If your BitBoxApp shows an incorrect balance, it might not be scanning far enough into your address history. This can happen after many transactions or if you’ve received funds to addresses generated outside the app.

Adjusting the gap limit tells the BitBoxApp to scan more addresses, which usually fixes the balance.

Important:

This is a temporary setting
The gap limit you set only applies to the current session.
When you close the BitBoxApp, the limit resets to the default of 20.

This is intentional. The standard 20 ensures compatibility with other wallets. This feature should only be used to check for or recover funds.

Before you start, make sure the BitBoxApp is completely closed.

How to adjust the gap limit

You will use a command-line instruction for your operating system. In the examples below, we use a value of 50. You can change this number as needed.

Windows

Open Command Prompt or PowerShell.
Navigate to the BitBoxApp installation folder. Type cd "C:\Program Files\BitBox" and press Enter.
Run one of the commands below:

Set receive address limit:

.\BitBox.exe -gapLimitReceive 50

Set change address limit:

.\BitBox.exe -gapLimitChange 50

Set both limits:

.\BitBox.exe -gapLimitReceive 50 -gapLimitChange 50

macOS

Open the Terminal app.
Run one of the commands below:

Set receive address limit:

open -a BitBoxApp --args -gapLimitReceive 50

Set change address limit:

open -a BitBoxApp --args -gapLimitChange 50

Set both limits:

open -a BitBoxApp --args -gapLimitReceive 50 -gapLimitChange 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

Once you run the command, the BitBoxApp will launch. It will rescan your accounts with the new limit, and your balance should now be correct.