Positions

Topic: /contract/positionAll

OR

Topic:/contract/position:XBTUSDTM

Description

You will receive this message when position changes.

These situations will cause position change

Position Changes Caused Operations. changeReason Descriptions:

“marginChange”: margin change;

“positionChange”: position change;

“liquidation”: liquidation;

“autoAppendMarginStatusChange”: auto-deposit-status change;

“adl”: adl;

Funding Fee Settlement

Adjustment Isolated Margin Risk Limit Level. msg failure reasons:

the value of the holding position exceeds the limit amount of the risk limit level;

insufficient balance to increase the margin.

Push frequency: real-time

//Get all symbols position change
{
  "id": 1545910660739,
  "type": "subscribe",
  "topic": "/contract/positionAll",
  "response": true,
  "privateChannel": "true"
}

//Get specific symbol position change
{
  "id": 1545910660739,
  "type": "subscribe",
  "topic": "/contract/position:XBTUSDTM",
  "response": true,
  "privateChannel": "true"
}

Response

Data Schema

position

userId

string

required

Deprecated, will delete later

topic

string

required

subject

string

required

type

string

required

channelType

string

required

data

object

required

symbol

string

required

Symbol of the contract. Please refer to Get Symbol endpoint: symbol

Examples:

XBTUSDTMXBTUSDMETHUSDTM

marginMode

enum<string>

required

Margin Mode: CROSS, ISOLATED

Allowed values:

CROSSISOLATED

crossMode

boolean

required

Whether it is cross margin.

delevPercentage

number

required

ADL ranking percentile

openingTimestamp

integer <int64>

required

Open time

currentTimestamp

integer <int64>

required

Current timestamp

currentQty

integer

required

Current position quantity

currentCost

number

required

Current position value

currentComm

number

required

Current commission

unrealisedCost

number

required

Unrealized value

unrealisedPnl

number

required

Unrealized profit and loss

unrealisedPnlPcnt

number

required

Profit-loss ratio of the position

unrealisedRoePcnt

number

required

Rate of return on investment

realisedCost

number

required

Current realized position value

realisedGrossCost

number

required

Accumulated realized gross profit value

realisedGrossPnl

number

required

Accumulated realized gross profit value

realisedPnl

number

required

Realized profit and loss

isOpen

boolean

required

Opened position or not

markPrice

number

required

Mark price

markValue

number

required

Mark Value

posCost

number

required

Position value

posInit

number

required

Inital margin Cross = opening value/cross leverage; isolated = accumulation of initial margin for each transaction

posMargin

number

required

Bankruptcy cost Cross = mark value * imr; Isolated = position margin (accumulation of initial margin, additional margin, generated funding fees, etc.)

avgEntryPrice

number

required

Average entry price

liquidationPrice

number

required

Liquidation price: For Cross Margin, you can refer to the liquidationPrice, and the liquidation is based on the risk rate.

bankruptPrice

number

required

Bankruptcy price: For Cross Margin, you can refer to the bankruptPrice, and the liquidation is based on the risk rate.

settleCurrency

string

required

Currency used to clear and settle the trades

positionSide

enum<string>

required

Position Side

Allowed value:

BOTH

leverage

number

required

Leverage

maintMarginReq

number

optional

Maintenance margin requirement

posMaint

number

optional

Maintenance margin

autoDeposit

boolean

optional

Auto deposit margin or not Only applicable to Isolated Margin

riskLimit

integer

optional

Risk limit Only applicable to Isolated Margin

realLeverage

number

optional

Leverage of the order Only applicable to Isolated Margin

posCross

number

optional

Added margin Only applicable to Isolated Margin

posComm

number

optional

Bankruptcy cost Only applicable to Isolated Margin

posLoss

number

optional

Funding fees paid out Only applicable to Isolated Margin

posFunding

number

optional

The current remaining unsettled funding fee for the position Only applicable to Isolated Margin

maintMargin

number

optional

Position margin Only applicable to Isolated Margin

fundingTime

integer <int64>

optional

Funding time

qty

integer

optional

Position size

fundingRate

number

optional

Funding rate

fundingFee

number

optional

Funding fees

integer <int64>

optional

Funding Fee Settlement Time (nanoseconds)

success

boolean

optional

Adjustment isolated margin risk limit level successful or not

msg

string

optional

Adjustment isolated margin risk limit level failure reason

Example

1. Position Changes Caused Operations

