Deribit API v2.0.1

Overview

Deribit provides three different interfaces to access the API:

JSON-RPC over Websocket
JSON-RPC over HTTP
FIX (Financial Information eXchange)

Deribit features testing environment, test.deribit.com, which can be used to test the API. For this reason all examples in this documentation refer to that environment. To reach production environment it should be changed to www.deribit.com. Note that both environments are separate, which means that they require separate accounts and credentials (API keys) to authenticate using private methods - test credentials do not work in production enviromnent and vice versa.

To see the list of your API keys check Account > API tab, where you'll also find a link to API Console (>_ Api Console) which allows you to test JSON-RPC API, both via HTTP and Websocket.

Error Codes (HTTP and Websocket RPC Error codes)

Naming

Deribit tradeable assets or instruments use the following system of naming:

Kind	Examples	Template	Comments
Future	`BTC-25MAR16`, `BTC-5AUG16`	`BTC-DMMMYY`	`BTC` is currency, `DMMMYY` is expiration date, `D` stands for day of month (1 or 2 digits), `MMM` - month (3 first letters in English), `YY` stands for year.
Perpetual	`BTC-PERPETUAL`		Perpetual contract for currency `BTC`.
Option	`BTC-25MAR16-420-C`, `BTC-5AUG16-580-P`	`BTC-DMMMYY-STRIKE-K`	`STRIKE` is option strike price in USD. Template `K` is option kind: `C` for call options or `P` for put options.

Rate Limits

Rate limits are described on separate document.

JSON-RPC

JSON-RPC is a light-weight remote procedure call (RPC) protocol. The JSON-RPC specification defines the data structures that are used for the messages that are exchanged between client and server, as well as the rules around their processing. JSON-RPC uses JSON (RFC 4627) as data format.

JSON-RPC is transport agnostic: it does not specify which transport mechanism must be used. The Deribit API supports both Websocket (preferred) and HTTP (with limitations: subscriptions are not supported over HTTP).

Request messages

An example of a request message:

{
    "jsonrpc": "2.0",
    "id": 8066,
    "method": "public/ticker",
    "params": {
        "instrument": "BTC-24AUG18-6500-P"
    }
}

According to the JSON-RPC sepcification the requests must be JSON objects with the following fields.

Name	Type	Description
jsonrpc	string	The version of the JSON-RPC spec: "2.0"
id	integer or string	An identifier of the request. If it is included, then the response will contain the same identifier
method	string	The method to be invoked
params	object	The parameters values for the method. The field names must match with the expected parameter names. The parameters that are expected are described in the documentation for the methods, below.

Response messages

An example of a response message:

{
    "jsonrpc": "2.0",
    "id": 5239,
    "testnet": false,
    "result": [
        {
            "coin_type": "BITCOIN",
            "currency": "BTC",
            "currency_long": "Bitcoin",
            "fee_precision": 4,
            "min_confirmations": 1,
            "min_withdrawal_fee": 0.0001,
            "withdrawal_fee": 0.0001,
            "withdrawal_priorities": [
                {
                    "value": 0.15,
                    "name": "very_low"
                },
                {
                    "value": 1.5,
                    "name": "very_high"
                }
            ]
        }
    ],
    "usIn": 1535043730126248,
    "usOut": 1535043730126250,
    "usDiff": 2
}

The JSON-RPC API always responds with a JSON object with the following fields.

Name	Type	Description
id	integer	This is the same id that was sent in the request.
result	any	If successful, the result of the API call. The format for the result is described with each method.
error	error object	Only present if there was an error invoking the method. The error object is described below.
testnet	boolean	Indicates whether the API in use is actually the test API. `false` for production server, `true` for test server.
usIn	integer	The timestamp when the requests was received (microseconds since the Unix epoch)
usOut	integer	The timestamp when the response was sent (microseconds since the Unix epoch)
usDiff	integer	The number of microseconds that was spent handling the request

The fields testnet, usIn, usOut and usDiff are not part of the JSON-RPC standard.

In order not to clutter the examples they will generally be omitted from the example code.

An example of a response with an error:

{
    "jsonrpc": "2.0",
    "id": 8163,
    "error": {
        "code": 11050,
        "message": "bad_request"
    },
    "testnet": false,
    "usIn": 1535037392434763,
    "usOut": 1535037392448119,
    "usDiff": 13356
}

In case of an error the response message will contain the error field, with as value an object with the following with the following fields:

Name	Type	Description
code	integer	A number that indicates the kind of error.
message	string	A short description that indicates the kind of error.
data	any	Additional data about the error. This field may be omitted.

Notifications

An example of a notification:

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "channel": "deribit_price_index.btc_usd",
        "data": {
            "timestamp": 1535098298227,
            "price": 6521.17,
            "index_name": "btc_usd"
        }
    }
}

API users can subscribe to certain types of notifications. This means that they will receive JSON-RPC notification-messages from the server when certain events occur, such as changes to the index price or changes to the order book for a certain instrument.

The API methods public/subscribe and private/subscribe are used to set up a subscription. Since HTTP does not support the sending of messages from server to client, these methods are only availble when using the Websocket transport mechanism.

At the moment of subscription a "channel" must be specified. The channel determines the type of events that will be received. See Subscriptions for more details about the channels.

In accordance with the JSON-RPC specification, the format of a notification is that of a request message without an id field. The value of the method field will always be "subscription". The params field will always be an object with 2 members: channel and data. The value of the channel member is the name of the channel (a string). The value of the data member is an object that contains data that is specific for the channel.

Authentication

An example of a JSON request with token:

{
    "id": 5647,
    "method": "private/get_subaccounts",
    "params": {
        "access_token": "1582628593469.1MbQ-J_4.CBP-OqOwm_FBdMYj4cRK2dMXyHPfBtXGpzLxhWg31nHu3H_Q60FpE5_vqUBEQGSiMrIGzw3nC37NMb9d1tpBNqBOM_Ql9pXOmgtV9Yj3Pq1c6BqC6dU6eTxHMFO67x8GpJxqw_QcKP5IepwGBD-gfKSHfAv9AEnLJkNu3JkMJBdLToY1lrBnuedF3dU_uARm"
    }
}

