NAV Show example code
shell javascript python

Deribit API v2.1.1

Overview

Deribit provides three different interfaces to access the API:

Deribit features a 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 the 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 environment 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-25MAR23, BTC-5AUG23 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-25MAR23-420-C, BTC-5AUG23-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.

In Linear Options d is used as a decimal point for decimal strikes.

Example: For XRP_USDC-30JUN23-0d625-C strike is 0.625.

Rate Limits

Rate limits are described in 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 specification 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",
      "replaced": false,
      "reduce_only": false,
      "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_rebalance": false,
      "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 the number of canceled orders there is a 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 a returned response with field security_key_authorization_required set to true. When that happens the client is required to resend 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 an error occurrs, the request needs to be repeated without authorization_data to obtain a 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 available 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 achieved 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 a dedicated authorization method, which harnesses 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 milliseconds. 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 omitted 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 milliseconds. 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 omitted, 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, the 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 the 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 the name provided by the user, then generates tokens and binds them with the session. Access is granted during session lifetime. It allows users to reconnect to the server and reuse assigned tokens (before their expiration time). Note that only 16 sessions are allowed per user - when the limit is reached, the 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 an 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 scopes.

Creating/editing/removing API Keys

Creating, editing and removing API Keys is available only with access tokens with scope account:read_write. Additionally when the methods of the API Key management are called with access token with scope set than server ensures that we do allow to create/remove/manage (or show client secrets in case of private/list_api_keys) the keys up to the same level of the scopes as calling set from access token. If not error scope_exceeded (code: 13403) is returned.

JSON-RPC over websocket

Websocket is the preferred 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",
      "enabled_features": [],
      "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
  ›  access_token string
  ›  enabled_features array of string List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval
  ›  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 a token for a 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
  ›  access_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 a token for a 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
  ›  access_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 the 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.

Scope: account:read_write

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.

Scope: account:read_write

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.

Scope: account:read

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,
      "mark_iv": 80,
      "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,
      "mark_iv": 80,
      "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
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
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 Optional (only for derivatives). 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_iv number (Only for option) implied volatility for mark price
  ›  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
  ›  open_interest number Optional (only for derivatives). 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 the 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_notional number Volume in quote currency (futures and spots only)
  ›  volume_usd number Volume in USD

/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,
      "mark_price": 80,
      "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 Optional (only for derivatives). 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_iv number (Only for option) implied volatility for mark price
  ›  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
  ›  open_interest number Optional (only for derivatives). 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 the 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_notional number Volume in quote currency (futures and spots only)
  ›  volume_usd number Volume in USD

/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
  ›  in_cross_collateral_pool boolean true if the currency is part of the cross collateral pool
  ›  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
  }
}

Retrieves delivery prices for then given index

Try in API console

Parameters

