NAV Navbar Show example code
shell javascript python

Deribit API v2.0.0

Overview

Deribit provides three different interfaces to access the API:

With the API Console you can use and test the JSON-RPC API, both via HTTP and via Websocket. To visit the API console, go to Account > API tab > API Console tab.

Naming

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

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

Rate Limits

The default rate limit for HTTPS-REST is 25 requests per second and for Websocket, FIX -- 50 requests/s. Special settings for a higher amount of requests may be set for the options' market makers.

JSON-RPC

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

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

Request messages

An example of a request message:

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

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

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

Response messages

An example of a response message:

{
    "jsonrpc": "2.0",
    "id": 5239,
    "testnet": false,
    "result": [
        {
            "currency": "BTC",
            "currencyLong": "Bitcoin",
            "minConfirmation": 2,
            "txFee": 0.0006,
            "isActive": true,
            "coinType": "BITCOIN",
            "baseAddress": null
        }
    ],
    "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.

Notifications

An example of a notification:

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

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

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

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

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

Authentication

An example of a JSON request with token:

{
    "id": 5647,
    "method": "private/get_subaccounts",
    "params": {
        "access_token": "67SVutDoVZSzkUStHSuk51WntMNBJ5mh5DYZhwzpiqDF"
    }
}

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 get achived by calling method public/auth.

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

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

NOTICE: Every authorization request invalidates current tokens and creates a new one.

Additional authorization method - basic user credentials

! Not recommended - however, it could be useful for quick testing API

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

Authorization: Basic BASE64(ClientId + : + ClientSecret)

Additional authorization method - Deribit signature credentials

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

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

where:

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

The signature is generated by the following formula:

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

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

Example using shell with openssl tool:

    ClientId=AAAAAAAAAAA
    ClientSecret=ABCD
    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> ea40d5e5e4fae235ab22b61da98121fbf4acdc06db03d632e23c66bcccb90d2c (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 = "AAAAAAAAAAA";
var clientSecret = "ABCD";
var timestamp = Date.now();
var nonce = "abcd";
var data = "";
var signature = CryptoJS.HmacSHA256(`${timestamp}\n${nonce}\n${data}`, clientSecret).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://testapp.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 = "AAAAAAAAAAA"
clientSecret = "ABCD"
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://testapp.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
timestamp Time when the request was generated - given as miliseconds. It's valid for 60 seconds since generation, after that time any request with an old timestamp will be rejected.
signature Value for signature calculated as described below
nonce Single usage, user generated initialization vector for the server token
data Optional field, which contains any user specific value

The signature is generated by the following formula:

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

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

Example using shell with openssl tool:

    ClientId=AAAAAAAAAAA
    ClientSecret=ABCD
    Timestamp=$( date +%s000 ) # e.g. 1554883365000
    Nonce=$( cat /dev/urandom | tr -dc 'a-z0-9' | head -c8 ) # e.g. fdbmmz79
    Data=""

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

    echo $Signature

    shell output> e20c9cd5639d41f8bbc88f4d699c4baf94a4f0ee320e9a116b72743c449eb994 (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" : "AAAAAAAAAAA",
    "timestamp": "1554883365000",
    "nonce": "fdbmmz79",
    "data": "",
    "signature" : "e20c9cd5639d41f8bbc88f4d699c4baf94a4f0ee320e9a116b72743c449eb994"
  }
}

Access scope

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

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

NOTICE: Depending on choosing an authentication method (grant type) some scopes could be narrowed by the server. e.g. when grant_type = client_credentials and scope = wallet:read_write it's modified by the server as scope = wallet:read.
The user shouldn't assume that requested values are blindly accepted and should verify assigned scoped.

JSON-RPC over websocket

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

JSON-RPC over HTTP

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

Methods

Authentication

/public/auth

curl -X GET "https://testapp.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://testapp.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://testapp.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

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

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

Three methods of authentication are supported:

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

Try in API console

Parameters

Parameter Required Type Enum Description
grant_type true string client_credentials
client_signature
refresh_token
Method of authentication
client_id true string Required for grant type client_credentials and client_signature
client_secret true string Required for grant type client_credentials
refresh_token true string Required for grant type refresh_token
timestamp true integer Required for grant type client_signature, provides time when request has been generated
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.

NOTICE: Depending on choosing an authentication method (grant type) some scopes could be narrowed by the server. e.g. when grant_type = client_credentials and scope = wallet:read_write it's modified by the server as scope = wallet:read

Please check details described in Access scope

Response

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

/public/exchange_token

curl -X GET "https://testapp.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://testapp.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://testapp.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

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

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

Try in API console

Parameters

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

Response

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

/public/fork_token

curl -X GET "https://testapp.deribit.com/api/v2/public/fork_token?currency=BTC&expired=false&kind=future" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7617,
  "method" : "public/get_instruments",
  "params" : {
    "currency" : "BTC",
    "kind" : "future",
    "expired" : false
  }
};
var ws = new WebSocket('wss://testapp.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 7617,
  "method" : "public/get_instruments",
  "params" : {
    "currency" : "BTC",
    "kind" : "future",
    "expired" : false
  }
}

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

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

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

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

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

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  acccess_token string
  ›  expires_in integer Token lifetime in seconds
  ›  refresh_token string Can be used to request a new token (with a new lifetime)
  ›  scope string Type of the access for assigned token
  ›  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": "7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG"}
    };
var ws = new WebSocket('wss://testapp.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": "7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG"}
    }

async def call_api(msg):
   async with websockets.connect('wss://testapp.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

This method takes no parameters

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

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7859,
  "method" : "private/enable_cancel_on_disconnect",
  "params" : {

  }
};
var ws = new WebSocket('wss://testapp.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" : {

  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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. This does not change the default account setting. After enabling Cancel On Disconnect all orders created by the connection will be removed when connection is closed.

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

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

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 1569,
  "method" : "private/disable_cancel_on_disconnect",
  "params" : {

  }
};
var ws = new WebSocket('wss://testapp.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" : {

  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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. This does not change the default account setting.

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

Supporting

/public/get_time

curl -X GET "https://testapp.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://testapp.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://testapp.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)

/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://testapp.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://testapp.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/test

curl -X GET "https://testapp.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://testapp.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://testapp.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://testapp.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://testapp.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://testapp.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://testapp.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.

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

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

Account management

/public/get_announcements

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

  }
};
var ws = new WebSocket('wss://testapp.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" : 7661,
  "method" : "public/get_announcements",
  "params" : {

  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 7661,
  "result": [
    {
      "title": "Example announcement",
      "publication_time": 1550058362418,
      "important": false,
      "id": 1550058362418,
      "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    }
  ]
}

Retrieves announcements. Default "start_timestamp" parameter value is current timestamp, "count" parameter value must be between 1 and 50, default is 5.

Try in API console

Parameters

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

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
  ›  body string The HTML body of the announcement
  ›  id number A unique identifier for the announcement
  ›  important boolean Whether the announcement is marked as important
  ›  publication_time integer The timestamp in ms at which the announcement was published
  ›  title string The title of the announcement

/private/change_scope_in_api_key

curl -X GET "https://testapp.deribit.com/api/v2/private/change_scope_in_api_key?id=3&max_scope=account%3Aread_write+wallet%3Aread_write+block_trade%3Aread+trade%3Aread_write" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2453,
  "method" : "private/change_scope_in_api_key",
  "params" : {
    "max_scope" : "account:read_write wallet:read_write block_trade:read trade:read_write",
    "id" : 3
  }
};
var ws = new WebSocket('wss://testapp.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" : 2453,
  "method" : "private/change_scope_in_api_key",
  "params" : {
    "max_scope" : "account:read_write wallet:read_write block_trade:read trade:read_write",
    "id" : 3
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 2453,
  "result": {
    "timestamp": 1560242482758,
    "max_scope": "account:read_write block_trade:read trade:read_write wallet:read_write",
    "id": 3,
    "enabled": true,
    "default": false,
    "client_secret": "B6RsF9rrLY5ezEGBQkyLlV-UC7whyPJ34BMA-kKYpes",
    "client_id": "1sXMQBhM"
  }
}

Changes scope for key with given id

Try in API console

Parameters

Parameter Required Type Enum Description
max_scope false string
id false integer Id of key

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret used for authentication
  ›  default boolean Informs whether this api key is default (default one is used for api console or trading view)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  id integer key identifier
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none].

Please check details described in Access scope
  ›  timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/change_subaccount_name

curl -X GET "https://testapp.deribit.com/api/v2/private/change_subaccount_name?name=new_user_1_1&sid=7" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3964,
  "method" : "private/change_subaccount_name",
  "params" : {
    "sid" : 7,
    "name" : "new_user_1_1"
  }
};
var ws = new WebSocket('wss://testapp.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" : 3964,
  "method" : "private/change_subaccount_name",
  "params" : {
    "sid" : 7,
    "name" : "new_user_1_1"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 3964,
    "result": "ok"
}

Change the user name for a subaccount

Try in API console

Parameters

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

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

curl -X GET "https://testapp.deribit.com/api/v2/private/create_api_key?scope=account%3Aread+trade%3Aread+block_trade%3Aread_write+wallet%3Anone" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8974,
  "method" : "private/create_api_key",
  "params" : {
    "scope" : "account:read trade:read block_trade:read_write wallet:none"
  }
};
var ws = new WebSocket('wss://testapp.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" : 8974,
  "method" : "private/create_api_key",
  "params" : {
    "scope" : "account:read trade:read block_trade:read_write wallet:none"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 8974,
  "result": {
    "timestamp": 1560238048714,
    "max_scope": "account:read block_trade:read_write trade:read wallet:none",
    "id": 5,
    "enabled": true,
    "default": false,
    "client_secret": "STu1eIkdOsLrDZFCRlddYLXUAx4Cubm4oUhEUoxWHKc",
    "client_id": "wcVoQGam"
  }
}

Creates new api key with given scope

Try in API console

Parameters

Parameter Required Type Enum Description
max_scope false string
default false boolean If true, new key is marked as default

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret used for authentication
  ›  default boolean Informs whether this api key is default (default one is used for api console or trading view)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  id integer key identifier
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none].

Please check details described in Access scope
  ›  timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/create_subaccount

curl -X GET "https://testapp.deribit.com/api/v2/private/create_subaccount?" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5414,
  "method" : "private/create_subaccount",
  "params" : {

  }
};
var ws = new WebSocket('wss://testapp.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" : 5414,
  "method" : "private/create_subaccount",
  "params" : {

  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 5414,
    "result": {
        "email": "user_AAA@email.com",
        "id": 13,
        "is_password": false,
        "login_enabled": false,
        "portfolio": {
            "eth": {
                "available_funds": 0,
                "available_withdrawal_funds": 0,
                "balance": 0,
                "currency": "eth",
                "equity": 0,
                "initial_margin": 0,
                "maintenance_margin": 0,
                "margin_balance": 0
            },
            "btc": {
                "available_funds": 0,
                "available_withdrawal_funds": 0,
                "balance": 0,
                "currency": "btc",
                "equity": 0,
                "initial_margin": 0,
                "maintenance_margin": 0,
                "margin_balance": 0
            }
        },
        "receive_notifications": false,
        "system_name": "user_1_4",
        "tfa_enabled": false,
        "type": "subaccount",
        "username": "user_1_4"
    }
}

Create a new subaccount

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
  ›  email string User email
  ›  id integer Subaccount identifier
  ›  is_password boolean true when password for the subaccount has been configured
  ›  login_enabled boolean Informs whether login to the subaccount is enabled
  ›  portfolio object
  ›    ›  btc object
  ›    ›    ›  available_funds number
  ›    ›    ›  available_withdrawal_funds number
  ›    ›    ›  balance number
  ›    ›    ›  currency string
  ›    ›    ›  equity number
  ›    ›    ›  initial_margin number
  ›    ›    ›  maintenance_margin number
  ›    ›    ›  margin_balance number
  ›    ›  eth object
  ›    ›    ›  available_funds number
  ›    ›    ›  available_withdrawal_funds number
  ›    ›    ›  balance number
  ›    ›    ›  currency string
  ›    ›    ›  equity number
  ›    ›    ›  initial_margin number
  ›    ›    ›  maintenance_margin number
  ›    ›    ›  margin_balance number
  ›  receive_notifications boolean When true - receive all notification emails on the main email
  ›  system_name string System generated user nickname
  ›  tfa_enabled boolean Whether the two factor authentication is enabled
  ›  type string Account type
  ›  username string Account name (given by user)

/private/disable_api_key

curl -X GET "https://testapp.deribit.com/api/v2/private/disable_api_key?id=3" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2861,
  "method" : "private/disable_api_key",
  "params" : {
    "id" : 3
  }
};
var ws = new WebSocket('wss://testapp.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" : 2861,
  "method" : "private/disable_api_key",
  "params" : {
    "id" : 3
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 2861,
  "result": {
    "timestamp": 1560242676023,
    "max_scope": "account:read_write block_trade:read trade:read_write wallet:read_write",
    "id": 3,
    "enabled": false,
    "default": false,
    "client_secret": "B6RsF9rrLY5ezEGBQkyLlV-UC7whyPJ34BMA-kKYpes",
    "client_id": "1sXMQBhM"
  }
}

Disables api key with given id

Try in API console

Parameters

Parameter Required Type Enum Description
id false integer Id of key

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret used for authentication
  ›  default boolean Informs whether this api key is default (default one is used for api console or trading view)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  id integer key identifier
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none].