The API consists of public and private methods. The public methods do not require authentication. The private methods use OAuth 2.0 authentication. This means that a valid OAuth access token must be included in the request, which can be achived by calling method public/auth.

When the token was assigned to the user, it should be passed along, with other request parameters, back to the server:

Connection type	Access token placement
Websocket	Inside request JSON parameters, as an `access_token` field
HTTP (REST)	Header `Authorization: bearerToken` value

Additional authorization method - basic user credentials

Every private method could be accessed by providing, inside HTTP Authorization: Basic XXX header, values with user ClientId and assigned ClientSecret (both values can be found on the API page on the Deribit website) encoded with Base64:

Authorization: Basic BASE64(ClientId + : + ClientSecret)

Additional authorization method - Deribit signature credentials

The Derbit service provides dedicated authorization method, which harness user generated signature to increase security level for passing request data. Generated value is passed inside Authorization header, coded as:

Authorization: deri-hmac-sha256 id=ClientId,ts=Timestamp,sig=Signature,nonce=Nonce

where:

Deribit credential	Description
ClientId	Can be found on the API page on the Deribit website (the user can configure up to 8 different `IDs` - with different privileges)
Timestamp	Time when the request was generated - given as miliseconds. It's valid for 60 seconds since generation, after that time any request with an old timestamp will be rejected.
Signature	Value for signature calculated as described below
Nonce	Single usage, user generated initialization vector for the server token

The signature is generated by the following formula:

RequestData = UPPERCASE(HTTP_METHOD()) + "\n" + URI() + "\n" + RequestBody + "\n";
StringToSign = Timestamp + "\n" + Nonce + "\n" + RequestData;
Signature = HEX_STRING( HMAC-SHA256( ClientSecret, StringToSign ) );

Note the newline characters in RequestData and StringToSign variables. If RequestBody is ommitted in RequestData, it's treated as an empty string, so these three newline characters must always be present.

Example using shell with openssl tool:

    ClientId=AMANDA
    ClientSecret=AMANDASECRECT
    Timestamp=$( date +%s000 )
    Nonce=$( cat /dev/urandom | tr -dc 'a-z0-9' | head -c8 )
    URI="/api/v2/private/get_account_summary?currency=BTC"
    HttpMethod=GET
    Body=""

    Signature=$( echo -ne "${Timestamp}\n${Nonce}\n${HttpMethod}\n${URI}\n${Body}\n" | openssl sha256 -r -hmac "$ClientSecret" | cut -f1 -d' ' )

    echo $Signature

    shell output> 9bfbc51a2bc372d72cc396cf1a213dc78d42eb74cb7dc272351833ad0de276ab (WARNING: Exact value depends on current timestamp and client credentials)

    curl -s -X ${HttpMethod} -H "Authorization: deri-hmac-sha256 id=${ClientId},ts=${Timestamp},nonce=${Nonce},sig=${Signature}" "https://www.deribit.com${URI}"

Additional authorization method - signature credentials (WebSocket API)

Example of authorization using client_signature:

# see javascript or python example

// using CryptoJS library
var clientId = "AMANDA";
var clientSecret = "AMANDASECRECT";
var timestamp = Date.now();
var nonce = "abcd";
var data = "";
var signature = CryptoJS.HmacSHA256(`${timestamp}\n${nonce}\n${data}`, accessSecret).toString();

