# 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"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pearprotocol.io/api-integration/api-specification/positions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.