> For the complete documentation index, see [llms.txt](https://docs.pearprotocol.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pearprotocol.io/api-integration/api-specification/positions.md).

# Positions

## List processed open positions

> Returns processed open positions for the authenticated user

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"OpenPositionProcessedDto":{"type":"object","properties":{"positionId":{"type":"string","description":"Position identifier"},"address":{"type":"string","description":"User wallet address"},"pearExecutionFlag":{"type":"string","description":"Pear execution flag","enum":["FULLY_PEAR","PARTIAL","FULLY_EXTERNAL"]},"stopLoss":{"description":"Stop loss trigger","nullable":true,"allOf":[{"$ref":"#/components/schemas/TpSlThreshold"}]},"takeProfit":{"description":"Take profit trigger","nullable":true,"allOf":[{"$ref":"#/components/schemas/TpSlThreshold"}]},"entryRatio":{"type":"number","description":"Weighted entry ratio"},"markRatio":{"type":"number","description":"Weighted mark ratio"},"entryPriceRatio":{"type":"number","description":"Entry price ratio (only for 1 long x 1 short)"},"markPriceRatio":{"type":"number","description":"Mark price ratio (only for 1 long x 1 short)"},"entryPositionValue":{"type":"number","description":"Total entry USD value"},"positionValue":{"type":"number","description":"Total current USD value"},"marginUsed":{"type":"number","description":"Total margin used"},"unrealizedPnl":{"type":"number","description":"Total unrealized PnL (USD)"},"unrealizedPnlPercentage":{"type":"number","description":"Unrealized PnL percentage relative to margin used"},"longAssets":{"description":"Long assets","type":"array","items":{"$ref":"#/components/schemas/PositionAssetDetailProcessedDto"}},"shortAssets":{"description":"Short assets","type":"array","items":{"$ref":"#/components/schemas/PositionAssetDetailProcessedDto"}},"createdAt":{"type":"string","description":"Creation timestamp","format":"date-time"},"updatedAt":{"type":"string","description":"Last update timestamp","format":"date-time"}},"required":["positionId","address","pearExecutionFlag","stopLoss","takeProfit","entryRatio","markRatio","entryPositionValue","positionValue","marginUsed","unrealizedPnl","unrealizedPnlPercentage","longAssets","shortAssets","createdAt","updatedAt"]},"TpSlThreshold":{"type":"object","properties":{"type":{"type":"string","description":"Trigger type","enum":["PERCENTAGE","DOLLAR","POSITION_VALUE","PRICE","PRICE_RATIO","WEIGHTED_RATIO"]},"value":{"type":"number","description":"Trigger value for the specified type"},"isTrailing":{"type":"boolean","description":"Enable trailing behavior for this TP/SL"},"trailingDeltaValue":{"type":"number","description":"Trailing delta value based on trigger type"},"trailingActivationValue":{"type":"number","description":"Activation value to start trailing"}},"required":["type"]},"PositionAssetDetailProcessedDto":{"type":"object","properties":{"coin":{"type":"string","description":"Asset symbol"},"entryPrice":{"type":"number","description":"Entry price"},"actualSize":{"type":"number","description":"Actual size filled"},"leverage":{"type":"number","description":"Leverage applied to this asset"},"marginUsed":{"type":"number","description":"Margin used for this asset (USD)"},"positionValue":{"type":"number","description":"Current USD value"},"unrealizedPnl":{"type":"number","description":"Unrealized PnL (USD)"},"entryPositionValue":{"type":"number","description":"Entry USD value"},"fundingPaid":{"type":"number","description":"Total funding paid/received for this asset (USD)"},"targetWeight":{"type":"number","description":"Target weight of asset in position (decimal, 0-1)"}},"required":["coin","entryPrice","actualSize","leverage","marginUsed","positionValue","unrealizedPnl","entryPositionValue","targetWeight"]}}},"paths":{"/positions":{"get":{"description":"Returns processed open positions for the authenticated user","operationId":"PositionsController_getOpenPositions","parameters":[],"responses":{"200":{"description":"Processed open positions fetched successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OpenPositionProcessedDto"}}}}}},"summary":"List processed open positions","tags":["Positions"]}}}}
```

## Create a new pair trading position with order

> Create a pair trading position with various execution types: MARKET (immediate execution), TRIGGER (conditional execution), TWAP (time-weighted average), or LADDER (multiple ratio levels)

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"CreatePositionRequestDto":{"type":"object","properties":{"slippage":{"type":"number","description":"Slippage tolerance percentage (0.01 = 1%)","minimum":0.001,"maximum":0.1},"executionType":{"type":"string","description":"Order execution type","enum":["SYNC","MARKET","TRIGGER","TWAP","LADDER","TP","SL","SPOT_MARKET","SPOT_LIMIT","SPOT_TWAP"]},"leverage":{"type":"number","description":"Applied leverage","minimum":1,"maximum":100},"usdValue":{"type":"number","description":"Position size in USD","minimum":1},"longAssets":{"description":"Long assets configuration - array of assets to go long on. Can be empty for short-only positions.","type":"array","items":{"$ref":"#/components/schemas/PairAssetDto"}},"shortAssets":{"description":"Short assets configuration - array of assets to go short on. Can be empty for long-only positions.","type":"array","items":{"$ref":"#/components/schemas/PairAssetDto"}},"triggerValue":{"type":"string","description":"Required trigger threshold for TRIGGER orders (price, dominance, ratios, etc.)"},"triggerType":{"type":"string","description":"Trigger type for TRIGGER orders (PRICE, PRICE_RATIO, WEIGHTED_RATIO, BTC_DOM, CROSS_ASSET_PRICE, PREDICTION_MARKET_OUTCOME)","enum":["PRICE","PRICE_LIMIT","PRICE_RATIO","WEIGHTED_RATIO","BTC_DOM","CROSS_ASSET_PRICE","PREDICTION_MARKET_OUTCOME"]},"direction":{"type":"string","description":"Direction for TRIGGER orders","enum":["MORE_THAN","LESS_THAN"]},"assetName":{"type":"string","description":"Asset to monitor when triggerType is CROSS_ASSET_PRICE"},"marketCode":{"type":"string","description":"Market code to monitor when triggerType is PREDICTION_MARKET_OUTCOME"},"marketSource":{"type":"string","description":"Market source for prediction market orders","enum":["KALSHI","HYPERLIQUID"]},"twapDuration":{"type":"number","description":"TWAP duration in minutes (required for TWAP orders)"},"twapIntervalSeconds":{"type":"number","description":"TWAP interval in seconds (time between chunks). Defaults to 30 seconds if not provided.","minimum":1,"maximum":3600},"randomizeExecution":{"type":"boolean","description":"Randomize TWAP execution timing","default":false},"ladderConfig":{"description":"Ladder order configuration","allOf":[{"$ref":"#/components/schemas/LadderConfigDto"}]},"stopLoss":{"description":"Stop loss trigger. PERCENTAGE: % change vs entry; DOLLAR: fixed USD change; POSITION_VALUE: % change of position value.","nullable":true,"allOf":[{"$ref":"#/components/schemas/TpSlThreshold"}]},"takeProfit":{"description":"Take profit trigger. PERCENTAGE: % change vs entry; DOLLAR: fixed USD change; POSITION_VALUE: % change of position value.","nullable":true,"allOf":[{"$ref":"#/components/schemas/TpSlThreshold"}]},"referralCode":{"type":"string","description":"Referral code to be attached to user address if user has no referral code"}},"required":["slippage","executionType","leverage","usdValue"]},"PairAssetDto":{"type":"object","properties":{"asset":{"type":"string","description":"Asset symbol"},"weight":{"type":"number","description":"Weight allocation for this asset (0.0001 to 1.0). If not provided, weights will be evenly distributed.","minimum":0.0001,"maximum":1}},"required":["asset"]},"LadderConfigDto":{"type":"object","properties":{"ratioStart":{"type":"number","description":"Starting ratio for the ladder","minimum":0.01},"ratioEnd":{"type":"number","description":"Ending ratio for the ladder","minimum":0.01},"numberOfLevels":{"type":"number","description":"Number of levels in the ladder","minimum":2,"maximum":50}},"required":["ratioStart","ratioEnd","numberOfLevels"]},"TpSlThreshold":{"type":"object","properties":{"type":{"type":"string","description":"Trigger type","enum":["PERCENTAGE","DOLLAR","POSITION_VALUE","PRICE","PRICE_RATIO","WEIGHTED_RATIO"]},"value":{"type":"number","description":"Trigger value for the specified type"},"isTrailing":{"type":"boolean","description":"Enable trailing behavior for this TP/SL"},"trailingDeltaValue":{"type":"number","description":"Trailing delta value based on trigger type"},"trailingActivationValue":{"type":"number","description":"Activation value to start trailing"}},"required":["type"]},"CreatePositionResponseDto":{"type":"object","properties":{"orderId":{"type":"string","description":"Unique identifier for the initial order"},"fills":{"description":"Fills returned from Hyperliquid for the order","type":"array","items":{"$ref":"#/components/schemas/ExternalFillDto"}}},"required":["orderId"]},"ExternalFillDto":{"type":"object","properties":{"coin":{"type":"string","description":"Asset symbol"},"px":{"type":"string","description":"Fill price"},"sz":{"type":"string","description":"Fill size"},"side":{"type":"string","description":"Side","enum":["B","A"]},"time":{"type":"number","description":"Timestamp in ms"},"dir":{"type":"string","description":"Direction (e.g. Open Long, Close Short)"},"fee":{"type":"string","description":"Fee amount"},"builderFee":{"type":"string","description":"Builder fee"},"startPosition":{"type":"string","description":"Start position size"},"oid":{"type":"string","description":"Order ID"},"tid":{"type":"string","description":"Trade ID"},"cloid":{"type":"string","description":"Client order ID","nullable":true},"hash":{"type":"string","description":"Transaction hash","nullable":true},"feeToken":{"type":"string","description":"Fee token","nullable":true},"liquidation":{"description":"Liquidation details","nullable":true,"allOf":[{"$ref":"#/components/schemas/ExternalLiquidationDto"}]},"closedPnl":{"type":"object","description":"Closed PnL","nullable":true},"crossed":{"type":"object","description":"Whether fill crossed the spread","nullable":true},"twapId":{"type":"object","description":"TWAP order ID","nullable":true}},"required":["coin","px","sz","side","time","dir","fee"]},"ExternalLiquidationDto":{"type":"object","properties":{"liquidatedUser":{"type":"string","description":"Liquidated user address"},"markPx":{"type":"string","description":"Mark price at liquidation"},"method":{"type":"string","description":"Liquidation method"}},"required":["liquidatedUser","markPx","method"]}}},"paths":{"/positions":{"post":{"description":"Create a pair trading position with various execution types: MARKET (immediate execution), TRIGGER (conditional execution), TWAP (time-weighted average), or LADDER (multiple ratio levels)","operationId":"PositionsController_createPosition","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePositionRequestDto"}}}},"responses":{"201":{"description":"Position order created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePositionResponseDto"}}}}},"summary":"Create a new pair trading position with order","tags":["Positions"]}}}}
```

