Get Position Info
Query real-time position data, such as position size, cumulative realizedPNL.
Unified account covers: USDT perpetual / USDC contract / Inverse contract / Options
Normal account covers: USDT perpetual / Inverse contract
HTTP Request
GET /v5/position/list
Request Parameters
Parameter | Required | Type | Comments |
---|---|---|---|
category | true | string | Product type
|
symbol | false | string | Symbol name
|
baseCoin | false | string | Base coin. option only. Return all option positions if not passed |
settleCoin | false | string | Settle coin. For linear & inverse , either symbol or settleCon is required. symbol has a higher priority |
limit | false | integer | Limit for data size per page. [1 , 200 ]. Default: 20 |
cursor | false | string | Cursor. Used for pagination |
Response Parameters
Parameter | Type | Comments |
---|---|---|
category | string | Product type |
list | array | Object |
> positionIdx | integer | Position idx, used to identify positions in different position modes
|
> riskId | integer | Risk limit ID. Note: for portfolio margin mode, this field returns 0, which means risk limit rules are invalid |
> riskLimitValue | string | Risk limit value. Note: for portfolio margin mode, this field returns 0, which means risk limit rules are invalid |
> symbol | string | Symbol name |
> side | string | Position side. Buy : long, Sell : short. Note: under one-way mode, it returns None if empty position |
> size | string | Position size |
> avgPrice | string | Average entry price |
> positionValue | string | Position value |
> tradeMode | integer | Trade mode. 0 : cross-margin, 1 : isolated margin |
> autoAddMargin | integer | Whether to add margin automatically. 0 : false, 1 : true. Unified account(spot/linear/option) does not return this field |
> positionStatus | String | Position status. Normal , Liq , Adl |
> leverage | string | Position leverage. Valid for contract. Note: for portfolio margin mode, this field returns "", which means leverage rules are invalid |
> markPrice | string | Last mark price |
> liqPrice | string | Position liquidation price. Note: the value returned in the unified mode is the estimated liquidation price, because the unified margin mode controls the risk rate according to the account, so the liquidation price on a single position is only estimated (exclude inverse trade under UTA) |
> bustPrice | string | Bankruptcy price. Note: Unified mode returns "" , no position bankruptcy price (exclude inverse trade under UTA) |
> positionIM | string | Initial margin. For portfolio margin mode, it returns "" |
> positionMM | string | Maintenance margin. For portfolio margin mode, it returns "" |
> tpslMode | string | Depreciated, meaningless here, always "Full". Spot does not return this field. Option returns "" |
> takeProfit | string | Take profit price |
> stopLoss | string | Stop loss price |
> trailingStop | string | Trailing stop (The distance from market price) |
> unrealisedPnl | string | Unrealised PnL |
> cumRealisedPnl | string | Cumulative realised pnl |
> adlRankIndicator | integer | Auto-deleverage rank indicator. What is Auto-Deleveraging? |
> createdTime | string | Position created timestamp (ms) |
> updatedTime | string | Position updated timestamp (ms) |
nextPageCursor | string | Cursor. Used for pagination |
Request Example
- HTTP
- Python
GET /v5/position/list?category=inverse&symbol=BTCUSD HTTP/1.1
Host: api-testnet.bybit.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: XXXXX
X-BAPI-TIMESTAMP: 1672280218882
X-BAPI-RECV-WINDOW: 5000
from pybit.unified_trading import HTTP
session = HTTP(
testnet=True,
api_key="XXXXX",
api_secret="XXXXX",
)
print(session.get_positions(
category="inverse",
symbol="BTCUSD",
))
Response Example
{
"retCode": 0,
"retMsg": "OK",
"result": {
"list": [
{
"positionIdx": 0,
"riskId": 1,
"riskLimitValue": "150",
"symbol": "BTCUSD",
"side": "Sell",
"size": "299",
"avgPrice": "30004.5006751",
"positionValue": "0.00996518",
"tradeMode": 0,
"positionStatus": "Normal",
"autoAddMargin": 1,
"adlRankIndicator": 2,
"leverage": "10",
"positionBalance": "0.00100189",
"markPrice": "26926.00",
"liqPrice": "999999.00",
"bustPrice": "999999.00",
"positionMM": "0.0000015",
"positionIM": "0.00009965",
"tpslMode": "Full",
"takeProfit": "0.00",
"stopLoss": "0.00",
"trailingStop": "0.00",
"unrealisedPnl": "0.00113932",
"cumRealisedPnl": "-0.00121275",
"createdTime": "1676538056258",
"updatedTime": "1684742400015"
}
],
"nextPageCursor": "",
"category": "inverse"
},
"retExtInfo": {},
"time": 1684767531904
}