API

1.API

Deribit API is divided in public and private parts. Users are required to apply for API authentication to be able to use the private API. Please go to Settings, enable REST & WebSocket API access, save and use your Access Key and Access Secret for further authorization of API request as described below. Example of API can be accessed via Settings -> REST&WebSocket Testing Console. Important Note: Do not reveal to anybody your ’Access Secret’, it is as important as your password. 

In the left menu of the trading application is a link to a API console where you can use and test the REST API and WEBSOCKETS API.

1.1.Naming

Deribit tradeable assets or instruments use following system of naming:

Kind Examples Template Comments
Future BTC-25MAR16, BTC-5AUG16 BTC-DMMMYY Template DMMMYY – is expiration date, D stands for day, MMM – month (3 first letters in English), YY stands for year
Option BTC-25MAR16-420-C, BTC-5AUG16-580-P BTC-DMMMYY-STRIKE-K Template STRIKE is option strike-price in USD. Template K is option kind, C for CALL options or P for PUT options.
Option, Future BTC-THISWEEK, BTC-NEXTWEEK, BTC-THISWEEK-580-C, BTC-NEXTWEEK-590-P (date aliases THISWEEK, NEXTWEEK) expiration date aliases THISWEEK, NEXTWEEK Expiration date instead of the explicit DMMMYY date. Note that subscribe API will not resubscribe after expiration of the expired instrument subscribed via aliases, i.e., the aliases are interpreted at the moment of the api call.

1.2.Timing

Timing

Successfull call of API returns JSON object with msIn and msOut fields:
msIn – server input time in milliseconds (when server has received the API call)
msOut – server output time in milliseconds
Notification messages have msOut only.

1.3.Rate Limits

Currently there is no fixed rate limit for http requests. The only limit currently imposed is to have no more than 8 simultaneous requests in the pipeline of the exchange. Due to an average latency of less than 1ms, the average trade bot will not have any problems with limitations. For market makers that need even less restricted access, please contact support. (for example if you need to be able to place or cancel 200 orders per second)

2.REST API

REST API consists of a public part and private part.
Private API requests must be signed. The signature is placed in the custom header ’x-deribit-sig’. The ’x-deribit-sig’ header is constructed as follows:
  • Use millisecond UTC timestamp to generate Nonce = ms timestamp UTC
  • Combine the Nonce, Access Key, Access Secret, URI Path (the path part of URI of the specific request, see below) and all request parameters (paramX – name of the X-th parameter, valueX – value of the X-th parameter) in a single string using token ’&’ as follows:
    • the string is ’_=Nonce&_ackey=Access Key&_acsec=Access Secret&_action=URI Path&param1=value1&param2=value2….&paramN=valueN’, if API request has no parameters the string is just ’_=Nonce&_ackey=Access Key&_acsec=Access Secret&_action=URI Path’
    • if the X-th value (corresponding to the valueX) is of array type, for instance [’a’, ’b’, ’c’], the entries should be concatenated in a single string, i.e., the resulting valueX = ’abc’
    • the parameters (param1, param2, …) must be sorted alphabetically according to the parameters’ name
    • do not reveal the string to anybody as it contains your Access Secret.
  • Create sha256 hash from the obtained string
  • The resulting sha256-hash is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line
  • Join the AccessKey, Nonce and obtained Base64(Hash) in a single string using ’.’ token, i.e., the result is ’x-deribit-sig’ header equal to AccessKey.Nonce.Base64(Hash)

Javascript code example:

tstamp = 1452237485895
data = ’_=1452237485895&_ackey=29mtdvvqV56&_acsec=BP2FEOFJLFENIYFBJI7PYWGFNPZOTRCE&_action=/api/v1/private/buy&instrument=BTC-15JAN16&price=500&quantity=1’
signature = ’29mtdvvqV56.1452237485895.0nkPWTDunuuc220vojSTirSj8/2eGT8Wv30YeLj+i4c=’

jQuery.ajax({
            type: method,
            url: uri,
            data: params,
			headers: [{’x-deribit-sig’: signature}],
            success: function (data) {
                ...
            },
            dataType: ’json’
        });

Working sample javascript code is available online via Deribit API console, https://deribit.com/static/js/scripts/apiconsole.js

3.Public API

3.1.getinstruments

Get the open and available trading instruments.
URI: https://deribit.com/api/v1/public/getinstruments
URI Path: /api/v1/public/getinstruments
Parameters: none
Method: GET
Result is JSON object:
{"success": true,  // false or true
 "message": "",    // empty or text message
 "result": [{
		"kind": "option",  			// future or option
		"baseCurrency": "BTC", 		// currently BTC only
		"currency": "USD",     		// currently USD only
		"minTradeSize": 0.01,		  // minimum size
		"instrumentName": "BTC-30JAN15-450-P", // instrument name
		"isActive": true,              // true or false
		"settlement": "month",         
		"created": "2014-12-09 11:34:24 GMT", // GMT date time
		"expiration": "2015-01-30 15:00:00 GMT" // GMT date time
			}, ...]}

