Position Margin

Add or remove margin on isolated positions

Adjust the margin on an isolated position via PerpsClient.updatePositionMargin. The registered provider plugin authorizes and submits the action according to its descriptor.

Position-margin support is market-specific. Read market.positionMarginAdjustment or use the helper predicates below instead of assuming every provider supports both directions.

​

Capability and removable margin

PositionMarginAdjustment has three values:

Value	Meaning
NONE	Individual position margin cannot be changed
ADD_ONLY	Margin can be added but not removed
ADD_AND_REMOVE	Margin can be added and removed

import {
  getPositions,
  isPositionMarginAdjustable,
  isPositionMarginRemovable,
} from '@lifi/perps-sdk';

const { positions } = await getPositions(perps.client, {
  provider: 'hyperliquid',
  address: userAddress,
});

for (const position of positions) {
  if (!isPositionMarginAdjustable(position)) continue;

  const removable = isPositionMarginRemovable(position)
    ? perps.getPositionRemovableMargin(position)
    : '0';
  console.log(position.market.baseAsset.displaySymbol, removable);
}

isPositionMarginAdjustable(position) is true for isolated positions on markets whose positionMarginAdjustment is not NONE. isPositionMarginRemovable(position) additionally requires ADD_AND_REMOVE.

perps.getPositionRemovableMargin(position) returns the largest amount you can remove, as a decimal string rounded down to 6 decimals:

Result	Meaning
undefined	The position has no individual margin adjustment (a cross position, or a cross-only venue such as Ondo)
'0'	Nothing is removable, or the market is add-only
decimal string	Maximum removable margin

The formula is venue-specific:

Provider	Removable margin
Hyperliquid	marginUsed − max(initialMarginRequirement, 0.1 × size × markPrice). Unrealized PnL is already part of marginUsed
Lighter	marginUsed + unrealizedPnl − initialMarginRequirement

The method throws PerpsError (ValidationError) when a Position decimal the formula reads is malformed. It does not read the venue; the input is the Position you already fetched. The venue still rejects a removal that would leave the position below its margin requirement.

---

​

updatePositionMargin

const result = await perps.updatePositionMargin({
  provider: 'hyperliquid',
  address: userAddress,
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
  action: 'add',
  amount: '500.00',
});

Pass action: 'remove' (with a positive amount) to withdraw margin from the position without changing its size.

A venue refusal does not throw; check status on each entry of result.results. See Execution reports and Error Handling. After the write, re-read the position once after a short delay; the venue’s read can lag the update.

API Reference: POST /createAction · /executeAction