Address Gap Limit

What Is the Address Gap Limit?

The address gap limit is a wallet parameter that controls how far ahead a wallet looks when scanning for used addresses in a hierarchical deterministic (HD) wallet. An HD wallet can generate a practically infinite number of addresses from a single seed phrase, but scanning all possible addresses would take forever. The gap limit sets a boundary: once the wallet encounters a consecutive run of unused addresses equal to the gap limit, it assumes there are no more funds beyond that point and stops scanning.

This concept was introduced in BIP-44, which standardized how HD wallets derive addresses. The specification recommends a default gap limit of 20, meaning a wallet will generate and check 20 consecutive addresses. If none of them have ever received a transaction, the wallet concludes that the remaining address space is empty.

The gap limit exists because of a fundamental tension in HD wallets: deterministic key generation enables infinite addresses, but practical wallet software needs a finite scan window. Without a gap limit, wallet recovery would require checking an unbounded number of addresses against the blockchain, which is computationally impractical.

How It Works

HD Wallet Address Generation

An HD wallet derives addresses sequentially along a derivation path. Each address gets an incrementing index: address 0, address 1, address 2, and so on. The wallet tracks which addresses it has distributed to users or services for receiving payments.

Under normal use, a wallet hands out addresses in order. When you click "Generate New Address," the wallet increments its internal counter and derives the next address in the sequence. This sequential pattern means used addresses tend to cluster at the beginning of the index range, with unused addresses following after.

The Scanning Process

When a wallet recovers from a seed phrase, it needs to rediscover which addresses hold funds. The process works as follows:

1. Derive the first address (index 0) and check if it has any transaction history on the blockchain
2. Move to the next address (index 1) and repeat
3. Continue incrementing the index, checking each address for activity
4. Track the number of consecutive addresses with no transaction history
5. When the consecutive unused count reaches the gap limit (typically 20), stop scanning

The critical detail: the counter resets to zero whenever the wallet finds an address with transaction history. So if addresses 0 through 5 are used, addresses 6 through 24 are empty, and address 25 is used, the wallet will stop at address 25 (having hit 19 consecutive empty addresses) and then continue from 25 since it found activity. It only stops after finding 20 consecutive unused addresses in a row.

Scanning Logic

The following pseudocode illustrates how a wallet applies the gap limit during recovery:

function scanAddresses(masterKey, gapLimit = 20) {
  let index = 0;
  let consecutiveUnused = 0;
  let discoveredAddresses = [];

  while (consecutiveUnused < gapLimit) {
    const address = deriveAddress(masterKey, index);
    const hasHistory = checkBlockchain(address);

    if (hasHistory) {
      discoveredAddresses.push({ index, address });
      consecutiveUnused = 0; // reset the gap counter
    } else {
      consecutiveUnused++;
    }

    index++;
  }

  return discoveredAddresses;
}

This logic applies independently to each address type within the wallet. A BIP-44 wallet scans the external chain (for receiving addresses) and the internal chain (for change addresses) separately, each with its own gap limit counter.

Multiple Account Discovery

BIP-44 wallets support multiple accounts, each with its own address space. The gap limit also applies at the account level: wallets scan accounts sequentially and stop when they find an account whose first address has never been used. This means accounts must also be created in order to ensure proper discovery.

When the Default Gap Limit Falls Short

A gap limit of 20 works for typical wallet usage where addresses are generated and used sequentially. Problems arise when this assumption breaks:

• Merchant payment processors that pre-generate hundreds of unique addresses for incoming orders, many of which may never receive payment
• Sharing an xpub with multiple services that each generate addresses independently, creating gaps in the sequence
• Exchange deposit systems that assign unique addresses to thousands of users, with many accounts remaining unfunded
• Privacy-focused usage patterns where users skip addresses or generate many addresses in advance to avoid address reuse

In these scenarios, a wallet recovering from seed may miss funds sitting on addresses beyond the gap. The wallet reports a lower balance than expected, and the user may believe their funds are lost when they are simply invisible to the scanning process.

Solutions for Gap Limit Issues

Increasing the Gap Limit

The simplest fix is to increase the gap limit in your wallet software. Most wallets that support manual configuration allow you to set a custom value:

In Electrum, you can change the gap limit through the console:

