We do not store the mark price on our site, however it is possible to recreate the exact mark price at the time of your liquidation, using the REST API, in order to verify if a liquidation was correctly processed by the liquidation engine.


Using the formula presented in our references and our API explorer you can easily calculate the mark price at the exact time of your liquidation if you follow the steps below.


This is the formulas used for calculating the mark price:


  • Funding Basis = Funding Rate * (Time Until Funding / Funding Interval)
  • Fair Price = Index Price * (1 + Funding Basis)


You can pull the data from the REST API, using either the direct links or the API explorer, the respective end points for the API explorer are:


  1. Instrument/Instrument_getCompositeIndex
  2. /Funding/Funding_get


Please note that the .BXBT price that you note on the graph, is pasted in one minute intervals, and does not include the 5-second snapshot price movements of the index (this counts for any and all liquidations.) 


For this we need to use the composite index, which is a constant 5 second snapshot, that is used to calculate the one minute average index price. (1)


To Begin


There are a few details which you must ensure that you include if you would like the correct results to be printed by the REST API, below is an image of BitMEX's API Explorer.



1) The most common mistake is inputting an incorrect startTime and endTime, both dates need to be in JSON format. 


Provided in the yellow example box: 2018-02-22T09:11:02.774Z = 22 February 2018 at 9:11:02 AM UTC, where the 02 is seconds & the .774Z is the milliseconds.


You need to ensure that your startTime and endTime interval include the timestamp of your liquidation, which is given in your liquidation email. (Example below, date highlighted)



The above date (Tue, 16 Jan 2018 11:47:08 GMT) can easily be converted to JSON if you alter the dates provided in the API Explorer in the example value. It would be: 2018-01-16T11:47:08.000Z 




Part 1: .BXBT Index


We find the following API link: 

https://www.bitmex.com/api/v1/instrument/compositeIndex?symbol=.XBT&count=100&reverse=false&startTime=2018-01-16T11%3A47%3A00.000Z&endTime=2018-01-16T11%3A47%3A10.000Z


With the following response body (the data you need):


BMI is the Index price which is calculated as a weighted average of the Last Price for each constituent exchange.


[
  {
    "timestamp": "2018-01-16T11:47:00.000Z",
    "symbol": ".XBT",
    "indexSymbol": ".XBT",
    "reference": "BMI",
    "lastPrice": 12392.45,
    "weight": null,
    "logged": "2018-01-16T11:47:00.098Z"
  },
  {
    "timestamp": "2018-01-16T11:47:00.000Z",
    "symbol": "BTC-USD",
    "indexSymbol": ".XBT",
    "reference": "GDAX",
    "lastPrice": 12395.91,
    "weight": 0.5,
    "logged": "2018-01-16T11:47:00.098Z"
  },
  {
    "timestamp": "2018-01-16T11:47:00.000Z",
    "symbol": "BTCUSD",
    "indexSymbol": ".XBT",
    "reference": "BSTP",
    "lastPrice": 12388.99,
    "weight": 0.5,
    "logged": "2018-01-16T11:47:00.098Z"
  },
  {
    "timestamp": "2018-01-16T11:47:05.000Z",
    "symbol": ".XBT",
    "indexSymbol": ".XBT",
    "reference": "BMI",
    "lastPrice": 12399.5,
    "weight": null,
    "logged": "2018-01-16T11:47:05.098Z"
  },
  {
    "timestamp": "2018-01-16T11:47:05.000Z",
    "symbol": "BTC-USD",
    "indexSymbol": ".XBT",
    "reference": "GDAX",
    "lastPrice": 12400,
    "weight": 0.5,
    "logged": "2018-01-16T11:47:05.098Z"
  },
  {
    "timestamp": "2018-01-16T11:47:05.000Z",
    "symbol": "BTCUSD",
    "indexSymbol": ".XBT",
    "reference": "BSTP",
    "lastPrice": 12399,
    "weight": 0.5,
    "logged": "2018-01-16T11:47:05.098Z"
  }
]


We take the lastPrice: 12399.5




Part 2: Funding Rate





We find the following API link: 

https://www.bitmex.com/api/v1/funding?count=100&reverse=false&startTime=2018-01-16T11%3A47%3A00.000Z


With the following response body (the data you need):


Note that the fundingRate must be multiplied by 100, to convert the value into percentage!


You need to take the first fundingRate that occurs after your liquidation as that will be the fundingRate at the time of the liquidation, in this examples case, 12:00:00 is the first funding timestamp after 11:47 UTC. 

[
  {
    "timestamp": "2018-01-16T12:00:00.000Z",
    "symbol": "XBTUSD",
    "fundingInterval": "2000-01-01T08:00:00.000Z",
    "fundingRate": -0.000559,
    "fundingRateDaily": -0.001677
  }
]



Now that you have the respective data you can calculate the exact mark price at the time-stamp of your liquidation.




We recall the formulas used for calculating the mark price:

  • Funding Basis = Funding Rate * (Time Until Funding / Funding Interval)
  • Fair Price = Index Price * (1 + Funding Basis)



As regards (Time until funding/funding interval), from the reference page it is stated that funding occurs every 8 hours. 


Therefore you must calculate the (Time until funding) value from your timestamp. We know that the timestamp used in this example is 11:47, therefore time until funding is 13 minutes. However, we need to convert this into hours and thereafter we can calculate the first part of the formula (Funding Basis)


To convert into hours: 13/60 minutes = 0.21666666666 hours


Funding Rate: -0,000559 x 100 = -0,0559


Funding Basis: -0,0559% x (0.21666666666/8) = -0.00001513958


Index (.BXBT) price at the timestamp = 12399.5 


Finally you calculate your fair price


Fair price = 12399.5 * (1 - 0.00001513958)

               

 = 12399.3122768





Therefore we can conclude that the liquidation was valid if the fair price you calculate and the mark price on your email match after rounding and that the liquidation engine properly liquidated your position in accordance with the liquidation engines parameters as set by the formulas.


If you need any further clarification, please don't hesitate to contact support.