Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Accounts

Heat uses named accounts as its primary identity abstraction. Each account maps to an encrypted private key stored locally.

Overview

Accounts live in ~/.heat/accounts/ as TOML files. Keys live in ~/.heat/keys/ as encrypted keystore JSON files.

When you create an account, Heat:

  1. encrypts the key locally with your password (scrypt + AES-128-CTR)
  2. derives and caches the public identity for that account type
  3. stores account metadata in a TOML file, including how to find the password later when configured

The cached address means read-only commands (balance, positions, price) do not require your password.

Commands

List accounts

heat accounts list

Shows all accounts with their type. The default account is marked with *.

Show account details

heat accounts get myaccount

Displays name, type, key reference, address, default network, and stored password source metadata when present.

Create an account

Recommended: let Heat generate both the key and password, then persist the password locally.

heat accounts create myaccount --generate --persist-password ~/.heat/secrets/myaccount.password

You can also create from existing key material:

heat accounts create myaccount --key-file /path/to/private-key.txt --persist-password ~/.heat/secrets/myaccount.password

Arguments:

  • name — a short name for this account (used in --account and heat accounts use)
  • --generate — generate a fresh local key
  • --key — your private key as 0x-prefixed hex (32 bytes / 64 hex characters)
  • --key-file — path to a file containing the private key
  • --password-file — path to a file containing the encryption password
  • --password-env — name of an environment variable containing the password
  • --persist-password — path where Heat should store the password with secure file permissions

For safe non-interactive setup, you must provide one of:

  • --password-file
  • --password-env
  • --persist-password

If you provide --persist-password without --password-file or --password-env, Heat generates a strong password and stores it at that path.

Import an existing keystore

heat accounts import myaccount --keystore /path/to/keystore.json

Imports a standard Ethereum V3 keystore file. The keystore is copied into ~/.heat/keys/. The original file is not modified.

If you want Heat to remember how to unlock that keystore later, attach a password source when importing:

heat accounts import myaccount \
  --keystore /path/to/keystore.json \
  --password-file ~/.wallet-passwords/myaccount.txt

Set the default account

heat accounts use myaccount

Writes the account name to ~/.heat/default-account. This account is used when no --account flag or HEAT_ACCOUNT env var is set.

Remove an account

heat accounts remove myaccount

Removes the account metadata file. The key file in ~/.heat/keys/ is preserved — you must delete it manually if you want to remove the key entirely.

Account resolution

Heat resolves which account to use in this order:

  1. --account <name> flag (highest priority)
  2. HEAT_ACCOUNT environment variable
  3. default_account in ~/.heat/config.toml
  4. ~/.heat/default-account file

If none are set, commands that need an account fail with exit code 3 (auth error).

EVM keystore format

Keys are stored in Ethereum V3 keystore format:

  • KDF: scrypt (n=8192, r=8, p=1)
  • Cipher: AES-128-CTR
  • Compatible with Foundry, MetaMask, geth, and other Ethereum tools

Files are stored at ~/.heat/keys/<name>.json.

Password handling

Heat encrypts keys locally and can remember how to find the decryption password later.

Preferred setup:

  1. create the account with --persist-password <path>
  2. let Heat store that path in the account metadata
  3. use the account normally without re-specifying password flags on every command

Password resolution for signing commands is:

  1. account password_file metadata, if present
  2. account password_env metadata, if present
  3. HEAT_PASSWORD environment variable (fallback)

That means this is the best automation flow:

heat accounts create trader --generate --persist-password ~/.heat/secrets/trader.password
heat accounts use trader
heat hl buy BTC 0.001 --price 95000 --dry-run

You can still use env-based password management if needed:

export HEAT_PASSWORD="your-password"
heat hl buy BTC 0.001 --price 95000 --yes

Protocol-specific configuration

Accounts can store per-protocol settings in the [protocols] section of their TOML file. For example, Polymarket requires a signature type:

# ~/.heat/accounts/pm-trading.toml
name = "pm-trading"
type = "evm-local"
key_name = "pm-trading"
address = "0x..."
 
[protocols.polymarket]
signature_type = "EOA"

See Polymarket docs for details on signature types.

Directory structure

~/.heat/
  config.toml            # global config
  default-account        # name of the default account
  accounts/
    myaccount.toml       # account metadata
  keys/
    myaccount.json       # V3 encrypted keystore