//Isolated Margin
{
    "topic": "/contract/position:XBTUSDTM",
    "type": "message",
    "data": {
        "symbol": "XBTUSDTM",
        "maintMarginReq": 0.005,
        "riskLimit": 500000,
        "realLeverage": 4.9685590767,
        "crossMode": false,
        "delevPercentage": 0.10,
        "openingTimestamp": 1731916913097,
        "autoDeposit": true,
        "currentTimestamp": 1731924561514,
        "currentQty": 1,
        "currentCost": 91.5306,
        "currentComm": 0.09179284,
        "unrealisedCost": 91.6945,
        "realisedCost": -0.07210716,
        "isOpen": true,
        "markPrice": 91839.79,
        "markValue": 91.83979,
        "posCost": 91.6945,
        "posCross": 0,
        "posInit": 18.3389,
        "posComm": 0.06602004,
        "posLoss": 0,
        "posMargin": 18.40492004,
        "posFunding": 0,
        "posMaint": 0.5634627025,
        "maintMargin": 18.55021004,
        "avgEntryPrice": 91694.5,
        "liquidationPrice": 73853.0426625,
        "bankruptPrice": 73355.6,
        "settleCurrency": "USDT",
        "changeReason": "positionChange",
        "riskLimitLevel": 2,
        "realisedGrossCost": -0.1639,
        "realisedGrossPnl": 0.1639,
        "realisedPnl": 0.07210716,
        "unrealisedPnl": 0.14529,
        "unrealisedPnlPcnt": 0.0016,
        "unrealisedRoePcnt": 0.0079,
        "leverage": 4.9685590767,
        "marginMode": "ISOLATED",
        "positionSide": "BOTH"
    },
    "subject": "position.change",
    "userId": "633559791e1cbc0001f319bc",
    "channelType": "private"
}
      
//Cross Margin
{
    "topic": "/contract/position:XBTUSDTM",
    "type": "message",
    "data": {
        "symbol": "XBTUSDTM",
        "crossMode": true,
        "delevPercentage": 0.06,
        "openingTimestamp": 1717639498983,
        "currentTimestamp": 1717724686618,
        "currentQty": -2,
        "currentCost": -136.002,
        "currentComm": 0.06739824,
        "unrealisedCost": -136.002,
        "realisedCost": 0.06739824,
        "isOpen": true,
        "markPrice": 70778.04,
        "markValue": -141.55608,
        "posCost": -136.002,
        "posInit": 5.4509819612,
        "posMargin": 5.6735903779,
        "avgEntryPrice": 68001,
        "liquidationPrice": 80700.49720065,
        "bankruptPrice": 81152.42267235,
        "settleCurrency": "USDT",
        "changeReason": "positionChange",
        "realisedGrossCost": 0,
        "realisedGrossPnl": 0,
        "realisedPnl": -0.09580416,
        "unrealisedPnl": -5.55408,
        "unrealisedPnlPcnt": -0.0408,
        "unrealisedRoePcnt": -1.0189,
        "leverage": 24.95, 
        "marginMode": "CROSS", // CROSS，ISOLATED
        "positionSide": "BOTH"
    },
    "subject": "position.change",
    "userId": "665ec530aa70390001d22576",
    "channelType": "private"
}
      
2. Funding Fee Settlement
{
  "userId": "xbc453tg732eba53a88ggyt8c", // Deprecated, will detele later
  "topic": "/contract/position:XBTUSDM",
  "subject": "position.settlement",
  "data": {
    "fundingTime": 1551770400000, //Funding time
    "qty": 100, //Position size
    "markPrice": 3610.85, //Settlement price
    "fundingRate": -0.002966, //Funding rate
    "fundingFee": -296, //Funding fees
    "ts": 1547697294838004923, //Current time (nanosecond)
    "settleCurrency": "XBT" //Currency used to clear and settle the trades
  }
}
      
3. Adjustment Isolated margin Risk Limit Level
{
  "userId": "xbc453tg732eba53a88ggyt8c",
  "topic": "/contract/position:ADAUSDTM",
  "subject": "position.adjustRiskLimit",
  "data": {
    "success": true, // Successful or not
    "riskLimitLevel": 1, // Current risk limit level
    "msg": "" // Failure reason
  }
}

Request

Query Params

token

string

required

The token required to establish a websocket connection

Example:

2neAiuYvAU737TOajb2U3uT8AEZqSWYe0fBD4LoHuXJDSC7gIzJiH4kNTWhCPISWo6nDpAe7aUaaHJ4fG8oRjFgMfUI2sM4IySWHrBceFocY8pKy2REU1HwZIngtMdMrjqPnP-biofFWbNaP1cl0X1pZc2SQ-33hDH1LgNP-yg8ht7P5VWcj8iVVF8KnrZyV.ju8o70DBgQIHLwPJo2vIXA==

connectId

string

optional

Connection Id, a unique value taken from the client side. Both the id of the welcome message and the id of the error message are connectId.

Example:

121345

Topic: /contract/positionAll#

OR#

Topic:/contract/position:XBTUSDTM#

Subscribe Message#

Response#

Request

Topic: /contract/positionAll

OR

Topic:/contract/position:XBTUSDTM

Subscribe Message

Response