## Close an entire position

> Close a position using MARKET (immediate execution), TWAP (time-weighted average), or TRIGGER (conditional trigger-close order) execution type

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"ClosePositionRequestDto":{"type":"object","properties":{"executionType":{"type":"string","description":"Type of close order","enum":["MARKET","TWAP","TRIGGER"]},"twapDuration":{"type":"number","description":"TWAP duration in minutes - required if executionType is TWAP"},"twapIntervalSeconds":{"type":"number","description":"TWAP interval in seconds (time between close chunks). Defaults to 30 seconds if not provided."},"randomizeExecution":{"type":"boolean","description":"Randomize TWAP execution times - optional for TWAP orders"},"triggerValue":{"type":"string","description":"Trigger threshold for TRIGGER close orders"},"triggerType":{"type":"string","description":"Trigger type for TRIGGER close orders","enum":["PRICE","PRICE_RATIO","WEIGHTED_RATIO","PERCENTAGE","DOLLAR","POSITION_VALUE"]},"direction":{"type":"string","description":"Direction for TRIGGER close orders","enum":["MORE_THAN","LESS_THAN"]},"referralCode":{"type":"string","description":"Referral code to be attached to user address if user has no referral code"}},"required":["executionType"]},"ClosePositionResponseDto":{"type":"object","properties":{"orderId":{"type":"string","description":"Unique identifier for the close order","format":"uuid"},"executionTime":{"type":"string","description":"Execution time for the order"},"orderIds":{"description":"Created trigger order identifiers for TRIGGER close requests","type":"array","items":{"type":"string"}},"chunksScheduled":{"type":"number","description":"Number of TWAP chunks scheduled (only for TWAP orders)"}},"required":["orderId"]}}},"paths":{"/positions/{positionId}/close":{"post":{"description":"Close a position using MARKET (immediate execution), TWAP (time-weighted average), or TRIGGER (conditional trigger-close order) execution type","operationId":"PositionsController_closePosition","parameters":[{"name":"positionId","required":true,"in":"path","description":"Position identifier","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClosePositionRequestDto"}}}},"responses":{"200":{"description":"Position close order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClosePositionResponseDto"}}}}},"summary":"Close an entire position","tags":["Positions"]}}}}
```

## Close all open positions

> Fetches all open positions and closes them sequentially using MARKET or TWAP execution

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"ClosePositionRequestDto":{"type":"object","properties":{"executionType":{"type":"string","description":"Type of close order","enum":["MARKET","TWAP","TRIGGER"]},"twapDuration":{"type":"number","description":"TWAP duration in minutes - required if executionType is TWAP"},"twapIntervalSeconds":{"type":"number","description":"TWAP interval in seconds (time between close chunks). Defaults to 30 seconds if not provided."},"randomizeExecution":{"type":"boolean","description":"Randomize TWAP execution times - optional for TWAP orders"},"triggerValue":{"type":"string","description":"Trigger threshold for TRIGGER close orders"},"triggerType":{"type":"string","description":"Trigger type for TRIGGER close orders","enum":["PRICE","PRICE_RATIO","WEIGHTED_RATIO","PERCENTAGE","DOLLAR","POSITION_VALUE"]},"direction":{"type":"string","description":"Direction for TRIGGER close orders","enum":["MORE_THAN","LESS_THAN"]},"referralCode":{"type":"string","description":"Referral code to be attached to user address if user has no referral code"}},"required":["executionType"]},"CloseAllPositionsResponseDto":{"type":"object","properties":{"results":{"description":"Results for each position close action","type":"array","items":{"$ref":"#/components/schemas/CloseAllPositionsResultDto"}}},"required":["results"]},"CloseAllPositionsResultDto":{"type":"object","properties":{"positionId":{"type":"string","description":"Position identifier"},"success":{"type":"boolean","description":"Whether the close action succeeded"},"orderId":{"type":"string","description":"Order ID created for the close action"},"error":{"type":"string","description":"Error message if the close action failed"}},"required":["positionId","success"]}}},"paths":{"/positions/close-all":{"post":{"description":"Fetches all open positions and closes them sequentially using MARKET or TWAP execution","operationId":"PositionsController_closeAllPositions","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClosePositionRequestDto"}}}},"responses":{"200":{"description":"Close orders created for all positions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloseAllPositionsResponseDto"}}}}},"summary":"Close all open positions","tags":["Positions"]}}}}
```