3.2.index

Get price index, BTC-USD rates.
URI: https://deribit.com/api/v1/public/index
URI Path: /api/v1/public/index
Parameters: none
Method: GET
Result is JSON object:
{
    "success": true, // false or true
    "message": "",   // empty or text message
    "result": {
        "btc": 780.59  // float, BTC-USD exchange rates
    }
}

3.3.getcurrencies

Get all supported currencies.
URI: https://deribit.com/api/v1/public/getcurrencies
URI Path: /api/v1/public/getcurrencies
Parameters: none
Method: GET
Result is JSON object:
{"success": true, // true or false
 "message": "",   // empty or text message
 "result": [{
		"currency": "BTC",			// currently BTC only
		"currencyLong": "Bitcoin",    // currently Bitcoin
		"minConfirmation": 2,         // minimum confirmation for deposit
		"txFee": 0.0001,              // transaction fee in BTC
		"isActive": true,			 // true or false
        "coinType": "BITCOIN",		// currently BITCOIN only
	    "baseAddress": null		   
        }]}

3.4.getorderbook

Retrieve the orderbook for a given instrument.
URI: https://deribit.com/api/v1/public/getorderbook
URI Path: /api/v1/public/getorderbook
Parameters: instrument – string [optional], instrument name, example “BTC-19DEC14”, see getinstruments
Method: GET
Result is JSON object:
{
    "success": true,  // true or false
    "message": "",    // empty or text message
    "result": {
        "bids": [      // buy orders
            {
                "quantity": 2,     // quantity, in contracts ($10 per contract for futures, ฿1 — for options)
                "price": 416.02,   // float USD for futures, BTC for options
                "cm": 2            // cumulative quantity, with better orders, "quantity" is less or equal to the "cm"
            }
        ],
        "asks": [
            {
                "quantity": 1,
                "price": 420.02,
                "cm": 1
            },
            {
                "quantity": 2,
                "price": 421.02,
                "cum": 3
            }
        ],
		"last": 418.75, // last, BTC
        "low": 414.75,  // 24H low 
        "high": 420.75, // 24H high
		"slip": 0 // reserved, system purpose, usually 0
    }
}

3.5.getlasttrades

Retrieve the latest trades that have occured for a specific instrument.
URI: https://deribit.com/api/v1/public/getlasttrades
URI Path: /api/v1/public/getlasttrades
Parameters:
        instrument – string [optional], instrument name, example “BTC-19DEC14” .
        since – integer [optional], “since” trade id, the server returns trades newer than that “since”.
        count – integer [optional], count of trades returned (limitation: max. count is 100)
trade id.
Method: GET
Result is JSON object:
{
    "success": true, // true or false
    "message": "",   // empty or text message 
    "result": [      // list of trades 
        {
            "tradeId": 1,           // trade id
	    "instrument": "BTC-22JAN16",  // name of the instrument 
            "timeStamp": 1418148659276,   // timestamp in milliseconds, e.g., javascript Date object — new Date(1418148659276)
            "quantity": 2,                // quantity, in contracts ($10 per contract for futures, ฿1 — for options)
            "price": 418.02,              // float, USD for futures, BTC for options
            "direction": "sell",          // "buy", "sell"
            "matchingId": 3,              // id of matching order
            "indexPrice": 420.04
        }
    ]
}

3.6.getsummary

Retrieve the summary info such as Open Interest, 24H Volume etc for a specific instrument.
URI: https://deribit.com/api/v1/public/getsummary
URI Path: /api/v1/public/getsummary
Parameters: instrument – string [optional], instrument name, example “BTC-19DEC14”.
Method: GET
Result is JSON object:
{
“success”: true, // true or false
“message”: “”,
“result”: { // summary
“instrumentName”: “BTC-19DEC14”,
“openInterest”: 2.009614922,
“high”: 418.02,
“low”: 418.02,
“volume”: 4,
“last”: 418.02,
“bidPrice”: 416.02, // float, USD for futures, BTC for options
“askPrice”: 420.02, // float, USD for futures, BTC for options
“midPrice”: 418.02, // float, USD for futures, BTC for options
“created”: “2015-10-15 12:47:10 GMT” // GMT date time
}
}

4.Private API

4.1.account

Get user account summary. (Authorization is required)
URI: https://deribit.com/api/v1/private/account
URI Path: /api/v1/private/account
Parameters: none
Method: GET
Result is JSON object:
{
    "success": true,       // true or false
    "result": {
        "equity": 100.035027761,  // float, in BTC
        "maintenanceMargin": 0.160038249,  // float, in BTC
        "initialMargin": 13.126500563, // float, in BTC
        "availableFunds": 86.908527198, // float, in BTC
        "profitLoss": 0.018841995 // float, in BTC
    }
}

