Blockchain Blog

Receive Payments API Update: Address Gap Limits


Recently we’ve encountered interesting edge cases where Receive Payments API V2 users had long runs of unused addresses, which makes funds paid to later addresses not display within the wallet. We’re taking a proactive approach to prevent this from happening, and in this post we’ll explain these changes and their impact on our API users. Users may also have received an email version of this update.

The problem

When you make requests from the Receive V2 API, we create new addresses for you sequentially, ensuring that you don’t give two users the same address. If you request several addresses on behalf of your users without any of them making a payment, this will leave empty gaps between addresses with funds. This is fine, unless this consecutive empty address gap reaches 21 addresses or more.

Most wallet software will only look ahead 20 addresses from the highest index address it can see (due to the BIP 44 standard we are following). 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).

What we’re changing, and what it means for you

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.

Because such wide gaps might simply be the result of a high transaction volume and will resolve themselves over time, we will provide an advanced-user mechanism for you to override the gap limit by adding an optional ‘gap_limit’ parameter you can set to the API call. Please note, this will not increase our wallet software look-ahead window of 20, so funds will run the risk of not showing within the wallet.

Alternatively, if you would prefer having full control over address generation and are willing to take on the responsibility of managing the address gap, you can directly pass an ‘index’ parameter to the ‘receive’ API call, specifying the address index we should derive for you.

How to know if you’re affected

You can call the checkgap API via the following endpoint:{xpub}&key={apikey}

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.

In summary

  • We will begin enforcing the gap limit on August 1st, 2016.
  • Affected users can use the new optional parameters to manage their address gaps.
  • You can find out if you’re affected by the gap limit by using the gap check API.


If you have any questions, don’t hesitate to open a support ticket. You can also check out the API documentation on our site, which will also be updated to reflect these changes.