Parameter Required Type Enum Description
index_name true string ada_usd
algo_usd
avax_usd
bch_usd
btc_usd
doge_usd
dot_usd
eth_usd
link_usd
ltc_usd
matic_usd
near_usd
shib_usd
sol_usd
trx_usd
uni_usd
usdc_usd
xrp_usd
ada_usdc
bch_usdc
algo_usdc
avax_usdc
btc_usdc
doge_usdc
dot_usdc
bch_usdc
eth_usdc
link_usdc
ltc_usdc
matic_usdc
near_usdc
shib_usdc
sol_usdc
trx_usdc
uni_usdc
xrp_usdc
ada_usdt
algo_usdt
avax_usdt
bch_usdt
bnb_usdt
bnb_usdt
btc_usdt
btc_usdt
doge_usdt
dot_usdt
eth_usdt
eth_usdt
link_usdt
ltc_usdt
luna_usdt
matic_usdt
near_usdt
shib_usdt
sol_usdt
trx_usdt
uni_usdt
xrp_usdt
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 from (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result from (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 from (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result from (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
USDC
USDT
EURR		 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
USDC
USDT
EURR		 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
algo_usd
avax_usd
bch_usd
btc_usd
doge_usd
dot_usd
eth_usd
link_usd
ltc_usd
matic_usd
near_usd
shib_usd
sol_usd
trx_usd
uni_usd
usdc_usd
xrp_usd
ada_usdc
bch_usdc
algo_usdc
avax_usdc
btc_usdc
doge_usdc
dot_usdc
bch_usdc
eth_usdc
link_usdc
ltc_usdc
matic_usdc
near_usdc
shib_usdc
sol_usdc
trx_usdc
uni_usdc
xrp_usdc
ada_usdt
algo_usdt
avax_usdt
bch_usdt
bnb_usdt
bnb_usdt
btc_usdt
btc_usdt
doge_usdt
dot_usdt
eth_usdt
eth_usdt
link_usdt
ltc_usdt
luna_usdt
matic_usdt
near_usdt
shib_usdt
sol_usdt
trx_usdt
uni_usdt
xrp_usdt
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-13JAN23-16000-P" \
-H "Content-Type: application/json"

var msg = 
{
  "method" : "public/get_instrument",
  "params" : {
    "instrument_name" : "BTC-13JAN23-16000-P"
  },
  "jsonrpc" : "2.0",
  "id" : 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 = \
{
  "method" : "public/get_instrument",
  "params" : {
    "instrument_name" : "BTC-13JAN23-16000-P"
  },
  "jsonrpc" : "2.0",
  "id" : 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": 2,
  "result": {
    "tick_size": 0.0005,
    "tick_size_steps": [
      {
        "above_price": 120,
        "tick_size": 0.001
      },
      {
        "above_price": 200,
        "tick_size": 0.003
      }
    ],
    "taker_commission": 0.0003,
    "strike": 16000,
    "settlement_period": "week",
    "settlement_currency": "BTC",
    "rfq": false,
    "quote_currency": "BTC",
    "price_index": "btc_usd",
    "option_type": "put",
    "min_trade_amount": 0.1,
    "maker_commission": 0.0003,
    "kind": "option",
    "is_active": true,
    "instrument_name": "BTC-13JAN23-16000-P",
    "instrument_id": 144613,
    "expiration_timestamp": 1673596800000,
    "creation_timestamp": 1671696002000,
    "counter_currency": "USD",
    "contract_size": 1,
    "block_trade_tick_size": 0.0001,
    "block_trade_min_trade_amount": 25,
    "block_trade_commission": 0.00015,
    "base_currency": "BTC"
  }
}

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.
  ›  block_trade_min_trade_amount number Minimum amount for block trading.
  ›  block_trade_tick_size number Specifies minimal price change for block trading.
  ›  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)(field is deprecated and will be removed in the future, instrument_type should be used instead).
  ›  instrument_id integer Instrument ID
  ›  instrument_name string Unique instrument identifier
  ›  instrument_type string Type of the instrument. linear or reversed
  ›  is_active boolean Indicates if the instrument can currently be traded.
  ›  kind string Instrument kind: "future", "option", "spot", "future_combo", "option_combo"
  ›  maker_commission number Maker commission for instrument.
  ›  max_leverage integer Maximal leverage for instrument (only for futures).
  ›  max_liquidation_commission number Maximal liquidation trade commission for instrument (only for futures).
  ›  min_trade_amount number Minimum amount for trading. For perpetual and futures - in USD units, for options it is the 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.
  ›  rfq boolean Whether or not RFQ is active on the instrument.
  ›  settlement_currency string Optional (not added for spot). Settlement currency for the instrument.
  ›  settlement_period string Optional (not added for spot). 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.
  ›  tick_size_steps object
  ›    ›  above_price number The price from which the increased tick size applies
  ›    ›  tick_size number Tick size to be used above the price. It must be multiple of the minimum tick size.

/public/get_instruments

curl -X GET "https://test.deribit.com/api/v2/public/get_instruments?currency=BTC&kind=future" \
-H "Content-Type: application/json"

var msg = 
{
  "method" : "public/get_instruments",
  "params" : {
    "currency" : "BTC",
    "kind" : "future"
  },
  "jsonrpc" : "2.0",
  "id" : 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 = \
{
  "method" : "public/get_instruments",
  "params" : {
    "currency" : "BTC",
    "kind" : "future"
  },
  "jsonrpc" : "2.0",
  "id" : 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": 1,
  "result": [
    {
      "tick_size": 2.5,
      "tick_size_steps": [],
      "taker_commission": 0.0005,
      "settlement_period": "month",
      "settlement_currency": "BTC",
      "rfq": false,
      "quote_currency": "USD",
      "price_index": "btc_usd",
      "min_trade_amount": 10,
      "max_liquidation_commission": 0.0075,
      "max_leverage": 50,
      "maker_commission": 0,
      "kind": "future",
      "is_active": true,
      "instrument_name": "BTC-29SEP23",
      "instrument_id": 138583,
      "instrument_type": "reversed",
      "expiration_timestamp": 1695974400000,
      "creation_timestamp": 1664524802000,
      "counter_currency": "USD",
      "contract_size": 10,
      "block_trade_tick_size": 0.01,
      "block_trade_min_trade_amount": 200000,
      "block_trade_commission": 0.00025,
      "base_currency": "BTC"
    },
    {
      "tick_size": 0.5,
      "tick_size_steps": [],
      "taker_commission": 0.0005,
      "settlement_period": "perpetual",
      "settlement_currency": "BTC",
      "rfq": false,
      "quote_currency": "USD",
      "price_index": "btc_usd",
      "min_trade_amount": 10,
      "max_liquidation_commission": 0.0075,
      "max_leverage": 50,
      "maker_commission": 0,
      "kind": "future",
      "is_active": true,
      "instrument_name": "BTC-PERPETUAL",
      "instrument_id": 124972,
      "instrument_type": "reversed",
      "expiration_timestamp": 32503708800000,
      "creation_timestamp": 1534167754000,
      "counter_currency": "USD",
      "contract_size": 10,
      "block_trade_tick_size": 0.01,
      "block_trade_min_trade_amount": 200000,
      "block_trade_commission": 0.00025,
      "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
USDC
USDT
EURR
any		 The currency symbol or "any" for all
kind false string future
option
spot
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.
  ›  block_trade_min_trade_amount number Minimum amount for block trading.
  ›  block_trade_tick_size number Specifies minimal price change for block trading.
  ›  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)(field is deprecated and will be removed in the future, instrument_type should be used instead).
  ›  instrument_id integer Instrument ID
  ›  instrument_name string Unique instrument identifier
  ›  instrument_type string Type of the instrument. linear or reversed
  ›  is_active boolean Indicates if the instrument can currently be traded.
  ›  kind string Instrument kind: "future", "option", "spot", "future_combo", "option_combo"
  ›  maker_commission number Maker commission for instrument.
  ›  max_leverage integer Maximal leverage for instrument (only for futures).
  ›  max_liquidation_commission number Maximal liquidation trade commission for instrument (only for futures).
  ›  min_trade_amount number Minimum amount for trading. For perpetual and futures - in USD units, for options it is the 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.
  ›  rfq boolean Whether or not RFQ is active on the instrument.
  ›  settlement_currency string Optional (not added for spot). Settlement currency for the instrument.
  ›  settlement_period string Optional (not added for spot). 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.
  ›  tick_size_steps object
  ›    ›  above_price number The price from which the increased tick size applies
  ›    ›  tick_size number Tick size to be used above the price. It must be multiple of the minimum tick size.

/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 a given currency.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 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 from (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_bankruptcy number value of session bankruptcy (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 taxes/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 from (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_bankruptcy number value of session bankruptcy (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 taxes/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
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
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 of the first trade to be returned. Number for BTC trades, or hyphen name in ex. "ETH-15" # "ETH_USDC-16"
end_id false string The ID of the last trade to be returned. Number for BTC trades, or hyphen name in ex. "ETH-15" # "ETH_USDC-16"
start_timestamp false integer The earliest timestamp to return result from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp false integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
count false integer Number of requested items, default - 10
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 the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  block_trade_leg_count integer Block trade leg count - when trade was part of a block trade
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  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 a given time range.

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
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 from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp true integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
count false integer Number of requested items, default - 10
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 the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  block_trade_leg_count integer Block trade leg count - when trade was part of a block trade
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  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
start_timestamp false integer The earliest timestamp to return result from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp false integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
count false integer Number of requested items, default - 10
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 the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  block_trade_leg_count integer Block trade leg count - when trade was part of a block trade
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  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 a 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 from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp true integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
count false integer Number of requested items, default - 10
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 the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  block_trade_leg_count integer Block trade leg count - when trade was part of a block trade
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  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 an 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 from (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result from (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 integer 1
5
10
20
50
100
1000
10000		 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 the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  settlement_price number Optional (not added for spot). 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=1" \
-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": 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",
     "method": "public/get_order_book_by_instrument_id",
     "id": 42,
     "params": {
        "instrument_id": 42,
        "depth": 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":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 integer 1
5
10
20
50
100
1000
10000		 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 the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  settlement_price number Optional (not added for spot). 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
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
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 the 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_supported_index_names

curl -X GET "https://test.deribit.com/api/v2/public/get_supported_index_names?type=all" \
-H "Content-Type: application/json"

var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_supported_index_names",
     "id": 42,
     "params": {
        "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 () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
    {"jsonrpc": "2.0",
     "method": "public/get_supported_index_names",
     "id": 42,
     "params": {
        "type": "all"}
    }

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": 25718,
  "result": [
    "btc_eth",
    "btc_usdc",
    "eth_usdc"
  ]
}

Retrieves the identifiers of all supported Price Indexes

Try in API console

Parameters

Parameter Required Type Enum Description
type false string all
spot
derivative		 Type of a cryptocurrency price index

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_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,
      "spot_volume": 11.1
    },
    {
      "puts_volume": 122.65,
      "futures_volume": 374.392173,
      "currency": "ETH",
      "calls_volume": 37.4,
      "spot_volume": 57.7
    }
  ]
}

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.
  ›  spot_volume number Total 24h trade for spot.
  ›  spot_volume_30d number Total 30d trade for spot.
  ›  spot_volume_7d number Total 7d trade for spot.

/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 from (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result from (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
USDC
USDT
EURR		 The currency symbol
start_timestamp true integer The earliest timestamp to return result from (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result from (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 the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  settlement_price number Optional (not added for spot). 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",
        "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,
      "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_rebalance": false,
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "filled_amount": 40,
      "direction": "buy",
      "creation_timestamp": 1590483938456,
      "average_price": 203.3,
      "api": true,
      "amount": 40
    }
  }
}

Places a buy order for an instrument.

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
amount false number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For linear futures it is the underlying base currency coin. For options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH. The amount is a mandatory parameter if contracts parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
contracts false number It represents the requested order size in contract units and can be passed instead of amount. The contracts is a mandatory parameter if amount parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
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 an order with advanced=usd, the field price should be the option price value in USD.

When adding an 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 the order book unmodified or the 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. Advanced USD orders are not supported for linear 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.
linked_order_type false string one_triggers_other
one_cancels_other
one_triggers_one_cancels_other

The type of the linked order.

  • "one_triggers_other" - Execution of primary order triggers the placement of one or more secondary orders.
  • "one_cancels_other" - The execution of one order in a pair automatically cancels the other, typically used to set a stop-loss and take-profit simultaneously.
  • "one_triggers_one_cancels_other" - The execution of a primary order triggers two secondary orders (a stop-loss and take-profit pair), where the execution of one secondary order cancels the other.
trigger_fill_condition false string first_hit
complete_fill
incremental

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
otoco_config false array of objects

List of trades to create or cancel when this order is filled.
  ›  amount false number It represents the requested trade size. For perpetual and futures the amount is in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH
  ›  direction true string buy
sell		 Direction of trade from the maker perspective
  ›  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 an order with advanced=usd, the field price should be the option price value in USD.

When adding an 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%
  ›  reduce_only false boolean If true, the order is considered reduce-only which is intended to only reduce a current position
  ›  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
  ›  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 (according to the direction of the order).

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 the order book unmodified or the request is rejected.

Only valid in combination with "post_only" set to true
  ›  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

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
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  api boolean true if created with API
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  primary_order_id string Unique order identifier
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  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.
  ›    ›  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.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  order_id string Unique order identifier
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  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.
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  trades array of object
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  api boolean true if user order was created with API
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  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)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  direction string Direction: buy, or sell
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  matching_id string Always null
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  post_only string true if user order is post-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
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)

/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,
      "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_rebalance": false,
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "direction": "sell",
      "creation_timestamp": 1550659803407,
      "api": true,
      "amount": 123
    }
  }
}

Places a sell order for an instrument.

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
amount false number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For linear futures it is the underlying base currency coin. For options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH. The amount is a mandatory parameter if contracts parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
contracts false number It represents the requested order size in contract units and can be passed instead of amount. The contracts is a mandatory parameter if amount parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
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 an order with advanced=usd, the field price should be the option price value in USD.

When adding an 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 the order book unmodified or the 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. Advanced USD orders are not supported for linear 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.
linked_order_type false string one_triggers_other
one_cancels_other
one_triggers_one_cancels_other

The type of the linked order.

  • "one_triggers_other" - Execution of primary order triggers the placement of one or more secondary orders.
  • "one_cancels_other" - The execution of one order in a pair automatically cancels the other, typically used to set a stop-loss and take-profit simultaneously.
  • "one_triggers_one_cancels_other" - The execution of a primary order triggers two secondary orders (a stop-loss and take-profit pair), where the execution of one secondary order cancels the other.
trigger_fill_condition false string first_hit
complete_fill
incremental

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
otoco_config false array of objects

List of trades to create or cancel when this order is filled.
  ›  amount false number It represents the requested trade size. For perpetual and futures the amount is in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH
  ›  direction true string buy
sell		 Direction of trade from the maker perspective
  ›  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 an order with advanced=usd, the field price should be the option price value in USD.

When adding an 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%
  ›  reduce_only false boolean If true, the order is considered reduce-only which is intended to only reduce a current position
  ›  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
  ›  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 (according to the direction of the order).

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 the order book unmodified or the request is rejected.

Only valid in combination with "post_only" set to true
  ›  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

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
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  api boolean true if created with API
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  primary_order_id string Unique order identifier
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  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.
  ›    ›  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.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  order_id string Unique order identifier
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  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.
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  trades array of object
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  api boolean true if user order was created with API
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  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)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  direction string Direction: buy, or sell
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  matching_id string Always null
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  post_only string true if user order is post-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
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)

/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,
      "price": 0.1448,
      "post_only": false,
      "order_type": "limit",
      "order_state": "open",
      "order_id": "438994",
      "max_show": 4,
      "last_update_timestamp": 1550585797677,
      "label": "",
      "is_rebalance": false,
      "is_liquidation": false,
      "instrument_name": "BTC-22FEB19-3500-C",
      "implv": 222,
      "filled_amount": 0,
      "direction": "buy",
      "creation_timestamp": 1550585741277,
      "average_price": 0,
      "api": false,
      "amount": 4,
      "advanced": "implv"
    }
  }
}

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

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
order_id true string The order id
amount false number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For linear futures it is the underlying base currency coin. For options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH. The amount is a mandatory parameter if contracts parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
contracts false number It represents the requested order size in contract units and can be passed instead of amount. The contracts is a mandatory parameter if amount parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
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 the order book unmodified or the 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
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  api boolean true if created with API
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  primary_order_id string Unique order identifier
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  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.
  ›    ›  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.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  order_id string Unique order identifier
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  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.
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  trades array of object
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  api boolean true if user order was created with API
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  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)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  direction string Direction: buy, or sell
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  matching_id string Always null
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  post_only string true if user order is post-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
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)