4.2.buy

Place a buy order in an instrument. (Authorization is required)
URI: https://deribit.com/api/v1/private/buy
URI Path: /api/v1/private/buy
Parameters: shown as JQuery data for POST
{
    "instrument": "BTC-19DEC14",   // name 
    "quantity": 1,                 // quantity, in contracts ($10 per contract for futures, ฿1 — for options)
    "price": "380.0"               // float, USD for futures, BTC for options     
}
Method: POST
Result is JSON object:
{
    "success": true, // true or false
    "result": {
        "order": {
            "orderId": 889, 	// id of created order if success = true
            "instrument": "BTC-22JAN16", 	//instrument name of the order
            "direction": "buy", 	// direction, buy
            "price": 417, 	// price, float, USD for futures, BTC for options
            "quantity": 1, 	// quantity, in contracts ($10 per contract for futures, ฿1 — for options)
            "filledQuantity": 0, 	//filled quantity, in contracts ($10 per contract for futures, ฿1 — for options)
            "commision": 0, 	// commision in btc
            "created": 1453398857489,
            "lastUpdate": 1453398857489,
            "state": "open"
        },
        "trades": []
    },
    "message": "" 	// empty or text message, e.g. error message
}

4.3.sell

Place a sell order in an instrument. (Authorization is required).
URI: https://deribit.com/api/v1/private/sell
URI Path: /api/v1/private/sell
Parameters: shown as JQuery data for POST
{
    "instrument": "BTC-29JAN16-450-C",  // name 
    "quantity": "1",					// quantity, in contracts ($10 per contract for futures, ฿1 — for options)
    "price": "0.2"					  // float, USD for futures, BTC for options
}
Method: POST
Result is JSON object:
{
    "success": true,
    "result": {
        "order": {
            "orderId": 894,   // id of created order if success = true
            "instrument": "BTC-29JAN16-450-C", //instrument name of the order
            "direction": "sell", // direction, sell
            "price": 0.2,    // price, float, USD for futures, BTC for options
            "quantity": 10,  // quantity, in contracts ($10 per contract for futures, ฿1 — for options)
            "filledQuantity": 1, //filled quantity, in contracts ($10 per contract for futures, ฿1 — for options)
            "commision": 0,  // commision in btc
            "created": 1453399515235,
            "lastUpdate": 1453399515235,
            "state": "open"
        },
        "trades": [ // list of immediate trades
            {
                "quantity": 1, // quantity, in contracts ($10 per contract for futures, ฿1 — for options)
                "price": 415   // price, float, USD for futures, BTC for options
            }
		]
    },
    "message": ""
}

4.4.edit

Edit price and/or quantity of the own order. (Authorization is required).
URI: https://deribit.com/api/v1/private/edit
URI Path: /api/v1/private/edit
Paramerts: shown as JQuery data for POST
{
    "orderId": "994",   // ID of the order returned by "sell" or "buy" request
    "quantity": "1",    // quantity, in contracts ($10 per contract for futures, ฿1 — for options)
    "price": "415"      // float, USD for futures, BTC for options
}
Method: POST
Result is JSON object:
{
    "success": true, // true or false
    "result": {
        "order": {
            "orderId": 994, 	// id of created order if success = true
            "instrument": "BTC-22JAN16", 	//instrument name of the order
            "direction": "buy", 	// direction, buy
            "price": 415, 	// price, float, USD for futures, BTC for options
            "quantity": 1, 	// quantity, in contracts ($10 per contract for futures, ฿1 — for options)
            "filledQuantity": 0, 	//filled quantity, in contracts ($10 per contract for futures, ฿1 — for options)
            "commision": 0, 	// commision in btc
            "created": 1453398857489,
            "lastUpdate": 1453398857489,
            "state": "open"
        },
        "trades": []
    },
    "message": "" 	// empty or text message, e.g. error message
}

4.5.cancel

Cancell own order by id. (Authorization is required).
URI: https://deribit.com/api/v1/private/cancel
URI Path: /api/v1/private/cancel
Parameters: shown as JQuery data for POST
{
    "orderId": "5"
}
Method: POST
Result is JSON object:
{
    "success": true,  // true or false
    "message": "",    // empty or text message, e.g. error message
    "result": null    
}

4.6.cancelall

Cancell all own futures, or all options, or all. (Authorization is required).
URI: https://deribit.com/api/v1/private/cancelall
URI Path: /api/v1/private/cancelall
Parameters: shown as JQuery data for POST
{
    "type": "all"  // "all", "futures", "options"
}
Method: POST
Result is JSON object:
{
    "success": true,  // true or false
    "message": "cancel all",    // text message, e.g. error message
}