Please check details described in Access scope
  ›  timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/disable_tfa_for_subaccount

curl -X GET "https://testapp.deribit.com/api/v2/private/disable_tfa_for_subaccount?sid=7" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7640,
  "method" : "private/disable_tfa_for_subaccount",
  "params" : {
    "sid" : 7
  }
};
var ws = new WebSocket('wss://testapp.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" : 7640,
  "method" : "private/disable_tfa_for_subaccount",
  "params" : {
    "sid" : 7
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 7640,
    "result": "ok"
}

Disable two factor authentication for a subaccount.

Try in API console

Parameters

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

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_api_key

curl -X GET "https://testapp.deribit.com/api/v2/private/enable_api_key?id=3" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8580,
  "method" : "private/enable_api_key",
  "params" : {
    "id" : 3
  }
};
var ws = new WebSocket('wss://testapp.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" : 8580,
  "method" : "private/enable_api_key",
  "params" : {
    "id" : 3
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 8580,
  "result": {
    "timestamp": 1560242634599,
    "max_scope": "account:read_write block_trade:read trade:read_write wallet:read_write",
    "id": 3,
    "enabled": true,
    "default": false,
    "client_secret": "B6RsF9rrLY5ezEGBQkyLlV-UC7whyPJ34BMA-kKYpes",
    "client_id": "1sXMQBhM"
  }
}

Enables api key with given id

Try in API console

Parameters

Parameter Required Type Enum Description
id false integer Id of key

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret used for authentication
  ›  default boolean Informs whether this api key is default (default one is used for api console or trading view)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  id integer key identifier
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none].

Please check details described in Access scope
  ›  timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/get_account_summary

curl -X GET "https://testapp.deribit.com/api/v2/private/get_account_summary?currency=BTC&extended=true" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2515,
  "method" : "private/get_account_summary",
  "params" : {
    "currency" : "BTC",
    "extended" : true
  }
};
var ws = new WebSocket('wss://testapp.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" : 2515,
  "method" : "private/get_account_summary",
  "params" : {
    "currency" : "BTC",
    "extended" : true
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 2515,
    "result": {
        "available_funds": 5.00040249,
        "available_withdrawal_funds": 5.00040249,
        "balance": 5.00059399,
        "currency": "BTC",
        "delta_total": 0.0054,
        "deposit_address": "2N35qDKDY22zmJq9eSyiAerMD4enJ1xx6ax",
        "email": "user_AAA@email.com",
        "equity": 5.0005616,
        "futures_pl": -0.0000432,
        "futures_session_rpl": 0.00001081,
        "futures_session_upl": -0.0000432,
        "id": 2,
        "initial_margin": 0.00015911,
        "maintenance_margin": 0.00011597,
        "margin_balance": 5.0005616,
        "options_delta": 0,
        "options_gamma": 0,
        "options_pl": 0,
        "options_session_rpl": 0,
        "options_session_upl": 0,
        "options_theta": 0,
        "options_vega": 0,
        "portfolio_margining_enabled": false,
        "session_funding": 0,
        "session_rpl": 0.00001081,
        "session_upl": -0.0000432,
        "system_name": "user_1",
        "tfa_enabled": false,
        "total_pl": -0.0000432,
        "type": "main",
        "username": "user_1"
    }
}

Retrieves user account summary.

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  options_gamma number Options summary gamma
  ›  projected_maintenance_margin number Projected maintenance margin (for portfolio margining users)
  ›  system_name string System generated user nickname (available when parameter extended = true)
  ›  margin_balance number The account's margin balance
  ›  tfa_enabled boolean Whether two factor authentication is enabled (available when parameter extended = true)
  ›  username string Account name (given by user) (available when parameter extended = true)
  ›  equity number The account's current equity
  ›  futures_pl number Futures profit and Loss
  ›  fees array of object User fees in case of any discounts (available when parameter extended = true and user has any discounts)
  ›    ›  currency string The currency the fee applies to
  ›    ›  fee_type string Fee type - relative if fee is calculated as a fraction of base instrument fee, fixed if fee is calculated solely using user fee
  ›    ›  instrument_type string Type of the instruments the fee applies to - future for future instruments (excluding perpetual), perpetual for future perpetual instruments, option for options
  ›    ›  maker_fee number User fee as a maker
  ›    ›  taker_fee number User fee as a taker
  ›  options_session_upl number Options session unrealized profit and Loss
  ›  id integer Account id (available when parameter extended = true)
  ›  options_vega number Options summary vega
  ›  referrer_id string Optional identifier of the referrer (of the affiliation program, and available when parameter extended = true), which link was used by this account at registration. It coincides with suffix of the affiliation link path after /reg-
  ›  session_funding number Session funding
  ›  currency string The selected currency
  ›  type string Account type (available when parameter extended = true)
  ›  futures_session_rpl number Futures session realized profit and Loss
  ›  options_theta number Options summary theta
  ›  portfolio_margining_enabled boolean true when portfolio margining is enabled for user
  ›  session_rpl number Session realized profit and loss
  ›  delta_total number The sum of position deltas
  ›  options_pl number Options profit and Loss
  ›  available_withdrawal_funds number The account's available to withdrawal funds
  ›  maintenance_margin number The maintenance margin.
  ›  initial_margin number The account's initial margin
  ›  futures_session_upl number Futures session unrealized profit and Loss
  ›  options_session_rpl number Options session realized profit and Loss
  ›  available_funds number The account's available funds
  ›  email string User email (available when parameter extended = true)
  ›  session_upl number Session unrealized profit and loss
  ›  total_pl number Profit and loss
  ›  options_delta number Options summary delta
  ›  balance number The account's balance
  ›  projected_initial_margin number Projected initial margin (for portfolio margining users)
  ›  deposit_address string The deposit address for the account (if available)

/private/get_email_language

curl -X GET "https://testapp.deribit.com/api/v2/private/get_email_language?" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9265,
  "method" : "private/get_email_language",
  "params" : {

  }
};
var ws = new WebSocket('wss://testapp.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" : 9265,
  "method" : "private/get_email_language",
  "params" : {

  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 9265,
  "result": "en"
}

Retrieves the language to be used for emails.

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 The abbreviation of the language

/private/get_new_announcements

curl -X GET "https://testapp.deribit.com/api/v2/private/get_new_announcements?" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3022,
  "method" : "private/get_new_announcements",
  "params" : {

  }
};
var ws = new WebSocket('wss://testapp.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" : 3022,
  "method" : "private/get_new_announcements",
  "params" : {

  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 3022,
  "result": [
    {
      "title": "Example announcement",
      "publication_time": 1550058362418,
      "important": false,
      "id": 1550058362418,
      "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    }
  ]
}

Retrieves announcements that have not been marked read by the user.

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
  ›  body string The HTML body of the announcement
  ›  id number A unique identifier for the announcement
  ›  important boolean Whether the announcement is marked as important
  ›  publication_time integer The timestamp in ms at which the announcement was published
  ›  title string The title of the announcement

/private/get_position

curl -X GET "https://testapp.deribit.com/api/v2/private/get_position?instrument_name=BTC-PERPETUAL" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 404,
  "method" : "private/get_position",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL"
  }
};
var ws = new WebSocket('wss://testapp.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" : 404,
  "method" : "private/get_position",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 404,
  "result": {
      "average_price": 0,
      "delta": 0,
      "direction": "buy",
      "estimated_liquidation_price": 0,
      "floating_profit_loss": 0,
      "index_price": 3555.86,
      "initial_margin": 0,
      "instrument_name": "BTC-PERPETUAL",
      "leverage": 100,
      "kind": "future",
      "maintenance_margin": 0,
      "mark_price": 3556.62,
      "open_orders_margin": 0.000165889,
      "realized_profit_loss": 0,
      "settlement_price": 3555.44,
      "size": 0,
      "size_currency": 0,
      "total_profit_loss": 0
  }
}

Retrieve user position.

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
  ›  average_price number Average price of trades that built this position
  ›  average_price_usd number Only for options, average price in USD
  ›  delta number Delta parameter
  ›  direction string Direction: buy, sell or zero
  ›  estimated_liquidation_price number Only for futures, estimated liquidation price
  ›  floating_profit_loss number Floating profit or loss
  ›  floating_profit_loss_usd number Only for options, floating profit or loss in USD
  ›  index_price number Current index price
  ›  initial_margin number Initial margin
  ›  instrument_name string Unique instrument identifier
  ›  kind string Instrument kind, "future" or "option"
  ›  leverage integer Current available leverage for future position
  ›  maintenance_margin number Maintenance margin
  ›  mark_price number Current mark price for position's instrument
  ›  open_orders_margin number Open orders margin
  ›  realized_profit_loss number Realized profit or loss
  ›  settlement_price number Last settlement price for position's instrument 0 if instrument wasn't settled yet
  ›  size number Position size for futures size in quote currency (e.g. USD), for options size is in base currency (e.g. BTC)
  ›  size_currency number Only for futures, position size in base currency
  ›  total_profit_loss number Profit or loss from position

/private/get_positions

