Get Position Info

Query real-time position data, such as position size, cumulative realizedPNL.

info

Trading account 2.0 - Query inverse positions

1. You can get all positions with "/v3/position/list?category=inverse".
2. Querying multiple symbols at once is not supported for inverse contracts.

HTTP Request

GET /cloud/trade/v3/position/list

Request Parameters

Parameter	Required	Type	Comments
category	true	string	Product type Trading account linear, inverse Normal account: linear, inverse. Please note that category is not involved with business logic and is only used for routing
symbol	false	string	Symbol name If symbol passed, it returns data regardless of having position or not. If symbol=null and settleCoin specified, it returns position size greater than zero.
baseCoin	false	string	Base coin.
settleCoin	false	string	Settle coin. For linear & inverse, 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 0: One-Way Mode 1: Buy side of both side mode 2: Sell side of both side mode
> riskId	integer	Risk limit ID.
> riskLimitValue	string	Risk limit value.
> symbol	string	Symbol name
> side	string	Position side. Buy: long, Sell: short. One-way: Classic account, empty position returns None. Unified account (linear): either one-way or hedge mode returns an empty string "" for an empty position.
> size	string	Position size
> avgPrice	string	Average entry price
> positionValue	string	Position value
> tradeMode	integer	Trade mode Classic account: 0 cross margin, 1 isolated margin Unified account (except inverse): deprecated, always 0. Please query account config to get the actual margin mode
> positionStatus	String	Position status. Normal, Liq, Adl
> leverage	string	Position leverage. Valid for contracts only.
> markPrice	string	Last mark price
> liqPrice	string	Position liquidation price. For unified account (isolated) and classic account: this is the real price for isolated and cross positions; when liqPrice <= minPrice or liqPrice >= maxPrice, it returns "". For unified account (cross margin): this is an estimated liquidation price for cross positions (risk rate is controlled at account level). When liqPrice <= minPrice or liqPrice >= maxPrice, it returns "". For portfolio margin mode, this field is empty and no liquidation price is provided
> bustPrice	string	Bankruptcy price.
> positionIM	string	Initial margin. Classic account: ignore this field Unified account portfolio margin (PM): returns empty string
> positionMM	string	Maintenance margin. Classic account: ignore this field Unified account portfolio margin (PM): returns empty string
> positionBalance	string	Position margin. Classic account can refer to this field to get position initial margin + closing fee
> 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
> isReduceOnly	boolean	Useful when Zoomex lowers the risk limit. true: Only allowed to reduce the position. You may consider a series of measures, e.g., lower the risk limit tier, decrease leverage or reduce the position, add margin, or cancel orders. After these operations, you can call the "confirm new risk limit" endpoint false (default): No restriction. It means your position is below the system risk level during adjustment Only meaningful for futures isolated and cross positions
> mmrSysUpdatedTime	string	Useful when Zoomex lowers the risk limit. When isReduceOnly=true: the timestamp when MMR will be forcibly adjusted by the system When isReduceOnly=false: if not empty, the timestamp when the MMR adjustment has been completed by the system Only set for system adjustments. Manual adjustments will not show a timestamp here Defaults to "". If this symbol has been downgraded by the system previously, it shows the most recent system operation timestamp Only meaningful for futures isolated and cross positions
> leverageSysUpdatedTime	string	Useful when Zoomex lowers the risk limit. When isReduceOnly=true: the timestamp when leverage will be forcibly adjusted by the system When isReduceOnly=false: if not empty, the timestamp when the leverage adjustment has been completed by the system Only set for system adjustments. Manual adjustments will not show a timestamp here Defaults to "". If this symbol has been downgraded by the system previously, it shows the most recent system operation timestamp Only meaningful for futures isolated and cross positions
> adlRankIndicator	integer	Auto-deleverage rank indicator. What is Auto-Deleveraging?
> createdTime	string	Position created timestamp (ms)
> updatedTime	string	Position updated timestamp (ms)
nextPageCursor	string	Refer to the cursor request parameter

---

Request Example

GET /cloud/trade/v3/position/list?category=inverse&symbol=BTCUSD HTTP/1.1
Host: openapi-testnet.zoomex.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: XXXXX
X-BAPI-TIMESTAMP: 1672280218882
X-BAPI-RECV-WINDOW: 5000

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
}