Skip to main content
Managing a position means four read-and-act loops: see what you hold, shrink it without flipping it, account for the funding it accrues, and watch the portfolio status that signals trouble. This is the how; for what a position is and how margin and funding work, see Positions, leverage, and funding. The reads here take optional subaccount_index and portfolio_index filters and return everything your credential reaches — one portfolio, or every portfolio on the account. The reduce-only write carries one full PortfolioId in its signed body.

​
Read your positions

GET /api/v1/positions returns the account’s open positions as an array of PositionResponse. Narrow it with the optional portfolio_index and market query parameters; an invalid market returns 400 Bad Request.
FieldMeaning
sideLONG or SHORT.
quantityPosition size in base-asset units, as a decimal string.
avg_entry_priceAverage entry price in USDC.
net_fundingFunding accrued against this position so far, in USDC.
side and quantity agree by construction: a LONG position has positive quantity, a SHORT has negative. That sign is what you negate to reduce.

​
Reduce or flatten a position

To shrink a position, place an order on the opposite side with reduce_only set. There is no “close position” endpoint — you flatten by trading against yourself with a reduce-only order sized to your current quantity. Side is the sign of quantity (positive = long/buy, negative = short/sell), so the reducing order’s sign is the opposite of your position’s. See Orders and time-in-force for the full order body and flags.
1

Read the current quantity

GET /api/v1/positions?portfolio_index=0&market=BTC-PERP. A LONG 0.25 BTC position reads back side: LONG, quantity: "0.25".
2

Pick a reducing quantity, opposite sign

To flatten, send quantity = -0.25 BTC (converted to atoms). To halve it, send -0.125 BTC. The sign must oppose the position; same-sign would grow it and be rejected.
3

Set reduce_only and place the order

Set the reduce_only flag on the order’s flags struct, then place it. Both order types carry the flag: OrderFlags.reduce_only on POST /api/v1/trading/order/place/limit, MarketOrderFlags.reduce_only on POST /api/v1/trading/order/place/market.
4

Branch on the RequestAck

A signed write returns 200 OK with a RequestAck even when rejected. Read status: request_completed means accepted. A reduce-only order that would not reduce comes back invalid_reduce_only_order.
A reduce-only order can only shrink a position, never open or grow one. The exchange rejects any reduce-only order whose fill would increase your absolute quantity or flip the side, with status invalid_reduce_only_order. An order larger than the position fills only down to flat; the excess does not reverse you into the opposite side. The common mistake is sign, not size: a reduce-only order on the same side as the position is rejected, because it would grow the position rather than reduce it.
A reduce-only limit order rests on the book until it fills or you cancel it. If the position is closed by other fills first, the resting reduce-only order can no longer reduce anything and is rejected on its next match. Cancel stale reduce-only orders rather than leaving them resting.

​
Read funding paid and received

Funding accrues against an open position and settles in USDC cash. Two reads report it.
PositionResponse.net_funding is the net funding accrued against the current open position, in USDC. Read it from GET /api/v1/positions. For the cash-direction convention, read the settled payment values in the settlement history.
The payment sign is the direction of cash: positive means you received funding, negative means you paid. A negative payment decreases your cash; a positive one increases it.

​
Watch portfolio status

Liquidation does not arrive as a notification. It surfaces as a change in portfolio status, so poll it. GET /api/v1/portfolio/balance returns a PortfolioBalanceResponse; its status field is one of three states.
statusMeaning
ACTIVENormal trading.
IN_LIQUIDATIONThe exchange is unwinding the portfolio’s positions.
CLOSEDThe portfolio is closed.
The same response carries cash_balance in USDC, the free cash backing the portfolio’s positions. When status reads IN_LIQUIDATION, the exchange is already reducing your positions; you cannot close the portfolio until it returns to ACTIVE. Top up cash or reduce positions before equity falls below the maintenance margin requirement, not after. To pair this with reductions, see Fund and trade for opening positions and depositing collateral, and the Trading API reference for the full schema of each response.