NAV Show example code
shell javascript python

Deribit API v2.1.1

Overview

Deribit provides three different interfaces to access the API:

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.

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

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.

Detailed response for private/cancel_all* and private/cancel_by_label methods

An example of a positive execution of cancellation trigger orders in ETH-PERPETUAL when one order was canceled:

{
    "currency": "BTC",
    "type": "trigger",
    "instrument_name": "ETH-PERPETUAL",
    "result": [{
      "web": true,
      "triggered": false,
      "trigger_price": 1628.7,
      "trigger": "last_price",
      "time_in_force": "good_til_cancelled",
      "stop_price": 1628.7,
      "replaced": false,
      "reduce_only": false,
      "profit_loss": 0,
      "price": "market_price",
      "post_only": false,
      "order_type": "stop_market",
      "order_state": "untriggered",
      "order_id": "ETH-SLTS-250756",
      "max_show": 100,
      "last_update_timestamp": 1634206091071,
      "label": "",
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "direction": "sell",
      "creation_timestamp": 1634206000230,
      "api": false,
      "amount": 100
    }]
}

When boolean parameter detailed with value true is added to cancel_all* or cancel_by_label methods response format is changed. Instead of number of canceled orders there is returned list of execution reports objects for every requested instrument, order type and currency: results of positive or erroneous execution. It is done this way because internally during processing cancel_all request there are done separate requests for every currency, order type and book.

Positive execution report

Positive execution report is object with fields:

Erroneous execution report

Erroneous execution report is object with fields:

An example of information that cancel of limit orders in ETH failed:

{
  "currency": "ETH",
  "type": "limit", 
  "error": {
    "message": "matching_engine_queue_full",
    "code": 10047
  }
}

Security keys

Request that may require security key authorization

{
  "method": "private/list_api_keys",
  "params": {}
}

Some methods may require additional authorization using Security Keys (depending on the user's account configuration). In this case, instead of a normal response, there is returned response with field security_key_authorization_required set to true. When that happens the client is required to resent a request with additional parameters: authorization_data and challenge.

For example, after client sends request that needs Security Key confirmation, like private/list_api_keys server return (non error) response with field: security_key_authorization_required set to true. Other fields are attached too:

Example of response with request to make Security Key authorization:

{
    "jsonrpc": "2.0",
    "result": {
      "security_keys": [
         {
            "type": "tfa",
            "name": "tfa"
         }
      ],
      "security_key_authorization_required": true,
      "rp_id": "test.deribit.com",
      "challenge": "+Di4SKN9VykrSoHlZO2KF3LEyEZF4ih9CZXVuudQiKQ="
    }
}

TFA authorization

When the user chooses TFA authorization, he should read the TFA code from his application, and it should be added to original requests parameters as authorization_data. It is required to add to parameters challenge too. Then request should be repeated with those updated parameters.

Example of request when TFA code is 602051:

{
    "id":88,
    "method": "private/list_api_keys",
    "params": {
        "authorization_data": "602051",
        "challenge": "+Di4SKN9VykrSoHlZO2KF3LEyEZF4ih9CZXVuudQiKQ="
    }
}

U2F authorization

For details of U2F authorization ask our staff.

Errors:

When there is an error related to the Security Key authorization, a response with the error security_key_authorization_error (code: 13668) is returned. It will have a data.reason field that possible values are:

When error occurred, request needs to be repeated without authorization_data to obtain new challenge.

Example of erroneous response:

{
    "jsonrpc":"2.0",
    "error":{
        "message":"security_key_authorization_error",
        "data":{
            "reason":"tfa_code_not_matched"
        },
        "code":13668
    }
}

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:

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.

Try in API console

Parameters

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 (milliseconds since the UNIX epoch)
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

Response

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
  ›  sid string Optional Session id
  ›  state string Copied from the input (if applicable)
  ›  token_type string Authorization type, allowed value - bearer

/public/exchange_token

curl -X GET "https://test.deribit.com/api/v2/public/exchange_token?refresh_token=1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ&subject_id=10" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7619,
  "method" : "public/exchange_token",
  "params" : {
    "refresh_token" : "1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ",
    "subject_id" : 10
  }
};
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" : 7619,
  "method" : "public/exchange_token",
  "params" : {
    "refresh_token" : "1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ",
    "subject_id" : 10
  }
}

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": "session:named_session mainaccount",
      "token_type": "bearer"
  }
}

Generates token for new subject id. This method can be used to switch between subaccounts.

Try in API console

Parameters

Parameter Required Type Enum Description
refresh_token true string Refresh token
subject_id true integer New subject id

Response

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
  ›  sid string Optional Session id
  ›  token_type string Authorization type, allowed value - bearer

/public/fork_token

curl -X GET "https://test.deribit.com/api/v2/public/fork_token?refresh_token=1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ&session_name=forked_session_name" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7620,
  "method" : "public/fork_token",
  "params" : {
    "refresh_token" : "1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ",
    "session_name" : "forked_session_name"
  }
};
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" : 7620,
  "method" : "public/fork_token",
  "params" : {
    "refresh_token" : "1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ",
    "session_name" : "forked_session_name"
  }
}

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": "session:named_session mainaccount",
      "token_type": "bearer"
  }
}

Generates token for new named session. This method can be used only with session scoped tokens.

Try in API console

Parameters

Parameter Required Type Enum Description
refresh_token true string Refresh token
session_name true string New session name

Response

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
  ›  sid string Optional Session id
  ›  token_type string Authorization type, allowed value - bearer

/private/logout

This method is only available via websockets.

var msg = 
    {"jsonrpc": "2.0",
     "method": "private/logout",
     "id": 42,
     "params": {
        "access_token": "1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP",
        "invalidate_token": true}
    };
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
    {"jsonrpc": "2.0",
     "method": "private/logout",
     "id": 42,
     "params": {
        "access_token": "1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP",
        "invalidate_token": True}
    }

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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)))

This method has no response body

Gracefully close websocket connection, when COD (Cancel On Disconnect) is enabled orders are not cancelled

Try in API console

Parameters

Parameter Required Type Enum Description
invalidate_token false boolean If value is true all tokens created in current session are invalidated, default: true

Response

This method has no response body

Session management

/public/set_heartbeat

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9098,
  "method" : "public/set_heartbeat",
  "params" : {
    "interval" : 30
  }
};
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" : 9098,
  "method" : "public/set_heartbeat",
  "params" : {
    "interval" : 30
  }
}

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": 9098,
  "result": "ok"
}

Signals the Websocket connection to send and request heartbeats. Heartbeats can be used to detect stale connections. When heartbeats have been set up, the API server will send heartbeat messages and test_request messages. Your software should respond to test_request messages by sending a /api/v2/public/test request. If your software fails to do so, the API server will immediately close the connection. If your account is configured to cancel on disconnect, any orders opened over the connection will be cancelled.

Try in API console

Parameters

Parameter Required Type Enum Description
interval true number The heartbeat interval in seconds, but not less than 10

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result string Result of method execution. ok in case of success

/public/disable_heartbeat

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3562,
  "method" : "public/disable_heartbeat",
  "params" : {

  }
};
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" : 3562,
  "method" : "public/disable_heartbeat",
  "params" : {

  }
}

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": 3562,
    "result": "ok"
}

Stop sending heartbeat messages.

Try in API console

Parameters

This method takes no parameters

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result string Result of method execution. ok in case of success

/private/enable_cancel_on_disconnect

curl -X GET "https://test.deribit.com/api/v2/private/enable_cancel_on_disconnect?scope=account" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7859,
  "method" : "private/enable_cancel_on_disconnect",
  "params" : {
    "scope" : "account"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 7859,
  "method" : "private/enable_cancel_on_disconnect",
  "params" : {
    "scope" : "account"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 7859,
  "result": "ok"
}

Enable Cancel On Disconnect for the connection. After enabling Cancel On Disconnect all orders created by the connection will be removed when connection is closed.

NOTICE It does not affect orders created by other connections - they will remain active !

When change is applied for the account, then every newly opened connection will start with active Cancel on Disconnect.

Try in API console

Parameters

Parameter Required Type Enum Description
scope false string connection
account
Specifies if Cancel On Disconnect change should be applied/checked for the current connection or the account (default - connection)

NOTICE: Scope connection can be used only when working via Websocket.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result string Result of method execution. ok in case of success

/private/disable_cancel_on_disconnect

curl -X GET "https://test.deribit.com/api/v2/private/disable_cancel_on_disconnect?scope=account" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 1569,
  "method" : "private/disable_cancel_on_disconnect",
  "params" : {
    "scope" : "account"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 1569,
  "method" : "private/disable_cancel_on_disconnect",
  "params" : {
    "scope" : "account"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 1569,
  "result": "ok"
}

Disable Cancel On Disconnect for the connection.

When change is applied for the account, then every newly opened connection will start with inactive Cancel on Disconnect.

Try in API console

Parameters

Parameter Required Type Enum Description
scope false string connection
account
Specifies if Cancel On Disconnect change should be applied/checked for the current connection or the account (default - connection)

NOTICE: Scope connection can be used only when working via Websocket.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result string Result of method execution. ok in case of success

/private/get_cancel_on_disconnect

curl -X GET "https://test.deribit.com/api/v2/private/get_cancel_on_disconnect?scope=account" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 220,
  "method" : "private/get_cancel_on_disconnect",
  "params" : {
    "scope" : "account"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 220,
  "method" : "private/get_cancel_on_disconnect",
  "params" : {
    "scope" : "account"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 220,
  "result": {
    "scope" : "account",
    "enabled": false
  }
}

Read current Cancel On Disconnect configuration for the account.

Try in API console

Parameters

Parameter Required Type Enum Description
scope false string connection
account
Specifies if Cancel On Disconnect change should be applied/checked for the current connection or the account (default - connection)

NOTICE: Scope connection can be used only when working via Websocket.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  enabled boolean Current configuration status
  ›  scope string Informs if Cancel on Disconnect was checked for the current connection or the account

Supporting

/public/get_time

curl -X GET "https://test.deribit.com/api/v2/public/get_time?" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7365,
  "method" : "public/get_time",
  "params" : {

  }
};
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" : 7365,
  "method" : "public/get_time",
  "params" : {

  }
}

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": 7365,
  "result": 1550147385946
}

Retrieves the current time (in milliseconds). This API endpoint can be used to check the clock skew between your software and Deribit's systems.

Try in API console

Parameters

This method takes no parameters

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result integer Current timestamp (milliseconds since the UNIX epoch)

/public/hello

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2841,
  "method" : "public/hello",
  "params" : {
    "client_name" : "My Trading Software",
    "client_version" : "1.0.2"
  }
};
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" : 2841,
  "method" : "public/hello",
  "params" : {
    "client_name" : "My Trading Software",
    "client_version" : "1.0.2"
  }
}

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": 2841,
    "result": {
        "version": "1.2.26"
    }
}

Method used to introduce the client software connected to Deribit platform over websocket. Provided data may have an impact on the maintained connection and will be collected for internal statistical purposes. In response, Deribit will also introduce itself.

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  version string The API version

/public/status

curl -X GET "https://test.deribit.com/api/v2/public/status?" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 55,
  "method" : "public/status",
  "params" : {

  }
};
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" : 55,
  "method" : "public/status",
  "params" : {

  }
}

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": 55,
  "result": {
    "locked_currencies": ["BTC", "ETH"],
    "locked": true
  }
}

Method used to get information about locked currencies

Try in API console

Parameters

This method takes no parameters

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  locked string true when platform is locked in all currencies, partial when some currencies are locked, false - when there are not currencies locked
  ›  locked_currencies array List of currencies in which platform is locked

/public/test

curl -X GET "https://test.deribit.com/api/v2/public/test?" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8212,
  "method" : "public/test",
  "params" : {

  }
};
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" : 8212,
  "method" : "public/test",
  "params" : {

  }
}

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": 8212,
  "result": {
    "version": "1.2.26"
  }
}

Tests the connection to the API server, and returns its version. You can use this to make sure the API is reachable, and matches the expected version.

Try in API console