## POST /positions/{positionId}/adjust

> Adjust position size by reducing or increasing by a specified amount

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"AdjustPositionRequestDto":{"type":"object","properties":{"adjustmentType":{"type":"string","description":"Type of position adjustment (reduce or increase)","enum":["REDUCE","INCREASE"],"default":"REDUCE"},"adjustmentSize":{"type":"number","description":"Percentage of position to adjust (1-100%)","minimum":1,"maximum":100},"executionType":{"type":"string","description":"Type of execution for the adjustment","enum":["MARKET","LIMIT"],"default":"MARKET"},"limitRatio":{"type":"number","description":"Required if executionType is LIMIT"},"referralCode":{"type":"string","description":"Referral code to be attached to user address if user has no referral code"}},"required":["adjustmentType","adjustmentSize","executionType"]},"AdjustPositionResponseDto":{"type":"object","properties":{"orderId":{"type":"string","description":"Unique identifier for the adjustment order","format":"uuid"},"status":{"type":"string","description":"Status of the adjustment order"},"adjustmentType":{"type":"string","description":"Type of adjustment that was made","enum":["REDUCE","INCREASE"]},"adjustmentSize":{"type":"number","description":"Percentage used for position adjustment"},"newSize":{"type":"number","description":"New position size after adjustment"},"executedAt":{"type":"string","description":"Timestamp when the reduction was executed","format":"date-time"}},"required":["orderId","status","adjustmentType","adjustmentSize","newSize","executedAt"]}}},"paths":{"/positions/{positionId}/adjust":{"post":{"operationId":"PositionsController_adjustPosition","parameters":[{"name":"positionId","required":true,"in":"path","description":"Position identifier","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustPositionRequestDto"}}}},"responses":{"200":{"description":"Position adjustment order created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustPositionResponseDto"}}}}},"summary":"Adjust position size by reducing or increasing by a specified amount","tags":["Positions"]}}}}
```

## POST /positions/{positionId}/adjust-advance

> Adjust position to target absolute sizes per asset (advance)

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"AdjustAdvanceItemDto":{"type":"object","properties":{"longAssets":{"description":"Target long assets with absolute sizes","type":"array","items":{"$ref":"#/components/schemas/AdjustAdvanceAssetDto"}},"shortAssets":{"description":"Target short assets with absolute sizes","type":"array","items":{"$ref":"#/components/schemas/AdjustAdvanceAssetDto"}}},"required":["longAssets","shortAssets"]},"AdjustAdvanceAssetDto":{"type":"object","properties":{"asset":{"type":"string","description":"Asset symbol"},"size":{"type":"number","description":"Target absolute size for this asset","minimum":0}},"required":["asset","size"]},"AdjustAdvanceResponseDto":{"type":"object","properties":{"orderId":{"type":"string","description":"Order identifier"},"status":{"type":"string","description":"Order status"},"executedAt":{"type":"string","description":"Execution timestamp"}},"required":["orderId","status","executedAt"]}}},"paths":{"/positions/{positionId}/adjust-advance":{"post":{"operationId":"PositionsController_adjustAdvancePosition","parameters":[{"name":"positionId","required":true,"in":"path","description":"Position identifier","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AdjustAdvanceItemDto"}}}}},"responses":{"200":{"description":"Advance adjustment executed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustAdvanceResponseDto"}}}}},"summary":"Adjust position to target absolute sizes per asset (advance)","tags":["Positions"]}}}}
```