4.7.getopenorders

Retrieve openorders. (Authorization is required).
URI: https://deribit.com/api/v1/private/getopenorders
URI Path: /api/v1/private/getopenorders
Parameters: instrument – string [optional], instrument name, example “BTC-19DEC14”.
Method: GET
Result is JSON object:
{
    "success": true,  // true or false
    "message": "",    // empty or text message, e.g. error message
    "result": [       // list of open orders
		{
            "orderId": 30,  // ID of the order
            "instrument": "BTC-22JAN16-270-C",
            "direction": "buy",
            "price": 0.5, // float, USD for futures, BTC for options
            "quantity": 1, // quantity, in contracts ($10 per contract for futures, ฿1 — for options)
            "filledQuantity": 0, // filled quantity, in contracts ($10 per contract for futures, ฿1 — for options)
            "commision": 0,
            "created": 1453397825239,
            "lastUpdate": 1453397825239,
            "state": "open"
        }
    ]
}

4.8.positions

Retreive positions. (Authorization is required).
URI: https://deribit.com/api/v1/private/positions
URI Path: /api/v1/private/positions
Parameters: none
Method: GET
Result is JSON object:
{
    "success": true,  // true or false
    "result": [ //list of position objects
        {   //example future position
            "instrument": "BTC-22JAN16", // name of the instrument
            "size": 1,  // position size, in contracts ($10 per contract for futures, ฿1 — for options)
            "averagePrice": 384.289999987, // average price for the position in BTC
            "direction": "buy", 
	        "sizeBtc": 0.025844001, // position size in BTC for futures
            "floatingPl": 0.000178014,
            "realizedPl": -0.00060691,
            "markPrice": 386.937,  // mark price
            "indexPrice": 379.35,  // index price
            "maintenanceMargin": 0.00245518,  // maintenance margin in BTC
            "initialMargin": 0.00439348,      // initial margin in BTC
            "openOrderMargin": 0.184398603
        },
        {   //example option position 
            "instrument": "BTC-22JAN16-360-C",
            "size": -0.2,
            "averagePrice": 0.2, // average price for the position in BTC
            "averageUsdPrice": 78.62, // average price in USD for options
            "direction": "sell",
            "quantity": -1,
            "floatingPl": 0.144582976,
            "floatingUsdPl": 57.597551946,
            "realizedPl": 0,
            "markPrice": 0.05541702431231484,
            "indexPrice": 379.35,
            "maintenanceMargin": 0.1,
            "initialMargin": 0.2,
            "openOrderMargin": 0
        }, .....
    ]
}

4.9.orderhistory

Get history. (Authorization is required).
URI: https://deribit.com/api/v1/private/orderhistory
URI Path: /api/v1/private/orderhistory
Parameters: none
Method: GET
Result is JSON object:
{
    "success": true,
    "result": [ // list of orders from history, filled quantity > 0 
        {
            "orderId": 1000,   // ID of the order
            "instrument": "BTC-22JAN16-360-C", // name of the instrument
            "direction": "sell", // direction of the order
            "price": 0.5,  // float, USD for futures, BTC for options
            "quantity": 1,  // quantity, in contracts ($10 per contract for futures, ฿1 — for options)
            "filledQuantity": 1, // filled quantity, in contracts ($10 per contract for futures, ฿1 — for options)
            "state": "filled",   // state of the order
            "created": 1453411118214,
            "tstamp": 1453411118214,
            "commission": 0.0005,
            "modified": 1453411118215
        } ....
    ]
}

5.Websockets API

WebSocket API include all REST API and in addition subscriptions for notifications.
WebSocket address is wss://deribit.com/ws/api/v1/
and test WebSocket server address is wss://test.deribit.com/ws/api/v1/
Please click here for (Websockets and REST) API Console.
Each WebSocket request has the following structure (private WS API request uses ’sig’ property as a replacement of ’x-deribit-sig’ header for the REST API):
{
    "id": 201,     // id, developer identifies the response by the request id (the response has the same id with the corresponding request)
    "action": URI Path, // request URI Path
    "arguments": {key: value}, // same arguments as for the REST API
    "sig": signature // request signature if it is necessary (private API), same as for the REST API
}
WebSocket response is a websocket message, example of handling:
// ws is the JavaScript WebSocket object
ws.onmessage = function (e) {
                if (e.data.length > 0) {
                    // get JSON object of the API response
                    var obj = JSON.parse(e.data);
					// use obj
                    ...
                }
            };
