查詢持倉 (實時)

該接口可以獲取用戶的持倉信息，比如持倉數量，累計盈虧等

信息

統一帳戶2.0 - 查詢反向合約倉位

通過這種查詢方式 "/v5/position/list?category=inverse", 可以獲得所有持倉數據
不支持傳入多個symbol來查詢關於反向合約的額外查詢規則,

統一帳戶1.0 和經典帳戶 - 查詢反向合約倉位

通過這樣子查詢"/v5/position/list?category=inverse", 您可以查詢到所有當前持有的反向合約倉位;
symbol字段支持傳入最多10個反向合約, 比如 symbol=BTCUSD,ETHUSD,SOLUSD

HTTP 請求

GET /v5/position/list

請求參數

參數	是否必需	類型	說明
category	true	string	產品類型統一帳戶2.0, 統一帳戶1.0: `linear`,`inverse`, `option` 經典帳戶: `linear`, `inverse`
symbol	false	string	合約名稱若傳了`symbol`, 則不管是否有倉位都返回該symbol數據若`symbol`不傳但傳了`settleCoin`, 則僅返回有實際倉位的數據
baseCoin	false	string	交易幣種, 若不傳, 則返回期權下所有持倉僅適用於`option`
settleCoin	false	string	結算幣種 USDT和USDC期貨: `symbol`和`settleCon`必傳其中一個, 若都傳，則`symbol`有更高的優先級
limit	false	integer	每頁數量限制. [`1`, `200`]. 默認: `20`
cursor	false	string	游標，用於翻頁

響應參數

參數	類型	說明
category	string	產品類型
list	array	Object
> positionIdx	integer	倉位標識符, 用于在不同仓位模式下标识仓位
> riskId	integer	风险限额ID, 參見風險限額接口若賬戶為組合保證金模式(PM), 該字段返回0, 風險限額規則失效
> riskLimitValue	string	當前風險限額ID對應的持倉限制量若賬戶為組合保證金模式(PM)，該字段返回"", 風險限額規則失效
> symbol	string	合約名称
> side	string	持倉方向, Buy: 多头; Sell: 空头. 單向持倉: 經典帳戶 & 統一帳戶1.0(inverse), 空倉返回`None`. 統一帳戶2.0和統一帳戶1.0(linear): 空倉時, 單向或者雙向持倉模式都返回空字符串 `""`
> size	string	當前倉位的合约數量, 總是正數
> avgPrice	string	當前倉位的平均入場價格對於8小時結算的USDC合約倉位, 該字段表示的是平均開倉價格, 不隨著結算而改變
> positionValue	string	仓位的價值
> tradeMode	integer	交易模式經典帳戶 & 統一帳戶1.0(inverse): `0`: 全倉保證金, `1`: 逐倉保證金統一帳戶2.0, 統一帳戶1.0(除了反向): 該字段無效, 總是 `0`, 請通過接口查詢賬戶配置查詢帳戶保證金模式
> autoAddMargin	integer	是否自動追加保證金, 反向合約不支持設置自動追加保證金 `0`: 否 `1`: 是
> positionStatus	String	倉位状态. `Normal`,`Liq`, `Adl`
> leverage	string	當前倉位的槓桿，仅适用于合约若賬戶為組合保證金模式(PM), 該字段返回空字符串, 槓桿規則失效
> markPrice	string	symbol 的最新標記價格
> liqPrice	string	倉位強平價格對於統一帳戶2.0(逐倉), 統一帳戶1.0(逐倉), 統一帳戶1.0(反向合約), 經典帳戶: 是逐倉和全倉持仓的真實價格, 當強平價 <= minPrice或者強平價 >= maxPrice, 則為`""`。對於統一帳戶2.0(全倉保證金), 統一帳戶1.0(全倉保證金): 請注意, 這是預計強平價格僅供參考。僅當帳戶維持保證金率達到100%時會觸發強平, 當強平價 <= minPrice或者強平價 >= maxPrice, 則為`""` 對於組合保證金模式, 此字段為空, 不會提供強平價格
> bustPrice	string	倉位破產價格,僅適用於經典帳戶，對於統一帳戶，將始終返回空值
> positionIM	string	倉位起始保證金經典帳戶 & 統一帳戶1.0(inverse): 忽略該字段統一帳戶組合保證金模式(PM)下, 該字段返回為空字符串
> positionIMByMp	string	倉位起始保證金(用mark price計算) 經典帳戶 & 統一帳戶1.0(inverse) : 忽略該字段統一帳戶組合保證金模式(PM)下, 該字段返回為空字符串
> positionMM	string	倉位維持保證金經典帳戶 & 統一帳戶1.0(inverse): 忽略該字段統一帳戶組合保證金模式(PM)下, 該字段返回為空字符串
> positionMMByMp	string	倉位維持保證金(用mark price計算) 經典帳戶 & 統一帳戶1.0(inverse): 忽略該字段統一帳戶組合保證金模式(PM)下, 該字段返回為空字符串
> positionBalance	string	倉位保證金經典帳戶 & 統一帳戶1.0(inverse)可以根據這個字段了解倉位初始保證金+平倉手續費
> takeProfit	string	止盈價格
> stopLoss	string	止損價格
> trailingStop	string	追蹤止損（與當前價格的距離）
> sessionAvgPrice	string	USDC合約平均持倉價格, 會隨著8小時結算而變動
> delta	string	Delta
> gamma	string	Gamma
> vega	string	Vega
> theta	string	Theta
> unrealisedPnl	string	未结盈亏
> curRealisedPnl	string	當前持倉的已結盈虧
> cumRealisedPnl	string	累计已结盈亏期貨: 是從第一次開始有持倉加總的已結盈虧期權: 總是"", 無意義
> adlRankIndicator	integer	自動減倉燈. 什麼是自動減倉機制?
> createdTime	string	倉位創建時間
> updatedTime	string	倉位數據更新時間
> seq	long	序列號, 用於關聯成交和倉位的更新不同的幣對會存在相同seq, 可以使用seq + symbol來做唯一性識別如果該幣對從未被交易過, 查詢時則會返回`"-1"` 對於更新槓桿、更新風險限額等非交易行為, 將會返回上一次成交時更新的seq
> isReduceOnly	boolean	僅當Bybit需要降低某個Symbol的風險限額時有用 `true`: 僅允許減倉操作. 您可以考慮一系列的方式, 比如, 降低risk limit檔位, 或者同檔位修改槓桿或減少倉位, 或者增加保證金, 或者撤單, 這些操作做完後, 可以主動調用確認新的風險限額接口 `false`(默認): 沒有交易限制, 表示您的倉位在系統調整時處於風險水平之下僅對逐倉和全倉的期貨倉位有意義
> mmrSysUpdatedTime	string	僅當Bybit需要降低某個Symbol的風險限額時有用當isReduceOnly=`true`: 這個時間戳表示系統強制修改MMR的時間當isReduceOnly=`false`: 若不為空, 則表示系統已經完成了MMR調整的時間僅當系統調整才會賦值, 對於主動的調整, 不會在這裡展示時間戳默認為`""`, 但如果曾經這個symbol有過系統降檔的操作, 那麼這裡會顯示上一次操作的時間僅對逐倉和全倉的期貨倉位有意義
> leverageSysUpdatedTime	string	僅當Bybit需要降低某個Symbol的風險限額時有用當isReduceOnly=`true`: 這個時間戳表示系統強制修改槓桿的時間當isReduceOnly=`false`: 若不為空, 則表示系統已經完成了槓桿調整的時間僅當系統調整才會賦值, 對於主動的調整, 不會在這裡展示時間戳默認為`""`, 但如果曾經這個symbol有過系統降檔的操作, 那麼這裡會顯示上一次操作的時間僅對逐倉和全倉的期貨倉位有意義
> tpslMode	string	該字段廢棄, 無意義, 總是返回"Full". 期權總是返回""
nextPageCursor	string	游標，用於翻頁