curl -X GET "https://testapp.deribit.com/api/v2/private/get_positions?currency=BTC&kind=future" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2236,
  "method" : "private/get_positions",
  "params" : {
    "currency" : "BTC",
    "kind" : "future"
  }
};
var ws = new WebSocket('wss://testapp.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" : 2236,
  "method" : "private/get_positions",
  "params" : {
    "currency" : "BTC",
    "kind" : "future"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 2236,
  "result": [
      {
          "average_price": 0,
          "delta": 0,
          "direction": "buy",
          "estimated_liquidation_price": 0,
          "floating_profit_loss": 0,
          "index_price": 3563.04,
          "initial_margin": 0,
          "instrument_name": "BTC-PERPETUAL",
          "leverage": 100,
          "kind": "future",
          "maintenance_margin": 0,
          "mark_price": 3579.63,
          "open_orders_margin": 0.000139733,
          "realized_profit_loss": 0,
          "settlement_price": 3561.74,
          "size_currency": 0,
          "size": 0,
          "total_profit_loss": 0
      }
  ]
}

Retrieve user positions.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
kind false string future
option
Kind filter on positions

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
  ›  average_price number Average price of trades that built this position
  ›  average_price_usd number Only for options, average price in USD
  ›  delta number Delta parameter
  ›  direction string Direction: buy, sell or zero
  ›  estimated_liquidation_price number Only for futures, estimated liquidation price
  ›  floating_profit_loss number Floating profit or loss
  ›  floating_profit_loss_usd number Only for options, floating profit or loss in USD
  ›  index_price number Current index price
  ›  initial_margin number Initial margin
  ›  instrument_name string Unique instrument identifier
  ›  kind string Instrument kind, "future" or "option"
  ›  leverage integer Current available leverage for future position
  ›  maintenance_margin number Maintenance margin
  ›  mark_price number Current mark price for position's instrument
  ›  open_orders_margin number Open orders margin
  ›  realized_profit_loss number Realized profit or loss
  ›  settlement_price number Last settlement price for position's instrument 0 if instrument wasn't settled yet
  ›  size number Position size for futures size in quote currency (e.g. USD), for options size is in base currency (e.g. BTC)
  ›  size_currency number Only for futures, position size in base currency
  ›  total_profit_loss number Profit or loss from position

/private/get_subaccounts

curl -X GET "https://testapp.deribit.com/api/v2/private/get_subaccounts?with_portfolio=true" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 4947,
  "method" : "private/get_subaccounts",
  "params" : {
    "with_portfolio" : true
  }
};
var ws = new WebSocket('wss://testapp.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" : 4947,
  "method" : "private/get_subaccounts",
  "params" : {
    "with_portfolio" : true
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 4947,
    "result": [
        {
            "email": "user_AAA@email.com",
            "id": 2,
            "is_password": true,
            "login_enabled": true,
            "portfolio": {
                "eth": {
                    "available_funds": 5,
                    "available_withdrawal_funds": 5,
                    "balance": 5,
                    "currency": "eth",
                    "equity": 5,
                    "initial_margin": 0,
                    "maintenance_margin": 0,
                    "margin_balance": 5
                },
                "btc": {
                    "available_funds": 5.000413075,
                    "available_withdrawal_funds": 5.000413075,
                    "balance": 5.000593987,
                    "currency": "btc",
                    "equity": 5.000571846,
                    "initial_margin": 0.000158771,
                    "maintenance_margin": 0.000115715,
                    "margin_balance": 5.000571846
                }
            },
            "receive_notifications": false,
            "system_name": "user_1",
            "tfa_enabled": false,
            "type": "main",
            "username": "user_1"
        },
        {
            "email": "user_AAA@gmail.com",
            "id": 7,
            "is_password": true,
            "login_enabled": false,
            "portfolio": {
                "eth": {
                    "available_funds": 0,
                    "available_withdrawal_funds": 0,
                    "balance": 0,
                    "currency": "eth",
                    "equity": 0,
                    "initial_margin": 0,
                    "maintenance_margin": 0,
                    "margin_balance": 0
                },
                "btc": {
                    "available_funds": 0,
                    "available_withdrawal_funds": 0,
                    "balance": 0,
                    "currency": "btc",
                    "equity": 0,
                    "initial_margin": 0,
                    "maintenance_margin": 0,
                    "margin_balance": 0
                }
            },
            "receive_notifications": false,
            "system_name": "user_1_1",
            "tfa_enabled": false,
            "type": "subaccount",
            "username": "user_1_1"
        },
        {
            "email": "user_AAA@gmail.com",
            "id": 11,
            "is_password": false,
            "login_enabled": false,
            "portfolio": {
                "eth": {
                    "available_funds": 0,
                    "available_withdrawal_funds": 0,
                    "balance": 0,
                    "currency": "eth",
                    "equity": 0,
                    "initial_margin": 0,
                    "maintenance_margin": 0,
                    "margin_balance": 0
                },
                "btc": {
                    "available_funds": 0,
                    "available_withdrawal_funds": 0,
                    "balance": 0,
                    "currency": "btc",
                    "equity": 0,
                    "initial_margin": 0,
                    "maintenance_margin": 0,
                    "margin_balance": 0
                }
            },
            "receive_notifications": false,
            "system_name": "user_1_2",
            "tfa_enabled": false,
            "type": "subaccount",
            "username": "user_1_2"
        }
    ]
}


Get information about subaccounts

Try in API console

Parameters

Parameter Required Type Enum Description
with_portfolio false boolean

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
  ›  email string User email
  ›  id integer Account/Subaccount identifier
  ›  is_password boolean true when password for the subaccount has been configured
  ›  login_enabled boolean Informs whether login to the subaccount is enabled
  ›  not_confirmed_email string New email address that has not yet been confirmed. This field is only included if with_portfolio == true.
  ›  portfolio object
  ›    ›  btc object
  ›    ›    ›  available_funds number
  ›    ›    ›  available_withdrawal_funds number
  ›    ›    ›  balance number
  ›    ›    ›  currency string
  ›    ›    ›  equity number
  ›    ›    ›  initial_margin number
  ›    ›    ›  maintenance_margin number
  ›    ›    ›  margin_balance number
  ›    ›  eth object
  ›    ›    ›  available_funds number
  ›    ›    ›  available_withdrawal_funds number
  ›    ›    ›  balance number
  ›    ›    ›  currency string
  ›    ›    ›  equity number
  ›    ›    ›  initial_margin number
  ›    ›    ›  maintenance_margin number
  ›    ›    ›  margin_balance number
  ›  receive_notifications boolean When true - receive all notification emails on the main email
  ›  system_name string System generated user nickname
  ›  tfa_enabled boolean Whether the two factor authentication is enabled
  ›  type string
  ›  username string

/private/list_api_keys

curl -X GET "https://testapp.deribit.com/api/v2/private/list_api_keys?" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2553,
  "method" : "private/list_api_keys"
};
var ws = new WebSocket('wss://testapp.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" : 2553,
  "method" : "private/list_api_keys"
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 2553,
  "result": [
    {
      "timestamp": 1560236001108,
      "max_scope": "account:read block_trade:read trade:read_write wallet:read",
      "id": 1,
      "enabled": false,
      "default": false,
      "client_secret": "SjM57m1T2CfXZ4vZ76X1APjqRlJdtzHI8IwVXoQnfoM",
      "client_id": "TiA4AyLPq3"
    },
    {
      "timestamp": 1560236287708,
      "max_scope": "account:read_write block_trade:read_write trade:read_write wallet:read_write",
      "id": 2,
      "enabled": true,
      "default": true,
      "client_secret": "mwNOvbUVyQczytQ5IVM8CbzmgqNJ81WvLKfu6MXcJPs",
      "client_id": "aD-KFx-H"
    }
  ]
}

Retrieves list of api keys

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
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret used for authentication
  ›  default boolean Informs whether this api key is default (default one is used for api console or trading view)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  id integer key identifier
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none].

Please check details described in Access scope
  ›  timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/remove_api_key

curl -X GET "https://testapp.deribit.com/api/v2/private/remove_api_key?id=2" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8190,
  "method" : "private/remove_api_key",
  "params" : {
    "id" : 2
  }
};
var ws = new WebSocket('wss://testapp.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" : 8190,
  "method" : "private/remove_api_key",
  "params" : {
    "id" : 2
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 8190,
  "result": "ok"
}

Removes api key

Try in API console

Parameters

Parameter Required Type Enum Description
id false integer Id of key

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

curl -X GET "https://testapp.deribit.com/api/v2/private/reset_api_key?id=3" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 6524,
  "method" : "private/reset_api_key",
  "params" : {
    "id" : 3
  }
};
var ws = new WebSocket('wss://testapp.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" : 6524,
  "method" : "private/reset_api_key",
  "params" : {
    "id" : 3
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 6524,
  "result": {
    "timestamp": 1560238942222,
    "max_scope": "account:read block_trade:read trade:read wallet:read",
    "id": 3,
    "enabled": true,
    "default": false,
    "client_secret": "P9Z_c73KaBPwpoTVfsXzehAhjhdJn5kM7Zlz_hhDhE8",
    "client_id": "IY2D68DS"
  }
}

Resets secret in api key

Try in API console

Parameters

Parameter Required Type Enum Description
id false integer Id of key

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret used for authentication
  ›  default boolean Informs whether this api key is default (default one is used for api console or trading view)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  id integer key identifier
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none].

Please check details described in Access scope
  ›  timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/set_announcement_as_read

curl -X GET "https://testapp.deribit.com/api/v2/private/set_announcement_as_read?announcement_id=1550058362418" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5147,
  "method" : "private/set_announcement_as_read",
  "params" : {
    "announcement_id" : 1550058362418
  }
};
var ws = new WebSocket('wss://testapp.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" : 5147,
  "method" : "private/set_announcement_as_read",
  "params" : {
    "announcement_id" : 1550058362418
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 5147,
  "result": "ok"
}

Marks an announcement as read, so it will not be shown in get_new_announcements.

Try in API console

Parameters

Parameter Required Type Enum Description
announcement_id true number the ID of the announcement

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

curl -X GET "https://testapp.deribit.com/api/v2/private/set_api_key_as_default?" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 402,
  "result" : {
    "timestamp" : 1560242795712,
    "max_scope" : "account:read_write block_trade:read trade:read_write wallet:read_write",
    "id" : 3,
    "enabled" : false,
    "default" : true,
    "client_secret" : "B6RsF9rrLY5ezEGBQkyLlV-UC7whyPJ34BMA-kKYpes",
    "client_id" : "1sXMQBhM"
  }
};
var ws = new WebSocket('wss://testapp.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" : 402,
  "result" : {
    "timestamp" : 1560242795712,
    "max_scope" : "account:read_write block_trade:read trade:read_write wallet:read_write",
    "id" : 3,
    "enabled" : false,
    "default" : true,
    "client_secret" : "B6RsF9rrLY5ezEGBQkyLlV-UC7whyPJ34BMA-kKYpes",
    "client_id" : "1sXMQBhM"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 402,
  "result": {
    "timestamp": 1560242795712,
    "max_scope": "account:read_write block_trade:read trade:read_write wallet:read_write",
    "id": 3,
    "enabled": false,
    "default": true,
    "client_secret": "B6RsF9rrLY5ezEGBQkyLlV-UC7whyPJ34BMA-kKYpes",
    "client_id": "1sXMQBhM"
  }
}

Sets key with given id as default one

Try in API console

Parameters

Parameter Required Type Enum Description
id false integer Id of key

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret used for authentication
  ›  default boolean Informs whether this api key is default (default one is used for api console or trading view)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  id integer key identifier
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none].

Please check details described in Access scope
  ›  timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/set_email_for_subaccount