# In Electrum console (View > Console)
wallet.change_gap_limit(50)
wallet.synchronize()

Setting the gap limit higher forces the wallet to scan further along the address chain before giving up. A value of 100 or 200 resolves most merchant and multi-service scenarios.

Server-Based Lookups

Rather than scanning addresses one by one against a local or remote node, some architectures use indexing servers that maintain a full map of address activity. ElectrumX and Fulcrum servers index the entire blockchain by address, making lookups fast regardless of gap size.

With an indexing server, increasing the gap limit has minimal performance cost because address lookups are database queries rather than blockchain scans. This is why Electrum-based wallets handle high gap limits efficiently: the server does the heavy lifting.

For developers building wallet applications, connecting to an indexing server and using a generous gap limit (100 or more) is the most robust approach. The UTXO model means every address potentially holds independent UTXOs, and missing even one address means missing those funds entirely.

Descriptor Wallets

Modern Bitcoin Core versions use descriptor wallets that explicitly define the derivation scheme and range of addresses to scan. Instead of relying solely on the gap limit heuristic, descriptors specify exactly which key paths the wallet should monitor:

# Bitcoin Core descriptor with explicit range
wpkh([fingerprint/84'/0'/0']xpub.../0/*)#checksum

# Import with a specific range
importdescriptors '[{
  "desc": "wpkh(xpub.../0/*)#checksum",
  "range": [0, 1000],
  "timestamp": "now"
}]'

This approach sidesteps the gap limit entirely for known address ranges, giving the wallet explicit instructions about which addresses to track.

Use Cases

Wallet Recovery

The most common scenario where the gap limit matters is wallet recovery. When restoring a wallet from a seed phrase, the wallet software must rediscover all previously used addresses. If the original wallet had generated addresses beyond the gap limit (due to pre-generation or multi-service use), the recovering wallet will miss those funds unless configured with a matching or higher gap limit.

Payment Processing

E-commerce systems that generate a unique Bitcoin address per invoice commonly run into gap limit issues. If a store creates 100 addresses for 100 pending orders but only 10 are paid, there are 90 unused addresses scattered throughout the sequence. During wallet recovery, a gap limit of 20 would fail to discover payments made to addresses later in the sequence.

Multi-Service Xpub Sharing

Users who share their xpub with multiple services (a BTCPay Server instance, a portfolio tracker, and a mobile wallet) may find that each service generates addresses independently. Service A might generate addresses 0 through 30, while Service B starts at 0 and generates its own sequence. The resulting address usage pattern can have large gaps that exceed the default limit.

Privacy Practices

Users who avoid address reuse for privacy reasons may generate many addresses in advance without using all of them. This creates natural gaps in the address sequence that can exceed the default gap limit, making proper configuration important for anyone prioritizing transaction privacy.

Risks and Considerations

Lost Funds Perception

The most significant risk is users believing their funds are lost when they are simply beyond the wallet's scan range. After recovering a wallet and seeing a zero or lower-than-expected balance, users may panic or assume theft. Education about the gap limit and how to adjust it is the primary mitigation: the funds remain on the blockchain and are recoverable once the wallet scans far enough.

Performance Impact

Setting an extremely high gap limit increases the time and resources required for wallet synchronization. For wallets that query a full node directly (rather than an indexing server), scanning 10,000 addresses means 10,000 blockchain lookups. On resource-constrained devices like mobile phones, this can significantly delay wallet loading.

The tradeoff is straightforward: higher gap limits increase the chance of discovering all funds but slow down initial sync. For most users, a gap limit between 50 and 200 balances thoroughness with acceptable performance. Wallets connected to ElectrumX or Fulcrum servers experience minimal slowdown even with high values.

Security Considerations

Sharing an xpub with third-party services exposes all current and future addresses derived from that key. While the xpub cannot be used to spend funds, it reveals the full transaction history and balance across every derived address. This is a privacy risk independent of the gap limit, but gap limit issues often surface alongside xpub sharing because that is where address generation diverges from sequential order.

No Universal Standard Beyond 20

While BIP-44 standardized the default gap limit at 20, there is no universal standard for higher values. Different wallet software, hardware devices, and services may use different defaults or impose different maximums. When moving between wallets, users must be aware of each tool's gap limit configuration and adjust accordingly to ensure full fund discovery.

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.