Position

Subscribe to the position stream to see changes to your position data in real-time.

All-In-One Topic: position
Categorised Topic: position.linear, position.inverse, position.option

info

• All-In-One topic and Categorised topic cannot be in the same subscription request
• All-In-One topic: Allow you to listen to all categories (linear, inverse, option) websocket updates
• Categorised Topic: Allow you to listen only to specific category websocket updates

tip

Every time when you create/amend/cancel an order, the position topic will generate a new message (regardless if there's any actual change)

Response Parameters

Parameter	Type	Comments
id	string	Message ID
topic	string	Topic name
creationTime	number	Data created timestamp (ms)
data	array	Object
> category	string	Product type
> symbol	string	Symbol name
> side	string	Position side. Buy: long, Sell: short one-way mode: classic & UTA1.0(inverse), an empty position returns None. UTA2.0(linear, inverse) & UTA1.0(linear): either one-way or hedge mode returns an empty string "" for an empty position.
> size	string	Position size
> positionIdx	integer	Used to identify positions in different position modes
> tradeMode	integer	Trade mode Classic & UTA1.0(inverse): 0: cross-margin, 1: isolated margin UTA2.0, UTA1.0(execpt inverse): deprecated, always 0, check Get Account Info to know the margin mode
> positionValue	string	Position value
> riskId	integer	Risk tier ID for portfolio margin mode, this field returns 0, which means risk limit rules are invalid
> riskLimitValue	string	Risk limit value for portfolio margin mode, this field returns 0, which means risk limit rules are invalid
> entryPrice	string	Entry price
> markPrice	string	Mark price
> leverage	string	Position leverage for portfolio margin mode, this field returns "", which means leverage rules are invalid
> positionBalance	string	Position margin Classic & UTA1.0(inverse) can refer to this field to get the position initial margin
> autoAddMargin	integer	Whether to add margin automatically. 0: false, 1: true. For UTA, it is meaningful only when UTA enables ISOLATED_MARGIN
> positionIM	string	Initial margin Classic & UTA1.0(inverse): ignore this field UTA portfolio margin mode, it returns ""
> positionIMByMp	string	Initial margin calculated by mark price Classic & UTA1.0(inverse): ignore this field UTA portfolio margin mode, it returns ""
> positionMM	string	Maintenance margin Classic & UTA1.0(inverse): ignore this field UTA portfolio margin mode, it returns ""
> positionMMByMp	string	Maintenance margin calculated by mark price Classic & UTA1.0(inverse): ignore this field UTA portfolio margin mode, it returns ""
> liqPrice	string	Position liquidation price UTA1.0(inverse) & UTA(isolated margin enabled) & Classic account: it is the real price for isolated and cross positions, and keeps "" when liqPrice <= minPrice or liqPrice >= maxPrice UTA (Cross margin mode): it is an estimated price for cross positions(because the unified mode controls the risk rate according to the account), and keeps "" when liqPrice <= minPrice or liqPrice >= maxPrice However, this field is empty for Portfolio Margin Mode, and no liquidation price will be provided
> bustPrice	string	Bankruptcy price Unified mode returns "", no position bankruptcy price (except UTA1.0(inverse))
> tpslMode	string	deprecated, meaningless here, always "Full"
> takeProfit	string	Take profit price
> stopLoss	string	Stop loss price
> trailingStop	string	Trailing stop
> unrealisedPnl	string	Unrealised profit and loss
> curRealisedPnl	string	The realised PnL for the current holding position
> sessionAvgPrice	string	USDC contract session avg price, it is the same figure as avg entry price shown in the web UI
> delta	string	Delta. It is only pushed when you subscribe to the option position.
> gamma	string	Gamma. It is only pushed when you subscribe to the option position.
> vega	string	Vega. It is only pushed when you subscribe to the option position.
> theta	string	Theta. It is only pushed when you subscribe to the option position.
> cumRealisedPnl	string	Cumulative realised pnl Futures & Perp: it is the all time cumulative realised P&L Option: it is the realised P&L when you hold that position
> positionStatus	string	Position status. Normal, Liq, Adl
> adlRankIndicator	integer	Auto-deleverage rank indicator. What is Auto-Deleveraging?
> isReduceOnly	boolean	Useful when Bybit lower the risk limit true: Only allowed to reduce the position. You can consider a series of measures, e.g., lower the risk limit, decrease leverage or reduce the position, add margin, or cancel orders, after these operations, you can call confirm new risk limit endpoint to check if your position can be removed the reduceOnly mark false: There is no restriction, and it means your position is under the risk when the risk limit is systematically adjusted Only meaningful for isolated margin & cross margin of USDT Perp, USDC Perp, USDC Futures, Inverse Perp and Inverse Futures, meaningless for others
> mmrSysUpdatedTime	string	Useful when Bybit lower the risk limit When isReduceOnly=true: the timestamp (ms) when the MMR will be forcibly adjusted by the system When isReduceOnly=false: the timestamp when the MMR had been adjusted by system It returns the timestamp when the system operates, and if you manually operate, there is no timestamp Keeps "" by default, if there was a lower risk limit system adjustment previously, it shows that system operation timestamp Only meaningful for isolated margin & cross margin of USDT Perp, USDC Perp, USDC Futures, Inverse Perp and Inverse Futures, meaningless for others
> leverageSysUpdatedTime	string	Useful when Bybit lower the risk limit When isReduceOnly=true: the timestamp (ms) when the leverage will be forcibly adjusted by the system When isReduceOnly=false: the timestamp when the leverage had been adjusted by system It returns the timestamp when the system operates, and if you manually operate, there is no timestamp Keeps "" by default, if there was a lower risk limit system adjustment previously, it shows that system operation timestamp Only meaningful for isolated margin & cross margin of USDT Perp, USDC Perp, USDC Futures, Inverse Perp and Inverse Futures, meaningless for others
> createdTime	string	Timestamp of the first time a position was created on this symbol (ms)
> updatedTime	string	Position data updated timestamp (ms)
> seq	long	Cross sequence, used to associate each fill and each position update Different symbols may have the same seq, please use seq + symbol to check unique Returns "-1" if the symbol has never been traded Returns the seq updated by the last transaction when there are setting like leverage, risk limit

Subscribe Example

{
    "op": "subscribe",
    "args": [
        "position"
    ]
}

from pybit.unified_trading import WebSocket
from time import sleep
ws = WebSocket(
    testnet=True,
    channel_type="private",
    api_key="xxxxxxxxxxxxxxxxxx",
    api_secret="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)
def handle_message(message):
    print(message)
ws.position_stream(callback=handle_message)
while True:
    sleep(1)

Stream Example

{
    "id": "1003076014fb7eedb-c7e6-45d6-a8c1-270f0169171a",
    "topic": "position",
    "creationTime": 1697682317044,
    "data": [
        {
            "positionIdx": 2,
            "tradeMode": 0,
            "riskId": 1,
            "riskLimitValue": "2000000",
            "symbol": "BTCUSDT",
            "side": "",
            "size": "0",
            "entryPrice": "0",
            "leverage": "10",
            "positionValue": "0",
            "positionBalance": "0",
            "markPrice": "28184.5",
            "positionIM": "0",
            "positionIMByMp": "0",
            "positionMM": "0",
            "positionMMByMp": "0",
            "takeProfit": "0",
            "stopLoss": "0",
            "trailingStop": "0",
            "unrealisedPnl": "0",
            "curRealisedPnl": "1.26",
            "cumRealisedPnl": "-25.06579337",
            "sessionAvgPrice": "0",
            "createdTime": "1694402496913",
            "updatedTime": "1697682317038",
            "tpslMode": "Full",
            "liqPrice": "0",
            "bustPrice": "",
            "category": "linear",
            "positionStatus": "Normal",
            "adlRankIndicator": 0,
            "autoAddMargin": 0,
            "leverageSysUpdatedTime": "",
            "mmrSysUpdatedTime": "",
            "seq": 8327597863,
            "isReduceOnly": false
        }
    ]
}