Hathor Network

Integration guide

Use case integration architecture


This article explains the architecture to integrate a use case with Hathor Network. This architecture is the basis upon which businesses will design their use case integration. We will cover:
  • what are the components that comprise the architecture;
  • what consists each component;
  • why the need of such component; and
  • how to implement the component.


  • Business in this context, is an individual or organization that owns a use case.
  • Wallet is the component of a blockchain system that enables the management of funds by end users. From the point of view of the blockchain end users, a wallet is analogous to a bank account, and its implementations are analogous to banking applications, cashiers, and ATMs.

Architecture overview

The following diagram presents the architecture that best suits the majority of use cases:
Credits: icons created by Trevor Dsouza, Ralph Schmitzer, and Maria Kislitsina from the Noun Project.
This architecture comprises five main components:
  • Hathor headless wallet.
  • Hathor Network.
  • Hathor full node.
  • The use case's system.
  • The integration environment.
In the following sections, we discuss each of these components.

Hathor headless wallet

A headless wallet is a service that implements a wallet, and whose interface is an API. Hathor headless wallet is the official headless wallet of Hathor.

Why do businesses need to run Hathor headless wallet?

It is through a wallet implementation that a business interacts with a blockchain. And, for security reasons, the business itself needs to run it.
This is because a wallet implementation stores the private keys of the business, and anyone with the private keys associated with a wallet has access to its funds.
For most use cases, the best choice of wallet implementation is Hathor headless wallet. However, some use cases may benefit from other choices. For example, implementing their wallet directly within their system, using Hathor wallet library or contracting a custody solution to guard their wallet.

How to operate the Hathor headless wallet?

The following article provides a journey to assist developers in operating Hathor headless wallet: Hathor headless wallet pathway.

Hathor Network

Hathor Network is the official public blockchain network that implements Hathor.
Hathor Network has a peer-to-peer architecture (like any authentic blockchain network). Thus, wallet requests are not received by a central server but rather by a peer from the network, i.e., a full node.

Hathor full node

Hathor full node is the computer system unit that is the primary building block that comprises Hathor Network.

Why do businesses need to run a full node?

There are four reasons businesses need to run their own full nodes rather than rely their wallet requests to a third-party full node — whether public or other businesses' full nodes.
The first reason is security. One of the main advantages of blockchain technology is being trustless. And for a blockchain user, the only way to become 100% trustless is by being a peer on the network. While it is reasonable for personal wallets to trust in a public full node, use cases with hundreds or thousands of users need higher security requirements.
The second and third reasons are performance and availability. Hathor has public full nodes that accept requests from anyone. However, public full nodes are made to serve personal wallets. With the exception of initial tests, they are not suitable for use cases.
Public full nodes have rate limits for the number of requests they can receive from the same client. Thus, the service provided to a use case by a public full node may have throughput limitations or even become unavailable.
The fourth and final reason is robustness. Adding a new full node to the network increases its resilience, distribution, and decentralization levels. With this, the business contributes to maintaining and strengthening Hathor, which benefits itself and all Hathor users.
There is no reward for operating a full node.

How to operate a Hathor full node?

The following article provides a journey to assist developers in operating Hathor full node: Hathor full node pathway.

Use case's system

The use case's system comprises all components of the use case, except for those regarding integration — i.e., Hathor headless wallet, Hathor blockchain, and Hathor full node. Some of these components may be modules that the business will develop specifically for the use case, and others may already exist to attend to purposes beyond the scope of the use case.

Integration environment

Besides obviously the use case's system, the integration environment comprises two other components: Hathor headless wallet and Hathor full node. To integrate a use case, a business needs to take care of the integration environment, i.e., infrastructure, configuration, and support services to run Hathor headless wallet and Hathor full node.

Configuration of the integration environment

Within the integration environment, the only component that needs to be publicly accessible is Hathor full node. Even so, only the TCP port assigned for the peer-to-peer connection with Hathor Network needs to be open to the internet. As for its web API, It should not be publicly accessible.
Similarly, Hathor headless wallet web API should not be publicly accessible. The only possible exception would be a deliberate design decision to fulfill some specific uncommon requirement of a use case.

Key takeaway

For the majority of use cases, the best integration architecture is:
  • Run Hathor headless wallet and connect it with the use case's system and Hathor full node.
  • Run Hathor full node and connect it with Hathor Network.