/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,
      "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_rebalance": false,
      "is_liquidation": false,
      "instrument_name": "BTC-PERPETUAL",
      "filled_amount": 0,
      "direction": "buy",
      "creation_timestamp": 1616155547764,
      "average_price": 0.0,
      "api": true,
      "amount": 150
    }
  }
}

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

Scope: trade:read_write

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 false number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For linear futures it is the underlying base currency coin. For options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH. The amount is a mandatory parameter if contracts parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
contracts false number It represents the requested order size in contract units and can be passed instead of amount. The contracts is a mandatory parameter if amount parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
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 the order book unmodified or the 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
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  api boolean true if created with API
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  primary_order_id string Unique order identifier
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  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.
  ›    ›  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.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  order_id string Unique order identifier
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  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.
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  trades array of object
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  api boolean true if user order was created with API
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  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)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  direction string Direction: buy, or sell
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  matching_id string Always null
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  post_only string true if user order is post-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
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)

/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,
    "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_rebalance": false,
    "is_liquidation": false,
    "instrument_name": "ETH-PERPETUAL",
    "direction": "sell",
    "creation_timestamp": 1550575961291,
    "api": false,
    "amount": 5
  }
}

Cancel an order, specified by order id

Scope: trade:read_write

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
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  original_order_type string Original order type. Optional field
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  api boolean true if created with API
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  primary_order_id string Unique order identifier
  ›  quote boolean If order is a quote. Present only if true.
  ›  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.
  ›  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.
  ›  instrument_name string Unique instrument identifier
  ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  direction string Direction: buy, or sell
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  post_only boolean true for post-only orders only
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  order_id string Unique order identifier
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  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.
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  web boolean true if created via Deribit frontend (optional)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).

