Get Historical Position Information

API Description

This interface allows querying all historical positions (filled orders). User can specify the base currency of an instrument and the position margin to retrieve more specific details.

Note: Historical position information data is only available via RESTful API.

Precautions

1. For a single position, there can be two possible events in the response: an opening event and a closing event. In the case of an opening event, the "netProfit" field will not be returned. However, for a closing event, the "netProfit" field will be included. This behavior should not be misunderstood as certain positions lacking "netProfit" information; rather, it is dependent on the event type.

Authentication

This is a private interface and requires authentication. For details on using the RESTful API, refer to Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface.

Request Method

GET

Endpoint

/v1/perpum/positions/history

Frequency Limit

The frequency limit for this interface is 15 requests/second per user ID and 100000 requests/second per IP. In addition to this per-interface limit, a global rate limit is also enforced.

For detailed information on Global rate limits and API Rate Limiting Policy, please refer to the "Frequency Limit" section at click here

Request Parameters

Parameter	Mandatory	Type	Description
instrument	false	String	The base currency of the instrument. (e.g., BTC or btc). This parameter is case-insensitive. Note: For instruments that start with numbers (e.g., 1000PEPE), both uppercase and lowercase formats are valid.
positionModel	false	Integer	Margin mode: 0: Isolated margin, 1: Cross margin.

Response Parameters

Parameter	Type	Description
avgOpenPrice	String	Average opening price
completeUsdt	String	Transaction amount in (USDT)
direction	String	Trade direction: long/short
entrustUsdt	String	Order size in USDT.
fee	String	Fees
havShortfall	boolean	Indicates whether the user is at risk of liquidation.
indexPrice	BigDecimal	Index price at trigger
instrument	String	Base currency of the instrument e.g., BTC or ETH.
leverage	String	Position leverage
liquidateBy	String	Reason for position closure: manual: Manually closed, stopProfit: Stop profit, stopLoss: Stop loss, cancel: Canceled, stepMarginClose: Step margin closing.
margin	String	Margin amount used for the position.
openId	Long	Position ID
orderId	Long	Order ID
orderStatus	String	Current order status: unFinish: Order unfulfilled, part: Partially filled, Finish: Fully filled, Cancel: Canceled.
originalType	String	Original order type
positionModel	integer	Position margin mode: 0: Isolated margin, 1: Cross position
status	String	Status:open/close
totalPiece	String	Total number of contracts
tradePiece	String	Filled contracts
tradeStartDate	Long	Creation date (Timestamp)
netProfit	String	Net profit or loss
userId	Long	User ID

Request Example

The following Python codes shows how to get the historical positions.

Note: For a complete code example, please refer to Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface.

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 rFuturesRestfulPrivate() is defined in section (Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface)

Note: For a complete Java code example, please refer to Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface.

Response Example

The following is an example response returned by the above Python request. The actual response included the history of all BTC positions with cross margin. For brevity, only one position information is shown below:

{'code': 0,
 'data': {'nextId': 0,
  'prevId': 0,
  'rows': [{'avgClosePrice': '118825.4',   # position closing event
 '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',  # position openning event
 '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': ''}