Parameters

Parameter Required Type Enum Description
expected_result false string exception The value "exception" will trigger an error response. This may be useful for testing wrapper libraries.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  version string The API version

Subscription management

Subscription works as notifications, so users will automatically (after subscribing) receive messages from the server. Overview for each channel response format is described in subscriptions section.

/public/subscribe

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3600,
  "method" : "public/subscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
};
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" : 3600,
  "method" : "public/subscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
}

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": 3600,
  "result": [
    "deribit_price_index.btc_usd"
  ]
}

Subscribe to one or more channels.

This is the same method as /private/subscribe, but it can only be used for 'public' channels.

Try in API console

Parameters

Parameter Required Type Enum Description
channels true array A list of channels to subscribe to.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of string A list of subscribed channels.

/public/unsubscribe

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8691,
  "method" : "public/unsubscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
};
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" : 8691,
  "method" : "public/unsubscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
}

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": 8691,
  "result": [
    "deribit_price_index.btc_usd"
  ]
}

Unsubscribe from one or more channels.

Try in API console

Parameters

Parameter Required Type Enum Description
channels true array A list of channels to unsubscribe from.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of string A list of subscribed channels.

/public/unsubscribe_all

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 153,
  "method" : "public/unsubscribe_all",
  "params" : {

  }
};
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" : 153,
  "method" : "public/unsubscribe_all",
  "params" : {

  }
}

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": 153,
  "result": "ok"
}

Unsubscribe from all the channels subscribed so far.

Try in API console

Parameters

This method takes no parameters

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result string Result of method execution. ok in case of success

/private/subscribe

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 4235,
  "method" : "private/subscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 4235,
  "method" : "private/subscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 4235,
  "result": [
    "deribit_price_index.btc_usd"
  ]
}

Subscribe to one or more channels.

The name of the channel determines what information will be provided, and in what form.

Try in API console

Parameters

Parameter Required Type Enum Description
channels true array A list of channels to subscribe to.
label false string Optional label which will be added to notifications of private channels (max 16 characters).

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of string A list of subscribed channels.

/private/unsubscribe

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3370,
  "method" : "private/unsubscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 3370,
  "method" : "private/unsubscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 3370,
  "result": [
    "deribit_price_index.btc_usd"
  ]
}

Unsubscribe from one or more channels.

Try in API console

Parameters

Parameter Required Type Enum Description
channels true array A list of channels to unsubscribe from.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of string A list of subscribed channels.

/private/unsubscribe_all

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 154,
  "method" : "private/unsubscribe_all",
  "params" : {

  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 154,
  "method" : "private/unsubscribe_all",
  "params" : {

  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 154,
  "result": "ok"
}

Unsubscribe from all the channels subscribed so far.

Try in API console

Parameters

This method takes no parameters

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result string Result of method execution. ok in case of success

Market data

/public/get_book_summary_by_currency

curl -X GET "https://test.deribit.com/api/v2/public/get_book_summary_by_currency?currency=BTC&kind=future" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9344,
  "method" : "public/get_book_summary_by_currency",
  "params" : {
    "currency" : "BTC",
    "kind" : "future"
  }
};
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" : 9344,
  "method" : "public/get_book_summary_by_currency",
  "params" : {
    "currency" : "BTC",
    "kind" : "future"
  }
}

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": 9344,
  "result": [
    {
      "volume_usd": 0,
      "volume": 0,
      "quote_currency": "USD",
      "price_change": -11.1896349,
      "open_interest": 0,
      "mid_price": null,
      "mark_price": 3579.73,
      "low": null,
      "last": null,
      "instrument_name": "BTC-22FEB19",
      "high": null,
      "estimated_delivery_price": 3579.73,
      "creation_timestamp": 1550230036440,
      "bid_price": null,
      "base_currency": "BTC",
      "ask_price": null
    },
    {
      "volume_usd": 22440,
      "volume": 6.24,
      "quote_currency": "USD",
      "price_change": -60.8183509,
      "open_interest": 183180,
      "mid_price": null,
      "mark_price": 3579.73,
      "low": 3591,
      "last": 3595,
      "instrument_name": "BTC-PERPETUAL",
      "high": 3595,
      "funding_8h": 0.0002574,
      "estimated_delivery_price": 3579.73,
      "current_funding": 0,
      "creation_timestamp": 1550230036440,
      "bid_price": null,
      "base_currency": "BTC",
      "ask_price": null
    }
  ]
}

Retrieves the summary information such as open interest, 24h volume, etc. for all instruments for the currency (optionally filtered by kind).

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
kind false string future
option
future_combo
option_combo
Instrument kind, if not provided instruments of all kinds are considered

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  ask_price number The current best ask price, null if there aren't any asks
  ›  base_currency string Base currency
  ›  bid_price number The current best bid price, null if there aren't any bids
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  current_funding number Current funding (perpetual only)
  ›  estimated_delivery_price number Estimated delivery price for the market. For more details, see Contract Specification > General Documentation > Expiration Price
  ›  funding_8h number Funding 8h (perpetual only)
  ›  high number Price of the 24h highest trade
  ›  instrument_name string Unique instrument identifier
  ›  interest_rate number Interest rate used in implied volatility calculations (options only)
  ›  last number The price of the latest trade, null if there weren't any trades
  ›  low number Price of the 24h lowest trade, null if there weren't any trades
  ›  mark_price number The current instrument market price
  ›  mid_price number The average of the best bid and ask, null if there aren't any asks or bids
  ›  notional_volume number Volume in quote currency (futures only)
  ›  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.
  ›  price_change number 24-hour price change expressed as a percentage, null if there weren't any trades
  ›  quote_currency string Quote currency
  ›  underlying_index string Name of the underlying future, or 'index_price' (options only)
  ›  underlying_price number underlying price for implied volatility calculations (options only)
  ›  volume number The total 24h traded volume (in base currency)
  ›  volume_usd number [DEPRECATED] Volume in usd, use 'notional_volume' instead, available only for instruments with USD as quote currency

/public/get_book_summary_by_instrument

curl -X GET "https://test.deribit.com/api/v2/public/get_book_summary_by_instrument?instrument_name=ETH-22FEB19-140-P" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3659,
  "method" : "public/get_book_summary_by_instrument",
  "params" : {
    "instrument_name" : "ETH-22FEB19-140-P"
  }
};
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" : 3659,
  "method" : "public/get_book_summary_by_instrument",
  "params" : {
    "instrument_name" : "ETH-22FEB19-140-P"
  }
}

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": 3659,
  "result": [
    {
      "volume": 0.55,
      "underlying_price": 121.38,
      "underlying_index": "index_price",
      "quote_currency": "USD",
      "price_change": -26.7793594,
      "open_interest": 0.55,
      "mid_price": 0.2444,
      "mark_price": 0.179112,
      "low": 0.34,
      "last": 0.34,
      "interest_rate": 0.207,
      "instrument_name": "ETH-22FEB19-140-P",
      "high": 0.34,
      "creation_timestamp": 1550227952163,
      "bid_price": 0.1488,
      "base_currency": "ETH",
      "ask_price": 0.34
    }
  ]
}

Retrieves the summary information such as open interest, 24h volume, etc. for a specific instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  ask_price number The current best ask price, null if there aren't any asks
  ›  base_currency string Base currency
  ›  bid_price number The current best bid price, null if there aren't any bids
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  current_funding number Current funding (perpetual only)
  ›  estimated_delivery_price number Estimated delivery price for the market. For more details, see Contract Specification > General Documentation > Expiration Price
  ›  funding_8h number Funding 8h (perpetual only)
  ›  high number Price of the 24h highest trade
  ›  instrument_name string Unique instrument identifier
  ›  interest_rate number Interest rate used in implied volatility calculations (options only)
  ›  last number The price of the latest trade, null if there weren't any trades
  ›  low number Price of the 24h lowest trade, null if there weren't any trades
  ›  mark_price number The current instrument market price
  ›  mid_price number The average of the best bid and ask, null if there aren't any asks or bids
  ›  notional_volume number Volume in quote currency (futures only)
  ›  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.
  ›  price_change number 24-hour price change expressed as a percentage, null if there weren't any trades
  ›  quote_currency string Quote currency
  ›  underlying_index string Name of the underlying future, or 'index_price' (options only)
  ›  underlying_price number underlying price for implied volatility calculations (options only)
  ›  volume number The total 24h traded volume (in base currency)
  ›  volume_usd number [DEPRECATED] Volume in usd, use 'notional_volume' instead, available only for instruments with USD as quote currency

/public/get_contract_size

curl -X GET "https://test.deribit.com/api/v2/public/get_contract_size?instrument_name=BTC-PERPETUAL" \
-H "Content-Type: application/json"
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_contract_size",
     "id": 42,
     "params": {
        "instrument_name": "BTC-PERPETUAL"}
    };
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",
     "method": "public/get_contract_size",
     "id": 42,
     "params": {
        "instrument_name": "BTC-PERPETUAL"}
    }

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:

{
    "jsonrpc": "2.0",
    "result": {
        "contract_size": 10
    }
}

Retrieves contract size of provided instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  contract_size integer Contract size, for futures in USD, for options in base currency of the instrument (BTC, ETH, ...)

/public/get_currencies

curl -X GET "https://test.deribit.com/api/v2/public/get_currencies?" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7538,
  "method" : "public/get_currencies",
  "params" : {

  }
};
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" : 7538,
  "method" : "public/get_currencies",
  "params" : {

  }
}

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": 7538,
  "result": [
      {
          "coin_type": "ETHER",
          "currency": "ETH",
          "currency_long": "Ethereum",
          "fee_precision": 4,
          "min_confirmations": 1,
          "min_withdrawal_fee": 0.0001,
          "withdrawal_fee": 0.0006,
          "withdrawal_priorities": []
      },
      {
          "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"
              }
          ]
      }
  ]
}    

Retrieves all cryptocurrencies supported by the API.

Try in API console

Parameters

This method takes no parameters

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  coin_type string The type of the currency.
  ›  currency string The abbreviation of the currency. This abbreviation is used elsewhere in the API to identify the currency.
  ›  currency_long string The full name for the currency.
  ›  fee_precision integer fee precision
  ›  min_confirmations integer Minimum number of block chain confirmations before deposit is accepted.
  ›  min_withdrawal_fee number The minimum transaction fee paid for withdrawals
  ›  withdrawal_fee number The total transaction fee paid for withdrawals
  ›  withdrawal_priorities array of object
  ›    ›  name string
  ›    ›  value number

/public/get_delivery_prices

curl -X GET "https://test.deribit.com/api/v2/public/get_delivery_prices?count=5&index_name=btc_usd&offset=0" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3601,
  "method" : "public/get_delivery_prices",
  "params" : {
    "index_name" : "btc_usd",
    "offset" : 0,
    "count" : 5
  }
};
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" : 3601,
  "method" : "public/get_delivery_prices",
  "params" : {
    "index_name" : "btc_usd",
    "offset" : 0,
    "count" : 5
  }
}

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": 3601,
  "result": {
    "data": [
      {
        "date": "2020-01-02",
        "delivery_price": 7131.214606410254
      },
      {
        "date": "2019-12-21",
        "delivery_price": 7150.943217777777
      },
      {
        "date": "2019-12-20",
        "delivery_price": 7175.988445532345
      },
      {
        "date": "2019-12-19",
        "delivery_price": 7189.540776143791
      },
      {
        "date": "2019-12-18",
        "delivery_price": 6698.353743857118
      }
    ],
    "records_total": 58
  }
}

Retrives delivery prices for then given index

Try in API console

Parameters

Parameter Required Type Enum Description
index_name true string ada_usd
avax_usd
btc_usd
eth_usd
dot_usd
luna_usd
matic_usd
sol_usd
usdc_usd
xrp_usd
ada_usdc
avax_usdc
btc_usdc
eth_usdc
dot_usdc
luna_usdc
matic_usdc
sol_usdc
xrp_usdc
btcdvol_usdc
ethdvol_usdc
Index identifier, matches (base) cryptocurrency with quote currency
offset false integer The offset for pagination, default - 0
count false integer Number of requested items, default - 10

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  data array of object
  ›    ›  date string The event date with year, month and day
  ›    ›  delivery_price number The settlement price for the instrument. Only when state = closed
  ›  records_total number Available delivery prices

