Agent Integration

hlz is designed for AI agents and automated workflows. Every command works non-interactively with structured output.

Design Guarantees

Property	Guarantee
No prompts	Every command completes without user input
Structured output	JSON when piped, `--json` flag always available
Semantic exit codes	`0`=OK, `1`=error, `2`=usage, `3`=auth, `4`=network
Dry-run mode	`--dry-run` previews any trade without submitting
Stdin batch	Pipe order lists via `--stdin`
Deterministic	Same inputs → same outputs (except market data)

Detecting Output Mode

hlz auto-detects whether stdout is a TTY:

# TTY: colored tables
hlz positions
 
# Piped: JSON automatically
hlz positions | jq .
 
# Explicit JSON
hlz positions --json
 
# Minimal output
hlz price BTC -q    # Just: 97432.5

Agent Workflow Examples

Check-then-trade

PRICE=$(hlz price BTC -q)
if (( $(echo "$PRICE < 50000" | bc -l) )); then
  hlz buy BTC 0.1 @${PRICE} --json
fi

Monitor and react

hlz stream trades BTC | while read -r line; do
  SIZE=$(echo "$line" | jq -r '.sz')
  if (( $(echo "$SIZE > 10" | bc -l) )); then
    echo "Large trade detected: $line"
    # React to whale trades
  fi
done

Batch from file

# orders.txt:
# buy BTC 0.1 @98000
# buy ETH 1.0 @3400
# sell SOL 100 @180
 
cat orders.txt | hlz batch --stdin --json

Portfolio snapshot

# Capture full state as JSON
hlz portfolio --json > snapshot_$(date +%s).json
hlz orders --json >> snapshot_$(date +%s).json

Environment Variables

Configure everything via environment for CI/agents:

export HL_KEY="private_key_hex"       # Trading key
export HL_ADDRESS="0x..."             # Default address
export HL_CHAIN="mainnet"             # or testnet
export HL_OUTPUT="json"               # Always JSON
export HL_PASSWORD="keystore_pass"    # Keystore password

Error Handling

In --json mode, errors are written to stdout as a structured JSON envelope — same stream as success output. Parse the status field to distinguish:

hlz buy BTC 0.1 @50000 --json
# stdout: {"v":1,"status":"error","cmd":"buy","error":"MissingKey","message":"","retryable":false,"hint":"set HL_KEY env var or pass --key","timing_ms":0}
 
# Check status in your agent:
RESULT=$(hlz buy BTC 0.1 @50000 --json)
STATUS=$(echo "$RESULT" | jq -r '.status')
if [ "$STATUS" = "error" ]; then
  echo "$RESULT" | jq -r '.hint'
fi

Exit codes work in all modes:

hlz buy INVALID 0.1
echo $?  # 2 (usage error)

Rate Limits

Hyperliquid API: 1200 requests/minute per IP. The CLI doesn't add any additional throttling — manage this in your agent logic.

Agent-Approve Workflow

For security, use a dedicated API wallet:

# Generate a new API wallet
hlz keys new api-agent
 
# Approve it from your main wallet
hlz approve-agent 0xAPI_WALLET_ADDRESS
 
# Agent uses the API wallet (limited permissions)
export HL_KEY_NAME=api-agent