Position Types

This reference documents all position-related types in the Trading API, including position schemas, P&L tracking, and endpoints for managing your holdings.

Enums

PositionSide

The direction of the position.

Value	Description
`LONG`	Bought the asset, profit when price increases
`SHORT`	Sold the asset, profit when price decreases

MarginMode

Margin mode for leveraged positions.

Value	Description
`CROSS`	Margin shared across all positions - higher capital efficiency, but losses in one position can affect others
`ISOLATED`	Margin isolated per position - limits risk to the margin allocated to each position

Position Schema

Positions returned from GET /positions or via WebSocket events.

Required Fields

Field	Type	Description
`id`	string	Position ID (may be synthetic for stock brokers)
`symbol`	string	Trading symbol (e.g., "AAPL", "EUR/USD", "BTC/USD")
`side`	PositionSide	Position direction (`LONG` or `SHORT`)
`quantity`	string	Current position quantity in base units
`average_entry_price`	string	Weighted average entry price
`current_price`	string	Current market price
`unrealized_pnl`	string	Unrealized profit/loss
`realized_pnl`	string	Realized profit/loss from partial closes
`opened_at`	datetime	When the position was opened
`updated_at`	datetime	When the position was last modified

Optional Fields

Field	Type	Description
`leverage`	string	Leverage multiplier (for leveraged positions)
`liquidation_price`	string	Price at which position will be liquidated
`margin_mode`	MarginMode	`CROSS` or `ISOLATED`

Example Response

{
  "id": "pos_abc123",
  "symbol": "BTC/USD",
  "side": "LONG",
  "quantity": "0.5",
  "average_entry_price": "42000.00",
  "current_price": "43500.00",
  "unrealized_pnl": "750.00",
  "realized_pnl": "0.00",
  "leverage": "10",
  "liquidation_price": "38000.00",
  "margin_mode": "ISOLATED",
  "opened_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T14:45:00Z"
}

P&L Calculations

Unrealized P&L

Unrealized profit/loss represents the gain or loss on open positions based on current market prices. It is calculated as:

Long positions:

unrealized_pnl = (current_price - average_entry_price) * quantity

Short positions:

unrealized_pnl = (average_entry_price - current_price) * quantity

This value updates continuously as market prices change.

Realized P&L

Realized profit/loss represents gains or losses that have been locked in from partial position closes. When you close part of a position:

The closed portion's P&L is calculated and added to realized_pnl
The remaining position continues with its original average_entry_price
quantity is reduced by the amount closed

Realized P&L only changes when you close positions, not from market price movements.

REST Endpoints

List Positions

GET /positions

Returns all open positions, optionally filtered by symbol.

Query Parameters:

Parameter	Type	Description
`symbol`	string	Filter by symbol (optional)

Response: Array of Position objects

Get Position

GET /positions/{position_id}

Returns a specific position by ID.

Path Parameters:

Parameter	Type	Description
`position_id`	string	Position ID

Response: Position object

Error Responses:

404 - Position not found
503 - Provider unavailable

Close Position

DELETE /positions/{position_id}

Close a position (partially or fully).

Path Parameters:

Parameter	Type	Description
`position_id`	string	Position ID

Request Body (optional):

{
  "quantity": "0.25",
  "order_type": "LIMIT",
  "limit_price": "43000.00",
  "cancel_associated_orders": true
}

Field	Type	Description
`quantity`	string	Quantity to close (null = close entire position)
`order_type`	OrderType	Order type for close (default: `MARKET`)
`limit_price`	string	Required if `order_type` is `LIMIT`
`cancel_associated_orders`	boolean	Cancel pending SL/TP orders (default: true)

Response: OrderHandle for the close order

Close All Positions

DELETE /positions

Close all open positions, optionally filtered by symbol.

Query Parameters:

Parameter	Type	Description
`symbol`	string	Filter by symbol (null = close all)

Response: Array of OrderHandle objects

Related Types

Order Types - Place and manage orders
Event Types - Handle position update events