TABLE OF CONTENTS

What is Gap Limit ?

  • Bitcoin wallets automatically create a new receiving address for each payment. This process usually works seamlessly.
  • However, wallets have a limit to how many unused addresses they can “look ahead” to check for incoming payments. This limit is called the Gap Limit.
  • If too many addresses go unused (for example, if orders aren’t paid or if many addresses are created for testing purposes), your wallet might temporarily stop noticing new payments.
  • In such cases, you might see the payment on the blockchain network but not in your wallet.

For more technical details, it is recommended to read this article.


Understanding Gap Limit Error Messages

1. Gap Limit Error: You are creating too many addresses/orders with no real payments

What it Means:

  • The system has detected several addresses or orders that didn’t receive payments.
  • This can happen if:
    • Many test orders were created, or
    • Customers repeatedly triggered orders automatically.

2. Gap Limit Error: Unavailable gap limit funds

What it Means:

  • This is usually a temporary issue that occurs if Blockonomics servers experience connectivity problems or momentarily lack funds to perform a small network transaction for automatic gap limit handling.

3. Gap Limit Exceeded

What it Means:

  • This is often a temporary issue and usually resolves on its own. If it continues, follow the troubleshooting steps below.


How to fix these Errors ?

  • Increase Your Gap Limit

    • Use the Gap Limit utility to raise the gap limit for your xpub in Blockonomics (e.g., to 200).

    • Set the same Gap Limit in your wallet.

      • Electrum wallet supports custom Gap Limits and is recommended if you handle many orders Change Gap Limit in Electrum

      • For other wallets, check their documentation to see if Gap Limit adjustment is possible.

    • Important: Your wallet and Blockonomics must use the same Gap Limit value. If they don’t match, some payments may not show up in your wallet.

  • Remove your existing wallet and add a new wallet in the wallets section. After adding it, configure this new wallet to accept payments for your store.
  • Add a CAPTCHA or similar protection on your checkout page to stop bots or users from creating too many unpaid orders.
  • If your website has large order volume, we recommend to switch to electrum wallet with 200 Gap Limit.
  • Keep a positive credit balance (recommended: 0.0005 BTC). You can deposit credit balance here.


What are Gap Limit fill-up Transactions ?

When they happen:

  • When your store has around 20 consecutive unpaid or unused addresses (for example, from unpaid or test orders), your wallet reaches its Gap Limit.
  • To prevent your wallet from missing future payments, Blockonomics automatically sends a small transaction to the 20th address.
  • This keeps your wallet in sync and ensures future payments are not missed. 

About the Charges:

  • These are not additional fees charged by Blockonomics.
  • The small deduction only covers the Bitcoin network transaction fee required to confirm the fill-up transaction.
  • To ensure these automated transactions work smoothly, we recommend maintaining at least 0.0005 BTC in your Blockonomics credit balance.

Is This Really Necessary?:

  • Yes, Since Blockonomics sends all payments directly to your wallet (without holding any funds), your wallet must always stay in sync to detect new payments.
  • Gap Limit fill-up transactions are small network transactions that help maintain this sync when many addresses go unused.
  • These are not extra fees from Blockonomics, just the normal Bitcoin network fee needed to keep your wallet functioning smoothly.