docs(trade): spell out --reduce-only side semantics (close = opposite side)#61
Open
psmiratisu wants to merge 1 commit into
Open
docs(trade): spell out --reduce-only side semantics (close = opposite side)#61psmiratisu wants to merge 1 commit into
psmiratisu wants to merge 1 commit into
Conversation
… side)
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 <noreply@anthropic.com>
Zuhwa
approved these changes
Jul 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
We're seeing a high volume of
Reduce only order would increase positionrejections from Hyperliquid. Root cause: the--reduce-onlyhelp text ("Only reduce an existing perp position") and the README example ("Reduce-only (close part of a position)") never state the one rule that matters — the order side must be the opposite of the position. An LLM agent reasoning "my position is long, so --side long" when closing gets this rejection 100% of the time, and the docs are exactly what agents read to compose these commands.Change
--reduce-onlyhelp string now reads: "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."Docs-only; no behavior change.
tsc --noEmitclean.Companion server-side fix: internal-trading-bot#59 adds a plan-time position check so a wrong reduce-only order fails instantly with the correct close order spelled out, instead of after the full sign roundtrip.
🤖 Generated with Claude Code
Note
Low Risk
Documentation-only changes to README and Commander option help; no trade execution or validation logic modified.
Overview
Clarifies Hyperliquid perp
--reduce-onlyusage in docs and CLI help so agents stop submitting orders with the wrong--side.The
--reduce-onlyoption description inacp tradenow states that--sidemust be opposite to the open position (short to close a long, long to close a short), and warns not to use the flag when opening or adding.The README perp section replaces a single reduce-only example with both close directions and adds a callout that mismatched sides trigger Hyperliquid’s "Reduce only order would increase position" rejection.
No runtime or API behavior changes — documentation and help text only.
Reviewed by Cursor Bugbot for commit 2c78eb9. Bugbot is set up for automated code reviews on this repo. Configure here.