List of WebSocket API corresponding to the REST API and they URI:
  • getinstruments – action, URI Path /api/v1/public/getinstruments
  • getcurrencies – action, URI Path /api/v1/public/getcurrencies
  • getorderbook – action, URI Path /api/v1/public/getorderbook
  • getlasttrades – action, URI Path /api/v1/public/getlasttrades
  • getsummary – action, URI Path /api/v1/public/getsummary
  • account – action, URI Path /api/v1/private/account
  • buy – action, URI Path /api/v1/private/buy
  • sell – action, URI Path /api/v1/private/sell
  • edit – action, URI Path /api/v1/private/edit
  • cancel – action, URI Path /api/v1/private/cancel
  • cancelall – action, URI Path /api/v1/private/cancelall
  • getopenorders – action, URI Path /api/v1/private/getopenorders
  • positions- action, URI Path /api/v1/private/positions
  • orderhistory – action, URI Path /api/v1/private/orderhistory

5.1.subscribe

WebSocket API to subscribe to notifications.

action, URI Path: /api/v1/private/subscribe
Parameters:
{
    "id": 5533, // id, developer identifies the response by the sent id
    "action": "/api/v1/private/subscribe",  
    "arguments": {
        "instrument": ["BTC-19DEC14"], // instrument filter if applicable, i.e., list of instrument names,
                                       // see getinstruments REST API
	                                   // also filters ["all"], ["futures"], ["options"] are allowed
                                       // ["all"] = no filter, all uinstruments
									   // ["futures"] = notification for futures	
                                       // ["options"] = notification for options
       "event": ["order_book", "trade", "user_order"] // events to be reported, possible events:
                                                      // "order_book" -- order book change 
                                                      // "trade" — trade notification, trade notification is not filtered 
                                                      // "user_order" -- change of user orders (openning, cancelling, filling)
    },     
   "sig": "...." // required !
}
Response message is JSON object:
{
    "id": 5533,       // equal to the request id
    "success": true,  // true or false 
    "message": "subscribed", // subscribed or not
    "result": null
}
WebSocket notification message:
{
 "notifications": [ 
			// list of notifications (notification objects)
		.....
 	  ]
}
Following notification objects are possible:
trade_event
with list of the trades. JSON object:
{
     "success": true,  // false of true
      "message": "trade_event", // event type
      "result": [ // list of trades (for trade event)
            {
             "tradeId": 3,                    // trade id
             "timeStamp": 1418152290669, // Unix timestamp 
			 "instrument": "BTC-22JAN16", // name of instrument
             "quantity": 61,          // quantity, in contracts ($10 per contract for futures, ฿1 — for options)   
             "price": 415,       // float, USD for futures, BTC for options
             "state": "closed",     // order state
             "direction": "buy",   
             "orderId": 10,         // order id
             "matchingId": 6,       // id of matching order
             "makerComm": 0.0001,   
             "takerComm": 0.0005,
             "indexPrice": 420.69   // index price
           }
        ]
     }
order_book_event
It notifies about a change of order book for certain instrument. JSON object:
{
            "success": true,
            "message": "order_book_event",
            "result": {
                "instrument": "BTC-9OCT15",
                "bids": [
                    {
                        "quantity": 10, // quantity, in contracts ($10 per contract for futures, ฿1 — for options)
                        "price": 418.19, // float, USD for futures, BTC for options
                        "cm": 10  // cumulative quantity, in contracts ($10 per contract for futures, ฿1 — for options)
                    }
                    ...// next best bids
                ],
                "asks": [
                    {
                        "quantity": 10,
                        "price": 422.21,
                        "cm": 20
                    }
                    ...// next best asks  
                ],
                "last": 418.19,
                "low": 415.18,
                "high": 420.26
            }
        }
user_order_event
It notifies about a change of user’s orders. This event is triggered for all changes of the user orders, it doesn’t depend on “instrument” parameter at subscription. JSON object:
{   "success": true,
    "message": "user_orders_event",
    "result": [
                {
                    "id": 1031,                   // order identifier
                    "instrument": "BTC-22JAN16",  // instrument name
                    "direction": "sell",          // direction of the order "buy" or "sell"
                    "price": 426,                 // price
                    "quantity": 10,               // quantity, in contracts ($10 per contract for futures, ฿1 — for options)
                    "filledQuantity": 0,          // filled quantity, in contracts ($10 per contract for futures, ฿1 — for options)
                    "state": "open",              // order state "open", "cancelled", "filled"
                    "created": 1453454229858,     // creation Unix timestamp
                    "modified": 1453454229858     // Unix timestamp of the last change
                }
              ]
}
              

unsubscribe

Unsubscribe from all notifications without closing the websocket connection. Currently there is no selectors.
action, URI Path: /api/v1/private/unsubscribe
Paramerts: none
{
    "id": 1798, // id, developer identifies the response by the sent id
    "action": "/api/v1/private/unsubscribe",
    "sig": "...."  // required
}
Response message is JSON object:
{
    "id": 1798,      // equal to the request id
    "success": true,
    "message": "unsubscribed",
    "result": null
}

6.FIX API