/public/get_funding_chart_data

curl -X GET "https://test.deribit.com/api/v2/public/get_funding_chart_data?instrument_name=BTC-PERPETUAL&length=8h" \
-H "Content-Type: application/json"
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_funding_chart_data",
     "id": 42,
     "params": {
        "instrument_name": "BTC-PERPETUAL",
        "length": "8h"}
    };
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",
     "method": "public/get_funding_chart_data",
     "id": 42,
     "params": {
        "instrument_name": "BTC-PERPETUAL",
        "length": "8h"}
    }

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:

{
    "jsonrpc": "2.0",
    "result": {
        "current_interest": 0.0050006706,
        "data": [{
                "index_price": 8247.27,
                "interest_8h": 0.0049995114,
                "timestamp": 1536569522277
            }],
        "interest_8h": 0.0040080897
    }
}

Retrieve the list of the latest PERPETUAL funding chart points within a given time period.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
length true string 8h
24h
1m
Specifies time period. 8h - 8 hours, 24h - 24 hours, 1m - 1 month

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  current_interest number Current interest
  ›  data array of object
  ›    ›  index_price number Current index price
  ›    ›  interest_8h number Historical interest 8h value
  ›    ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  interest_8h number Current interest 8h

/public/get_funding_rate_history

curl -X GET "https://test.deribit.com/api/v2/public/get_funding_rate_history?end_timestamp=1569902400000&instrument_name=BTC-PERPETUAL&start_timestamp=1569888000000" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7617,
  "method" : "public/get_funding_rate_history",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "start_timestamp" : 1569888000000,
    "end_timestamp" : 1569902400000
  }
};
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" : 7617,
  "method" : "public/get_funding_rate_history",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "start_timestamp" : 1569888000000,
    "end_timestamp" : 1569902400000
  }
}

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": 7617,
  "result": [
    {
      "timestamp": 1569891600000,
      "index_price": 8222.87,
      "prev_index_price": 8305.72,
      "interest_8h": -0.00009234260068476106,
      "interest_1h": -4.739622041017375e-7
    },
    {
      "timestamp": 1569895200000,
      "index_price": 8286.49,
      "prev_index_price": 8222.87,
      "interest_8h": -0.00006720918180255509,
      "interest_1h": -2.8583510923267753e-7
    },
    {
      "timestamp": 1569898800000,
      "index_price": 8431.97,
      "prev_index_price": 8286.49,
      "interest_8h": -0.00003544496169694662,
      "interest_1h": -0.000003815906848177951
    },
    {
      "timestamp": 1569902400000,
      "index_price": 8422.36,
      "prev_index_price": 8431.97,
      "interest_8h": -0.00001404147515584998,
      "interest_1h": 8.312033064379086e-7
    }
  ]
}

Retrieves hourly historical interest rate for requested PERPETUAL instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_timestamp true integer The earliest timestamp to return result for (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result for (milliseconds since the UNIX epoch)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  index_price number Price in base currency
  ›  interest_1h float 1hour interest rate
  ›  interest_8h float 8hour interest rate
  ›  prev_index_price number Price in base currency
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

/public/get_funding_rate_value

curl -X GET "https://test.deribit.com/api/v2/public/get_funding_rate_value?end_timestamp=1569974400000&instrument_name=BTC-PERPETUAL&start_timestamp=1569888000000" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7617,
  "method" : "public/get_funding_rate_value",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "start_timestamp" : 1569888000000,
    "end_timestamp" : 1569974400000
  }
};
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" : 7617,
  "method" : "public/get_funding_rate_value",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "start_timestamp" : 1569888000000,
    "end_timestamp" : 1569974400000
  }
}

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": 7617,
  "result": -0.00025056853702101664
}

Retrieves interest rate value for requested period. Applicable only for PERPETUAL instruments.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_timestamp true integer The earliest timestamp to return result for (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result for (milliseconds since the UNIX epoch)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result float

/public/get_historical_volatility

curl -X GET "https://test.deribit.com/api/v2/public/get_historical_volatility?currency=BTC" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8387,
  "method" : "public/get_historical_volatility",
  "params" : {
    "currency" : "BTC"
  }
};
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" : 8387,
  "method" : "public/get_historical_volatility",
  "params" : {
    "currency" : "BTC"
  }
}

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": 8387,
  "result": [
      [
          1549720800000,
          14.747743607344217
      ],
      [
          1549720800000,
          14.747743607344217
      ],
      [
          1549724400000,
          14.74257778551467
      ],
      [
          1549728000000,
          14.73502799931767
      ],
      [
          1549731600000,
          14.73502799931767
      ],
      [
          1549735200000,
          14.73502799931767
      ],
      [
          1550228400000,
          46.371891307340015
      ]
  ]
}

Provides information about historical volatility for given cryptocurrency.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of [timestamp, value]

/public/get_index

curl -X GET "https://test.deribit.com/api/v2/public/get_index?currency=BTC" \
-H "Content-Type: application/json"
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_index",
     "id": 42,
     "params": {
        "currency": "BTC"}
    };
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",
     "method": "public/get_index",
     "id": 42,
     "params": {
        "currency": "BTC"}
    }

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:

{
    "jsonrpc": "2.0",
    "result": {
        "BTC": 11628.81,
        "edp": 11628.81
    }
}

Retrieves the current index price for the instruments, for the selected currency.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  BTC number The current index price for BTC-USD (only for selected currency == BTC)
  ›  ETH number The current index price for ETH-USD (only for selected currency == ETH)
  ›  edp number Estimated delivery price for the currency. For more details, see Documentation > General > Expiration Price

/public/get_index_price

curl -X GET "https://test.deribit.com/api/v2/public/get_index_price?index_name=ada_usd" \
-H "Content-Type: application/json"
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_index_price",
     "id": 42,
     "params": {
        "index_name": "ada_usd"}
    };
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",
     "method": "public/get_index_price",
     "id": 42,
     "params": {
        "index_name": "ada_usd"}
    }

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:

{
    "jsonrpc": "2.0",
    "result": {
        "estimated_delivery_price": 11628.81,
        "index_price": 11628.81
    }
}

Retrieves the current index price value for given index name.

Try in API console

Parameters

Parameter Required Type Enum Description
index_name true string ada_usd
avax_usd
btc_usd
eth_usd
dot_usd
luna_usd
matic_usd
sol_usd
usdc_usd
xrp_usd
ada_usdc
avax_usdc
btc_usdc
eth_usdc
dot_usdc
luna_usdc
matic_usdc
sol_usdc
xrp_usdc
btcdvol_usdc
ethdvol_usdc
Index identifier, matches (base) cryptocurrency with quote currency

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  estimated_delivery_price number Estimated delivery price for the market. For more details, see Documentation > General > Expiration Price
  ›  index_price number Value of requested index

/public/get_index_price_names

curl -X GET "https://test.deribit.com/api/v2/public/get_index_price_names" \
-H "Content-Type: application/json"
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_index_price_names",
     "id": 42
    };
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",
     "method": "public/get_index_price_names",
     "id": 42
    }

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": 7617,
  "result": [
    "btc_usd",
    "eth_usd",
    "btc_usdc",
    "eth_usdc"
  ]
}

Retrieves the identifiers of all supported Price Indexes

Try in API console

Parameters

This method takes no parameters

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of string

/public/get_instrument

curl -X GET "https://test.deribit.com/api/v2/public/get_instrument?instrument_name=BTC-12FEB21-31500-P" \
-H "Content-Type: application/json"
var msg = 
{
  "method" : "public/get_instrument",
  "params" : {
    "instrument_name" : "BTC-12FEB21-31500-P"
  },
  "jsonrpc" : "2.0",
  "id" : 0
};
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 = \
{
  "method" : "public/get_instrument",
  "params" : {
    "instrument_name" : "BTC-12FEB21-31500-P"
  },
  "jsonrpc" : "2.0",
  "id" : 0
}

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": 0,
  "result": {
    "tick_size": 0.0001,
    "taker_commission": 0.0005,
    "strike": 31500,
    "settlement_period": "week",
    "quote_currency": "USD",
    "settlement_currency": "BTC",
    "counter_currency": "USD",
    "price_index": "btc_usd",
    "option_type": "put",
    "min_trade_amount": 0.01,
    "maker_commission": 0.0001,
    "kind": "option",
    "is_active": true,
    "instrument_name": "BTC-12FEB21-31500-P",
    "expiration_timestamp": 1613116800000,
    "creation_timestamp": 1611658131000,
    "contract_size": 1,
    "block_trade_commission": 0.00015,
    "base_currency": "BTC"
  },
  "usIn": 1612272393029966,
  "usOut": 1612272393030246,
  "usDiff": 280,
  "testnet": false
}

Retrieves information about instrument

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  base_currency string The underlying currency being traded.
  ›  block_trade_commission number Block Trade commission for instrument
  ›  contract_size integer Contract size for instrument
  ›  counter_currency string Counter currency for the instrument.
  ›  creation_timestamp integer The time when the instrument was first created (milliseconds since the UNIX epoch)
  ›  expiration_timestamp integer The time when the instrument will expire (milliseconds since the UNIX epoch)
  ›  future_type string Future type (only for futures)
  ›  instrument_id integer Instrument ID
  ›  instrument_name string Unique instrument identifier
  ›  is_active boolean Indicates if the instrument can currently be traded.
  ›  kind string Instrument kind: "future", "option", "future_combo", "option_combo"
  ›  leverage integer Maximal leverage for instrument, for futures only
  ›  maker_commission number Maker commission for instrument
  ›  min_trade_amount number Minimum amount for trading. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  option_type string The option type (only for options)
  ›  price_index string Name of price index that is used for this instrument
  ›  quote_currency string The currency in which the instrument prices are quoted.
  ›  settlement_currency string Settlement currency for the instrument.
  ›  settlement_period string The settlement period.
  ›  strike number The strike value. (only for options)
  ›  taker_commission number Taker commission for instrument
  ›  tick_size number specifies minimal price change and, as follows, the number of decimal places for instrument prices

/public/get_instruments

curl -X GET "https://test.deribit.com/api/v2/public/get_instruments?currency=BTC&expired=false&kind=future" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7617,
  "method" : "public/get_instruments",
  "params" : {
    "currency" : "BTC",
    "kind" : "future",
    "expired" : false
  }
};
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" : 7617,
  "method" : "public/get_instruments",
  "params" : {
    "currency" : "BTC",
    "kind" : "future",
    "expired" : False
  }
}

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": 7617,
  "result": [
    {
      "tick_size": 0.01,
      "taker_commission": 0.0005,
      "settlement_period": "week",
      "quote_currency": "USD",
      "settlement_currency": "BTC",
      "counter_currency": "USD",
      "price_index": "btc_usd",
      "min_trade_amount": 1,
      "maker_commission": 0.0001,
      "leverage": 100,
      "kind": "future",
      "future_type": "reversed",
      "is_active": true,
      "instrument_name": "BTC-26JUL19",
      "expiration_timestamp": 1564153200000,
      "creation_timestamp": 1563522420000,
      "contract_size": 10,
      "base_currency": "BTC"
    },
    {
      "tick_size": 0.01,
      "taker_commission": 0.0005,
      "settlement_period": "perpetual",
      "quote_currency": "USD",
      "settlement_currency": "BTC",
      "counter_currency": "USD",
      "price_index": "btc_usd",
      "min_trade_amount": 1,
      "maker_commission": 0.0001,
      "leverage": 100,
      "kind": "future",
      "future_type": "reversed",
      "is_active": true,
      "instrument_name": "BTC-PERPETUAL",
      "expiration_timestamp": 32503734000000,
      "creation_timestamp": 1554806122000,
      "contract_size": 10,
      "base_currency": "BTC"
    }
  ]
}

