Skip to main content

FAQ: headless wallet

1. What should I do when wallet headless reaches the gap limit for public nodes?

First of all, it is strongly recommended that use cases run their own full node so there is no risk in reaching the public full nodes limits, such as the gap limit.

Rather than using the gap limit default value, there is the option to run a custom full node with configs that allow a larger gap limit value.

Basically, the variable WS_MAX_SUBS_ADDRS_EMPTY must be changed to hold the new gap limit value. More details about how to run a full node with custom configurations are available in the Custom Configuration section of the Full Node guide.

2. Why should I use --wallet-index parameter when running the wallet headless with a local full node?

This --wallet-index parameter creates an index of transactions by address. This index is required for some full node APIs and the headless wallet to work properly.

Running a full node with no --wallet-index parameter causes the wallet headless to throw an HTTP 503 (Service Unavailable) error.

3. I am running the wallet headless and the full node connecting to the testnet. Why am I getting the following error after making a post request to the endpoint wallet/simple-send-tx?

Error returned by wallet/simple-send-tx endpoint.

This error usually happens when you use parents that do not belong to the network. A common reason for such a situation is to connect the full node with the testnet and the wallet headless is configured to use the mainnet (or vice versa).

Check if the txMiningURL parameter of the config.js file of the wallet headless holds the correct address of the mining service. Another option is just to remove such a parameter from the file. In this case, the headless wallet will select the mining service correctly depending on the network you are using.

4. How can I get a new address using the mark_as_used parameter of the headless wallet?

When you request an address to the headless wallet, it returns a new empty address to be used. The mark_as_used parameter is an artificial way to say that this address is used and the next time you request an address this one shouldn't be returned.

By requesting the /wallet/address endpoint twice you will get in return the same address. However, by requesting the /wallet/address?mark_as_used=true endpoint twice, it will return two different addresses.

It is important to note that the mark_as_used parameter causes the generated addresses to be stored exclusively in memory in case they have not been used yet. Consequently, an eventual restart of the headless wallet will cause all this information to be lost.

5. Is there a request limit on the headless wallet when connected to the public nodes?

The request limit is in the full node API. The limits are per IP and global, so you can be limited even if you don't use it a lot or if there is a lot of use of public APIs. If you are developing a project, we highly recommend running a local full node.

6. Is there any limit on how many wallet addresses I can create?

Using the headless wallet there is no limit. But you must be aware of the gap limit. It could prevent you from detecting deposits on your wallet. More information about the Gap Limit is available in the Fundamentals section.


In theory, we have a hard limit of 2312{31} addresses per wallet; in practice this is infinite.

7. How can I get information (e.g. balance) of a specific wallet address?

You can use two different endpoints for running such an operation: /wallet/address-info and /wallet/utxo-filter. You can learn more about them in the Wallet Headless API documentation.