# Heat — One CLI for All of Finance

> One CLI for all of finance — built for humans and AI agents

## Limitations

Heat v0.4.0 is an early release. This page lists known limitations so you can plan accordingly.

:::warning[Early release]
Start with small amounts. Use `--dry-run` liberally. Verify behavior before scaling up. Report issues if you find them.
:::

### Bridging is available, but scoped

Heat now includes LI.FI-backed EVM routing and bridge execution.

Current scope is intentionally narrow:

* supported EVM-focused routing and bridge execution
* best fit for Ethereum, Polygon, Arbitrum, Base, and supported Optimism routes
* not a promise of universal all-chain/all-token support
* not non-EVM execution
* not HyperCore support

Always preview with `--dry-run` first.

### Hyperliquid funding is still external

Heat does not yet include a Hyperliquid deposit or funding flow.
You still need to fund the Hyperliquid account externally, then return to Heat.

### Polymarket deposit flow is still partly external

Heat can fetch Polymarket deposit addresses, but it does not move the funds for you into Polymarket directly.

Use:

* `heat pm bridge deposit`
* fund externally
* `heat pm bridge status`

### Aave scope is phase 1 only

Aave support is intentionally narrow today.

Supported:

* `markets`
* `positions`
* `health`
* `supply`
* `withdraw`

Not supported yet:

* `borrow`
* `repay`
* collateral toggles
* eMode
* rewards

### DefiLlama is read-only market data

DefiLlama integration is read-only — 42 commands across 9 endpoint families (27 free + 15 pro).

Current limitations:

* **Not yet shipped:** ecosystem intelligence, institutions, ETFs, and FDV performance families are planned but require live API validation before inclusion
* **No HTTP-layer integration tests yet** — unit tests cover mapping and URL construction only
* **Pro API key required** for bridges, some yields, some volumes, some coins, dominance, and usage commands
* Upstream API responses are sometimes inconsistent in field types (handled gracefully)

### Local key accounts only

Heat stores encrypted private keys locally in `~/.heat/keys/`. There is no support for:

* Hardware wallets (Ledger, Trezor)
* Remote signers or KMS
* Multisig wallets
* WalletConnect or browser wallet integration

### No TUI or interactive mode

Heat is a non-interactive CLI. There is no terminal UI, no interactive order entry, and no live dashboards. Use piping and scripting for automation.

### Polymarket API key commands

The `heat pm clob api-keys`, `heat pm clob create-api-key`, and `heat pm clob delete-api-key` commands remain limited by an upstream SDK issue. They should not be treated as a production-ready part of the current release.

### No shell completion

Shell tab-completion (bash, zsh, fish) is not yet shipped. You can rely on `--help` at any level:

```bash
heat --help
heat hl --help
heat lifi bridge --help
```

### Single-account per command

Each command operates with a single resolved account. There is no batch mode or multi-account fan-out built into Heat itself. You can script around this:

```bash
for acct in alice bob charlie; do
  heat hl balance --account "$acct" --json
done
```

### Known caveats

* Integration tests are still thinner than the unit-test and mapping-test coverage.
* Hyperliquid funding/deposit flows remain manual.
* Aave is intentionally not full-surface yet.
* LI.FI scope is honest but still deliberately narrow.
* DefiLlama is read-only market data (42 commands, 9 families); some endpoint families not yet shipped pending live API validation; no HTTP-layer integration tests yet.
* Heat does not do interactive password prompts yet. Use `--persist-password`, `--password-file`, `--password-env`, or `HEAT_PASSWORD`.
* All financial amounts are handled as strings/decimals to preserve precision; never as floating point.


## Heat CLI v0.1.0

This page preserves the original narrower release scope before Aave and LI.FI were added to the public release story.

### Supported protocols

#### Hyperliquid

* price queries, perpetual and spot market listings
* account balances, positions, open orders
* buy/sell order placement, order cancellation
* leverage management
* transfers
* real-time trade streaming

#### Polymarket

* market and event browsing
* helper-first trading commands
* approvals, bridge helpers, and CTF operations
* data queries and WebSocket streams

#### Aave V3 (phase 1)

* `markets`
* `positions`
* `health`
* `supply`
* `withdraw`
* Ethereum, Arbitrum, and Base

#### LI.FI

* `chains`
* `tokens`
* `tools`
* `quote`
* `routes`
* `bridge`
* `status`
* supported EVM bridge execution through Heat accounts

### Key features

* **Account-first model** — encrypted V3 keystore (scrypt + AES-128-CTR)
* **Pipe-aware output** — TTY gets pretty output, piped output gets JSON; `--json`, `--quiet`, and `--output ndjson` are available where appropriate
* **Safety-first** — `--dry-run`, TTY confirmation prompts for dangerous writes, `--yes` for automation
* **Shared infrastructure** — unified error model, config layering, semantic exit codes
* **Shared EVM substrate** — common chain/RPC/signer/approval helpers across Aave and LI.FI

### Current boundaries

* Hyperliquid funding remains external/manual
* Polymarket funding remains partly external/manual
* Aave is not full-surface yet (`borrow`/`repay` deferred)
* LI.FI is focused on supported EVM routing/bridging, not non-EVM execution
* Local encrypted keys only; no hardware wallet support yet

### Example commands

```bash
# Hyperliquid
heat hl price ETH

# Polymarket
heat pm markets search "election"

# Aave
heat aave markets --chain ethereum
heat aave supply USDC 1000 --chain arbitrum --account main --dry-run

# LI.FI
heat lifi bridge 100 USDC --from ethereum --to base --account main --dry-run
```


## Heat CLI v0.2.0

Heat v0.2.0 is the first broader multi-protocol release of Heat.

### Supported protocols

#### Hyperliquid

* price queries, perpetual and spot market listings
* account balances, positions, open orders
* buy/sell order placement, order cancellation
* leverage management
* transfers
* real-time trade streaming

#### Polymarket

* market and event browsing
* helper-first trading commands
* approvals, bridge helpers, and CTF operations
* data queries and WebSocket streams

#### Aave V3 (phase 1)

* `markets`
* `positions`
* `health`
* `supply`
* `withdraw`
* Ethereum, Arbitrum, and Base

#### LI.FI

* `chains`
* `tokens`
* `tools`
* `quote`
* `routes`
* `bridge`
* `status`
* supported EVM bridge execution through Heat accounts

### What defines this release

Heat now ships as a practical product around four connected workflow areas:

* **trading** — Hyperliquid and Polymarket
* **lending** — Aave phase 1
* **capital movement** — LI.FI-backed EVM bridging
* **shared execution model** — one account/safety/output contract across protocols

### Shared foundations

* account-first model with encrypted V3 keystore
* pipe-aware output (`pretty`, `json`, `ndjson`, `quiet`)
* safety-first writes with `--dry-run`, TTY confirmation, and `--yes`
* shared EVM substrate for chain/RPC/signer/approval handling
* protocol-first CLI shape with Heat-owned output contracts

### Current boundaries

* Hyperliquid funding remains external/manual
* Polymarket funding remains partly external/manual
* Aave does not include `borrow`/`repay` yet
* LI.FI is focused on supported EVM routing/bridging, not non-EVM execution
* local encrypted keys only; no hardware wallet support yet

### Example commands

```bash
# Hyperliquid
heat hl price ETH

# Polymarket
heat pm markets search "election"

# Aave
heat aave markets --chain ethereum
heat aave supply USDC 1000 --chain arbitrum --account main --dry-run

# LI.FI
heat lifi bridge 100 USDC --from ethereum --to base --account main --dry-run
```


