Wallet Guide
This guide covers setting up and using a Lethean CLI wallet. The CLI wallet is the most complete and tested option, and is what the Docker mining stack uses internally.
Getting Started
Download
Download the latest Lethean CLI binaries from downloads.lthn.io. The package includes:
lethean-chain-node-- the blockchain daemonlethean-wallet-cli-- the command-line wallet
Start the Daemon
The wallet requires a running daemon to synchronise with the network. Open a terminal and start the daemon:
./lethean-chain-node
Wait for the daemon to fully synchronise before using the wallet.
Create a New Wallet
In a second terminal:
./lethean-wallet-cli --generate-new-wallet mywallet.wallet
You will be prompted to set a password. After creation, the wallet displays your receive address (starts with iTHN). Save your seed phrase (26 words) -- it is the only way to recover your wallet if you lose the file or password.
Open an Existing Wallet
./lethean-wallet-cli --wallet-file mywallet.wallet
Enter your password when prompted. The wallet will display your receive address after "Opened wallet."
To close the wallet cleanly, use the exit command. The daemon can be left running.
Checking Your Balance
If you have received funds but they are not showing, resynchronise:
refresh
To see your balance:
balance
To see balances for all assets (LTHN, confidential assets, etc.):
balance raw
Sending LTHN
The transfer command takes a mixin count, destination address, and amount:
transfer <mixin_count> <address> <amount>
- mixin_count: the number of decoy outputs mixed with yours for privacy. Use 15 for standard wallets, 0 for auditable wallets.
- address: the recipient's Lethean address (starts with
iTHNfor standard oriThNfor auditable) - amount: the amount of LTHN to send
Example -- send 10 LTHN:
transfer 15 iTHNUNiuu3VP1yy8xH2y5iQaABKXurdjqZmzFiBiyR4dKG3j6534e9jMriY6SM7PH8NibVwVWW1DWJfQEWnSjS8n3Wgx86pQpY 10
Send to multiple recipients in one transaction:
transfer 15 <address_1> <amount_1> <address_2> <amount_2>
An optional payment_id can be appended at the end for services that require it.
Sending Confidential Assets
To send a confidential asset other than LTHN, prefix the address with the asset ID:
transfer 15 <asset_id>:<address> <amount>
Receiving LTHN
Your receive address is shown when the wallet opens, or at any time with:
address
To generate an integrated address with an embedded payment ID (useful for exchanges or services):
integrated_address
Or with a specific payment ID:
integrated_address <payment_id>
Transaction History
View recent transactions (last 100 by default):
list_recent_transfers
With offset and count:
list_recent_transfers <offset> <count>
Export transaction history to CSV:
export_history
Export recent transfers as JSON:
export_recent_transfers
Restoring a Wallet from Seed
If you have lost your wallet file or password, restore it using your seed phrase.
Start the daemon, then in another terminal:
./lethean-wallet-cli --restore-wallet mywallet.wallet
You will be prompted to create a password, then enter your seed phrase. Current wallets use 26-word seeds; older wallets may have 24 or 25 words.
If your seed phrase has a typo or swapped words, try the Seed Doctor tool:
./lethean-wallet-cli --seed-doctor
Wallet RPC Mode
For automated services, exchanges, and bots, run the wallet in RPC mode:
./lethean-wallet-cli --wallet-file mywallet.wallet --password "" \
--daemon-address 127.0.0.1:36941 \
--rpc-bind-port 36944 --rpc-bind-ip 127.0.0.1
This exposes a JSON-RPC interface for programmatic wallet operations.
PoS Staking
You can stake LTHN directly from the CLI wallet:
./lethean-wallet-cli --wallet-file mywallet.wallet --do-pos-mining
To send staking rewards to a different address:
./lethean-wallet-cli --wallet-file mywallet.wallet --do-pos-mining \
--pos-mining-reward-address <address>
Aliases
Lethean supports on-chain aliases -- human-readable names (like @myname) associated with your wallet address. Instead of sharing a long address, you can register an alias that others can use to find you.
Requirements
- Minimum 6 characters, maximum 25
- Lowercase letters (a-z) and numbers (0-9) only
- Registration cost: 1 LTHN
- Aliases shorter than 6 characters are reserved for the Lethean Core Team
Register via RPC
curl -X POST http://127.0.0.1:36944/json_rpc \
-H 'Content-Type: application/json' \
-d '{
"jsonrpc":"2.0","method":"register_alias",
"params":{
"al":{
"address":"YOUR_iTHN_ADDRESS",
"alias":"myname",
"comment":"My Lethean alias"
},
"authority_key":""
}
}'
Look Up an Alias
# By alias name
curl -X POST http://127.0.0.1:36941/json_rpc \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":"0","method":"get_alias_details","params":{"alias":"myname"}}'
# By address (reverse lookup)
curl -X POST http://127.0.0.1:36941/json_rpc \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":"0","method":"get_alias_by_address","params":{"address":"iTHN..."}}'
Aliases can be used beyond transactions -- they serve as decentralised identifiers for VPN subscriptions, identity, agent federation, and marketplace listings on the Lethean platform.
Auditable Wallets
Standard Lethean wallets are private by default. An auditable wallet allows a third party to view your balances and transactions (useful for public organisations or compliance).
Create an auditable wallet
./lethean-wallet-cli --generate-new-auditable-wallet mywallet.wallet
Auditable wallet addresses start with iThN (standard wallets start with iTHN).
Get the tracking seed
Open the auditable wallet and run:
tracking_seed
Share the tracking seed with anyone who needs to audit the wallet. They can restore a read-only copy using --restore-wallet and entering the tracking seed.
Watch-Only Wallets
A watch-only wallet lets someone view your wallet without spending access:
save_watch_only mywallet_watchonly.wallet mypassword
Command-Line Flags Reference
| Flag | Description |
|---|---|
--wallet-file <file> |
Open an existing wallet |
--generate-new-wallet <file> |
Create a new standard wallet |
--generate-new-auditable-wallet <file> |
Create a new auditable wallet |
--restore-wallet <file> |
Restore from seed phrase or tracking seed |
--password <pass> |
Supply password (skip interactive prompt) |
--daemon-address <host>:<port> |
Connect to a specific daemon |
--offline-mode |
Do not connect to the daemon |
--do-pos-mining |
Enable PoS staking |
--pos-mining-reward-address <addr> |
Send staking rewards elsewhere |
--rpc-bind-port <port> |
Run as RPC server on this port |
--rpc-bind-ip <ip> |
Bind RPC to this IP (default: 127.0.0.1) |
--seed-doctor |
Attempt to recover a broken seed phrase |
--no-refresh |
Do not sync on startup |
--log-level <0-4> |
Set log verbosity |
In-Wallet Commands Reference
| Command | Description |
|---|---|
address |
Show wallet public address |
balance |
Show balance (balance raw for all assets) |
refresh |
Resynchronise transactions and balance |
resync |
Reset and re-synchronise from scratch |
save |
Save wallet state |
exit |
Close the wallet |
help |
Show all available commands |
transfer |
<mixin> <addr> <amount> [payment_id] |
list_recent_transfers |
[offset] [count] -- show recent transactions |
show_seed |
Display 26-word seed recovery phrase |
spendkey |
Display secret spend key |
viewkey |
Display secret view key |
tracking_seed |
Display tracking seed (auditable wallets) |
save_watch_only |
<file> <password> -- export watch-only wallet |
integrated_address |
[payment_id] -- generate integrated address |
show_staking_history |
[days] -- show PoS staking rewards |
export_history |
Export transaction history to CSV |
sweep_below |
<mixin> <address> <amount_limit> -- consolidate small outputs |
Further Reading
- Mining Overview -- How mining works on Lethean
- Block Explorer -- View transactions and blocks