Hyperliquid normalTpsl links fixed-size TP/SL children to a parent order; positionTpsl attaches exits to a position. A partial entry does not activate its parent-attached children by itself. Position TP/SL can target the whole position at trigger or a fixed configured size, so grouping and size policy must be checked together.
TP/SL means take profit and stop loss. The practical difference appears when an entry fills only partly and somebody cancels the remainder. The account already has exposure, while its planned children can be canceled. A second distinction appears after a manual reduction: a whole-position exit and a fixed quantity can now cover different amounts.
This guide follows the public Hyperliquid rules checked on 29 October 2026 and a pinned official Python SDK snapshot. The illustration concerns a native ETH perpetual position in a conventional perps account. It does not model unified-account balances, portfolio margin, spot or builder-deployed markets.
For native ETH, Hyperliquid's contract specifications distinguish USDT-denominated prices from USDC collateral and PnL accounting. No USDC/USDT exchange conversion is applied. Prices below use USDT per ETH; modeled realized PnL uses USDC.
Separate grouping, trigger and reduction
The exchange endpoint specification puts grouping on the order action. Each component separately carries size, price, a reduce-only flag and an order type. A trigger type also has triggerPx, isMarket and tpsl, which selects take-profit or stop-loss.
These fields answer different questions:
| Control | Question it answers | What to verify |
|---|---|---|
normalTpsl grouping | Which entry owns these children? | Parent identity and activation event |
positionTpsl grouping | Which position do these exits concern? | Whole-position or explicit-size configuration |
| Trigger condition | When may the exit activate? | Reference price and threshold |
| Reduce-only | May execution increase exposure? | Correct side and current reducible quantity |
| Execution price/type | Which fills are acceptable? | Market or limit behavior and remaining quantity |
The official Python TP/SL example places the parent first, followed by opposite-side, reduce-only trigger children, then submits them through bulk_orders with normalTpsl. The pinned serializer preserves grouping in the action and maps the reduction flag to the wire field r.
That code establishes request construction. It does not disclose the matching engine's ordering of simultaneous fills, triggers and cancellations. The general OCO and bracket guide supplies the vocabulary; Hyperliquid's own lifecycle rules determine this example.
Follow an incomplete normalTpsl entry
Hyperliquid documents parent-attached TP/SL as fixed to the parent's size. Children are placed when the parent fully fills, or when a partially filled parent is canceled for insufficient margin. Trader cancellation of a partially filled parent cancels its children. Hyperliquid TP/SL lifecycle.
Consider a hypothetical limit buy for 1.20 ETH at 2,500 USDT per ETH, with attached take-profit and stop-loss children. Start with no ETH position and no competing orders. Assume every stated price and quantity meets the market's metadata rules. The two entry fills both occur at 2,500.
| Observation | Cumulative entry fills | Parent remainder working | Attached children |
|---|---|---|---|
| Parent accepted | 0 ETH | 1.20 ETH | Await parent activation |
| First fill: 0.45 ETH | 0.45 ETH | 0.75 ETH | Still await parent activation |
| Second fill: 0.35 ETH | 0.80 ETH | 0.40 ETH | Still await parent activation |
| Trader cancels remainder | 0.80 ETH | 0 ETH working | Children canceled |
The fourth row leaves a 0.80 ETH long. Canceling the unfilled 0.40 ETH removes an instruction to acquire more; it does not sell the quantity already bought. The position needs a fresh exit decision after its original children are canceled.
The arithmetic separates three records: requested entry was 1.20 ETH, executed entry was 0.80 ETH, and canceled entry remainder was 0.40 ETH. Treating the canceled parent as a canceled trade would erase actual exposure. Treating the attached child size as active coverage would make a different error.
Change the cancellation reason
Return to the third row and take an alternative branch. If the remaining 0.40 ETH fills, the parent reaches 1.20 ETH and its children are placed under the documented full-fill rule.
In a separate branch, suppose the partially filled parent is canceled specifically for insufficient margin. The documentation says its children are placed as though the parent had fully filled. Their parent-based nominal size therefore must be distinguished from the 0.80 ETH position actually acquired.
In the insufficient-margin branch, the nominal 1.20 ETH child cannot establish a completed 1.20 ETH reduction of a 0.80 ETH long. Hyperliquid defines reduce-only as reducing a current position rather than opening the opposite direction. The reduce-only explanation develops that exposure constraint; the official order-type rules establish it for Hyperliquid.
Do not turn that constraint into an assumed automatic resizing algorithm. Acceptance, cancellation and executed size need their own evidence.
Position TP/SL still needs a size policy
Continue from the trader-cancellation branch with the 0.80 ETH long. The operator now creates a position-associated exit. Hyperliquid's position form defaults to attempting the entire position at trigger; an explicitly configured quantity stays fixed after placement. Position TP/SL sizing.
Compare two alternative configurations: a whole-position stop, or a fixed 0.30 ETH stop. Before either triggers, assume a separate valid manual sell closes 0.30 ETH at 2,560. The long falls to:
0.80 − 0.30 = 0.50 ETH
A whole-position stop now attempts to close the current 0.50 ETH. A fixed 0.30 ETH stop still requests 0.30 ETH. If that fixed exit fills completely and nothing else trades, 0.20 ETH remains.
Both configurations can be intentional. A fixed exit suits a specified partial reduction; a whole-position exit expresses an intention to flatten the position present at activation. The configuration must match the intended outcome.
A fixed exit originally set to 0.80 ETH presents another case: it remains a larger request than the current 0.50 ETH long. Reduce-only constrains the possible exposure change, but does not establish that the oversized request will be accepted or filled for exactly 0.50 ETH.
For an API integration, retain the actual accepted size configuration alongside grouping. The string positionTpsl alone is insufficient evidence that the request expresses the interface's whole-position default. Verify the accepted mode through returned order details and a controlled position-size change.
A mark-price trigger does not establish the fill price
Hyperliquid uses mark price to trigger TP/SL. Its support documentation separately explains execution and the possibility of a triggered limit remaining unfilled after a price gap. A trade-price chart and a mark-price trigger record answer different questions. Official TP/SL execution explanation.
Take the whole-position branch with 0.50 ETH left. Assume a sell stop-limit has a trigger of 2,400 and a sell limit of 2,350. Mark passes below the trigger. For this illustration only, assume the resulting valid order fills completely:
| Assumed fill | Quantity | Quoted fill notional |
|---|---|---|
| 2,390 USDT/ETH | 0.20 ETH | 478 USDT |
| 2,380 USDT/ETH | 0.30 ETH | 714 USDT |
| Total | 0.50 ETH | 1,192 USDT |
The average fill price is 1,192 ÷ 0.50 = 2,384 USDT/ETH. Both fills meet the illustrative 2,350 sell limit. The trigger was 2,400, and neither execution occurred there.
The earlier manual close produced 18 USDC of gross price profit: 0.30 × (2,560 − 2,500). The stop fills produce a combined gross price loss of 58 USDC relative to their 2,500 entry. Together, the two exits realize a 40 USDC gross price loss and leave zero ETH position.
These are exact decimal calculations over invented fills. Fees and funding are excluded. Use the Hyperliquid funding-rate versus payment ledger to account for that separate cash flow. A full permitted fill is an assumption in this example; a real stop-limit can leave some or all of the position open.
Validate the transition before replacing exits
A usable validation method compares the intended transition with the observed account state. Keep a record for each parent and child rather than one combined label such as “bracket active.”
-
Fix the account and market context. Query the actual master or subaccount address. Hyperliquid warns that an agent wallet's address can return an empty account result. For this native-perp example, keep the first-perp-DEX context consistent across observations. Account query identity.
-
Count distinct fills and read the current position. Separate requested, filled, canceled and remaining quantities. The documented
clearinghouseStatequery supplies perpetual positions. Record when each observation was obtained; separate calls should not be assumed to form one atomic snapshot. Perpetual position query. -
Inspect the exit configuration and status.
frontendOpenOrdersexposes fields includingisPositionTpsl,isTrigger,reduceOnly,szandorigSz. Order status distinguishestriggered,marginCanceled,reduceOnlyCanceledandsiblingFilledCanceled. Retrieve evidence for the specific component; disappearance alone does not identify what happened. Order inspection fields and statuses. -
Check the whole response contract. Hyperliquid documents component-level errors and payload-level pre-validation failures. Invalid trigger prices and invalid reduction behavior are separate failure categories. A recognized grouping value does not prove every child was accepted. Exchange error responses.
-
Reconcile after the change. Compare the new position with surviving orders and unresolved requests. The documented
orderUpdatesanduserFillsstreams provide different evidence; distinguish initial snapshots from new fills to avoid counting an execution twice. Account-data subscriptions.
Preserve decimal values through this record. The API decimal-precision guide explains why a tidy display does not prove the submitted quantity survived conversion.
For a vault account, also distinguish its trading position from a depositor's withdrawal claim. The Hyperliquid HLP versus user-vault withdrawal comparison covers that separate account boundary; a trader's exit status cannot establish a depositor's withdrawal state.
Finally, rehearse the incomplete-entry cancellation and the manual-reduction branches in a controlled environment. Include a partial exit and inspect both siblings afterward: the public status vocabulary does not specify every partial-fill interleaving. A completed validation record should show the position left to close, the exits currently accepted, their size policy and any outcome still unresolved.