Retrieves available trading instruments. This method can be used to see which instruments are available for trading, or which instruments have recently expired.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
kind false string future
option
future_combo
option_combo
Instrument kind, if not provided instruments of all kinds are considered
expired false boolean Set to true to show recently expired instruments instead of active ones.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  base_currency string The underlying currency being traded.
  ›  block_trade_commission number Block Trade commission for instrument
  ›  contract_size integer Contract size for instrument
  ›  counter_currency string Counter currency for the instrument.
  ›  creation_timestamp integer The time when the instrument was first created (milliseconds since the UNIX epoch)
  ›  expiration_timestamp integer The time when the instrument will expire (milliseconds since the UNIX epoch)
  ›  future_type string Future type (only for futures)
  ›  instrument_id integer Instrument ID
  ›  instrument_name string Unique instrument identifier
  ›  is_active boolean Indicates if the instrument can currently be traded.
  ›  kind string Instrument kind: "future", "option", "future_combo", "option_combo"
  ›  leverage integer Maximal leverage for instrument, for futures only
  ›  maker_commission number Maker commission for instrument
  ›  min_trade_amount number Minimum amount for trading. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  option_type string The option type (only for options)
  ›  price_index string Name of price index that is used for this instrument
  ›  quote_currency string The currency in which the instrument prices are quoted.
  ›  settlement_currency string Settlement currency for the instrument.
  ›  settlement_period string The settlement period.
  ›  strike number The strike value. (only for options)
  ›  taker_commission number Taker commission for instrument
  ›  tick_size number specifies minimal price change and, as follows, the number of decimal places for instrument prices

/public/get_last_settlements_by_currency

curl -X GET "https://test.deribit.com/api/v2/public/get_last_settlements_by_currency?count=2&currency=BTC&type=delivery" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 4497,
  "method" : "public/get_last_settlements_by_currency",
  "params" : {
    "currency" : "BTC",
    "type" : "delivery",
    "count" : 2
  }
};
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" : 4497,
  "method" : "public/get_last_settlements_by_currency",
  "params" : {
    "currency" : "BTC",
    "type" : "delivery",
    "count" : 2
  }
}

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": 4497,
  "result": {
    "settlements": [
      {
        "type": "delivery",
        "timestamp": 1550242800013,
        "session_profit_loss": 4.703907906,
        "profit_loss": -0.427669766,
        "position": 64,
        "mark_price": 0.121679828,
        "instrument_name": "BTC-15FEB19-4000-P",
        "index_price": 3566.08
      },
      {
        "type": "delivery",
        "timestamp": 1550242800013,
        "session_profit_loss": 3.135938604,
        "profit_loss": -2.539278115,
        "position": 206,
        "mark_price": 0,
        "instrument_name": "BTC-15FEB19-4000-C",
        "index_price": 3566.08
      }
    ],
    "continuation": "29XjjMM7Zc6U4oytmV27f7a6YRb5aSdVijwfuYhHRTLphugjRf1edP8uGLo3w2mWKV23QgrxsmenRGqzucc7"
  }
}

Retrieves historical settlement, delivery and bankruptcy events coming from all instruments within given currency.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
type false string settlement
delivery
bankruptcy
Settlement type
count false integer Number of requested items, default - 20
continuation false string Continuation token for pagination
search_start_timestamp false integer The latest timestamp to return result for (milliseconds since the UNIX epoch)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  continuation string Continuation token for pagination.
  ›  settlements array of object
  ›    ›  funded number funded amount (bankruptcy only)
  ›    ›  funding number funding (in base currency ; settlement for perpetual product only)
  ›    ›  index_price number underlying index price at time of event (in quote currency; settlement and delivery only)
  ›    ›  instrument_name string instrument name (settlement and delivery only)
  ›    ›  mark_price number mark price for at the settlement time (in quote currency; settlement and delivery only)
  ›    ›  position number position size (in quote currency; settlement and delivery only)
  ›    ›  profit_loss number profit and loss (in base currency; settlement and delivery only)
  ›    ›  session_bankrupcy number value of session bankrupcy (in base currency; bankruptcy only)
  ›    ›  session_profit_loss number total value of session profit and losses (in base currency)
  ›    ›  session_tax number total amount of paid taxes/fees (in base currency; bankruptcy only)
  ›    ›  session_tax_rate number rate of paid texes/fees (in base currency; bankruptcy only)
  ›    ›  socialized number the amount of the socialized losses (in base currency; bankruptcy only)
  ›    ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  type string The type of settlement. settlement, delivery or bankruptcy.

/public/get_last_settlements_by_instrument

curl -X GET "https://test.deribit.com/api/v2/public/get_last_settlements_by_instrument?count=1&instrument_name=BTC-22FEB19&type=settlement" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5482,
  "method" : "public/get_last_settlements_by_instrument",
  "params" : {
    "instrument_name" : "BTC-22FEB19",
    "type" : "settlement",
    "count" : 1
  }
};
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" : 5482,
  "method" : "public/get_last_settlements_by_instrument",
  "params" : {
    "instrument_name" : "BTC-22FEB19",
    "type" : "settlement",
    "count" : 1
  }
}

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": 5482,
  "result": {
    "settlements": [
      {
        "type": "settlement",
        "timestamp": 1550502000023,
        "session_profit_loss": 0.116509752,
        "profit_loss": -9.999999999886402e-10,
        "position": 240,
        "mark_price": 3578.16,
        "instrument_name": "BTC-22FEB19",
        "index_price": 3796.43
      }
    ],
    "continuation": "2Z7mdtavzYvfuyYcHkJXvPTr9ZSMsEzM3sLCH7AbYEDd1AzTXY2hnhegQDiaP1TtU4b5iSJZ4"
  }
}

Retrieves historical public settlement, delivery and bankruptcy events filtered by instrument name.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
type false string settlement
delivery
bankruptcy
Settlement type
count false integer Number of requested items, default - 20
continuation false string Continuation token for pagination
search_start_timestamp false integer The latest timestamp to return result for (milliseconds since the UNIX epoch)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  continuation string Continuation token for pagination.
  ›  settlements array of object
  ›    ›  funded number funded amount (bankruptcy only)
  ›    ›  funding number funding (in base currency ; settlement for perpetual product only)
  ›    ›  index_price number underlying index price at time of event (in quote currency; settlement and delivery only)
  ›    ›  instrument_name string instrument name (settlement and delivery only)
  ›    ›  mark_price number mark price for at the settlement time (in quote currency; settlement and delivery only)
  ›    ›  position number position size (in quote currency; settlement and delivery only)
  ›    ›  profit_loss number profit and loss (in base currency; settlement and delivery only)
  ›    ›  session_bankrupcy number value of session bankrupcy (in base currency; bankruptcy only)
  ›    ›  session_profit_loss number total value of session profit and losses (in base currency)
  ›    ›  session_tax number total amount of paid taxes/fees (in base currency; bankruptcy only)
  ›    ›  session_tax_rate number rate of paid texes/fees (in base currency; bankruptcy only)
  ›    ›  socialized number the amount of the socialized losses (in base currency; bankruptcy only)
  ›    ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  type string The type of settlement. settlement, delivery or bankruptcy.

/public/get_last_trades_by_currency

curl -X GET "https://test.deribit.com/api/v2/public/get_last_trades_by_currency?count=1&currency=BTC" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9290,
  "method" : "public/get_last_trades_by_currency",
  "params" : {
    "currency" : "BTC",
    "count" : 1
  }
};
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" : 9290,
  "method" : "public/get_last_trades_by_currency",
  "params" : {
    "currency" : "BTC",
    "count" : 1
  }
}

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": 9290,
    "result": {
        "trades": [
            {
                "trade_seq": 36798,
                "trade_id": "277976",
                "timestamp": 1590476708320,
                "tick_direction": 2,
                "price": 8767.08,
                "mark_price": 8829.7,
                "instrument_name": "BTC-PERPETUAL",
                "index_price": 8878.53,
                "direction": "sell",
                "amount": 100
            }
        ],
        "has_more": true
    }
}

Retrieve the latest trades that have occurred for instruments in a specific currency symbol.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
kind false string future
option
future_combo
option_combo
combo
any
Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
start_id false string The ID number of the first trade to be returned
end_id false string The ID number of the last trade to be returned
count false integer Number of requested items, default - 10
include_old false boolean Include trades older than a few recent days, default - false
sorting false string asc
desc
default
Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of 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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/public/get_last_trades_by_currency_and_time

curl -X GET "https://test.deribit.com/api/v2/public/get_last_trades_by_currency_and_time?count=1&currency=BTC&end_timestamp=1590480022768&start_timestamp=1590470022768" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 1469,
  "method" : "public/get_last_trades_by_currency_and_time",
  "params" : {
    "currency" : "BTC",
    "start_timestamp" : 1590470022768,
    "end_timestamp" : 1590480022768,
    "count" : 1
  }
};
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" : 1469,
  "method" : "public/get_last_trades_by_currency_and_time",
  "params" : {
    "currency" : "BTC",
    "start_timestamp" : 1590470022768,
    "end_timestamp" : 1590480022768,
    "count" : 1
  }
}

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": 1469,
    "result": {
        "trades": [
            {
                "trade_seq": 3471,
                "trade_id": "48077291",
                "timestamp": 1590470616101,
                "tick_direction": 2,
                "price": 0.032,
                "mark_price": 0.04070324,
                "iv": 74.74,
                "instrument_name": "BTC-25SEP20-6000-P",
                "index_price": 8899.93,
                "direction": "sell",
                "amount": 0.5
            }
        ],
        "has_more": true
    }
}

Retrieve the latest trades that have occurred for instruments in a specific currency symbol and within given time range.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
kind false string future
option
future_combo
option_combo
combo
any
Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
start_timestamp true integer The earliest timestamp to return result for (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result for (milliseconds since the UNIX epoch)
count false integer Number of requested items, default - 10
include_old false boolean Include trades older than a few recent days, default - false
sorting false string asc
desc
default
Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of 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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/public/get_last_trades_by_instrument

curl -X GET "https://test.deribit.com/api/v2/public/get_last_trades_by_instrument?count=1&instrument_name=BTC-PERPETUAL" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9267,
  "method" : "public/get_last_trades_by_instrument",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "count" : 1
  }
};
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" : 9267,
  "method" : "public/get_last_trades_by_instrument",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "count" : 1
  }
}

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": 9267,
    "result": {
        "trades": [
            {
                "trade_seq": 36798,
                "trade_id": "277976",
                "timestamp": 1590476708320,
                "tick_direction": 2,
                "price": 8767.08,
                "mark_price": 8829.7,
                "instrument_name": "BTC-PERPETUAL",
                "index_price": 8878.53,
                "direction": "sell",
                "amount": 100
            }
        ],
        "has_more": true
    }
}

Retrieve the latest trades that have occurred for a specific instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_seq false integer The sequence number of the first trade to be returned
end_seq false integer The sequence number of the last trade to be returned
count false integer Number of requested items, default - 10
include_old false boolean Include trades older than a few recent days, default - false
sorting false string asc
desc
default
Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of 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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/public/get_last_trades_by_instrument_and_time

curl -X GET "https://test.deribit.com/api/v2/public/get_last_trades_by_instrument_and_time?count=1&end_timestamp=1590480022768&instrument_name=ETH-PERPETUAL" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3983,
  "method" : "public/get_last_trades_by_instrument_and_time",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "end_timestamp" : 1590480022768,
    "count" : 1
  }
};
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" : 3983,
  "method" : "public/get_last_trades_by_instrument_and_time",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "end_timestamp" : 1590480022768,
    "count" : 1
  }
}

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": 3983,
    "result": {
        "trades": [
            {
                "trade_seq": 1966031,
                "trade_id": "ETH-2696055",
                "timestamp": 1590479408216,
                "tick_direction": 0,
                "price": 203.6,
                "mark_price": 203.41,
                "instrument_name": "ETH-PERPETUAL",
                "index_price": 203.45,
                "direction": "buy",
                "amount": 10
            }
        ],
        "has_more": true
    }
}

