Positions

Channel: positions

Before subscribing to this channel, authentication is required.

The positions channel provides updates on all positions across all markets. Upon subscription, you receive one snapshot of all open positions. Afterward, real-time updates are streamed to you whenever there are changes to your positions.

Notes:

positions channel will send update only when size of position changes. Thus, positions channel will not send messages when the oracle price changes, which effectively changes some fields of positions like: initial_margin_requirement, maintenance_margin_requirement, unrealized_pnl.
For some fields depend on oracle prices, we will the current oracle prices to compute their values.
Field stop_position will always be null. You can get stop_position using REST api.

// Request
{
  "op": "sub",
  "channel": "positions"
}

// Response - SNAPSHOT
// the format should be the same with the REST api about positions,
// If there are no open positions, the data return null
{
   "channel":"positions",
   "type":"snapshot",
   "data": null,
   "timestamp": "1721281771050521000" // unix timestamp when the snapshot is created
}

// Response - SNAPSHOT
// the format should be the same with the REST api about positions,
// If there are no open positions, the data return null
{
  "channel": "positions",
  "type": "snapshot",
  "data": [
    {
      "avg_entry_price": "67965.6818181818181818",
      "funding_index": "1007.500479",
      "index_price": "67910.745172499996",
      "initial_margin_requirement": "149.3616877752999912",
      "leverage": "0.3093674252364947",
      "liquidation_price": "0",
      "maintenance_margin_requirement": "98.578713931697994192",
      "mark_price": "67891.676261499996",
      "net_size": "0.044",
      "product_id": "BTC-PERP",
      "product_index": 1,
      "quote_balance": "-2991.110906",
      "stop_position": null,
      "unrealized_pnl": "-2.4172124100001759992",
      "unsettled_funding": "0"
    },
    {
      "avg_entry_price": "3542.1",
      "funding_index": "234.916587",
      "index_price": "3543.166988999998",
      "initial_margin_requirement": "49.607844194999972",
      "leverage": "0.1027148089813124",
      "liquidation_price": "0",
      "maintenance_margin_requirement": "32.74117716869998152",
      "mark_price": "3543.417442499998",
      "net_size": "0.28",
      "product_id": "ETH-PERP",
      "product_index": 2,
      "quote_balance": "-992.4330728",
      "stop_position": null,
      "unrealized_pnl": "0.29875691999944",
      "unsettled_funding": "0"
    }
  ],
  "timestamp": "1721281771050521000" // unix timestamp when the snapshot is created
}

// Response - update
// the API format is the same with the snapshot. In each update, the server might returns multiple changed positions.
{
  "channel": "positions",
  "type": "update",
  "data": [
    {
      "avg_entry_price": "67950.0689655172413793",
      "funding_index": "1007.500479",
      "index_price": "67916.073672500001",
      "initial_margin_requirement": "196.9773496884500087",
      "leverage": "0.4077804858339715",
      "liquidation_price": "0",
      "maintenance_margin_requirement": "130.005050794377005742",
      "mark_price": "67923.224030500003",
      "net_size": "0.058",
      "product_id": "BTC-PERP",
      "product_index": 1,
      "quote_balance": "-3942.3452744",
      "stop_position": null,
      "unrealized_pnl": "-1.9717269949999419994",
      "unsettled_funding": "0"
    }
  ],
  "timestamp": "1721281771050521000" // unix timestamp when this event is emitted
}

// return when sub orders is sent without authentication
{
  "channel": "positions",
  "type": "error",
  "message": "not authenticated",
  "code": 401
}