curl -X GET "https://testapp.deribit.com/api/v2/private/set_email_for_subaccount?email=user_1_1%40email.com&sid=7" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 1667,
  "method" : "private/set_email_for_subaccount",
  "params" : {
    "sid" : 7,
    "email" : "user_1_1@email.com"
  }
};
var ws = new WebSocket('wss://testapp.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" : 1667,
  "method" : "private/set_email_for_subaccount",
  "params" : {
    "sid" : 7,
    "email" : "user_1_1@email.com"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 1667,
    "result": "ok"
}

Assign an email address to a subaccount. User will receive an email with confirmation link.

Try in API console

Parameters

Parameter Required Type Enum Description
sid true integer The user id for the subaccount
email true string The email address for the subaccount

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

curl -X GET "https://testapp.deribit.com/api/v2/private/set_email_language?language=en" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3269,
  "method" : "private/set_email_language",
  "params" : {
    "language" : "en"
  }
};
var ws = new WebSocket('wss://testapp.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" : 3269,
  "method" : "private/set_email_language",
  "params" : {
    "language" : "en"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 3269,
  "result": "ok"
}

Changes the language to be used for emails.

Try in API console

Parameters

Parameter Required Type Enum Description
language true string The abbreviated language name. Valid values include "en", "ko", "zh"

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

curl -X GET "https://testapp.deribit.com/api/v2/private/set_password_for_subaccount?password=ABCDEFGHIJKLMO&sid=7" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5819,
  "method" : "private/set_password_for_subaccount",
  "params" : {
    "sid" : 7,
    "password" : "ABCDEFGHIJKLMO"
  }
};
var ws = new WebSocket('wss://testapp.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" : 5819,
  "method" : "private/set_password_for_subaccount",
  "params" : {
    "sid" : 7,
    "password" : "ABCDEFGHIJKLMO"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 5819,
    "result": "ok"
}

Set the password for the subaccount

Try in API console

Parameters

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

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

curl -X GET "https://testapp.deribit.com/api/v2/private/toggle_notifications_from_subaccount?sid=7&state=true" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9995,
  "method" : "private/toggle_notifications_from_subaccount",
  "params" : {
    "sid" : 7,
    "state" : true
  }
};
var ws = new WebSocket('wss://testapp.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" : 9995,
  "method" : "private/toggle_notifications_from_subaccount",
  "params" : {
    "sid" : 7,
    "state" : true
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 9995,
    "result": "ok"
}

Enable or disable sending of notifications for the subaccount.

Try in API console

Parameters

Parameter Required Type Enum Description
sid true integer The user id for the subaccount
state true boolean enable (true) or disable (false) notifications

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

curl -X GET "https://testapp.deribit.com/api/v2/private/toggle_subaccount_login?sid=7&state=enable" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 938,
  "method" : "private/toggle_subaccount_login",
  "params" : {
    "sid" : 7,
    "state" : "enable"
  }
};
var ws = new WebSocket('wss://testapp.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" : 938,
  "method" : "private/toggle_subaccount_login",
  "params" : {
    "sid" : 7,
    "state" : "enable"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 938,
    "result": "ok"
}

Enable or disable login for a subaccount. If login is disabled and a session for the subaccount exists, this session will be terminated.

Try in API console

Parameters

Parameter Required Type Enum Description
sid true integer The user id for the subaccount
state true string enable
disable
enable or disable login.

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

Block Trade

/private/execute_block_trade

curl -X GET "https://testapp.deribit.com/api/v2/private/execute_block_trade?counterparty_signature=1565172710935.1ESE83qh.g6fbgRd4VWagaJz7xdi2WaV-q-d3J0njoz1jZavuRudZJZif9uH8XdUAx1LHsu0E3e0ZG_xe1UPYlwo41xRVrkWU6OMgygDRafUkEmBuk9iLqjc9rh4&currency=BTC&nonce=okpdjkdo&role=taker&timestamp=1565172650935&trades=%5B%7B%22price%22%3A11624%2C%22instrument_name%22%3A%22BTC-PERPETUAL%22%2C%22direction%22%3A%22buy%22%2C%22amount%22%3A40%7D%2C%7B%22price%22%3A0.0707%2C%22instrument_name%22%3A%22BTC-9AUG19-10250-P%22%2C%22direction%22%3A%22buy%22%2C%22amount%22%3A1.2%7D%5D" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "method" : "private/execute_block_trade",
  "params" : {
    "currency" : "BTC",
    "nonce" : "okpdjkdo",
    "timestamp" : 1565172650935,
    "role" : "taker",
    "trades" : [
      {
        "instrument_name" : "BTC-PERPETUAL",
        "direction" : "buy",
        "price" : 11624,
        "amount" : 40
      },
      {
        "instrument_name" : "BTC-9AUG19-10250-P",
        "direction" : "buy",
        "amount" : 1.2,
        "price" : 0.0707
      }
    ],
    "counterparty_signature" : "1565172710935.1ESE83qh.g6fbgRd4VWagaJz7xdi2WaV-q-d3J0njoz1jZavuRudZJZif9uH8XdUAx1LHsu0E3e0ZG_xe1UPYlwo41xRVrkWU6OMgygDRafUkEmBuk9iLqjc9rh4"
  }
};
var ws = new WebSocket('wss://testapp.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/execute_block_trade",
  "params" : {
    "currency" : "BTC",
    "nonce" : "okpdjkdo",
    "timestamp" : 1565172650935,
    "role" : "taker",
    "trades" : [
      {
        "instrument_name" : "BTC-PERPETUAL",
        "direction" : "buy",
        "price" : 11624,
        "amount" : 40
      },
      {
        "instrument_name" : "BTC-9AUG19-10250-P",
        "direction" : "buy",
        "amount" : 1.2,
        "price" : 0.0707
      }
    ],
    "counterparty_signature" : "1565172710935.1ESE83qh.g6fbgRd4VWagaJz7xdi2WaV-q-d3J0njoz1jZavuRudZJZif9uH8XdUAx1LHsu0E3e0ZG_xe1UPYlwo41xRVrkWU6OMgygDRafUkEmBuk9iLqjc9rh4"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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",
  "result":{
    "trades":[
      {
        "trade_seq":43,
        "trade_id":"92483",
        "timestamp":1565172650938,
        "tick_direction":2,
        "state":"filled",
        "self_trade":false,
        "price":0.0707,
        "order_type":"limit",
        "order_id":"343242",
        "matching_id":null,
        "liquidity":"M",
        "iv":449.22,
        "instrument_name":"BTC-9AUG19-10250-P",
        "index_price":11628.15,
        "fee_currency":"BTC",
        "fee":0.0,
        "direction":"sell",
        "block_trade_id":"72",
        "amount":1.2
      },
      {
        "trade_seq":25361,
        "trade_id":"92482",
        "timestamp":1565172650937,
        "tick_direction":2,
        "state":"filled",
        "self_trade":false,
        "price":11624.0,
        "order_type":"limit",
        "order_id":"343240",
        "matching_id":null,
        "liquidity":"M",
        "instrument_name":"BTC-PERPETUAL",
        "index_price":11628.15,
        "fee_currency":"BTC",
        "fee":0.0,
        "direction":"sell",
        "block_trade_id":"72",
        "amount":40.0
      }
    ],
    "timestamp":1565172650938,
    "initiator_user_id":13,
    "id":"72",
    "executor_user_id":2,
    "currency":"BTC"
  }
}

Creates block trade

The whole request have to be exact the same as in private/verify_block_trade, only role field should be set appropriately - it basically means that both sides have to agree on the same timestamp, nonce, trades fields and server will assure that role field is different between sides (each party accepted own role).

Using the same timestamp and nonce by both sides in private/verify_block_trade assures that even if unintentionally both sides execute given block trade with valid counterparty_signature, the given block trade will be executed only once.

Try in API console

Parameters

Parameter Required Type Enum Description
timestamp true integer Timestamp, shared with other party
nonce true string Nonce, shared with other party
role true string maker
taker
Describes if user wants to be maker or taker of trades
trades true array of objects List of trades for block trade
  ›  instrument_name true string Instrument name
  ›  price true number Price for trade
  ›  amount true number It represents the requested trade size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH
  ›  direction true string buy
sell
Direction of trade from the maker perspective
counterparty_signature true string Signature of block trade generated by private/verify_block_trade_method
currency false string BTC
ETH
The currency symbol

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  currency string Currency, i.e "BTC", "ETH"
  ›  executor_user_id integer Id of user that executed block_trade
  ›  id string Block trade id
  ›  initiator_user_id integer Id of user that initiated block_trade
  ›  timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH"
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/private/get_block_trade

curl -X GET "https://testapp.deribit.com/api/v2/private/get_block_trade?id=61" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "method" : "private/get_block_trade",
  "params" : {
    "id" : "61"
  },
  "jsonrpc" : "2.0"
};
var ws = new WebSocket('wss://testapp.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/get_block_trade",
  "params" : {
    "id" : "61"
  },
  "jsonrpc" : "2.0"
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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",
  "result": {
    "trades": [
      {
        "trade_seq": 37,
        "trade_id": "92437",
        "timestamp": 1565089523719,
        "tick_direction": 3,
        "state": "filled",
        "self_trade": false,
        "price": 0.0001,
        "order_type": "limit",
        "order_id": "343062",
        "matching_id": null,
        "liquidity": "T",
        "iv": 0,
        "instrument_name": "BTC-9AUG19-10250-C",
        "index_price": 11738,
        "fee_currency": "BTC",
        "fee": 0.00025,
        "direction": "sell",
        "block_trade_id": "61",
        "amount": 10
      },
      {
        "trade_seq": 25350,
        "trade_id": "92435",
        "timestamp": 1565089523719,
        "tick_direction": 3,
        "state": "filled",
        "self_trade": false,
        "price": 11590,
        "order_type": "limit",
        "order_id": "343058",
        "matching_id": null,
        "liquidity": "T",
        "instrument_name": "BTC-PERPETUAL",
        "index_price": 11737.98,
        "fee_currency": "BTC",
        "fee": 0.00000164,
        "direction": "buy",
        "block_trade_id": "61",
        "amount": 190
      }
    ],
    "timestamp": 1565089523720,
    "initiator_user_id": 2,
    "id": "61",
    "executor_user_id": 3,
    "currency": "BTC"
  }
}

Returns information about users block trade

Try in API console

Parameters

Parameter Required Type Enum Description
id true string Block trade 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
  ›  currency string Currency, i.e "BTC", "ETH"
  ›  executor_user_id integer Id of user that executed block_trade
  ›  id string Block trade id
  ›  initiator_user_id integer Id of user that initiated block_trade
  ›  timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH"
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/private/get_last_block_trades_by_currency

curl -X GET "https://testapp.deribit.com/api/v2/private/get_last_block_trades_by_currency?count=1&currency=BTC" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "method" : "private/get_last_block_trades_by_currency",
  "params" : {
    "currency" : "BTC",
    "count" : 1
  },
  "jsonrpc" : "2.0"
};
var ws = new WebSocket('wss://testapp.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/get_last_block_trades_by_currency",
  "params" : {
    "currency" : "BTC",
    "count" : 1
  },
  "jsonrpc" : "2.0"
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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",
  "result": [
    {
      "trades": [
        {
          "trade_seq": 4,
          "trade_id": "92462",
          "timestamp": 1565093070164,
          "tick_direction": 2,
          "state": "filled",
          "self_trade": false,
          "price": 0.0151,
          "order_type": "limit",
          "order_id": "343121",
          "matching_id": null,
          "liquidity": "M",
          "iv": 72.38,
          "instrument_name": "BTC-9AUG19-11500-P",
          "index_price": 11758.65,
          "fee_currency": "BTC",
          "fee": 0,
          "direction": "sell",
          "block_trade_id": "66",
          "amount": 2.3
        },
        {
          "trade_seq": 41,
          "trade_id": "92460",
          "timestamp": 1565093070164,
          "tick_direction": 2,
          "state": "filled",
          "self_trade": false,
          "price": 11753,
          "order_type": "limit",
          "order_id": "343117",
          "matching_id": null,
          "liquidity": "M",
          "instrument_name": "BTC-9AUG19",
          "index_price": 11758.65,
          "fee_currency": "BTC",
          "fee": 0,
          "direction": "sell",
          "block_trade_id": "66",
          "amount": 50
        }
      ],
      "timestamp": 1565093070165,
      "initiator_user_id": 3,
      "id": "66",
      "executor_user_id": 12,
      "currency": "BTC"
    }
  ]
}

Returns list of last users block trades

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
The currency symbol
count false integer Number of requested items, default - 20
start_id false string The id of the newest block trade to be returned
end_id false string The id of the oldest block trade to be returned

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
  ›  currency string Currency, i.e "BTC", "ETH"
  ›  executor_user_id integer Id of user that executed block_trade
  ›  id string Block trade id
  ›  initiator_user_id integer Id of user that initiated block_trade
  ›  timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH"
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/private/invalidate_block_trade_signature

curl -X GET "https://testapp.deribit.com/api/v2/private/invalidate_block_trade_signature?signature=1565173369982.1M9tO0Q-.z9n9WyZUU5op9pEz6Jtd2CI71QxQMMsCZAexnIfK9HQRT1pKH3clxeIbY7Bqm-yMcWIoE3IfCDPW5VEdiN-6oS0YkKUyXPD500MUf3ULKhfkmH81EZs" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "method" : "private/invalidate_block_trade_signature",
  "params" : {
    "signature" : "1565173369982.1M9tO0Q-.z9n9WyZUU5op9pEz6Jtd2CI71QxQMMsCZAexnIfK9HQRT1pKH3clxeIbY7Bqm-yMcWIoE3IfCDPW5VEdiN-6oS0YkKUyXPD500MUf3ULKhfkmH81EZs"
  }
};
var ws = new WebSocket('wss://testapp.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/invalidate_block_trade_signature",
  "params" : {
    "signature" : "1565173369982.1M9tO0Q-.z9n9WyZUU5op9pEz6Jtd2CI71QxQMMsCZAexnIfK9HQRT1pKH3clxeIbY7Bqm-yMcWIoE3IfCDPW5VEdiN-6oS0YkKUyXPD500MUf3ULKhfkmH81EZs"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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",
  "result":"ok"
}

User at any time (before the private/execute_block_trade is called) can invalidate its own signature effectively cancelling block trade

Try in API console

Parameters

Parameter Required Type Enum Description
signature true string Signature of block trade that will be invalidated

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

curl -X GET "https://testapp.deribit.com/api/v2/private/verify_block_trade?currency=BTC&nonce=okpdjkdo&role=maker&timestamp=1565172650935&trades=%5B%7B%22price%22%3A11624%2C%22instrument_name%22%3A%22BTC-PERPETUAL%22%2C%22direction%22%3A%22buy%22%2C%22amount%22%3A40%7D%2C%7B%22price%22%3A0.0707%2C%22instrument_name%22%3A%22BTC-9AUG19-10250-P%22%2C%22direction%22%3A%22buy%22%2C%22amount%22%3A1.2%7D%5D" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "method" : "private/verify_block_trade",
  "params" : {
    "currency" : "BTC",
    "nonce" : "okpdjkdo",
    "timestamp" : 1565172650935,
    "role" : "maker",
    "trades" : [
      {
        "instrument_name" : "BTC-PERPETUAL",
        "direction" : "buy",
        "price" : 11624,
        "amount" : 40
      },
      {
        "instrument_name" : "BTC-9AUG19-10250-P",
        "direction" : "buy",
        "amount" : 1.2,
        "price" : 0.0707
      }
    ]
  }
};
var ws = new WebSocket('wss://testapp.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/verify_block_trade",
  "params" : {
    "currency" : "BTC",
    "nonce" : "okpdjkdo",
    "timestamp" : 1565172650935,
    "role" : "maker",
    "trades" : [
      {
        "instrument_name" : "BTC-PERPETUAL",
        "direction" : "buy",
        "price" : 11624,
        "amount" : 40
      },
      {
        "instrument_name" : "BTC-9AUG19-10250-P",
        "direction" : "buy",
        "amount" : 1.2,
        "price" : 0.0707
      }
    ]
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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",
  "result":{
    "signature":"1565172710935.1ESE83qh.g6fbgRd4VWagaJz7xdi2WaV-q-d3J0njoz1jZavuRudZJZif9uH8XdUAx1LHsu0E3e0ZG_xe1UPYlwo41xRVrkWU6OMgygDRafUkEmBuk9iLqjc9rh4"
  }
}

Verifies and creates block trade signature

Try in API console

Parameters

Parameter Required Type Enum Description
timestamp true integer Timestamp, shared with other party
nonce true string Nonce, shared with other party
role true string maker
taker
Describes if user wants to be maker or taker of trades
trades true array of objects List of trades for block trade
  ›  instrument_name true string Instrument name
  ›  price true number Price for trade
  ›  amount true number It represents the requested trade size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH
  ›  direction true string buy
sell
Direction of trade from the maker perspective
currency false string BTC
ETH
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
  ›  signature string Signature of block trade
It is valid only for 1 minute “around” given timestamp

Trading

/private/buy

curl -X GET "https://testapp.deribit.com/api/v2/private/buy?amount=40&instrument_name=ETH-PERPETUAL&label=market0000234&type=market" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-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://testapp.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://testapp.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": 14151,
        "trade_id": "ETH-37435",
        "timestamp": 1550657341322,
        "tick_direction": 2,
        "state": "closed",
        "self_trade": false,
        "price": 143.81,
        "order_type": "market",
        "order_id": "ETH-349249",
        "matching_id": null,
        "liquidity": "T",
        "label": "market0000234",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 143.73,
        "fee_currency": "ETH",
        "fee": 0.000139,
        "direction": "buy",
        "amount": 40
      }
    ],
    "order": {
      "time_in_force": "good_til_cancelled",
      "reduce_only": false,
      "profit_loss": 0,
      "price": "market_price",
      "post_only": false,
      "order_type": "market",
      "order_state": "filled",
      "order_id": "ETH-349249",
      "max_show": 40,
      "last_update_timestamp": 1550657341322,
      "label": "market0000234",
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "filled_amount": 40,
      "direction": "buy",
      "creation_timestamp": 1550657341322,
      "commission": 0.000139,
      "average_price": 143.81,
      "api": true,
      "amount": 40
    }
  }
}

