获取历史持仓信息

API说明

此接口允许查询所有历史持仓（已成交订单）。用户可以指定交易品种基础货币和持仓保证金来检索更具体的详情。

注意：历史持仓信息数据只能通过 RESTful API 获取。

注意事项

对于单个持仓，响应中可能包含两种事件：开仓事件和平仓事件。在开仓事件中，不会返回 "netProfit" 字段；而在平仓事件中，则会包含 "netProfit" 字段。这种行为不应被误解为某些持仓缺少 "netProfit" 信息，而是取决于事件类型

认证

这是一个私有接口，需要认证。有关使用RESTful API的详细信息，请参考简介 > 认证和代码示例 > 合约 > RESTful私有接口。

请求方法

GET

接口地址

/v1/perpum/positions/history

频率限制

该接口的调用频率限制为每个用户 ID 每秒 15 个请求，每个 IP 每秒 100000 个请求。
此外，该接口还受到全局频率限制的约束。
有关"全局速率限制"和"API限频策略"的详细信息，请参阅“频率限制”部分，跳转

请求参数

参数	必填	类型	描述
instrument	false	String	交易品种的基础货币（例如，BTC或btc）。此参数不区分大小写。注意：对于以数字开头的交易品种（例如1000PEPE），大写和小写格式都有效。
positionModel	false	Integer	持仓模式：0：逐仓，1：全仓

响应参数

参数	类型	描述
avgOpenPrice	String	平均开仓价格
completeUsdt	String	交易金额（USDT）
direction	String	交易方向：做多(long)/做空(short)
entrustUsdt	String	USDT订单规模
fee	String	费用
havShortfall	boolean	表示用户是否有清算风险
indexPrice	BigDecimal	触发时的指数价格
instrument	String	交易品种的基础货币，例如BTC或ETH
leverage	String	持仓杠杆率
liquidateBy	String	持仓平仓原因：manual：手动平仓，stopProfit：止盈，stopLoss：止损，cancel：已取消，stepMarginClose：阶梯保证金平仓
margin	String	持仓使用的保证金金额
openId	Long	持仓ID
orderId	Long	订单ID
orderStatus	String	当前订单状态：unFinish：订单未成交part：部分成交Finish：完全成交Cancel：已取消
originalType	String	原始订单类型
positionModel	integer	持仓持仓模式：0：逐仓，1：全仓
status	String	状态：open/close
totalPiece	String	合约总数量
tradePiece	String	已成交合约
tradeStartDate	Long	创建日期（时间戳）
netProfit	String	盈亏/收益
userId	Long	用户ID

请求示例

以下Python代码展示了如何获取历史持仓。

注意：完整代码示例请参考简介 > 认证和代码示例 > 合约 > Restful私有接口。

params = {
        "instrument": "BTC",    
        "positionModel" : 1,  
    }
 
api_url = "/v1/perpum/positions/history"
method = "GET"
response_code, response_data = FuturesRestfulPrivate(params, api_url, method, sec_key, api_key)   # function FuturesRestfulPrivate() is defined in section (Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface)

注意：完整Java代码示例请参考简介 > 认证和代码示例 > 合约 > RESTful私有接口。

响应示例

以下是上述Python请求返回的示例响应。实际响应包括所有全仓保证金的BTC持仓历史。为简洁起见，以下仅显示一个持仓信息：

{'code': 0,
 'data': {'nextId': 0,
  'prevId': 0,
  'rows': [{'avgClosePrice': '118825.4',    #平仓事件
 'avgOpenPrice': '118737.9',
 'avgPrice': '118825.4',
 'base': 'btc',
 'completeUsdt': '118.8',
 'direction': 'long',
 'entrustUsdt': '118.8',
 'fee': '0.07129524',
 'havShortfall': False,
 'indexPrice': '118825.6',
 'instrument': 'BTC',
 'isMultiCurrency': True,
 'leverage': '1',
 'liquidateBy': 'manual',
 'margin': '118.66665726',
 'netProfit': '0.0875',
 'openId': '2435521222636484675',
 'orderId': '33308947151523774',
 'orderStatus': 'finish',
 'originalType': 'execute',
 'positionModel': 0,
 'profitRate': '0.07%',
 'quote': 'usdt',
 'status': 'close',
 'totalPiece': '1',
 'tradePiece': '1',
 'tradeStartDate': 1754989457000,
 'userId': '1162061'},
 {'avgOpenPrice': '118737.9',  #开仓事件
 'base': 'btc',
 'completeUsdt': '118.7',
 'direction': 'long',
 'entrustUsdt': '118.7',
 'fee': '0.07124274',
 'havShortfall': False,
 'indexPrice': '118735.8',
 'instrument': 'BTC',
 'leverage': '1',
 'liquidateBy': 'manual',
 'margin': '118.66665726',
 'openId': '2435521222636484675',
 'orderId': '33308947148738327',
 'orderStatus': 'finish',
 'originalType': 'execute',
 'positionModel': 0,
 'quote': 'usdt',
 'status': 'open',
 'totalPiece': '1',
 'tradePiece': '1',
 'tradeStartDate': 1754989301000,
 'userId': '1162061'}
 ],
  'total': 1},
 'msg': ''}

API说明​

注意事项​

认证​

请求方法​

接口地址​

频率限制​

请求参数​

响应参数​

请求示例​

响应示例​