Skip to content

Execution

Hyperliquid normalTpsl vs positionTpsl Orders

Follow a partial Hyperliquid entry through cancellation, then compare fixed-size and whole-position exits against the quantity actually left to close.

Ivory blocks in a loose fixed bracket beside a fitted screw clamp with a lime adjustment wedge.
Illustration for execution; examples in this article are educational.

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:

ControlQuestion it answersWhat to verify
normalTpsl groupingWhich entry owns these children?Parent identity and activation event
positionTpsl groupingWhich position do these exits concern?Whole-position or explicit-size configuration
Trigger conditionWhen may the exit activate?Reference price and threshold
Reduce-onlyMay execution increase exposure?Correct side and current reducible quantity
Execution price/typeWhich 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.

ObservationCumulative entry fillsParent remainder workingAttached children
Parent accepted0 ETH1.20 ETHAwait parent activation
First fill: 0.45 ETH0.45 ETH0.75 ETHStill await parent activation
Second fill: 0.35 ETH0.80 ETH0.40 ETHStill await parent activation
Trader cancels remainder0.80 ETH0 ETH workingChildren 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 fillQuantityQuoted fill notional
2,390 USDT/ETH0.20 ETH478 USDT
2,380 USDT/ETH0.30 ETH714 USDT
Total0.50 ETH1,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.”

  1. 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.

  2. Count distinct fills and read the current position. Separate requested, filled, canceled and remaining quantities. The documented clearinghouseState query supplies perpetual positions. Record when each observation was obtained; separate calls should not be assumed to form one atomic snapshot. Perpetual position query.

  3. Inspect the exit configuration and status. frontendOpenOrders exposes fields including isPositionTpsl, isTrigger, reduceOnly, sz and origSz. Order status distinguishes triggered, marginCanceled, reduceOnlyCanceled and siblingFilledCanceled. Retrieve evidence for the specific component; disappearance alone does not identify what happened. Order inspection fields and statuses.

  4. 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.

  5. Reconcile after the change. Compare the new position with surviving orders and unresolved requests. The documented orderUpdates and userFills streams 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.

Keep the context with the example.

Each worked example is illustrative, with its sources and assumptions in the article. Read our editorial standards for authorship, verification and corrections.