Places a buy order for an instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
amount true number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH
type false string limit
stop_limit
market
stop_market
The order type, default: "limit"
label false string user defined label for the order (maximum 32 characters)
price false number

The order price in base currency (Only for limit and stop_limit orders)

When adding order with advanced=usd, the field price should be the option price value in USD.

When adding order with advanced=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%

time_in_force false string good_til_cancelled
fill_or_kill
immediate_or_cancel

Specifies how long the order remains in effect. Default "good_til_cancelled"

  • "good_til_cancelled" - unfilled order remains in order book until cancelled
  • "fill_or_kill" - execute a transaction immediately and completely or not at all
  • "immediate_or_cancel" - execute a transaction immediately, and any portion of the order that cannot be immediately filled is cancelled
max_show false number Maximum amount within an order to be shown to other customers, 0 for invisible order
post_only false boolean

If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below the bid.

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
stop_price false number Stop price, required for stop limit orders (Only for stop orders)
trigger false string index_price
mark_price
last_price
Defines trigger type, required for "stop_limit" order type
advanced false string usd
implv
Advanced option order type. (Only for options)

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
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  commission number Commission paid so far (in base currency)
  ›    ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  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.
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  is_liquidation boolean true if order was automatically created during liquidation
  ›    ›  label string user defined label (up to 32 characters)
  ›    ›  last_update_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›    ›  order_id string Unique order identifier
  ›    ›  order_state string order state, "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  order_type string order type, "limit", "market", "stop_limit", "stop_market"
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only boolean true for reduce-only orders only
  ›    ›  replaced boolean true if the order was modified (edited) via API, otherwise false.
  ›    ›  stop_order_id string Id of the stop order that was triggered to create the order (Only for orders that were created by triggered stop orders).
  ›    ›  stop_price number stop price (Only for future stop orders)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
  ›    ›  trigger string Trigger type (Only for stop orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  triggered boolean Whether the stop order has been triggered (Only for stop orders)
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH"
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/private/sell

curl -X GET "https://testapp.deribit.com/api/v2/private/sell?amount=123&instrument_name=ETH-PERPETUAL&price=1.45610000000000013642e%2B02&stop_price=145&trigger=last_price&type=stop_limit" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-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,
    "stop_price" : 145,
    "trigger" : "last_price"
  }
};
var ws = new WebSocket('wss://testapp.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,
    "stop_price" : 145,
    "trigger" : "last_price"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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",
      "stop_price": 145,
      "reduce_only": false,
      "profit_loss": 0,
      "price": 145.61,
      "post_only": false,
      "order_type": "stop_limit",
      "order_state": "untriggered",
      "order_id": "ETH-SLTS-28",
      "max_show": 123,
      "last_update_timestamp": 1550659803407,
      "label": "",
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "direction": "sell",
      "creation_timestamp": 1550659803407,
      "api": true,
      "amount": 123
    }
  }
}

Places a sell order for an instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
amount true number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH
type false string limit
stop_limit
market
stop_market
The order type, default: "limit"
label false string user defined label for the order (maximum 32 characters)
price false number

The order price in base currency (Only for limit and stop_limit orders)

When adding order with advanced=usd, the field price should be the option price value in USD.

When adding order with advanced=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%

time_in_force false string good_til_cancelled
fill_or_kill
immediate_or_cancel

Specifies how long the order remains in effect. Default "good_til_cancelled"

  • "good_til_cancelled" - unfilled order remains in order book until cancelled
  • "fill_or_kill" - execute a transaction immediately and completely or not at all
  • "immediate_or_cancel" - execute a transaction immediately, and any portion of the order that cannot be immediately filled is cancelled
max_show false number Maximum amount within an order to be shown to other customers, 0 for invisible order
post_only false boolean

If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below the bid.

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
stop_price false number Stop price, required for stop limit orders (Only for stop orders)
trigger false string index_price
mark_price
last_price
Defines trigger type, required for "stop_limit" order type
advanced false string usd
implv
Advanced option order type. (Only for options)

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
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  commission number Commission paid so far (in base currency)
  ›    ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  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.
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  is_liquidation boolean true if order was automatically created during liquidation
  ›    ›  label string user defined label (up to 32 characters)
  ›    ›  last_update_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›    ›  order_id string Unique order identifier
  ›    ›  order_state string order state, "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  order_type string order type, "limit", "market", "stop_limit", "stop_market"
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only boolean true for reduce-only orders only
  ›    ›  replaced boolean true if the order was modified (edited) via API, otherwise false.
  ›    ›  stop_order_id string Id of the stop order that was triggered to create the order (Only for orders that were created by triggered stop orders).
  ›    ›  stop_price number stop price (Only for future stop orders)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
  ›    ›  trigger string Trigger type (Only for stop orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  triggered boolean Whether the stop order has been triggered (Only for stop orders)
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH"
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/private/edit

curl -X GET "https://testapp.deribit.com/api/v2/private/edit?advanced=implv&amount=4&order_id=438994&price=222" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-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://testapp.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://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 3725,
  "result": {
    "trades": [],
    "order": {
      "time_in_force": "good_til_cancelled",
      "reduce_only": false,
      "profit_loss": 0,
      "price": 0.1448,
      "post_only": false,
      "order_type": "limit",
      "order_state": "open",
      "order_id": "438994",
      "max_show": 4,
      "last_update_timestamp": 1550585797677,
      "label": "",
      "is_liquidation": false,
      "instrument_name": "BTC-22FEB19-3500-C",
      "implv": 222,
      "filled_amount": 0,
      "direction": "buy",
      "creation_timestamp": 1550585741277,
      "commission": 0,
      "average_price": 0,
      "api": false,
      "amount": 4,
      "advanced": "implv"
    }
  }
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
order_id true string The order id
amount true number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH
price true 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 the bid.

Only valid in combination with time_in_force="good_til_cancelled"

advanced false string usd
implv
Advanced option order type. If you have posted an advanced option order, it is necessary to re-supply this parameter when editing it (Only for options)
stop_price false number Stop price, required for stop limit orders (Only for stop orders)

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
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  commission number Commission paid so far (in base currency)
  ›    ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  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.
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  is_liquidation boolean true if order was automatically created during liquidation
  ›    ›  label string user defined label (up to 32 characters)
  ›    ›  last_update_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›    ›  order_id string Unique order identifier
  ›    ›  order_state string order state, "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  order_type string order type, "limit", "market", "stop_limit", "stop_market"
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only boolean true for reduce-only orders only
  ›    ›  replaced boolean true if the order was modified (edited) via API, otherwise false.
  ›    ›  stop_order_id string Id of the stop order that was triggered to create the order (Only for orders that were created by triggered stop orders).
  ›    ›  stop_price number stop price (Only for future stop orders)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
  ›    ›  trigger string Trigger type (Only for stop orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  triggered boolean Whether the stop order has been triggered (Only for stop orders)
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH"
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/private/cancel

curl -X GET "https://testapp.deribit.com/api/v2/private/cancel?order_id=ETH-SLIS-12" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-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://testapp.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://testapp.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",
    "stop_price": 144.73,
    "reduce_only": false,
    "profit_loss": 0,
    "price": "market_price",
    "post_only": false,
    "order_type": "stop_market",
    "order_state": "untriggered",
    "order_id": "ETH-SLIS-12",
    "max_show": 5,
    "last_update_timestamp": 1550575961291,
    "label": "",
    "is_liquidation": false,
    "instrument_name": "ETH-PERPETUAL",
    "direction": "sell",
    "creation_timestamp": 1550575961291,
    "api": false,
    "amount": 5
  }
}

Cancel an order, specified by order id

Try in API console

Parameters

Parameter Required Type Enum Description
order_id true string The order id

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  commission number Commission paid so far (in base currency)
  ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  direction string Direction: buy, or sell
  ›  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.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  instrument_name string Unique instrument identifier
  ›  is_liquidation boolean true if order was automatically created during liquidation
  ›  label string user defined label (up to 32 characters)
  ›  last_update_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›  order_id string Unique order identifier
  ›  order_state string order state, "open", "filled", "rejected", "cancelled", "untriggered"
  ›  order_type string order type, "limit", "market", "stop_limit", "stop_market"
  ›  original_order_type string Original order type. Optional field
  ›  post_only boolean true for post-only orders only
  ›  price number Price in base currency
  ›  profit_loss number Profit and loss in base currency.
  ›  reduce_only boolean true for reduce-only orders only
  ›  replaced boolean true if the order was modified (edited) via API, otherwise false.
  ›  stop_order_id string Id of the stop order that was triggered to create the order (Only for orders that were created by triggered stop orders).
  ›  stop_price number stop price (Only for future stop orders)
  ›  time_in_force string Order time in force: "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
  ›  trigger string Trigger type (Only for stop orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  triggered boolean Whether the stop order has been triggered (Only for stop orders)
  ›  usd number Option price in USD (Only if advanced="usd")

/private/cancel_all

curl -X GET "https://testapp.deribit.com/api/v2/private/cancel_all?" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8748,
  "method" : "private/cancel_all",
  "params" : {

  }
};
var ws = new WebSocket('wss://testapp.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://testapp.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 stop orders within all currencies and instrument kinds.

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)
object
result number Total number of successfully cancelled orders

/private/cancel_all_by_currency

curl -X GET "https://testapp.deribit.com/api/v2/private/cancel_all_by_currency?currency=BTC&kind=option" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-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://testapp.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://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 5663,
  "result": 3
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
The currency symbol
kind false string future
option
Instrument kind, if not provided instruments of all kinds are considered
type false string all
limit
stop
Order type - limit, stop or all, default - all

Response

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

/private/cancel_all_by_instrument

curl -X GET "https://testapp.deribit.com/api/v2/private/cancel_all_by_instrument?instrument_name=ETH-22FEB19-120-P&type=all" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-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://testapp.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://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 4122,
  "result": 7
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
type false string all
limit
stop
Order type - limit, stop or all, default - all

Response

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

/private/close_position

curl -X GET "https://testapp.deribit.com/api/v2/private/close_position?instrument_name=ETH-PERPETUAL&price=1.45169999999999987494e%2B02&type=limit" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-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://testapp.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://testapp.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": 14147,
        "trade_id": "ETH-37431",
        "timestamp": 1550570832250,
        "tick_direction": 0,
        "state": "open",
        "self_trade": false,
        "price": 145.17,
        "order_type": "limit",
        "order_id": "ETH-349197",
        "matching_id": null,
        "liquidity": "T",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 144.82,
        "fee_currency": "ETH",
        "fee": 0.000034,
        "direction": "sell",
        "amount": 10
      }
    ],
    "order": {
      "time_in_force": "good_til_cancelled",
      "reduce_only": true,
      "profit_loss": 0,
      "price": 145.17,
      "post_only": false,
      "order_type": "limit",
      "order_state": "open",
      "order_id": "ETH-349197",
      "max_show": 27475,
      "last_update_timestamp": 1550570832250,
      "label": "",
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "filled_amount": 10,
      "direction": "sell",
      "creation_timestamp": 1550570832250,
      "commission": 0.000034,
      "average_price": 145.17,
      "api": false,
      "amount": 27475
    }
  }
}

