Hyperliquid Perps Trading#

Installation#

bash

# Check if already installed
which byreal-perps-cli && byreal-perps-cli --version

# Install
npm install -g @byreal-io/byreal-perps-cli

Credentials & Permissions#

• All trading commands require account initialization via byreal-perps-cli account init before any trading operations
• Read-only commands (account info, position list, order list, account history): Require initialized perps account
• Write commands (order market, order limit, order cancel, position close-market/close-limit/close-all, position leverage): Require initialized perps account with valid agent wallet
• Signal commands (signal scan, signal detail): No account required — uses public market data only
• Perps agent keys are stored locally in the byreal data directory with strict file permissions (mode 0600)
• The CLI never transmits private keys over the network — keys are only used locally for transaction signing
• AI agents should never ask users to paste private keys in chat; always direct them to run byreal-perps-cli account init interactively

WebSocket / API Fallback#

Some commands ( account info, position list, position close-market, position close-limit, position close-all) use WebSocket subscriptions to fetch real-time data. If the WebSocket connection fails or times out, the CLI automatically falls back to HTTP API calls. No user action is needed.

If a command returns a connection error:

1. The CLI will retry via HTTP API automatically; if it still fails, the issue is likely network connectivity or Hyperliquid API downtime.
2. Check network connectivity: curl -s https://api.hyperliquid.xyz/info -X POST -H 'Content-Type: application/json' -d '{"type":"meta"}'
3. For testnet, check: curl -s https://api.hyperliquid-testnet.xyz/info -X POST -H 'Content-Type: application/json' -d '{"type":"meta"}'
4. If HTTP API also fails, the Hyperliquid service may be temporarily unavailable — retry after a short wait.

Hard Constraints#

1. -o json only for parsing — when showing results to the user, omit it and let the CLI's built-in tables render directly. Never fetch JSON then re-draw tables yourself.
2. Never display private keys — use keypair paths only
3. Never call the SDK directly — do NOT write node -e / tsx -e scripts that import or require packages like @nktkas/hyperliquid or viem. Always use byreal-perps-cli commands to interact with Hyperliquid. The SDK is bundled inside the CLI; calling it externally causes CJS/ESM compatibility errors.

Commands Reference#

Account Management#

bash

# Initialize perps account (interactive wizard)
byreal-perps-cli account init

# Show account info & balance
byreal-perps-cli account info

# Show recent trade history
byreal-perps-cli account history

Orders#

bash

# Market order (side: buy/sell/long/short, size in coin units)
byreal-perps-cli order market <side> <size> <coin>
byreal-perps-cli order market buy 0.01 BTC --tp 110000 --sl 90000

# Limit order
byreal-perps-cli order limit <side> <size> <coin> <price>
byreal-perps-cli order limit sell 1 ETH 4000

# List open orders
byreal-perps-cli order list

# Cancel an order
byreal-perps-cli order cancel <coin> <oid>

# Cancel all orders
byreal-perps-cli order cancel-all -y

Positions#

bash

# List open positions
byreal-perps-cli position list

# Set leverage (1-50x)
byreal-perps-cli position leverage <coin> <leverage>

# Close at market price (full or partial)
byreal-perps-cli position close-market <coin>

# Close with limit order
byreal-perps-cli position close-limit <coin> <price>

# Close all positions
byreal-perps-cli position close-all -y

Market Signals#

bash

# Scan markets for trading signals
byreal-perps-cli signal scan

# Detailed technical analysis
byreal-perps-cli signal detail <coin>

Update#

bash

# Check for available CLI updates
byreal-perps-cli update check

# Install the latest CLI version
byreal-perps-cli update install

Testnet#

All commands support --testnet:

bash

byreal-perps-cli --testnet account info