Frequently questions and answers
Introduction
This section lists the most frequent questions reported on the Hathor contact channels.
Full node (core)
1. How can I run a full node in a private VPC on AWS?
The full node will need outbound access to other nodes (usually allowed by default) and it will benefit from having inbound rules to enable other nodes to try to connect to it. But, be careful to not expose all ports (restrict inbound rules to only the port that the node will listen with --listen tcp:<PORT>
).
Another detail is that you don't need to expose port 40403 of your full node to connect to the network. However, it is generally good practice to expose a port that will allow more nodes to connect to your nodes and thus reducing the overall latency for receiving transactions/blocks. Also, it doesn't have to be port 40403, you can use any port: --listen tcp:50504
will use port 50504.
You will usually need at least one inbound rule to expose your full node in a private VPC on AWS. This rule must allow IPv4 access to port 40403 for any source (0.0.0.0/0), assuming you are using -listen tcp:40403
on your node.
Headless wallet
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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 addresses per wallet; in practice this is infinite.
8. 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.
Ledger hardware wallet
9. How do I store HTR on a ledger?
Hathor can be stored on Ledger Nano. A walkthrough of how to do this is available in the article Hathor is available in Ledger.
10. How can I withdraw my NFTs from the Hathor Ledger wallet?
A detailed tutorial on how to store custom tokens and NFTs in Ledger is available in this video. However, it is important to take into account some particularities and limitations:
- Tokens with emojis (or any non-UTF-8 printable character) are not supported as this could create issues with Ledger and also cause security concerns
- A maximum of 10 custom tokens plus the native HTR token can be sent in a single transaction (this limitation is exclusive to Ledger)
- When sending NFTs the amount shown on Ledger is decimal (1 NFT equals 0.01)
- It is not possible to mint or melt custom tokens or NFTs using Ledger
- Before transferring a token it must be trusted.
- When resetting token signatures it is only possible to reset all tokens at once, not just a single one.
Mining and resources
11. What type of rig should I use for mining HTR?
It is not feasible anymore to mine HTR using neither a CPU nor a GPU. For mining HTR, it is strongly recommended the use of an Application-Specific Integrated Circuit (ASIC). Check the current Hathor hash rate accessing the Explorer graphical tool.
12. How long does Hathor Network need to mine a block?
On average, each block takes 30 seconds to be mined.
13. How can I do PoW for transactions sent from my wallet since I don't have a mining rig?
Transactions sent from Hathor wallets are mined in our public transaction mining service by default. But you could also run your own mining service. More information can be found in the article On the scalability of the public Tx Mining Service.
14. How can I run the chain locally with no nodes and make my own chain from it?
This involves running a private network. All details of how to go through this procedure are available in the RFC-0033: Private Network Guide.
15. Is Hathor compatible with Ethereum Virtual Machine?
No, Hathor is not EVM compatible. There are no plans for an EVM because it needs Turing completeness. Hathor aims to be Turing incomplete to obtain good performance and also for security reasons.
EVMs are also very slow, complex, and expensive. The Hathor architecture can support an EVM but there are more cons than pros when thinking about being Turing-complete.
16. How can I validate an address?
For JavaScript projects, there is the hathor-wallet-lib with some logic to validate addresses. The lib must be added to the project through the command
npm install @hathor/wallet-lib
and the following code snippet can be used:
import walletLib from '@hathor/wallet-lib';
const testnet = new walletLib.Network('testnet');
const mainnet = new walletLib.Network('mainnet');
const testAddress = 'WdaaBTSs5tuh3qSZ4TMxL3sYUsdkh2EDku';
const address = new walletLib.Address(testAddress, { network: testnet });
console.log(address.isValid()); // true
const address2 = new walletLib.Address(testAddress, { network: mainnet });
console.log(address2.isValid()); // false
For direct address validation without the hathor-wallet-lib dependency, you can replicate the Address class's validation method. Basically, this validation involves three steps:
-
- Make sure the address is 25 bytes
-
- Check address checksum
-
- Validate byte version - the first byte corresponds to the mainnet
The third option is to use the full node API for this. When running your own node, you can use the validate_address endpoint.
Scalability and security
17. Why does Hathor have a 200 TPS limit if the DAG is able to handle millions of transactions per second?
Hathor is not actually restricted to a hard TPS limit. The threshold of 200 TPS was achieved by the last stress test and it was the highest stable TPS. Nevertheless, several optimizations have already been identified to get the TPS rate closer to the values from 2K to 10K that has been mentioned in the article On cryptocurrencies scalability and decentralization.
Such an article underscores it is possible to verify 2.700 signatures/second on a thread of a specific processor. Verifying signatures is one of the main CPU bottlenecks of verifying transactions. A transaction could have many signatures though. Hence, by optimizing a node to its fullest and without any protocol changes, it would possible, in theory, to have a TPS in that order of magnitude.
The TPS threshold of around 10K is actually a hardware limitation. Several chains get around that by requiring really beefy hardware for running nodes - like requiring server-grade processors with 64+ cores.
18. Is there a way to scale more than 10K TPS without requiring supernodes to the rest of the network?
Each side of DAG is almost like an independent chain that only uses the main DAG's consensus to reach finality, without barely using any resources. For certain use cases, they might benefit a lot from being implemented as a side DAG, which would "bypass" and not count towards the network limits.
A more detailed explanation about scalability is available in the article On cryptocurrencies scalability and decentralization.
19. Since HTR has no fees, how do Hathor prevent a malicious user transaction spamming the network or running a DDOS attack?
Hathor requires PoW for both transactions and blocks. There is a built-in PoW on the client-side that requires Pow for low-weight transactions like token transfer. This basically means that anyone spamming the network would have to perform PoW for every transaction, while also validating two other transactions with each generated. This PoW for transactions essentially is raising the hash power and throughput of the network making it more secure.
Custom tokens
20. How can I stake HTR tokens?
It is not possible to stake HTR tokens once the Hathor Network uses a Proof-of-Work-based consensus mechanism.
21. Can I configure the decimal places of a custom token?
Currently, Hathor supports only two decimal places for any token.
22. What are the limits of the headless wallet API for minting an NFT via and where can I find them?
Only two NFT attributes have limitations: name - 30 characters, and symbol - 5 characters. The description of these and all other attributes can be found in the wallet headless API documentation.
23. Why is it not possible to register two NFTs with the same symbol in my wallet?
An NFT can have a symbol equal to another one. Tokens created on Hathor can have the same name/symbol and only the UID is unique for any token.
On the other hand, the wallet cannot register two tokens with the same name/symbol for security reasons so you don't get deceived by anyone trying to pretend to send you a fake token.
24. Is the creation of tokens comparable to ERC20-tokens on Ethereum?
Ethereum implements tokens using smart contracts in compliance with its ERC-20 standard. Hathor takes a different approach for building tokens: there are no smart contracts, solidity, or anything of the sort involved. Tokens are built-in in our network, which allows them to operate exactly as HTRs.
Nonetheless, Hathor tokens are compatible with ERC-20 tokens, meaning that all functionality provided by ERC-20 tokens can also be performed on Hathor tokens. In addition, there's also the ability to create (token mint) or destroy tokens (token melt). These are not in the ERC-20 standard, but many ERC-20 tokens implement this additional functionality.
Desktop wallet
25. What should I do for having my NFT approved and displayed on the NFT section of my Hathor Desktop Wallet?
As an NFT is a token like any other, it does not require any prior approval to create.
However, an NFT usually has some digital media associated with it. In this case, for having that digital media displayed on both wallet's NFTs tab and explorer it is needed to submit a request for approval through this form.
26. How can I find my Hathor Desktop Wallet private key?
You cannot. For security reasons, we show the seed only at the time you back your wallet up.
27. How can I change the network in the Hathor Desktop Wallet?
By default, the Desktop wallet connects to the mainnet. To connect to the testnet, follow the steps:
- Click on the Settings icon in the bottom left corner.