Retrieve the latest trades that have occurred for a specific instrument and within given time range.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_timestamp true integer The earliest timestamp to return result for (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result for (milliseconds since the UNIX epoch)
count false integer Number of requested items, default - 10
include_old false boolean Include trades older than a few recent days, default - false
sorting false string asc
desc
default
Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of 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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/public/get_mark_price_history

curl -X GET "https://test.deribit.com/api/v2/public/get_mark_price_history?end_timestamp=1609376810000&instrument_name=BTC-25JUN21-50000-C&start_timestamp=1609376800000" \
-H "Content-Type: application/json"
var msg = 
{
  "id" : 1,
  "method" : "public/get_mark_price_history",
  "params" : {
    "instrument_name" : "BTC-25JUN21-50000-C",
    "start_timestamp" : 1609376800000,
    "end_timestamp" : 1609376810000
  },
  "jsonrpc" : "2.0"
};
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 = \
{
  "id" : 1,
  "method" : "public/get_mark_price_history",
  "params" : {
    "instrument_name" : "BTC-25JUN21-50000-C",
    "start_timestamp" : 1609376800000,
    "end_timestamp" : 1609376810000
  },
  "jsonrpc" : "2.0"
}

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": 25,
  "result": [
    [1608142381229,0.5165791606037885],
    [1608142380231,0.5165737855432504],
    [1608142379227,0.5165768236356326]
  ]
}

Public request for 5min history of markprice values for the instrument. For now the markprice history is available only for a subset of options which take part in the volatility index calculations. All other instruments, futures and perpetuals will return empty list.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_timestamp true integer The earliest timestamp to return result for (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result for (milliseconds since the UNIX epoch)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array Markprice history values as an array of arrays with 2 values each. The inner values correspond to the timestamp in ms and the markprice itself.

/public/get_order_book

curl -X GET "https://test.deribit.com/api/v2/public/get_order_book?depth=5&instrument_name=BTC-PERPETUAL" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8772,
  "method" : "public/get_order_book",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "depth" : 5
  }
};
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" : 8772,
  "method" : "public/get_order_book",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "depth" : 5
  }
}

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":8772,
    "result":{
        "timestamp":1550757626706,
        "stats":{
            "volume":93.35589552,
            "price_change": 0.6913,
            "low":3940.75,
            "high":3976.25
        },
        "state":"open",
        "settlement_price":3925.85,
        "open_interest":45.27600333464605,
        "min_price":3932.22,
        "max_price":3971.74,
        "mark_price":3931.97,
        "last_price":3955.75,
        "instrument_name":"BTC-PERPETUAL",
        "index_price":3910.46,
        "funding_8h":0.00455263,
        "current_funding":0.00500063,
        "change_id":474988,
        "bids":[
            [
                3955.75,
                30.0
            ],
            [
                3940.75,
                102020.0
            ],
            [
                3423.0,
                42840.0
            ]
        ],
        "best_bid_price":3955.75,
        "best_bid_amount":30.0,
        "best_ask_price":0.0,
        "best_ask_amount":0.0,
        "asks":[

        ]
    }
}

Retrieves the order book, along with other market values for a given instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string The instrument name for which to retrieve the order book, see public/get_instruments to obtain instrument names.
depth false number The number of entries to return for bids and asks.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  ask_iv number (Only for option) implied volatility for best ask
  ›  asks array of [price, amount] List of asks
  ›  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
  ›  bids array of [price, amount] List of bids
  ›  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
  ›    ›  volume_usd number Volume in usd (futures only)
  ›  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)

/public/get_order_book_by_instrument_id

curl -X GET "https://test.deribit.com/api/v2/public/get_order_book_by_instrument_id?instrument_id=42&depth=42.0" \
-H "Content-Type: application/json"
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_order_book_by_instrument_id",
     "id": 42,
     "params": {
        "instrument_id": 42,
        "depth": 42.0}
    };
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",
     "method": "public/get_order_book_by_instrument_id",
     "id": 42,
     "params": {
        "instrument_id": 42,
        "depth": 42.0}
    }

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":8772,
    "result":{
        "timestamp":1550757626706,
        "stats":{
            "volume":93.35589552,
            "price_change": 0.6913,
            "low":3940.75,
            "high":3976.25
        },
        "state":"open",
        "settlement_price":3925.85,
        "open_interest":45.27600333464605,
        "min_price":3932.22,
        "max_price":3971.74,
        "mark_price":3931.97,
        "last_price":3955.75,
        "instrument_name":"BTC-PERPETUAL",
        "index_price":3910.46,
        "funding_8h":0.00455263,
        "current_funding":0.00500063,
        "change_id":474988,
        "bids":[
            [
                3955.75,
                30.0
            ],
            [
                3940.75,
                102020.0
            ],
            [
                3423.0,
                42840.0
            ]
        ],
        "best_bid_price":3955.75,
        "best_bid_amount":30.0,
        "best_ask_price":0.0,
        "best_ask_amount":0.0,
        "asks":[

        ]
    }
}

Retrieves the order book, along with other market values for a given instrument ID.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_id true integer The instrument ID for which to retrieve the order book, see public/get_instruments to obtain instrument IDs.
depth false number The number of entries to return for bids and asks.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  ask_iv number (Only for option) implied volatility for best ask
  ›  asks array of [price, amount] List of asks
  ›  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
  ›  bids array of [price, amount] List of bids
  ›  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
  ›    ›  volume_usd number Volume in usd (futures only)
  ›  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)

/public/get_rfqs

curl -X GET "https://test.deribit.com/api/v2/public/get_rfqs?currency=BTC&kind=future" \
-H "Content-Type: application/json"
var msg = 
{
  "id" : 1,
  "method" : "public/get_rfqs",
  "params" : {
    "currency" : "BTC",
    "kind" : "future"
  },
  "jsonrpc" : "2.0"
};
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 = \
{
  "id" : 1,
  "method" : "public/get_rfqs",
  "params" : {
    "currency" : "BTC",
    "kind" : "future"
  },
  "jsonrpc" : "2.0"
}

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": 1,
  "result": [
    {
      "traded_volume": 0,
      "amount": 10,
      "side": "buy",
      "last_rfq_tstamp": 1634816611595,
      "instrument_name": "BTC-PERPETUAL"
    }
  ]
}

Retrieve active RFQs for instruments in given currency.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
kind false string future
option
future_combo
option_combo
Instrument kind, if not provided instruments of all kinds are considered

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  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.
  ›  instrument_name string Unique instrument identifier
  ›  last_rfq_timestamp integer The timestamp of last RFQ (milliseconds since the Unix epoch)
  ›  side string Side - buy or sell
  ›  traded_volume number Volume traded since last RFQ

/public/get_trade_volumes

curl -X GET "https://test.deribit.com/api/v2/public/get_trade_volumes?" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 6387,
  "method" : "public/get_trade_volumes"
};
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" : 6387,
  "method" : "public/get_trade_volumes"
}

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": 6387,
  "result": [
    {
      "puts_volume": 48,
      "futures_volume": 6.25578452,
      "currency": "BTC",
      "calls_volume": 145
    },
    {
      "puts_volume": 122.65,
      "futures_volume": 374.392173,
      "currency": "ETH",
      "calls_volume": 37.4
    }
  ]
}

Retrieves aggregated 24h trade volumes for different instrument types and currencies.

Try in API console

Parameters

Parameter Required Type Enum Description
extended false boolean Request for extended statistics. Including also 7 and 30 days volumes (default false)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  calls_volume number Total 24h trade volume for call options.
  ›  calls_volume_30d number Total 30d trade volume for call options.
  ›  calls_volume_7d number Total 7d trade volume for call options.
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  futures_volume number Total 24h trade volume for futures.
  ›  futures_volume_30d number Total 30d trade volume for futures.
  ›  futures_volume_7d number Total 7d trade volume for futures.
  ›  puts_volume number Total 24h trade volume for put options.
  ›  puts_volume_30d number Total 30d trade volume for put options.
  ›  puts_volume_7d number Total 7d trade volume for put options.

/public/get_tradingview_chart_data

curl -X GET "https://test.deribit.com/api/v2/public/get_tradingview_chart_data?end_timestamp=1554376800000&instrument_name=BTC-5APR19&resolution=30&start_timestamp=1554373800000" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 833,
  "method" : "public/get_tradingview_chart_data",
  "params" : {
    "instrument_name" : "BTC-5APR19",
    "start_timestamp" : 1554373800000,
    "end_timestamp" : 1554376800000,
    "resolution" : "30"
  }
};
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" : 833,
  "method" : "public/get_tradingview_chart_data",
  "params" : {
    "instrument_name" : "BTC-5APR19",
    "start_timestamp" : 1554373800000,
    "end_timestamp" : 1554376800000,
    "resolution" : "30"
  }
}

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": 833,
  "result": {
    "volume": [
      19.007942601,
      20.095877981
    ],
    "cost": [
      19000.0,
      23400.0
    ],
    "ticks": [
      1554373800000,
      1554375600000
    ],
    "status": "ok",
    "open": [
      4963.42,
      4986.29
    ],
    "low": [
      4728.94,
      4726.6
    ],
    "high": [
      5185.45,
      5250.87
    ],
    "close": [
      5052.95,
      5013.59
    ]
  },
  "usIn": 1554381680742493,
  "usOut": 1554381680742698,
  "usDiff": 205,
  "testnet": false
}

Publicly available market data used to generate a TradingView candle chart.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_timestamp true integer The earliest timestamp to return result for (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result for (milliseconds since the UNIX epoch)
resolution true string 1
3
5
10
15
30
60
120
180
360
720
1D
Chart bars resolution given in full minutes or keyword 1D (only some specific resolutions are supported)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  close array of number List of prices at close (one per candle)
  ›  cost array of number List of cost bars (volume in quote currency, one per candle)
  ›  high array of number List of highest price levels (one per candle)
  ›  low array of number List of lowest price levels (one per candle)
  ›  open array of number List of prices at open (one per candle)
  ›  status string Status of the query: ok or no_data
  ›  ticks array of integer Values of the time axis given in milliseconds since UNIX epoch
  ›  volume array of number List of volume bars (in base currency, one per candle)

/public/get_volatility_index_data

curl -X GET "https://test.deribit.com/api/v2/public/get_volatility_index_data?currency=BTC&end_timestamp=1599376800000&resolution=60&start_timestamp=1599373800000" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 833,
  "method" : "public/get_volatility_index_data",
  "params" : {
    "currency" : "BTC",
    "start_timestamp" : 1599373800000,
    "end_timestamp" : 1599376800000,
    "resolution" : "60"
  }
};
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" : 833,
  "method" : "public/get_volatility_index_data",
  "params" : {
    "currency" : "BTC",
    "start_timestamp" : 1599373800000,
    "end_timestamp" : 1599376800000,
    "resolution" : "60"
  }
}

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":5,
  "result":
  {
    "data": [
      [1598019300000,0.210084879,0.212860821,0.210084879,0.212860821],
      [1598019360000,0.212869011,0.212987527,0.212869011,0.212987527],
      [1598019420000,0.212987723,0.212992597,0.212987723,0.212992597]
    ],
    "continuation": null
  }
}

Public market data request for volatility index candles.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
start_timestamp true integer The earliest timestamp to return result for (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result for (milliseconds since the UNIX epoch)
resolution true string 1
60
3600
43200
1D
Time resolution given in full seconds or keyword 1D (only some specific resolutions are supported)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object Volatility index candles.
  ›  continuation integer Continuation - to be used as the end_timestamp parameter on the next request. NULL when no continuation.
  ›  data array Candles as an array of arrays with 5 values each. The inner values correspond to the timestamp in ms, open, high, low, and close values of the volatility index correspondingly.

/public/ticker

curl -X GET "https://test.deribit.com/api/v2/public/ticker?instrument_name=BTC-PERPETUAL" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8106,
  "method" : "public/ticker",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL"
  }
};
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" : 8106,
  "method" : "public/ticker",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL"
  }
}

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": 8106,
  "result": {
    "best_ask_amount": 53040,
    "best_ask_price": 36290,
    "best_bid_amount": 4600,
    "best_bid_price": 36289.5,
    "current_funding": 0,
    "estimated_delivery_price": 36297.02,
    "funding_8h": 0.00002203,
    "index_price": 36297.02,
    "instrument_name": "BTC-PERPETUAL",
    "interest_value": 1.7362511643080387,
    "last_price": 36289.5,
    "mark_price": 36288.31,
    "max_price": 36833.4,
    "min_price": 35744.73,
    "open_interest": 502231260,
    "settlement_price": 36169.49,
    "state": "open",
    "stats": {
      "high": 36824.5,
      "low": 35213.5,
      "price_change": 0.2362,
      "volume": 7831.26548117,
      "volume_usd": 282615600
    },
    "timestamp": 1623059681955
  }
}