/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.

Scope: trade:read_write

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
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.

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.

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
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
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.

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_pair

curl -X GET "https://test.deribit.com/api/v2/private/cancel_all_by_currency_pair?currency_pair=BTC_USD&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_pair",
  "params" : {
    "currency_pair" : "BTC_USD",
    "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_pair",
  "params" : {
    "currency_pair" : "BTC_USD",
    "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 pair, optionally filtered by instrument kind and/or order type.

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency_pair true string ada_usd
algo_usd
avax_usd
bch_usd
btc_usd
doge_usd
dot_usd
eth_usd
link_usd
ltc_usd
matic_usd
near_usd
shib_usd
sol_usd
trx_usd
uni_usd
usdc_usd
xrp_usd
ada_usdc
bch_usdc
algo_usdc
avax_usdc
btc_usdc
doge_usdc
dot_usdc
bch_usdc
eth_usdc
link_usdc
ltc_usdc
matic_usdc
near_usdc
shib_usdc
sol_usdc
trx_usdc
uni_usdc
xrp_usdc
ada_usdt
algo_usdt
avax_usdt
bch_usdt
bnb_usdt
bnb_usdt
btc_usdt
btc_usdt
doge_usdt
dot_usdt
eth_usdt
eth_usdt
link_usdt
ltc_usdt
luna_usdt
matic_usdt
near_usdt
shib_usdt
sol_usdt
trx_usdt
uni_usdt
xrp_usdt
btcdvol_usdc
ethdvol_usdc		 The currency pair symbol
kind false string future
option
spot
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
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.

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.

Scope: trade:read_write

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 a given position will also be cancelled. Default: false
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.

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_kind_or_type

curl -X GET "https://test.deribit.com/api/v2/private/cancel_all_by_kind_or_type?currency=%5B%22BTC%22%2C%22ETH%22%5D&kind=future" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{
  "method" : "private/cancel_all_by_kind_or_type",
  "params" : {
    "currency" : [
      "BTC",
      "ETH"
    ],
    "kind" : "future"
  },
  "jsonrpc" : "2.0",
  "id" : 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 = \
{
  "method" : "private/cancel_all_by_kind_or_type",
  "params" : {
    "currency" : [
      "BTC",
      "ETH"
    ],
    "kind" : "future"
  },
  "jsonrpc" : "2.0",
  "id" : 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": 2,
  "result": 6
}

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

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string or array of strings The currency symbol, list of currency symbols or "any" for all
kind false string future
option
spot
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
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.

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 a given label are canceled in all currencies or in one given currency (in this case currency queue is used)

Scope: trade:read_write

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
USDC
USDT
EURR		 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/cancel_quotes

curl -X GET "https://test.deribit.com/api/v2/private/cancel_quotes?cancel_type=delta&max_delta=5.99999999999999977796e-01&min_delta=4.00000000000000022204e-01" \
-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_quotes",
  "params" : {
    "cancel_type" : "delta",
    "min_delta" : 0.4,
    "max_delta" : 0.6
  }
};
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_quotes",
  "params" : {
    "cancel_type" : "delta",
    "min_delta" : 0.4,
    "max_delta" : 0.6
  }
}

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 quotes based on the provided type. delta cancels quotes within a Delta range defined by min_delta and max_delta. quote_set_id cancels quotes by a specific Quote Set identifier. instrument cancels all quotes associated with a particular instrument. kind cancels all quotes for a certain instrument kind. currency cancels all quotes in a specified currency. currency_pair cancels all quotes in a specified currency pair. all cancels all quotes.

Scope: trade:read_write

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
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.
cancel_type true string delta
quote_set_id
instrument
instrument_kind
currency
currency_pair
all		 Type of cancel criteria.
min_delta false number Min delta to cancel by delta (for cancel_type: delta).
max_delta false number Max delta to cancel by delta (for cancel_type: delta).
quote_set_id false string Unique identifier for the Quote set.
instrument_name false string Instrument name.
kind false string future
option
spot
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
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
currency_pair true string ada_usd
algo_usd
avax_usd
bch_usd
btc_usd
doge_usd
dot_usd
eth_usd
link_usd
ltc_usd
matic_usd
near_usd
shib_usd
sol_usd
trx_usd
uni_usd
usdc_usd
xrp_usd
ada_usdc
bch_usdc
algo_usdc
avax_usdc
btc_usdc
doge_usdc
dot_usdc
bch_usdc
eth_usdc
link_usdc
ltc_usdc
matic_usdc
near_usdc
shib_usdc
sol_usdc
trx_usdc
uni_usdc
xrp_usdc
ada_usdt
algo_usdt
avax_usdt
bch_usdt
bnb_usdt
bnb_usdt
btc_usdt
btc_usdt
doge_usdt
dot_usdt
eth_usdt
eth_usdt
link_usdt
ltc_usdt
luna_usdt
matic_usdt
near_usdt
shib_usdt
sol_usdt
trx_usdt
uni_usdt
xrp_usdt
btcdvol_usdc
ethdvol_usdc		 The currency pair 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 quotes

/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",
        "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,
      "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_rebalance": false,
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "filled_amount": 21,
      "direction": "sell",
      "creation_timestamp": 1590486335742,
      "average_price": 202.8,
      "api": true,
      "amount": 21
    }
  }
}

