Basic Information

Why am I getting gap limit fillup TX?

These transactions occur when you have consecutive 20 unpaid orders. To prevent your HD wallet from not discovering your future payments, blockonomics will send a small TX to the 20th address to keep your payments going. For more technical details, it is recommended to read this article  

I get the following error message, what to do ?

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

This means that system has detected bot like activity and you are creating too many orders for which system cannot do auto gap limit fillup. You can do any of the following to fix this:

  • Make sure you have positive credit balance. You can deposit credit balance here. It is good to have atleast 0.0005BTC
  • Remove existing xpub and add new one in address watcher. Set your callback URL again after this
  • Make sure you website is using some kind of captcha to stop customers doing automatic orders
  • If your website has large order volume, please switch to electrum wallet with 200 gap limit 

2. Gap Limit Error: Unavailable gap limit funds

These are temporary error you got when sometimes Blockonomics server doesn't have funds/has some connection issues.

If you get this only once/twice, you can ignore. If you repeatedly face this, you can any of the following to fix this

3. Gap Limit Exceeded

Most of the times this is a temporary error and you can ignore. Try again a few times and it will start working. If you are still having problems - Remove existing xpub and add new one in address watcher. Set your callback URL again after this.

Why are these charge present in account?

Please note that these are not any extra charges from Blockonomics. The charge reflects the amount of transaction fee needed to confirm the TX on the bitcoin network. In period of high congestion, these fee will increase and during days of low activity, they will decrease. You can use this utility to view the current state of the bitcoin network. You are  recommended to have minimum balance like 0.0005BTC in your  Blockonomics credit balance for this

This seems complex. Is it necessary?

Please note that Blockonomics is not holding any of your funds and sends 100% of your BTC payments directly to your wallet. This means financial independence and security for you. A small price is gap limit tx, that is required sometimes when you have lots of unpaid orders. Without these transactions, your wallet will have problems discovering new payments that you receive.

Using Electrum to increase Gap Limit


  1. Switch to electrum wallet to receive your merchant payments. If you are already using electrum, you can goto Step 2
    i. Download Electrum wallet and get its XPUB (extended public key)
    ii. Copy your existing HTTP Callback URL from Merchants and keep it safely
    iii. Delete your existing wallet xpub from Address Watcher and add the electrum XPUB
    iv. Goto Merchants > Settings and Paste back the HTTP Callback URL you copied earlier and Save Changes

  2. Set Gap Limit in Electrum Console. Use the following command to set the gap limit (You can use any number between 20-500):

    Using Electrum console to set Gap Limit

  3. (Optional) If you are using Electrum < 4.0 run also the command below to save the change:  
  4. Restart electrum and verify that gap limit has been set properly. If you type following in the console it should print the expected gap limit setting:

  5. Set same Gap Limit in Blockonomics for your XPUB using  this utility

 Setting Gap Limit in Blockonomics