Deribit FIX API is a subset of FIX version 4.4. Deribit uses the standard header and trailer structure for all messages. To enable the API, sign in and go to Account -> Security -> API Tab and use the checkbox. Write down your ’Access Key’ and ’Access Secret. ’Access Secret’ is the user’s secret key provided by Deribit. Important Note: Do not reveal to anybody your ’Access Secret’, it is important as your password.

FIX SERVER ADDRESS

Socket host = deribit.com, socket port = 9880
Socket host = test.deribit.com, socket port = 9881 

Message Header

Each request message includes
Tag Name Required Comments
49 SenderCompID Yes SenderCompID user defined client name
 56 TargetCompID Yes TargetCompID constant value: DERIBITSERVER

LOGON(A)

LOGON(A) is the first message sent by the client to initiate a session. If authentication succeeds, the exchange should echo the message back to the client. If authentication fails, the exchange should send a LOGOUT(5) message with an appropriate reason.

Request Parameters

Tag Name Required Comments
108 HeartBtInt Yes Used to declare the timeout interval in seconds for generating heartbeats(same value used by both sides).
96 RawData Yes A Nonce, which is base64 encoded data of 32 random bytes, example “3pM14pgJOYBATBDaCmE+0YvdPExppg5bJXAZtxakwDQ=”
553 Username Yes API authenticated ’Access Key’
554 Password Yes base64 encoded data of SHA256 hash of concatenation the Nonce and ’Access Secret’ string, SHA256(Nonce ++ AccessSecret)

LOGOUT(5)

LOGOUT(5) can be sent by either party in order to terminate a session. The sending party should always wait for the echo of the logout request before they close the socket. Closing connections in any other way is considered abnormal behavior.

Request Parameters

Tag Name Required Comments
58 text No Free format text string specifying the logout reason.

HEARTBEAT(0)

When either end of a FIX connection has not sent or received any data for [HeartBtInt] seconds (as specified in the Logon (A) message), it will transmit a Heartbeat (0) message. When either end of a FIX connection has not received any data for [HeartBtInt] seconds, it will transmit a Test Request Message (1). If there is still no response, the session should be considered lost and corrective action should be initiated.

Request Parameters

Tag Name Required Comments
112 TestReqId No Required when the heartbeat is the result of a TestRequest (1) message

TEST REQUEST(1)

The Test Request (1) message forces a heartbeat from the opposing application. The opposing application responds with a Heartbeat (0) containing the original TestReqID.

Request Parameters

Tag Name Required Comments
112 TestReqId Yes Mirrors the original request ID.

RESEND REQUEST(2)

The Resend Request(2) message is used by the server to initiate the retransmission of messages. This function is utilized if a sequence number gap is detected, if the receiving application lost a message, or as a function of the initialization process.

Request Parameters

Tag Name Required Comments
7 BeginSeqNo Yes
16 EndSeqNo Yes

REJECT(3)

The Reject (3) message should be issued when a message is received but cannot be properly processed due to a session-level or data structure rule violation. An example of when a reject may be appropriate would be the receipt of a message with invalid basic data (e.g. missing tags) which successfully passes decryption.

Request Parameters

Tag Name Required Comments
45 RefSeqNum Yes MsgSeqNum of the rejected message
372 RefMsgType No The MsgType<35> of the FIX message being referenced
373 SessionRejectReason No Code to identity reason for rejection.
58 Text No Text string explaining the reason for rejection

MARKET DATA REQUEST(V)

Market Data Request (V) is used by the trading platform to request market data in the snapshot or the incremental form. Deribit uses his message for order book requests and its change notification.

Request Parameters

Tag Name Required Comments
55 Symbol Yes Instrument symbol
262 MdReqId Yes Unique ID assigned to this request.
263 SubscriptionRequestType Yes 0 = Snapshot, 1 = Snapshot + Subscribe, 2 = Unsubscribe
264 MarketDepth No Default 20
100007 DeribitTradeAmount No Amount of trades returned in the snapshot response to request for snapshot of recent trades, default – 20, maximum – 100000
100008 DeribitSinceTimestamp No UTC Timestamp in milliseconds (integer number of milliseconds), if specified, the response returns the trades happened since that DeribitSinceTimestamp, applicable to the request for recent trades snapshot
Group MDEntryTypes
267 NoMdEntryTypes No Number of entry types in the request.
=>269 MDEntryType Yes 0 = Bid (Bid side of the order book), 1 = Offer (Ask side of the order book), 2 = Trade (Info about recent trades)

MARKET DATA REQUEST REJECT(Y)

If a Market Data Request (V) message is not accepted, the exchange responds with a Market Data Request Reject (Y) message

Request Parameters

Tag Name Required Comments
58 Text No Free format text string
262 MDReqID Yes ID of the original request
281 MDReqRejReason Yes

MARKET DATA SNAPSHOT/FULL REFRESH (W)