Makes closing position reduce only order .

Scope: trade:read_write

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
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  api boolean true if created with API
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  primary_order_id string Unique order identifier
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  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.
  ›    ›  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.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  order_id string Unique order identifier
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  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.
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  trades array of object
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  api boolean true if user order was created with API
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  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)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  direction string Direction: buy, or sell
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  matching_id string Always null
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  post_only string true if user order is post-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
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)

/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 a given instrument, amount and price.

Scope: trade:read

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 inverse futures the amount is in USD units. For linear futures it is the underlying base currency coin. For options it is the 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?index_name=btc_usd&mmp_group=MassQuoteBot7" \
-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" : {
    "index_name" : "btc_usd",
    "mmp_group" : "MassQuoteBot7"
  }
};
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" : {
    "index_name" : "btc_usd",
    "mmp_group" : "MassQuoteBot7"
  }
}

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": {
    "index_name": "btc_usd",
    "mmp_group": "MassQuoteBot7",
    "interval": 60,
    "frozen_time": 0,
    "quantity_limit": 0.5
  }
}

Get MMP configuration for an index, if the parameter is not provided, a list of all MMP configurations is returned. Empty list means no MMP configuration.

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
index_name false string btc_usd
eth_usd
btc_usdc
eth_usdc
ada_usdc
algo_usdc
avax_usdc
bch_usdc
doge_usdc
dot_usdc
link_usdc
ltc_usdc
matic_usdc
near_usdc
shib_usdc
sol_usdc
trx_usdc
uni_usdc
xrp_usdc
ada_usdt
algo_usdt
avax_usdt
bch_usdt
bnb_usdt
bnb_usdt
btc_usdt
btc_usdt
doge_usdt
dot_usdt
eth_usdt
eth_usdt
link_usdt
ltc_usdt
luna_usdt
matic_usdt
near_usdt
shib_usdt
sol_usdt
trx_usdt
uni_usdt
xrp_usdt
btcdvol_usdc
ethdvol_usdc		 Index identifier of derivative instrument on the platform; skipping this parameter will return all configurations
mmp_group false string Specifies the MMP group for which the configuration is being retrieved. MMP groups are used for Mass Quotes. If MMP group is not provided, the endpoint returns the configuration for the MMP settings for regular orders. The index_name must be specified before using this parameter

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
  ›  delta_limit number Delta limit
  ›  frozen_time integer MMP frozen time in seconds, if set to 0 manual reset is required
  ›  index_name string Index identifier, matches (base) cryptocurrency with quote currency
  ›  interval integer MMP Interval in seconds, if set to 0 MMP is disabled
  ›  mmp_group string Specified MMP Group
  ›  quantity_limit number Quantity limit