- Press the button Change Server.
- Tick the option Select new server.
- Enter the URL https://node1.testnet.hathor.network/v1a/ of the testnet server.
- Inform the PIN.
- Press the button Connect to server.

28. How can I enable notifications for new transactions?
In the desktop wallet, you can set it in the settings. The wallet mobile app does not support such an operation yet, but this feature will be added in the future.
29. What does "Locked" mean in the Desktop wallet under "Total" and "Available"?
Mined blocks need to wait some more blocks to spend the rewards. Then, when a miner mines a block, the reward is locked for 300 blocks. Besides that, the wallet can send an output with a timelock, which basically says that you can't spend a given output until some date and time. Those output values show in your wallet as "Locked".
30. Why does the Desktop Wallet take so long to be ready after I open it and put my pin?
Nowadays it depends on the number of transactions your wallet has and how many addresses you've already used. We have a new wallet service that is in the final development phase that will speed up the wallet load even for millions of transactions. Soon your wallet will load much faster.
31. Why does Desktop Wallet list 20 available addresses?**
The wallet uses the gap limit default value, i.e., 20. Then, it starts with 20 empty (with no transactions associated) addresses to be used in transactions. Although an address can be used indefinitely, every time an empty address is used, a new one is generated. This way the wallet always keeps a sequence of 20 distinct empty addresses in memory.