Market Data Snapshot/Full Refresh (W) is used as the response to a Market Data Request (V) message.

Request Parameters

Tag Name Required Comments
55 Symbol Yes Instrument symbol
262 MDReqID No ID of the original request, if it is applicable
268 < NoMDEntries > Yes Repeating group . Specifies the number of entries in the group.
=>270 MDEntryPx No Price of an entry
=>271 MDEntrySize No Size of an entry
=>269 MDEntryType No 0 = Bid (Bid side of the order book), 1 = Offer (Ask side of the order book), 2 = Trade (in case of request for info about recent trades)
=>272 MDEntryDate No UTCTimestamp string (up to ms), e.g., timestamp for trade
=>100009 DeribitTradeId No Id of the trade, in case of the request for trades
=>54 Side No Side of trade (1 = Buy, 2 = Sell)
=>37 OrderId No For trade – order id
=>198 SecondaryOrderId No For trade – matching order id
=>39 OrdStatus No For trade – order status (0 = New, 1 = Partially filled, 2 = Filled, 4 = Canceled)
=>100010 DeribitLabel No User defined 4-char label of the order, in case of the request for trades

MARKET DATA INCREMENTAL REFRESH (X)

Market Data – Incremental Refresh (X) message is used for incremental updates in case of Market Data Request (V) for Snapshot + Subscribe

Request Parameters

Tag Name Required Comments
55 Symbol Yes Instrument symbol
262 MDReqID No ID of the original “subscribe” request
268 NoMDEntries Yes Number of entries following
=>279 MDUpdateAction Yes 0 = New, 1 = Change, 2 = Delete
=>269 MDEntryType No 0 = Bid (Bid side of the order book), 1 = Offer (Ask side of the order book), 2 = Trade (in case of request for info about recent trades)
=>270 MDEntryPx No Price of an entry
=>271 MDEntrySize No Size of an entry
=>272 MDEntryDate No UTCTimestamp string (up to ms), e.g., timestamp for trade
=>100009 DeribitTradeId No Id of the trade, in case of the request for trades
=>54 Side No Side of trade (1 = Buy, 2 = Sell)
=>37 OrderId No For trade – order id
=>198 SecondaryOrderId No For trade – matching order id
=>39 OrdStatus No For trade – order status (0 = New, 1 = Partially filled, 2 = Filled, 4 = Canceled)
=>100010 DeribitLabel No User defined 4-char label of the order, in case of the request for trades

NEW ORDER SINGLE(D)

The NEW ORDER SINGLE (D) is used by the client to submit new orders to the exchange. Note Deribit doesn’t store client identifiers (for the sake of speed of execution), i.e., client software should manage matching client-server identifiers using

Request Parameters

Tag Name Required Comments
11 ClOrdID Yes Unique identifier for the order as assigned by the client
54 Side Yes 1 = Buy, 2 = Sell
38 OrderQty Yes Order quantity
44 Price Yes Price
55 Symbol Yes Instrument symbol, e.g., “BTC-1JAN16”

EXECUTION REPORT(8)

Upon receiving a new order, the exchange responds with the Execution Report (8) message communicating whether the order was accepted or rejected.

Request Parameters

Tag Name Required Comments
11 ClOrdID Yes Deribit replaces this field with the own value assigned by the server (it is not the client id from New Order Single)
41 OrigClOrdId Yes The original value assigned by the client in the New Order Single (D) message
39 OrdStatus Yes 0 = New, 8 = Rejected
54 Side Yes 1 = Buy, 2 = Sell
60 TransactTime Yes Time the transaction represented by this Execution Report occurred. Fix timestamp.
151 LeavesQty Yes Order quantity open for further execution (LeavesQty = OrderQty – CumQty )
14 CumQty Yes Total executed quantity or 0.0
38 OrderQty Yes Order quantity
40 OrdType Yes 2 = Limit, Limit orders only
44 Price Yes Price
103 OrdRejReason Yes
58 Text No Free format text string, usually exceptions
207 SecurityExchange No “Deribit”
55 Symbol Yes Instrument symbol
6 AvgPx No Average execution price or 0.0 if not executed yet or rejected

ORDER CANCEL REQUEST(F)

ORDER CANCEL REQUEST (F) message requests the cancellation of a particular order. If an order has been partially filled, only the remaining quantity can be cancelled. The request should be accepted only if an order can successfully be cancelled without executing further. The server generated identifiers should be used as OrigClOrdId-s, Deribit doesn’t store client identifiers.

Request Parameters

Tag Name Required Comments
11 ClOrdID Yes Order identifier
41 OrigClOrdId Yes Order identifier assigned by Deribit

ORDER CANCEL REJECT(9)

ORDER CANCEL REJECT (9) is issued by the exchange upon receipt of Order Cancel Request (F) message which cannot be executed.