Makes closing position reduce only order .

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  order object
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  commission number Commission paid so far (in base currency)
  ›    ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  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.
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  is_liquidation boolean true if order was automatically created during liquidation
  ›    ›  label string user defined label (up to 32 characters)
  ›    ›  last_update_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›    ›  order_id string Unique order identifier
  ›    ›  order_state string order state, "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  order_type string order type, "limit", "market", "stop_limit", "stop_market"
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  price number Price in base currency
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  reduce_only boolean true for reduce-only orders only
  ›    ›  replaced boolean true if the order was modified (edited) via API, otherwise false.
  ›    ›  stop_order_id string Id of the stop order that was triggered to create the order (Only for orders that were created by triggered stop orders).
  ›    ›  stop_price number stop price (Only for future stop orders)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
  ›    ›  trigger string Trigger type (Only for stop orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  triggered boolean Whether the stop order has been triggered (Only for stop orders)
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH"
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/private/get_margins

curl -X GET "https://testapp.deribit.com/api/v2/private/get_margins?amount=10000&instrument_name=BTC-PERPETUAL&price=3725" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-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://testapp.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://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

The above command returns JSON structured like this:

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

Get margins for given instrument, amount and price.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
amount true number Amount, integer for future, float for option. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
price true number Price

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  buy number Margin when buying
  ›  max_price number The maximum price for the future. Any buy orders you submit higher than this price, will be clamped to this maximum.
  ›  min_price number The minimum price for the future. Any sell orders you submit lower than this price will be clamped to this minimum.
  ›  sell number Margin when selling

/private/get_open_orders_by_currency

curl -X GET "https://testapp.deribit.com/api/v2/private/get_open_orders_by_currency?currency=BTC" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-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://testapp.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://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
    "jsonrpc": "2.0",
    "id": 1953,
    "result": [
        {
            "time_in_force": "good_til_cancelled",
            "reduce_only": false,
            "profit_loss": 0,
            "price": 0.0028,
            "post_only": false,
            "order_type": "limit",
            "order_state": "open",
            "order_id": "146062",
            "max_show": 10,
            "last_update_timestamp": 1550050597036,
            "label": "",
            "is_liquidation": false,
            "instrument_name": "BTC-15FEB19-3250-P",
            "filled_amount": 0,
            "direction": "buy",
            "creation_timestamp": 1550050597036,
            "commission": 0,
            "average_price": 0,
            "api": true,
            "amount": 10
        }
    ]
}

Retrieves list of user's open orders.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
The currency symbol
kind false string future
option
Instrument kind, if not provided instruments of all kinds are considered
type false string all
limit
stop_all
stop_limit
stop_market
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
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  commission number Commission paid so far (in base currency)
  ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  direction string Direction: buy, or sell
  ›  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.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  instrument_name string Unique instrument identifier
  ›  is_liquidation boolean true if order was automatically created during liquidation
  ›  label string user defined label (up to 32 characters)
  ›  last_update_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›  order_id string Unique order identifier
  ›  order_state string order state, "open", "filled", "rejected", "cancelled", "untriggered"
  ›  order_type string order type, "limit", "market", "stop_limit", "stop_market"
  ›  original_order_type string Original order type. Optional field
  ›  post_only boolean true for post-only orders only
  ›  price number Price in base currency
  ›  profit_loss number Profit and loss in base currency.
  ›  reduce_only boolean true for reduce-only orders only
  ›  replaced boolean true if the order was modified (edited) via API, otherwise false.
  ›  stop_order_id string Id of the stop order that was triggered to create the order (Only for orders that were created by triggered stop orders).
  ›  stop_price number stop price (Only for future stop orders)
  ›  time_in_force string Order time in force: "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
  ›  trigger string Trigger type (Only for stop orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  triggered boolean Whether the stop order has been triggered (Only for stop orders)
  ›  usd number Option price in USD (Only if advanced="usd")

/private/get_open_orders_by_instrument

curl -X GET "https://testapp.deribit.com/api/v2/private/get_open_orders_by_instrument?instrument_name=ETH-22FEB19-120-C" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-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://testapp.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://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
    "jsonrpc": "2.0",
    "id": 8442,
    "result": [
        {
            "time_in_force": "good_til_cancelled",
            "reduce_only": false,
            "profit_loss": 0,
            "price": 0.135,
            "post_only": false,
            "order_type": "limit",
            "order_state": "open",
            "order_id": "ETH-252017",
            "max_show": 10,
            "last_update_timestamp": 1550050594882,
            "label": "",
            "is_liquidation": false,
            "instrument_name": "ETH-22FEB19-120-C",
            "filled_amount": 0,
            "direction": "sell",
            "creation_timestamp": 1550050594882,
            "commission": 0,
            "average_price": 0,
            "api": true,
            "amount": 10
        }
    ]
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
type false string all
limit
stop_all
stop_limit
stop_market
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
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  commission number Commission paid so far (in base currency)
  ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  direction string Direction: buy, or sell
  ›  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.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  instrument_name string Unique instrument identifier
  ›  is_liquidation boolean true if order was automatically created during liquidation
  ›  label string user defined label (up to 32 characters)
  ›  last_update_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›  order_id string Unique order identifier
  ›  order_state string order state, "open", "filled", "rejected", "cancelled", "untriggered"
  ›  order_type string order type, "limit", "market", "stop_limit", "stop_market"
  ›  original_order_type string Original order type. Optional field
  ›  post_only boolean true for post-only orders only
  ›  price number Price in base currency
  ›  profit_loss number Profit and loss in base currency.
  ›  reduce_only boolean true for reduce-only orders only
  ›  replaced boolean true if the order was modified (edited) via API, otherwise false.
  ›  stop_order_id string Id of the stop order that was triggered to create the order (Only for orders that were created by triggered stop orders).
  ›  stop_price number stop price (Only for future stop orders)
  ›  time_in_force string Order time in force: "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
  ›  trigger string Trigger type (Only for stop orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  triggered boolean Whether the stop order has been triggered (Only for stop orders)
  ›  usd number Option price in USD (Only if advanced="usd")

/private/get_order_history_by_currency

curl -X GET "https://testapp.deribit.com/api/v2/private/get_order_history_by_currency?count=1&currency=BTC&kind=future" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9305,
  "method" : "private/get_order_history_by_currency",
  "params" : {
    "currency" : "BTC",
    "kind" : "future",
    "count" : 1
  }
};
var ws = new WebSocket('wss://testapp.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 9305,
  "result": [
    {
      "time_in_force": "good_til_cancelled",
      "reduce_only": false,
      "profit_loss": 0,
      "price": 3886.5,
      "post_only": false,
      "order_type": "limit",
      "order_state": "filled",
      "order_id": "146475",
      "max_show": 40,
      "last_update_timestamp": 1550661808761,
      "label": "",
      "is_liquidation": false,
      "instrument_name": "BTC-PERPETUAL",
      "filled_amount": 40,
      "direction": "buy",
      "creation_timestamp": 1550661808761,
      "commission": 0.00000547,
      "average_price": 3659.8,
      "api": true,
      "amount": 40
    }
  ]
}

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

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  commission number Commission paid so far (in base currency)
  ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  direction string Direction: buy, or sell
  ›  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.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  instrument_name string Unique instrument identifier
  ›  is_liquidation boolean true if order was automatically created during liquidation
  ›  label string user defined label (up to 32 characters)
  ›  last_update_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›  order_id string Unique order identifier
  ›  order_state string order state, "open", "filled", "rejected", "cancelled", "untriggered"
  ›  order_type string order type, "limit", "market", "stop_limit", "stop_market"
  ›  original_order_type string Original order type. Optional field
  ›  post_only boolean true for post-only orders only
  ›  price number Price in base currency
  ›  profit_loss number Profit and loss in base currency.
  ›  reduce_only boolean true for reduce-only orders only
  ›  replaced boolean true if the order was modified (edited) via API, otherwise false.
  ›  stop_order_id string Id of the stop order that was triggered to create the order (Only for orders that were created by triggered stop orders).
  ›  stop_price number stop price (Only for future stop orders)
  ›  time_in_force string Order time in force: "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
  ›  trigger string Trigger type (Only for stop orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  triggered boolean Whether the stop order has been triggered (Only for stop orders)
  ›  usd number Option price in USD (Only if advanced="usd")

/private/get_order_history_by_instrument

curl -X GET "https://testapp.deribit.com/api/v2/private/get_order_history_by_instrument?count=1&instrument_name=BTC-PERPETUAL" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 1032,
  "method" : "private/get_order_history_by_instrument",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "count" : 1
  }
};
var ws = new WebSocket('wss://testapp.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 1032,
  "result": [
    {
      "time_in_force": "good_til_cancelled",
      "reduce_only": false,
      "profit_loss": 0,
      "price": 3886.5,
      "post_only": false,
      "order_type": "limit",
      "order_state": "filled",
      "order_id": "146475",
      "max_show": 40,
      "last_update_timestamp": 1550661808761,
      "label": "",
      "is_liquidation": false,
      "instrument_name": "BTC-PERPETUAL",
      "filled_amount": 40,
      "direction": "buy",
      "creation_timestamp": 1550661808761,
      "commission": 0.00000547,
      "average_price": 3659.8,
      "api": true,
      "amount": 40
    }
  ]
}

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

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  commission number Commission paid so far (in base currency)
  ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  direction string Direction: buy, or sell
  ›  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.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  instrument_name string Unique instrument identifier
  ›  is_liquidation boolean true if order was automatically created during liquidation
  ›  label string user defined label (up to 32 characters)
  ›  last_update_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›  order_id string Unique order identifier
  ›  order_state string order state, "open", "filled", "rejected", "cancelled", "untriggered"
  ›  order_type string order type, "limit", "market", "stop_limit", "stop_market"
  ›  original_order_type string Original order type. Optional field
  ›  post_only boolean true for post-only orders only
  ›  price number Price in base currency
  ›  profit_loss number Profit and loss in base currency.
  ›  reduce_only boolean true for reduce-only orders only
  ›  replaced boolean true if the order was modified (edited) via API, otherwise false.
  ›  stop_order_id string Id of the stop order that was triggered to create the order (Only for orders that were created by triggered stop orders).
  ›  stop_price number stop price (Only for future stop orders)
  ›  time_in_force string Order time in force: "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
  ›  trigger string Trigger type (Only for stop orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  triggered boolean Whether the stop order has been triggered (Only for stop orders)
  ›  usd number Option price in USD (Only if advanced="usd")

/private/get_order_margin_by_ids

curl -X GET "https://testapp.deribit.com/api/v2/private/get_order_margin_by_ids?ids=%5B%22ETH-349280%22%2C%22ETH-349279%22%2C%22ETH-349278%22%5D" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5625,
  "method" : "private/get_order_margin_by_ids",
  "params" : {
    "ids" : [
      "ETH-349280",
      "ETH-349279",
      "ETH-349278"
    ]
  }
};
var ws = new WebSocket('wss://testapp.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 5625,
  "result": [
    {
      "order_id": "ETH-349278",
      "initial_margin": 0.00091156
    },
    {
      "order_id": "ETH-349279",
      "initial_margin": 0
    },
    {
      "order_id": "ETH-349280",
      "initial_margin": 0
    }
  ]
}

Retrieves initial margins of given orders

Try in API console

Parameters

Parameter Required Type Enum Description
ids true array Ids of orders

Response

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

/private/get_order_state

curl -X GET "https://testapp.deribit.com/api/v2/private/get_order_state?order_id=ETH-331562" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 4316,
  "method" : "private/get_order_state",
  "params" : {
    "order_id" : "ETH-331562"
  }
};
var ws = new WebSocket('wss://testapp.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 4316,
  "result": {
    "time_in_force": "good_til_cancelled",
    "reduce_only": false,
    "profit_loss": 0.051134,
    "price": 118.94,
    "post_only": false,
    "order_type": "limit",
    "order_state": "filled",
    "order_id": "ETH-331562",
    "max_show": 37,
    "last_update_timestamp": 1550219810944,
    "label": "",
    "is_liquidation": false,
    "instrument_name": "ETH-PERPETUAL",
    "filled_amount": 37,
    "direction": "sell",
    "creation_timestamp": 1550219749176,
    "commission": 0.000031,
    "average_price": 118.94,
    "api": false,
    "amount": 37
  }
}

Retrieve the current state of an order.

Try in API console

Parameters

