--- title: "byreal-perps-cli by byreal-git · skilld" canonical_url: "https://skilld.dev/gh/byreal-git/byreal-perps-cli" meta: description: "Use when the user wants to trade perpetual futures on Hyperliquid: open/close positions, set leverage, manage TP/SL, check funding rates, scan market signals.… From byreal-git/byreal-perps-cli." "og:description": "Use when the user wants to trade perpetual futures on Hyperliquid: open/close positions, set leverage, manage TP/SL, check funding rates, scan market signals.… From byreal-git/byreal-perps-cli." "og:title": "byreal-perps-cli by byreal-git" "twitter:description": "Use when the user wants to trade perpetual futures on Hyperliquid: open/close positions, set leverage, manage TP/SL, check funding rates, scan market signals.… From byreal-git/byreal-perps-cli." "twitter:title": "byreal-perps-cli by byreal-git" --- ` [All skills](https://skilld.dev/skills) [![byreal-git avatar](https://skilld.dev/_img/avatar?url=https%3A%2F%2Fgithub.com%2Fbyreal-git.png%3Fsize%3D96)](https://skilld.dev/gh/byreal-git) # **/byreal-perps-cli** [@cd142b6](https://github.com/byreal-git/byreal-perps-cli/commit/cd142b6b5604b68012f16b667ab934f94506bb22 "Your agent reads SKILL.md at commit cd142b6") by [byreal-git](https://skilld.dev/gh/byreal-git)· [byreal-git](https://skilld.dev/gh/byreal-git)/ [byreal-perps-cli](https://skilld.dev/gh/byreal-git/byreal-perps-cli)·1 stars Use when the user wants to trade perpetual futures on Hyperliquid: open/close positions, set leverage, manage TP/SL, check funding rates, scan market signals. Trigger phrases: "open a long BTC perp", "close my ETH position", "set leverage to 5x", "set stop-loss at 90000", "perp funding rate for BTC", "scan perp market signals". SKIP when the user wants to deposit to, withdraw from, or bridge funds to/from the Hyperliquid perp account — use the agent-token skill for that. - 2 files - 30.9 KB - Updated 5 months ago - [GitHub](https://github.com/byreal-git/byreal-perps-cli/blob/cd142b6b5604b68012f16b667ab934f94506bb22/skills/byreal-perps-cli/SKILL.md "View SKILL.md on GitHub") - [2 warnings](#third-party-checks "Third-party checks: 2 warnings · 4 checks · Risk SAFE") ## SKILL.md 22.4 KB **≈124** tokens always: the name and description. **≈5.5k** when used: this file. **≈2.2k** more on demand in 1 file. ## Hyperliquid Perps Trading ### References - `references/perps-fundamentals.md` — Notional/margin/leverage triangle, funding rate, liquidation, margin modes, user intent mapping. Read before handling any trading request. ### ROLE You are a CLI operator for byreal-perps-cli. Translate the user's trading intent into the correct CLI command and execute it. - Do not add generic risk warnings ("trading is risky") or open-ended "are you sure?" questions. But before every opening order ( `order market` / `order limit`), emit the pre-execute summary (see Typical Execution Flows → Open a new position) and stop the turn for the user's go-ahead. The summary is a concrete preview of size / leverage / margin mode / liquidation — not a risk warning. - Respect the user's exact parameters. "stop-loss 90000" → `--sl 90000`. "sell" → `sell`. - If a command fails with "No perps account configured", run `byreal-perps-cli account init` automatically (token method, no private key), then resume the user's original request in the same turn. If init succeeds but the command still fails, report the error — do not re-run init. ### Handoff — deposit / withdraw / bridge `byreal-perps-cli` has no deposit, withdraw, or bridge command. If the user wants to move funds in or out of their Hyperliquid perp account, stop using this skill and follow the **agent-token** skill instead. Do not probe `--help`, do not try a CLI flag, do not fall back to explaining the Hyperliquid UI. Example: ``` User: top up my perps balance / deposit USDC to Hyperliquid / withdraw to Solana Action (LLM): do not run any byreal-perps-cli command. Follow the agent-token skill from here. ``` ### Markets `byreal-perps-cli` covers two DEXes: `main` (BTC, ETH, SOL, standard perps) and `xyz` (HIP-3 sub-DEX, e.g., GOLD). See `references/perps-fundamentals.md` for bare-ticker silent-routing behavior. If a bare ticker exists on both DEXes, fetch both and lay them side-by-side so the user picks. Example for "Open 1 GOLD long": ``` User: "Open 1 GOLD long" GOLD exists on both markets: | DEX | Price | Max Leverage | Margin Mode | |------|----------|--------------|-------------| | main | 2450.30 | 20x | cross/iso | | xyz | 2447.80 | 10x | iso only | Which one do you want? ``` If only one market has the coin, proceed and note `Market: xyz` in the open-flow summary. #### Ticker existence check Never use `signal scan` as a universe lister — it returns only coins that passed the signal filter, not every listed asset. Missing from `signal scan` does **not** mean "not on Hyperliquid". To check whether a ticker exists, run `signal detail` directly: ``` byreal-perps-cli signal detail -o json ``` If the user gave a bare ticker and `main` returns an error, try the `xyz:` prefix before telling the user it doesn't exist: ``` byreal-perps-cli signal detail xyz: -o json ``` Only conclude "not listed on Hyperliquid" after both forms fail. Commodity-style and non-crypto tickers (GOLD, OIL, CL, WTI, SP500, HIMS) almost always live on `xyz`, not `main`. ### Size & Leverage #### Size calculation `` in order commands is coin units representing notional value, not margin. See `references/perps-fundamentals.md` for the full notional/margin/leverage relationship. ``` size_in_coins = usd_notional / current_price ``` Map user input literally: - `$N` (e.g., "$20 position", "20 dollars of BTC") → N USD notional; convert via `size = N / price`. Do not divide by leverage. - `N ` (e.g., "100 BTC", "5 ETH") → N units of that coin, taken at face value. Resulting notional = `N × price`, which may be very large. Do NOT rewrite this as "$N of \" just because the dollar value looks unreasonable. To get current price, run `byreal-perps-cli signal detail -o json` and read `data.price`. #### Worked example Shows the size / margin calculation only. User: "Open $20 ETH position, 5x leverage" Given `byreal-perps-cli signal detail ETH -o json` returns `data.price = 2327.8`: - **Size** = notional / price = $20 / $2327.8 ≈ **0.00859 ETH** - **Margin** = notional / leverage = $20 / 5 = **$4** The numeric price in this example is illustrative only. Always query the live price at runtime and recalculate size from the returned `data.price`. Result: \~$20 notional, 5x leverage, \~$4 margin. #### Leverage check before every order 1. Check current leverage: review position list output or know the account default 2. If user specified a leverage → position leverage \ \ first 3. If user did NOT specify leverage → check current setting; if it looks unexpected (e.g., 20x for a small casual trade), ask the user before proceeding 4. Only report a leverage value you actually set or verified #### Size sanity checks Before submitting an order, verify the size is valid: 1. **Minimum notional** — Hyperliquid rejects orders below approximately $10 notional. If the user asks for "$5 BTC" or similar, tell them the request is below the exchange minimum before running any command. Do not just submit and rely on the API error. 2. **Precision / zero-size risk** — `size = usd_notional / price` is truncated to the asset's size precision ( `szDecimals`). For tiny positions on high-priced coins (e.g., $5 worth of BTC), the truncated size may round to 0, which fails with an opaque CLI error. If the computed size has more than `szDecimals` significant decimals below the first non-zero digit, warn the user and suggest a larger position. 3. **Vs. account balance** — before opening a large position, run `byreal-perps-cli account info` and confirm the user has enough `withdrawable` / free margin to cover the required margin ( `notional / leverage`). If requested notional exceeds available margin, warn the user before submitting. ### Funding Rate The CLI displays the **8-hour rate** as `fundingRate`. Settlement happens **every hour** at **1/8 of the displayed rate**. Annualized = `fundingRate × 3 × 365` (3 × 8h windows per day). Funding rate cap: 4%/hour (theoretical ceiling, rarely hit). When the user asks about "interest" on a perps position, they mean funding rate. See `references/perps-fundamentals.md` for more. ### TP/SL (Take-Profit / Stop-Loss) TP/SL are trigger-based reduce-only orders — they wait until the trigger price is hit, then close the position. This is fundamentally different from a limit sell or market sell, which executes immediately. #### How to set TP/SL **Opening a new position with TP/SL** — attach `--tp` / `--sl` flags to the order: ``` byreal-perps-cli order market long 1 ETH --tp 4000 --sl 3500 ``` **Adding TP/SL to an existing position** — use `position tpsl`: ``` byreal-perps-cli position tpsl BTC --sl 90000 ``` **Viewing existing TP/SL**: ``` byreal-perps-cli position tpsl ``` **Cancelling TP/SL**: ``` byreal-perps-cli position tpsl --cancel-tp byreal-perps-cli position tpsl --cancel-sl ``` #### Key distinction: trigger order vs immediate order Limit orders and trigger orders (`--sl` / `--tp`) both reference a price, but fire under opposite conditions: - **Limit order** — fires **now** if price is already past the threshold in the fillable direction: - `limit buy X` → fills if price ≤ X - `limit sell X` → fills if price ≥ X - **Trigger order** — **waits** for price to cross the threshold; direction depends on position side: - Long: `--sl X` fires when price drops to X; `--tp X` fires when price rises to X - Short: `--sl X` fires when price rises to X; `--tp X` fires when price drops to X SL lives on the loss side of entry, TP on the profit side. When the user says "stop-loss", always use `--sl` (on a new order) or `position tpsl` (on an existing position). A standalone sell/short order opens a new position or closes immediately — it does not set a conditional stop. #### TP/SL behavior - `--tp` and `--sl` attach to opening orders ( `order market` / `order limit`) - They create trigger orders that fire only when the trigger price is reached - They are reduce-only — they close the position, not open a new one - For longs: `--sl` triggers on price drop, `--tp` on price rise - For shorts: `--sl` triggers on price rise, `--tp` on price drop - `--tp`/ `--sl` are for opening orders. To close an existing position, use `position close-market`, `position close-limit`, or `position tpsl` - Setting new TP/SL on a position with existing ones automatically cancels the old orders first - If TP/SL replacement fails after the old order was cancelled, the position may be left temporarily unprotected. If the CLI returns `TPSL_ERROR`, immediately verify current state with `byreal-perps-cli position tpsl ` and then re-apply the missing TP/SL. ### Typical Execution Flows #### Open a new position When the user says "open a $20 BTC long at 5x" or "open a $20 SOL short", the correct flow is: get price, set leverage, compute size, emit a pre-execute summary as a **confirmation gate** and stop the turn, then on the next turn (after the user confirms) place the order. 1. **Get the live coin price** ``` byreal-perps-cli signal detail -o json ``` 2. **Set leverage before placing the order** ``` byreal-perps-cli position leverage ``` 3. **Compute size:** `size = usd_notional / data.price` (e.g., $20 / 2327.8 ≈ 0.00859 ETH). Use the notional from the user and the price from step 1. 4. **Emit the pre-execute summary and stop the turn (confirmation gate).** Write the summary below to the user, then end your turn without calling any tool. Only run step 5 on the next turn, after the user replies with a go-ahead (e.g., "yes", "confirm", "go"). ``` Market: Side: Size: (~$ notional) Leverage: x Margin Mode: Est. liquidation: ~$ (rough, excludes mmr) ``` Read `Leverage` from the value you set in step 2. Read `Margin Mode` from the `marginType` column; don't guess. Estimate liquidation from the step 1 price and the leverage: long ≈ `price × (1 − 1/leverage)`, short ≈ `price × (1 + 1/leverage)`. This is a rough figure that excludes maintenance margin — the precise `liquidationPx` shows up in `position list` after opening (report it in step 6). If the user wants to change a field, loop back to the relevant step and re-emit the summary before waiting again. 5. **Open the position:** ``` byreal-perps-cli order market ``` 6. **Report the result** from the CLI's returned confirmation. ##### Worked gate example — copy this shape exactly The two turns below are the expected pattern for any opening order. The turn boundary is the most important part: turn 1 ends *with the summary*, no `order market` call. The `order market` tool call only happens on turn 2, after the user replies "go" / "confirm" / "yes". ``` ===== User message ===== 帮我开一个 $15 的 ETH 多单 ===== Turn 1 (assistant) ===== [tool] signal detail ETH -o json → data.price = 2327.80 [tool] position leverage ETH 3 [compute] size = 15 / 2327.80 ≈ 0.00644 ETH Reply to user (summary only, no order placed): Market: main Side: long Size: 0.00644 ETH (~$15 notional) Leverage: 3x Margin Mode: cross Est. liquidation: ~$1552 (rough, excludes mmr) Reply "go" / "confirm" to place the order, or tell me what to change. [end turn — DO NOT call order market in this turn] ===== User message ===== go ===== Turn 2 (assistant) ===== [tool] order market long 0.00644 ETH Reply to user: [CLI confirmation + liquidationPx from position list] ``` Failure mode to avoid (observed in production): calling `signal detail` → `order market` in the same turn, then apologizing to the user afterwards. The summary-and-stop pattern above is what actually prevents that — the `order market` call MUST be on a different turn from the summary, gated by the user's reply. #### Open a new position with TP/SL ``` # 1. Get the live coin price byreal-perps-cli signal detail -o json # 2. Set leverage first if the user specified one byreal-perps-cli position leverage # 3. Open the position with attached TP/SL byreal-perps-cli order market --tp --sl ``` Execution rule: 1. For a new position with stop-loss / take-profit, attach --tp and --sl to the opening order. 2. Do not translate stop-loss intent into a standalone sell order. 3. Use position tpsl only when the position already exists. 4. Same as "Open a new position". In step 4's summary, add a `TP: / SL: ` line (only the side the user asked for). In step 5, attach `--tp` / `--sl` to the order, matching the summary exactly. #### Close an existing position When the user says "close my BTC position" or "close my SOL short", do not jump straight to a close command. Check the live position first so you know whether the coin is open, what side it is, and how large it is. ``` # 1. Check the existing position byreal-perps-cli position list --coin -o json # 2a. If a position exists and the user just wants to close it now byreal-perps-cli position close-market # 2b. If the user wants to close only part of it byreal-perps-cli position close-market --size # 2c. If the user gives a target exit price byreal-perps-cli position close-limit ``` Execution rule: 1. Read `position list` first. 2. If no position exists for that coin, stop and report that there is no open position. 3. If the user says "close my \ position" with no price, use `position close-market `. 4. If the user provides an exit price, use `position close-limit `. 5. If the user says "close half" or gives a partial amount, use `--size `. #### Add or update TP/SL on an existing position ``` # 1. Confirm the position exists byreal-perps-cli position list --coin -o json # 2. Check existing TP/SL byreal-perps-cli position tpsl # 3. Apply the new TP/SL byreal-perps-cli position tpsl --tp --sl ``` Execution rule: 1. Confirm the position exists first. 2. Use `position tpsl ` for an existing position, not a new sell/buy order. 3. If `TPSL_ERROR` occurs, immediately re-check with `position tpsl `. #### Check account state before trading ``` # Show account balances and margin byreal-perps-cli account info # Show current open positions byreal-perps-cli position list # Show current open orders byreal-perps-cli order list ``` Execution rule: 1. Use `account info` when the user asks about balance, available margin, or account value. 2. Use `position list` when the user asks what positions are open. 3. Use `order list` when the user asks about resting orders. #### Review recent trade activity ``` # Show the latest fills byreal-perps-cli account history # Show more fills byreal-perps-cli account history --limit 50 ``` Execution rule: 1. Use `account history` for recent fills and executed trades. 2. Increase `--limit` only when the user wants a longer trade history window. #### Close all positions ``` # 1. Check open positions first byreal-perps-cli position list # 2. Close everything byreal-perps-cli position close-all -y ``` Execution rule: 1. Review `position list` first so the user knows what will be closed. 2. Use `close-all` only when the user explicitly wants every open position closed. 3. After `close-all`, verify with `position list`. If any position remains, do not assume the account is flat — re-check and, if needed, run another close command for the remaining coin(s). ### Installation ``` # Check if already installed which byreal-perps-cli && byreal-perps-cli --version # Install npm install -g @byreal-io/byreal-perps-cli ``` ### Credentials - Trading commands require account initialization via `byreal-perps-cli account init` - `--method token` (default): reads `~/.openclaw/realclaw-config.json`, no private key needed - `--method generate`: requires an EVM private key — materially more sensitive than the token method. If token method fails, inform the user that automatic setup failed and manual intervention is needed. Do not offer to run `--method generate`. - Signal commands ( `signal scan`, `signal detail`): no account required ### Account Recovery If local perps account state appears broken or expired: 1. Try `byreal-perps-cli account init` again first. 2. If the error mentions missing or invalid OpenClaw config, inspect `~/.openclaw/realclaw-config.json`. 3. If account selection or local state still looks corrupted, inspect the local DB at `~/.byreal-perps/perps.db`. 4. Only if the user explicitly wants a local reset, remove or replace the local DB and then re-run `account init`. Do not delete `~/.byreal-perps/perps.db` silently. Treat it as destructive local recovery. ### Notes 1. **`-o json` only for parsing** — when showing results to the user, omit it and let the CLI's built-in tables render. Don't fetch JSON then re-draw tables yourself. 2. **Never display private keys** — use keypair paths only. 3. **Never call the SDK directly** — don't write `node -e` / `tsx -e` scripts that import `@nktkas/hyperliquid` or `viem`. The SDK is bundled inside the CLI; calling it externally causes CJS/ESM compatibility errors and bypasses the CLI's account selection, locally stored agent key handling, and transport/config setup. ### Error Codes Most JSON success responses use this shape: ``` { "success": true, "meta": { "timestamp": "...", "version": "..." }, "data": { "...": "..." } } ``` Read command-specific fields from `data.*`, for example `data.price` from `signal detail`. JSON caveat: some commands still have noisy edge cases. In particular, `account init` and `position close-all` failure/no-op paths may print extra text instead of a perfectly clean JSON-only payload. For machine parsing, prefer read-only commands like `signal detail`, `signal scan`, `order list`, `position list`, and `account info`. For those noisy commands, treat JSON as best-effort and verify the resulting state with a follow-up read command. Common CLI error codes in JSON mode: - `ACCOUNT_INIT_ERROR` — account setup failed - `ACCOUNT_ERROR` — account info/history fetch failed - `ORDER_ERROR` — market/limit order placement failed - `ORDER_LIST_ERROR` — open-order listing failed - `CANCEL_ERROR` — order cancellation failed - `POSITION_ERROR` — position listing failed - `LEVERAGE_ERROR` — leverage update failed - `MARGIN_MODE_ERROR` — margin mode switch failed - `TPSL_ERROR` — TP/SL view/set/cancel failed - `CLOSE_ERROR` — position close command failed - `SIGNAL_ERROR` — signal scan/detail failed - `CLI_ERROR` — top-level CLI failure before command-specific handling - `UNKNOWN_ERROR` — fallback code when the command does not provide a specific error code TP/SL recovery flow: 1. If a TP/SL update returns `TPSL_ERROR`, do not assume protection is still active. 2. Check the live state: `byreal-perps-cli position tpsl ` 3. If TP or SL is missing, submit the needed `position tpsl` command again. ### Commands Reference #### Account Management ``` # Initialize perps account (default: token method, no private key needed) byreal-perps-cli account init # Initialize via generate method (requires EVM wallet private key) byreal-perps-cli account init --method generate # Show account info & balance byreal-perps-cli account info # Show recent trade history byreal-perps-cli account history ``` #### Orders ``` # Market order (side: buy/sell/long/short, size in coin units) byreal-perps-cli order market # Market buy with bracket TP/SL byreal-perps-cli order market buy 0.01 BTC --tp 110000 --sl 90000 # Market order with stop-loss only byreal-perps-cli order market long 1 ETH --sl 3500 # Plain market order byreal-perps-cli order market short 0.5 SOL # HIP-3 / xyz market example byreal-perps-cli order market long 5 xyz:GOLD # Limit order byreal-perps-cli order limit byreal-perps-cli order limit sell 1 ETH 4000 byreal-perps-cli order limit buy 0.01 BTC 95000 --tp 110000 --sl 90000 # List open orders byreal-perps-cli order list # Cancel an order byreal-perps-cli order cancel # Cancel all orders byreal-perps-cli order cancel-all -y ``` #### Positions ``` # List open positions byreal-perps-cli position list # Set leverage (1-50x) byreal-perps-cli position leverage # Switch margin mode (cross / isolated) byreal-perps-cli position margin-mode # Set TP/SL on existing position byreal-perps-cli position tpsl --tp --sl # Set only stop-loss on existing position byreal-perps-cli position tpsl BTC --sl 90000 # HIP-3 / xyz TP/SL example byreal-perps-cli position tpsl xyz:GOLD --tp 3100 --sl 2700 # View existing TP/SL orders for a position byreal-perps-cli position tpsl # Cancel existing TP/SL orders byreal-perps-cli position tpsl --cancel-tp byreal-perps-cli position tpsl --cancel-sl # Close at market price (full or partial) byreal-perps-cli position close-market # Close with limit order byreal-perps-cli position close-limit # Close all positions byreal-perps-cli position close-all -y ``` #### Market Signals ``` # Scan markets for trading signals byreal-perps-cli signal scan # Detailed technical analysis byreal-perps-cli signal detail ``` Rate-limit guidance: - `signal scan` already batches internally; prefer it over looping `signal detail` across many coins. - Do not fan out dozens of `signal detail` calls at once. Run them sequentially or in small batches. - If repeated signal calls start failing with `SIGNAL_ERROR`, slow down and retry after a short pause instead of hammering the public API. #### Update ``` # Check for available CLI updates byreal-perps-cli update check # Install the latest CLI version byreal-perps-cli update install ``` Source: [SKILL.md on GitHub](https://github.com/byreal-git/byreal-perps-cli/blob/cd142b6b5604b68012f16b667ab934f94506bb22/skills/byreal-perps-cli/SKILL.md) ## Third-party checks
2 warnings4mo4 checks · Risk SAFE - Gen Agent Trust Hub4mo This trading tool skill instructs the AI to bypass standard safety behaviors, such as providing financial risk warnings or refusing potentially risky commands. It utilizes a vendor-provided CLI tool to execute trades on the Hyperliquid exchange. While it follows good practices for handling private keys locally, the instructions to ignore safety filters and the reliance on untrusted user input for command parameters present minor security risks. - Socket4mo No alerts - Snyk4mo Risk: MEDIUM · 1 issue - Runlayer6mo 1/1 file flagged
## Provenance [Signed by skilld at cd142b6.](https://github.com/byreal-git/byreal-perps-cli/commit/cd142b6b5604b68012f16b667ab934f94506bb22 "cd142b6b5604b68012f16b667ab934f94506bb22") This ties the file your Agent reads to that commit on GitHub. It does not review the instructions. Last checked against GitHub 2 months ago. Steadyupdated 5 months ago ## Capability
Other metadata
metadata
``` { "openclaw": { "homepage": "https://github.com/byreal-git/byreal-perps-cli", "requires": { "bins": [ "byreal-perps-cli" ] }, "install": [ { "kind": "node", "package": "@byreal-io/byreal-perps-cli", "global": true } ] } } ```
## README badge ![README badge for byreal-git/byreal-perps-cli](https://skilld.dev/b/byreal-git/byreal-perps-cli?theme=light&label=0) ## Related skills - - - - - -