Gap Limit

The gap limit is the rule a hierarchical deterministic wallet uses to decide when to stop scanning for funds. Because an HD wallet can derive an effectively infinite sequence of addresses, it needs a stopping condition during recovery and balance checks. The BIP44 convention sets this limit at 20: if the wallet encounters 20 consecutive addresses with no transaction history, it assumes there is nothing further on that branch and halts the scan. It is a pragmatic heuristic that works invisibly for most users — right up until it doesn't.

Why it can lose funds (temporarily)

The gap limit is a heuristic, not a guarantee. If you (or a generating tool) skip ahead and receive payment to, say, the 25th address while addresses 5 through 24 stay empty, a fresh wallet restored from the seed may never scan far enough to find it. The balance appears as zero even though the coins are safely on-chain and fully recoverable. This is a classic and avoidable cause of "my restored wallet shows nothing" panic — the funds were never lost, only unfound. Note also that a wallet scans the external (receive) chain and the internal (change) chain separately, each with its own gap counting, so a long run of unused receive addresses can hide funds even while change addresses show activity.

Where people actually hit it

Ordinary wallet use rarely trips the limit, because standard UIs hand out addresses in order and only advance as previous ones see use. The real-world trouble spots are systems that generate addresses faster than payments arrive: a self-hosted store or donation page that derives a fresh address per visitor, a merchant running BTCPay-style invoicing where most invoices expire unpaid, or a user who repeatedly mashes "new address" for privacy. Importing a seed across different wallet software is the other classic trigger, since implementations differ in how far they scan and some older tools used tighter limits. If you run any kind of automated address generation from an xpub, assume you will exceed 20-address gaps eventually and plan recovery accordingly.

Working with it safely

If funds seem missing after a restore, do not panic and do not touch the seed: raise the gap limit in a recovery tool and rescan, or rescan with an output descriptor that specifies the exact derivation range. Wallets built on descriptors handle this most cleanly, since the descriptor records precisely which script type and path to search, eliminating half the guesswork of legacy recovery. For merchant setups, either configure a larger gap limit up front or periodically consolidate so the used-address trail stays contiguous. And when testing a new wallet's recovery — which every sovereign holder should do before trusting it with real value — deliberately include a far-ahead address in the test so you learn your tools' behaviour on your own terms.

Why 20, and not 5 or 500? The number is a deliberate compromise baked into BIP44's account-discovery algorithm. Scanning costs real resources — every candidate address means database or network lookups against the chain's entire history — and a limit too generous would make wallet restoration crawl, especially on lightweight clients querying remote servers. A limit too tight, meanwhile, would strand funds behind ordinary usage patterns. Twenty consecutive empties was judged wide enough that normal wallets never hit it and narrow enough that recovery stays fast. The same logic explains why the limit applies per chain and per account: discovery walks account 0, then account 1, stopping at the first account with no history at all, so the gap-limit trade-off repeats at every level of the hierarchy.

Gap-limit behavior is defined alongside the account-discovery process in HD wallet accounts, and understanding it is part of disciplined self-custody for anyone who values BIP32 HD wallet sovereignty.