請求示例

HTTP
Python
Java
Node.js

GET /v5/position/list?category=linear&symbol=XRPUSDT HTTP/1.1
Host: api-testnet.bybit.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1672280218882
X-BAPI-RECV-WINDOW: 5000

from pybit.unified_trading import HTTP
session = HTTP(
    testnet=True,
    api_key="xxxxxxxxxxxxxxxxxx",
    api_secret="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)
print(session.get_positions(
    category="linear",
    symbol="XRPUSDT",
))

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: 'xxxxxxxxxxxxxxxxxx',
    secret: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
});

client
    .getPositionInfo({
        category: 'inverse',
        symbol: 'BTCUSD',
    })
    .then((response) => {
        console.log(response);
    })
    .catch((error) => {
        console.error(error);
    });

響應示例

{
    "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",
                "positionMMByMp": "0.0000015",
                "positionIM": "0.00010923",
                "positionIMByMp": "0.00010923",
                "tpslMode": "Full",
                "takeProfit": "0.00",
                "stopLoss": "0.00",
                "trailingStop": "0.00",
                "unrealisedPnl": "-0.00029413",
                "sessionAvgPrice": "",
                "curRealisedPnl": "0.00013123",
                "cumRealisedPnl": "-0.00096902",
                "seq": 5723621632,
                "isReduceOnly": false,
                "mmrSysUpdateTime": "",
                "leverageSysUpdatedTime": "",
                "createdTime": "1676538056258",
                "updatedTime": "1697673600012"
            }
        ],
        "nextPageCursor": "",
        "category": "inverse"
    },
    "retExtInfo": {},
    "time": 1697684980172
}

HTTP 請求​

請求參數​

響應參數​

請求示例​

響應示例​

HTTP 請求

請求參數

響應參數

請求示例

響應示例