Positions

Snapshot of the authenticated account's open positions.

GET /positions

Auth: Authorization: Bearer <access_token>. The account is derived from the token — there is no path parameter for user id.

Query Parameters

Parameter	Required	Description
`status`	No	Filter by position status. Accepts `OPEN` (default), `CLOSING`, `CLOSED`.
`symbol`	No	Filter to a single instrument.

Example

curl "https://api.godarkdex.com/api/v1/positions?status=OPEN" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "code": 0,
  "data": {
    "positions": [
      {
        "position_id": "pos_01HXYZ",
        "symbol": "BTC-USDC-PERP",
        "side": "long",
        "size": 0.5,
        "entry_price": 95000.0,
        "mark_price": 95500.0,
        "margin": 4750.0,
        "leverage": 5,
        "unrealized_pnl": 250.0,
        "realized_pnl": 0,
        "funding_accrued": -12.5,
        "liquidation_price": 85500.0,
        "status": "OPEN",
        "created_at": "2026-04-20T10:30:00.123Z",
        "updated_at": "2026-04-20T11:00:00.456Z"
      }
    ]
  },
  "timestamp": "2026-04-20T11:05:00.789Z",
  "request_id": "req_01HXYZ..."
}

Field Reference

Field	Type	Description
`position_id`	string	Position id
`symbol`	string	Instrument id
`side`	string	`long` or `short`
`size`	number	Position size in base asset (always positive; direction is given by `side`)
`entry_price`	number	Volume-weighted average entry price
`mark_price`	number	Reference price used for PnL and liquidation math
`margin`	number	Collateral allocated to this position (USDC)
`leverage`	number	Effective leverage
`unrealized_pnl`	number	Current unrealized PnL (USDC)
`realized_pnl`	number	Cumulative realized PnL since position opened (USDC)
`funding_accrued`	number	Net funding paid/received (USDC; negative = paid out)
`liquidation_price`	number	Price at which this position would be liquidated (see Margin & Liquidation)
`status`	string	`OPEN`, `CLOSING`, or `CLOSED`
`created_at`	string	Position open timestamp (RFC 3339)
`updated_at`	string	Last update timestamp (RFC 3339)

Streaming Alternative

GET /positions is a single snapshot. For live updates — fills, mark price moves, liquidation-price changes — subscribe to the Positions Channel over WebSocket. The channel sends a snapshot on subscribe and then incremental updates.

For margin health tiers, partial liquidation, and how liquidation_price is derived, see Margin & Liquidation.