WebSocket API — Positions Channel

Live position updates for the authenticated account. Sends a snapshot of every open position on subscribe, then incremental updates as positions change — fills, mark-price moves, funding accruals, liquidations.

wss://api.godarkdex.com/ws/v1

Authenticate with op: login first (see WebSocket Trading).

{ "id": "c-4", "op": "subscribe", "args": { "channel": "positions" } }

Response:

{ "id": "c-4", "op": "subscribe", "code": 0, "data": { "channel": "positions", "seq_start": 1 } }

Event Flow

Identical pattern to the Orders Channel:

snapshot → snapshot → ... → snapshot (snapshot_complete: true) → update → update → ...

The final snapshot frame carries snapshot_complete: true. Updates arriving during snapshot delivery should be buffered and replayed after.

Frame Shape

{
  "channel": "positions",
  "type": "snapshot" | "update",
  "seq": 42,
  "snapshot_complete": false,
  "data": { /* position object — fields below */ }
}

Field	Description
`type`	`snapshot` during initial replay; `update` afterward
`seq`	Monotonic per subscription per session
`snapshot_complete`	`true` on the final snapshot frame
`data`	Position object — schema matches `GET /positions` plus `update_reason`

Position Object

{
  "channel": "positions",
  "type": "update",
  "seq": 214,
  "snapshot_complete": false,
  "data": {
    "update_reason": "fill",
    "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",
    "updated_at": "2026-04-20T11:00:00.456Z"
  }
}

`update_reason` Values

Value	Description
`fill`	Position changed due to an order fill
`mark_price`	Mark price moved (PnL / liquidation price recomputed)
`funding`	Funding rate accrued to the position
`liquidation`	Position partially or fully liquidated
`closed`	Position closed (size reached 0)
`settlement`	Realized PnL settled to the vault

The server throttles mark_price updates to at most once per second per position to avoid flooding slow clients; other reasons are emitted immediately.

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

Field Reference

Same semantics as GET /positions — see that page for the authoritative field reference.

Gap Recovery

Clients should track seq. On a gap:

op: unsubscribe { channel: "positions" }
op: subscribe { channel: "positions" } — receive a fresh snapshot
Resume applying updates from the new seq series

Unsubscribe

{ "id": "c-9", "op": "unsubscribe", "args": { "channel": "positions" } }