## POST /positions/{positionId}/adjust-leverage

> Adjust leverage for a position

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"AdjustLeverageRequestDto":{"type":"object","properties":{"leverage":{"type":"number","description":"Applied leverage","minimum":1,"maximum":100}},"required":["leverage"]}}},"paths":{"/positions/{positionId}/adjust-leverage":{"post":{"operationId":"PositionsController_adjustLeverage","parameters":[{"name":"positionId","required":true,"in":"path","description":"Position identifier","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustLeverageRequestDto"}}}},"responses":{"200":{"description":"Leverage updated successfully","content":{"application/json":{"schema":{"type":"object"}}}}},"summary":"Adjust leverage for a position","tags":["Positions"]}}}}
```

## Preview rebalance plan without executing

> Computes weight deltas and returns what would be traded, without placing any orders. Use this to preview before calling the execute endpoint.

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"RebalancePositionRequestDto":{"type":"object","properties":{"targetWeights":{"type":"object","description":"Optional target weight overrides per asset coin (decimal, should sum to 1.0 per side). If omitted, uses existing targetWeight from position.","additionalProperties":{"type":"number"}}},"required":["targetWeights"]},"RebalancePlanDto":{"type":"object","properties":{"positionId":{"type":"string","description":"Position ID being rebalanced"},"assets":{"description":"Per-asset rebalance details","type":"array","items":{"$ref":"#/components/schemas/RebalanceAssetPlanDto"}},"canExecute":{"type":"boolean","description":"Whether any asset has a non-skipped trade to execute"}},"required":["positionId","assets","canExecute"]},"RebalanceAssetPlanDto":{"type":"object","properties":{"coin":{"type":"string","description":"Asset ticker symbol"},"side":{"type":"string","description":"Position side","enum":["long","short"]},"currentWeight":{"type":"number","description":"Current weight of asset in position (decimal, 0-1)"},"targetWeight":{"type":"number","description":"Desired target weight (decimal, 0-1)"},"currentValue":{"type":"number","description":"Current notional value in USD"},"targetValue":{"type":"number","description":"Target notional value in USD after rebalance"},"deltaValue":{"type":"number","description":"Difference between target and current value in USD"},"currentSize":{"type":"number","description":"Current position size in asset units"},"newSize":{"type":"number","description":"Position size in asset units after rebalance"},"deltaSize":{"type":"number","description":"Size change required in asset units"},"skipped":{"type":"boolean","description":"Whether this asset will be skipped during rebalance"},"skipReason":{"type":"string","description":"Reason for skipping (e.g. trade below minimum size)"}},"required":["coin","side","currentWeight","targetWeight","currentValue","targetValue","deltaValue","currentSize","newSize","deltaSize","skipped"]}}},"paths":{"/positions/{positionId}/rebalance/plan":{"post":{"description":"Computes weight deltas and returns what would be traded, without placing any orders. Use this to preview before calling the execute endpoint.","operationId":"PositionsController_planRebalance","parameters":[{"name":"positionId","required":true,"in":"path","description":"Position identifier","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RebalancePositionRequestDto"}}}},"responses":{"200":{"description":"Rebalance plan computed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RebalancePlanDto"}}}}},"summary":"Preview rebalance plan without executing","tags":["Positions"]}}}}
```