/private/get_open_orders

curl -X GET "https://test.deribit.com/api/v2/private/get_open_orders?" \
-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",
  "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" : 1953,
  "method" : "private/get_open_orders",
  "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": 1953,
    "result": [
        {
            "time_in_force": "good_til_cancelled",
            "reduce_only": false,
            "price": 0.0028,
            "post_only": false,
            "order_type": "limit",
            "order_state": "open",
            "order_id": "146062",
            "max_show": 10,
            "last_update_timestamp": 1550050597036,
            "label": "",
            "is_rebalance": false,
            "is_liquidation": false,
            "instrument_name": "BTC-15FEB19-3250-P",
            "filled_amount": 0,
            "direction": "buy",
            "creation_timestamp": 1550050597036,
            "average_price": 0,
            "api": true,
            "amount": 10
        }
    ]
}

Retrieves list of user's open orders across many currencies.

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
kind false string future
option
spot
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
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  original_order_type string Original order type. Optional field
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  api boolean true if created with API
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  primary_order_id string Unique order identifier
  ›  quote boolean If order is a quote. Present only if true.
  ›  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.
  ›  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.
  ›  instrument_name string Unique instrument identifier
  ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  direction string Direction: buy, or sell
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  post_only boolean true for post-only orders only
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  order_id string Unique order identifier
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  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.
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  web boolean true if created via Deribit frontend (optional)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).

