We currently offer Bitcoin withdrawals and deposits on our website. Blockchain API is used to handle all operations.

Only problem is Blockchain Receive API's 20 address gap limit, as mentioned here: http://bitcoinx.io/news/articles/blockchain-info-updates-receive-payments-api-version-to-address-edge-cases/

Now we get a lot of curious users who click on Bitcoin deposit button and commit to it without actually sending any transaction, which easily build up to 20 addresses. What are some ways of removing this limitation? I have few ideas but they are rather bulky and some require complete re-write of code and replacement of Blockchain API. Can you guys offer any insight and/or advice? How can this problem be solved in elegant and efficient way?

  • I don't think I have a full understanding of your problem, but couldn't you just keep displaying the same address to the user who wishes to deposit until they actually deposit something to that address? Granted, this would take more API calls to check for any transactions that pay to that address.
    – morsecoder
    Commented Aug 17, 2016 at 18:41
  • You should also be able to request more addresses after you use the initial 20, correct?
    – morsecoder
    Commented Aug 17, 2016 at 18:42

2 Answers 2


Yes the gap is an issue with the HD wallet. Blockchain made a blog post about working with this issue. See here: https://blog.blockchain.com/2016/06/15/receive-payments-api-update-address-gap-limits/#more-9024

Let’s say you get paid to the first address, address 1 — the wallet will look ahead 2-21 addresses to see if there are any additional funds or transaction history in those addresses. If it doesn’t find anything, it will stop looking. So, if you get paid to address 22, the wallet software will not see the funds because it stopped at 21. However, if you get paid to address 2, the wallet software will look ahead addresses 3-22, see the funds that were sent to the address 22, and then look an additional 20 ahead (addresses 23 – 43).

Starting from August 1st, 2016, we will respond to API requests that would push you past the 20-address gap limit with an HTTP error, and we will not generate any new addresses for your xpub until we detect a payment that would close the gap below that limit. This ensures that you will never have unreachable funds through the use of Receive Payments API V2, but might lead to not generating addresses when your users request them.

You can call the checkgap API via the following endpoint:


You’ll get a JSON response that looks like:

{ "gap": 1 }

This gap value represents the difference between the index of the most recent address paid to, and the most recently-requested address. If that value is 20 or greater, funds paid to any further addresses created will be hard to access until earlier addresses receive funds.

  • what is the status of this now in May 2019? is there a way to reduce the gap invalidating non paid addresses? maybe some expiration time?
    – Enrique
    Commented Jun 2, 2019 at 4:00
  • 1
    I noticed with this blockchain.info company, most of their old URLs don't work. Like the one you posted to that blog post. (And it's not in the way-back-machine either.)
    – c00000fd
    Commented Jan 25, 2020 at 4:29

Before new API limits happened a proper way to handle Bitcoin payments was

  • Request separate address (public/private key) for each user
  • Store new address in user's account and display public part for transaction
  • Listen to callback from Blockchain.info
  • When callback arrives, check who's address made a payment, how much has been paid, conduct business logic and request a new address for this user.

After new API introduced limits to the total number of requested addresses, it became useless from my point of view. At least I can not see how "reliably" handle payments from multiple user accounts simultaneously.

  • 2
    -1 please focus on answering the question instead of presenting a now obsolete solution and complaining about its obsolescence.
    – Murch
    Commented Jan 3, 2017 at 10:56

Not the answer you're looking for? Browse other questions tagged or ask your own question.