Get Position Info
Query real-time position data, such as position size, cumulative realizedPNL.
Unified account covers: USDT perpetual / USDC contract / Inverse contract / Options
Classic account covers: USDT perpetual / Inverse contract
info
Regarding inverse contracts,
- you can query all holding positions with "/v5/position/list?category=inverse";
symbol
parameter is supported to be passed with multiple symbols up to 10
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 , either symbol or settleCoin is required. symbol has a higher priority |
limit | false | integer | Limit for data size per page. [1 , 200 ]. Default: 20 |
cursor | false | string | Cursor. Use the nextPageCursor token from the response to retrieve the next page of the result set |
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
|
> size | string | Position size |
> avgPrice | string | Average entry price |
> positionValue | string | Position value |
> tradeMode | integer | Trade mode
|
> autoAddMargin | integer | Whether to add margin automatically. 0 : false, 1 : true. For UTA, it is meaningful only when UTA enables ISOLATED_MARGIN |
> 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
|
> 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 "" |
> positionBalance | string | Position margin |
> 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) |
> sessionAvgPrice | string | USDC contract session avg price, it is the same figure as avg entry price shown in the web UI |
> delta | string | Delta, unique field for option |
> gamma | string | Gamma, unique field for option |
> vega | string | Vega, unique field for option |
> theta | string | Theta, unique field for option |
> unrealisedPnl | string | Unrealised PnL |
> curRealisedPnl | string | The realised PnL for the current holding position |
> cumRealisedPnl | string | Cumulative realised pnl
|
> adlRankIndicator | integer | Auto-deleverage rank indicator. What is Auto-Deleveraging? |
> isReduceOnly | boolean | Useful when Bybit lower the risk limit
|
> mmrSysUpdatedTime | string | Useful when Bybit lower the risk limit
false : the timestamp when the MMR had been adjusted by system |
> leverageSysUpdatedTime | string | Useful when Bybit lower the risk limit
false : the timestamp when the leverage had been adjusted by system |
> createdTime | string | Position created timestamp (ms) |
> updatedTime | string | Position updated timestamp (ms) |
> seq | long | Cross sequence, used to associate each fill and each position update
|
nextPageCursor | string | Refer to the cursor request parameter |
Request Example
- HTTP
- Python
- Java
- Node.js
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",
))
import com.bybit.api.client.domain.*;
import com.bybit.api.client.domain.position.*;
import com.bybit.api.client.domain.position.request.*;
import com.bybit.api.client.service.BybitApiClientFactory;
var client = BybitApiClientFactory.newInstance().newAsyncPositionRestClient();
var positionListRequest = PositionDataRequest.builder().category(CategoryType.LINEAR).symbol("BTCUSDT").build();
client.getPositionInfo(positionListRequest, System.out::println);
const { RestClientV5 } = require('bybit-api');
const client = new RestClientV5({
testnet: true,
key: 'apikey',
secret: 'apisecret',
});
client
.getPositionInfo({
category: 'inverse',
symbol: 'BTCUSD',
})
.then((response) => {
console.log(response);
})
.catch((error) => {
console.error(error);
});
Response Example
{
"retCode": 0,
"retMsg": "OK",
"result": {
"list": [
{
"positionIdx": 0,
"riskId": 1,
"riskLimitValue": "150",
"symbol": "BTCUSD",
"side": "Sell",
"size": "300",
"avgPrice": "27464.50441675",
"positionValue": "0.01092319",
"tradeMode": 0,
"positionStatus": "Normal",
"autoAddMargin": 1,
"adlRankIndicator": 2,
"leverage": "10",
"positionBalance": "0.00139186",
"markPrice": "28224.50",
"liqPrice": "",
"bustPrice": "999999.00",
"positionMM": "0.0000015",
"positionIM": "0.00010923",
"tpslMode": "Full",
"takeProfit": "0.00",
"stopLoss": "0.00",
"trailingStop": "0.00",
"unrealisedPnl": "-0.00029413",
"curRealisedPnl": "0.00013123",
"cumRealisedPnl": "-0.00096902",
"seq": 5723621632,
"isReduceOnly": false,
"mmrSysUpdateTime": "",
"leverageSysUpdatedTime": "",
"sessionAvgPrice": "",
"createdTime": "1676538056258",
"updatedTime": "1697673600012"
}
],
"nextPageCursor": "",
"category": "inverse"
},
"retExtInfo": {},
"time": 1697684980172
}