## Heat CLI v0.4.0

Heat v0.4.0 adds DefiLlama as the fifth protocol — a read-only DeFi research and market data layer with 27 free commands and 15 pro commands across 9 families.

### New: DefiLlama

Command: `heat llama` (aliases: `heat defillama`, `heat dl`)

#### Free commands (no API key required)

These 27 commands work against DefiLlama's public API with no authentication:

* **Protocols (3):** `list`, `get`, `tvl`
* **Chains (2):** `list`, `history`
* **Coins (7):** `price`, `historical`, `chart`, `change`, `first`, `block`, `batch-historical`
* **Stablecoins (5):** `list`, `get`, `chains`, `chart`, `prices`
* **Fees (3):** `overview`, `chain`, `protocol`
* **Volumes (5):** `dexs`, `dex`, `options`, `option`, `open-interest`
* **Yields (2):** `pools`, `chart`

#### Pro commands ($300/mo API key)

These 15 commands require a DefiLlama Pro API key. Without one, they fail gracefully with a clear auth error and a hint on how to set the key.

* **Coins (1):** `liquidity`
* **Stablecoins (1):** `dominance`
* **Bridges (5):** `list`, `get`, `volume`, `daystats`, `tx`
* **Volumes (2):** `derivatives`, `derivative`
* **Yields (5):** `pools-old`, `borrow`, `lend-borrow-chart`, `perps`, `lsd`
* **Usage (1):** `usage`

#### API key

Set a Pro API key via `HEAT_DEFILLAMA_API_KEY` or `[protocols.defillama].api_key` in config. Free commands never require it.

#### Design highlights

* Direct REST client in Rust — no JS/Python SDK runtime
* Heat-owned output DTOs — no raw upstream JSON leaks into the CLI contract
* Multi-base-URL routing across DefiLlama's API families (api.llama.fi, coins.llama.fi, stablecoins.llama.fi, bridges.llama.fi, yields.llama.fi)
* Pro key gating with clear error messages
* Flexible upstream data parsing (e.g. timestamps, chainId as string or number)
* POST support for batch endpoints (e.g. `coins batch-historical`)
* Sort validation with explicit errors on unknown values
* 57 unit tests covering mapping, URL construction, and edge cases

### All supported protocols

| Protocol    | Status                       | Since  |
| ----------- | ---------------------------- | ------ |
| Hyperliquid | Supported                    | v0.1.0 |
| Polymarket  | Supported                    | v0.2.0 |
| Aave V3     | Supported (Phase 1)          | v0.2.0 |
| LI.FI       | Supported                    | v0.2.0 |
| DefiLlama   | Supported (27 free / 15 pro) | v0.4.0 |

### Current boundaries

Everything from v0.2.0 still applies, plus:

* DefiLlama is read-only — no write-path commands
* Some endpoint families (ecosystem, institutions, ETFs, FDV) are not yet shipped pending live API validation
* No HTTP-layer integration tests yet (unit tests cover mapping and URL construction)

### Example commands

```bash
# Top protocols by TVL (free)
heat llama protocols list --sort tvl --limit 10

# Protocol deep dive (free)
heat llama protocols get aave

# Token prices (free)
heat llama coins price "coingecko:bitcoin,coingecko:ethereum"

# Stablecoin market (free)
heat llama stablecoins list --sort circulating --limit 5

# Fee landscape (free)
heat llama fees overview --chain Ethereum --sort fees

# DEX volumes (free)
heat llama volumes dexs --chain Ethereum

# Yield pools (free)
heat llama yields pools --sort apy --limit 10

# Bridge overview (pro)
heat llama bridges list --sort volume --limit 10

# Borrow rates (pro)
heat llama yields borrow --chain Ethereum --limit 5

# Machine-readable
heat llama protocols list --json | jq '.protocols[:3]'
```


## Aave

Heat supports a focused Aave V3 phase-1 integration for:

* Ethereum
* Arbitrum
* Base

### What you can do today

```bash
heat aave markets --chain ethereum
heat aave positions --chain arbitrum --account main
heat aave health --chain base --account main
heat aave supply USDC 1000 --chain ethereum --account main --dry-run
heat aave withdraw USDC 500 --chain arbitrum --account main --dry-run
```

### Native ETH support

Heat supports supplying and withdrawing native ETH via Aave's WrappedTokenGatewayV3.
Use `ETH` as the asset symbol:

```bash
# Supply native ETH (wraps to WETH via gateway in one tx, no approval needed)
heat aave supply ETH 0.5 --chain ethereum --account main --dry-run

# Withdraw as native ETH (unwraps from WETH via gateway, approves aWETH automatically)
heat aave withdraw ETH 0.5 --chain ethereum --account main --dry-run
```

* `ETH` means native ETH routed through the WETH Gateway (one transaction).
* `WETH` means the ERC-20 WETH token directly via the Pool (standard approve + supply/withdraw).
* For native ETH withdraw, Heat automatically approves the gateway to spend your aWETH tokens.
* JSON output includes `execution_path` ("native\_gateway" or "erc20") and `gateway_address` for transparency.

### Current scope

Supported now:

* `markets`
* `positions`
* `health`
* `supply` (ERC-20 tokens and native ETH)
* `withdraw` (ERC-20 tokens and native ETH)

Not supported yet:

* `borrow`
* `repay`
* collateral toggles
* eMode
* rewards

### Notes

* Heat resolves contract addresses through Aave's `PoolAddressesProvider` at runtime.
* Use `--dry-run` before any live write.
* For writes, Heat uses your normal Heat account and `heat-evm` signer flow.

### Example

```bash
# Inspect available reserves
heat aave markets --chain ethereum

# Check account health
heat aave health --chain base --account main

# Preview a supply transaction
heat aave supply USDC 1000 --chain arbitrum --account main --dry-run

# Supply native ETH
heat aave supply ETH 1.0 --chain ethereum --account main

# Withdraw as native ETH
heat aave withdraw ETH 0.5 --chain ethereum --account main
```

### Output

* TTY defaults to pretty output
* piped output defaults to JSON
* `-q` / `--quiet` is useful for scalar health-factor output on `health`


## DefiLlama

Heat integrates DefiLlama for read-only DeFi market data — 27 free commands + 15 pro commands across 9 families.

**Command:** `heat llama` (aliases: `heat defillama`, `heat dl`)

### Free commands (no API key needed)

These work out of the box against DefiLlama's public API:

```bash
# Protocol TVL data (3 commands)
heat llama protocols list --sort tvl --limit 10
heat llama protocols get aave
heat llama protocols tvl uniswap

# Chain TVL data (2 commands)
heat llama chains list --sort tvl
heat llama chains history Ethereum --limit 30

# Token prices (7 commands)
heat llama coins price "coingecko:bitcoin,coingecko:ethereum"
heat llama coins historical 1704067200 "coingecko:bitcoin"
heat llama coins chart "coingecko:bitcoin" --period 30d
heat llama coins change "coingecko:bitcoin"
heat llama coins first "coingecko:bitcoin"
heat llama coins block Ethereum 1704067200
heat llama coins batch-historical ./batch.json  # POST body from file

# Stablecoins (5 commands)
heat llama stablecoins list --sort circulating --limit 10
heat llama stablecoins get 1
heat llama stablecoins chains
heat llama stablecoins chart Ethereum
heat llama stablecoins prices

# Fees and revenue (4 commands)
heat llama fees overview --chain Ethereum --sort fees
heat llama fees chain Ethereum
heat llama fees protocol aave
heat llama fees history hyperliquid --data-type dailyFees --limit 30

# Volumes (11 commands)
heat llama volumes dexs --sort volume --limit 10
heat llama volumes dex uniswap
heat llama volumes dex-history uniswap --limit 30
heat llama volumes options --sort volume
heat llama volumes option derive --data-type dailyPremiumVolume
heat llama volumes option-history derive --data-type dailyPremiumVolume --limit 30
heat llama volumes open-interest --sort volume
heat llama volumes open-interest-history --limit 30

# Yields (2 commands)
heat llama yields pools --sort apy --limit 10
heat llama yields chart <pool-id>
```

