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

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.

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:

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

Or create from an existing EVM private key:

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

Or import an existing Ethereum V3 keystore:

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

Set it as the default account:

heat accounts use trading

Show the account and copy the address:

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:

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

heat hl balance
heat hl positions
heat hl orders

For read-only inspection of another address:

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:

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.

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

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

heat hl leverage show

Set leverage:

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

Send assets:

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

9. Streaming for agents

Use NDJSON for continuous machine-readable output:

heat hl stream trades BTC --output ndjson

This is the best starting stream for automation.

Minimal onboarding checklist

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