Skip to main content

Position Lifecycle

A position is the net exposure you hold on a futures symbol. Positions open when an order fills, accumulate or shrink as more orders fill, and close when the net size reaches zero.

How positions form​

When your first order on a symbol fills, a position is created with:

  • position_side — LONG (you bought) or SHORT (you sold).
  • position_size — the filled quantity, in base asset.
  • avg_entry_price — the price at which it filled.
  • leverage — the leverage you had set on that symbol at the time. See Margin & Leverage.

The position then carries until you close it.

How positions change​

EventEffect
New order fills in the same directionposition_size grows; avg_entry_price recalculated as a weighted average.
Order fills against the position (smaller than current size)position_size shrinks; avg_entry_price unchanged. P&L realised.
Order fills against the position (equal to current size)Position closes. Disappears from Get Positions.
Order fills against the position (larger than current size)Position flips: closes the existing side, opens a new one in the opposite direction with the leftover quantity.
Funding settlementA FUNDING_FEE transaction is recorded; balance changes; position size unchanged.
Add marginposition_margin increases; liquidation price moves favourably.

Statuses​

The status field on a position is OPEN while the position is live. Once size reaches zero, the position no longer appears in Get Positions — there is no terminal "CLOSED" entry.

Reduce-only orders​

To close part of a position safely, set reduce_only=true on a counter-side order. This guarantees the order will not open a new opposite-direction position if it accidentally fills more than the current size.

# Close half a long BTC position safely
body = {
    "exchange": "EXCHANGE_2",
    "symbol": "btcusdt",
    "side": "SELL",
    "order_type": "LIMIT",
    "price": 60000,
    "quantity": current_size / 2,
    "reduce_only": True,
}

reduce_only=true is mandatory for TAKE_PROFIT_MARKET and STOP_MARKET orders. See Place Order.

Liquidation​

If your position's mark price moves enough against you that position_margin falls below maint_margin, the exchange liquidates the position. The liquidation_price field on Get Positions is your current liquidation level — keep it well away from mark_price to avoid forced closure.

You can move the liquidation price by:

  • Add Margin — top up margin to push liquidation further away.
  • Reducing position size — partial close via a reduce-only counter-order.
  • Lowering leverage — note that this is only allowed when there are no open positions or open orders on the symbol.

Tracking position changes in real time​

Position updates aren't pushed via WebSocket today. Poll Get Positions periodically (rate limit: 20/60s).

Last updated on