From 2c78eb93832436990b5c09110a91f3d601669810 Mon Sep 17 00:00:00 2001 From: brianna Date: Thu, 2 Jul 2026 21:22:25 +0800 Subject: [PATCH] docs(trade): spell out --reduce-only side semantics (close = opposite side) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The help text ("Only reduce an existing perp position") and README example never stated the rule that matters: a reduce-only order's --side must be the OPPOSITE of the position (close a long with --side short, close a short with --side long), and the flag must never be set when opening. LLM agents reading the docs were sending side == position when closing, which HL rejects with "Reduce only order would increase position" — our most frequent perp error. Co-Authored-By: Claude Fable 5 --- README.md | 10 ++++++++-- src/commands/trade.ts | 8 +++++++- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0f8782a..2a52945 100644 --- a/README.md +++ b/README.md @@ -788,10 +788,16 @@ acp trade --side short --token ETH --size 0.5 --price 4000 --post-only # Same shape for an equity, FX, or commodity perp — just change the symbol acp trade --side long --token --size 1 --leverage 3 -# Reduce-only (close part of a position) -acp trade --side short --token BTC --size 0.01 --reduce-only +# Close (part of) a position: --reduce-only with --side OPPOSITE to the position. +# Closing a LONG is a SHORT order; closing a SHORT is a LONG order. +acp trade --side short --token BTC --size 0.01 --reduce-only # closes a BTC long +acp trade --side long --token BTC --size 0.01 --reduce-only # closes a BTC short ``` +> `--reduce-only` only shrinks an existing position — never set it when opening or +> adding. If the side matches the position (or there's no position), Hyperliquid +> rejects the order with "Reduce only order would increase position". + **Hyperliquid — account & withdraw:** ```bash diff --git a/src/commands/trade.ts b/src/commands/trade.ts index 3551c17..203e59c 100644 --- a/src/commands/trade.ts +++ b/src/commands/trade.ts @@ -268,7 +268,13 @@ export function registerTradeCommands(program: Command): void { .option("--size ", "Perp order size in token units") .option("--leverage ", "Set leverage for this token before a perp order") .option("--isolated", "Use isolated margin when setting leverage", false) - .option("--reduce-only", "Only reduce an existing perp position", false) + .option( + "--reduce-only", + "Close/shrink an existing perp position. --side must be the OPPOSITE of the position " + + "(close a long with --side short, close a short with --side long). " + + "Never set this when opening or adding to a position — HL rejects it.", + false + ) .option("--dry-run", "Preview the trade (route, size, margin, fees) without signing or submitting anything", false) .action(async (opts, cmd) => { const json = isJson(cmd);