### Pro commands (require DefiLlama API key)

These require a [DefiLlama Pro](https://defillama.com/pro-api) API key ($300/month). Without a key, they return a clear authentication error.

```bash
# Coins (1 command)
heat llama coins liquidity "coingecko:bitcoin"

# Stablecoins (1 command)
heat llama stablecoins dominance Ethereum

# Bridges (5 commands)
heat llama bridges list --sort volume
heat llama bridges get 1
heat llama bridges volume Ethereum
heat llama bridges daystats 1704067200 Ethereum
heat llama bridges tx 1

# Volumes (3 pro commands)
heat llama volumes derivatives --sort volume
heat llama volumes derivative hyperliquid
heat llama volumes derivative-history hyperliquid --limit 30

# Yields (5 commands)
heat llama yields pools-old
heat llama yields borrow --sort apy
heat llama yields lend-borrow-chart <pool-id>
heat llama yields perps --sort open_interest
heat llama yields lsd --sort apy

# Usage analytics (1 command)
heat llama usage
```

### Setting your API key

```bash
# Via environment variable
export HEAT_DEFILLAMA_API_KEY=your-key

# Or in Heat config under [protocols.defillama]
# api_key = "your-key"
```

### Command scope

| Family          | Free                                                                                                          | Pro                                                        | Total  |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------ |
| **Protocols**   | `list`, `get`, `tvl`                                                                                          | —                                                          | 3      |
| **Chains**      | `list`, `history`                                                                                             | —                                                          | 2      |
| **Coins**       | `price`, `historical`, `chart`, `change`, `first`, `block`, `batch-historical`                                | `liquidity`                                                | 8      |
| **Stablecoins** | `list`, `get`, `chains`, `chart`, `prices`                                                                    | `dominance`                                                | 6      |
| **Bridges**     | —                                                                                                             | `list`, `get`, `volume`, `daystats`, `tx`                  | 5      |
| **Fees**        | `overview`, `chain`, `protocol`, `history`                                                                    | —                                                          | 4      |
| **Volumes**     | `dexs`, `dex`, `dex-history`, `options`, `option`, `option-history`, `open-interest`, `open-interest-history` | `derivatives`, `derivative`, `derivative-history`          | 11     |
| **Yields**      | `pools`, `chart`                                                                                              | `pools-old`, `borrow`, `lend-borrow-chart`, `perps`, `lsd` | 7      |
| **Usage**       | —                                                                                                             | *(top-level)*                                              | 1      |
|                 | **32 free**                                                                                                   | **16 pro**                                                 | **48** |

All commands are read-only and do not require a signer or account.

### Notes

* **Yields** commands hit `yields.llama.fi` instead of the main API base URL.
* **`coins batch-historical`** uses a POST request (accepts many tokens at once).
* **`fees history`** exposes DefiLlama's `totalDataChart` timeseries from `overview/fees/{target}` and supports `--data-type dailyFees|dailyRevenue|dailyHoldersRevenue`.
* **`volumes dex-history`**, **`option-history`**, **`derivative-history`**, and **`open-interest-history`** expose timeseries data from DefiLlama summary/overview endpoints.
* **`volumes option`** and **`option-history`** support `--data-type dailyPremiumVolume|dailyNotionalVolume`.
* **Pro commands** use `pro-api.llama.fi` as their base URL when a key is set.

### Output

All commands support Heat's standard output modes:

```bash
# Pretty table (TTY default)
heat llama protocols list

# JSON (piped default, or explicit)
heat llama protocols list --json | jq '.protocols[:3]'

# Quiet — scalar output only (where supported)
TVL=$(heat llama protocols tvl aave -q)
```

### Sorting and filtering

List commands support `--sort` and `--limit`. Protocol lists also support `--category` and `--chain` filters.

```bash
heat llama protocols list --category Lending --chain Ethereum --sort tvl --limit 5
heat llama stablecoins list --sort name
heat llama fees overview --sort change_1d
heat llama yields pools --sort tvl --limit 20
```


## Hyperliquid Onboarding

This guide explains how to get from a fresh Heat install to your first safe Hyperliquid command.

Heat uses your named Heat account as the signing wallet for Hyperliquid. There is no separate Hyperliquid wallet command tree.

:::warning[Funding today is manual]
Heat does **not** yet include a built-in bridge or deposit flow for Hyperliquid. For now, humans must fund the account externally, then return to Heat to inspect balances and trade.
:::

### What you need

* a Heat account with an EVM private key
* a password available to Heat for signing commands
* funds already available on Hyperliquid for that address

Read-only market commands do not need an account. Trading and account commands do.

### 1. Create or import a Heat account

Recommended: generate a fresh local account:

```bash
heat accounts create trading --generate --persist-password ~/.heat/secrets/trading.password
```

Or create from an existing EVM private key:

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

Or import an existing Ethereum V3 keystore:

```bash
heat accounts import trading --keystore /path/to/keystore.json
```

Set it as the default account:

```bash
heat accounts use trading
```

Show the account and copy the address:

```bash
heat accounts get trading
```

That address is the one you should use for Hyperliquid account funding.

### 2. Choose network

Heat supports:

* `mainnet` — live trading
* `testnet` — paper trading

Examples:

```bash
heat hl price BTC
heat hl price BTC --network testnet
```

Unknown network values are rejected. Heat will not silently fall back to mainnet.

### 3. Fund the account externally

Heat does not yet perform Hyperliquid deposits or bridging for you.

For now, the correct human flow is:

1. get your Heat account address with `heat accounts get <name>`
2. open your external funding path for Hyperliquid
3. deposit or bridge funds to that address outside Heat
4. return to Heat and verify with `heat hl balance`

### Agent instruction: how to ask for funding

If an agent sees that Hyperliquid balance is empty, it should not invent a deposit command.
Instead it should ask the human explicitly.

Recommended wording:

> Your Heat account is configured, but Heat does not yet support Hyperliquid funding inside the CLI. Please fund the Hyperliquid account for address `<ADDRESS>` externally, then tell me when to continue. After that I can verify balance, inspect markets, and place dry-run or live orders.

Recommended agent flow:

1. inspect account address
2. tell the human the exact address
3. ask them to fund externally
4. wait for confirmation
5. run `heat hl balance`
6. only then suggest trading commands

### 4. Verify the account after funding

```bash
heat hl balance
heat hl positions
heat hl orders
```

For read-only inspection of another address:

```bash
heat hl balance --address 0x...
heat hl positions --address 0x...
heat hl orders --address 0x...
```

### 5. Learn the market before trading

Start with read-only commands:

```bash
heat hl price BTC
heat hl perps
heat hl spot
```

These are the best first commands for humans and agents.

### 6. Preview before trading

Use `--dry-run` first on dangerous commands.

```bash
heat hl buy ETH 0.1 --price 3500 --dry-run
heat hl sell BTC 0.01 --dry-run
```

Dangerous Hyperliquid commands include:

* `buy`
* `sell`
* `cancel`
* `leverage set`
* `send`

In a terminal, Heat asks for confirmation. In non-TTY mode, scripts and agents must pass `--yes`.

### 7. Place and manage trades

```bash
# limit order
heat hl buy ETH 0.1 --price 3500

# market order
heat hl buy ETH 0.1

# inspect open orders
heat hl orders

# cancel one order
heat hl cancel ETH --oid 12345

# cancel all BTC orders
heat hl cancel BTC --all
```

### 8. Leverage and transfers

Show leverage for open positions:

```bash
heat hl leverage show
```

Set leverage:

```bash
heat hl leverage set BTC 10
heat hl leverage set ETH 5 --isolated
```

Send assets:

```bash
heat hl send 0xDESTINATION 100
heat hl send 0xDESTINATION 50 --token PURR
```

### 9. Streaming for agents

Use NDJSON for continuous machine-readable output:

```bash
heat hl stream trades BTC --output ndjson
```

This is the best starting stream for automation.

### Minimal onboarding checklist

```bash
heat accounts create trading --generate --persist-password ~/.heat/secrets/trading.password
heat accounts use trading
heat accounts get trading
# fund externally, then continue
heat hl balance
heat hl price BTC
heat hl buy ETH 0.1 --price 3500 --dry-run
```

### Command map

#### Best first commands

* `heat hl price`
* `heat hl perps`
* `heat hl balance`
* `heat hl positions`
* `heat hl buy --dry-run`
* `heat hl orders`
* `heat hl cancel`

#### When to use testnet

Use `--network testnet` when:

* you are validating agent behavior
* you want paper trading
* you want to test automation before using real funds


## Hyperliquid

All Hyperliquid commands live under `heat hl`.

Hyperliquid is currently the simpler protocol in Heat: your Heat account address is the address you use for Hyperliquid reads and writes.

For the recommended first-time flow, start with [Hyperliquid Onboarding](/protocols/hyperliquid-onboarding).

:::info[Network selection]
Hyperliquid supports two networks. Use `--network testnet` for paper trading. Unknown network values are rejected to prevent silent mainnet fallback.
:::

### What needs an account

Read-only market commands do not need a signing account:

* `price`
* `perps`
* `spot`

Account and trading commands do:

* `balance`
* `positions`
* `orders`
* `buy`
* `sell`
* `cancel`
* `leverage`
* `send`
* some user-specific streams

### Funding

:::warning[Manual for now]
Heat does not yet include a Hyperliquid deposit or bridging command. Humans must fund the Hyperliquid account externally, then return to Heat to verify balances and trade.
:::

Use `heat accounts get <name>` to retrieve the account address you need to fund.

### Network selection

| Network | Flag                | Description        |
| ------- | ------------------- | ------------------ |
| Mainnet | (default)           | Production trading |
| Testnet | `--network testnet` | Paper trading      |

```bash
heat hl price BTC --network testnet
```

### Best first commands

```bash
heat hl price BTC
heat hl perps
heat hl balance
heat hl buy ETH 0.1 --price 3500 --dry-run
```

### Commands

#### price

Show the mid price for an asset.

```bash
heat hl price BTC
heat hl price ETH
heat hl price PURR/USDC
```

Quiet mode emits just the number:

```bash
PRICE=$(heat hl price BTC -q)
```

#### perps

List perpetual markets.

```bash
heat hl perps
```

Output includes name, index, size decimals, and max leverage.

Filter by HIP-3 DEX:

```bash
heat hl perps --dex <dex_name>
```

#### spot

List spot markets.

```bash
heat hl spot
```

Output includes name, index, base token, and quote token.

#### balance

Show account balances.

```bash
heat hl balance
heat hl balance --address 0x...
```

In pretty mode, Heat displays balances per coin. Quiet mode emits the account value.

#### positions

Show open perpetual positions.

```bash
heat hl positions
heat hl positions --address 0x...
```

#### orders

Show open orders.

```bash
heat hl orders
heat hl orders --address 0x...
```

#### buy

Place a buy order. Requires an account.

```bash
# limit order
heat hl buy ETH 0.5 --price 3500

# market order
heat hl buy ETH 0.5

# custom time in force
heat hl buy ETH 0.5 --price 3500 --tif ioc

# reduce-only
heat hl buy ETH 0.5 --price 3500 --reduce-only
```

Market orders use a small internal slippage buffer from the mid price.

Preview without executing:

```bash
heat hl buy ETH 0.5 --price 3500 --dry-run
```

#### sell

Place a sell order.

```bash
heat hl sell BTC 0.01 --price 100000
heat hl sell BTC 0.01 --dry-run
```

#### cancel

Cancel orders.

```bash
heat hl cancel BTC --oid 12345
heat hl cancel BTC --all
heat hl cancel --all
```

#### leverage

View or set leverage.

```bash
heat hl leverage show
heat hl leverage set BTC 10
heat hl leverage set ETH 5 --isolated
```

#### send

Send USDC or spot tokens.

```bash
heat hl send 0xDEST... 100
heat hl send 0xDEST... 50 --token PURR
```

#### stream trades

Stream real-time trades.

```bash
heat hl stream trades BTC
heat hl stream trades ETH --output ndjson | jq -r '.px'
```

The connection auto-reconnects. Diagnostics go to stderr.

:::warning[Dangerous commands]
`buy`, `sell`, `cancel`, `leverage set`, and `send` are dangerous commands. They prompt in a terminal and require `--yes` in non-TTY mode. Use `--dry-run` first.
:::


## LI.FI

Heat uses LI.FI as its EVM routing and bridging layer.

Current publishable scope focuses on supported EVM flows across:

* Ethereum
* Polygon
* Arbitrum
* Base
* Optimism where route support is available

### What you can do today

```bash
heat lifi chains
heat lifi tokens --chain ethereum
heat lifi tools
heat lifi quote --from-chain ethereum --to-chain arbitrum --from-token USDC --to-token USDC --amount 1000000 --from-address 0x...
heat lifi routes --from-chain ethereum --to-chain base --from-token USDC --to-token USDC --amount 1000000 --from-address 0x...
heat lifi bridge 100 USDC --from ethereum --to arbitrum --account main --dry-run
heat lifi status --tx-hash 0x... --from-chain ethereum --to-chain arbitrum --bridge stargate
```

### Current scope

Supported now:

* `chains`
* `tokens`
* `tools`
* `quote`
* `routes`
* `bridge`
* `status`

Current focus:

* supported EVM → EVM route execution
* Heat account / signer integration
* explicit approval handling
* dry-run previews and confirmations

Not the current promise:

* non-EVM execution
* universal all-chain/all-token support
* HyperCore flows

### Safety

`heat lifi bridge` is a real write path.

Use:

* `--dry-run` to preview route details first
* `--yes` only in automation when you fully understand the route
* small amounts first while validating your environment

### Example

```bash
# Preview a bridge first
heat lifi bridge 100 USDC --from ethereum --to base --account main --dry-run

# Execute when ready
heat lifi bridge 100 USDC --from ethereum --to base --account main
```


## Polymarket Onboarding

This guide explains the correct Polymarket setup flow in Heat for both humans and agents.

Polymarket is more complex than Hyperliquid because the signer address and the effective Polymarket wallet may differ.

### The important model

Heat reuses your Heat EVM account for Polymarket.

There are two address concepts:

* **EOA address** — the underlying signer from your Heat account
* **Polymarket wallet address** — the effective funder / trading wallet used by Polymarket

For some signature types, these are different addresses.

### Signature types

Heat currently supports:

* `proxy`
* `eoa`
* `gnosis-safe`

Current precedence is:

1. `--sig-type`
2. `account.protocols.polymarket.signature_type`
3. default `proxy`

:::info[Current default]
Heat currently defaults Polymarket to `proxy`.
That matches the reference Polymarket CLI setup flow and the SDK's automatic funder derivation model.
:::

### What the official Polymarket tooling does

From the official CLI and SDK:

* wallet setup creates or imports an EOA signer
* proxy or safe wallet addresses are derived from that signer address
* deposits are sent to the effective Polymarket wallet
* approvals are required before trading
* the SDK authenticates the CLOB client using the signer plus signature type

That means the right mental model is:

> create Heat account → derive effective Polymarket wallet → deposit funds → set approvals → trade

### 1. Create or import a Heat account

```bash
heat accounts create trading --generate --persist-password ~/.heat/secrets/trading.password
heat accounts use trading
heat accounts get trading
```

This is local account setup only. It does **not** call Polygon RPC and does **not** send any on-chain transaction.

### 2. Understand what address Polymarket will use

Heat signs with your Heat EVM key, but the effective Polymarket wallet depends on signature type:

* `eoa` → use the signer address directly
* `proxy` → derive a proxy wallet from the signer address
* `gnosis-safe` → derive a safe wallet from the signer address

In Heat, bridge and trading flows default to the effective Polymarket wallet, not always the raw signer address.

### 3. Get deposit addresses

Use the Heat bridge command:

```bash
heat pm bridge deposit
```

This fetches deposit addresses for the current account's effective Polymarket wallet.

The command is read-only. It does not move funds.

You can also inspect supported bridge assets:

```bash
heat pm bridge supported-assets
```

### 4. Fund externally

Heat currently does **not** perform the transfer for you. The bridge command only returns the deposit addresses.

So the correct human flow is:

1. run `heat pm bridge deposit`
2. copy the returned deposit address for the chain you want to use
3. send funds from an external wallet or exchange
4. return to Heat and check status

### Agent instruction: how to ask for funding

If an agent needs the user to fund Polymarket, it should ask explicitly and include the correct address context.

Recommended wording:

> Your Heat account is configured for Polymarket, but Heat does not yet move funds on your behalf. Please send funds to the Polymarket deposit address returned by `heat pm bridge deposit`, then tell me when to continue. After funding lands, I can check deposit status, approvals, balances, and prepare orders.

Recommended agent flow:

1. run `heat pm bridge deposit`
2. show the returned address to the human
3. explain that Heat only fetches deposit instructions today
4. wait for the human to fund externally
5. run `heat pm bridge status`
6. run `heat pm approve check`
7. only then proceed to trading

### 5. Check deposit status

```bash
heat pm bridge status
```

This uses the effective Polymarket wallet by default.

### 6. Check and set approvals

Polymarket trading requires approvals for exchange contracts.

Check status:

```bash
heat pm approve check
```

Grant approvals:

```bash
heat pm approve set
```

`approve set` is dangerous because it sends Polygon transactions.

Heat sets approvals for:

* `CTF Exchange`
* `Neg Risk Exchange`
* `Neg Risk Adapter`

### Important approval nuance

Approval checks currently use the signer owner path anchored to the EOA address.
That is correct for the current on-chain approval flow in Heat, but users and agents should still think of balances and trading in terms of the effective Polymarket wallet.

### 7. Browse markets before trading

Start with read-only discovery:

```bash
heat pm markets list --limit 5
heat pm markets search "election"
heat pm price <token_id> --side buy
heat pm clob book <token_id>
```

These are the best first commands for humans and agents.

### 8. Preview before trading

Use `--dry-run` first:

```bash
heat pm buy <token_id> --price 0.55 --size 100 --dry-run
heat pm sell <token_id> --price 0.65 --size 50 --dry-run
```

### 9. Trade and manage orders

```bash
# helper commands
heat pm buy <token_id> --price 0.55 --size 100
heat pm sell <token_id> --price 0.65 --size 50
heat pm orders
heat pm trades
heat pm cancel <order_id>

# lower-level CLOB commands
heat pm clob market-order <token_id> --side buy --amount 50
heat pm clob orders --market <condition_id>
heat pm clob cancel-all
```

### 10. Monitor live account events

After you are funded and approved, you can monitor live account events. Omit `--market` for all markets.

```bash
heat pm stream orders
heat pm stream orders --market <condition_id>
heat pm stream trades --market <condition_id>
```

### 11. Positions, balances, and analytics

```bash
heat pm positions
heat pm balance
heat pm data positions --limit 25
heat pm data trades --limit 25
```

### Polygon RPC used by Heat

For Polymarket on-chain provider calls, Heat currently uses:

```text
https://polygon.drpc.org
```

This is used for read-only and wallet-backed Polygon calls such as approvals and CTF operations.
It is **not** used when merely creating a Heat account.

### Minimal onboarding checklist

```bash
heat accounts create trading --generate --persist-password ~/.heat/secrets/trading.password
heat accounts use trading
heat pm bridge deposit
# fund externally, then continue
heat pm bridge status
heat pm approve check
heat pm approve set
heat pm markets list --limit 5
heat pm buy <token_id> --price 0.55 --size 100 --dry-run
```

### Command map

#### Best first commands

* `heat pm markets list`
* `heat pm markets search`
* `heat pm price`
* `heat pm bridge deposit`
* `heat pm bridge status`
* `heat pm approve check`
* `heat pm approve set`
* `heat pm positions`
* `heat pm buy --dry-run`

#### Helper path vs protocol-native path

Use the helper commands when possible:

* `price`
* `buy`
* `sell`
* `cancel`
* `orders`
* `trades`
* `positions`
* `balance`

Use the lower-level command trees when you need deeper protocol control:

* `markets`, `events`, `tags`, `series`, `comments`, `profiles`, `sports`
* `clob`
* `data`
* `stream`
* `ctf`
* `bridge`
* `approve`

### Real-time streaming

After onboarding, you can stream live market data and user events.

Market data streams require no account:

```bash
heat pm stream orderbook <token_id>
heat pm stream prices <token_id>
heat pm stream midpoints <token_id>
```

User event streams require an authenticated account. Use `--market` to filter to one market, or omit it to receive events across all markets.

```bash
heat pm stream orders
heat pm stream orders --market <condition_id>
heat pm stream trades --market <condition_id>
```

Streams output NDJSON by default when piped. Use `--json` or `--ndjson` for machine-readable output.


## Polymarket

All Polymarket commands live under `heat polymarket` or `heat pm`.

Polymarket is a prediction market on Polygon. Heat wraps the Gamma API, CLOB API, Data API, Bridge API, and on-chain CTF contracts.

For the recommended first-time flow, start with [Polymarket Onboarding](/protocols/polymarket-onboarding).

:::info[Default signature type]
Heat currently defaults Polymarket to `proxy` unless you override it with `--sig-type` or configure `account.protocols.polymarket.signature_type`.
:::

### What needs an account

Read-only discovery commands do not need a signing account:

* `markets`
* `events`
* `tags`
* `series`
* `comments`
* `profiles`
* `sports`
* `status`
* read-only `clob` pricing and book commands
* `stream orderbook`, `stream prices`, `stream midpoints`

Trading, account, approval, on-chain, and user stream commands do.

### Funding

:::warning[Partly manual for now]
`heat pm bridge deposit` fetches Polymarket deposit addresses for the effective wallet, but Heat does not send the transfer for you. Humans still fund externally, then return to Heat for status, approvals, and trading.
:::

### Signature types

Heat supports:

* `proxy`
* `eoa`
* `gnosis-safe`

Current precedence:

1. `--sig-type`
2. `account.protocols.polymarket.signature_type`
3. default `proxy`

In practice:

* `eoa` uses the Heat signer address directly
* `proxy` derives the effective Polymarket wallet from the Heat signer address
* `gnosis-safe` derives the effective safe wallet from the Heat signer address

### Best first commands

```bash
heat pm markets list --limit 5
heat pm price <token_id> --side buy
heat pm bridge deposit
heat pm approve check
heat pm buy <token_id> --price 0.55 --size 100 --dry-run
```

### Helper commands

These are the recommended primary path for humans and agents.

#### price

```bash
heat pm price <token_id> --side buy
heat pm price <token_id> --side sell
```

#### buy / sell

```bash
heat pm buy <token_id> --price 0.55 --size 100
heat pm sell <token_id> --price 0.65 --size 50
```

Optional `--sig-type` overrides the Polymarket signature type.

#### cancel

```bash
heat pm cancel <order_id>
```

#### orders

```bash
heat pm orders
heat pm orders --market <condition_id>
```

#### trades

```bash
heat pm trades
heat pm trades --market <condition_id>
```

#### positions

```bash
heat pm positions
heat pm positions --user 0x...
heat pm positions --limit 50
```

#### balance

```bash
heat pm balance
```

### Markets and discovery

#### markets

```bash
heat pm markets list --limit 10
heat pm markets list --closed true
heat pm markets get <condition_id_or_slug>
heat pm markets search "election" --limit 5
heat pm markets tags <market_id>
```

#### events

```bash
heat pm events list --limit 10 --active true
heat pm events get <id_or_slug>
heat pm events tags <event_id>
```

#### tags

```bash
heat pm tags list --limit 50
heat pm tags get <id_or_slug>
heat pm tags related <id> --omit-empty
```

#### series

```bash
heat pm series list
heat pm series get <id>
```

#### comments

```bash
heat pm comments list --entity-type market --entity-id <id>
heat pm comments get <comment_id>
heat pm comments by-user <address>
```

#### profiles

```bash
heat pm profiles get <address>
```

#### sports

```bash
heat pm sports list
heat pm sports market-types
heat pm sports teams
```

#### status

```bash
heat pm status
```

### Streaming

Real-time WebSocket streams for market data and user events.

#### Market data streams (no account required)

These subscribe by token/asset ID and emit events as they happen.

```bash
heat pm stream orderbook <token_id>
heat pm stream prices <token_id>
heat pm stream midpoints <token_id>
```

#### User streams (requires account)

These subscribe to your authenticated order and trade events. Omit `--market` to receive events across all markets.

```bash
heat pm stream orders
heat pm stream orders --market <condition_id>
heat pm stream trades
heat pm stream trades --market <condition_id>
```

Optional `--sig-type` overrides the Polymarket signature type.

:::info[Machine output]
Streams emit NDJSON (one JSON object per line). Use `--json` or `--ndjson` for machine consumption. `--quiet` is not supported for streams.
:::

### CLOB

Lower-level access to Polymarket's order book and authenticated trading.

#### Pricing and market info

```bash
heat pm clob price <token_id> --side buy
heat pm clob midpoint <token_id>
heat pm clob spread <token_id>
heat pm clob book <token_id>
heat pm clob last-trade-price <token_id>
heat pm clob price-history <market> --range 1d
heat pm clob market <condition_id>
heat pm clob markets
heat pm clob tick-size <token_id>
heat pm clob fee-rate <token_id>
heat pm clob neg-risk <token_id>
heat pm clob server-time
heat pm clob geoblock
heat pm clob ok
```

#### Order management

```bash
heat pm clob limit-order <token_id> --side buy --price 0.55 --size 100
heat pm clob market-order <token_id> --side buy --amount 50
heat pm clob order <order_id>
heat pm clob orders --market <condition_id>
heat pm clob trades --market <condition_id>
heat pm clob cancel-order <order_id>
heat pm clob cancel-market-orders --market <condition_id>
heat pm clob cancel-all
```

#### Balance, notifications, rewards

```bash
heat pm clob balance-allowance --asset-type collateral
heat pm clob update-balance-allowance
heat pm clob notifications
heat pm clob delete-notifications <comma_separated_ids>
heat pm clob earnings <YYYY-MM-DD>
heat pm clob total-earnings <YYYY-MM-DD>
heat pm clob reward-percentages
heat pm clob current-rewards
heat pm clob raw-rewards <condition_id>
heat pm clob is-order-scoring <order_id>
```

### Data

```bash
heat pm data positions --user 0x... --limit 25
heat pm data closed-positions --user 0x...
heat pm data value --user 0x...
heat pm data traded --user 0x...
heat pm data trades --user 0x... --limit 25
heat pm data activity --user 0x... --limit 25
heat pm data holders <condition_ids> --limit 20
heat pm data open-interest <condition_ids>
heat pm data live-volume <event_id>
heat pm data leaderboard --period week --order-by pnl --limit 25
heat pm data builder-leaderboard --period all
heat pm data builder-volume --period month
```

### Bridge

```bash
heat pm bridge deposit
heat pm bridge status
heat pm bridge supported-assets
```

`deposit` is read-only and returns deposit addresses. You still fund externally.

### CTF

```bash
heat pm ctf split --collateral 0x... --condition-id 0x... --partition 1,2 --amount 1000
heat pm ctf merge --collateral 0x... --condition-id 0x... --partition 1,2 --amount 1000
heat pm ctf redeem --collateral 0x... --condition-id 0x... --index-sets 1,2
heat pm ctf redeem-neg-risk --condition-id 0x... --amounts 100,200
heat pm ctf condition-id --oracle 0x... --question-id 0x...
heat pm ctf collection-id --condition-id 0x... --index-set 1
heat pm ctf position-id --collateral 0x... --collection-id 0x...
```

### Approve

```bash
heat pm approve check
heat pm approve set
```

`approve set` sends Polygon transactions and is dangerous.

### Polygon RPC

For Polymarket on-chain provider calls, Heat currently uses:

```text
https://polygon.drpc.org
```


## Getting Started

This guide walks through first-time setup: install Heat, create an account, understand funding, and run your first protocol commands.

:::info[What is Heat?]
Heat is a unified crypto CLI for traders, AI agents, researchers, and terminal power users. It currently supports Hyperliquid, Polymarket, Aave phase 1, LI.FI-backed EVM bridging, and DefiLlama read-only market data behind one consistent output, account, and safety model.
:::

### 1. Install Heat

```bash
# One-command install (recommended)
curl -fsSL https://raw.githubusercontent.com/dzmbs/heat-cli/main/install.sh | bash

# Or install with cargo
cargo install --git https://github.com/dzmbs/heat-cli --bin heat
```

Confirm it works:

```bash
heat --version
heat --help
```

See [Installation](/introduction/installation) for other methods and platform details.

### 2. Create a Heat account

Heat uses named accounts to manage keys. Each account has encrypted local key material plus account metadata under `~/.heat/`.

#### Option A: Generate a new Heat account locally

```bash
heat accounts create trading --generate --persist-password ~/.heat/secrets/trading.password
```

This is the recommended path for both humans and agents:

* Heat generates the key locally
* Heat generates the encryption password locally
* Heat stores the password at the path you chose
* future signing commands can reuse that stored password path automatically

#### Option B: Create from an existing private key

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

#### Option C: Import an existing keystore

If you already have an Ethereum V3 keystore file:

```bash
heat accounts import trading --keystore /path/to/keystore.json
```

### 3. Set a default account

```bash
heat accounts use trading
```

Override per-command with `--account`:

```bash
heat hl balance --account other-account
```

### 4. Verify account details

```bash
heat accounts list
heat accounts get trading
heat config
```

The address shown by `heat accounts get trading` is important for onboarding.

* Hyperliquid funding is currently done externally to that account address.
* Polymarket uses the same Heat account for signing, but may derive a different effective Polymarket wallet depending on signature type.
* Aave and LI.FI use the same Heat EVM account model directly.
* DefiLlama is read-only market data and does not require an account for normal usage.

### 5. Understand funding today

:::warning[Funding is still partly manual in early releases]
Heat now supports LI.FI bridging between supported EVM chains, but onboarding and protocol funding are still not fully unified. You may still need to fund accounts externally before using protocol commands.
:::

#### Hyperliquid

Heat does not currently include a Hyperliquid deposit or bridge command.

Current flow:

1. get your account address with `heat accounts get trading`
2. fund that address externally for Hyperliquid
3. return to Heat and verify with `heat hl balance`

#### Polymarket

Heat can fetch Polymarket deposit addresses, but it does not send the transfer itself.

Current flow:

1. run `heat pm bridge deposit`
2. send funds externally to the returned deposit address
3. check status with `heat pm bridge status`
4. run approvals with `heat pm approve check` and `heat pm approve set`

#### Aave

Aave does not need a special onboarding flow beyond having funds on the target EVM chain.

Current flow:

1. make sure your Heat EVM account has funds on Ethereum, Arbitrum, or Base
2. inspect available reserves with `heat aave markets --chain <chain>`
3. preview with `--dry-run` before `supply` or `withdraw`

#### LI.FI

LI.FI is Heat's EVM bridge layer.

Current flow:

1. fund your source-chain Heat account
2. preview route execution with `heat lifi bridge ... --dry-run`
3. execute the bridge when ready
4. check progress with `heat lifi status`

### 6. Run your first read-only commands

#### Hyperliquid

```bash
heat hl price BTC
heat hl perps
heat hl spot
```

#### Polymarket

```bash
heat pm markets list --limit 5
heat pm markets search "election"
heat pm price <token_id> --side buy
```

#### Aave

```bash
heat aave markets --chain ethereum
heat aave positions --chain arbitrum --account trading
heat aave health --chain base --account trading
```

#### LI.FI

```bash
heat lifi chains
heat lifi tokens --chain ethereum
heat lifi routes --from-chain ethereum --to-chain arbitrum --from-token USDC --to-token USDC --amount 1000000 --from-address 0x...
```

#### DefiLlama

```bash
heat llama protocols list --limit 5
heat llama chains list --limit 5
heat llama fees overview --chain Ethereum
```

### 7. Verify funded accounts

#### Hyperliquid

```bash
heat hl balance
heat hl positions
heat hl orders
```

#### Polymarket

```bash
heat pm bridge status
heat pm approve check
heat pm balance
heat pm positions
```

#### Aave

```bash
heat aave positions --chain ethereum
heat aave health --chain ethereum
```

#### LI.FI

```bash
heat lifi bridge 100 USDC --from ethereum --to base --account trading --dry-run
```

### 8. Preview dangerous commands first

Use `--dry-run` before any action that could move money, place an order, bridge funds, or execute a lending action.

#### Hyperliquid

```bash
heat hl buy ETH 0.1 --price 3500 --dry-run
```

#### Polymarket

```bash
heat pm buy <token_id> --price 0.55 --size 100 --dry-run
```

#### Aave

```bash
heat aave supply USDC 1000 --chain ethereum --account trading --dry-run
```

#### LI.FI

```bash
heat lifi bridge 100 USDC --from ethereum --to arbitrum --account trading --dry-run
```

### 9. Agent workflow guidance

If you are building an agent on top of Heat, use this pattern:

1. resolve or confirm the active account
2. inspect addresses and balances
3. if funding is missing, ask the human to fund externally or bridge with LI.FI if appropriate
4. re-check balances or deposit status
5. use `--dry-run` before proposing a live action
6. require explicit confirmation before real-money writes

#### Recommended agent wording for Hyperliquid

> Your Heat account is configured, but Heat does not yet support Hyperliquid funding inside the CLI. Please fund address `<ADDRESS>` externally, then tell me when to continue.

#### Recommended agent wording for Polymarket

> Your Heat account is configured, but Heat does not yet move funds on your behalf into Polymarket directly. Please send funds to the deposit address returned by `heat pm bridge deposit`, then tell me when to continue.

#### Recommended agent wording for LI.FI

> I can bridge supported EVM assets with `heat lifi bridge`, but I will first show you a dry-run preview and wait for explicit confirmation before executing.

### 10. Account resolution order

Heat resolves which account to use in this order:

1. `--account` flag
2. `HEAT_ACCOUNT` environment variable
3. `default_account` in `~/.heat/config.toml`
4. `~/.heat/default-account` file set by `heat accounts use`

If none are set, commands that require an account fail with an auth error and a hint.

### Next steps

* [Hyperliquid Overview](/protocols/hyperliquid)
* [Hyperliquid Onboarding](/protocols/hyperliquid-onboarding)
* [Polymarket Overview](/protocols/polymarket)
* [Polymarket Onboarding](/protocols/polymarket-onboarding)
* [Aave Overview](/protocols/aave)
* [LI.FI Overview](/protocols/lifi)
* [Accounts](/core/accounts)
* [Output Modes](/core/output)
* [Safety](/core/safety)


## Installation

### Quick install (recommended)

The installer detects your OS and architecture, downloads a prebuilt binary, and falls back to cargo if needed.

```bash
curl -fsSL https://raw.githubusercontent.com/dzmbs/heat-cli/main/install.sh | bash
```

By default, the binary is installed to `~/.local/bin`. Override with `HEAT_INSTALL_DIR`:

```bash
HEAT_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/dzmbs/heat-cli/main/install.sh | bash
```

### From source (cargo install)

Requires Rust 1.85 or later.

#### From Git

```bash
cargo install --git https://github.com/dzmbs/heat-cli --bin heat
```

#### From a local checkout

```bash
git clone https://github.com/dzmbs/heat-cli.git
cd heat-cli
cargo install --path crates/heat-cli
```

### Pre-built binaries (manual)

Download the latest release tarball for your platform from the releases page.

```bash
# Example for macOS arm64
tar xzf heat-v0.2.0-macos-aarch64.tar.gz
sudo mv heat /usr/local/bin/
```

Or place it anywhere on your `PATH`:

```bash
mkdir -p ~/.local/bin
mv heat ~/.local/bin/
```

### Verify installation

```bash
heat --version
heat --help
```

### Supported platforms

| Platform | Architecture          | Status      |
| -------- | --------------------- | ----------- |
| macOS    | arm64 (Apple Silicon) | Supported   |
| macOS    | x86\_64 (Intel)       | Supported   |
| Linux    | x86\_64               | Supported   |
| Linux    | arm64                 | Best-effort |
| Windows  | x86\_64               | Best-effort |

"Best-effort" means it should work but is not part of the primary test matrix.

### Build from source

```bash
cargo build --release -p heat
# Binary is at target/release/heat
```

:::tip[Rust version]
Heat requires Rust 1.85 or later. Run `rustup update stable` to get the latest stable toolchain.
:::


## 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

```bash
heat accounts list
```

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

#### Show account details

```bash
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.

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

You can also create from existing key material:

```bash
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

```bash
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:

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

#### Set the default account

```bash
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

```bash
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:

```bash
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:

```bash
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:

```toml
# ~/.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](/protocols/polymarket) 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
```

:::warning[Key security]
Your private keys are encrypted locally. Heat never transmits your password or raw private key. Back up both the keystore file and the password file if you use `--persist-password`.
:::


## Output Modes

Heat separates data from diagnostics and supports multiple output formats for both human and machine consumption.

### The contract

* **stdout** = command data (results, JSON, tables)
* **stderr** = diagnostics (warnings, hints, progress, confirmations)

This separation means you can safely pipe Heat's output into `jq` or other tools without diagnostic noise contaminating the data stream.

### Four output modes

#### pretty (default in terminals)

Human-readable tables and labels. This is the default when stdout is a TTY.

```bash
heat hl price BTC
# BTC: 97421.5
```

#### json (default in pipes)

A single JSON object per command invocation. This is the default when stdout is piped to another program.

```bash
heat hl price BTC | jq .
# {
#   "asset": "BTC",
#   "mid": "97421.5"
# }
```

#### ndjson (newline-delimited JSON)

One JSON object per line. Useful for streaming commands and log processing.

```bash
heat hl stream trades BTC --output ndjson
# {"coin":"BTC","side":"B","sz":"0.1","px":"97421.5",...}
# {"coin":"BTC","side":"A","sz":"0.05","px":"97422.0",...}
```

#### quiet

Suppresses most output. Commands that support quiet mode emit a single scalar value (e.g., just the price or just the order ID).

```bash
heat hl price BTC -q
# 97421.5

PRICE=$(heat hl price BTC -q)
```

### Controlling the mode

#### Auto-detection (default)

When you do not specify a format, Heat auto-detects:

* TTY stdout → `pretty`
* Non-TTY stdout (pipe, redirect) → `json`

#### Explicit flags

| Flag                     | Effect                                            |
| ------------------------ | ------------------------------------------------- |
| `--json`                 | Force JSON output (shorthand for `--output json`) |
| `--output pretty`        | Force pretty output                               |
| `--output json`          | Force JSON output                                 |
| `--output ndjson`        | Force NDJSON output                               |
| `-q` or `--output quiet` | Force quiet output                                |

Explicit flags override auto-detection. For example, `--json` gives you JSON even in a terminal.

### Piping with jq

Because piped commands default to JSON, Heat works naturally with `jq`:

```bash
# Extract a single field
heat hl price ETH | jq -r .mid

# Filter positions
heat hl positions | jq '.[] | select(.unrealized_pnl | tonumber > 0)'

# Get account value as a number
heat hl balance | jq -r .account_value
```

### Errors in machine mode

In JSON and NDJSON modes, errors are emitted as structured JSON to stdout:

```json
{
  "error": {
    "type": "validation",
    "reason": "asset_not_found",
    "message": "No price found for: FAKE",
    "retryable": false,
    "hint": "Use 'heat hl perps' or 'heat hl spot' to list available markets"
  }
}
```

In pretty and quiet modes, errors go to stderr as plain text.

### Exit codes

| Code | Meaning                               |
| ---- | ------------------------------------- |
| 0    | Success                               |
| 1    | Protocol or internal error            |
| 2    | Validation / usage error              |
| 3    | Auth error (no account, bad password) |
| 4    | Network error (API unreachable)       |

:::tip[Agent-friendly design]
The stdout/stderr split is intentional for agent use. Your orchestrator can capture stdout for structured data while stderr carries human-readable diagnostics. Exit codes give you semantic status without parsing output.
:::


## Safety

Heat handles real money. Its safety model prevents accidental execution of dangerous actions.

### Dangerous actions

The following commands are considered dangerous and require confirmation:

**Hyperliquid:**

* `heat hl buy` / `heat hl sell` — placing orders
* `heat hl cancel` — cancelling orders
* `heat hl leverage set` — changing leverage
* `heat hl send` — sending tokens

**Polymarket:**

* `heat pm buy` / `heat pm sell` — placing orders
* `heat pm cancel` — cancelling orders
* `heat pm clob limit-order` / `heat pm clob market-order` — CLOB orders
* `heat pm clob cancel-order` / `heat pm clob cancel-all` — CLOB cancellations
* `heat pm ctf split` / `heat pm ctf merge` / `heat pm ctf redeem` — CTF operations
* `heat pm approve set` — granting token approvals

Read-only commands (price, balance, positions, market data) never require confirmation.

### --dry-run

Preview what a command would do without executing it. Dry-run output goes to stderr.

```bash
heat hl buy ETH 1.0 --price 3500 --dry-run
```

Output:

```
[dry-run] hl buy
  asset: ETH
  size: 1.0
  price: 3500
  notional: $3500
  reduce_only: false
[dry-run] No action taken.
```

Dry-run is available on all dangerous commands and always exits with code 0.

### TTY confirmation

When running in a terminal (TTY) without `--yes`, dangerous commands prompt for confirmation:

```
Confirm buy 1.0 ETH @ 3500? [y/N]
```

Only `y` (case-insensitive) proceeds. Anything else cancels the action.

### --yes

Skip the confirmation prompt:

```bash
heat hl buy ETH 1.0 --price 3500 --yes
```

This is required for scripts and automated workflows.

### Non-TTY behavior

When stdout is not a terminal (pipes, cron, CI), Heat is strict:

* Dangerous commands without `--yes` **fail with an error**.
* Heat never silently prompts on a non-TTY.
* Scripts must explicitly opt in with `--yes`.

This prevents accidental execution when a script is missing the confirmation flag.

```bash
# This fails in a script:
heat hl buy ETH 1.0 --price 3500
# error: Dangerous action requires confirmation: buy 1.0 ETH @ 3500
# hint: Use --yes to confirm in non-interactive mode

# This works:
heat hl buy ETH 1.0 --price 3500 --yes
```

### Combining --dry-run with scripts

A common pattern: preview first, then execute.

```bash
# Preview
heat hl buy ETH 1.0 --price 3500 --dry-run

# Execute
heat hl buy ETH 1.0 --price 3500 --yes
```

### Summary

| Context          | No flag          | --yes                | --dry-run     |
| ---------------- | ---------------- | -------------------- | ------------- |
| TTY (terminal)   | Prompts `[y/N]`  | Executes immediately | Previews only |
| Non-TTY (script) | Fails with error | Executes immediately | Previews only |

:::danger[Real money]
Heat operates on live exchange accounts with real funds. Always use `--dry-run` to preview orders before executing. Start with small amounts when testing new workflows.
:::