PhoenixPerpetualsDocs API v1
Get an API key

Your accounts

Positions and margin⁠.

Open positions with their liquidation and breach prices, leverage and margin mode per market, closing and flattening.

View as Markdown

On this page
  1. Open positions
  2. Leverage and margin mode
  3. Closing
  4. Closed positions

An account holds at most one position per market, long or short. Orders in the same direction add to it, orders the other way reduce it, close it, or turn it.

Open positions#

GET /v1/accounts/{account_id}/positions lists them all, valued at the market price. The list is always complete: if the trading servers cannot answer for every position, the call fails rather than leave one out.

FieldWhat it holds
idThe position, for as long as it stays open on the same side
market, side, sizeWhat you hold
entry_price, mark_price, notional, unrealized_pnlIts cost, its price now, its value and its open P&L
leverage, margin_mode, marginHow it is margined, and what it holds of the balance
liquidationThe price at which it would be liquidated and how far the market is from it. With cross margin on several markets there is no single price: account_wide is true
breach_pricesThe prices at which this position alone would breach the daily loss limit and the max drawdown
exits, protectedThe take-profits and stop-losses resting on it, and whether at least one stop-loss protects it

GET .../positions/BTC-USD answers one market, and 404 position_not_found when you hold none there.

Leverage and margin mode#

Each market has its own setting on each account: GET .../margin lists them, with the highest leverage the market allows and where each setting comes from (an open position, your saved choice, or the market's default).

  • Isolated: each position holds its own margin, and its liquidation depends on that margin alone.
  • Cross: positions share the account's balance, and move each other's liquidation.

Change one with PUT .../margin/{market}:

{ "margin_mode": "isolated", "leverage": 10 }

The mode cannot change while a position or a working order is open on that market (locked: true); the leverage can, and changing it on an open position changes the margin it holds. The setting applies to new positions on that market from then on.

Closing#

  • **POST .../positions/{market}/close** closes the position at the market, all of it, or the size you send. No other order is touched, except that its exits shrink with it.
  • **POST .../flatten** cancels every working order, then closes every position. A key limited to some markets does this on those only.
  • **POST .../orders/cancel-all** cancels working orders and leaves positions as they are.

All three take an Idempotency-Key (see Idempotency).

Closed positions#

GET .../closed-positions lists positions once fully closed, newest first: entry and exit prices, P&L before and after fees, and its lots. A position is closed first in, first out: each lot is a part of it opened at one entry price, with the exit price, P&L and fees of its close. So a partial close takes the oldest part first, and the open position's entry_price (the average of what is left) can change. A position still open is listed here once it closes. For the executions themselves, see History.

The fees of closed positions and of daily results are as the engine settles them: each lot's to the cent, with the holding cost of a position kept open over time included. Your balance is their exact sum, so these can differ from it by a few cents over many trades; an order's or a fill's fee is the trading fee alone, to the millionth.

Guides, endpoints, fields and error codes.