/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,
            "price": 0.0028,
            "post_only": false,
            "order_type": "limit",
            "order_state": "open",
            "order_id": "146062",
            "max_show": 10,
            "last_update_timestamp": 1550050597036,
            "label": "",
            "is_rebalance": false,
            "is_liquidation": false,
            "instrument_name": "BTC-15FEB19-3250-P",
            "filled_amount": 0,
            "direction": "buy",
            "creation_timestamp": 1550050597036,
            "average_price": 0,
            "api": true,
            "amount": 10
        }
    ]
}

Retrieves list of user's open orders.

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
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
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  original_order_type string Original order type. Optional field
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  api boolean true if created with API
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  primary_order_id string Unique order identifier
  ›  quote boolean If order is a quote. Present only if true.
  ›  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.
  ›  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.
  ›  instrument_name string Unique instrument identifier
  ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  direction string Direction: buy, or sell
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  post_only boolean true for post-only orders only
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  order_id string Unique order identifier
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  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.
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  web boolean true if created via Deribit frontend (optional)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).

/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,
            "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_rebalance": false,
            "is_liquidation": false,
            "instrument_name": "ETH-22FEB19-120-C",
            "filled_amount": 0,
            "direction": "sell",
            "creation_timestamp": 1550050594882,
            "average_price": 0,
            "api": true,
            "amount": 10
        }
    ]
}

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

