Headless Hathor Wallet API
This wallet is fully controlled through an HTTP API.
License
MIT
About this API
The Hathor Headless Wallet is a server-side wallet designed for system integrations, automated pipelines, and back-end services that need to interact with Hathor Network programmatically. Unlike the desktop and mobile wallets, it has no graphical interface — all wallet operations are performed through this HTTP API.
It is the recommended wallet solution for organizations integrating an external system with Hathor Network, and is also used by DApps that need to programmatically create or manage nano contracts on-chain.
Prerequisites
Before using this API reference, ensure you have:
- A running instance of Hathor Headless Wallet v0.40.0 or later. See the Headless wallet pathway for installation options (Docker or Docker Compose).
- A running Hathor full node that the headless wallet connects to. See the Full node pathway.
- At least one wallet started via the
/startendpoint before calling any wallet-specific endpoints.
Authentication
By default, the headless wallet does not require authentication — it is designed to run in a controlled server environment accessible only to your own services. If you expose it beyond localhost, configure access control at the network or proxy level.
Never expose the headless wallet API directly to the public internet without additional access controls. All API calls that control a wallet are unauthenticated by default.
API scope
This reference covers all operations available through the headless wallet HTTP API, organized into the following categories:
| Category | Description |
|---|---|
| Wallet management | Start, stop, and query wallet state |
| Addresses | Generate and list wallet addresses |
| Balances and history | Query token balances and transaction history |
| Transactions | Create and push transactions to Hathor Network |
| Tokens | Create and manage custom tokens |
| Nano contracts | Deploy blueprints, create contracts, execute methods, and read contract state |
| Atomic swaps | Propose, sign, and complete multi-party atomic swap transactions |
Next steps
- Headless wallet pathway: installation, configuration, and component overview.
- Nano contracts tutorial: step-by-step guide for deploying blueprints and interacting with nano contracts via this API.
- System integration architecture: how the headless wallet fits into a typical integration environment alongside a full node.
- Download OpenAPI spec: import into Postman, Insomnia, or other API tools.