Get ticker for an instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result 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
  ›  estimated_delivery_price number Estimated delivery price for the market. For more details, see Contract Specification > General Documentation > Expiration Price
  ›  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)
  ›  interest_value number Value used to calculate realized_funding in positions (perpetual 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
  ›    ›  volume_usd number Volume in usd (futures only)
  ›  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)

Trading

/private/buy

curl -X GET "https://test.deribit.com/api/v2/private/buy?amount=40&instrument_name=ETH-PERPETUAL&label=market0000234&type=market" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5275,
  "method" : "private/buy",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "amount" : 40,
    "type" : "market",
    "label" : "market0000234"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 5275,
  "method" : "private/buy",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "amount" : 40,
    "type" : "market",
    "label" : "market0000234"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 5275,
  "result": {
    "trades": [
      {
        "trade_seq": 1966056,
        "trade_id": "ETH-2696083",
        "timestamp": 1590483938456,
        "tick_direction": 0,
        "state": "filled",
        "self_trade": false,
        "reduce_only": false,
        "price": 203.3,
        "post_only": false,
        "order_type": "market",
        "order_id": "ETH-584849853",
        "matching_id": null,
        "mark_price": 203.28,
        "liquidity": "T",
        "label": "market0000234",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 203.33,
        "fee_currency": "ETH",
        "fee": 0.00014757,
        "direction": "buy",
        "amount": 40
      }
    ],
    "order": {
      "web": false,
      "time_in_force": "good_til_cancelled",
      "replaced": false,
      "reduce_only": false,
      "profit_loss": 0.00022929,
      "price": 207.3,
      "post_only": false,
      "order_type": "market",
      "order_state": "filled",
      "order_id": "ETH-584849853",
      "max_show": 40,
      "last_update_timestamp": 1590483938456,
      "label": "market0000234",
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "filled_amount": 40,
      "direction": "buy",
      "creation_timestamp": 1590483938456,
      "commission": 0.00014757,
      "average_price": 203.3,
      "api": true,
      "amount": 40
    }
  }
}

Places a buy order for an instrument.

Try in API console

Parameters

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
take_limit
market
stop_market
take_market
market_limit
trailing_stop
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
good_til_day
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
  • "good_til_day" - unfilled order remains in order book till the end of the trading session
  • "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.

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
trigger_price false number Trigger price, required for trigger orders only (Stop-loss or Take-profit orders)
trigger_offset false number The maximum deviation from the price peak beyond which the order will be triggered
trigger false string index_price
mark_price
last_price
Defines the trigger type. Required for "Stop-Loss", "Take-Profit" and "Trailing" trigger orders
advanced false string usd
implv
Advanced option order type. (Only for options)
mmp false boolean Order MMP flag, only for order_type 'limit'
valid_until false integer Timestamp, when provided server will start processing request in Matching Engine only before given timestamp, in other cases timed_out error will be responded. Remember that the given timestamp should be consistent with the server's time, use /public/time method to obtain current server time.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  order 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.
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  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 trigger order has been triggered
  ›    ›  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
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  price number Price in base currency
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "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.
  ›    ›  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 The name of the application that placed the order on behalf of the user (optional).
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  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.
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trades array of object
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  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.
  ›    ›  api boolean true if user order was created with API
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  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)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  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
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)

/private/sell

curl -X GET "https://test.deribit.com/api/v2/private/sell?amount=123&instrument_name=ETH-PERPETUAL&price=1.45610000000000013642e%2B02&trigger=last_price&trigger_price=145&type=stop_limit" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2148,
  "method" : "private/sell",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "amount" : 123,
    "type" : "stop_limit",
    "price" : 145.61,
    "trigger_price" : 145,
    "trigger" : "last_price"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 2148,
  "method" : "private/sell",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "amount" : 123,
    "type" : "stop_limit",
    "price" : 145.61,
    "trigger_price" : 145,
    "trigger" : "last_price"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 2148,
  "result": {
    "trades": [],
    "order": {
      "triggered": false,
      "trigger": "last_price",
      "time_in_force": "good_til_cancelled",
      "trigger_price": 145,
      "reduce_only": false,
      "profit_loss": 0,
      "price": 145.61,
      "post_only": false,
      "order_type": "stop_limit",
      "order_state": "untriggered",
      "order_id": "ETH-SLTS-28",
      "max_show": 123,
      "last_update_timestamp": 1550659803407,
      "label": "",
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "direction": "sell",
      "creation_timestamp": 1550659803407,
      "api": true,
      "amount": 123
    }
  }
}

Places a sell order for an instrument.

Try in API console

Parameters

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
take_limit
market
stop_market
take_market
market_limit
trailing_stop
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
good_til_day
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
  • "good_til_day" - unfilled order remains in order book till the end of the trading session
  • "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 above 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.

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
trigger_price false number Trigger price, required for trigger orders only (Stop-loss or Take-profit orders)
trigger_offset false number The maximum deviation from the price peak beyond which the order will be triggered
trigger false string index_price
mark_price
last_price
Defines the trigger type. Required for "Stop-Loss", "Take-Profit" and "Trailing" trigger orders
advanced false string usd
implv
Advanced option order type. (Only for options)
mmp false boolean Order MMP flag, only for order_type 'limit'
valid_until false integer Timestamp, when provided server will start processing request in Matching Engine only before given timestamp, in other cases timed_out error will be responded. Remember that the given timestamp should be consistent with the server's time, use /public/time method to obtain current server time.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  order 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.
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  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 trigger order has been triggered
  ›    ›  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
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  price number Price in base currency
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "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.
  ›    ›  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 The name of the application that placed the order on behalf of the user (optional).
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  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.
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trades array of object
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  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.
  ›    ›  api boolean true if user order was created with API
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  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)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  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
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)

/private/edit

curl -X GET "https://test.deribit.com/api/v2/private/edit?advanced=implv&amount=4&order_id=438994&price=222" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3725,
  "method" : "private/edit",
  "params" : {
    "order_id" : "438994",
    "amount" : 4,
    "price" : 222,
    "advanced" : "implv"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 3725,
  "method" : "private/edit",
  "params" : {
    "order_id" : "438994",
    "amount" : 4,
    "price" : 222,
    "advanced" : "implv"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 3725,
  "result": {
    "trades": [],
    "order": {
      "time_in_force": "good_til_cancelled",
      "reduce_only": false,
      "profit_loss": 0,
      "price": 0.1448,
      "post_only": false,
      "order_type": "limit",
      "order_state": "open",
      "order_id": "438994",
      "max_show": 4,
      "last_update_timestamp": 1550585797677,
      "label": "",
      "is_liquidation": false,
      "instrument_name": "BTC-22FEB19-3500-C",
      "implv": 222,
      "filled_amount": 0,
      "direction": "buy",
      "creation_timestamp": 1550585741277,
      "commission": 0,
      "average_price": 0,
      "api": false,
      "amount": 4,
      "advanced": "implv"
    }
  }
}

Change price, amount and/or other properties of an order.

Try in API console

Parameters

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.

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)
trigger_price false number Trigger price, required for trigger orders only (Stop-loss or Take-profit orders)
trigger_offset false number The maximum deviation from the price peak beyond which the order will be triggered
mmp false boolean Order MMP flag, only for order_type 'limit'
valid_until false integer Timestamp, when provided server will start processing request in Matching Engine only before given timestamp, in other cases timed_out error will be responded. Remember that the given timestamp should be consistent with the server's time, use /public/time method to obtain current server time.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  order 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.
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  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 trigger order has been triggered
  ›    ›  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
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  price number Price in base currency
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "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.
  ›    ›  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 The name of the application that placed the order on behalf of the user (optional).
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  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.
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trades array of object
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  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.
  ›    ›  api boolean true if user order was created with API
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  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)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  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
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)

/private/edit_by_label

curl -X GET "https://test.deribit.com/api/v2/private/edit_by_label?amount=150&instrument_name=BTC-PERPETUAL&label=i_love_deribit&price=50111" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "method" : "private/edit_by_label",
  "id" : 9,
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "label" : "i_love_deribit",
    "amount" : 150,
    "price" : 50111
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "method" : "private/edit_by_label",
  "id" : 9,
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "label" : "i_love_deribit",
    "amount" : 150,
    "price" : 50111
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 9,
  "result": {
    "trades": [],
    "order": {
      "web": false,
      "time_in_force": "good_til_cancelled",
      "replaced": true,
      "reduce_only": false,
      "profit_loss": 0.0,
      "price": 50111.0,
      "post_only": false,
      "order_type": "limit",
      "order_state": "open",
      "order_id": "94166",
      "max_show": 150,
      "last_update_timestamp": 1616155550773,
      "label": "i_love_deribit",
      "is_liquidation": false,
      "instrument_name": "BTC-PERPETUAL",
      "filled_amount": 0,
      "direction": "buy",
      "creation_timestamp": 1616155547764,
      "commission": 0.0,
      "average_price": 0.0,
      "api": true,
      "amount": 150
    }
  }
}

Change price, amount and/or other properties of an order with given label. It works only when there is one open order with this label

Try in API console

Parameters

Parameter Required Type Enum Description
label false string user defined label for the order (maximum 64 characters)
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
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.

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)
trigger_price false number Trigger price, required for trigger orders only (Stop-loss or Take-profit orders)
mmp false boolean Order MMP flag, only for order_type 'limit'
valid_until false integer Timestamp, when provided server will start processing request in Matching Engine only before given timestamp, in other cases timed_out error will be responded. Remember that the given timestamp should be consistent with the server's time, use /public/time method to obtain current server time.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  order 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.
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  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 trigger order has been triggered
  ›    ›  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
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  price number Price in base currency
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "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.
  ›    ›  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 The name of the application that placed the order on behalf of the user (optional).
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  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.
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trades array of object
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  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.
  ›    ›  api boolean true if user order was created with API
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  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)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  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
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)

/private/cancel