var msg = {
    "jsonrpc" : "2.0",
    "id" : 4316,
    "method" : "public/auth",
    "params" : {
        "grant_type": "client_signature",
        "client_id": clientId,
        "timestamp": timestamp,
        "signature": signature,
        "nonce": nonce,
        "data": data
    }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json
import hmac
import hashlib
from datetime import datetime

clientId = "AMANDA"
clientSecret = "AMANDASECRECT"
timestamp = round(datetime.now().timestamp() * 1000)
nonce = "abcd"
data = ""
signature = hmac.new(
    bytes(clientSecret, "latin-1"),
    msg=bytes('{}\n{}\n{}'.format(timestamp, nonce, data), "latin-1"),
    digestmod=hashlib.sha256
).hexdigest().lower()

msg = {
    "jsonrpc": "2.0",
    "id": 8748,
    "method": "public/auth",
    "params": {
        "grant_type": "client_signature",
        "client_id": clientId,
        "timestamp": timestamp,
        "signature": signature,
        "nonce": nonce,
        "data": data
    }
}

print(msg)

async def call_api(msg):
    async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
        await websocket.send(msg)
        while websocket.open:
            response = await websocket.recv()
            print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

When connecting through Websocket, user can request for authorization using client_signature method, which requires providing following parameters (as a part of JSON request):

JSON parameter	Description
grant_type	Must be client_signature
client_id	Can be found on the API page on the Deribit website (the user can configure up to 8 different `IDs` - with different privileges)
timestamp	Time when the request was generated - given as miliseconds. It's valid for 60 seconds since generation, after that time any request with an old timestamp will be rejected.
signature	Value for signature calculated as described below
nonce	Single usage, user generated initialization vector for the server token
data	Optional field, which contains any user specific value

The signature is generated by the following formula:

StringToSign = Timestamp + "\n" + Nonce + "\n" + Data;
Signature = HEX_STRING( HMAC-SHA256( ClientSecret, StringToSign ) );

Note the newline characters separating parts of the StringToSign variable. If Data is ommitted, it's treated as an empty string, so these two newline characters must always be present.

Example using shell with openssl tool:

    ClientId=AMANDA
    ClientSecret=AMANDASECRECT
    Timestamp=$( date +%s000 ) # e.g. 1576074319000
    Nonce=$( cat /dev/urandom | tr -dc 'a-z0-9' | head -c8 ) # e.g. 1iqt2wls
    Data=""

    Signature=$( echo -ne "${Timestamp}\n${Nonce}\n${Data}" | openssl sha256 -r -hmac "$ClientSecret" | cut -f1 -d' ' )

    echo $Signature

    shell output> 56590594f97921b09b18f166befe0d1319b198bbcdad7ca73382de2f88fe9aa1 (WARNING: Exact value depends on current timestamp and client credentials)

You can also check the signature value using some online tools like, e.g: https://codebeautify.org/hmac-generator (remember that you should use it only with your test credentials).

Here's a sample JSON request created using the values from the example above:

{ "jsonrpc" : "2.0", "id" : 9929, "method" : "public/auth", "params" : { "grant_type" : "client_signature", "client_id" : "AMANDA", "timestamp": "1576074319000", "nonce": "1iqt2wls", "data": "", "signature" : "56590594f97921b09b18f166befe0d1319b198bbcdad7ca73382de2f88fe9aa1" } }

Access scope

When asking for access token user can provide the required access level (called scope) which defines what type of functionality he/she wants to use, and whether requests are only going to check for some data or also to update them. Scopes are required and checked for private methods, so if you plan to use only public information you can stay with values assigned by default.

Scope	Description
mainaccount	It is set automatically by the server when currently connecting user (his/her credentials) is the main user, otherwise it's not included in the final scope.
connection	Access with requested parameters is granted when connection is open (or till expiration time). When the connection is closed user need to repeat the authentication request to get new tokens. It is set and used automatically by the server when neither connection nor session scope is provided within the request.
session:name	The server creates a new session with name provided by the user, then generates tokens and binds them with the session. Access is granted during session lifetime. It allows to reconnect to the server and reuse assigned tokens (before their expiration time). Note that only 16 sessions are allowed per user - when limit is reached session with the shortest lifetime is removed. When using WebSocket it also allows (due to the fact that tokens are bound to the created session) skipping providing `access_token` with every subsequent request.
account:read	Access to account methods - read only data.
account:read_write	Access to account methods - allows to manage account settings, add subaccounts, etc.
trade:read	Access to trade methods - read only data.
trade:read_write	Access to trade methods - required to create and modify orders.
wallet:read	Access to wallet methods - read only data.
wallet:read_write	Access to wallet methods - allows to withdraw, generate new deposit address, etc.
wallet:none, account:none, trade:none	Blocked access to specified functionality.
expires:NUMBER	Access token will expire after `NUMBER` of seconds.
ip:ADDR	Token will work with connection from `ADDR` IPv4 address, when `*` is provided as `ADDR` token will work from all IP addresses.
block_trade:read	Access to block_trade methods - reading info about block trades - read only data.
block_trade:read_write	Access to block_trade methods - required to create block trades.

NOTICE: Depending on choosing an authentication method (grant type) some scopes could be narrowed by the server or limited by user API key configured scope, e.g. when grant_type = client_credentials and scope = wallet:read_write could be modified by the server as scope = wallet:read.

The user shouldn't assume that requested values are blindly accepted and should verify assigned scoped.

JSON-RPC over websocket

Websocket is the prefered transport mechanism for the JSON-RPC API, because it is faster and because it can support subscriptions and cancel on disconnect. The code examples that can be found next to each of the methods show how websockets can be used from Python or Javascript/node.js.

JSON-RPC over HTTP

Besides websockets it is also possible to use the API via HTTP. The code examples for 'shell' show how this can be done using curl. Note that subscriptions and cancel on disconnect are not supported via HTTP.

Methods

Authentication

/public/auth

curl -X GET "https://test.deribit.com/api/v2/public/auth?client_id=fo7WAPRm4P&client_secret=W0H6FJW4IRPZ1MOQ8FP6KMC5RZDUUKXS&grant_type=client_credentials" \
-H "Content-Type: application/json"

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9929,
  "method" : "public/auth",
  "params" : {
    "grant_type" : "client_credentials",
    "client_id" : "fo7WAPRm4P",
    "client_secret" : "W0H6FJW4IRPZ1MOQ8FP6KMC5RZDUUKXS"
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9929,
  "method" : "public/auth",
  "params" : {
    "grant_type" : "client_credentials",
    "client_id" : "fo7WAPRm4P",
    "client_secret" : "W0H6FJW4IRPZ1MOQ8FP6KMC5RZDUUKXS"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 9929,
  "result": {
      "access_token": "1582628593469.1MbQ-J_4.CBP-OqOwm_FBdMYj4cRK2dMXyHPfBtXGpzLxhWg31nHu3H_Q60FpE5_vqUBEQGSiMrIGzw3nC37NMb9d1tpBNqBOM_Ql9pXOmgtV9Yj3Pq1c6BqC6dU6eTxHMFO67x8GpJxqw_QcKP5IepwGBD-gfKSHfAv9AEnLJkNu3JkMJBdLToY1lrBnuedF3dU_uARm",
      "expires_in": 31536000,
      "refresh_token": "1582628593469.1GP4rQd0.A9Wa78o5kFRIUP49mScaD1CqHgiK50HOl2VA6kCtWa8BQZU5Dr03BhcbXPNvEh3I_MVixKZXnyoBeKJwLl8LXnfo180ckAiPj3zOclcUu4zkXuF3NNP3sTPcDf1B3C1CwMKkJ1NOcf1yPmRbsrd7hbgQ-hLa40tfx6Oa-85ymm_3Z65LZcnCeLrqlj_A9jM",
      "scope": "connection mainaccount",
      "token_type": "bearer"
  }
}

Retrieve an Oauth access token, to be used for authentication of 'private' requests.

Three methods of authentication are supported:

client_credentials - using the access key and access secret that can be found on the API page on the website
client_signature - using the access key that can be found on the API page on the website and user generated signature. The signature is calculated using some fields provided in the request, using formula described here Deribit signature credentials
refresh_token - using a refresh token that was received from an earlier invocation

The response will contain an access token, expiration period (number of seconds that the token is valid) and a refresh token that can be used to get a new set of tokens.

Parameter	Required	Type	Enum	Description
grant_type	true	string	`client_credentials` `client_signature` `refresh_token`	Method of authentication
client_id	true	string		Required for grant type `client_credentials` and `client_signature`
client_secret	true	string		Required for grant type `client_credentials`
refresh_token	true	string		Required for grant type `refresh_token`
timestamp	true	integer		Required for grant type `client_signature`, provides time when request has been generated
signature	true	string		Required for grant type `client_signature`; it's a cryptographic signature calculated over provided fields using user secret key. The signature should be calculated as an HMAC (Hash-based Message Authentication Code) with `SHA256` hash algorithm
nonce	false	string		Optional for grant type `client_signature`; delivers user generated initialization vector for the server token
data	false	string		Optional for grant type `client_signature`; contains any user specific value
state	false	string		Will be passed back in the response
scope	false	string		Describes type of the access for assigned token, possible values: `connection`, `session:name`, `trade:[read, read_write, none]`, `wallet:[read, read_write, none]`, `account:[read, read_write, none]`, `expires:NUMBER`, `ip:ADDR`. Details are elucidated in Access scope

Name	Type	Description
id	integer	The id that was sent in the request
jsonrpc	string	The JSON-RPC version (2.0)
result	object
› acccess_token	string
› expires_in	integer	Token lifetime in seconds
› refresh_token	string	Can be used to request a new token (with a new lifetime)
› scope	string	Type of the access for assigned token
› state	string	Copied from the input (if applicable)
› token_type	string	Authorization type, allowed value - `bearer`

Parameter	Required	Type	Enum	Description
client_name	true	string		Client software name
client_version	true	string		Client software version

Parameter	Required	Type	Enum	Description
start_timestamp	false	integer		Timestamp from which we want to retrieve announcements
count	false	integer		Maximum count of returned announcements

Parameter	Required	Type	Enum	Description
id	true	integer		Id of key
name	true	string		Name of key (only letters, numbers and underscores allowed; maximum length - 16 characters)

Parameter	Required	Type	Enum	Description
sid	true	integer		The user id for the subaccount
name	true	string		The new user name

Parameter	Required	Type	Description
max_scope	true	string
default	false	boolean	If `true`, new key is marked as default
name	false	string	Name of key (only letters, numbers and underscores allowed; maximum length - 16 characters)

Parameter	Required	Type	Enum	Description
currency	true	string	`BTC` `ETH` `USDT`	The currency symbol
extended	false	boolean		Include additional fields

Parameter	Required	Type	Enum	Description
instrument_name	true	string		Instrument name
amount	true	number		It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH
type	false	string	`limit` `stop_limit` `market` `stop_market`	The order type, default: `"limit"`
label	false	string		user defined label for the order (maximum 64 characters)
price	false	number		The order price in base currency (Only for limit and stop_limit orders) When adding order with advanced=usd, the field price should be the option price value in USD. When adding order with advanced=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%
time_in_force	false	string	`good_til_cancelled` `fill_or_kill` `immediate_or_cancel`	Specifies how long the order remains in effect. Default `"good_til_cancelled"` `"good_til_cancelled"` - unfilled order remains in order book until cancelled `"fill_or_kill"` - execute a transaction immediately and completely or not at all `"immediate_or_cancel"` - execute a transaction immediately, and any portion of the order that cannot be immediately filled is cancelled
max_show	false	number		Maximum amount within an order to be shown to other customers, `0` for invisible order
post_only	false	boolean		If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below the spread. Only valid in combination with time_in_force=`"good_til_cancelled"`
reject_post_only	false	boolean		If an order is considered post-only and this field is set to true then the order is put to order book unmodified or request is rejected and order is canceled. Only valid in combination with `"post_only"` set to true
reduce_only	false	boolean		If `true`, the order is considered reduce-only which is intended to only reduce a current position
stop_price	false	number		Stop price, required for stop limit orders (Only for stop orders)
trigger	false	string	`index_price` `mark_price` `last_price`	Defines trigger type, required for `"stop_limit"` and `"stop_market"` order types
advanced	false	string	`usd` `implv`	Advanced option order type. (Only for options)
mmp	false	boolean		Order MMP flag, only for order_type 'limit'

Parameter	Required	Type	Enum	Description
order_id	true	string		The order id
amount	true	number		It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH
price	false	number		The order price in base currency. When editing an option order with advanced=usd, the field price should be the option price value in USD. When editing an option order with advanced=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%
post_only	false	boolean		If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below or above the spread (accordingly to the original order type). Only valid in combination with time_in_force=`"good_til_cancelled"`
reduce_only	false	boolean		If `true`, the order is considered reduce-only which is intended to only reduce a current position
reject_post_only	false	boolean		If an order is considered post-only and this field is set to true then the order is put to order book unmodified or request is rejected and order is canceled. Only valid in combination with `"post_only"` set to true
advanced	false	string	`usd` `implv`	Advanced option order type. If you have posted an advanced option order, it is necessary to re-supply this parameter when editing it (Only for options)
stop_price	false	number		Stop price, required for stop limit orders (Only for stop orders)
mmp	false	boolean		Order MMP flag, only for order_type 'limit'

Name	Type	Description
data	object
› action	string	Action taken by the platform administrators. Published a `new` announcement, or `delete`d the old one
› body	string	HTML-formatted announcement body
› confirmation	boolean	Whether the user confirmation is required for this announcement
› id	integer	Announcement's identifier
› important	boolean	Whether the announcement is marked as important
› publication_timestamp	integer	The timestamp (milliseconds since the Unix epoch) of announcement publication
› title	string	Announcement's title
› unread	integer	The number of previous unread announcements (optional, only for authorized users).

Name	Type	Description
data	object
› asks	array of [price, amount]	List of asks
› bids	array of [price, amount]	List of bids
› change_id	integer	id of the notification
› instrument_name	string	Unique instrument identifier
› timestamp	integer	The timestamp of last change (milliseconds since the Unix epoch)

Name	Type	Description
data	object
› close	number	The close price for the candle
› cost	number	Cost data for the candle
› high	number	The highest price level for the candle
› low	number	The lowest price level for the candle
› open	number	The open price for the candle'
› tick	integer	The timestamp (milliseconds since the Unix epoch)
› volume	number	Volume data for the candle

Name	Type	Description
data	object
› index_name	string	Index identifier, matches (base) cryptocurrency with quote currency
› price	number	Current index price
› timestamp	integer	The timestamp (milliseconds since the Unix epoch)

Name	Type	Description
data	array of object
› enabled	boolean	Stock exchange status
› identifier	string	Stock exchange identifier
› original_price	number	Index price retrieved from stock's data
› price	number	Adjusted stock exchange index price, used for Deribit price index calculations
› timestamp	integer	The timestamp of the last update from stock exchange
› weight	number	The weight of the ranking given in percent

Name	Type	Description
data	object
› is_estimated	boolean	When `true` then price is given as an estimated value, otherwise it's current index price
› left_ticks	number	number of time ticks that are left until expiration (field added when price is estimated)
› price	number	Index current or estimated price
› seconds	integer	Number of seconds till finalizing the nearest instrument
› total_ticks	number	number of total time ticks (field added when price is estimated)

Name	Type	Description
data	object
› index_price	number	Current index price
› interest	number	Current interest
› timestamp	integer	The timestamp (milliseconds since the Unix epoch)

Name	Type	Description
data	object
› currency	string	Currency, i.e `"BTC"`, `"ETH"`, `"USDT"`
› locked	boolean	Value is set to 'true' when platform is locked

Name	Type	Description
data	object
› best_ask_amount	number	It represents the requested order size of all best asks
› best_ask_price	number	The current best ask price, `null` if there aren't any asks
› best_bid_amount	number	It represents the requested order size of all best bids
› best_bid_price	number	The current best bid price, `null` if there aren't any bids
› instrument_name	string	Unique instrument identifier
› timestamp	integer	The timestamp (milliseconds since the Unix epoch)

Name	Type	Description
data	object
› ask_iv	number	(Only for option) implied volatility for best ask
› best_ask_amount	number	It represents the requested order size of all best asks
› best_ask_price	number	The current best ask price, `null` if there aren't any asks
› best_bid_amount	number	It represents the requested order size of all best bids
› best_bid_price	number	The current best bid price, `null` if there aren't any bids
› bid_iv	number	(Only for option) implied volatility for best bid
› current_funding	number	Current funding (perpetual only)
› delivery_price	number	The settlement price for the instrument. Only when `state = closed`
› funding_8h	number	Funding 8h (perpetual only)
› greeks	object	Only for options
› › delta	number	(Only for option) The delta value for the option
› › gamma	number	(Only for option) The gamma value for the option
› › rho	number	(Only for option) The rho value for the option
› › theta	number	(Only for option) The theta value for the option
› › vega	number	(Only for option) The vega value for the option
› index_price	number	Current index price
› instrument_name	string	Unique instrument identifier
› interest_rate	number	Interest rate used in implied volatility calculations (options only)
› last_price	number	The price for the last trade
› mark_iv	number	(Only for option) implied volatility for mark price
› mark_price	number	The mark price for the instrument
› max_price	number	The maximum price for the future. Any buy orders you submit higher than this price, will be clamped to this maximum.
› min_price	number	The minimum price for the future. Any sell orders you submit lower than this price will be clamped to this minimum.
› open_interest	number	The total amount of outstanding contracts in the corresponding amount units. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
› settlement_price	number	The settlement price for the instrument. Only when `state = open`
› state	string	The state of the order book. Possible values are `open` and `closed`.
› stats	object
› › high	number	Highest price during 24h
› › low	number	Lowest price during 24h
› › price_change	number	24-hour price change expressed as a percentage, `null` if there weren't any trades
› › volume	number	Volume during last 24h in base currency
› timestamp	integer	The timestamp (milliseconds since the Unix epoch)
› underlying_index	number	Name of the underlying future, or `index_price` (options only)
› underlying_price	number	Underlying price for implied volatility calculations (options only)

Deribit API v2.0.1

Overview

Naming

Rate Limits

JSON-RPC

Request messages

Response messages

Notifications

Authentication

Additional authorization method - basic user credentials

Additional authorization method - Deribit signature credentials

Additional authorization method - signature credentials (WebSocket API)

Access scope

JSON-RPC over websocket

JSON-RPC over HTTP

Methods

Authentication

/public/auth

Parameters

Response

/public/exchange_token

Parameters

Response

/public/fork_token

Parameters

Response

/private/logout

Parameters

Response

Session management

/public/set_heartbeat

Parameters

Response

/public/disable_heartbeat

Parameters

Response

/private/enable_cancel_on_disconnect

Parameters

Response

/private/disable_cancel_on_disconnect

Parameters

Response

/private/get_cancel_on_disconnect

Parameters

Response

Supporting

/public/get_time

Parameters

Response

/public/hello

Parameters

Response

/public/test

Parameters

Response

Subscription management

/public/subscribe

Parameters

Response

/public/unsubscribe

Parameters

Response

/private/subscribe

Parameters

Response

/private/unsubscribe

Parameters

Response

Account management

/public/get_announcements

Parameters

Response

/private/change_api_key_name

Parameters

Response

/private/change_scope_in_api_key

Parameters

Response

/private/change_subaccount_name

Parameters

Name	Type	Description
data	object
› amount	number	Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
› block_trade_id	string	Block trade id - when trade was part of block trade
› direction	string	Direction: `buy`, or `sell`
› index_price	number	Index Price at the moment of trade
› instrument_name	string	Unique instrument identifier
› iv	number	Option implied volatility for the price (Option only)
› liquidation	string	Optional field (only for trades caused by liquidation): `"M"` when maker side of trade was under liquidation, `"T"` when taker side was under liquidation, `"MT"` when both sides of trade were under liquidation
› mark_price	number	Mark Price at the moment of trade
› price	number	Price in base currency
› tick_direction	integer	Direction of the "tick" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` = Minus Tick, `3` = Zero-Minus Tick).
› timestamp	integer	The timestamp of the trade
› trade_id	string	Unique (per currency) trade identifier
› trade_seq	integer	The sequence number of the trade within instrument

Name	Type	Description
data	object
› frozen_until	integer	Timestamp until user will be frozen, i 0 it means that user is frozen until manual reset.

Name	Type	Description
data	object
› mmp_cancelled	boolean	`true` if order was cancelled by mmp trigger (optional)
› order_state	string	Order state: `"open"`, `"filled"`, `"rejected"`, `"cancelled"`, `"untriggered"`
› max_show	number	Maximum amount within an order to be shown to other traders, 0 for invisible order.
› api	boolean	`true` if created with API
› amount	number	It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
› web	boolean	`true` if created via Deribit frontend (optional)
› instrument_name	string	Unique instrument identifier
› advanced	string	advanced type: `"usd"` or `"implv"` (Only for options; field is omitted if not applicable).

› triggered	boolean	Whether the stop order has been triggered (Only for stop orders)
› block_trade	boolean	`true` if order made from block_trade trade, added only in that case.
› original_order_type	string	Original order type. Optional field
› price	number	Price in base currency
› time_in_force	string	Order time in force: `"good_til_cancelled"`, `"fill_or_kill"`, `"immediate_or_cancel"`
› auto_replaced	boolean	Options, advanced orders only - `true` if last modification of the order was performed by the pricing engine, otherwise `false`.
› stop_order_id	string	Id of the stop order that was triggered to create the order (Only for orders that were created by triggered stop orders).
› last_update_timestamp	integer	The timestamp (milliseconds since the Unix epoch)
› post_only	boolean	`true` for post-only orders only
› replaced	boolean	`true` if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise `false`.
› filled_amount	number	Filled amount of the order. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.
› average_price	number	Average fill price of the order
› order_id	string	Unique order identifier
› reduce_only	boolean	`true` for reduce-only orders only
› commission	number	Commission paid so far (in base currency)
› app_name	string	Name of the application that placed the order on behalf of the user (optional).
› stop_price	number	Stop price (Only for future stop orders)
› label	string	User defined label (up to 64 characters)
› creation_timestamp	integer	The timestamp (milliseconds since the Unix epoch)
› direction	string	Direction: `buy`, or `sell`
› is_liquidation	boolean	`true` if order was automatically created during liquidation
› order_type	string	Order type: `"limit"`, `"market"`, `"stop_limit"`, `"stop_market"`
› usd	number	Option price in USD (Only if `advanced="usd"`)
› profit_loss	number	Profit and loss in base currency.
› implv	number	Implied volatility in percent. (Only if `advanced="implv"`)
› trigger	string	Trigger type (Only for stop orders). Allowed values: `"index_price"`, `"mark_price"`, `"last_price"`.

Name	Type	Description
data	object
› available_funds	number	The account's available funds
› available_withdrawal_funds	number	The account's available to withdrawal funds
› balance	number	The account's balance
› currency	string	The selected currency
› delta_total	number	The sum of position deltas
› equity	number	The account's current equity
› estimated_liquidation_ratio	number	Estimated Liquidation Ratio is returned only for users without portfolio margining enabled. Multiplying it by future position's market price returns its estimated liquidation price.
› futures_pl	number	Futures profit and Loss
› futures_session_rpl	number	Futures session realized profit and Loss
› futures_session_upl	number	Futures session unrealized profit and Loss
› initial_margin	number	The account's initial margin
› maintenance_margin	number	The maintenance margin.
› margin_balance	number	The account's margin balance
› options_delta	number	Options summary delta
› options_gamma	number	Options summary gamma
› options_pl	number	Options profit and Loss
› options_session_rpl	number	Options session realized profit and Loss
› options_session_upl	number	Options session unrealized profit and Loss
› options_theta	number	Options summary theta
› options_value	number	Options value
› options_vega	number	Options summary vega
› portfolio_margining_enabled	boolean	When `true` portfolio margining is enabled for user
› projected_delta_total	number	The sum of position deltas without positions that will expire during closest expiration
› projected_initial_margin	number	Projected initial margin
› projected_maintenance_margin	number	Projected maintenance margin
› session_rpl	number	Session realized profit and loss
› session_upl	number	Session unrealized profit and loss
› total_pl	number	Profit and loss

Error Code	Short message	Description
0 or absent		Success, No error.
9999	`"api_not_enabled"`	User didn't enable API for the Account.
10000	`"authorization_required"`	Authorization issue, invalid or absent signature etc.
10001	`"error"`	Some general failure, no public information available.
10002	`"qty_too_low"`	Order quantity is too low.
10003	`"order_overlap"`	Rejection, order overlap is found and self-trading is not enabled.
10004	`"order_not_found"`	Attempt to operate with order that can't be found by specified id.
10005	`"price_too_low <Limit>"`	Price is too low, `<Limit>` defines current limit for the operation.
10006	`"price_too_low4idx <Limit>"`	Price is too low for current index, `<Limit>` defines current bottom limit for the operation.
10007	`"price_too_high <Limit>"`	Price is too high, `<Limit>` defines current up limit for the operation.
10008	`"price_too_high4idx <Limit>"`	Price is too high for current index, `<Limit>` defines current up limit for the operation.
10009	`"not_enough_funds"`	Account has not enough funds for the operation.
10010	`"already_closed"`	Attempt of doing something with closed order.
10011	`"price_not_allowed"`	This price is not allowed for some reason.
10012	`"book_closed"`	Operation for instrument which order book had been closed.
10013	`"pme_max_total_open_orders <Limit>"`	Total limit of open orders has been exceeded, it is applicable for PME users.
10014	`"pme_max_future_open_orders <Limit>"`	Limit of count of futures' open orders has been exceeded, it is applicable for PME users.
10015	`"pme_max_option_open_orders <Limit>"`	Limit of count of options' open orders has been exceeded, it is applicable for PME users.
10016	`"pme_max_future_open_orders_size <Limit>"`	Limit of size for futures has been exceeded, it is applicable for PME users.
10017	`"pme_max_option_open_orders_size <Limit>"`	Limit of size for options has been exceeded, it is applicable for PME users.
10018	`"non_pme_max_future_position_size <Limit>"`	Limit of size for futures has been exceeded, it is applicable for non-PME users.
10019	`"locked_by_admin"`	Trading is temporary locked by admin.
10020	`"invalid_or_unsupported_instrument"`	Instrument name is not valid.
10021	`"invalid_amount"`	Amount is not valid.
10022	`"invalid_quantity"`	quantity was not recognized as a valid number (for API v1).
10023	`"invalid_price"`	price was not recognized as a valid number.
10024	`"invalid_max_show"`	`max_show` parameter was not recognized as a valid number.
10025	`"invalid_order_id"`	Order id is missing or its format was not recognized as valid.
10026	`"price_precision_exceeded"`	Extra precision of the price is not supported.
10027	`"non_integer_contract_amount"`	Futures contract amount was not recognized as integer.
10028	`"too_many_requests"`	Allowed request rate has been exceeded.
10029	`"not_owner_of_order"`	Attempt to operate with not own order.
10030	`"must_be_websocket_request"`	REST request where Websocket is expected.
10031	`"invalid_args_for_instrument"`	Some of arguments are not recognized as valid.
10032	`"whole_cost_too_low"`	Total cost is too low.
10033	`"not_implemented"`	Method is not implemented yet.
10034	`"stop_price_too_high"`	Stop price is too high.
10035	`"stop_price_too_low"`	Stop price is too low.
10036	`"invalid_max_show_amount"`	Max Show Amount is not valid.
10040	`"retry"`	Request can't be processed right now and should be retried.
10041	`"settlement_in_progress"`	Settlement is in progress. Every day at settlement time for several seconds, the system calculates user profits and updates balances. That time trading is paused for several seconds till the calculation is completed.
10043	`"price_wrong_tick"`	Price has to be rounded to a certain tick size.
10044	`"stop_price_wrong_tick"`	Stop Price has to be rounded to a certain tick size.
10045	`"can_not_cancel_liquidation_order"`	Liquidation order can't be canceled.
10046	`"can_not_edit_liquidation_order"`	Liquidation order can't be edited.
10047	`"matching_engine_queue_full"`	Reached limit of pending Matching Engine requests for user.
10048	`"not_on_this_server"`	The requested operation is not available on this server.
10049	`"cancel_on_disconnect_failed"`	Enabling Cancel On Disconnect for the connection failed.
10066	`"too_many_concurrent_requests"`	The client has sent too many public requests that have not yet been executed.
11008	`"already_filled"`	This request is not allowed in regards to the filled order.
11029	`"invalid_arguments"`	Some invalid input has been detected.
11030	`"other_reject <Reason>"`	Some rejects which are not considered as very often, more info may be specified in `<Reason>`.
11031	`"other_error <Error>"`	Some errors which are not considered as very often, more info may be specified in `<Error>`.
11035	`"no_more_stops <Limit>"`	Allowed amount of stop orders has been exceeded.
11036	`"invalid_stop_price_"`	Invalid `StopPx` (too high or too low) as to the last, current index or market price
11037	`"outdated_instrument_for_IV_order"`	Instrument already not available for trading.
11038	`"no_adv_for_futures"`	Advanced orders are not available for futures.
11039	`"no_adv_postonly"`	Advanced post-only orders are not supported yet.
11041	`"not_adv_order"`	Advanced order properties can't be set if the order is not advanced.
11042	`"permission_denied"`	Permission for the operation has been denied.
11043	`"bad_argument"`	Bad argument has been passed.
11044	`"not_open_order"`	Attempt to do open order operations with the not open order.
11045	`"invalid_event"`	Event name has not been recognized.
11046	`"outdated_instrument"`	At several minutes to instrument expiration, corresponding advanced implied volatility orders are not allowed.
11047	`"unsupported_arg_combination"`	The specified combination of arguments is not supported.
11048	`"wrong_max_show_for_option"`	Wrong Max Show for options.
11049	`"bad_arguments"`	Several bad arguments have been passed.
11050	`"bad_request"`	Request has not been parsed properly.
11051	`"system_maintenance"`	System is under maintenance.
11052	`"subscribe_error_unsubscribed"`	Subscription error. However, subscription may fail without this error, please check list of subscribed channels returned, as some channels can be not subscribed due to wrong input or lack of permissions.
11053	`"transfer_not_found"`	Specified transfer is not found.
11090	`"invalid_addr"`	Invalid address.
11091	`"invalid_transfer_address"`	Invalid addres for the transfer.
11092	`"address_already_exist"`	The address already exists.
11093	`"max_addr_count_exceeded"`	Limit of allowed addresses has been reached.
11094	`"internal_server_error"`	Some unhandled error on server. Please report to admin. The details of the request will help to locate the problem.
11095	`"disabled_deposit_address_creation"`	Deposit address creation has been disabled by admin.
11096	`"address_belongs_to_user"`	Withdrawal instead of transfer.
12000	`"bad_tfa"`	Wrong TFA code
12001	`"too_many_subaccounts"`	Limit of subbacounts is reached.
12002	`"wrong_subaccount_name"`	The input is not allowed as name of subaccount.
12998	`"tfa_over_limit"`	The number of failed TFA attempts is limited.
12003	`"login_over_limit"`	The number of failed login attempts is limited.
12004	`"registration_over_limit"`	The number of registration requests is limited.
12005	`"country_is_banned"`	The country is banned (possibly via IP check).
12100	`"transfer_not_allowed"`	Transfer is not allowed. Possible wrong direction or other mistake.
12999	`"tfa_used"`	TFA code is correct but it is already used. Please, use next code.
13000	`"invalid_login"`	Login name is invalid (not allowed or it contains wrong characters).
13001	`"account_not_activated"`	Account must be activated.
13002	`"account_blocked"`	Account is blocked by admin.
13003	`"tfa_required"`	This action requires TFA authentication.
13004	`"invalid_credentials"`	Invalid credentials has been used.
13005	`"pwd_match_error"`	Password confirmation error.
13006	`"security_error"`	Invalid Security Code.
13007	`"user_not_found"`	User's security code has been changed or wrong.
13008	`"request_failed"`	Request failed because of invalid input or internal failure.
13009	`"unauthorized"`	Wrong or expired authorization token or bad signature. For example, please check scope of the token, "connection" scope can't be reused for other connections.
13010	`"value_required"`	Invalid input, missing value.
13011	`"value_too_short"`	Input is too short.
13012	`"unavailable_in_subaccount"`	Subaccount restrictions.
13013	`"invalid_phone_number"`	Unsupported or invalid phone number.
13014	`"cannot_send_sms"`	SMS sending failed -- phone number is wrong.
13015	`"invalid_sms_code"`	Invalid SMS code.
13016	`"invalid_input"`	Invalid input.
13017	`"subscription_failed"`	Subscription failed, invalid subscription parameters.
13018	`"invalid_content_type"`	Invalid content type of the request.
13019	`"orderbook_closed"`	Closed, expired order book.
13020	`"not_found"`	Instrument is not found, invalid instrument name.
13021	`"forbidden"`	Not enough permissions to execute the request, forbidden.
13025	`"method_switched_off_by_admin"`	API method temporarily switched off by administrator.
13031	`"verification_required"`	API method allowed only for verified users
13503	`"unavailable"`	Method is currently not available.
13666	`"request_cancelled_by_user"`	Request was cancelled by user with other api request.
13777	`"replaced"`	Edit request was replaced by other one
-32602	`"Invalid params"`	See JSON-RPC spec.
-32601	`"Method not found"`	See JSON-RPC spec.
-32700	`"Parse error"`	See JSON-RPC spec.
-32000	`"Missing params"`	See JSON-RPC spec.

Tag	Name	Type	Required	Comments
8	`BeginString`	String	Yes	Identifies beginning of new message and protocol version. Must always be first in the message.
9	`BodyLength`	Length	Yes	Message length in bytes, not including fields 8, 9 and 10. See refer to FIX specification on how to compute this field. Must always be the first field in the message.
35	`MsgType`	String	Yes	The type of the message. See below for available types
49	`SenderCompID`	String	Yes	A user defined client name
56	`TargetCompID`	String	Yes	Constant value: `DERIBITSERVER`
34	`MsgSeqNum`	SeqNum	Yes	A sequence number for the message, starts with 1, and must be incremented by 1 for every message.
52	`SendingTime`	UTCTimestamp	No	The time the request is sent. This field is ignored by the server
10	`CheckSum`	String	Yes	The checksum of all of all preceding messages. See refer to FIX specification on how to compute this field. Must always be the last field in the message.

Tag	Name	Type	Required	Comments
108	`HeartBtInt`	int	Yes	Used to declare the timeout interval in seconds for generating heartbeats.
95	`RawDataLength`	Length	No	Number of bytes in raw data field. Not required, as the normal RawData is base64 text here
96	`RawData`	data	Yes	The timestamp and a Base64 encoded nonce (see below)
553	`Username`	String	Yes	API Access Key. This can be obtained from the API tab on your account settings.
554	`Password`	String	Yes	See below
9002	`UseWordsafeTags`	Boolean	No	If present and set to `Y`, all of the tag values for our custom tags start at 5000 instead of 100000. This can be used for FIX libraries that don't allow higher tag numbers. This will setting will apply for the remainder of the connection. For example, `Volume24h`(`100087`) would become `5078`.
9001	`CancelOnDisconnect`	Boolean	No	Boolean, to enable or disable session-level cancel on disconnect. Default - false(`N`).
9004	`DeribitAppId`	String	No	Registered application Client ID. It is necessary for registered applications only.
9005	`DeribitAppSig`	String	No	Registered application Signature. It is necessary for registered applications only. It is calculated in a similar way to the Password(554) but with Application Secret instead of Access Secret: `base64(sha256(RawData ++ application_secret))`, see below
9007	`DeribitSequential`	Boolean	No	Custom tag to adapt Deribit internal messaging to sequential FIX messaging. If the tag is present and set to 'Y', the messages are sent with sequential ordering, i.e., there is no priority for direct "call responses" over notifications. Please note this may lead to slower call-return information delivery in comparison with other user which do not use this flag
9009	`UnsubscribeExecutionReports`	Boolean	No	Custom tag. Default - false (`N`). If the tag is present and set to 'Y' this connection is unsubscribed from notificational Execution Reports about order changes. Only responses to order operation requests in this connection will be sent as Execution Reports, but no notifications such as orders from other connection or trades initiated by counterparty

Tag	Name	Type	Required	Comments
58	`text`	String	No	Free format text string specifying the logout reason. This is ignored by the server
9003	`DontCancelOnDisconnect`	Boolean	No	If `Y` then it disables `CancelOnDisconnect` for this connection even if `CancelOnDisconnect` was enabled in `Logon` or account settings. Default - false(`N`), no changes for `CancelOnDisconnect` flag.

Tag	Name	Type	Required	Comments
7	`BeginSeqNo`	Yes	The first message to repeat
16	`EndSeqNo`	Yes	The last message to repeat

Tag	Name	Type	Required	Comments
45	`RefSeqNum`	SeqNum	Yes	`MsgSeqNum`(`34`) of the rejected message
372	`RefMsgType`	String	No	The `MsgType`(`35`) of the FIX message being referenced
373	`SessionRejectReason`	int	No	Code to identity reason for rejection. See FIX specification for possible values.
58	`Text`	String	No	Text string explaining the reason for rejection.