Hyperliquid Perps Trading
Installation
CODEBLOCK0
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.
- Check network connectivity: INLINECODE7
- For testnet, check: INLINECODE8
- 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. - Never display private keys — use keypair paths only
- 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
CODEBLOCK1
Orders
CODEBLOCK2
Positions
CODEBLOCK3
Market Signals
CODEBLOCK4
Update
CODEBLOCK5
Testnet
All commands support --testnet:
CODEBLOCK6
Hyperliquid 永续合约交易
安装
bash
检查是否已安装
which byreal-perps-cli && byreal-perps-cli --version
安装
npm install -g @byreal-io/byreal-perps-cli
凭证与权限
- - 所有交易命令在执行任何交易操作前，都需要通过 byreal-perps-cli account init 进行账户初始化
- 只读命令（账户信息、持仓列表、订单列表、账户历史）：需要已初始化的永续合约账户
- 写入命令（市价单、限价单、撤单、平仓-市价/限价/全部平仓、持仓杠杆）：需要已初始化且带有有效代理钱包的永续合约账户
- 信号命令（信号扫描、信号详情）：无需账户——仅使用公开市场数据
- 永续合约代理密钥存储在本地 byreal 数据目录中，具有严格的文件权限（模式 0600）
- CLI 永远不会通过网络传输私钥——密钥仅用于本地交易签名
- AI 代理绝不应要求用户在聊天中粘贴私钥；始终引导他们交互式运行 byreal-perps-cli account init
WebSocket / API 回退
某些命令（account info、position list、position close-market、position close-limit、position close-all）使用 WebSocket 订阅获取实时数据。如果 WebSocket 连接失败或超时，CLI 会自动回退到 HTTP API 调用。无需用户操作。
如果命令返回连接错误：
- 1. CLI 会自动通过 HTTP API 重试；如果仍然失败，问题可能是网络连接或 Hyperliquid API 停机。
- 检查网络连接：curl -s https://api.hyperliquid.xyz/info -X POST -H Content-Type: application/json -d {type:meta}
- 对于测试网，检查：curl -s https://api.hyperliquid-testnet.xyz/info -X POST -H Content-Type: application/json -d {type:meta}
- 如果 HTTP API 也失败，Hyperliquid 服务可能暂时不可用——稍等片刻后重试。
硬性约束
- 1. -o json 仅用于解析——向用户展示结果时，省略该参数，让 CLI 内置表格直接渲染。切勿自行获取 JSON 后再重新绘制表格。
- 绝不显示私钥——仅使用密钥对路径
- 绝不直接调用 SDK——不要编写 node -e / tsx -e 脚本来 import 或 require 诸如 @nktkas/hyperliquid 或 viem 之类的包。始终使用 byreal-perps-cli 命令与 Hyperliquid 交互。SDK 已集成在 CLI 内部；外部调用会导致 CJS/ESM 兼容性错误。
命令参考
账户管理
bash
初始化永续合约账户（交互式向导）
byreal-perps-cli account init
显示账户信息与余额
byreal-perps-cli account info
显示近期交易历史
byreal-perps-cli account history
订单
bash
市价单（方向：buy/sell/long/short，数量以币为单位）
byreal-perps-cli order market <方向> <数量> <币种>
byreal-perps-cli order market buy 0.01 BTC --tp 110000 --sl 90000
限价单
byreal-perps-cli order limit <方向> <数量> <币种> <价格>
byreal-perps-cli order limit sell 1 ETH 4000
列出未成交订单
byreal-perps-cli order list
撤销订单
byreal-perps-cli order cancel <币种> <订单ID>
撤销所有订单
byreal-perps-cli order cancel-all -y
持仓
bash
列出未平仓持仓
byreal-perps-cli position list
设置杠杆（1-50倍）
byreal-perps-cli position leverage <币种> <杠杆倍数>
以市价平仓（全仓或部分）
byreal-perps-cli position close-market <币种>
以限价单平仓
byreal-perps-cli position close-limit <币种> <价格>
平掉所有持仓
byreal-perps-cli position close-all -y
市场信号
bash
扫描市场寻找交易信号
byreal-perps-cli signal scan
详细技术分析
byreal-perps-cli signal detail <币种>
更新
bash
检查是否有可用的 CLI 更新
byreal-perps-cli update check
安装最新版 CLI
byreal-perps-cli update install
测试网
所有命令均支持 --testnet：
bash
byreal-perps-cli --testnet account info