Parameter Required Type Enum Description
order_id true string The order id

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  commission number Commission paid so far (in base currency)
  ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  direction string Direction: buy, or sell
  ›  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.
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  instrument_name string Unique instrument identifier
  ›  is_liquidation boolean true if order was automatically created during liquidation
  ›  label string user defined label (up to 32 characters)
  ›  last_update_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  max_show number Maximum amount within an order to be shown to other traders, 0 for invisible order.
  ›  order_id string Unique order identifier
  ›  order_state string order state, "open", "filled", "rejected", "cancelled", "untriggered"
  ›  order_type string order type, "limit", "market", "stop_limit", "stop_market"
  ›  original_order_type string Original order type. Optional field
  ›  post_only boolean true for post-only orders only
  ›  price number Price in base currency
  ›  profit_loss number Profit and loss in base currency.
  ›  reduce_only boolean true for reduce-only orders only
  ›  replaced boolean true if the order was modified (edited) via API, otherwise false.
  ›  stop_order_id string Id of the stop order that was triggered to create the order (Only for orders that were created by triggered stop orders).
  ›  stop_price number stop price (Only for future stop orders)
  ›  time_in_force string Order time in force: "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
  ›  trigger string Trigger type (Only for stop orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  triggered boolean Whether the stop order has been triggered (Only for stop orders)
  ›  usd number Option price in USD (Only if advanced="usd")

/private/get_stop_order_history

curl -X GET "https://testapp.deribit.com/api/v2/private/get_stop_order_history?count=10&currency=ETH" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2552,
  "method" : "private/get_stop_order_history",
  "params" : {
    "currency" : "ETH",
    "count" : 10
  }
};
var ws = new WebSocket('wss://testapp.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 2192,
  "result": [
    {
      "trigger": "index",
      "timestamp": 1555918941451,
      "stop_price": 5285,
      "stop_id": "SLIS-103",
      "order_state": "new",
      "request": "trigger:order",
      "price": 5179.28,
      "order_id": "671473",
      "offset": 277,
      "instrument_name": "BTC-PERPETUAL",
      "amount": 10,
      "direction": "buy"
    }
  ]
}

Retrieves detailed log of the user's stop-orders.

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  continuation string Continuation token for pagination.
  ›  entities object
  ›    ›  amount number It represents the requested order size. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  last_update_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›  order_id string Unique order identifier
  ›    ›  order_state string order state, "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  price number Price in base currency
  ›    ›  request string user or system request type for the stop order. "add" - to add order, "cancel" - to cancel, "edit" - to change order, "trigger:stop" - to trigger stop order, "trigger:order" - to spawn limit or market order as the result of the triggering "trigger:stop"
  ›    ›  stop_id string Id of the user stop-order used for the stop-order reference before triggering
  ›    ›  stop_price number stop price (Only for future stop orders)
  ›    ›  timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›  trigger string Trigger type (Only for stop orders). Allowed values: "index_price", "mark_price", "last_price".

/private/get_user_trades_by_currency

curl -X GET "https://testapp.deribit.com/api/v2/private/get_user_trades_by_currency?count=2&currency=ETH&start_id=ETH-34066" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9367,
  "method" : "private/get_user_trades_by_currency",
  "params" : {
    "currency" : "ETH",
    "start_id" : "ETH-34066",
    "count" : 2
  }
};
var ws = new WebSocket('wss://testapp.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 9367,
  "result": {
    "trades": [
      {
        "trade_seq": 3,
        "trade_id": "ETH-34066",
        "timestamp": 1550219814585,
        "tick_direction": 1,
        "state": "open",
        "self_trade": false,
        "reduce_only": false,
        "price": 0.04,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-334607",
        "matching_id": null,
        "liquidity": "M",
        "iv": 56.83,
        "instrument_name": "ETH-22FEB19-120-C",
        "index_price": 121.37,
        "fee_currency": "ETH",
        "fee": 0.0011,
        "direction": "buy",
        "amount": 11
      },
      {
        "trade_seq": 4,
        "trade_id": "ETH-36286",
        "timestamp": 1550219953466,
        "tick_direction": 1,
        "state": "closed",
        "self_trade": false,
        "reduce_only": false,
        "price": 0.04,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-334607",
        "matching_id": null,
        "liquidity": "M",
        "iv": 56.5,
        "instrument_name": "ETH-22FEB19-120-C",
        "index_price": 121.41,
        "fee_currency": "ETH",
        "fee": 0.000055,
        "direction": "buy",
        "amount": 0.55
      }
    ],
    "has_more": true
  }
}

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

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH"
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/private/get_user_trades_by_currency_and_time

curl -X GET "https://testapp.deribit.com/api/v2/private/get_user_trades_by_currency_and_time?count=2&currency=ETH&end_timestamp=1550219814586&start_timestamp=1550219991813" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9292,
  "method" : "private/get_user_trades_by_currency_and_time",
  "params" : {
    "currency" : "ETH",
    "start_timestamp" : 1550219991813,
    "end_timestamp" : 1550219814586,
    "count" : 2
  }
};
var ws = new WebSocket('wss://testapp.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9292,
  "method" : "private/get_user_trades_by_currency_and_time",
  "params" : {
    "currency" : "ETH",
    "start_timestamp" : 1550219991813,
    "end_timestamp" : 1550219814586,
    "count" : 2
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 9292,
  "result": {
    "trades": [
      {
        "trade_seq": 2,
        "trade_id": "ETH-36939",
        "timestamp": 1550219991813,
        "tick_direction": 1,
        "state": "closed",
        "self_trade": false,
        "reduce_only": false,
        "price": 0.004,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-345387",
        "matching_id": null,
        "liquidity": "T",
        "iv": 17.84,
        "instrument_name": "ETH-22FEB19-120-P",
        "index_price": 121.42,
        "fee_currency": "ETH",
        "fee": 0.000275,
        "direction": "sell",
        "amount": 0.55
      },
      {
        "trade_seq": 1,
        "trade_id": "ETH-36747",
        "timestamp": 1550219981078,
        "tick_direction": 1,
        "state": "closed",
        "self_trade": false,
        "reduce_only": false,
        "price": 0.004,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-344773",
        "matching_id": null,
        "liquidity": "T",
        "iv": 17.84,
        "instrument_name": "ETH-22FEB19-120-P",
        "index_price": 121.42,
        "fee_currency": "ETH",
        "fee": 0.06105,
        "direction": "sell",
        "amount": 122.1
      }
    ],
    "has_more": true
  }
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
The currency symbol
kind false string future
option
Instrument kind, if not provided instruments of all kinds are considered
start_timestamp true integer The earliest timestamp to return result for
end_timestamp true integer The most recent timestamp to return result for
count false integer Number of requested items, default - 10
include_old false boolean Include trades older than 7 days, default - false
sorting false string asc
desc
default
Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH"
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/private/get_user_trades_by_instrument

curl -X GET "https://testapp.deribit.com/api/v2/private/get_user_trades_by_instrument?count=2&instrument_name=ETH-PERPETUAL&start_seq=10722" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5728,
  "method" : "private/get_user_trades_by_instrument",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "start_seq" : 10722,
    "count" : 2
  }
};
var ws = new WebSocket('wss://testapp.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 5728,
  "result": {
    "trades": [
      {
        "trade_seq": 10722,
        "trade_id": "ETH-33999",
        "timestamp": 1550219810814,
        "tick_direction": 1,
        "state": "open",
        "self_trade": false,
        "reduce_only": false,
        "price": 118.94,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-331562",
        "matching_id": null,
        "liquidity": "M",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 121.37,
        "fee_currency": "ETH",
        "fee": 0.000007,
        "direction": "sell",
        "amount": 8
      },
      {
        "trade_seq": 10723,
        "trade_id": "ETH-34000",
        "timestamp": 1550219810816,
        "tick_direction": 1,
        "state": "open",
        "self_trade": false,
        "reduce_only": false,
        "price": 118.94,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-331562",
        "matching_id": null,
        "liquidity": "M",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 121.37,
        "fee_currency": "ETH",
        "fee": 0.000004,
        "direction": "sell",
        "amount": 5
      }
    ],
    "has_more": true
  }
}

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

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH"
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/private/get_user_trades_by_instrument_and_time

curl -X GET "https://testapp.deribit.com/api/v2/private/get_user_trades_by_instrument_and_time?end_timestamp=1550219715972&instrument_name=BTC-PERPETUAL&start_timestamp=1550150986031" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 276,
  "method" : "private/get_user_trades_by_instrument_and_time",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "start_timestamp" : 1550150986031,
    "end_timestamp" : 1550219715972
  }
};
var ws = new WebSocket('wss://testapp.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" : 276,
  "method" : "private/get_user_trades_by_instrument_and_time",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "start_timestamp" : 1550150986031,
    "end_timestamp" : 1550219715972
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 276,
  "result": {
    "trades": [
      {
        "trade_seq": 22295,
        "trade_id": "65211",
        "timestamp": 1550219715972,
        "tick_direction": 1,
        "state": "closed",
        "self_trade": false,
        "reduce_only": false,
        "price": 3595,
        "post_only": false,
        "order_type": "limit",
        "order_id": "438746",
        "matching_id": null,
        "liquidity": "M",
        "instrument_name": "BTC-PERPETUAL",
        "index_price": 3579.46,
        "fee_currency": "BTC",
        "fee": 5.6e-7,
        "direction": "buy",
        "amount": 20
      }
    ],
    "has_more": false
  }
}

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

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›  block_trade_id string Block trade id - when trade was part of block trade
  ›    ›  direction string Direction: buy, or sell
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH"
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  post_only string true if user order is post-only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
  ›    ›  state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/private/get_user_trades_by_order

curl -X GET "https://testapp.deribit.com/api/v2/private/get_user_trades_by_order?order_id=ETH-332357" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3466,
  "method" : "private/get_user_trades_by_order",
  "params" : {
    "order_id" : "ETH-332357"
  }
};
var ws = new WebSocket('wss://testapp.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" : 3466,
  "method" : "private/get_user_trades_by_order",
  "params" : {
    "order_id" : "ETH-332357"
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 3466,
  "result": [
    {
      "trade_seq": 9910,
      "trade_id": "ETH-33186",
      "timestamp": 1550219763047,
      "tick_direction": 1,
      "state": "closed",
      "self_trade": false,
      "reduce_only": false,
      "price": 118.92,
      "post_only": false,
      "order_type": "limit",
      "order_id": "ETH-332357",
      "matching_id": null,
      "liquidity": "T",
      "instrument_name": "ETH-PERPETUAL",
      "index_price": 121.37,
      "fee_currency": "ETH",
      "fee": 0.000139,
      "direction": "buy",
      "amount": 33
    }
  ]
}

Retrieve the list of user trades that was created for given order

Try in API console

Parameters

Parameter Required Type Enum Description
order_id true string The order id
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)
array of amount number
block_trade_id string Block trade id - when trade was part of block trade
direction string Direction: buy, or sell
fee number User's fee in units of the specified fee_currency
fee_currency string Currency, i.e "BTC", "ETH"
index_price number Index Price at the moment of trade
instrument_name string Unique instrument identifier
iv number Option implied volatility for the price (Option only)
label string User defined label (presented only when previously set for order by user)
liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
matching_id string Always null, except for a self-trade which is possible only if self-trading is switched on for the account (in that case this will be id of the maker order of the subscriber)
order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
order_type string Order type: "limit, "market", or "liquidation"
post_only string true if user order is post-only
price number Price in base currency
reduce_only string true if user order is reduce-only
self_trade boolean true if the trade is against own order. This can only happen when your account has self-trading enabled. Contact an administrator if you think you need that
state string order state, "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
timestamp integer The timestamp of the trade
trade_id string Unique (per currency) trade identifier
trade_seq integer The sequence number of the trade within instrument

/private/get_settlement_history_by_instrument

