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.

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

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 microseconds (last 3 digits could be 000). 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:

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

e.g. (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}"

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

JSON-RPC over websocket

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

JSON-RPC over HTTP

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

Methods

Authentication

/public/auth

curl -X GET "https://test.deribit.com/api/v2/public/auth?client_id=fo7WAPRm4P&client_secret=W0H6FJW4IRPZ1MOQ8FP6KMC5RZDUUKXS&grant_type=client_credentials" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9929,
  "method" : "public/auth",
  "params" : {
    "grant_type" : "client_credentials",
    "client_id" : "fo7WAPRm4P",
    "client_secret" : "W0H6FJW4IRPZ1MOQ8FP6KMC5RZDUUKXS"
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

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

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

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

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

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

Three methods of authentication are supported:

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

Try in API console

Parameters

Parameter Required Type Enum Description
grant_type true string password
client_credentials
client_signature
refresh_token
Method of authentication
username true string Required for grant type password
password true string Required for grant type password
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 string 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
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, session:name, trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none]

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

/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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
    {"jsonrpc": "2.0",
     "method": "private/logout",
     "id": 42,
     "params": {
        "access_token": "7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG"}
    }

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

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

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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9098,
  "method" : "public/set_heartbeat",
  "params" : {
    "interval" : 30
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 9098,
  "result": "ok"
}

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

Try in API console

Parameters

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

Response

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

/public/disable_heartbeat

This method is only available via websockets.

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

  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 3562,
    "result": "ok"
}

Stop sending heartbeat messages.

Try in API console

Parameters

This method takes no parameters

Response

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

/private/enable_cancel_on_disconnect

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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7859,
  "result": "ok"
}

Enable 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

/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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 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://test.deribit.com/api/v2/public/get_time?" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7365,
  "method" : "public/get_time",
  "params" : {

  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 7365,
  "method" : "public/get_time",
  "params" : {

  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7365,
  "result": 1550147385946
}

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

Try in API console

Parameters

This method takes no parameters

Response

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

/public/hello

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2841,
  "method" : "public/hello",
  "params" : {
    "client_name" : "My Trading Software",
    "client_version" : "1.0.2"
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 2841,
  "method" : "public/hello",
  "params" : {
    "client_name" : "My Trading Software",
    "client_version" : "1.0.2"
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 2841,
    "result": {
        "version": "1.2.26"
    }
}

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

Try in API console

Parameters

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

Response

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

/public/test

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

  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 8212,
  "method" : "public/test",
  "params" : {

  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 8212,
  "result": {
    "version": "1.2.26"
  }
}

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

Try in API console

Parameters

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

Response

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

Subscription management

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

/public/subscribe

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3600,
  "method" : "public/subscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 3600,
  "result": [
    "deribit_price_index.btc_usd"
  ]
}

Subscribe to one or more channels.

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

Try in API console

Parameters

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

Response

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

/public/unsubscribe

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8691,
  "method" : "public/unsubscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 8691,
  "result": [
    "deribit_price_index.btc_usd"
  ]
}

Unsubscribe from one or more channels.

Try in API console

Parameters

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

Response

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

/private/subscribe

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 4235,
  "method" : "private/subscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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

/private/unsubscribe

This method is only available via websockets.

