Bitcoin — What is Gap limit ?

If you are using a bitcoin wallet you are most likely using an HD (Hierarchical Deterministic) wallet, which is an upgrade over the wallets…

If you are using a bitcoin wallet you are most likely using an HD (Hierarchical Deterministic) wallet, which is an upgrade over the wallets of the past. HD wallets simply generate addresses and private keys based off of a master seed which can be backed up and used to restore the same wallet in other software or on another device. Sometimes, however, when you are using an HD wallet to accept bitcoin from customers, the funds that you receive may not appear. You can see your money in a block explorer, but not in your wallet! What is happening? Most likely you are experiencing the gap limit problem.

Missing funds ? You have a gap limit !

This means you ended with more than 20 consecutive unused addresses in your bitcoin wallet. This could have have happened due to various reasons:

  • You generated more than 20 receiving addresses for testing, that didn’t receive any funds
  • Generated 20 orders in succession on your website, that didn’t get paid

Bitcoin gap limit and account discovery was introduced in BIP44. In a nutshell here is what happens when you import/recover an HD wallet:

  • Seed/Master private key given as input
  • Start account discovery to generate private keys upto gap limit
  • Discover funds on blockchain in private keys found

Basically, if you keep using the same wallet, it could keep track of your current address index. But if your recover your wallet from seed/import the seed into another compatible wallet, it doesn’t know where to stop looking for funds and it cannot traverse an infinite tree

So what can you do ?

Scan addresses feature in copay wallet
  • Scan addresses for funds : Most of times, you haven’t actually crossed the gap limit; wallet just hasn’t looked ahead enough. You can force the wallet to scan addresses. Ledger wallet has a similar feature Reset Application Data that will rediscover your wallet funds
  • Increase gap limit: Electrum allows to set custom gap limit. Warning: This can break compatibility when you attempt to recover your funds
  • Manually send funds to fill gap limit: For this you can use tools like hd-wallet-address / blockpath that will show you addresses according to derivation path. You can send small amount fund like 0.00001 BTC at location where you find consecutive number of unused addresses.
  • Limit receiving address generation : Blockchain info APIv2 will stop generating new receiving address after they hit gap limit. This helps merchants to avoid situation where they got the order paid, but didn’t find the funds in the wallet
  • Auto gap limit fix: Merchant services like blockonomics will automatically send small amount of BTC to the gap limit address. This process is transparent to the merchant who can just keep calling the new address API

If you own private keys of your wallet, no need to worry! It may just take a little sherlock style work to find them :D