This page will help you get started with "positions" channel
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 benull
. You can getstop_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
}