Gap Limit

What Is the Gap Limit?

The gap limit is a wallet configuration parameter that controls how many consecutive unused addresses an HD (hierarchical deterministic) wallet will scan before it assumes there are no more funds to find. Because an HD wallet can derive an effectively infinite number of addresses from a single seed phrase, it needs a stopping rule to know when to quit looking. The gap limit is that stopping rule.

The default gap limit of 20 was established by BIP-44, the specification that defines the standard multi-account hierarchy for deterministic wallets. The BIP states: "If the software hits 20 unused addresses in a row, it expects there are no used addresses beyond this point and stops searching the address chain."

This parameter only matters during wallet discovery: when you restore a wallet from a seed phrase, import it into new software, or when the wallet performs account discovery on startup. During normal use, the wallet already knows which addresses it has generated and tracks them internally.

How It Works

The gap limit operates at the address_index level of the BIP-44 derivation path:

m / purpose' / coin_type' / account' / change / address_index
                                                          ↑
                                              gap limit applies here

When a wallet restores from a seed, it runs the following discovery algorithm:

1. Derive the first account node at index 0 using the extended key
2. Derive the external chain (change = 0) for receiving addresses
3. Sequentially generate addresses starting from address_index 0, checking each against the blockchain for transaction history
4. Count consecutive addresses with no transaction history; when 20 unused addresses appear in a row, stop scanning that chain
5. If no transactions were found on the external chain at all, stop account discovery entirely
6. If transactions were found, increment the account index and repeat from step 1

A critical detail: the algorithm checks for transaction history, not current balance. An address that once received and then spent all its coins still counts as "used." This prevents the wallet from prematurely stopping at addresses that held funds in the past.

The Gap Limit in Practice

Consider a wallet that has generated 50 receiving addresses:

Index:  0  1  2  3  4  ... 18 19 20 21 ... 38 39 40 41 ... 49
Used:   ✓  ✓  ✓  ✗  ✓  ...  ✓  ✗  ✗  ✗  ...  ✗  ✗  ✓  ✗  ...  ✗
                                       ↑
                           gap count starts here

Addresses 20-39: 20 consecutive unused addresses
→ Wallet stops scanning at index 39
→ Address 40 (which has funds) is never checked

In this example, the wallet correctly finds all funds through index 19, but misses the transaction at index 40 because it already encountered 20 consecutive unused addresses and stopped scanning.

Why It Matters

The gap limit becomes a practical problem whenever many addresses are generated without receiving payments in sequence. BIP-44 explicitly requires wallet software to warn users when they attempt to exceed the gap limit by generating a new address, but not all wallets enforce this warning.

For most individual users who generate addresses one at a time and use them sequentially, the default gap limit of 20 works well. Problems arise in specific scenarios where address generation outpaces address usage:

• Merchants using payment processors like BTCPay Server generate a new address for every invoice; if 20+ consecutive invoices go unpaid (common for low-conversion stores), the gap is exceeded
• Exchanges assign unique deposit addresses to each user, and if 20+ consecutive users never deposit, the gap widens beyond the default limit
• CoinJoin operations generate many addresses for mixing outputs, and connection errors during mixing can cause address skips that widen the gap
• Using the same seed across multiple devices without synchronization causes one device to generate addresses the other does not know about

In all these cases, the funds are not lost. The private keys remain derivable from the seed. The wallet software simply does not know to look for them. The funds will appear if you check those specific addresses in a blockchain explorer or increase the gap limit.

Gap Limit Across Wallet Implementations

Different wallets handle the gap limit with varying degrees of flexibility. Most default to 20, but the ease of changing it depends on the wallet's backend architecture.

Electrum Servers vs. Bitcoin Core

The performance cost of increasing the gap limit depends heavily on the wallet's backend architecture:

Bitcoin Core and full-node-backed wallets must query the blockchain directly for each address. Scanning 10,000 addresses means 10,000 individual lookups against the chain state, which is resource-intensive and slow on mobile or low-powered devices. SPV wallets using Bloom filters (BIP-37) face an additional constraint: the 36,000-byte filter size limit caps practical scanning at roughly 20,000 addresses before false positive rates degrade privacy.

Electrum servers (ElectrumX, Fulcrum) take a fundamentally different approach. They maintain an address-indexed database of all transactions, turning each address lookup into a fast database query rather than a blockchain scan. Increasing the gap limit to hundreds or thousands has minimal performance impact. This architectural advantage makes Electrum-based wallets the practical choice for merchants, exchanges, and power users who need high gap limits. For a deeper look at how this indexing works, see the Electrum server architecture research article.

How to Adjust the Gap Limit

If you suspect your wallet is missing funds due to the gap limit, you can increase it in most wallet software. The process varies by wallet:

Electrum

# Open View > Show Console, then run:
wallet.change_gap_limit(100)
wallet.storage.write()

# Restart Electrum, then verify:
wallet.gap_limit

Sparrow Wallet

1. Open the Settings tab for your wallet
2. Click Advanced
3. Increase the gap limit value
4. Click Apply and allow the wallet to rescan

Wasabi Wallet

# Locate the wallet JSON file and edit:
"MinGapLimit": 100

# Save and restart Wasabi

After adjusting the gap limit in any wallet, a rescan of the blockchain is typically required. The wallet will re-derive addresses up to the new limit and check each one for transaction history.

Use Cases

Wallet Recovery

The most common scenario where the gap limit matters is wallet recovery. When restoring a seed phrase into a new wallet application, the software must discover all addresses that ever received funds. If the original wallet generated addresses beyond the gap limit (through merchant invoicing, CoinJoin, or multi-device use), the recovery wallet will show an incomplete balance until the gap limit is increased.

Merchant Payment Processing

Payment processors generate a unique address for each customer invoice. A store that creates hundreds of invoices daily will quickly exceed the default gap limit. BTCPay Server addresses this by using a rescan gap limit of 10,000, ensuring merchant funds are always discoverable during recovery.

UTXO Management

Users who practice careful coin control or UTXO management may generate many change addresses. While change addresses use a separate internal chain (change = 1), the same gap limit logic applies. Heavy UTXO activity can push change addresses beyond the default scanning range.

Risks and Considerations

Invisible Funds

The primary risk of the gap limit is showing an incorrect balance after wallet restoration. Users may believe funds are lost when they are actually sitting at addresses beyond the scanning threshold. This is especially dangerous if a user discards their seed phrase thinking the wallet is empty. Always increase the gap limit and rescan before concluding that funds are missing.

Performance Tradeoff

Higher gap limits require scanning more addresses, which increases wallet recovery time. On full-node-backed wallets, scanning 10,000 addresses can take minutes or longer depending on hardware. On Electrum server-backed wallets, the overhead is minimal due to indexed lookups. Choose a gap limit appropriate for your usage pattern: 20 for casual use, 100 or more for merchants and mixing, 1,000 or more for exchanges.

Privacy Implications

Scanning many addresses reveals your interest in those addresses to whatever server processes the queries. SPV wallets using Bloom filters leak address information to connected peers. Running your own full node or Electrum server eliminates this concern, since all queries stay local.

Cross-Wallet Compatibility

Not all wallets implement the gap limit identically. Some scan only the external chain, others scan both external and internal (change) chains. Some wallets use different default values (Wasabi uses 21, for example). When moving a seed between wallets, the new wallet may not find all funds if its gap limit behavior differs from the original. Using standardized output descriptors can help ensure consistent address discovery across wallet implementations. For more on wallet portability, see the research on output descriptor wallet portability.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.