Request Parameters

Tag Name Required Comments
52 SendingTime Yes
11 ClOrdID Yes Order identifier
41 OrigClOrdId Yes Order identifier assigned by Deribit
39 OrdStatus No If it is applicable
58 Text No Text string explaining the reason for rejection

EXECUTION REPORT(8)

The following Execution Report (8) is sent by the exchange upon successfully processing a cancel request.

Request Parameters

Tag Name Required Comments
52 SendingTime Yes
11 ClOrdID Yes Deribit replaces this field with the own value assigned by the server (it is not the client id from New Order Single)
41 OrigClOrdId Yes The original value assigned by the client in the New Order Single (D) message
39 OrdStatus Yes 0 = New, 1 = Partial, 4 = Canceled, 8 = Rejected
58 Text Yes Text string describing the result

ORDER MASS STATUS REQUEST(AF)

Order Mass Status Request (AF) message requests the status of currently open orders. The exchange should respond with a series of Execution Report (8) messages detailing orders.

Request Parameters

Tag Name Required Comments
584 MassStatusReqID Yes Client-assigned unique ID of this request or OrderId if MassStatusReqType = 1
585 MassStatusReqType Yes Specifies the scope of the mass status request. 1 = status of a specified order(Tag584 is OrderId), 7 = Status for all orders

EXECUTION REPORT(8)

When the client requests the status of current orders, the exchange should reply with a series of special Execution Reports (8), one for every active order.

Request Parameters

Tag Name Required Comments
11 ClOrdID Yes Deribit replaces this field with the own value assigned by the server (it is not the client id from New Order Single)
41 OrigClOrdId Yes For Order Mass Status Request(AF), OrigClOrdId is equal to the ClOrdID, i.e., order identifier assigned by Deribit
39 OrdStatus Yes 0 = New, 1 = Partial, 2 = Filled, 3 = Done, 4 = Canceled, 8 = Rejected
54 Side Yes 1 = Buy, 2 = Sell
60 TransactTime Yes Time the transaction represented by this Execution Report occurred. Fix timestamp.
38 OrderQty Yes Order quantity
40 OrdType Yes 2 = Limit, Limit orders only
44 Price Yes Price
103 OrdRejReason Yes
58 Text No Free format text string, usually exceptions
207 SecurityExchange No “Deribit”
55 Symbol Yes Instrument symbol
6 AvgPx No Average execution price, filled.

REQUEST FOR POSITIONS (AN)

Request For Positions (AN) is used by the owner of a position to request a Position Report.

Request Parameters

Tag Name Required Comments
710 PosReqID Yes Unique identifier for the Request for Positions (AN) as assigned by the submitter.
724 PosReqType Yes 0 = Positions (currently)

POSITION REPORT (AP)

The Position Report (AP) message is returned by the holder of a position in response to a Request for Position (AN) message.

Request Parameters

Tag Name Required Comments
721 PosMaintRptID Yes Unique identifier for this position report
710 PosReqID No Unique identifier for the Request for Positions associated with this report.
724 PosReqType No 0 = Positions (currently)
728 PosReqResult No 0 = success, 1 = unsupported request for positions
702 NoPositions No \strikeout off\uuline off\uwave offNumber of position entries following
=>704 LongQty No Qty for long position (0 for short position)
=>705 ShortQty No Qty for short position (0 for long position)
=>55 Symbol No Instrument symbol
=>883 UnderlyingEndPrice No Mark price (reference price)
=>54 Side No 1 = Buy, 2 = Sell
=>730 SettlPrice No Average price
=>96 RawData No Additional info, semi-colon separated: maintenance margin;initial margin;floating P/L

USER REQUEST (BE)

USER REQUEST used to request a report on a user’s status and user account info

Request Parameters

Tag Name Required Comments
923 UserRequestID Yes The request ID
924 UserRequestType Yes Shoulr be equal to 4 (Request individual user status), only UserRequestType=4 supported for now
553 Username Yes API authenticated ’Access Key’, user can request only own info, should be the same as for previous LOGON(A)

USER RESPONSE (BF)

USER RESPONSE(BF) is used to respond to a USER REQUEST (BE) message, it reports the status of the user and user’s account info

Response Parameters

Tag Name Required Comments
923 UserRequestID Yes The request ID
553 Username Yes User’s API ’Access Key’
926 UserStatus N 1 = logged in, current implementation accepts USER REQUEST-s only from logged in users
100001 DeribitUserEquity N Equity of the user
100002 DeribitUserBalance N Balance of the user
100003 DeribitUserInitialMargin N Initial margin of the user
100004 DeribitUserMaintenanceMargin N Maintenance margin of the user
100005 DeribitUnrealizedPl N Unrealized P/L of the user
100006 DeribitRealizedPl N Realized P/L of the user
Suggest Edit