Positions Channel

Channel name: position

Authentication

You must send a successful auth message before subscribing.

{ "op": "sub", "channel": "position" }

No params field is required. The stream is account-scoped.

Message Types

Snapshot

Sent immediately after subscribing. Contains a position object for every enabled market, including markets where the user has no open position (net_sz: "0").

{
  "channel": "position",
  "type": "snapshot",
  "data": [
    {
      "mkt_idx": 1,
      "mkt_id": "BTC-PERP",
      "net_sz": "1.5",
      "avg_entry_px": "50000.00",
      "quote_bal": "-75000.00",
      "mark_px": "50100.00",
      "idx_px": "50095.00",
      "mrgn_mode": "MARGIN_MODE_CROSS",
      "lev": "10",
      "mrgn_bal": "7500.00",
      "init_mrgn_req": "5000.00",
      "maint_mrgn_req": "2500.00",
      "liq_px": "45100.00",
      "unrlzd_pnl": "150.00",
      "tot_fund_paid": "5.00",
      "iso_usdc_bal": "0",
      "free_iso_usdc_bal": "0",
      "in_iso_liq": false,
      "mrgn_ratio": "0.033"
    }
  ],
  "gsn": 12345,
  "ts": "1234567890000000000"
}

Update

Incremental position changes from trade fills. The data field is a single position object (not an array). The filter field identifies which market was updated.

{
  "channel": "position",
  "type": "update",
  "filter": "BTC-PERP",
  "data": {
    "mkt_idx": 1,
    "mkt_id": "BTC-PERP",
    "net_sz": "2.0",
    "avg_entry_px": "50025.00",
    "quote_bal": "-100050.00",
    "mark_px": "50150.00",
    "idx_px": "50145.00",
    "mrgn_mode": "MARGIN_MODE_CROSS",
    "lev": "10",
    "mrgn_bal": "10000.00",
    "init_mrgn_req": "10005.00",
    "maint_mrgn_req": "5002.50",
    "liq_px": "45022.50",
    "unrlzd_pnl": "250.00",
    "tot_fund_paid": "5.00",
    "iso_usdc_bal": "0",
    "free_iso_usdc_bal": "0",
    "in_iso_liq": false,
    "mrgn_ratio": "0.033"
  },
  "gsn": 12346,
  "ts": "1234567891000000000"
}

Fields

Position fields in WebSocket messages use the same v1Position schema as the REST API:

Field	Type	Description
`filter`	string	Market ID (update messages only, e.g. `"BTC-PERP"`)
`mkt_idx`	number	Market signing index
`mkt_id`	string	Market ID
`net_sz`	string	Net size (positive = long, negative = short)
`avg_entry_px`	string	Average entry price
`quote_bal`	string	Quote balance
`mark_px`	string	Current mark price
`idx_px`	string	Current index price
`mrgn_mode`	string	`MARGIN_MODE_CROSS` or `MARGIN_MODE_ISOLATED`
`lev`	string	Leverage
`mrgn_bal`	string	Margin balance
`init_mrgn_req`	string	Initial margin requirement
`maint_mrgn_req`	string	Maintenance margin requirement
`liq_px`	string	Liquidation price
`unrlzd_pnl`	string	Unrealized PnL
`tot_fund_paid`	string	Cumulative funding payments
`iso_usdc_bal`	string	Isolated USDC balance
`free_iso_usdc_bal`	string	Free isolated USDC balance
`in_iso_liq`	boolean	In isolated liquidation
`mrgn_ratio`	string	Margin ratio

See the full schema in GET /portfolio and GET /positions/history.

Authentication

Message Types

Snapshot

Update

Fields

On this page