var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3370,
  "method" : "private/unsubscribe",
  "params" : {
    "channels" : [
      "deribit_price_index.btc_usd"
    ]
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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

Account management

/public/get_announcements

curl -X GET "https://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 7661,
  "method" : "public/get_announcements",
  "params" : {

  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7661,
  "result": [
    {
      "title": "Example announcement",
      "publication_time": 1550058362418,
      "important": false,
      "id": 1550058362418,
      "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    }
  ]
}

Retrieves announcements from the last 30 days.

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

curl -X GET "https://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 3964,
  "method" : "private/change_subaccount_name",
  "params" : {
    "sid" : 7,
    "name" : "new_user_1_1"
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 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_subaccount

curl -X GET "https://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 5414,
  "method" : "private/create_subaccount",
  "params" : {

  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 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_tfa_for_subaccount

curl -X GET "https://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 7640,
  "method" : "private/disable_tfa_for_subaccount",
  "params" : {
    "sid" : 7
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 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/get_account_summary

curl -X GET "https://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 2515,
  "method" : "private/get_account_summary",
  "params" : {
    "currency" : "BTC",
    "extended" : true
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 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
  ›  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
  ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9265,
  "method" : "private/get_email_language",
  "params" : {

  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 3022,
  "method" : "private/get_new_announcements",
  "params" : {

  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 404,
  "method" : "private/get_position",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL"
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 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",
      "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 or sell
  ›  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"
  ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 2236,
  "method" : "private/get_positions",
  "params" : {
    "currency" : "BTC",
    "kind" : "future"
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 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",
          "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 or sell
  ›    ›  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"
  ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 4947,
  "method" : "private/get_subaccounts",
  "params" : {
    "with_portfolio" : true
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 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/set_announcement_as_read

curl -X GET "https://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 5147,
  "method" : "private/set_announcement_as_read",
  "params" : {
    "announcement_id" : 1550058362418
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 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_email_for_subaccount

curl -X GET "https://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 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://test.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
    "jsonrpc": "2.0",
    "id": 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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 3269,
  "method" : "private/set_email_language",
  "params" : {
    "language" : "en"
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 5819,
  "method" : "private/set_password_for_subaccount",
  "params" : {
    "sid" : 7,
    "password" : "ABCDEFGHIJKLMO"
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9995,
  "method" : "private/toggle_notifications_from_subaccount",
  "params" : {
    "sid" : 7,
    "state" : true
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 938,
  "method" : "private/toggle_subaccount_login",
  "params" : {
    "sid" : 7,
    "state" : "enable"
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 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

Trading

/private/buy

curl -X GET "https://test.deribit.com/api/v2/private/buy?amount=40&instrument_name=ETH-PERPETUAL&label=market0000234&type=market" \
-H "Authorization: Bearer 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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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
  ›    ›  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"
  ›    ›  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
  ›    ›  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.
  ›    ›    ›  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)
  ›    ›    ›  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"
  ›    ›    ›  price number Price in base currency
  ›    ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 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://test.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 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
  ›    ›  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"
  ›    ›  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
  ›    ›  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.
  ›    ›    ›  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)
  ›    ›    ›  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"
  ›    ›    ›  price number Price in base currency
  ›    ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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
  ›    ›  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"
  ›    ›  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
  ›    ›  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.
  ›    ›    ›  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)
  ›    ›    ›  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"
  ›    ›    ›  price number Price in base currency
  ›    ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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
  ›  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"
  ›  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
  ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 8748,
  "result": "ok"
}

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)
result string Result of method execution. ok in case of success

/private/cancel_all_by_currency

curl -X GET "https://test.deribit.com/api/v2/private/cancel_all_by_currency?currency=BTC&kind=option" \
-H "Authorization: Bearer 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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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": "ok"
}

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)
result string Result of method execution. ok in case of success

/private/cancel_all_by_instrument

curl -X GET "https://test.deribit.com/api/v2/private/cancel_all_by_instrument?instrument_name=ETH-22FEB19-120-P&type=all" \
-H "Authorization: Bearer 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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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": "ok"
}

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)
result string Result of method execution. ok in case of success

/private/close_position

curl -X GET "https://test.deribit.com/api/v2/private/close_position?instrument_name=ETH-PERPETUAL&price=1.45169999999999987494e%2B02&type=limit" \
-H "Authorization: Bearer 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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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
  ›    ›  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"
  ›    ›  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
  ›    ›  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.
  ›    ›    ›  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)
  ›    ›    ›  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"
  ›    ›    ›  price number Price in base currency
  ›    ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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
  ›    ›  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"
  ›    ›  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
  ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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
  ›    ›  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"
  ›    ›  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
  ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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
  ›    ›  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"
  ›    ›  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
  ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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
  ›    ›  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"
  ›    ›  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
  ›    ›  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://test.deribit.com/api/v2/private/get_order_margin_by_ids?ids=ETH-349280ETH-349279ETH-349278" \
-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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

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

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

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

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

Retrieves initial margins of given orders

Try in API console

Parameters

Parameter Required Type Enum Description
ids true array Ids of orders

Response

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

/private/get_order_state

curl -X GET "https://test.deribit.com/api/v2/private/get_order_state?order_id=ETH-331562" \
-H "Authorization: Bearer 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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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
  ›  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"
  ›  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
  ›  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_user_trades_by_currency

curl -X GET "https://test.deribit.com/api/v2/private/get_user_trades_by_currency?count=2&currency=ETH&start_id=ETH-34066" \
-H "Authorization: Bearer 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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       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,
        "price": 0.04,
        "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,
        "price": 0.04,
        "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.
  ›    ›    ›  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)
  ›    ›    ›  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"
  ›    ›    ›  price number Price in base currency
  ›    ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 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://test.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 9292,
  "result": {
    "trades": [
      {
        "trade_seq": 2,
        "trade_id": "ETH-36939",
        "timestamp": 1550219991813,
        "tick_direction": 1,
        "state": "closed",
        "self_trade": false,
        "price": 0.004,
        "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,
        "price": 0.004,
        "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.
  ›    ›    ›  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)
  ›    ›    ›  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"
  ›    ›    ›  price number Price in base currency
  ›    ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 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://test.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 5728,
  "result": {
    "trades": [
      {
        "trade_seq": 10722,
        "trade_id": "ETH-33999",
        "timestamp": 1550219810814,
        "tick_direction": 1,
        "state": "open",
        "self_trade": false,
        "price": 118.94,
        "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,
        "price": 118.94,
        "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.
  ›    ›    ›  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)
  ›    ›    ›  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"
  ›    ›    ›  price number Price in base currency
  ›    ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 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://test.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 276,
  "result": {
    "trades": [
      {
        "trade_seq": 22295,
        "trade_id": "65211",
        "timestamp": 1550219715972,
        "tick_direction": 1,
        "state": "closed",
        "self_trade": false,
        "price": 3595,
        "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.
  ›    ›    ›  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)
  ›    ›    ›  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"
  ›    ›    ›  price number Price in base currency
  ›    ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 3466,
  "method" : "private/get_user_trades_by_order",
  "params" : {
    "order_id" : "ETH-332357"
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 3466,
  "result": [
    {
      "trade_seq": 9910,
      "trade_id": "ETH-33186",
      "timestamp": 1550219763047,
      "tick_direction": 1,
      "state": "closed",
      "self_trade": false,
      "price": 118.92,
      "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 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.
  ›  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)
  ›  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"
  ›  price number Price in base currency
  ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 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://test.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 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://test.deribit.com/ws/api/v2') as websocket:
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

{
  "jsonrpc": "2.0",
  "id": 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://test.deribit.com/api/v2/public/get_book_summary_by_currency?currency=BTC&kind=future" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9344,
  "method" : "public/get_book_summary_by_currency",
  "params" : {
    "currency" : "BTC",
    "kind" : "future"
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9344,
  "method" : "public/get_book_summary_by_currency",
  "params" : {
    "currency" : "BTC",
    "kind" : "future"
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 9344,
  "result": [
    {
      "volume_usd": 0,
      "volume": 0,
      "quote_currency": "USD",
      "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 (futures only). 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://test.deribit.com/api/v2/public/get_book_summary_by_instrument?instrument_name=ETH-22FEB19-140-P" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3659,
  "method" : "public/get_book_summary_by_instrument",
  "params" : {
    "instrument_name" : "ETH-22FEB19-140-P"
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 3659,
  "method" : "public/get_book_summary_by_instrument",
  "params" : {
    "instrument_name" : "ETH-22FEB19-140-P"
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 3659,
  "result": [
    {
      "volume": 0.55,
      "underlying_price": 121.38,
      "underlying_index": "index_price",
      "quote_currency": "USD",
      "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 (futures only). 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://test.deribit.com/api/v2/public/get_contract_size?instrument_name=BTC-PERPETUAL" \
-H "Content-Type: application/json"
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_contract_size",
     "id": 42,
     "params": {
        "instrument_name": "BTC-PERPETUAL"}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
    {"jsonrpc": "2.0",
     "method": "public/get_contract_size",
     "id": 42,
     "params": {
        "instrument_name": "BTC-PERPETUAL"}
    }

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

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

The above command returns JSON structured like this:

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

Retrieves contract size of provided instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

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

/public/get_currencies

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

  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 7538,
  "method" : "public/get_currencies",
  "params" : {

  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7538,
  "result": [
      {
          "coin_type": "ETHER"
          "currency": "ETH",
          "currency_long": "Ethereum",
          "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://test.deribit.com/api/v2/public/get_funding_chart_data?instrument_name=BTC-PERPETUAL&length=8h" \
-H "Content-Type: application/json"
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_funding_chart_data",
     "id": 42,
     "params": {
        "instrument_name": "BTC-PERPETUAL",
        "length": "8h"}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
    {"jsonrpc": "2.0",
     "method": "public/get_funding_chart_data",
     "id": 42,
     "params": {
        "instrument_name": "BTC-PERPETUAL",
        "length": "8h"}
    }

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

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

The above command returns JSON structured like this:

{
    "jsonrpc": "2.0",
    "result": {
        "current_interest": 0.0050006706,
        "data": [[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://test.deribit.com/api/v2/public/get_historical_volatility?currency=BTC" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 8387,
  "method" : "public/get_historical_volatility",
  "params" : {
    "currency" : "BTC"
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 8387,
  "method" : "public/get_historical_volatility",
  "params" : {
    "currency" : "BTC"
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 8387,
  "result": [
      [
          1549720800000,
          14.747743607344217
      ],
      [
          1549720800000,
          14.747743607344217
      ],
      [
          1549724400000,
          14.74257778551467
      ],
      [
          1549728000000,
          14.73502799931767
      ],
      [
          1549731600000,
          14.73502799931767
      ],
      [
          1549735200000,
          14.73502799931767
      ],
      [
          1550228400000,
          46.371891307340015
      ]
  ]
}

Provides information about historical volatility for given cryptocurrency.

Try in API console

Parameters

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

Response

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

/public/get_index

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

msg = \
    {"jsonrpc": "2.0",
     "method": "public/get_index",
     "id": 42,
     "params": {
        "currency": "BTC"}
    }

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

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

The above command returns JSON structured like this:

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

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

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
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://test.deribit.com/api/v2/public/get_instruments?currency=BTC&expired=false&kind=future" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7617,
  "method" : "public/get_instruments",
  "params" : {
    "currency" : "BTC",
    "kind" : "future",
    "expired" : false
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7617,
  "result": [
    {
      "tick_size": 0.01,
      "settlement_period": "week",
      "quote_currency": "USD",
      "min_trade_amount": 1,
      "kind": "future",
      "is_active": true,
      "instrument_name": "BTC-15FEB19",
      "expiration_timestamp": 1550228400000,
      "creation_timestamp": 1549537259000,
      "contract_size": 10,
      "base_currency": "BTC"
    },
    {
      "tick_size": 0.25,
      "settlement_period": "perpetual",
      "quote_currency": "USD",
      "min_trade_amount": 1,
      "kind": "future",
      "is_active": true,
      "instrument_name": "BTC-PERPETUAL",
      "expiration_timestamp": 32503728600000,
      "creation_timestamp": 1548148886000,
      "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"
  ›    ›  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)
  ›    ›  tick_size number specifies minimal price change and, as follows, the number of decimal places for instrument prices

/public/get_last_settlements_by_currency

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

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 4497,
  "method" : "public/get_last_settlements_by_currency",
  "params" : {
    "currency" : "BTC",
    "type" : "delivery",
    "count" : 2
  }
}

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

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

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

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

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

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
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://test.deribit.com/api/v2/public/get_last_settlements_by_instrument?count=1&instrument_name=BTC-22FEB19&type=settlement" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5482,
  "method" : "public/get_last_settlements_by_instrument",
  "params" : {
    "instrument_name" : "BTC-22FEB19",
    "type" : "settlement",
    "count" : 1
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 5482,
  "method" : "public/get_last_settlements_by_instrument",
  "params" : {
    "instrument_name" : "BTC-22FEB19",
    "type" : "settlement",
    "count" : 1
  }
}

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

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

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

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

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

Try in API console

Parameters

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

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://test.deribit.com/api/v2/public/get_last_trades_by_currency?count=1&currency=BTC" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9290,
  "method" : "public/get_last_trades_by_currency",
  "params" : {
    "currency" : "BTC",
    "count" : 1
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9290,
  "method" : "public/get_last_trades_by_currency",
  "params" : {
    "currency" : "BTC",
    "count" : 1
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 9290,
    "result": {
        "trades": [
            {
                "trade_seq": 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_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.
  ›    ›    ›  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)
  ›    ›    ›  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://test.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://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 1469,
  "method" : "public/get_last_trades_by_currency_and_time",
  "params" : {
    "currency" : "BTC",
    "start_timestamp" : 1550045469414,
    "end_timestamp" : 1550055556414,
    "count" : 1
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 1469,
    "result": {
        "trades": [
            {
                "trade_seq": 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 of corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›    ›    ›  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)
  ›    ›    ›  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_instrument

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

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9267,
  "method" : "public/get_last_trades_by_instrument",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "count" : 1
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 9267,
    "result": {
        "trades": [
            {
                "trade_seq": 2427,
                "trade_id": "48470",
                "timestamp": 1550050591859,
                "tick_direction": 2,
                "price": 3610,
                "instrument_name": "BTC-PERPETUAL",
                "index_price": 3579.08,
                "direction": "sell",
                "amount": 10
            }
        ],
        "has_more": true
    }
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_seq false integer The sequence number of the first trade to be returned
end_seq false integer The sequence number of the last trade to be returned
count false integer Number of requested items, default - 10
include_old false boolean Include trades older than 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.
  ›    ›    ›  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)
  ›    ›    ›  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_instrument_and_time

curl -X GET "https://test.deribit.com/api/v2/public/get_last_trades_by_instrument_and_time?count=1&end_timestamp=1550055556414&instrument_name=ETH-PERPETUAL" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3983,
  "method" : "public/get_last_trades_by_instrument_and_time",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "end_timestamp" : 1550055556414,
    "count" : 1
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 3983,
  "method" : "public/get_last_trades_by_instrument_and_time",
  "params" : {
    "instrument_name" : "ETH-PERPETUAL",
    "end_timestamp" : 1550055556414,
    "count" : 1
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 6952,
    "result": {
        "trades": [
            {
                "trade_seq": 24240,
                "trade_id": "ETH-73127",
                "timestamp": 1550050594998,
                "tick_direction": 0,
                "price": 122.26,
                "instrument_name": "ETH-PERPETUAL",
                "index_price": 121.67,
                "direction": "buy",
                "amount": 40
            }
        ],
        "has_more": true
    }
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_timestamp true integer The earliest timestamp to return result for
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.
  ›    ›    ›  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)
  ›    ›    ›  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_order_book

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

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 8772,
  "method" : "public/get_order_book",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL",
    "depth" : 5
  }
}

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

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

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

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

        ]
    }
}

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

Try in API console

Parameters

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

Response

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

/public/get_trade_volumes

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

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 6387,
  "method" : "public/get_trade_volumes"
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 6387,
  "result": [
    {
      "puts_volume": 48,
      "futures_volume": 6.2557,
      "currency_pair": "btc_usd",
      "calls_volume": 145
    },
    {
      "puts_volume": 122.65,
      "futures_volume": 374.3921,
      "currency_pair": "eth_usd",
      "calls_volume": 37.4
    }
  ]
}

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

Try in API console

Parameters

This method takes no parameters

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›    ›  calls_volume number Total 24h trade volume for call options. This is expressed in the base currency, e.g. BTC for btc_usd
  ›    ›  currency_pair string Currency pair: "btc_usd" or "eth_usd"
  ›    ›  futures_volume number Total 24h trade volume for futures. This is expressed in the base currency, e.g. BTC for btc_usd
  ›    ›  puts_volume number Total 24h trade volume for put options. This is expressed in the base currency, e.g. BTC for btc_usd

/public/ticker

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

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 8106,
  "method" : "public/ticker",
  "params" : {
    "instrument_name" : "BTC-PERPETUAL"
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 8106,
  "result": {
    "best_ask_amount": 3010
    "best_ask_price": 3562.75,
    "best_bid_amount": 135710,
    "best_bid_price": 3562.5,
    "current_funding": 0,
    "funding_8h": 0.00018344,
    "index_price": 3563.53,
    "instrument_name": "BTC-PERPETUAL",
    "last_price": 3562.25,
    "mark_price": 3562.62,
    "max_price": 3598.21,
    "min_price": 3526.96,
    "open_interest": 23126.924145440054,
    "settlement_price": 3573.77,
    "state": "open",
    "stats": {
      "volume": 85934.31950267,
      "low": 3492,
      "high": 3660.25
    },
    "timestamp": 1550153198202
  }
}

Get ticker for an instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

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

Wallet

/private/cancel_transfer_by_id

curl -X GET "https://test.deribit.com/api/v2/private/cancel_transfer_by_id?currency=BTC&id=2" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 9187,
  "method" : "private/cancel_transfer_by_id",
  "params" : {
    "currency" : "BTC",
    "id" : 2
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 9187,
  "method" : "private/cancel_transfer_by_id",
  "params" : {
    "currency" : "BTC",
    "id" : 2
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 9187,
    "result": {
        "amount": 0.2,
        "created_timestamp": 1550579457727,
        "currency": "BTC",
        "direction": "payment",
        "id": 2,
        "other_side": "2MzyQc5Tkik61kJbEpJV5D5H9VfWHZK9Sgy",
        "state": "cancelled",
        "type": "user",
        "updated_timestamp": 1550579457727
    }
}

Cancel transfer

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
The currency symbol
id true integer Id of transfer
tfa false string TFA code, required when TFA is enabled for current account

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  amount number Amount of funds in given currency
  ›  created_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  currency string Currency, i.e "BTC", "ETH"
  ›  direction string Transfer direction
  ›  id integer Id of transfer
  ›  other_side string For transfer from/to subaccount returns this subaccount name, for transfer to other account returns address, for transfer from other account returns that accounts username.
  ›  state string Transfer state, allowed values : prepared, confirmed, cancelled, waiting_for_admin, rejection_reason
  ›  type string Type of transfer: user - sent to user, subaccount - sent to subaccount
  ›  updated_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/cancel_withdrawal

curl -X GET "https://test.deribit.com/api/v2/private/cancel_withdrawal?currency=BTC&id=1" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7420,
  "method" : "private/cancel_withdrawal",
  "params" : {
    "currency" : "BTC",
    "id" : 1
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 7420,
  "method" : "private/cancel_withdrawal",
  "params" : {
    "currency" : "BTC",
    "id" : 1
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 7420,
    "result": {
        "address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz",
        "amount": 0.5,
        "confirmed_timestamp": null,
        "created_timestamp": 1550571443070,
        "currency": "BTC",
        "fee": 0.0001,
        "id": 1,
        "priority": 0.15,
        "state": "cancelled",
        "transaction_id": null,
        "updated_timestamp": 1550571443070
    }
}

Cancels withdrawal request

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
The currency symbol
id true number The withdrawal 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
  ›  address string Address in proper format for currency
  ›  amount number Amount of funds in given currency
  ›  confirmed_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision) of withdrawal confirmation, null when not confirmed
  ›  created_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  currency string Currency, i.e "BTC", "ETH"
  ›  fee number Fee in currency
  ›  id integer Withdrawal id in Deribit system
  ›  priority number Id of priority level
  ›  state string Withdrawal state, allowed values : unconfirmed, confirmed, cancelled, completed, interrupted, rejected
  ›  transaction_id string Transaction id in proper format for currency, null if id is not available
  ›  updated_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/create_deposit_address

curl -X GET "https://test.deribit.com/api/v2/private/create_deposit_address?currency=BTC" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7538,
  "method" : "private/create_deposit_address",
  "params" : {
    "currency" : "BTC"
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

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

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

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

{
    "jsonrpc": "2.0",
    "id": 7538,
    "result": {
        "address": "2N8udZGBc1hLRCFsU9kGwMPpmYUwMFTuCwB",
        "creation_timestamp": 1550575165170,
        "currency": "BTC",
        "type": "deposit"
    }
}

Creates deposit address in 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
  ›  address string Address in proper format for currency
  ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  currency string Currency, i.e "BTC", "ETH"
  ›  type string Address type/purpose, allowed values : deposit, withdrawal, transfer

/private/get_current_deposit_address

curl -X GET "https://test.deribit.com/api/v2/private/get_current_deposit_address?currency=BTC" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 3461,
  "method" : "private/get_current_deposit_address",
  "params" : {
    "currency" : "BTC"
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

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

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

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

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

{
    "jsonrpc": "2.0",
    "id": 3461,
    "result": {
        "address": "2N8udZGBc1hLRCFsU9kGwMPpmYUwMFTuCwB",
        "creation_timestamp": 1550575165170,
        "currency": "BTC",
        "type": "deposit"
    }
}


Retrieve deposit address for 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
  ›  address string Address in proper format for currency
  ›  creation_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  currency string Currency, i.e "BTC", "ETH"
  ›  type string Address type/purpose, allowed values : deposit, withdrawal, transfer

/private/get_deposits

curl -X GET "https://test.deribit.com/api/v2/private/get_deposits?count=10&currency=BTC&offset=0" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 5611,
  "method" : "private/get_deposits",
  "params" : {
    "currency" : "BTC",
    "count" : 10,
    "offset" : 0
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 5611,
  "method" : "private/get_deposits",
  "params" : {
    "currency" : "BTC",
    "count" : 10,
    "offset" : 0
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 5611,
  "result": {
        "count": 1,
        "data": [
          {
              "address": "2N35qDKDY22zmJq9eSyiAerMD4enJ1xx6ax",
              "amount": 5,
              "currency": "BTC",
              "received_timestamp": 1549295017670,
              "state": "completed",
              "transaction_id": "230669110fdaf0a0dbcdc079b6b8b43d5af29cc73683835b9bc6b3406c065fda",
              "updated_timestamp": 1549295130159
          }
      ]
  }
}

Retrieve the latest users deposits

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 - 10
offset false integer The offset for pagination, default - 0

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  count integer Total number of results available
  ›  data array of object
  ›    ›    ›  address string Address in proper format for currency
  ›    ›    ›  amount number Amount of funds in given currency
  ›    ›    ›  currency string Currency, i.e "BTC", "ETH"
  ›    ›    ›  received_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›    ›  state string Deposit state, allowed values : pending, completed, rejected, replaced
  ›    ›    ›  transaction_id string Transaction id in proper format for currency, null if id is not available
  ›    ›    ›  updated_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/get_transfers

curl -X GET "https://test.deribit.com/api/v2/private/get_transfers?count=10&currency=BTC" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 7606,
  "method" : "private/get_transfers",
  "params" : {
    "currency" : "BTC",
    "count" : 10
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 7606,
  "method" : "private/get_transfers",
  "params" : {
    "currency" : "BTC",
    "count" : 10
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 7606,
    "result": {
        "count": 2,
        "data": [
            {
                "amount": 0.2,
                "created_timestamp": 1550579457727,
                "currency": "BTC",
                "direction": "payment",
                "id": 2,
                "other_side": "2MzyQc5Tkik61kJbEpJV5D5H9VfWHZK9Sgy",
                "state": "prepared",
                "type": "user",
                "updated_timestamp": 1550579457727
            },
            {
                "amount": 0.3,
                "created_timestamp": 1550579255800,
                "currency": "BTC",
                "direction": "payment",
                "id": 1,
                "other_side": "new_user_1_1",
                "state": "confirmed",
                "type": "subaccount",
                "updated_timestamp": 1550579255800
            }
        ]
    }
}

Adds new entry to address book of given type

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 - 10
offset false integer The offset for pagination, default - 0

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  count integer Total number of results available
  ›  data array of object
  ›    ›    ›  amount number Amount of funds in given currency
  ›    ›    ›  created_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›    ›  currency string Currency, i.e "BTC", "ETH"
  ›    ›    ›  direction string Transfer direction
  ›    ›    ›  id integer Id of transfer
  ›    ›    ›  other_side string For transfer from/to subaccount returns this subaccount name, for transfer to other account returns address, for transfer from other account returns that accounts username.
  ›    ›    ›  state string Transfer state, allowed values : prepared, confirmed, cancelled, waiting_for_admin, rejection_reason
  ›    ›    ›  type string Type of transfer: user - sent to user, subaccount - sent to subaccount
  ›    ›    ›  updated_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/get_withdrawals

curl -X GET "https://test.deribit.com/api/v2/private/get_withdrawals?count=10&currency=BTC&offset=0" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 2745,
  "method" : "private/get_withdrawals",
  "params" : {
    "currency" : "BTC",
    "count" : 10,
    "offset" : 0
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 2745,
  "method" : "private/get_withdrawals",
  "params" : {
    "currency" : "BTC",
    "count" : 10,
    "offset" : 0
  }
}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 2745,
  "result": {
      "count": 1,
      "data": [
          {
              "address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz",
              "amount": 0.5,
              "confirmed_timestamp": null,
              "created_timestamp": 1550571443070,
              "currency": "BTC",
              "fee": 0.0001,
              "id": 1,
              "priority": 0.15,
              "state": "unconfirmed",
              "transaction_id": null,
              "updated_timestamp": 1550571443070
          }
      ]
  }
}

Retrieve the latest users withdrawals

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 - 10
offset false integer The offset for pagination, default - 0

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  count integer Total number of results available
  ›  data array of object
  ›    ›    ›  address string Address in proper format for currency
  ›    ›    ›  amount number Amount of funds in given currency
  ›    ›    ›  confirmed_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision) of withdrawal confirmation, null when not confirmed
  ›    ›    ›  created_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›    ›    ›  currency string Currency, i.e "BTC", "ETH"
  ›    ›    ›  fee number Fee in currency
  ›    ›    ›  id integer Withdrawal id in Deribit system
  ›    ›    ›  priority number Id of priority level
  ›    ›    ›  state string Withdrawal state, allowed values : unconfirmed, confirmed, cancelled, completed, interrupted, rejected
  ›    ›    ›  transaction_id string Transaction id in proper format for currency, null if id is not available
  ›    ›    ›  updated_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

/private/withdraw

curl -X GET "https://test.deribit.com/api/v2/private/withdraw?address=2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz&amount=4.00000000000000022204e-01&currency=BTC&priority=mid" \
-H "Authorization: Bearer 7Lsh6H8HGWHAXfZqq2dDWdQGcR991Swt2idyWyv74nWG" \
-H "Content-Type: application/json"
var msg = 
{
  "jsonrpc" : "2.0",
  "id" : 6931,
  "method" : "private/withdraw",
  "params" : {
    "currency" : "BTC",
    "address" : "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz",
    "amount" : 0.4,
    "priority" : "mid"
  }
};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

msg = \
{
  "jsonrpc" : "2.0",
  "id" : 6931,
  "method" : "private/withdraw",
  "params" : {
    "currency" : "BTC",
    "address" : "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz",
    "amount" : 0.4,
    "priority" : "mid"
  }
}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 6931,
    "result": {
        "address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz",
        "amount": 0.4,
        "confirmed_timestamp": null,
        "created_timestamp": 1550574558607,
        "currency": "BTC",
        "fee": 0.0001,
        "id": 4,
        "priority": 1,
        "state": "unconfirmed",
        "transaction_id": null,
        "updated_timestamp": 1550574558607
    }
}

Creates a new withdrawal request

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
The currency symbol
address true string Address in currency format, it must be in address book
amount true number Amount of funds to be withdrawn
priority false string insane
extreme_high
very_high
high
mid
low
very_low
Withdrawal priority, optional for BTC, default: high
tfa false string TFA code, required when TFA is enabled for current account

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  address string Address in proper format for currency
  ›  amount number Amount of funds in given currency
  ›  confirmed_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision) of withdrawal confirmation, null when not confirmed
  ›  created_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)
  ›  currency string Currency, i.e "BTC", "ETH"
  ›  fee number Fee in currency
  ›  id integer Withdrawal id in Deribit system
  ›  priority number Id of priority level
  ›  state string Withdrawal state, allowed values : unconfirmed, confirmed, cancelled, completed, interrupted, rejected
  ›  transaction_id string Transaction id in proper format for currency, null if id is not available
  ›  updated_timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

Subscriptions

The subscribe method can be used to subscribe to one or more channels. This section provides an overview of the channels and the notifications that the subscriber will receive for each of those channels.

In most cases the channel name is constructed from a couple of elements. This makes it possible to specify exactly which information is required, and/or the frequency or aggregation level. These elements are considered parameters for the subscription.

For example, when subscribing to the channel book.BTC-27JUL18.10.20.100ms, the element BTC-27JUL18 specifies that the name of the instrument (see naming), 10 means that the results should be grouped to that precision, etc.

As described in notifications, response data includes fields required by JSON-RPC and part dedicated for subscription data.

Name Type Description
jsonrpc string The JSON-RPC version (2.0)
method string Here it's always subscription
params object
  ›  channel string The same channel as given when subscribing to notifications
  ›  data object Data specific for the channel

For all the following channel types only specific data part will be described.

announcements

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["announcements"]}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the notifications...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

# To subscribe to this channel:
msg = \
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["announcements"]}
    }

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

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

This subscription will send next notifications like this:

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
         "channel": "announcements",
         "data": {
            "body": "string",
            "date": 1532593832021,
            "id": 42,
            "important": true,
            "title": "string"
        }
    }
}

General announcements concerning the Deribit platform.

Try in API console

Channel Parameters

This channel takes no parameters

Response

Name Type Description
action string
body string
date integer milliseconds since the Unix epoch
id integer
important boolean
number integer
title string

book.{instrument_name}.{group}.{depth}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["book.ETH-PERPETUAL.1.1.100ms"]}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the notifications...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

# To subscribe to this channel:
msg = \
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["book.ETH-PERPETUAL.1.1.100ms"]}
    }

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

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

This subscription will send first notification like this:

{
  "params" : {
    "data" : {
      "timestamp" : 1550760491966,
      "instrument_name" : "ETH-PERPETUAL",
      "change_id" : 813386,
      "bids" : [
        [
          133,
          121
        ]
      ],
      "asks" : [
        [
          134,
          3064
        ]
      ]
    },
    "channel" : "book.ETH-PERPETUAL.1.1.100ms"
  },
  "method" : "subscription",
  "jsonrpc" : "2.0"
}

This subscription will send next notifications like this:

{
  "params" : {
    "data" : {
      "timestamp" : 1550761724221,
      "instrument_name" : "ETH-PERPETUAL",
      "change_id" : 813395,
      "bids" : [
        [
          133,
          121
        ]
      ],
      "asks" : [
        [
          134,
          3061
        ]
      ]
    },
    "channel" : "book.ETH-PERPETUAL.1.1.100ms"
  },
  "method" : "subscription",
  "jsonrpc" : "2.0"
}

Notifies about changes to the order book for a certain instrument.

Notifications are sent once per specified interval, with prices grouped by (rounded to) the specified group, showing the complete order book to the specified depth (number of price levels).

The 'asks' and the 'bids' elements in the response are both a 'list of lists'. Each element in the outer list is a list of exactly two elements: price and amount.

price is a price level (USD per BTC, rounded as specified by the 'group' parameter for the susbcription).

amount indicates the amount of all orders at price level. For perpetual and futures the amount is in USD units, for options it is amount of corresponding cryptocurrency contracts, e.g., BTC or ETH.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
group true string none
1
2
5
10
Group prices (by rounding). Use none for no grouping.
depth true integer 1
10
20
Number of price levels to be included.
interval true string 100ms Frequency of notifications. Events will be aggregated over this interval.

Response

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

book.{instrument_name}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["book.BTC-PERPETUAL.100ms"]}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the notifications...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

# To subscribe to this channel:
msg = \
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["book.BTC-PERPETUAL.100ms"]}
    }

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

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

This subscription will send first notification like this:

{
  "params" : {
    "data" : {
      "timestamp" : 1550761777012,
      "instrument_name" : "BTC-PERPETUAL",
      "change_id" : 475300,
      "bids" : [
        [
          "new",
          3940.75,
          258.96
        ],
        [
          "new",
          3423,
          125.15
        ]
      ],
      "asks" : [

      ]
    },
    "channel" : "book.BTC-PERPETUAL.100ms"
  },
  "method" : "subscription",
  "jsonrpc" : "2.0"
}

This subscription will send next notifications like this:

{
  "params" : {
    "data" : {
      "timestamp" : 1550761828101,
      "previous_change_id" : 475300,
      "instrument_name" : "BTC-PERPETUAL",
      "change_id" : 475368,
      "bids" : [

      ],
      "asks" : [
        [
          "new",
          3958.25,
          50
        ]
      ]
    },
    "channel" : "book.BTC-PERPETUAL.100ms"
  },
  "method" : "subscription",
  "jsonrpc" : "2.0"
}

Notifies about changes to the order book for a certain instrument.

The first notification will contain the whole book (bid and ask amounts for all prices). After that there will only be information about changes to individual price levels.

The first notification will contain the amounts for all price levels (list of ['new', price, amount] tuples). All following notifications will contain a list of tuples with action, price level and new amount ([action, price, amount]). Action can be either new, change or delete.

Each notification will contain a change_id field, and each message except for the first one will contain a field prev_change_id. If prev_change_id is equal to the change_id of the previous message, this means that no messages have been missed.

The amount for perpetual and futures is in USD units, for options it is in corresponding cryptocurrency contracts, e.g., BTC or ETH.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
interval true string raw
100ms
Frequency of notifications. Events will be aggregated over this interval.

Response

Name Type Description
asks array of [action, price, amount] The first notification will contain the amounts for all price levels (a list of ["new", price, amount] tuples). All following notifications will contain a list of tuples with action, price level and new amount ([action, price, amount]). Action can be 'new', 'change' or 'delete'.
bids array of [action, price, amount] (See 'asks' above.)
change_id integer id of the notification
instrument_name string Unique instrument identifier
prev_change_id integer id of the previous notification
timestamp integer The timestamp of last change (seconds since the Unix epoch, with millisecond precision)

deribit_price_index.{index_name}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["deribit_price_index.btc_usd"]}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the notifications...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

# To subscribe to this channel:
msg = \
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["deribit_price_index.btc_usd"]}
    }

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

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

This subscription will send next notifications like this:

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

Provides information about current value (price) for Deribit Index

Try in API console

Channel Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd
Index identifier, matches (base) cryptocurrency with quote currency

Response

Name Type Description
index_name string
price number Current value of Deribit Index
timestamp integer The timestamp (seconds since the Unix epoch, with millisecond precision)

deribit_price_ranking.{index_name}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["deribit_price_ranking.btc_usd"]}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the notifications...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

# To subscribe to this channel:
msg = \
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["deribit_price_ranking.btc_usd"]}
    }

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

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

This subscription will send next notifications like this:

{
  "params" : {
    "data" : [
      {
        "weight" : 0,
        "timestamp" : 1550650265694,
        "price" : 4001.15,
        "identifier" : "bitfinex",
        "enabled" : true
      },
      {
        "weight" : 25,
        "timestamp" : 1550650264392,
        "price" : 3891.43,
        "identifier" : "bitstamp",
        "enabled" : true
      },
      {
        "weight" : 25,
        "timestamp" : 1550650265693,
        "price" : 3891.32,
        "identifier" : "gdax",
        "enabled" : true
      },
      {
        "weight" : 0,
        "timestamp" : 1550650265698,
        "price" : 3889.36,
        "identifier" : "gemini",
        "enabled" : true
      },
      {
        "weight" : 25,
        "timestamp" : 1550650263372,
        "price" : 3889.5,
        "identifier" : "itbit",
        "enabled" : true
      },
      {
        "weight" : 25,
        "timestamp" : 1550650246566,
        "price" : 3890.8,
        "identifier" : "kraken",
        "enabled" : true
      }
    ],
    "channel" : "deribit_price_ranking.btc_usd"
  },
  "method" : "subscription",
  "jsonrpc" : "2.0"
}

Provides information about current value (price) for stock exchanges used to calculate Deribit Index

Try in API console

Channel Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd
Index identifier, matches (base) cryptocurrency with quote currency

Response

Name Type Description
array of object
  ›  enabled boolean Stock exchange status
  ›  identifier string Stock exchange identifier
  ›  price number Stock exchange index price
  ›  timestamp integer The timestamp of the last update from stock exchange
  ›  weight number The weight of the ranking given in percent

estimated_expiration_price.{index_name}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["estimated_expiration_price.btc_usd"]}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the notifications...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

# To subscribe to this channel:
msg = \
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["estimated_expiration_price.btc_usd"]}
    }

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

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

This subscription will send next notifications like this:

{
  "params" : {
    "data" : {
      "seconds" : 180929,
      "price" : 3939.73,
      "is_estimated" : false
    },
    "channel" : "estimated_expiration_price.btc_usd"
  },
  "method" : "subscription",
  "jsonrpc" : "2.0"
}

Returns calculated (estimated) ending price for given index.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd
Index identifier, matches (base) cryptocurrency with quote currency

Response

Name Type Description
is_estimated boolean When true then prize is given as an estimated value, otherwise it's current index price
price number Index current or estimated price
seconds integer Number of seconds till finalizing the nearest instrument

markprice.options.{index_name}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["markprice.options.btc_usd"]}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the notifications...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

# To subscribe to this channel:
msg = \
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["markprice.options.btc_usd"]}
    }

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

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

This subscription will send next notifications like this:

{
  "params" : {
    "data" : [
      {
        "mark_price" : 0.06968487603001122,
        "iv" : 1.5000001635583038,
        "instrument_name" : "BTC-22FEB19-3750-C"
      },
      {
        "mark_price" : 0.11710577915095444,
        "iv" : 1.5000001635583038,
        "instrument_name" : "BTC-22FEB19-3500-C"
      },
      {
        "mark_price" : 0.09814100017129308,
        "iv" : 1.5000001635583038,
        "instrument_name" : "BTC-22FEB19-4250-P"
      },
      {
        "mark_price" : 0.008084913622698415,
        "iv" : 1.5000001635583038,
        "instrument_name" : "BTC-22FEB19-3500-P"
      },
      {
        "mark_price" : 0.03613861512644225,
        "iv" : 1.5000001635583038,
        "instrument_name" : "BTC-22FEB19-4000-C"
      }
    ],
    "channel" : "markprice.options.btc_usd"
  },
  "method" : "subscription",
  "jsonrpc" : "2.0"
}

Provides information about options markprices.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd
Index identifier, matches (base) cryptocurrency with quote currency

Response

Name Type Description
array of object
  ›  instrument_name string Unique instrument identifier
  ›  iv number Value of the volatility of the underlying instrument
  ›  mark_price number The mark price for the instrument

perpetual.{instrument_name}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["perpetual.BTC-PERPETUAL.raw"]}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the notifications...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

# To subscribe to this channel:
msg = \
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["perpetual.BTC-PERPETUAL.raw"]}
    }

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

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

This subscription will send next notifications like this:

{
  "params" : {
    "data" : {
      "interest" : 0.004999511380756577
    },
    "channel" : "perpetual.BTC-PERPETUAL.raw"
  },
  "method" : "subscription",
  "jsonrpc" : "2.0"
}

Provide current interest rate - but only for perpetual instruments. Other types won't generate any notification.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
interval true string 100ms
raw
Frequency of notifications. Events will be aggregated over this interval. The value raw means no aggregation will be applied

Response

Name Type Description
interest number Current interest

quote.{instrument_name}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["quote.BTC-PERPETUAL"]}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the notifications...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

# To subscribe to this channel:
msg = \
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["quote.BTC-PERPETUAL"]}
    }

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

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

This subscription will send next notifications like this:

{
  "params" : {
    "data" : {
      "timestamp" : 1550658624149,
      "instrument_name" : "BTC-PERPETUAL",
      "best_bid_price" : 3914.97,
      "best_bid_amount" : 40,
      "best_ask_price" : 3996.61,
      "best_ask_amount" : 50
    },
    "channel" : "quote.BTC-PERPETUAL"
  },
  "method" : "subscription",
  "jsonrpc" : "2.0"
}

Best bid/ask price and size.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

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

ticker.{instrument_name}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["ticker.BTC-PERPETUAL.raw"]}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the notifications...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};
import asyncio
import websockets
import json

# To subscribe to this channel:
msg = \
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,