Scope: trade:read

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
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  original_order_type string Original order type. Optional field
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  api boolean true if created with API
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  primary_order_id string Unique order identifier
  ›  quote boolean If order is a quote. Present only if true.
  ›  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.
  ›  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.
  ›  instrument_name string Unique instrument identifier
  ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  direction string Direction: buy, or sell
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  post_only boolean true for post-only orders only
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  order_id string Unique order identifier
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  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.
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  web boolean true if created via Deribit frontend (optional)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).

/private/get_open_orders_by_label

curl -X GET "https://test.deribit.com/api/v2/private/get_open_orders_by_label?currency=BTC&label=fooBar" \
-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_label",
  "params" : {
    "currency" : "BTC",
    "label" : "fooBar"
  }
};
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_label",
  "params" : {
    "currency" : "BTC",
    "label" : "fooBar"
  }
}

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,
            "price": 0.0028,
            "post_only": false,
            "order_type": "limit",
            "order_state": "open",
            "order_id": "146062",
            "max_show": 10,
            "last_update_timestamp": 1550050597036,
            "label": "fooBar",
            "is_rebalance": false,
            "is_liquidation": false,
            "instrument_name": "BTC-15FEB19-3250-P",
            "filled_amount": 0,
            "direction": "buy",
            "creation_timestamp": 1550050597036,
            "average_price": 0,
            "api": true,
            "amount": 10
        }
    ]
}

Retrieves list of user's open orders for given currency and label.

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
label false string user defined label for the order (maximum 64 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 object
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  original_order_type string Original order type. Optional field
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  api boolean true if created with API
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  primary_order_id string Unique order identifier
  ›  quote boolean If order is a quote. Present only if true.
  ›  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.
  ›  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.
  ›  instrument_name string Unique instrument identifier
  ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  direction string Direction: buy, or sell
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  trigger_offset n