## Rebalance position assets to target weights

> Computes weight deltas and adjusts asset sizes to match target weights. Uses existing targetWeight from position if no overrides provided.

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"RebalancePositionRequestDto":{"type":"object","properties":{"targetWeights":{"type":"object","description":"Optional target weight overrides per asset coin (decimal, should sum to 1.0 per side). If omitted, uses existing targetWeight from position.","additionalProperties":{"type":"number"}}},"required":["targetWeights"]},"RebalancePositionResponseDto":{"type":"object","properties":{"orderId":{"type":"string","description":"Rebalance order ID"},"status":{"type":"string","description":"Execution status"},"executedAt":{"type":"string","description":"ISO 8601 timestamp of execution"},"plan":{"description":"Rebalance plan that was executed","allOf":[{"$ref":"#/components/schemas/RebalancePlanDto"}]}},"required":["orderId","status","executedAt","plan"]},"RebalancePlanDto":{"type":"object","properties":{"positionId":{"type":"string","description":"Position ID being rebalanced"},"assets":{"description":"Per-asset rebalance details","type":"array","items":{"$ref":"#/components/schemas/RebalanceAssetPlanDto"}},"canExecute":{"type":"boolean","description":"Whether any asset has a non-skipped trade to execute"}},"required":["positionId","assets","canExecute"]},"RebalanceAssetPlanDto":{"type":"object","properties":{"coin":{"type":"string","description":"Asset ticker symbol"},"side":{"type":"string","description":"Position side","enum":["long","short"]},"currentWeight":{"type":"number","description":"Current weight of asset in position (decimal, 0-1)"},"targetWeight":{"type":"number","description":"Desired target weight (decimal, 0-1)"},"currentValue":{"type":"number","description":"Current notional value in USD"},"targetValue":{"type":"number","description":"Target notional value in USD after rebalance"},"deltaValue":{"type":"number","description":"Difference between target and current value in USD"},"currentSize":{"type":"number","description":"Current position size in asset units"},"newSize":{"type":"number","description":"Position size in asset units after rebalance"},"deltaSize":{"type":"number","description":"Size change required in asset units"},"skipped":{"type":"boolean","description":"Whether this asset will be skipped during rebalance"},"skipReason":{"type":"string","description":"Reason for skipping (e.g. trade below minimum size)"}},"required":["coin","side","currentWeight","targetWeight","currentValue","targetValue","deltaValue","currentSize","newSize","deltaSize","skipped"]}}},"paths":{"/positions/{positionId}/rebalance":{"post":{"description":"Computes weight deltas and adjusts asset sizes to match target weights. Uses existing targetWeight from position if no overrides provided.","operationId":"PositionsController_rebalancePosition","parameters":[{"name":"positionId","required":true,"in":"path","description":"Position identifier","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RebalancePositionRequestDto"}}}},"responses":{"200":{"description":"Rebalance executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RebalancePositionResponseDto"}}}}},"summary":"Rebalance position assets to target weights","tags":["Positions"]}}}}
```

## PUT /positions/{positionId}/riskParameters

> Update stop loss and take profit values for a position

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"UpdateRiskParametersRequestDto":{"type":"object","properties":{"stopLoss":{"description":"Stop loss configuration. Set to null to remove existing stop loss.","nullable":true,"allOf":[{"$ref":"#/components/schemas/TpSlThreshold"}]},"takeProfit":{"description":"Take profit configuration. Set to null to remove existing take profit.","nullable":true,"allOf":[{"$ref":"#/components/schemas/TpSlThreshold"}]}}},"TpSlThreshold":{"type":"object","properties":{"type":{"type":"string","description":"Trigger type","enum":["PERCENTAGE","DOLLAR","POSITION_VALUE","PRICE","PRICE_RATIO","WEIGHTED_RATIO"]},"value":{"type":"number","description":"Trigger value for the specified type"},"isTrailing":{"type":"boolean","description":"Enable trailing behavior for this TP/SL"},"trailingDeltaValue":{"type":"number","description":"Trailing delta value based on trigger type"},"trailingActivationValue":{"type":"number","description":"Activation value to start trailing"}},"required":["type"]},"UpdateRiskParametersResponseDto":{"type":"object","properties":{"positionId":{"type":"string","description":"Position identifier","format":"uuid"},"stopLoss":{"description":"Updated stop loss configuration","nullable":true,"allOf":[{"$ref":"#/components/schemas/TpSlThreshold"}]},"takeProfit":{"description":"Updated take profit configuration","nullable":true,"allOf":[{"$ref":"#/components/schemas/TpSlThreshold"}]},"updatedAt":{"type":"string","description":"Update timestamp","format":"date-time"}},"required":["positionId","stopLoss","takeProfit","updatedAt"]}}},"paths":{"/positions/{positionId}/riskParameters":{"put":{"operationId":"PositionsController_updateRiskParameters","parameters":[{"name":"positionId","required":true,"in":"path","description":"Position identifier","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRiskParametersRequestDto"}}}},"responses":{"200":{"description":"Risk parameters updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRiskParametersResponseDto"}}}}},"summary":"Update stop loss and take profit values for a position","tags":["Positions"]}}}}
```