curl -X GET "https://testapp.deribit.com/api/v2/private/get_settlement_history_by_instrument?count=1&instrument_name=ETH-22FEB19&type=settlement" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2192,
  "method" : "private/get_settlement_history_by_instrument",
  "params" : {
    "instrument_name" : "ETH-22FEB19",
    "type" : "settlement",
    "count" : 1
  }
};
var ws = new WebSocket('wss://testapp.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" : 2192,
  "method" : "private/get_settlement_history_by_instrument",
  "params" : {
    "instrument_name" : "ETH-22FEB19",
    "type" : "settlement",
    "count" : 1
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 2192,
  "result": {
    "settlements": [
      {
        "type": "settlement",
        "timestamp": 1550475692526,
        "session_profit_loss": 0.038358299,
        "profit_loss": -0.001783937,
        "position": -66,
        "mark_price": 121.67,
        "instrument_name": "ETH-22FEB19",
        "index_price": 119.8
      }
    ],
    "continuation": "xY7T6cusbMBNpH9SNmKb94jXSBxUPojJEdCPL4YociHBUgAhWQvEP"
  }
}

Retrieves 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

Response

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

/private/get_settlement_history_by_currency

curl -X GET "https://testapp.deribit.com/api/v2/private/get_settlement_history_by_currency?count=1&currency=BTC&type=delivery" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8304,
  "method" : "private/get_settlement_history_by_currency",
  "params" : {
    "currency" : "BTC",
    "type" : "delivery",
    "count" : 1
  }
};
var ws = new WebSocket('wss://testapp.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" : 8304,
  "method" : "private/get_settlement_history_by_currency",
  "params" : {
    "currency" : "BTC",
    "type" : "delivery",
    "count" : 1
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 6074,
  "result": {
    "settlements": [
      {
        "type": "delivery",
        "timestamp": 1550242800013,
        "session_profit_loss": 1.567969302,
        "profit_loss": -0.251617338,
        "position": 13,
        "mark_price": 0.121679828,
        "instrument_name": "BTC-15FEB19-4000-P",
        "index_price": 3566.08
      }
    ],
    "continuation": "AHmpC39UH5EeGVjryrf731YEhjL16oqCQorSvBFZFAbbwvCN7GCbMFgno7U5JKW"
  }
}

Retrieves settlement, delivery and bankruptcy events that have affected your account.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
The currency symbol
type false string settlement
delivery
bankruptcy
Settlement type
count false integer Number of requested items, default - 20

Response

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

Market data

/public/get_book_summary_by_currency

curl -X GET "https://testapp.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://testapp.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://testapp.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",
      "open_interest": 0,
      "mid_price": null,
      "mark_price": 3579.73,
      "low": null,
      "last": null,
      "instrument_name": "BTC-22FEB19",
      "high": null,
      "estimated_delivery_price": 3579.73,
      "creation_timestamp": 1550230036440,
      "bid_price": null,
      "base_currency": "BTC",
      "ask_price": null
    },
    {
      "volume_usd": 22440,
      "volume": 6.24,
      "quote_currency": "USD",
      "open_interest": 183180,
      "mid_price": null,
      "mark_price": 3579.73,
      "low": 3591,
      "last": 3595,
      "instrument_name": "BTC-PERPETUAL",
      "high": 3595,
      "funding_8h": 0.0002574,
      "estimated_delivery_price": 3579.73,
      "current_funding": 0,
      "creation_timestamp": 1550230036440,
      "bid_price": null,
      "base_currency": "BTC",
      "ask_price": null
    }
  ]
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
The currency symbol
kind false string future
option
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 (seconds since the Unix epoch, with millisecond precision)
  ›  current_funding number Current funding (perpetual only)
  ›  estimated_delivery_price number Estimated delivery price, in USD. For more details, see Documentation > General > Expiration Price
  ›  funding_8h number Funding 8h (perpetual only)
  ›  high number Price of the 24h highest trade
  ›  instrument_name string Unique instrument identifier
  ›  interest_rate number Interest rate used in implied volatility calculations (options only)
  ›  last number The price of the latest trade, null if there weren't any trades
  ›  low number Price of the 24h lowest trade, null if there weren't any trades
  ›  mark_price number The current instrument market price
  ›  mid_price number The average of the best bid and ask, null if there aren't any asks or bids
  ›  open_interest number The total amount of outstanding contracts in the corresponding amount units. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  quote_currency string Quote currency
  ›  underlying_index string Name of the underlying future, or 'index_price' (options only)
  ›  underlying_price number underlying price for implied volatility calculations (options only)
  ›  volume number The total 24h traded volume (in base currency)
  ›  volume_usd number Volume in usd (futures only)

/public/get_book_summary_by_instrument

curl -X GET "https://testapp.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://testapp.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://testapp.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",
      "open_interest": 0.55,
      "mid_price": 0.2444,
      "mark_price": 0.179112,
      "low": 0.34,
      "last": 0.34,
      "interest_rate": 0.207,
      "instrument_name": "ETH-22FEB19-140-P",
      "high": 0.34,
      "creation_timestamp": 1550227952163,
      "bid_price": 0.1488,
      "base_currency": "ETH",
      "ask_price": 0.34
    }
  ]
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  ask_price number The current best ask price, null if there aren't any asks
  ›  base_currency string Base currency
  ›  bid_price number The current best bid price, null if there aren't any bids
  ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  current_funding number Current funding (perpetual only)
  ›  estimated_delivery_price number Estimated delivery price, in USD. For more details, see Documentation > General > Expiration Price
  ›  funding_8h number Funding 8h (perpetual only)
  ›  high number Price of the 24h highest trade
  ›  instrument_name string Unique instrument identifier
  ›  interest_rate number Interest rate used in implied volatility calculations (options only)
  ›  last number The price of the latest trade, null if there weren't any trades
  ›  low number Price of the 24h lowest trade, null if there weren't any trades
  ›  mark_price number The current instrument market price
  ›  mid_price number The average of the best bid and ask, null if there aren't any asks or bids
  ›  open_interest number The total amount of outstanding contracts in the corresponding amount units. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  quote_currency string Quote currency
  ›  underlying_index string Name of the underlying future, or 'index_price' (options only)
  ›  underlying_price number underlying price for implied volatility calculations (options only)
  ›  volume number The total 24h traded volume (in base currency)
  ›  volume_usd number Volume in usd (futures only)

/public/get_contract_size

curl -X GET "https://testapp.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://testapp.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://testapp.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 BTC.

/public/get_currencies

curl -X GET "https://testapp.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://testapp.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://testapp.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",
          "disabled_deposit_address_creation": false,
          "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",
          "disabled_deposit_address_creation": false,
          "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.
  ›  disabled_deposit_address_creation boolean False if deposit address creation is disabled
  ›  fee_precision integer fee precision
  ›  min_confirmations integer Minimum number of block chain confirmations before deposit is accepted.
  ›  min_withdrawal_fee number The minimum transaction fee paid for withdrawals
  ›  withdrawal_fee number The total transaction fee paid for withdrawals
  ›  withdrawal_priorities array of object
  ›    ›  name string
  ›    ›  value number

/public/get_funding_chart_data

curl -X GET "https://testapp.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://testapp.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://testapp.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": [[1543306440000, -0.05649]],
        "index_price": 1234.23,
        "interest_8h": 0.0040080897,
        "max": 0.005
    }
}

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

Try in API console

Parameters

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

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 [timestamp, value]
  ›  index_price number Current index price
  ›  interest_8h number Current interest 8h
  ›  max number maximal interest

/public/get_historical_volatility

curl -X GET "https://testapp.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://testapp.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://testapp.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
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://testapp.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://testapp.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://testapp.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
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_instruments

curl -X GET "https://testapp.deribit.com/api/v2/public/get_instruments?currency=BTC&expired=false&kind=future" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7617,
  "method" : "public/get_instruments",
  "params" : {
    "currency" : "BTC",
    "kind" : "future",
    "expired" : false
  }
};
var ws = new WebSocket('wss://testapp.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 7617,
  "method" : "public/get_instruments",
  "params" : {
    "currency" : "BTC",
    "kind" : "future",
    "expired" : false
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7617,
  "result": [
    {
      "tick_size": 0.01,
      "taker_commission": 0.0005,
      "settlement_period": "week",
      "quote_currency": "USD",
      "min_trade_amount": 1,
      "maker_commission": 0.0001,
      "leverage": 100,
      "kind": "future",
      "is_active": true,
      "instrument_name": "BTC-26JUL19",
      "expiration_timestamp": 1564153200000,
      "creation_timestamp": 1563522420000,
      "contract_size": 10,
      "base_currency": "BTC"
    },
    {
      "tick_size": 0.01,
      "taker_commission": 0.0005,
      "settlement_period": "perpetual",
      "quote_currency": "USD",
      "min_trade_amount": 1,
      "maker_commission": 0.0001,
      "leverage": 100,
      "kind": "future",
      "is_active": true,
      "instrument_name": "BTC-PERPETUAL",
      "expiration_timestamp": 32503734000000,
      "creation_timestamp": 1554806122000,
      "contract_size": 10,
      "base_currency": "BTC"
    }
  ]
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
The currency symbol
kind false string future
option
Instrument kind, if not provided instruments of all kinds are considered
expired false boolean Set to true to show 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.
  ›  contract_size integer Contract size for instrument
  ›  creation_timestamp integer The time when the instrument was first created (milliseconds)
  ›  expiration_timestamp integer The time when the instrument will expire (milliseconds)
  ›  instrument_name string Unique instrument identifier
  ›  is_active boolean Indicates if the instrument can currently be traded.
  ›  kind string Instrument kind, "future" or "option"
  ›  leverage integer Maximal leverage for instrument, for futures only
  ›  maker_commission number Maker commission for instrument
  ›  min_trade_amount number Minimum amount for trading. For perpetual and futures - in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  option_type string The option type (only for options)
  ›  quote_currency string The currency in which the instrument prices are quoted.
  ›  settlement_period string The settlement period.
  ›  strike number The strike value. (only for options)
  ›  taker_commission number Taker commission for instrument
  ›  tick_size number specifies minimal price change and, as follows, the number of decimal places for instrument prices

/public/get_last_settlements_by_currency

curl -X GET "https://testapp.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://testapp.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://testapp.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 4497,
  "result": {
    "settlements": [
      {
        "type": "delivery",
        "timestamp": 1550242800013,
        "session_profit_loss": 4.703907906,
        "profit_loss": -0.427669766,
        "position": 64,
        "mark_price": 0.121679828,
        "instrument_name": "BTC-15FEB19-4000-P",
        "index_price": 3566.08
      },
      {
        "type": "delivery",
        "timestamp": 1550242800013,
        "session_profit_loss": 3.135938604,
        "profit_loss": -2.539278115,
        "position": 206,
        "mark_price": 0,
        "instrument_name": "BTC-15FEB19-4000-C",
        "index_price": 3566.08
      }
    ],
    "continuation": "29XjjMM7Zc6U4oytmV27f7a6YRb5aSdVijwfuYhHRTLphugjRf1edP8uGLo3w2mWKV23QgrxsmenRGqzucc7"
  }
}

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

Try in API console

Parameters

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

Response

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

/public/get_last_settlements_by_instrument

curl -X GET "https://testapp.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://testapp.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://testapp.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 5482,
  "result": {
    "settlements": [
      {
        "type": "settlement",
        "timestamp": 1550502000023,
        "session_profit_loss": 0.116509752,
        "profit_loss": -9.999999999886402e-10,
        "position": 240,
        "mark_price": 3578.16,
        "instrument_name": "BTC-22FEB19",
        "index_price": 3796.43
      }
    ],
    "continuation": "2Z7mdtavzYvfuyYcHkJXvPTr9ZSMsEzM3sLCH7AbYEDd1AzTXY2hnhegQDiaP1TtU4b5iSJZ4"
  }
}

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

Try in API console

Parameters

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

Response

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

/public/get_last_trades_by_currency

curl -X GET "https://testapp.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://testapp.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://testapp.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": 1158,
                "trade_id": "48487",
                "timestamp": 1550050596164,
                "tick_direction": 0,
                "price": 0.0964,
                "iv": 274.25,
                "instrument_name": "BTC-15FEB19-3500-C",
                "index_price": 3579.05,
                "direction": "buy",
                "amount": 2
            }
        ],
        "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
The currency symbol
kind false string future
option
Instrument kind, if not provided instruments of all kinds are considered
start_id false string The ID number of the first trade to be returned
end_id false string The ID number of the last trade to be returned
count false integer Number of requested items, default - 10
include_old false boolean Include trades older than 7 days, default - false
sorting false string asc
desc
default
Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

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

/public/get_last_trades_by_currency_and_time

curl -X GET "https://testapp.deribit.com/api/v2/public/get_last_trades_by_currency_and_time?count=1&currency=BTC&end_timestamp=1550055556414&start_timestamp=1550045469414" \
-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" : 1550045469414,
    "end_timestamp" : 1550055556414,
    "count" : 1
  }
};
var ws = new WebSocket('wss://testapp.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" : 1550045469414,
    "end_timestamp" : 1550055556414,
    "count" : 1
  }
}

async def call_api(msg):
   async with websockets.connect('wss://testapp.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": 794,
                "trade_id": "42399",
                "timestamp": 1550049108751,
                "tick_direction": 2,
                "price": 0.1347,
                "iv": 397.1,
                "instrument_name": "BTC-15FEB19-3500-C",
                "index_price": 3582.95,
                "direction": "buy",
                "amount": 4
            }
        ],
        "has_more": true
    }
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
The currency symbol
kind false string future
option
Instrument kind, if not provided instruments of all kinds are considered
start_timestamp true integer The earliest timestamp to return result for
end_timestamp true integer The most recent timestamp to return result for
count false integer Number of requested items, default - 10
include_old false boolean Include trades older than 7 days, default - false
sorting false string asc
desc
default
Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and futures - in USD units, for options it is amount