curl -X GET "https://test.deribit.com/api/v2/private/cancel?order_id=ETH-SLIS-12" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 4214,
  "method" : "private/cancel",
  "params" : {
    "order_id" : "ETH-SLIS-12"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 4214,
  "method" : "private/cancel",
  "params" : {
    "order_id" : "ETH-SLIS-12"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 4214,
  "result": {
    "triggered": false,
    "trigger": "index_price",
    "time_in_force": "good_til_cancelled",
    "trigger_price": 144.73,
    "reduce_only": false,
    "profit_loss": 0,
    "price": "market_price",
    "post_only": false,
    "order_type": "stop_market",
    "order_state": "untriggered",
    "order_id": "ETH-SLIS-12",
    "max_show": 5,
    "last_update_timestamp": 1550575961291,
    "label": "",
    "is_liquidation": false,
    "instrument_name": "ETH-PERPETUAL",
    "direction": "sell",
    "creation_timestamp": 1550575961291,
    "api": false,
    "amount": 5
  }
}

Cancel an order, specified by order id

Try in API console

Parameters

Parameter Required Type Enum Description
order_id true string The order id

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result 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.
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  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 trigger order has been triggered
  ›  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
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  price number Price in base currency
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "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.
  ›  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 The name of the application that placed the order on behalf of the user (optional).
  ›  label string User defined label (up to 64 characters)
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  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.
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".

/private/cancel_all

curl -X GET "https://test.deribit.com/api/v2/private/cancel_all?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8748,
  "method" : "private/cancel_all",
  "params" : {

  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 8748,
  "method" : "private/cancel_all",
  "params" : {

  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 8748,
  "result": 37
}

This method cancels all users orders and trigger orders within all currencies and instrument kinds.

Try in API console

Parameters

Parameter Required Type Enum Description
detailed false boolean When detailed is set to true output format is changed. See description. Default: false

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result number Total number of successfully cancelled orders

/private/cancel_all_by_currency

curl -X GET "https://test.deribit.com/api/v2/private/cancel_all_by_currency?currency=BTC&kind=option" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5663,
  "method" : "private/cancel_all_by_currency",
  "params" : {
    "currency" : "BTC",
    "kind" : "option"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 5663,
  "method" : "private/cancel_all_by_currency",
  "params" : {
    "currency" : "BTC",
    "kind" : "option"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 5663,
  "result": 3
}

Cancels all orders by currency, optionally filtered by instrument kind and/or order type.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
kind false string future
option
future_combo
option_combo
combo
any
Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
type false string all
limit
trigger_all
stop
take
trailing_stop
Order type - limit, stop, take, trigger_all or all, default - all
detailed false boolean When detailed is set to true output format is changed. See description. Default: false

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result number Total number of successfully cancelled orders

/private/cancel_all_by_instrument

curl -X GET "https://test.deribit.com/api/v2/private/cancel_all_by_instrument?instrument_name=ETH-22FEB19-120-P&type=all" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 4122,
  "method" : "private/cancel_all_by_instrument",
  "params" : {
    "instrument_name" : "ETH-22FEB19-120-P",
    "type" : "all"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 4122,
  "method" : "private/cancel_all_by_instrument",
  "params" : {
    "instrument_name" : "ETH-22FEB19-120-P",
    "type" : "all"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 4122,
  "result": 7
}

Cancels all orders by instrument, optionally filtered by order type.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
type false string all
limit
trigger_all
stop
take
trailing_stop
Order type - limit, stop, take, trigger_all or all, default - all
detailed false boolean When detailed is set to true output format is changed. See description. Default: false
include_combos false boolean When set to true orders in combo instruments affecting given position will also be cancelled. Default: false

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result number Total number of successfully cancelled orders

/private/cancel_by_label

curl -X GET "https://test.deribit.com/api/v2/private/cancel_by_label?label=label" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "id" : 47,
  "method" : "private/cancel_by_label",
  "params" : {
    "label" : "label"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "id" : 47,
  "method" : "private/cancel_by_label",
  "params" : {
    "label" : "label"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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":47,
  "result":4
}

Cancels orders by label. All user's orders (trigger orders too), with given label are canceled in all currencies or in one given currency (in this case currency queue is used)

Try in API console

Parameters

Parameter Required Type Enum Description
label true string user defined label for the order (maximum 64 characters)
currency false string BTC
ETH
SOL
USDC
The currency symbol

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result number Total number of successfully cancelled orders

/private/close_position

curl -X GET "https://test.deribit.com/api/v2/private/close_position?instrument_name=ETH-PERPETUAL&price=1.45169999999999987494e%2B02&type=limit" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 6130,
  "method" : "private/close_position",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "type" : "limit",
    "price" : 145.17
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 6130,
  "method" : "private/close_position",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "type" : "limit",
    "price" : 145.17
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 6130,
  "result": {
    "trades": [
      {
        "trade_seq": 1966068,
        "trade_id": "ETH-2696097",
        "timestamp": 1590486335742,
        "tick_direction": 0,
        "state": "filled",
        "self_trade": false,
        "reduce_only": true,
        "price": 202.8,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-584864807",
        "matching_id": null,
        "mark_price": 202.79,
        "liquidity": "T",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 202.86,
        "fee_currency": "ETH",
        "fee": 0.00007766,
        "direction": "sell",
        "amount": 21
      }
    ],
    "order": {
      "web": false,
      "time_in_force": "good_til_cancelled",
      "replaced": false,
      "reduce_only": true,
      "profit_loss": -0.00025467,
      "price": 198.75,
      "post_only": false,
      "order_type": "limit",
      "order_state": "filled",
      "order_id": "ETH-584864807",
      "max_show": 21,
      "last_update_timestamp": 1590486335742,
      "label": "",
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "filled_amount": 21,
      "direction": "sell",
      "creation_timestamp": 1590486335742,
      "commission": 0.00007766,
      "average_price": 202.8,
      "api": true,
      "amount": 21
    }
  }
}

Makes closing position reduce only order .

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
type true string limit
market
The order type
price false number Optional price for limit order.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  order 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.
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  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 trigger order has been triggered
  ›    ›  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
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  price number Price in base currency
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "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.
  ›    ›  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 The name of the application that placed the order on behalf of the user (optional).
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  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.
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trades array of object
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  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.
  ›    ›  api boolean true if user order was created with API
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  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)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  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
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)

/private/get_margins

curl -X GET "https://test.deribit.com/api/v2/private/get_margins?amount=10000&instrument_name=BTC-PERPETUAL&price=3725" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7,
  "method" : "private/get_margins",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "amount" : 10000,
    "price" : 3725
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 7,
  "method" : "private/get_margins",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "amount" : 10000,
    "price" : 3725
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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:

{
    "jsonrpc": "2.0",
    "result": {
        "buy": 0.01681367,
        "max_price": 42.0,
        "min_price": 42.0,
        "sell": 0.01680479
    }
}

Get margins for given instrument, amount and price.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
amount true number Amount, integer for future, float for option. 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 true number Price

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  buy number Margin when buying
  ›  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.
  ›  sell number Margin when selling

/private/get_mmp_config

curl -X GET "https://test.deribit.com/api/v2/private/get_mmp_config?currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7859,
  "method" : "private/get_mmp_config",
  "params" : {
    "currency" : "BTC"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 7859,
  "method" : "private/get_mmp_config",
  "params" : {
    "currency" : "BTC"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 7859,
  "result": {
    "currency": "BTC",
    "interval": 60,
    "frozen_time": 0,
    "quantity_limit": 0.5
  }
}

Get current config for MMP

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  delta_limit number Delta limit
  ›  frozen_time integer MMP frozen time in seconds, if set to 0 manual reset is required
  ›  interval integer MMP Interval in seconds, if set to 0 MMP is disabled
  ›  quantity_limit number Quantity limit

/private/get_open_orders_by_currency

curl -X GET "https://test.deribit.com/api/v2/private/get_open_orders_by_currency?currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 1953,
  "method" : "private/get_open_orders_by_currency",
  "params" : {
    "currency" : "BTC"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 1953,
  "method" : "private/get_open_orders_by_currency",
  "params" : {
    "currency" : "BTC"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 1953,
    "result": [
        {
            "time_in_force": "good_til_cancelled",
            "reduce_only": false,
            "profit_loss": 0,
            "price": 0.0028,
            "post_only": false,
            "order_type": "limit",
            "order_state": "open",
            "order_id": "146062",
            "max_show": 10,
            "last_update_timestamp": 1550050597036,
            "label": "",
            "is_liquidation": false,
            "instrument_name": "BTC-15FEB19-3250-P",
            "filled_amount": 0,
            "direction": "buy",
            "creation_timestamp": 1550050597036,
            "commission": 0,
            "average_price": 0,
            "api": true,
            "amount": 10
        }
    ]
}

Retrieves list of user's open orders.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
kind false string future
option
future_combo
option_combo
Instrument kind, if not provided instruments of all kinds are considered
type false string all
limit
trigger_all
stop_all
stop_limit
stop_market
take_all
take_limit
take_market
trailing_all
trailing_stop
Order type, default - all

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of 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.
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  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 trigger order has been triggered
  ›  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
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  price number Price in base currency
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "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.
  ›  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 The name of the application that placed the order on behalf of the user (optional).
  ›  label string User defined label (up to 64 characters)
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  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.
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".

/private/get_open_orders_by_instrument

curl -X GET "https://test.deribit.com/api/v2/private/get_open_orders_by_instrument?instrument_name=ETH-22FEB19-120-C" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8442,
  "method" : "private/get_open_orders_by_instrument",
  "params" : {
    "instrument_name" : "ETH-22FEB19-120-C"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 8442,
  "method" : "private/get_open_orders_by_instrument",
  "params" : {
    "instrument_name" : "ETH-22FEB19-120-C"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 8442,
    "result": [
        {
            "time_in_force": "good_til_cancelled",
            "reduce_only": false,
            "profit_loss": 0,
            "price": 0.135,
            "post_only": false,
            "order_type": "limit",
            "order_state": "open",
            "order_id": "ETH-252017",
            "max_show": 10,
            "last_update_timestamp": 1550050594882,
            "label": "",
            "is_liquidation": false,
            "instrument_name": "ETH-22FEB19-120-C",
            "filled_amount": 0,
            "direction": "sell",
            "creation_timestamp": 1550050594882,
            "commission": 0,
            "average_price": 0,
            "api": true,
            "amount": 10
        }
    ]
}

Retrieves list of user's open orders within given Instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
type false string all
limit
trigger_all
stop_all
stop_limit
stop_market
take_all
take_limit
take_market
trailing_all
trailing_stop
Order type, default - all

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of 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.
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  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 trigger order has been triggered
  ›  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
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  price number Price in base currency
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "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.
  ›  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 The name of the application that placed the order on behalf of the user (optional).
  ›  label string User defined label (up to 64 characters)
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  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.
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".

/private/get_order_history_by_currency

curl -X GET "https://test.deribit.com/api/v2/private/get_order_history_by_currency?count=1&currency=BTC&kind=future" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9305,
  "method" : "private/get_order_history_by_currency",
  "params" : {
    "currency" : "BTC",
    "kind" : "future",
    "count" : 1
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9305,
  "method" : "private/get_order_history_by_currency",
  "params" : {
    "currency" : "BTC",
    "kind" : "future",
    "count" : 1
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 9305,
  "result": [
    {
      "time_in_force": "good_til_cancelled",
      "reduce_only": false,
      "profit_loss": 0,
      "price": 3886.5,
      "post_only": false,
      "order_type": "limit",
      "order_state": "filled",
      "order_id": "146475",
      "max_show": 40,
      "last_update_timestamp": 1550661808761,
      "label": "",
      "is_liquidation": false,
      "instrument_name": "BTC-PERPETUAL",
      "filled_amount": 40,
      "direction": "buy",
      "creation_timestamp": 1550661808761,
      "commission": 0.00000547,
      "average_price": 3659.8,
      "api": true,
      "amount": 40
    }
  ]
}

Retrieves history of orders that have been partially or fully filled.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
kind false string future
option
future_combo
option_combo
combo
any
Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
count false integer Number of requested items, default - 20
offset false integer The offset for pagination, default - 0
include_old false boolean Include in result orders older than 2 days, default - false
include_unfilled false boolean Include in result fully unfilled closed orders, default - false

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of 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.
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  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 trigger order has been triggered
  ›  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
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  price number Price in base currency
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "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.
  ›  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 The name of the application that placed the order on behalf of the user (optional).
  ›  label string User defined label (up to 64 characters)
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  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.
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".

/private/get_order_history_by_instrument

curl -X GET "https://test.deribit.com/api/v2/private/get_order_history_by_instrument?count=1&instrument_name=BTC-PERPETUAL" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 1032,
  "method" : "private/get_order_history_by_instrument",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "count" : 1
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 1032,
  "method" : "private/get_order_history_by_instrument",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "count" : 1
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 1032,
  "result": [
    {
      "time_in_force": "good_til_cancelled",
      "reduce_only": false,
      "profit_loss": 0,
      "price": 3886.5,
      "post_only": false,
      "order_type": "limit",
      "order_state": "filled",
      "order_id": "146475",
      "max_show": 40,
      "last_update_timestamp": 1550661808761,
      "label": "",
      "is_liquidation": false,
      "instrument_name": "BTC-PERPETUAL",
      "filled_amount": 40,
      "direction": "buy",
      "creation_timestamp": 1550661808761,
      "commission": 0.00000547,
      "average_price": 3659.8,
      "api": true,
      "amount": 40
    }
  ]
}

Retrieves history of orders that have been partially or fully filled.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
count false integer Number of requested items, default - 20
offset false integer The offset for pagination, default - 0
include_old false boolean Include in result orders older than 2 days, default - false
include_unfilled false boolean Include in result fully unfilled closed orders, default - false

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of 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.
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  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 trigger order has been triggered
  ›  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
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  price number Price in base currency
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "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.
  ›  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 The name of the application that placed the order on behalf of the user (optional).
  ›  label string User defined label (up to 64 characters)
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  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.
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".

/private/get_order_margin_by_ids

curl -X GET "https://test.deribit.com/api/v2/private/get_order_margin_by_ids?ids=%5B%22ETH-349280%22%2C%22ETH-349279%22%2C%22ETH-349278%22%5D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5625,
  "method" : "private/get_order_margin_by_ids",
  "params" : {
    "ids" : [
      "ETH-349280",
      "ETH-349279",
      "ETH-349278"
    ]
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 5625,
  "method" : "private/get_order_margin_by_ids",
  "params" : {
    "ids" : [
      "ETH-349280",
      "ETH-349279",
      "ETH-349278"
    ]
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 5625,
  "result": [
    {
      "order_id": "ETH-349278",
      "initial_margin": 0.00091156
    },
    {
      "order_id": "ETH-349279",
      "initial_margin": 0
    },
    {
      "order_id": "ETH-349280",
      "initial_margin": 0
    }
  ]
}

Retrieves initial margins of given orders

Try in API console

Parameters

Parameter Required Type Enum Description
ids true array Ids of orders

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  initial_margin number Initial margin of order, in base currency
  ›  order_id string Unique order identifier

/private/get_order_state

curl -X GET "https://test.deribit.com/api/v2/private/get_order_state?order_id=ETH-331562" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 4316,
  "method" : "private/get_order_state",
  "params" : {
    "order_id" : "ETH-331562"
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 4316,
  "method" : "private/get_order_state",
  "params" : {
    "order_id" : "ETH-331562"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 4316,
  "result": {
    "time_in_force": "good_til_cancelled",
    "reduce_only": false,
    "profit_loss": 0.051134,
    "price": 118.94,
    "post_only": false,
    "order_type": "limit",
    "order_state": "filled",
    "order_id": "ETH-331562",
    "max_show": 37,
    "last_update_timestamp": 1550219810944,
    "label": "",
    "is_liquidation": false,
    "instrument_name": "ETH-PERPETUAL",
    "filled_amount": 37,
    "direction": "sell",
    "creation_timestamp": 1550219749176,
    "commission": 0.000031,
    "average_price": 118.94,
    "api": false,
    "amount": 37
  }
}

Retrieve the current state of an order.

Try in API console

Parameters

Parameter Required Type Enum Description
order_id true string The order id

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result 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.
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  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 trigger order has been triggered
  ›  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
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  price number Price in base currency
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "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.
  ›  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 The name of the application that placed the order on behalf of the user (optional).
  ›  label string User defined label (up to 64 characters)
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  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.
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".

/private/get_trigger_order_history

curl -X GET "https://test.deribit.com/api/v2/private/get_trigger_order_history?count=10&currency=ETH" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2552,
  "method" : "private/get_trigger_order_history",
  "params" : {
    "currency" : "ETH",
    "count" : 10
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 2552,
  "method" : "private/get_trigger_order_history",
  "params" : {
    "currency" : "ETH",
    "count" : 10
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 2192,
  "result": [
    {
      "trigger": "index",
      "timestamp": 1555918941451,
      "trigger_price": 5285,
      "trigger_order_id": "SLIS-103",
      "order_state": "new",
      "request": "trigger:order",
      "price": 5179.28,
      "order_id": "671473",
      "offset": 277,
      "instrument_name": "BTC-PERPETUAL",
      "amount": 10,
      "direction": "buy"
    }
  ]
}

Retrieves detailed log of the user's trigger orders.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
instrument_name false string Instrument name
count false integer Number of requested items, default - 20
continuation false string Continuation token for pagination

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  continuation string Continuation token for pagination.
  ›  entries array of object
  ›    ›  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.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  order_id string Unique order identifier
  ›    ›  order_state string Order state: "triggered", "cancelled", or "rejected" with rejection reason (e.g. "rejected:reduce_direction").
  ›    ›  order_type string Requested order type: "limit or "market"
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only boolean true for reduce-only orders only
  ›    ›  request string Type of last request performed on the trigger order by user or system. "cancel" - when order was cancelled, "trigger:order" - when trigger order spawned market or limit order after being triggered
  ›    ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  trigger_order_id string Id of the user order used for the trigger-order reference before triggering
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)

/private/get_user_trades_by_currency

curl -X GET "https://test.deribit.com/api/v2/private/get_user_trades_by_currency?count=2&currency=ETH&start_id=ETH-34066" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9367,
  "method" : "private/get_user_trades_by_currency",
  "params" : {
    "currency" : "ETH",
    "start_id" : "ETH-34066",
    "count" : 2
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9367,
  "method" : "private/get_user_trades_by_currency",
  "params" : {
    "currency" : "ETH",
    "start_id" : "ETH-34066",
    "count" : 2
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 9367,
  "result": {
    "trades": [
      {
        "underlying_price": 204.5,
        "trade_seq": 3,
        "trade_id": "ETH-2696060",
        "timestamp": 1590480363130,
        "tick_direction": 2,
        "state": "filled",
        "self_trade": false,
        "reduce_only": false,
        "price": 0.361,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-584827850",
        "matching_id": null,
        "mark_price": 0.364585,
        "liquidity": "T",
        "iv": 0,
        "instrument_name": "ETH-29MAY20-130-C",
        "index_price": 203.72,
        "fee_currency": "ETH",
        "fee": 0.002,
        "direction": "sell",
        "amount": 5
      },
      {
        "underlying_price": 204.82,
        "trade_seq": 3,
        "trade_id": "ETH-2696062",
        "timestamp": 1590480416119,
        "tick_direction": 0,
        "state": "filled",
        "self_trade": false,
        "reduce_only": false,
        "price": 0.015,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-584828229",
        "matching_id": null,
        "mark_price": 0.000596,
        "liquidity": "T",
        "iv": 352.91,
        "instrument_name": "ETH-29MAY20-140-P",
        "index_price": 204.06,
        "fee_currency": "ETH",
        "fee": 0.002,
        "direction": "buy",
        "amount": 5
      }
    ],
    "has_more": true
  }
}

Retrieve the latest user trades that have occurred for instruments in a specific currency symbol.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
kind false string future
option
future_combo
option_combo
combo
any
Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
start_id false string The ID number of the first trade to be returned
end_id false string The ID number of the last trade to be returned
count false integer Number of requested items, default - 10
include_old false boolean Include trades older than a few recent days, default - false
sorting false string asc
desc
default
Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  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.
  ›    ›  api boolean true if user order was created with API
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  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)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  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
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)

/private/get_user_trades_by_currency_and_time

curl -X GET "https://test.deribit.com/api/v2/private/get_user_trades_by_currency_and_time?count=2&currency=BTC&end_timestamp=1510480630731&start_timestamp=1590480630731" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9292,
  "method" : "private/get_user_trades_by_currency_and_time",
  "params" : {
    "currency" : "BTC",
    "start_timestamp" : 1590480630731,
    "end_timestamp" : 1510480630731,
    "count" : 2
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9292,
  "method" : "private/get_user_trades_by_currency_and_time",
  "params" : {
    "currency" : "BTC",
    "start_timestamp" : 1590480630731,
    "end_timestamp" : 1510480630731,
    "count" : 2
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 9292,
  "result": {
    "trades": [
      {
        "underlying_price": 8994.95,
        "trade_seq": 1,
        "trade_id": "48078936",
        "timestamp": 1590480620145,
        "tick_direction": 1,
        "state": "filled",
        "self_trade": false,
        "reduce_only": false,
        "price": 0.028,
        "post_only": false,
        "order_type": "limit",
        "order_id": "4008699030",
        "matching_id": null,
        "mark_price": 0.03135383,
        "liquidity": "M",
        "iv": 38.51,
        "instrument_name": "BTC-27MAY20-8750-C",
        "index_price": 8993.47,
        "fee_currency": "BTC",
        "fee": 0.0004,
        "direction": "sell",
        "amount": 1
      },
      {
        "trade_seq": 299513,
        "trade_id": "47958936",
        "timestamp": 1589923311862,
        "tick_direction": 2,
        "state": "filled",
        "self_trade": false,
        "reduce_only": false,
        "price": 9681.5,
        "post_only": false,
        "order_type": "limit",
        "order_id": "3993343822",
        "matching_id": null,
        "mark_price": 9684,
        "liquidity": "M",
        "instrument_name": "BTC-26JUN20",
        "index_price": 9679.48,
        "fee_currency": "BTC",
        "fee": -2.1e-7,
        "direction": "buy",
        "amount": 10
      }
    ],
    "has_more": false
  }
}

Retrieve the latest user trades that have occurred for instruments in a specific currency symbol and within given time range.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
SOL
USDC
The currency symbol
kind false string future
option
future_combo
option_combo
combo
any
Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
start_timestamp true integer The earliest timestamp to return result for (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result for (milliseconds since the UNIX epoch)
count false integer Number of requested items, default - 10
include_old false boolean Include trades older than a few recent days, default - false
sorting false string asc
desc
default
Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  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.
  ›    ›  api boolean true if user order was created with API
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  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)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  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
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)

/private/get_user_trades_by_instrument

curl -X GET "https://test.deribit.com/api/v2/private/get_user_trades_by_instrument?count=2&instrument_name=ETH-PERPETUAL&start_seq=1966042" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5728,
  "method" : "private/get_user_trades_by_instrument",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "start_seq" : 1966042,
    "count" : 2
  }
};
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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 5728,
  "method" : "private/get_user_trades_by_instrument",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "start_seq" : 1966042,
    "count" : 2
  }
}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       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": 5728,
  "result": {
    "trades": [
      {
        "trade_seq": 1966042,
        "trade_id": "ETH-2696068",
        "timestamp": 1590480712800,
        "tick_direction": 3,
        "state": "filled",
        "self_trade": false,
        "reduce_only": false,
        "price": 203.8,
        "post_only": false,
        "order_type": "market",
        "order_id": "ETH-584830574",
        "matching_id": null,
        "mark_price": 203.78,
        "liquidity": "T",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 203.89,
        "fee_currency": "ETH",
        "fee": 0.00036801,
        "direction": "buy",
        "amount": 100
      },
      {
        "trade_seq": 1966043,
        "trade_id": "ETH-2696069",
        "timestamp": 1590480724473,
        "tick_direction": 3,
        "state": "filled",
        "self_trade": false,
        "reduce_only": false,
        "price": 203.8,
        "post_only": false,
        "order_type": "market",
        "order_id": "ETH-584830695",
        "matching_id": null,
        "mark_price": 203.81,
        "liquidity": "T",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 203.92,
        "fee_currency": "ETH",
        "fee": 0.00036801,
        "direction": "sell",
        "amount": 100
      }
    ],
    "has_more": true
  }
}

Retrieve the latest user trades that have occurred for a specific instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_seq false integer The sequence number of the first trade to be returned
end_seq false integer The sequence number of the last trade to be returned
count false integer Number of requested items, default - 10
include_old false boolean Include trades older than a few recent days, default - false
sorting false string asc
desc
default
Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  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.
  ›    ›  api boolean true if user order was created with API
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  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)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  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
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  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 (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)

/private/get_user_trades_by_instrument_and_time

curl -X GET "https://test.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time?count=2&end_timestamp=1590480872894&instrument_name=BTC-PERPETUAL&start_timestamp=1590470872894" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 276,
  "method" : "private/get_user_trades_by_instrument_and_time",
  "params" : {
    "instrument_name" : "BTC-P