NAV Show example code
shell javascript python

Deribit API v2.1.1

Overview

Deribit provides three different interfaces to access the API:

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

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

Naming

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

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

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

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

Rate Limits

Rate limits are described in separate document.

JSON-RPC

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

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

Request messages

An example of a request message:

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

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

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

Response messages

An example of a response message:

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

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

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

An example of a response with an error:

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

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

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

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

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

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

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

Positive execution report

Positive execution report is object with fields:

Erroneous execution report

Erroneous execution report is object with fields:

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

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

Security keys

Request that may require security key authorization

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

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

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

Example of response with request to make Security Key authorization:

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

TFA authorization

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

Example of request when TFA code is 602051:

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

Errors:

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

When an error occurrs, the request needs to be repeated without authorization_data to obtain a new challenge.

Example of erroneous response:

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

Notifications

An example of a notification:

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

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

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

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

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

Authentication

An example of a JSON request with token:

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

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

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

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

Additional authorization method - basic user credentials

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

Authorization: Basic BASE64(ClientId + : + ClientSecret)

Additional authorization method - Deribit signature credentials

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

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

where:

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

The signature is generated by the following formula:

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

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

Example using shell with openssl tool:

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

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

    echo $Signature

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

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

Additional authorization method - signature credentials (WebSocket API)

Example of authorization using client_signature:

# see javascript or python example

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

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

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

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

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

print(msg)

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

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

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

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

The signature is generated by the following formula:

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

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

Example using shell with openssl tool:

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

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

    echo $Signature

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

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

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

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

Access scope

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

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

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

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

Creating/editing/removing API Keys

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

JSON-RPC over websocket

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

JSON-RPC over HTTP

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

Methods

Authentication

/public/auth

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

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

import asyncio
import websockets
import json

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

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

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

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

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

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

Three methods of authentication are supported:

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

Try in API console

Parameters

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

Details are elucidated in Access scope

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  access_token string
  ›  enabled_features array of string List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval. Methods that use block_rfq scope are not affected by Block Trade approval feature
  ›  expires_in integer Token lifetime in seconds
  ›  google_login boolean The access token was acquired by logging in through Google.
  ›  mandatory_tfa_status string 2FA is required for privileged methods
  ›  refresh_token string Can be used to request a new token (with a new lifetime)
  ›  scope string Type of the access for assigned token
  ›  sid string Optional Session id
  ›  state string Copied from the input (if applicable)
  ›  token_type string Authorization type, allowed value - bearer

/public/exchange_token

curl -X GET "https://test.deribit.com/api/v2/public/exchange_token?refresh_token=1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ&subject_id=10" \
-H "Content-Type: application/json"

var msg = 
{"id":7619,"jsonrpc":"2.0","method":"public/exchange_token","params":{"refresh_token":"1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ","subject_id":10}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":7619,"jsonrpc":"2.0","method":"public/exchange_token","params":{"refresh_token":"1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ","subject_id":10}}

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

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

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

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

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

Try in API console

Parameters

Parameter Required Type Enum Description
refresh_token true string Refresh token
subject_id true integer New subject id
scope false string Optional scope override for the new session. Cannot exceed caller's permissions. Supports session scope for direct session creation during token exchange.

Response

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

/public/fork_token

curl -X GET "https://test.deribit.com/api/v2/public/fork_token?refresh_token=1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ&session_name=forked_session_name" \
-H "Content-Type: application/json"

var msg = 
{"id":7620,"jsonrpc":"2.0","method":"public/fork_token","params":{"refresh_token":"1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ","session_name":"forked_session_name"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":7620,"jsonrpc":"2.0","method":"public/fork_token","params":{"refresh_token":"1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ","session_name":"forked_session_name"}}

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

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

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

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

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

Try in API console

Parameters

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

Response

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

/private/logout

This method is only available via websockets.

var msg = 
    {"jsonrpc": "2.0",
     "method": "private/logout",
     "id": 42,
     "params": {
        "access_token": "1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP",
        "invalidate_token": true}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

This method has no response body

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

Try in API console

Parameters

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

Response

This method has no response body

Session management

/public/set_heartbeat

This method is only available via websockets.

var msg = 
{"id":9098,"jsonrpc":"2.0","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 = \
{"id":9098,"jsonrpc":"2.0","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 = 
{"id":3562,"jsonrpc":"2.0","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 = \
{"id":3562,"jsonrpc":"2.0","method":"public/disable_heartbeat","params":{}}

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

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

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

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

Stop sending heartbeat messages.

Try in API console

Parameters

This method takes no parameters

Response

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

/private/enable_cancel_on_disconnect

curl -X GET "https://test.deribit.com/api/v2/private/enable_cancel_on_disconnect?scope=account" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":7859,"jsonrpc":"2.0","method":"private/enable_cancel_on_disconnect","params":{"scope":"account"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

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

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

Scope: account:read_write

Try in API console

Parameters

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

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

Response

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

/private/disable_cancel_on_disconnect

curl -X GET "https://test.deribit.com/api/v2/private/disable_cancel_on_disconnect?scope=account" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1569,"jsonrpc":"2.0","method":"private/disable_cancel_on_disconnect","params":{"scope":"account"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Disable Cancel On Disconnect for the connection.

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

Scope: account:read_write

Try in API console

Parameters

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

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

Response

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

/private/get_cancel_on_disconnect

curl -X GET "https://test.deribit.com/api/v2/private/get_cancel_on_disconnect?scope=account" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":220,"jsonrpc":"2.0","method":"private/get_cancel_on_disconnect","params":{"scope":"account"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 220,
  "result": {
    "scope" : "account",
    "enabled": false
  }
}

Read current Cancel On Disconnect configuration for the account.

Scope: account:read

Try in API console

Parameters

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

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

Response

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

Supporting

/public/get_time

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

var msg = 
{"id":7365,"jsonrpc":"2.0","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 = \
{"id":7365,"jsonrpc":"2.0","method":"public/get_time","params":{}}

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

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

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

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

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

Try in API console

Parameters

This method takes no parameters

Response

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

/public/hello

This method is only available via websockets.

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

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

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

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

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

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

Try in API console

Parameters

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

Response

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

/public/status

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

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

import asyncio
import websockets
import json

msg = \
{"id":55,"jsonrpc":"2.0","method":"public/status","params":{}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 55,
  "result": {
    "locked_currencies": ["BTC", "ETH"],
    "locked": true
  }
}

Method used to get information about locked currencies

Try in API console

Parameters

This method takes no parameters

Response

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

/public/test

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

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

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

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

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

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

Subscribe to one or more channels.

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

Try in API console

Parameters

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

Response

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

/public/unsubscribe

This method is only available via websockets.

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

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

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

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

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

Unsubscribe from one or more channels.

Try in API console

Parameters

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

Response

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

/public/unsubscribe_all

This method is only available via websockets.

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

import asyncio
import websockets
import json

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

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

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

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

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

Unsubscribe from all the channels subscribed so far.

Try in API console

Parameters

This method takes no parameters

Response

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

/private/subscribe

This method is only available via websockets.

var msg = 
{"id":4235,"jsonrpc":"2.0","method":"private/subscribe","params":{"channels":["deribit_price_index.btc_usd"]}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Subscribe to one or more channels.

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

Try in API console

Parameters

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

Response

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

/private/unsubscribe

This method is only available via websockets.

var msg = 
{"id":3370,"jsonrpc":"2.0","method":"private/unsubscribe","params":{"channels":["deribit_price_index.btc_usd"]}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Unsubscribe from one or more channels.

Try in API console

Parameters

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

Response

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

/private/unsubscribe_all

This method is only available via websockets.

var msg = 
{"id":154,"jsonrpc":"2.0","method":"private/unsubscribe_all","params":{}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Unsubscribe from all the channels subscribed so far.

Try in API console

Parameters

This method takes no parameters

Response

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

Market data

/public/get_apr_history

curl -X GET "https://test.deribit.com/api/v2/public/get_apr_history?currency=steth&limit=5" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"public/get_apr_history","params":{"currency":"steth","limit":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 = \
{"id":1,"jsonrpc":"2.0","method":"public/get_apr_history","params":{"currency":"steth","limit":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": 1,
  "result": {
    "data": [
      {
        "day": 20200,
        "apr": 2.814
      },
      {
        "day": 20199,
        "apr": 2.749
      },
      {
        "day": 20198,
        "apr": 2.684
      },
      {
        "day": 20197,
        "apr": 2.667
      },
      {
        "day": 20196,
        "apr": 2.722
      }
    ],
    "continuation": 20196
  }
}

Retrieves historical APR data for specified currency. Only applicable to yield-generating tokens (USDE, STETH).

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string usde
steth		 Currency for which to retrieve APR history
limit false integer Number of days to retrieve (default 365, maximum 365)
before false integer Used to receive APR history before given epoch day

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.
  ›  data array of object
  ›    ›  apr number The APR of the day
  ›    ›  day integer The full epoch day

/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 = 
{"id":9344,"jsonrpc":"2.0","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 = \
{"id":9344,"jsonrpc":"2.0","method":"public/get_book_summary_by_currency","params":{"currency":"BTC","kind":"future"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 9344,
  "result": [
    {
      "volume_usd": 0,
      "volume": 0,
      "quote_currency": "USD",
      "price_change": -11.1896349,
      "open_interest": 0,
      "mid_price": null,
      "mark_price": 3579.73,
      "mark_iv": 80,
      "low": null,
      "last": null,
      "instrument_name": "BTC-22FEB19",
      "high": null,
      "estimated_delivery_price": 3579.73,
      "creation_timestamp": 1550230036440,
      "bid_price": null,
      "base_currency": "BTC",
      "ask_price": null
    },
    {
      "volume_usd": 22440,
      "volume": 6.24,
      "quote_currency": "USD",
      "price_change": -60.8183509,
      "open_interest": 183180,
      "mid_price": null,
      "mark_price": 3579.73,
      "mark_iv": 80,
      "low": 3591,
      "last": 3595,
      "instrument_name": "BTC-PERPETUAL",
      "high": 3595,
      "funding_8h": 0.0002574,
      "estimated_delivery_price": 3579.73,
      "current_funding": 0,
      "creation_timestamp": 1550230036440,
      "bid_price": null,
      "base_currency": "BTC",
      "ask_price": null
    }
  ]
}

Retrieves the summary information such as open interest, 24h volume, etc. for all instruments for the currency (optionally filtered by kind). Note - For real-time updates, we recommend using the WebSocket subscription to ticker.{instrument_name}.{interval} instead of polling this endpoint.

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  ask_price number The current best ask price, null if there aren't any asks
  ›  base_currency string Base currency
  ›  bid_price number The current best bid price, null if there aren't any bids
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  current_funding number Current funding (perpetual only)
  ›  estimated_delivery_price number Optional (only for derivatives). Estimated delivery price for the market. For more details, see Contract Specification > General Documentation > Expiration Price.
  ›  funding_8h number Funding 8h (perpetual only)
  ›  high number Price of the 24h highest trade
  ›  instrument_name string Unique instrument identifier
  ›  interest_rate number Interest rate used in implied volatility calculations (options only)
  ›  last number The price of the latest trade, null if there weren't any trades
  ›  low number Price of the 24h lowest trade, null if there weren't any trades
  ›  mark_iv number (Only for option) implied volatility for mark price
  ›  mark_price number The current instrument market price
  ›  mid_price number The average of the best bid and ask, null if there aren't any asks or bids
  ›  open_interest number Optional (only for derivatives). The total amount of outstanding contracts in the corresponding amount units. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  price_change number 24-hour price change expressed as a percentage, null if there weren't any trades
  ›  quote_currency string Quote currency
  ›  underlying_index string Name of the underlying future, or 'index_price' (options only)
  ›  underlying_price number underlying price for implied volatility calculations (options only)
  ›  volume number The total 24h traded volume (in base currency)
  ›  volume_notional number Volume in quote currency (futures and spots only)
  ›  volume_usd number Volume in USD

/public/get_book_summary_by_instrument

curl -X GET "https://test.deribit.com/api/v2/public/get_book_summary_by_instrument?instrument_name=ETH-22FEB19-140-P" \
-H "Content-Type: application/json"

var msg = 
{"id":3659,"jsonrpc":"2.0","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 = \
{"id":3659,"jsonrpc":"2.0","method":"public/get_book_summary_by_instrument","params":{"instrument_name":"ETH-22FEB19-140-P"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 3659,
  "result": [
    {
      "volume": 0.55,
      "underlying_price": 121.38,
      "underlying_index": "index_price",
      "quote_currency": "USD",
      "price_change": -26.7793594,
      "open_interest": 0.55,
      "mid_price": 0.2444,
      "mark_price": 0.179112,
      "mark_price": 80,
      "low": 0.34,
      "last": 0.34,
      "interest_rate": 0.207,
      "instrument_name": "ETH-22FEB19-140-P",
      "high": 0.34,
      "creation_timestamp": 1550227952163,
      "bid_price": 0.1488,
      "base_currency": "ETH",
      "ask_price": 0.34
    }
  ]
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  ask_price number The current best ask price, null if there aren't any asks
  ›  base_currency string Base currency
  ›  bid_price number The current best bid price, null if there aren't any bids
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  current_funding number Current funding (perpetual only)
  ›  estimated_delivery_price number Optional (only for derivatives). Estimated delivery price for the market. For more details, see Contract Specification > General Documentation > Expiration Price.
  ›  funding_8h number Funding 8h (perpetual only)
  ›  high number Price of the 24h highest trade
  ›  instrument_name string Unique instrument identifier
  ›  interest_rate number Interest rate used in implied volatility calculations (options only)
  ›  last number The price of the latest trade, null if there weren't any trades
  ›  low number Price of the 24h lowest trade, null if there weren't any trades
  ›  mark_iv number (Only for option) implied volatility for mark price
  ›  mark_price number The current instrument market price
  ›  mid_price number The average of the best bid and ask, null if there aren't any asks or bids
  ›  open_interest number Optional (only for derivatives). The total amount of outstanding contracts in the corresponding amount units. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  price_change number 24-hour price change expressed as a percentage, null if there weren't any trades
  ›  quote_currency string Quote currency
  ›  underlying_index string Name of the underlying future, or 'index_price' (options only)
  ›  underlying_price number underlying price for implied volatility calculations (options only)
  ›  volume number The total 24h traded volume (in base currency)
  ›  volume_notional number Volume in quote currency (futures and spots only)
  ›  volume_usd number Volume in USD

/public/get_contract_size

curl -X GET "https://test.deribit.com/api/v2/public/get_contract_size?instrument_name=BTC-PERPETUAL" \
-H "Content-Type: application/json"

var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_contract_size",
     "id": 42,
     "params": {
        "instrument_name": "BTC-PERPETUAL"}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

The above command returns JSON structured like this:

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

Retrieves contract size of provided instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

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

/public/get_currencies

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

var msg = 
{"id":7538,"jsonrpc":"2.0","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 = \
{"id":7538,"jsonrpc":"2.0","method":"public/get_currencies","params":{}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7538,
  "result": [
      {
          "coin_type": "ETHER",
          "currency": "ETH",
          "currency_long": "Ethereum",
          "fee_precision": 4,
          "min_confirmations": 1,
          "min_withdrawal_fee": 0.0001,
          "withdrawal_fee": 0.0006,
          "withdrawal_priorities": []
      },
      {
          "coin_type": "BITCOIN",
          "currency": "BTC",
          "currency_long": "Bitcoin",
          "fee_precision": 4,
          "min_confirmations": 1,
          "min_withdrawal_fee": 0.0001,
          "withdrawal_fee": 0.0001,
          "withdrawal_priorities": [
              {
                  "value": 0.15,
                  "name": "very_low"
              },
              {
                  "value": 1.5,
                  "name": "very_high"
              }
          ]
      }
  ]
}

Retrieves all cryptocurrencies supported by the API.

Try in API console

Parameters

This method takes no parameters

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  apr number Simple Moving Average (SMA) of the last 7 days of rewards. If fewer than 7 days of reward data are available, the APR is calculated as the average of the available rewards. Only applicable to yield-generating tokens (USDE, STETH).
  ›  coin_type string The type of the currency.
  ›  currency string The abbreviation of the currency. This abbreviation is used elsewhere in the API to identify the currency.
  ›  currency_long string The full name for the currency.
  ›  fee_precision integer fee precision
  ›  in_cross_collateral_pool boolean true if the currency is part of the cross collateral pool
  ›  min_confirmations integer Minimum number of block chain confirmations before deposit is accepted.
  ›  min_withdrawal_fee number The minimum transaction fee paid for withdrawals
  ›  withdrawal_fee number The total transaction fee paid for withdrawals
  ›  withdrawal_priorities array of object
  ›    ›  name string
  ›    ›  value number

/public/get_delivery_prices

curl -X GET "https://test.deribit.com/api/v2/public/get_delivery_prices?count=5&index_name=btc_usd&offset=0" \
-H "Content-Type: application/json"

var msg = 
{"id":3601,"jsonrpc":"2.0","method":"public/get_delivery_prices","params":{"count":5,"index_name":"btc_usd","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 = \
{"id":3601,"jsonrpc":"2.0","method":"public/get_delivery_prices","params":{"count":5,"index_name":"btc_usd","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": 3601,
  "result": {
    "data": [
      {
        "date": "2020-01-02",
        "delivery_price": 7131.214606410254
      },
      {
        "date": "2019-12-21",
        "delivery_price": 7150.943217777777
      },
      {
        "date": "2019-12-20",
        "delivery_price": 7175.988445532345
      },
      {
        "date": "2019-12-19",
        "delivery_price": 7189.540776143791
      },
      {
        "date": "2019-12-18",
        "delivery_price": 6698.353743857118
      }
    ],
    "records_total": 58
  }
}

Retrieves delivery prices for then given index

Try in API console

Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
btc_usdc
btcdvol_usdc
buidl_usdc
doge_usdc
dot_usdc
eurr_usdc
eth_usdc
ethdvol_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
steth_usdc
ton_usdc
trump_usdc
trx_usdc
uni_usdc
usde_usdc
usyc_usdc
xrp_usdc
btc_usdt
eth_usdt
eurr_usdt
sol_usdt
steth_usdt
usdc_usdt
usde_usdt
btc_eurr
btc_usde
btc_usyc
eth_btc
eth_eurr
eth_usde
eth_usyc
steth_eth
paxg_btc		 Index identifier, matches (base) cryptocurrency with quote currency
offset false integer The offset for pagination, default - 0
count false integer Number of requested items, default - 10

Response

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

/public/get_expirations

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

var msg = 
{"id":1,"jsonrpc":"2.0","method":"public/get_expirations","params":{"currency":"any","kind":"any"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"public/get_expirations","params":{"currency":"any","kind":"any"}}

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",
  "result": {
    "future": [
      "21SEP24",
      "22SEP24",
      "PERPETUAL"
    ],
    "option": [
      "21SEP24",
      "22SEP24",
      "23SEP24"
    ]
  }
}

Retrieves expirations for instruments. This method can be used to see instruments's expirations.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
any
grouped		 The currency symbol or "any" for all or '"grouped"' for all grouped by currency
kind true string future
option
any		 Instrument kind, "future" or "option" or "any"
currency_pair false string btc_usd
eth_usd
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
btc_usdc
btcdvol_usdc
buidl_usdc
doge_usdc
dot_usdc
eurr_usdc
eth_usdc
ethdvol_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
steth_usdc
ton_usdc
trump_usdc
trx_usdc
uni_usdc
usde_usdc
usyc_usdc
xrp_usdc
btc_usdt
eth_usdt
eurr_usdt
sol_usdt
steth_usdt
usdc_usdt
usde_usdt
btc_eurr
btc_usde
btc_usyc
eth_btc
eth_eurr
eth_usde
eth_usyc
steth_eth
paxg_btc		 The currency pair symbol

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object A map where each key is valid currency (e.g. btc, eth, usdc), and the value is a list of expirations or a map where each key is a valid kind (future or options) and value is a list of expirations from every instrument
  ›  currency string Currency name or "any" if don't care or "grouped" if grouped by currencies
  ›  kind string Instrument kind: "future", "option" or "any" for all

/public/get_funding_chart_data

curl -X GET "https://test.deribit.com/api/v2/public/get_funding_chart_data?instrument_name=BTC-PERPETUAL&length=8h" \
-H "Content-Type: application/json"

var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_funding_chart_data",
     "id": 42,
     "params": {
        "instrument_name": "BTC-PERPETUAL",
        "length": "8h"}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

The above command returns JSON structured like this:

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

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

Try in API console

Parameters

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

Response

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

/public/get_funding_rate_history

curl -X GET "https://test.deribit.com/api/v2/public/get_funding_rate_history?end_timestamp=1569902400000&instrument_name=BTC-PERPETUAL&start_timestamp=1569888000000" \
-H "Content-Type: application/json"

var msg = 
{"id":7617,"jsonrpc":"2.0","method":"public/get_funding_rate_history","params":{"end_timestamp":1569902400000,"instrument_name":"BTC-PERPETUAL","start_timestamp":1569888000000}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":7617,"jsonrpc":"2.0","method":"public/get_funding_rate_history","params":{"end_timestamp":1569902400000,"instrument_name":"BTC-PERPETUAL","start_timestamp":1569888000000}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7617,
  "result": [
    {
      "timestamp": 1569891600000,
      "index_price": 8222.87,
      "prev_index_price": 8305.72,
      "interest_8h": -0.00009234260068476106,
      "interest_1h": -4.739622041017375e-7
    },
    {
      "timestamp": 1569895200000,
      "index_price": 8286.49,
      "prev_index_price": 8222.87,
      "interest_8h": -0.00006720918180255509,
      "interest_1h": -2.8583510923267753e-7
    },
    {
      "timestamp": 1569898800000,
      "index_price": 8431.97,
      "prev_index_price": 8286.49,
      "interest_8h": -0.00003544496169694662,
      "interest_1h": -0.000003815906848177951
    },
    {
      "timestamp": 1569902400000,
      "index_price": 8422.36,
      "prev_index_price": 8431.97,
      "interest_8h": -0.00001404147515584998,
      "interest_1h": 8.312033064379086e-7
    }
  ]
}

Retrieves hourly historical interest rate for requested PERPETUAL instrument.

Try in API console

Parameters

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

Response

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

/public/get_funding_rate_value

curl -X GET "https://test.deribit.com/api/v2/public/get_funding_rate_value?end_timestamp=1569974400000&instrument_name=BTC-PERPETUAL&start_timestamp=1569888000000" \
-H "Content-Type: application/json"

var msg = 
{"id":7617,"jsonrpc":"2.0","method":"public/get_funding_rate_value","params":{"end_timestamp":1569974400000,"instrument_name":"BTC-PERPETUAL","start_timestamp":1569888000000}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":7617,"jsonrpc":"2.0","method":"public/get_funding_rate_value","params":{"end_timestamp":1569974400000,"instrument_name":"BTC-PERPETUAL","start_timestamp":1569888000000}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7617,
  "result": -0.00025056853702101664
}

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

Try in API console

Parameters

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

Response

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

/public/get_historical_volatility

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

var msg = 
{"id":8387,"jsonrpc":"2.0","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 = \
{"id":8387,"jsonrpc":"2.0","method":"public/get_historical_volatility","params":{"currency":"BTC"}}

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

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

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

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

Provides information about historical volatility for given cryptocurrency.

Try in API console

Parameters

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

Response

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

/public/get_index

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

var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_index",
     "id": 42,
     "params": {
        "currency": "BTC"}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

The above command returns JSON structured like this:

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

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

Try in API console

Parameters

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

Response

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

/public/get_index_price

curl -X GET "https://test.deribit.com/api/v2/public/get_index_price?index_name=btc_usd" \
-H "Content-Type: application/json"

var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_index_price",
     "id": 42,
     "params": {
        "index_name": "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",
     "method": "public/get_index_price",
     "id": 42,
     "params": {
        "index_name": "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:

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

Retrieves the current index price value for given index name.

Try in API console

Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
btc_usdc
btcdvol_usdc
buidl_usdc
doge_usdc
dot_usdc
eurr_usdc
eth_usdc
ethdvol_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
steth_usdc
ton_usdc
trump_usdc
trx_usdc
uni_usdc
usde_usdc
usyc_usdc
xrp_usdc
btc_usdt
eth_usdt
eurr_usdt
sol_usdt
steth_usdt
usdc_usdt
usde_usdt
btc_eurr
btc_usde
btc_usyc
eth_btc
eth_eurr
eth_usde
eth_usyc
steth_eth
paxg_btc		 Index identifier, matches (base) cryptocurrency with quote currency

Response

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

/public/get_index_price_names

curl -X GET "https://test.deribit.com/api/v2/public/get_index_price_names" \
-H "Content-Type: application/json"

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

import asyncio
import websockets
import json

msg = \
    {"jsonrpc": "2.0",
     "method": "public/get_index_price_names",
     "id": 42
    }

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7617,
  "result": [
    "btc_usd",
    "eth_usd",
    "btc_usdc",
    "eth_usdc"
  ]
}

Retrieves the identifiers of all supported Price Indexes

Try in API console

Parameters

This method takes no parameters

Response

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

/public/get_instrument

curl -X GET "https://test.deribit.com/api/v2/public/get_instrument?instrument_name=BTC-13JAN23-16000-P" \
-H "Content-Type: application/json"

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

Retrieves information about instrument

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  base_currency string The underlying currency being traded.
  ›  block_trade_commission number Block Trade commission for instrument.
  ›  block_trade_min_trade_amount number Minimum amount for block trading.
  ›  block_trade_tick_size number Specifies minimal price change for block trading.
  ›  contract_size integer Contract size for instrument.
  ›  counter_currency string Counter currency for the instrument.
  ›  creation_timestamp integer The time when the instrument was first created (milliseconds since the UNIX epoch).
  ›  expiration_timestamp integer The time when the instrument will expire (milliseconds since the UNIX epoch).
  ›  future_type string Future type (only for futures)(field is deprecated and will be removed in the future, instrument_type should be used instead).
  ›  instrument_id integer Instrument ID
  ›  instrument_name string Unique instrument identifier
  ›  instrument_type string Type of the instrument. linear or reversed
  ›  is_active boolean Indicates if the instrument can currently be traded.
  ›  kind string Instrument kind: "future", "option", "spot", "future_combo", "option_combo"
  ›  maker_commission number Maker commission for instrument.
  ›  max_leverage integer Maximal leverage for instrument (only for futures).
  ›  max_liquidation_commission number Maximal liquidation trade commission for instrument (only for futures).
  ›  min_trade_amount number Minimum amount for trading. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  option_type string The option type (only for options).
  ›  price_index string Name of price index that is used for this instrument
  ›  quote_currency string The currency in which the instrument prices are quoted.
  ›  rfq boolean Whether or not RFQ is active on the instrument.
  ›  settlement_currency string Optional (not added for spot). Settlement currency for the instrument.
  ›  settlement_period string Optional (not added for spot). The settlement period.
  ›  strike number The strike value (only for options).
  ›  taker_commission number Taker commission for instrument.
  ›  tick_size number Specifies minimal price change and, as follows, the number of decimal places for instrument prices.
  ›  tick_size_steps object
  ›    ›  above_price number The price from which the increased tick size applies
  ›    ›  tick_size number Tick size to be used above the price. It must be multiple of the minimum tick size.

/public/get_instruments

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

var msg = 
{"id":1,"jsonrpc":"2.0","method":"public/get_instruments","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 = \
{"id":1,"jsonrpc":"2.0","method":"public/get_instruments","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": 1,
  "result": [
    {
      "tick_size": 2.5,
      "tick_size_steps": [],
      "taker_commission": 0.0005,
      "settlement_period": "month",
      "settlement_currency": "BTC",
      "rfq": false,
      "quote_currency": "USD",
      "price_index": "btc_usd",
      "min_trade_amount": 10,
      "max_liquidation_commission": 0.0075,
      "max_leverage": 50,
      "maker_commission": 0,
      "kind": "future",
      "is_active": true,
      "instrument_name": "BTC-29SEP23",
      "instrument_id": 138583,
      "instrument_type": "reversed",
      "expiration_timestamp": 1695974400000,
      "creation_timestamp": 1664524802000,
      "counter_currency": "USD",
      "contract_size": 10,
      "block_trade_tick_size": 0.01,
      "block_trade_min_trade_amount": 200000,
      "block_trade_commission": 0.00025,
      "base_currency": "BTC"
    },
    {
      "tick_size": 0.5,
      "tick_size_steps": [],
      "taker_commission": 0.0005,
      "settlement_period": "perpetual",
      "settlement_currency": "BTC",
      "rfq": false,
      "quote_currency": "USD",
      "price_index": "btc_usd",
      "min_trade_amount": 10,
      "max_liquidation_commission": 0.0075,
      "max_leverage": 50,
      "maker_commission": 0,
      "kind": "future",
      "is_active": true,
      "instrument_name": "BTC-PERPETUAL",
      "instrument_id": 124972,
      "instrument_type": "reversed",
      "expiration_timestamp": 32503708800000,
      "creation_timestamp": 1534167754000,
      "counter_currency": "USD",
      "contract_size": 10,
      "block_trade_tick_size": 0.01,
      "block_trade_min_trade_amount": 200000,
      "block_trade_commission": 0.00025,
      "base_currency": "BTC"
    }
  ]
}

Retrieves available trading instruments. This method can be used to see which instruments are available for trading, or which instruments have recently expired. Note - This endpoint has distinct API rate limiting requirements: 1 request per 10 seconds, with a burst of 5. To avoid rate limits, we recommend using either the REST requests for server-cached data or the WebSocket subscription to instrument_state.{kind}.{currency} for real-time updates. For more information, see Rate Limits.

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  base_currency string The underlying currency being traded.
  ›  block_trade_commission number Block Trade commission for instrument.
  ›  block_trade_min_trade_amount number Minimum amount for block trading.
  ›  block_trade_tick_size number Specifies minimal price change for block trading.
  ›  contract_size integer Contract size for instrument.
  ›  counter_currency string Counter currency for the instrument.
  ›  creation_timestamp integer The time when the instrument was first created (milliseconds since the UNIX epoch).
  ›  expiration_timestamp integer The time when the instrument will expire (milliseconds since the UNIX epoch).
  ›  future_type string Future type (only for futures)(field is deprecated and will be removed in the future, instrument_type should be used instead).
  ›  instrument_id integer Instrument ID
  ›  instrument_name string Unique instrument identifier
  ›  instrument_type string Type of the instrument. linear or reversed
  ›  is_active boolean Indicates if the instrument can currently be traded.
  ›  kind string Instrument kind: "future", "option", "spot", "future_combo", "option_combo"
  ›  maker_commission number Maker commission for instrument.
  ›  max_leverage integer Maximal leverage for instrument (only for futures).
  ›  max_liquidation_commission number Maximal liquidation trade commission for instrument (only for futures).
  ›  min_trade_amount number Minimum amount for trading. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  option_type string The option type (only for options).
  ›  price_index string Name of price index that is used for this instrument
  ›  quote_currency string The currency in which the instrument prices are quoted.
  ›  rfq boolean Whether or not RFQ is active on the instrument.
  ›  settlement_currency string Optional (not added for spot). Settlement currency for the instrument.
  ›  settlement_period string Optional (not added for spot). The settlement period.
  ›  strike number The strike value (only for options).
  ›  taker_commission number Taker commission for instrument.
  ›  tick_size number Specifies minimal price change and, as follows, the number of decimal places for instrument prices.
  ›  tick_size_steps object
  ›    ›  above_price number The price from which the increased tick size applies
  ›    ›  tick_size number Tick size to be used above the price. It must be multiple of the minimum tick size.

/public/get_last_settlements_by_currency

curl -X GET "https://test.deribit.com/api/v2/public/get_last_settlements_by_currency?count=2&currency=BTC&type=delivery" \
-H "Content-Type: application/json"

var msg = 
{"id":4497,"jsonrpc":"2.0","method":"public/get_last_settlements_by_currency","params":{"count":2,"currency":"BTC","type":"delivery"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

Try in API console

Parameters

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

Response

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

/public/get_last_settlements_by_instrument

curl -X GET "https://test.deribit.com/api/v2/public/get_last_settlements_by_instrument?count=1&instrument_name=BTC-22FEB19&type=settlement" \
-H "Content-Type: application/json"

var msg = 
{"id":5482,"jsonrpc":"2.0","method":"public/get_last_settlements_by_instrument","params":{"count":1,"instrument_name":"BTC-22FEB19","type":"settlement"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

Try in API console

Parameters

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

Response

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

/public/get_last_trades_by_currency

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

var msg = 
{"id":9290,"jsonrpc":"2.0","method":"public/get_last_trades_by_currency","params":{"count":1,"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 = \
{"id":9290,"jsonrpc":"2.0","method":"public/get_last_trades_by_currency","params":{"count":1,"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": 9290,
    "result": {
        "trades": [
            {
                "trade_seq": 36798,
                "trade_id": "277976",
                "timestamp": 1590476708320,
                "tick_direction": 2,
                "price": 8767.08,
                "mark_price": 8829.7,
                "instrument_name": "BTC-PERPETUAL",
                "index_price": 8878.53,
                "direction": "sell",
                "amount": 100
            }
        ],
        "has_more": true
    }
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
start_id false string The ID of the first trade to be returned. Number for BTC trades, or hyphen name in ex. "ETH-15" # "ETH_USDC-16"
end_id false string The ID of the last trade to be returned. Number for BTC trades, or hyphen name in ex. "ETH-15" # "ETH_USDC-16"
start_timestamp false integer The earliest timestamp to return result from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp false integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
count false integer Number of requested items, default - 10
sorting false string asc
desc
default		 Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  block_trade_leg_count integer Block trade leg count - when trade was part of a block trade
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  price number Price in base currency
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/public/get_last_trades_by_currency_and_time

curl -X GET "https://test.deribit.com/api/v2/public/get_last_trades_by_currency_and_time?count=1&currency=BTC&end_timestamp=1590480022768&start_timestamp=1590470022768" \
-H "Content-Type: application/json"

var msg = 
{"id":1469,"jsonrpc":"2.0","method":"public/get_last_trades_by_currency_and_time","params":{"count":1,"currency":"BTC","end_timestamp":1590480022768,"start_timestamp":1590470022768}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
    "jsonrpc": "2.0",
    "id": 1469,
    "result": {
        "trades": [
            {
                "trade_seq": 3471,
                "trade_id": "48077291",
                "timestamp": 1590470616101,
                "tick_direction": 2,
                "price": 0.032,
                "mark_price": 0.04070324,
                "iv": 74.74,
                "instrument_name": "BTC-25SEP20-6000-P",
                "index_price": 8899.93,
                "direction": "sell",
                "amount": 0.5
            }
        ],
        "has_more": true
    }
}

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

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
start_timestamp true integer The earliest timestamp to return result from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp true integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
count false integer Number of requested items, default - 10
sorting false string asc
desc
default		 Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  block_trade_leg_count integer Block trade leg count - when trade was part of a block trade
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  price number Price in base currency
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/public/get_last_trades_by_instrument

curl -X GET "https://test.deribit.com/api/v2/public/get_last_trades_by_instrument?count=1&instrument_name=BTC-PERPETUAL" \
-H "Content-Type: application/json"

var msg = 
{"id":9267,"jsonrpc":"2.0","method":"public/get_last_trades_by_instrument","params":{"count":1,"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 = \
{"id":9267,"jsonrpc":"2.0","method":"public/get_last_trades_by_instrument","params":{"count":1,"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": 9267,
    "result": {
        "trades": [
            {
                "trade_seq": 36798,
                "trade_id": "277976",
                "timestamp": 1590476708320,
                "tick_direction": 2,
                "price": 8767.08,
                "mark_price": 8829.7,
                "instrument_name": "BTC-PERPETUAL",
                "index_price": 8878.53,
                "direction": "sell",
                "amount": 100
            }
        ],
        "has_more": true
    }
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_seq false integer The sequence number of the first trade to be returned
end_seq false integer The sequence number of the last trade to be returned
start_timestamp false integer The earliest timestamp to return result from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp false integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
count false integer Number of requested items, default - 10
sorting false string asc
desc
default		 Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  block_trade_leg_count integer Block trade leg count - when trade was part of a block trade
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  price number Price in base currency
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/public/get_last_trades_by_instrument_and_time

curl -X GET "https://test.deribit.com/api/v2/public/get_last_trades_by_instrument_and_time?count=1&end_timestamp=1590480022768&instrument_name=ETH-PERPETUAL" \
-H "Content-Type: application/json"

var msg = 
{"id":3983,"jsonrpc":"2.0","method":"public/get_last_trades_by_instrument_and_time","params":{"count":1,"end_timestamp":1590480022768,"instrument_name":"ETH-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 = \
{"id":3983,"jsonrpc":"2.0","method":"public/get_last_trades_by_instrument_and_time","params":{"count":1,"end_timestamp":1590480022768,"instrument_name":"ETH-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": 3983,
    "result": {
        "trades": [
            {
                "trade_seq": 1966031,
                "trade_id": "ETH-2696055",
                "timestamp": 1590479408216,
                "tick_direction": 0,
                "price": 203.6,
                "mark_price": 203.41,
                "instrument_name": "ETH-PERPETUAL",
                "index_price": 203.45,
                "direction": "buy",
                "amount": 10
            }
        ],
        "has_more": true
    }
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_timestamp true integer The earliest timestamp to return result from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp true integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
count false integer Number of requested items, default - 10
sorting false string asc
desc
default		 Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  block_trade_leg_count integer Block trade leg count - when trade was part of a block trade
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  direction string Direction: buy, or sell
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  price number Price in base currency
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  trade_seq integer The sequence number of the trade within instrument

/public/get_mark_price_history

curl -X GET "https://test.deribit.com/api/v2/public/get_mark_price_history?end_timestamp=1609376810000&instrument_name=BTC-25JUN21-50000-C&start_timestamp=1609376800000" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"public/get_mark_price_history","params":{"end_timestamp":1609376810000,"instrument_name":"BTC-25JUN21-50000-C","start_timestamp":1609376800000}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"public/get_mark_price_history","params":{"end_timestamp":1609376810000,"instrument_name":"BTC-25JUN21-50000-C","start_timestamp":1609376800000}}

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

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

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

{"jsonrpc":"2.0",
  "id": 25,
  "result": [
    [1608142381229,0.5165791606037885],
    [1608142380231,0.5165737855432504],
    [1608142379227,0.5165768236356326]
  ]
}

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

Try in API console

Parameters

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

Response

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

/public/get_order_book

curl -X GET "https://test.deribit.com/api/v2/public/get_order_book?depth=5&instrument_name=BTC-PERPETUAL" \
-H "Content-Type: application/json"

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

        ]
    }
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string The instrument name for which to retrieve the order book, see public/get_instruments to obtain instrument names.
depth false integer 1
5
10
20
50
100
1000
10000		 The number of entries to return for bids and asks.

Response

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

/public/get_order_book_by_instrument_id

curl -X GET "https://test.deribit.com/api/v2/public/get_order_book_by_instrument_id?instrument_id=42&depth=1" \
-H "Content-Type: application/json"

var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_order_book_by_instrument_id",
     "id": 42,
     "params": {
        "instrument_id": 42,
        "depth": 1}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
    {"jsonrpc": "2.0",
     "method": "public/get_order_book_by_instrument_id",
     "id": 42,
     "params": {
        "instrument_id": 42,
        "depth": 1}
    }

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

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

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

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

        ]
    }
}

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

Try in API console

Parameters

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

Response

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

/public/get_rfqs

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

var msg = 
{"id":1,"jsonrpc":"2.0","method":"public/get_rfqs","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 = \
{"id":1,"jsonrpc":"2.0","method":"public/get_rfqs","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": 1,
  "result": [
    {
      "traded_volume": 0,
      "amount": 10,
      "side": "buy",
      "last_rfq_tstamp": 1634816611595,
      "instrument_name": "BTC-PERPETUAL"
    }
  ]
}

Retrieve active RFQs for instruments in given currency.

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  instrument_name string Unique instrument identifier
  ›  last_rfq_timestamp integer The timestamp of last RFQ (milliseconds since the Unix epoch)
  ›  side string Side - buy or sell
  ›  traded_volume number Volume traded since last RFQ

/public/get_supported_index_names

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

var msg = 
    {"jsonrpc": "2.0",
     "method": "public/get_supported_index_names",
     "id": 42,
     "params": {
        "type": "all"}
    };
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 25718,
  "result": [
    "btc_eth",
    "btc_usdc",
    "eth_usdc"
  ]
}

Retrieves the identifiers of all supported Price Indexes

Try in API console

Parameters

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

Response

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

/public/get_trade_volumes

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

var msg = 
{"id":6387,"jsonrpc":"2.0","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 = \
{"id":6387,"jsonrpc":"2.0","method":"public/get_trade_volumes"}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 6387,
  "result": [
    {
      "puts_volume": 48,
      "futures_volume": 6.25578452,
      "currency": "BTC",
      "calls_volume": 145,
      "spot_volume": 11.1
    },
    {
      "puts_volume": 122.65,
      "futures_volume": 374.392173,
      "currency": "ETH",
      "calls_volume": 37.4,
      "spot_volume": 57.7
    }
  ]
}

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

Try in API console

Parameters

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

Response

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

/public/get_tradingview_chart_data

curl -X GET "https://test.deribit.com/api/v2/public/get_tradingview_chart_data?end_timestamp=1554376800000&instrument_name=BTC-5APR19&resolution=30&start_timestamp=1554373800000" \
-H "Content-Type: application/json"

var msg = 
{"id":833,"jsonrpc":"2.0","method":"public/get_tradingview_chart_data","params":{"end_timestamp":1554376800000,"instrument_name":"BTC-5APR19","resolution":"30","start_timestamp":1554373800000}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":833,"jsonrpc":"2.0","method":"public/get_tradingview_chart_data","params":{"end_timestamp":1554376800000,"instrument_name":"BTC-5APR19","resolution":"30","start_timestamp":1554373800000}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 833,
  "result": {
    "volume": [
      19.007942601,
      20.095877981
    ],
    "cost": [
      19000.0,
      23400.0
    ],
    "ticks": [
      1554373800000,
      1554375600000
    ],
    "status": "ok",
    "open": [
      4963.42,
      4986.29
    ],
    "low": [
      4728.94,
      4726.6
    ],
    "high": [
      5185.45,
      5250.87
    ],
    "close": [
      5052.95,
      5013.59
    ]
  },
  "usIn": 1554381680742493,
  "usOut": 1554381680742698,
  "usDiff": 205,
  "testnet": false
}

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

Try in API console

Parameters

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

Response

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

/public/get_volatility_index_data

curl -X GET "https://test.deribit.com/api/v2/public/get_volatility_index_data?currency=BTC&end_timestamp=1599376800000&resolution=60&start_timestamp=1599373800000" \
-H "Content-Type: application/json"

var msg = 
{"id":833,"jsonrpc":"2.0","method":"public/get_volatility_index_data","params":{"currency":"BTC","end_timestamp":1599376800000,"resolution":"60","start_timestamp":1599373800000}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":833,"jsonrpc":"2.0","method":"public/get_volatility_index_data","params":{"currency":"BTC","end_timestamp":1599376800000,"resolution":"60","start_timestamp":1599373800000}}

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

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

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

{
  "jsonrpc":"2.0",
  "id":5,
  "result":
  {
    "data": [
      [1598019300000,0.210084879,0.212860821,0.210084879,0.212860821],
      [1598019360000,0.212869011,0.212987527,0.212869011,0.212987527],
      [1598019420000,0.212987723,0.212992597,0.212987723,0.212992597]
    ],
    "continuation": null
  }
}

Public market data request for volatility index candles.

Try in API console

Parameters

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

Response

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

/public/ticker

curl -X GET "https://test.deribit.com/api/v2/public/ticker?instrument_name=BTC-PERPETUAL" \
-H "Content-Type: application/json"

var msg = 
{"id":8106,"jsonrpc":"2.0","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 = \
{"id":8106,"jsonrpc":"2.0","method":"public/ticker","params":{"instrument_name":"BTC-PERPETUAL"}}

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

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

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

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

Get ticker for an instrument.

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  ask_iv number (Only for option) implied volatility for best ask
  ›  best_ask_amount number It represents the requested order size of all best asks
  ›  best_ask_price number The current best ask price, null if there aren't any asks
  ›  best_bid_amount number It represents the requested order size of all best bids
  ›  best_bid_price number The current best bid price, null if there aren't any bids
  ›  bid_iv number (Only for option) implied volatility for best bid
  ›  current_funding number Current funding (perpetual only)
  ›  delivery_price number The settlement price for the instrument. Only when state = closed
  ›  estimated_delivery_price number Estimated delivery price for the market. For more details, see Contract Specification > General Documentation > Expiration Price
  ›  funding_8h number Funding 8h (perpetual only)
  ›  greeks object Only for options
  ›    ›  delta number (Only for option) The delta value for the option
  ›    ›  gamma number (Only for option) The gamma value for the option
  ›    ›  rho number (Only for option) The rho value for the option
  ›    ›  theta number (Only for option) The theta value for the option
  ›    ›  vega number (Only for option) The vega value for the option
  ›  index_price number Current index price
  ›  instrument_name string Unique instrument identifier
  ›  interest_rate number Interest rate used in implied volatility calculations (options only)
  ›  interest_value number Value used to calculate realized_funding in positions (perpetual only)
  ›  last_price number The price for the last trade
  ›  mark_iv number (Only for option) implied volatility for mark price
  ›  mark_price number The mark price for the instrument
  ›  max_price number The maximum price for the future. Any buy orders you submit higher than this price, will be clamped to this maximum.
  ›  min_price number The minimum price for the future. Any sell orders you submit lower than this price will be clamped to this minimum.
  ›  open_interest number The total amount of outstanding contracts in the corresponding amount units. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  settlement_price number Optional (not added for spot). The settlement price for the instrument. Only when state = open
  ›  state string The state of the order book. Possible values are open and closed.
  ›  stats object
  ›    ›  high number Highest price during 24h
  ›    ›  low number Lowest price during 24h
  ›    ›  price_change number 24-hour price change expressed as a percentage, null if there weren't any trades
  ›    ›  volume number Volume during last 24h in base currency
  ›    ›  volume_usd number Volume in usd (futures only)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  underlying_index number Name of the underlying future, or index_price (options only)
  ›  underlying_price number Underlying price for implied volatility calculations (options only)

Trading

/private/buy

curl -X GET "https://test.deribit.com/api/v2/private/buy?amount=40&instrument_name=ETH-PERPETUAL&label=market0000234&type=market" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":5275,"jsonrpc":"2.0","method":"private/buy","params":{"amount":40,"instrument_name":"ETH-PERPETUAL","label":"market0000234","type":"market"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 5275,
  "result": {
    "trades": [
      {
        "trade_seq": 1966056,
        "trade_id": "ETH-2696083",
        "timestamp": 1590483938456,
        "tick_direction": 0,
        "state": "filled",
        "reduce_only": false,
        "price": 203.3,
        "post_only": false,
        "order_type": "market",
        "order_id": "ETH-584849853",
        "matching_id": null,
        "mark_price": 203.28,
        "liquidity": "T",
        "label": "market0000234",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 203.33,
        "fee_currency": "ETH",
        "fee": 0.00014757,
        "direction": "buy",
        "amount": 40
      }
    ],
    "order": {
      "web": false,
      "time_in_force": "good_til_cancelled",
      "replaced": false,
      "reduce_only": false,
      "price": 207.3,
      "post_only": false,
      "order_type": "market",
      "order_state": "filled",
      "order_id": "ETH-584849853",
      "max_show": 40,
      "last_update_timestamp": 1590483938456,
      "label": "market0000234",
      "is_rebalance": false,
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "filled_amount": 40,
      "direction": "buy",
      "creation_timestamp": 1590483938456,
      "average_price": 203.3,
      "api": true,
      "amount": 40
    }
  }
}

Places a buy order for an instrument.

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
amount false number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin. The amount is a mandatory parameter if contracts parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
contracts false number It represents the requested order size in contract units and can be passed instead of amount. The contracts is a mandatory parameter if amount parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
type false string limit
stop_limit
take_limit
market
stop_market
take_market
market_limit
trailing_stop		 The order type, default: "limit"
label false string user defined label for the order (maximum 64 characters)
price false number

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

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

When adding an order with advanced=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%
time_in_force false string good_til_cancelled
good_til_day
fill_or_kill
immediate_or_cancel

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

  • "good_til_cancelled" - unfilled order remains in order book until cancelled
  • "good_til_day" - unfilled order remains in order book till the end of the trading session
  • "fill_or_kill" - execute a transaction immediately and completely or not at all
  • "immediate_or_cancel" - execute a transaction immediately, and any portion of the order that cannot be immediately filled is cancelled
display_amount false number Initial display amount for iceberg order. Has to be at least 100 times minimum amount for instrument and ratio of hidden part vs visible part has to be less than 100 as well.
post_only false boolean

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

Only valid in combination with time_in_force="good_til_cancelled"
reject_post_only false boolean

If an order is considered post-only and this field is set to true then the order is put to the order book unmodified or the request is rejected.

Only valid in combination with "post_only" set to true
reduce_only false boolean If true, the order is considered reduce-only which is intended to only reduce a current position
trigger_price false number Trigger price, required for trigger orders only (Stop-loss or Take-profit orders)
trigger_offset false number The maximum deviation from the price peak beyond which the order will be triggered
trigger false string index_price
mark_price
last_price		 Defines the trigger type. Required for "Stop-Loss", "Take-Profit" and "Trailing" trigger orders
advanced false string usd
implv		 Advanced option order type. (Only for options. Advanced USD orders are not supported for linear options.)
mmp false boolean Order MMP flag, only for order_type 'limit'
valid_until false integer Timestamp, when provided server will start processing request in Matching Engine only before given timestamp, in other cases timed_out error will be responded. Remember that the given timestamp should be consistent with the server's time, use /public/time method to obtain current server time.
linked_order_type false string one_triggers_other
one_cancels_other
one_triggers_one_cancels_other

The type of the linked order.

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

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

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

List of trades to create or cancel when this order is filled.
  ›  amount false number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  direction true string buy
sell		 Direction of trade from the maker perspective
  ›  type false string limit
stop_limit
take_limit
market
stop_market
take_market
market_limit
trailing_stop		 The order type, default: "limit"
  ›  label false string user defined label for the order (maximum 64 characters)
  ›  price false number

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

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

When adding an order with advanced=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%
  ›  reduce_only false boolean If true, the order is considered reduce-only which is intended to only reduce a current position
  ›  time_in_force false string good_til_cancelled
good_til_day
fill_or_kill
immediate_or_cancel

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

  • "good_til_cancelled" - unfilled order remains in order book until cancelled
  • "good_til_day" - unfilled order remains in order book till the end of the trading session
  • "fill_or_kill" - execute a transaction immediately and completely or not at all
  • "immediate_or_cancel" - execute a transaction immediately, and any portion of the order that cannot be immediately filled is cancelled
  ›  post_only false boolean

If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below or above the spread (according to the direction of the order).

Only valid in combination with time_in_force="good_til_cancelled"
  ›  reject_post_only false boolean

If an order is considered post-only and this field is set to true then the order is put to the order book unmodified or the request is rejected.

Only valid in combination with "post_only" set to true
  ›  trigger_price false number Trigger price, required for trigger orders only (Stop-loss or Take-profit orders)
  ›  trigger_offset false number The maximum deviation from the price peak beyond which the order will be triggered
  ›  trigger false string index_price
mark_price
last_price		 Defines the trigger type. Required for "Stop-Loss", "Take-Profit" and "Trailing" trigger orders

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  order object
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  order_id string Unique order identifier
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  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.
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  trigger_fill_condition string

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

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  primary_order_id string Unique order identifier
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/sell

curl -X GET "https://test.deribit.com/api/v2/private/sell?amount=123&instrument_name=ETH-PERPETUAL&price=1.45610000000000013642e%2B02&trigger=last_price&trigger_price=145&type=stop_limit" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2148,"jsonrpc":"2.0","method":"private/sell","params":{"amount":123,"instrument_name":"ETH-PERPETUAL","price":145.61,"trigger":"last_price","trigger_price":145,"type":"stop_limit"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 2148,
  "result": {
    "trades": [],
    "order": {
      "triggered": false,
      "trigger": "last_price",
      "time_in_force": "good_til_cancelled",
      "trigger_price": 145,
      "reduce_only": false,
      "price": 145.61,
      "post_only": false,
      "order_type": "stop_limit",
      "order_state": "untriggered",
      "order_id": "ETH-SLTS-28",
      "max_show": 123,
      "last_update_timestamp": 1550659803407,
      "label": "",
      "is_rebalance": false,
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "direction": "sell",
      "creation_timestamp": 1550659803407,
      "api": true,
      "amount": 123
    }
  }
}

Places a sell order for an instrument.

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
amount false number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin. The amount is a mandatory parameter if contracts parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
contracts false number It represents the requested order size in contract units and can be passed instead of amount. The contracts is a mandatory parameter if amount parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
type false string limit
stop_limit
take_limit
market
stop_market
take_market
market_limit
trailing_stop		 The order type, default: "limit"
label false string user defined label for the order (maximum 64 characters)
price false number

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

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

When adding an order with advanced=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%
time_in_force false string good_til_cancelled
good_til_day
fill_or_kill
immediate_or_cancel

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

  • "good_til_cancelled" - unfilled order remains in order book until cancelled
  • "good_til_day" - unfilled order remains in order book till the end of the trading session
  • "fill_or_kill" - execute a transaction immediately and completely or not at all
  • "immediate_or_cancel" - execute a transaction immediately, and any portion of the order that cannot be immediately filled is cancelled
display_amount false number Initial display amount for iceberg order. Has to be at least 100 times minimum amount for instrument and ratio of hidden part vs visible part has to be less than 100 as well.
post_only false boolean

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

Only valid in combination with time_in_force="good_til_cancelled"
reject_post_only false boolean

If an order is considered post-only and this field is set to true then the order is put to the order book unmodified or the request is rejected.

Only valid in combination with "post_only" set to true
reduce_only false boolean If true, the order is considered reduce-only which is intended to only reduce a current position
trigger_price false number Trigger price, required for trigger orders only (Stop-loss or Take-profit orders)
trigger_offset false number The maximum deviation from the price peak beyond which the order will be triggered
trigger false string index_price
mark_price
last_price		 Defines the trigger type. Required for "Stop-Loss", "Take-Profit" and "Trailing" trigger orders
advanced false string usd
implv		 Advanced option order type. (Only for options. Advanced USD orders are not supported for linear options.)
mmp false boolean Order MMP flag, only for order_type 'limit'
valid_until false integer Timestamp, when provided server will start processing request in Matching Engine only before given timestamp, in other cases timed_out error will be responded. Remember that the given timestamp should be consistent with the server's time, use /public/time method to obtain current server time.
linked_order_type false string one_triggers_other
one_cancels_other
one_triggers_one_cancels_other

The type of the linked order.

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

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

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

List of trades to create or cancel when this order is filled.
  ›  amount false number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  direction true string buy
sell		 Direction of trade from the maker perspective
  ›  type false string limit
stop_limit
take_limit
market
stop_market
take_market
market_limit
trailing_stop		 The order type, default: "limit"
  ›  label false string user defined label for the order (maximum 64 characters)
  ›  price false number

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

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

When adding an order with advanced=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%
  ›  reduce_only false boolean If true, the order is considered reduce-only which is intended to only reduce a current position
  ›  time_in_force false string good_til_cancelled
good_til_day
fill_or_kill
immediate_or_cancel

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

  • "good_til_cancelled" - unfilled order remains in order book until cancelled
  • "good_til_day" - unfilled order remains in order book till the end of the trading session
  • "fill_or_kill" - execute a transaction immediately and completely or not at all
  • "immediate_or_cancel" - execute a transaction immediately, and any portion of the order that cannot be immediately filled is cancelled
  ›  post_only false boolean

If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below or above the spread (according to the direction of the order).

Only valid in combination with time_in_force="good_til_cancelled"
  ›  reject_post_only false boolean

If an order is considered post-only and this field is set to true then the order is put to the order book unmodified or the request is rejected.

Only valid in combination with "post_only" set to true
  ›  trigger_price false number Trigger price, required for trigger orders only (Stop-loss or Take-profit orders)
  ›  trigger_offset false number The maximum deviation from the price peak beyond which the order will be triggered
  ›  trigger false string index_price
mark_price
last_price		 Defines the trigger type. Required for "Stop-Loss", "Take-Profit" and "Trailing" trigger orders

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  order object
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  order_id string Unique order identifier
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  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.
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  trigger_fill_condition string

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

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  primary_order_id string Unique order identifier
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/edit

curl -X GET "https://test.deribit.com/api/v2/private/edit?advanced=implv&amount=4&order_id=438994&price=222" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":3725,"jsonrpc":"2.0","method":"private/edit","params":{"advanced":"implv","amount":4,"order_id":"438994","price":222}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
order_id true string The order id
amount false number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin. The amount is a mandatory parameter if contracts parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
contracts false number It represents the requested order size in contract units and can be passed instead of amount. The contracts is a mandatory parameter if amount parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
price false number

The order price in base currency.

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

When editing an option order with advanced=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%
post_only false boolean

If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below or above the spread (accordingly to the original order type).

Only valid in combination with time_in_force="good_til_cancelled"
reduce_only false boolean If true, the order is considered reduce-only which is intended to only reduce a current position
reject_post_only false boolean

If an order is considered post-only and this field is set to true then the order is put to the order book unmodified or the request is rejected.

Only valid in combination with "post_only" set to true
advanced false string usd
implv		 Advanced option order type. If you have posted an advanced option order, it is necessary to re-supply this parameter when editing it (Only for options)
trigger_price false number Trigger price, required for trigger orders only (Stop-loss or Take-profit orders)
trigger_offset false number The maximum deviation from the price peak beyond which the order will be triggered
mmp false boolean Order MMP flag, only for order_type 'limit'
valid_until false integer Timestamp, when provided server will start processing request in Matching Engine only before given timestamp, in other cases timed_out error will be responded. Remember that the given timestamp should be consistent with the server's time, use /public/time method to obtain current server time.
display_amount false number Initial display amount for iceberg order. Has to be at least 100 times minimum amount for instrument and ratio of hidden part vs visible part has to be less than 100 as well.

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
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  order_id string Unique order identifier
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  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.
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  trigger_fill_condition string

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

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  primary_order_id string Unique order identifier
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/edit_by_label

curl -X GET "https://test.deribit.com/api/v2/private/edit_by_label?amount=150&instrument_name=BTC-PERPETUAL&label=i_love_deribit&price=50111" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":9,"jsonrpc":"2.0","method":"private/edit_by_label","params":{"amount":150,"instrument_name":"BTC-PERPETUAL","label":"i_love_deribit","price":50111}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "trades": [],
    "order": {
      "web": false,
      "time_in_force": "good_til_cancelled",
      "replaced": true,
      "reduce_only": false,
      "price": 50111.0,
      "post_only": false,
      "order_type": "limit",
      "order_state": "open",
      "order_id": "94166",
      "max_show": 150,
      "last_update_timestamp": 1616155550773,
      "label": "i_love_deribit",
      "is_rebalance": false,
      "is_liquidation": false,
      "instrument_name": "BTC-PERPETUAL",
      "filled_amount": 0,
      "direction": "buy",
      "creation_timestamp": 1616155547764,
      "average_price": 0.0,
      "api": true,
      "amount": 150
    }
  }
}

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

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
label false string user defined label for the order (maximum 64 characters)
instrument_name true string Instrument name
amount false number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin. The amount is a mandatory parameter if contracts parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
contracts false number It represents the requested order size in contract units and can be passed instead of amount. The contracts is a mandatory parameter if amount parameter is missing. If both contracts and amount parameter are passed they must match each other otherwise error is returned.
price false number

The order price in base currency.

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

When editing an option order with advanced=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%
post_only false boolean

If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below or above the spread (accordingly to the original order type).

Only valid in combination with time_in_force="good_til_cancelled"
reduce_only false boolean If true, the order is considered reduce-only which is intended to only reduce a current position
reject_post_only false boolean

If an order is considered post-only and this field is set to true then the order is put to the order book unmodified or the request is rejected.

Only valid in combination with "post_only" set to true
advanced false string usd
implv		 Advanced option order type. If you have posted an advanced option order, it is necessary to re-supply this parameter when editing it (Only for options)
trigger_price false number Trigger price, required for trigger orders only (Stop-loss or Take-profit orders)
mmp false boolean Order MMP flag, only for order_type 'limit'
valid_until false integer Timestamp, when provided server will start processing request in Matching Engine only before given timestamp, in other cases timed_out error will be responded. Remember that the given timestamp should be consistent with the server's time, use /public/time method to obtain current server time.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  order object
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  order_id string Unique order identifier
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  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.
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  trigger_fill_condition string

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

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  primary_order_id string Unique order identifier
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/cancel

curl -X GET "https://test.deribit.com/api/v2/private/cancel?order_id=ETH-SLIS-12" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":4214,"jsonrpc":"2.0","method":"private/cancel","params":{"order_id":"ETH-SLIS-12"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 4214,
  "result": {
    "triggered": false,
    "trigger": "index_price",
    "time_in_force": "good_til_cancelled",
    "trigger_price": 144.73,
    "reduce_only": false,
    "price": "market_price",
    "post_only": false,
    "order_type": "stop_market",
    "order_state": "untriggered",
    "order_id": "ETH-SLIS-12",
    "max_show": 5,
    "last_update_timestamp": 1550575961291,
    "label": "",
    "is_rebalance": false,
    "is_liquidation": false,
    "instrument_name": "ETH-PERPETUAL",
    "direction": "sell",
    "creation_timestamp": 1550575961291,
    "api": false,
    "amount": 5
  }
}

Cancel an order, specified by order id

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
order_id true string The order id

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

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

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

/private/cancel_all

curl -X GET "https://test.deribit.com/api/v2/private/cancel_all?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":8748,"jsonrpc":"2.0","method":"private/cancel_all","params":{}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
detailed false boolean When detailed is set to true output format is changed. See description. Default: false
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.

Response

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

/private/cancel_all_by_currency

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

var msg = 
{"id":5663,"jsonrpc":"2.0","method":"private/cancel_all_by_currency","params":{"currency":"BTC","kind":"option"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
type false string all
limit
trigger_all
stop
take
trailing_stop		 Order type - limit, stop, take, trigger_all or all, default - all
detailed false boolean When detailed is set to true output format is changed. See description. Default: false
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.

Response

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

/private/cancel_all_by_currency_pair

curl -X GET "https://test.deribit.com/api/v2/private/cancel_all_by_currency_pair?currency_pair=BTC_USD&kind=option" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":5663,"jsonrpc":"2.0","method":"private/cancel_all_by_currency_pair","params":{"currency_pair":"BTC_USD","kind":"option"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":5663,"jsonrpc":"2.0","method":"private/cancel_all_by_currency_pair","params":{"currency_pair":"BTC_USD","kind":"option"}}

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

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

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

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

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

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency_pair true string btc_usd
eth_usd
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
btc_usdc
btcdvol_usdc
buidl_usdc
doge_usdc
dot_usdc
eurr_usdc
eth_usdc
ethdvol_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
steth_usdc
ton_usdc
trump_usdc
trx_usdc
uni_usdc
usde_usdc
usyc_usdc
xrp_usdc
btc_usdt
eth_usdt
eurr_usdt
sol_usdt
steth_usdt
usdc_usdt
usde_usdt
btc_eurr
btc_usde
btc_usyc
eth_btc
eth_eurr
eth_usde
eth_usyc
steth_eth
paxg_btc		 The currency pair symbol
kind false string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
type false string all
limit
trigger_all
stop
take
trailing_stop		 Order type - limit, stop, take, trigger_all or all, default - all
detailed false boolean When detailed is set to true output format is changed. See description. Default: false
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.

Response

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

/private/cancel_all_by_instrument

curl -X GET "https://test.deribit.com/api/v2/private/cancel_all_by_instrument?instrument_name=ETH-22FEB19-120-P&type=all" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":4122,"jsonrpc":"2.0","method":"private/cancel_all_by_instrument","params":{"instrument_name":"ETH-22FEB19-120-P","type":"all"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
type false string all
limit
trigger_all
stop
take
trailing_stop		 Order type - limit, stop, take, trigger_all or all, default - all
detailed false boolean When detailed is set to true output format is changed. See description. Default: false
include_combos false boolean When set to true orders in combo instruments affecting a given position will also be cancelled. Default: false
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.

Response

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

/private/cancel_all_by_kind_or_type

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

var msg = 
{"id":2,"jsonrpc":"2.0","method":"private/cancel_all_by_kind_or_type","params":{"currency":["BTC","ETH"],"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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2,"jsonrpc":"2.0","method":"private/cancel_all_by_kind_or_type","params":{"currency":["BTC","ETH"],"kind":"future"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": 6
}

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

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string or array of strings The currency symbol, list of currency symbols or "any" for all
kind false string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
type false string all
limit
trigger_all
stop
take
trailing_stop		 Order type - limit, stop, take, trigger_all or all, default - all
detailed false boolean When detailed is set to true output format is changed. See description. Default: false
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.

Response

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

/private/cancel_by_label

curl -X GET "https://test.deribit.com/api/v2/private/cancel_by_label?label=label" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":47,"method":"private/cancel_by_label","params":{"label":"label"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc":"2.0",
  "id":47,
  "result":4
}

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

Scope: trade:read_write

Try in API console

Parameters

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

Response

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

/private/cancel_quotes

curl -X GET "https://test.deribit.com/api/v2/private/cancel_quotes?cancel_type=delta&max_delta=5.99999999999999977796e-01&min_delta=4.00000000000000022204e-01" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":5663,"jsonrpc":"2.0","method":"private/cancel_quotes","params":{"cancel_type":"delta","max_delta":0.6,"min_delta":0.4}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":5663,"jsonrpc":"2.0","method":"private/cancel_quotes","params":{"cancel_type":"delta","max_delta":0.6,"min_delta":0.4}}

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

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

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

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

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

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
detailed false boolean When detailed is set to true output format is changed. See description. Default: false
freeze_quotes false boolean Whether or not to reject incoming quotes for 1 second after cancelling (false by default). Related to private/mass_quote request.
cancel_type true string delta
quote_set_id
instrument
instrument_kind
currency
currency_pair
all		 Type of cancel criteria.
min_delta false number Min delta to cancel by delta (for cancel_type: delta).
max_delta false number Max delta to cancel by delta (for cancel_type: delta).
quote_set_id false string Unique identifier for the Quote set.
instrument_name false string Instrument name.
kind false string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
currency_pair true string btc_usd
eth_usd
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
btc_usdc
btcdvol_usdc
buidl_usdc
doge_usdc
dot_usdc
eurr_usdc
eth_usdc
ethdvol_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
steth_usdc
ton_usdc
trump_usdc
trx_usdc
uni_usdc
usde_usdc
usyc_usdc
xrp_usdc
btc_usdt
eth_usdt
eurr_usdt
sol_usdt
steth_usdt
usdc_usdt
usde_usdt
btc_eurr
btc_usde
btc_usyc
eth_btc
eth_eurr
eth_usde
eth_usyc
steth_eth
paxg_btc		 The currency pair symbol

Response

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

/private/close_position

curl -X GET "https://test.deribit.com/api/v2/private/close_position?instrument_name=ETH-PERPETUAL&price=1.45169999999999987494e%2B02&type=limit" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":6130,"jsonrpc":"2.0","method":"private/close_position","params":{"instrument_name":"ETH-PERPETUAL","price":145.17,"type":"limit"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 6130,
  "result": {
    "trades": [
      {
        "trade_seq": 1966068,
        "trade_id": "ETH-2696097",
        "timestamp": 1590486335742,
        "tick_direction": 0,
        "state": "filled",
        "reduce_only": true,
        "price": 202.8,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-584864807",
        "matching_id": null,
        "mark_price": 202.79,
        "liquidity": "T",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 202.86,
        "fee_currency": "ETH",
        "fee": 0.00007766,
        "direction": "sell",
        "amount": 21
      }
    ],
    "order": {
      "web": false,
      "time_in_force": "good_til_cancelled",
      "replaced": false,
      "reduce_only": true,
      "price": 198.75,
      "post_only": false,
      "order_type": "limit",
      "order_state": "filled",
      "order_id": "ETH-584864807",
      "max_show": 21,
      "last_update_timestamp": 1590486335742,
      "label": "",
      "is_rebalance": false,
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "filled_amount": 21,
      "direction": "sell",
      "creation_timestamp": 1590486335742,
      "average_price": 202.8,
      "api": true,
      "amount": 21
    }
  }
}

Makes closing position reduce only order .

Scope: trade:read_write

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  order object
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  order_id string Unique order identifier
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  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.
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  trigger_fill_condition string

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

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  primary_order_id string Unique order identifier
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/get_margins

curl -X GET "https://test.deribit.com/api/v2/private/get_margins?amount=10000&instrument_name=BTC-PERPETUAL&price=3725" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":7,"jsonrpc":"2.0","method":"private/get_margins","params":{"amount":10000,"instrument_name":"BTC-PERPETUAL","price":3725}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

The above command returns JSON structured like this:

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

Get margins for a given instrument, amount and price.

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
amount true number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
price true number Price

Response

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

/private/get_mmp_config

curl -X GET "https://test.deribit.com/api/v2/private/get_mmp_config?index_name=btc_usd&mmp_group=MassQuoteBot7" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":7859,"jsonrpc":"2.0","method":"private/get_mmp_config","params":{"index_name":"btc_usd","mmp_group":"MassQuoteBot7"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":7859,"jsonrpc":"2.0","method":"private/get_mmp_config","params":{"index_name":"btc_usd","mmp_group":"MassQuoteBot7"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7859,
  "result": [
    {
      "index_name": "btc_usd",
      "mmp_group": "MassQuoteBot7",
      "interval": 60,
      "frozen_time": 0,
      "quantity_limit": 0.5,
      "delta_limit": 0.3,
      "vega_limit": 0.1
    }
  ]
}

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

Scope: trade:read or block_rfq:read (when block_rfq = true)

Try in API console

Parameters

Parameter Required Type Enum Description
index_name false string btc_usd
eth_usd
btc_usdc
eth_usdc
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
doge_usdc
dot_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
ton_usdc
trx_usdc
trump_usdc
uni_usdc
xrp_usdc
usde_usdc
buidl_usdc
btcdvol_usdc
ethdvol_usdc
btc_usdt
eth_usdt
all		 Index identifier of derivative instrument on the platform; skipping this parameter will return all configurations
mmp_group false string Specifies the MMP group for which the configuration is being retrieved. MMP groups are used for Mass Quotes. If MMP group is not provided, the endpoint returns the configuration for the MMP settings for regular orders. The index_name must be specified before using this parameter
block_rfq false boolean If true, retrieves MMP configuration for Block RFQ. When set, requires block_rfq scope instead of trade scope. Block RFQ MMP settings are completely separate from normal order/quote MMP settings.

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
  ›  block_rfq boolean If true, indicates MMP configuration for Block RFQ. Block RFQ MMP settings are completely separate from normal order/quote MMP settings.
  ›  delta_limit number Delta limit
  ›  frozen_time integer MMP frozen time in seconds, if set to 0 manual reset is required
  ›  index_name string Index identifier, matches (base) cryptocurrency with quote currency
  ›  interval integer MMP Interval in seconds, if set to 0 MMP is disabled
  ›  mmp_group string Specified MMP Group
  ›  quantity_limit number Quantity limit
  ›  trade_count_limit integer For Block RFQ only. The maximum number of Block RFQ trades allowed in the lookback window. Each RFQ trade counts as +1 towards the limit (not individual legs). Works across all currency pairs.
  ›  vega_limit number Vega limit

/private/get_mmp_status

curl -X GET "https://test.deribit.com/api/v2/private/get_mmp_status?index_name=btc_usd&mmp_group=MassQuoteBot7" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":7851,"jsonrpc":"2.0","method":"private/get_mmp_status","params":{"index_name":"btc_usd","mmp_group":"MassQuoteBot7"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":7851,"jsonrpc":"2.0","method":"private/get_mmp_status","params":{"index_name":"btc_usd","mmp_group":"MassQuoteBot7"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7851,
  "result": [
    {
      "index_name": "btc_usd",
      "frozen_until": 1744275841861,
      "mmp_group": "MassQuoteBot7"
    }
  ]
}

Get MMP status for triggered index (or group). If the parameter is not provided, a list of all triggered MMP statuses is returned.

Scope: trade:read or block_rfq:read (when block_rfq = true)

Try in API console

Parameters

Parameter Required Type Enum Description
index_name false string btc_usd
eth_usd
btc_usdc
eth_usdc
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
doge_usdc
dot_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
ton_usdc
trx_usdc
trump_usdc
uni_usdc
xrp_usdc
usde_usdc
buidl_usdc
btcdvol_usdc
ethdvol_usdc
btc_usdt
eth_usdt
all		 Index identifier of derivative instrument on the platform; skipping this parameter will return all configurations
mmp_group false string Specifies the MMP group for which the status is being retrieved. The index_name must be specified before using this parameter.
block_rfq false boolean If true, retrieves MMP status for Block RFQ. When set, requires block_rfq scope instead of trade scope. Block RFQ MMP status is completely separate from normal order/quote MMP status.

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
  ›  block_rfq boolean If true, indicates that the MMP status is for Block RFQ. Block RFQ MMP status is completely separate from normal order/quote MMP status.
  ›  frozen_until integer Timestamp (milliseconds since the UNIX epoch) until the user will be frozen - 0 means that the user is frozen until manual reset.
  ›  index_name string Index identifier, matches (base) cryptocurrency with quote currency
  ›  mmp_group string Triggered mmp group, this parameter is optional (appears only for Mass Quote orders trigger)

/private/get_open_orders

curl -X GET "https://test.deribit.com/api/v2/private/get_open_orders?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1953,"jsonrpc":"2.0","method":"private/get_open_orders","params":{}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

Scope: trade:read

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

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

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

/private/get_open_orders_by_currency

curl -X GET "https://test.deribit.com/api/v2/private/get_open_orders_by_currency?currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1953,"jsonrpc":"2.0","method":"private/get_open_orders_by_currency","params":{"currency":"BTC"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Retrieves list of user's open orders.

Scope: trade:read

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

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

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

/private/get_open_orders_by_instrument

curl -X GET "https://test.deribit.com/api/v2/private/get_open_orders_by_instrument?instrument_name=ETH-22FEB19-120-C" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":8442,"jsonrpc":"2.0","method":"private/get_open_orders_by_instrument","params":{"instrument_name":"ETH-22FEB19-120-C"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

Scope: trade:read

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

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

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

/private/get_open_orders_by_label

curl -X GET "https://test.deribit.com/api/v2/private/get_open_orders_by_label?currency=BTC&label=fooBar" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1953,"jsonrpc":"2.0","method":"private/get_open_orders_by_label","params":{"currency":"BTC","label":"fooBar"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

Scope: trade:read

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

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

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

/private/get_order_history_by_currency

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

var msg = 
{"id":9305,"jsonrpc":"2.0","method":"private/get_order_history_by_currency","params":{"count":1,"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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
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
with_continuation false boolean When set to true, the API response format changes from a simple list of orders to an object containing the orders and a continuation token.
continuation false string Continuation token for pagination
historical false boolean

Determines whether historical trade and order records should be retrieved.

  • false (default): Returns recent records: orders for 30 min, trades for 24h.
  • true: Fetches historical records, available after a short delay due to indexing. Recent data is not included.

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
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

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

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

/private/get_order_history_by_instrument

curl -X GET "https://test.deribit.com/api/v2/private/get_order_history_by_instrument?count=1&instrument_name=BTC-PERPETUAL" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1032,"jsonrpc":"2.0","method":"private/get_order_history_by_instrument","params":{"count":1,"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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

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

Scope: trade:read

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
with_continuation false boolean When set to true, the API response format changes from a simple list of orders to an object containing the orders and a continuation token.
continuation false string Continuation token for pagination
historical false boolean

Determines whether historical trade and order records should be retrieved.

  • false (default): Returns recent records: orders for 30 min, trades for 24h.
  • true: Fetches historical records, available after a short delay due to indexing. Recent data is not included.

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
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

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

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

/private/get_order_margin_by_ids

curl -X GET "https://test.deribit.com/api/v2/private/get_order_margin_by_ids?ids=%5B%22ETH-349280%22%2C%22ETH-349279%22%2C%22ETH-349278%22%5D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":5625,"jsonrpc":"2.0","method":"private/get_order_margin_by_ids","params":{"ids":["ETH-349280","ETH-349279","ETH-349278"]}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Retrieves initial margins of given orders

Scope: trade:read

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
  ›  initial_margin_currency string Currency of initial margin
  ›  order_id string Unique order identifier

/private/get_order_state

curl -X GET "https://test.deribit.com/api/v2/private/get_order_state?order_id=ETH-331562" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":4316,"jsonrpc":"2.0","method":"private/get_order_state","params":{"order_id":"ETH-331562"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 4316,
  "result": {
    "time_in_force": "good_til_cancelled",
    "reduce_only": false,
    "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_rebalance": false,
    "is_liquidation": false,
    "instrument_name": "ETH-PERPETUAL",
    "filled_amount": 37,
    "direction": "sell",
    "creation_timestamp": 1550219749176,
    "average_price": 118.94,
    "api": false,
    "amount": 37
  }
}

Retrieve the current state of an order.

Scope: trade:read

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
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

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

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

/private/get_order_state_by_label

curl -X GET "https://test.deribit.com/api/v2/private/get_order_state_by_label?currency=ETH&label=fooBar" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":4316,"jsonrpc":"2.0","method":"private/get_order_state_by_label","params":{"currency":"ETH","label":"fooBar"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":4316,"jsonrpc":"2.0","method":"private/get_order_state_by_label","params":{"currency":"ETH","label":"fooBar"}}

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

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

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

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

Retrieve the state of recent orders with a given label.

Scope: trade:read

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

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

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

/private/get_trigger_order_history

curl -X GET "https://test.deribit.com/api/v2/private/get_trigger_order_history?count=10&currency=ETH" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2552,"jsonrpc":"2.0","method":"private/get_trigger_order_history","params":{"count":10,"currency":"ETH"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Retrieves detailed log of the user's trigger orders.

Scope: trade:read

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  continuation string Continuation token for pagination.
  ›  entries array of object
  ›    ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  order_id string Unique order identifier
  ›    ›  order_state string Order state: "triggered", "cancelled", or "rejected" with rejection reason (e.g. "rejected:reduce_direction").
  ›    ›  order_type string Requested order type: "limit or "market"
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  price number Price in base currency
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  request string Type of last request performed on the trigger order by user or system. "cancel" - when order was cancelled, "trigger:order" - when trigger order spawned market or limit order after being triggered
  ›    ›  source string Source of the order that is linked to the trigger order.
  ›    ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  trigger_order_id string Id of the user order used for the trigger-order reference before triggering
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)

/private/get_user_trades_by_currency

curl -X GET "https://test.deribit.com/api/v2/private/get_user_trades_by_currency?count=2&currency=ETH&start_id=ETH-34066" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":9367,"jsonrpc":"2.0","method":"private/get_user_trades_by_currency","params":{"count":2,"currency":"ETH","start_id":"ETH-34066"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 9367,
  "result": {
    "trades": [
      {
        "underlying_price": 204.5,
        "trade_seq": 3,
        "trade_id": "ETH-2696060",
        "timestamp": 1590480363130,
        "tick_direction": 2,
        "state": "filled",
        "reduce_only": false,
        "price": 0.361,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-584827850",
        "matching_id": null,
        "mark_price": 0.364585,
        "liquidity": "T",
        "iv": 0,
        "instrument_name": "ETH-29MAY20-130-C",
        "index_price": 203.72,
        "fee_currency": "ETH",
        "fee": 0.002,
        "direction": "sell",
        "amount": 5
      },
      {
        "underlying_price": 204.82,
        "trade_seq": 3,
        "trade_id": "ETH-2696062",
        "timestamp": 1590480416119,
        "tick_direction": 0,
        "state": "filled",
        "reduce_only": false,
        "price": 0.015,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-584828229",
        "matching_id": null,
        "mark_price": 0.000596,
        "liquidity": "T",
        "iv": 352.91,
        "instrument_name": "ETH-29MAY20-140-P",
        "index_price": 204.06,
        "fee_currency": "ETH",
        "fee": 0.002,
        "direction": "buy",
        "amount": 5
      }
    ],
    "has_more": true
  }
}

Retrieve the latest user trades that have occurred for instruments in a specific currency symbol. To read subaccount trades, use subaccount_id parameter.

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
start_id false string The ID of the first trade to be returned. Number for BTC trades, or hyphen name in ex. "ETH-15" # "ETH_USDC-16"
end_id false string The ID of the last trade to be returned. Number for BTC trades, or hyphen name in ex. "ETH-15" # "ETH_USDC-16"
count false integer Number of requested items, default - 10
start_timestamp false integer The earliest timestamp to return result from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp false integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
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)
historical false boolean

Determines whether historical trade and order records should be retrieved.

  • false (default): Returns recent records: orders for 30 min, trades for 24h.
  • true: Fetches historical records, available after a short delay due to indexing. Recent data is not included.
subaccount_id false 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 object
  ›  has_more boolean
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/get_user_trades_by_currency_and_time

curl -X GET "https://test.deribit.com/api/v2/private/get_user_trades_by_currency_and_time?count=2&currency=BTC&end_timestamp=1510480630731&start_timestamp=1590480630731" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":9292,"jsonrpc":"2.0","method":"private/get_user_trades_by_currency_and_time","params":{"count":2,"currency":"BTC","end_timestamp":1510480630731,"start_timestamp":1590480630731}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 9292,
  "result": {
    "trades": [
      {
        "underlying_price": 8994.95,
        "trade_seq": 1,
        "trade_id": "48078936",
        "timestamp": 1590480620145,
        "tick_direction": 1,
        "state": "filled",
        "reduce_only": false,
        "price": 0.028,
        "post_only": false,
        "order_type": "limit",
        "order_id": "4008699030",
        "matching_id": null,
        "mark_price": 0.03135383,
        "liquidity": "M",
        "iv": 38.51,
        "instrument_name": "BTC-27MAY20-8750-C",
        "index_price": 8993.47,
        "fee_currency": "BTC",
        "fee": 0.0004,
        "direction": "sell",
        "amount": 1
      },
      {
        "trade_seq": 299513,
        "trade_id": "47958936",
        "timestamp": 1589923311862,
        "tick_direction": 2,
        "state": "filled",
        "reduce_only": false,
        "price": 9681.5,
        "post_only": false,
        "order_type": "limit",
        "order_id": "3993343822",
        "matching_id": null,
        "mark_price": 9684,
        "liquidity": "M",
        "instrument_name": "BTC-26JUN20",
        "index_price": 9679.48,
        "fee_currency": "BTC",
        "fee": -2.1e-7,
        "direction": "buy",
        "amount": 10
      }
    ],
    "has_more": false
  }
}

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

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
kind false string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all. If not provided instruments of all kinds are considered
start_timestamp true integer The earliest timestamp to return result from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp true integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
count false integer Number of requested items, default - 10
sorting false string asc
desc
default		 Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)
historical false boolean

Determines whether historical trade and order records should be retrieved.

  • false (default): Returns recent records: orders for 30 min, trades for 24h.
  • true: Fetches historical records, available after a short delay due to indexing. Recent data is not included.

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
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/get_user_trades_by_instrument

curl -X GET "https://test.deribit.com/api/v2/private/get_user_trades_by_instrument?count=2&instrument_name=ETH-PERPETUAL&start_seq=1966042" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":5728,"jsonrpc":"2.0","method":"private/get_user_trades_by_instrument","params":{"count":2,"instrument_name":"ETH-PERPETUAL","start_seq":1966042}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 5728,
  "result": {
    "trades": [
      {
        "trade_seq": 1966042,
        "trade_id": "ETH-2696068",
        "timestamp": 1590480712800,
        "tick_direction": 3,
        "state": "filled",
        "reduce_only": false,
        "price": 203.8,
        "post_only": false,
        "order_type": "market",
        "order_id": "ETH-584830574",
        "matching_id": null,
        "mark_price": 203.78,
        "liquidity": "T",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 203.89,
        "fee_currency": "ETH",
        "fee": 0.00036801,
        "direction": "buy",
        "amount": 100
      },
      {
        "trade_seq": 1966043,
        "trade_id": "ETH-2696069",
        "timestamp": 1590480724473,
        "tick_direction": 3,
        "state": "filled",
        "reduce_only": false,
        "price": 203.8,
        "post_only": false,
        "order_type": "market",
        "order_id": "ETH-584830695",
        "matching_id": null,
        "mark_price": 203.81,
        "liquidity": "T",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 203.92,
        "fee_currency": "ETH",
        "fee": 0.00036801,
        "direction": "sell",
        "amount": 100
      }
    ],
    "has_more": true
  }
}

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

Scope: trade:read

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
start_timestamp false integer The earliest timestamp to return result from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp false integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
historical false boolean

Determines whether historical trade and order records should be retrieved.

  • false (default): Returns recent records: orders for 30 min, trades for 24h.
  • true: Fetches historical records, available after a short delay due to indexing. Recent data is not included.
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
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/get_user_trades_by_instrument_and_time

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

var msg = 
{"id":276,"jsonrpc":"2.0","method":"private/get_user_trades_by_instrument_and_time","params":{"count":2,"end_timestamp":1590480872894,"instrument_name":"BTC-PERPETUAL","start_timestamp":1590470872894}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":276,"jsonrpc":"2.0","method":"private/get_user_trades_by_instrument_and_time","params":{"count":2,"end_timestamp":1590480872894,"instrument_name":"BTC-PERPETUAL","start_timestamp":1590470872894}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 276,
  "result": {
    "trades": [
      {
        "trade_seq": 30289127,
        "trade_id": "48078944",
        "timestamp": 1590480866924,
        "tick_direction": 2,
        "state": "filled",
        "reduce_only": false,
        "price": 8988.5,
        "post_only": false,
        "order_type": "limit",
        "order_id": "4008716877",
        "matching_id": null,
        "mark_price": 8990.52,
        "liquidity": "T",
        "instrument_name": "BTC-PERPETUAL",
        "index_price": 8995.15,
        "fee_currency": "BTC",
        "fee": 0.00037465,
        "direction": "sell",
        "amount": 4490
      },
      {
        "trade_seq": 30289128,
        "trade_id": "48078945",
        "timestamp": 1590480866924,
        "tick_direction": 2,
        "state": "filled",
        "reduce_only": false,
        "price": 8983.5,
        "post_only": false,
        "order_type": "limit",
        "order_id": "4008716877",
        "matching_id": null,
        "mark_price": 8990.52,
        "liquidity": "T",
        "instrument_name": "BTC-PERPETUAL",
        "index_price": 8995.15,
        "fee_currency": "BTC",
        "fee": 0.00001503,
        "direction": "sell",
        "amount": 180
      }
    ],
    "has_more": true
  }
}

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

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
start_timestamp true integer The earliest timestamp to return result from (milliseconds since the UNIX epoch). When param is provided trades are returned from the earliest
end_timestamp true integer The most recent timestamp to return result from (milliseconds since the UNIX epoch). Only one of params: start_timestamp, end_timestamp is truly required
count false integer Number of requested items, default - 10
sorting false string asc
desc
default		 Direction of results sorting (default value means no sorting, results will be returned in order in which they left the database)
historical false boolean

Determines whether historical trade and order records should be retrieved.

  • false (default): Returns recent records: orders for 30 min, trades for 24h.
  • true: Fetches historical records, available after a short delay due to indexing. Recent data is not included.

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
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/get_user_trades_by_order

curl -X GET "https://test.deribit.com/api/v2/private/get_user_trades_by_order?order_id=ETH-584830574" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":3466,"jsonrpc":"2.0","method":"private/get_user_trades_by_order","params":{"order_id":"ETH-584830574"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 3466,
  "result": [
    {
      "trade_seq": 1966042,
      "trade_id": "ETH-2696068",
      "timestamp": 1590480712800,
      "tick_direction": 3,
      "state": "filled",
      "reduce_only": false,
      "price": 203.8,
      "post_only": false,
      "order_type": "market",
      "order_id": "ETH-584830574",
      "matching_id": null,
      "mark_price": 203.78,
      "liquidity": "T",
      "instrument_name": "ETH-PERPETUAL",
      "index_price": 203.89,
      "fee_currency": "ETH",
      "fee": 0.00036801,
      "direction": "buy",
      "amount": 100
    }
  ]
}

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

Scope: trade:read

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)
historical false boolean

Determines whether historical trade and order records should be retrieved.

  • false (default): Returns recent records: orders for 30 min, trades for 24h.
  • true: Fetches historical records, available after a short delay due to indexing. Recent data is not included.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
array of trade_id string
tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
fee_currency string Currency, i.e "BTC", "ETH", "USDC"
api boolean true if user order was created with API
advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
post_only string true if user order is post-only
direction string Direction: buy, or sell
contracts number Trade size in contract units (optional, may be absent in historical trades)
mmp boolean true if user order is MMP
fee number User's fee in units of the specified fee_currency
quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
index_price number Index Price at the moment of trade
label string User defined label (presented only when previously set for order by user)
block_trade_id string Block trade id - when trade was part of a block trade
price number Price in base currency
combo_id string Optional field containing combo instrument name if the trade is a combo trade
matching_id string Always null
order_type string Order type: "limit, "market", or "liquidation"
profit_loss number Profit and loss in base currency.
timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
iv number Option implied volatility for the price (Option only)
state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
underlying_price number Underlying price for implied volatility calculations (Options only)
block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
mark_price number Mark Price at the moment of trade
block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
reduce_only string true if user order is reduce-only
amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
trade_seq integer The sequence number of the trade within instrument
risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
instrument_name string Unique instrument identifier
legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/mass_quote

curl -X GET "https://test.deribit.com/api/v2/private/mass_quote?detailed=true&mmp_group=default&quote_id=1&quotes=%5B%7B%22ask%22%3A%7B%22amount%22%3A10%2C%22price%22%3A43800%7D%2C%22bid%22%3A%7B%22amount%22%3A10%2C%22price%22%3A43700%7D%2C%22instrument_name%22%3A%22BTC-PERPETUAL%22%2C%22quote_set_id%22%3A%22futures%22%7D%2C%7B%22ask%22%3A%7B%22amount%22%3A1%2C%22price%22%3A0.05%7D%2C%22bid%22%3A%7B%22amount%22%3A1%2C%22price%22%3A0.04%7D%2C%22instrument_name%22%3A%22BTC-22DEC23-41600-C%22%2C%22quote_set_id%22%3A%22options%22%7D%5D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":7859,"jsonrpc":"2.0","method":"private/mass_quote","params":{"detailed":true,"mmp_group":"default","quote_id":"1","quotes":[{"ask":{"amount":10,"price":43800},"bid":{"amount":10,"price":43700},"instrument_name":"BTC-PERPETUAL","quote_set_id":"futures"},{"ask":{"amount":1,"price":0.05},"bid":{"amount":1,"price":0.04},"instrument_name":"BTC-22DEC23-41600-C","quote_set_id":"options"}]}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":7859,"jsonrpc":"2.0","method":"private/mass_quote","params":{"detailed":True,"mmp_group":"default","quote_id":"1","quotes":[{"ask":{"amount":10,"price":43800},"bid":{"amount":10,"price":43700},"instrument_name":"BTC-PERPETUAL","quote_set_id":"futures"},{"ask":{"amount":1,"price":0.05},"bid":{"amount":1,"price":0.04},"instrument_name":"BTC-22DEC23-41600-C","quote_set_id":"options"}]}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7859,
  "result": {
    "errors": [
      {
        "instrument_name": "BTC-PERPETUAL",
        "side": "bid",
        "error": {
          "message": "price_too_high 43666.4288",
          "code": 10007
        }
      }
    ],
    "orders": [
      {
        "is_liquidation": false,
        "reduce_only": false,
        "risk_reducing": false,
        "last_update_timestamp": 1703162550180,
        "creation_timestamp": 1703162478689,
        "filled_amount": 0,
        "average_price": 0,
        "order_type": "limit",
        "order_state": "open",
        "quote": true,
        "quote_set_id": "options",
        "quote_id": "1",
        "post_only": false,
        "replaced": false,
        "mmp_group": "default",
        "web": false,
        "mmp": true,
        "api": false,
        "instrument_name": "BTC-22DEC23-41600-C",
        "order_id": "6653852",
        "max_show": 1,
        "time_in_force": "good_til_cancelled",
        "price": 0.04,
        "direction": "buy",
        "amount": 1,
        "label": ""
      },
      {
        "is_liquidation": false,
        "reduce_only": false,
        "risk_reducing": false,
        "last_update_timestamp": 1703162550180,
        "creation_timestamp": 1703162478689,
        "filled_amount": 0,
        "average_price": 0,
        "order_type": "limit",
        "order_state": "open",
        "quote": true,
        "quote_set_id": "options",
        "quote_id": "1",
        "post_only": false,
        "replaced": false,
        "mmp_group": "default",
        "web": false,
        "mmp": true,
        "api": false,
        "instrument_name": "BTC-22DEC23-41600-C",
        "order_id": "6653853",
        "max_show": 1,
        "time_in_force": "good_til_cancelled",
        "price": 0.05,
        "direction": "sell",
        "amount": 1,
        "label": ""
      },
      {
        "is_liquidation": false,
        "reduce_only": false,
        "risk_reducing": false,
        "last_update_timestamp": 1703162550180,
        "creation_timestamp": 1703162478689,
        "filled_amount": 0,
        "average_price": 0,
        "order_type": "limit",
        "order_state": "open",
        "quote": true,
        "quote_set_id": "futures",
        "quote_id": "1",
        "post_only": false,
        "replaced": false,
        "mmp_group": "default",
        "web": false,
        "mmp": true,
        "api": false,
        "instrument_name": "BTC-PERPETUAL",
        "order_id": "6653855",
        "max_show": 10,
        "time_in_force": "good_til_cancelled",
        "price": 43800,
        "direction": "sell",
        "amount": 10,
        "label": ""
      }
    ],
    "trades": []
  }
}

Place buy and/or sell orders on one or more instruments. This endpoint can only be used after approval from the administrators.

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
wait_for_response false boolean If false, the response is sent immediately after the risk check. If true, the response is sent after the orders all go through the matching engine. Default - true.
detailed false boolean Flag to receive a list of all order changes and a list of errors, or to only receive a list of errors. Default - false.
quote_id true string Identifier of a mass quote message. Can be used to match trades to requests. We recommend using an incrementing counter.
mmp_group true string Name of the MMP group. An MMP group has to be used and only one quote can exist per instrument per side per MMP group.
valid_until false integer Timestamp, when provided server will start processing request in Matching Engine only before given timestamp, in other cases timed_out error will be responded. Remember that the given timestamp should be consistent with the server's time, use /public/time method to obtain current server time.
quotes true array of objects List of quotes.
  ›  instrument_name true string The name of the instrument.
  ›  quote_set_id true string User-defined label that can be used for targeted cancels using private/cancel_quotes.
  ›  ask false object Order details for the ask. If not provided, bid must be present.
  ›    ›  price false number The price of this side of the quote. If no price is supplied, only the amount is amended.
  ›    ›  amount false number The amount of this side of the quote. If no quantity is supplied, only the price is amended.
  ›    ›  post_only false boolean If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below the spread. Default - false
  ›    ›  reject_post_only false boolean If an order is considered post-only and this field is set to true then the order is put to the order book unmodified or the request is rejected. Only valid in combination with "post_only" set to true. Default value - false
  ›  bid false object Order details for the bid. If not provided, ask must be present.
  ›    ›  price false number The price of this side of the quote. If no price is supplied, only the amount is amended.
  ›    ›  amount false number The amount of this side of the quote. If no quantity is supplied, only the price is amended.
  ›    ›  post_only false boolean If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below the spread. Default - false
  ›    ›  reject_post_only false boolean If an order is considered post-only and this field is set to true then the order is put to the order book unmodified or the request is rejected. Only valid in combination with "post_only" set to true. Default value - false

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  errors array of object List of errors (present when detailed : true).
  ›    ›  code int Error code
  ›    ›  error object Error data.
  ›    ›  instrument_name string Instrument name.
  ›    ›  message string Error message.
  ›    ›  side string Quote side - bid or ask.
  ›  errors_count int Number of errors (present when detailed : false).
  ›  orders array of object
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  order_id string Unique order identifier
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  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.
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  trigger_fill_condition string

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

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  primary_order_id string Unique order identifier
  ›  pending_requests array of object List of pending quotes (present when wait_for_response: false and detailed : true).
  ›    ›  instrument_name string Instrument name.
  ›    ›  side string Quote side - bid or ask.
  ›  pending_requests_count int Number of pending quotes (present when wait_for_response: false and detailed : false).
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/move_positions

curl -X GET "https://test.deribit.com/api/v2/private/move_positions?currency=BTC&source_uid=3&target_uid=23&trades=%5B%7B%22amount%22%3A%22110%22%2C%22instrument_name%22%3A%22BTC-PERPETUAL%22%2C%22price%22%3A%2235800%22%7D%2C%7B%22amount%22%3A%220.1%22%2C%22instrument_name%22%3A%22BTC-28JAN22-32500-C%22%7D%5D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":3,"jsonrpc":"2.0","method":"private/move_positions","params":{"currency":"BTC","source_uid":3,"target_uid":23,"trades":[{"amount":"110","instrument_name":"BTC-PERPETUAL","price":"35800"},{"amount":"0.1","instrument_name":"BTC-28JAN22-32500-C"}]}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":3,"jsonrpc":"2.0","method":"private/move_positions","params":{"currency":"BTC","source_uid":3,"target_uid":23,"trades":[{"amount":"110","instrument_name":"BTC-PERPETUAL","price":"35800"},{"amount":"0.1","instrument_name":"BTC-28JAN22-32500-C"}]}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": [
    {
      "target_uid": 23,
      "source_uid": 3,
      "price": 0.1223,
      "instrument_name": "BTC-28JAN22-32500-C",
      "direction": "sell",
      "amount": 0.1
    },
    {
      "target_uid": 23,
      "source_uid": 3,
      "price": 35800,
      "instrument_name": "BTC-PERPETUAL",
      "direction": "buy",
      "amount": 110
    }
  ]
}

Moves positions from source subaccount to target subaccount

Note:
In rare cases, the request may return an internal_server_error. This does not necessarily mean the operation failed entirely. Part or all of the position transfer might have still been processed successfully.

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency false string BTC
ETH
USDC
USDT
EURR		 The currency symbol
source_uid true integer Id of source subaccount. Can be found in My Account >> Subaccounts tab
target_uid true integer Id of target subaccount. Can be found in My Account >> Subaccounts tab
trades true array of objects List of trades for position move
  ›  instrument_name true string Instrument name
  ›  price false number Price for trade - if not provided average price of the position is used
  ›  amount true number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin. Amount can't exceed position size.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price in base currency
  ›    ›  source_uid integer Trade source uid
  ›    ›  target_uid integer Trade target uid

/private/reset_mmp

curl -X GET "https://test.deribit.com/api/v2/private/reset_mmp?index_name=btc_usd&mmp_group=MassQuoteBot7" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":7859,"jsonrpc":"2.0","method":"private/reset_mmp","params":{"index_name":"btc_usd","mmp_group":"MassQuoteBot7"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":7859,"jsonrpc":"2.0","method":"private/reset_mmp","params":{"index_name":"btc_usd","mmp_group":"MassQuoteBot7"}}

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

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

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

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

Reset MMP

Scope: trade:read_write or block_rfq:read_write (when block_rfq = true)

Try in API console

Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd
btc_usdc
eth_usdc
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
doge_usdc
dot_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
ton_usdc
trx_usdc
trump_usdc
uni_usdc
xrp_usdc
usde_usdc
buidl_usdc
btcdvol_usdc
ethdvol_usdc
btc_usdt
eth_usdt
all		 Index identifier of derivative instrument on the platform
mmp_group false string Specifies the MMP group for which limits are being reset. If this parameter is omitted, the endpoint resets the traditional (no group) MMP limits
block_rfq false boolean If true, resets MMP for Block RFQ. When set, requires block_rfq scope instead of trade scope. Block RFQ MMP settings are completely separate from normal order/quote MMP settings.

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

curl -X GET "https://test.deribit.com/api/v2/private/send_rfq?amount=10000&instrument_name=BTC-PERPETUAL&side=sell" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":8352,"jsonrpc":"2.0","method":"private/send_rfq","params":{"amount":10000,"instrument_name":"BTC-PERPETUAL","side":"sell"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":8352,"jsonrpc":"2.0","method":"private/send_rfq","params":{"amount":10000,"instrument_name":"BTC-PERPETUAL","side":"sell"}}

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

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

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

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

Sends RFQ on a given instrument.

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
amount false number Amount
side false string buy
sell		 Side - buy or sell

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_mmp_config

curl -X GET "https://test.deribit.com/api/v2/private/set_mmp_config?frozen_time=0&index_name=btc_usd&interval=60&mmp_group=MassQuoteBot7&quantity_limit=3.00000000000000000000e%2B00" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":7859,"jsonrpc":"2.0","method":"private/set_mmp_config","params":{"frozen_time":0,"index_name":"btc_usd","interval":60,"mmp_group":"MassQuoteBot7","quantity_limit":3.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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":7859,"jsonrpc":"2.0","method":"private/set_mmp_config","params":{"frozen_time":0,"index_name":"btc_usd","interval":60,"mmp_group":"MassQuoteBot7","quantity_limit":3.0}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7859,
  "method": "private/set_mmp_config",
  "result": {
    "index_name": "btc_usd",
    "mmp_group": "MassQuoteBot7",
    "interval" : 60,
    "frozen_time": 0,
    "quantity_limit": 3.0
  }
}

Set config for MMP - triggers MMP reset

Scope: trade:read_write or block_rfq:read_write (when block_rfq = true)

Try in API console

Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd
btc_usdc
eth_usdc
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
doge_usdc
dot_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
ton_usdc
trx_usdc
trump_usdc
uni_usdc
xrp_usdc
usde_usdc
buidl_usdc
btcdvol_usdc
ethdvol_usdc
btc_usdt
eth_usdt
all		 Index identifier of derivative instrument on the platform
interval true integer MMP Interval in seconds, if set to 0 MMP is removed
frozen_time true integer MMP frozen time in seconds, if set to 0 manual reset is required
mmp_group false string Designates the MMP group for which the configuration is being set. If the specified group is already associated with a different index_name, an error is returned. This parameter enables distinct configurations for each MMP group, linked to particular index_name
quantity_limit false number Quantity limit, positive value
delta_limit false number Delta limit, positive value
vega_limit false number Vega limit, positive value
block_rfq false boolean If true, configures MMP for Block RFQ. When set, requires block_rfq scope instead of trade scope. Block RFQ MMP settings are completely separate from normal order/quote MMP settings.
trade_count_limit false integer For Block RFQ only (block_rfq = true). Sets the maximum number of Block RFQ trades allowed in the lookback window. Each RFQ trade counts as +1 towards the limit (not individual legs). Works across all currency pairs. When using this parameter, index_name must be set to "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
  ›  block_rfq boolean If true, indicates MMP configuration for Block RFQ. Block RFQ MMP settings are completely separate from normal order/quote MMP settings.
  ›  delta_limit number Delta limit
  ›  frozen_time integer MMP frozen time in seconds, if set to 0 manual reset is required
  ›  index_name string Index identifier, matches (base) cryptocurrency with quote currency
  ›  interval integer MMP Interval in seconds, if set to 0 MMP is disabled
  ›  mmp_group string Specified MMP Group
  ›  quantity_limit number Quantity limit
  ›  trade_count_limit integer For Block RFQ only. The maximum number of Block RFQ trades allowed in the lookback window. Each RFQ trade counts as +1 towards the limit (not individual legs). Works across all currency pairs.
  ›  vega_limit number Vega limit

/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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2192,"jsonrpc":"2.0","method":"private/get_settlement_history_by_instrument","params":{"count":1,"instrument_name":"ETH-22FEB19","type":"settlement"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2192,"jsonrpc":"2.0","method":"private/get_settlement_history_by_instrument","params":{"count":1,"instrument_name":"ETH-22FEB19","type":"settlement"}}

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

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

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

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

Scope: trade:read

Try in API console

Parameters

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

Response

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

/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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":8304,"jsonrpc":"2.0","method":"private/get_settlement_history_by_currency","params":{"count":1,"currency":"BTC","type":"delivery"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":8304,"jsonrpc":"2.0","method":"private/get_settlement_history_by_currency","params":{"count":1,"currency":"BTC","type":"delivery"}}

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

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

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

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

Scope: trade:read

Try in API console

Parameters

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

Response

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

Combo Books

/public/get_combo_details

curl -X GET "https://test.deribit.com/api/v2/public/get_combo_details?combo_id=BTC-FS-29APR22_PERP" \
-H "Content-Type: application/json"

var msg = 
{"id":3,"jsonrpc":"2.0","method":"public/get_combo_details","params":{"combo_id":"BTC-FS-29APR22_PERP"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":3,"jsonrpc":"2.0","method":"public/get_combo_details","params":{"combo_id":"BTC-FS-29APR22_PERP"}}

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": 3,
  "result": {
    "state_timestamp": 1650620605150,
    "state": "active",
    "legs": [
      {
        "instrument_name": "BTC-PERPETUAL",
        "amount": -1
      },
      {
        "instrument_name": "BTC-29APR22",
        "amount": 1
      }
    ],
    "id": "BTC-FS-29APR22_PERP",
    "instrument_id": 27,
    "creation_timestamp": 1650620575000
  }
}

Retrieves information about a combo

Try in API console

Parameters

Parameter Required Type Enum Description
combo_id true string Combo 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
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  id string Unique combo identifier
  ›  instrument_id integer Instrument ID
  ›  legs array of object
  ›    ›  amount integer Size multiplier of a leg. A negative value indicates that the trades on given leg are in opposite direction to the combo trades they originate from
  ›    ›  instrument_name string Unique instrument identifier
  ›  state string Combo state: "rfq", "active", "inactive"
  ›  state_timestamp integer The timestamp (milliseconds since the Unix epoch)

/public/get_combo_ids

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

var msg = 
{"id":1,"jsonrpc":"2.0","method":"public/get_combo_ids","params":{"currency":"BTC","state":"active"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"public/get_combo_ids","params":{"currency":"BTC","state":"active"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "BTC-CS-29APR22-39300_39600",
    "BTC-FS-29APR22_PERP"
  ]
}

Retrieves available combos. This method can be used to get the list of all combos, or only the list of combos in the given state.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
state false string rfq
active
inactive		 Combo state, if not provided combos of all states 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 string Unique combo identifier

/public/get_combos

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

var msg = 
{"id":2,"jsonrpc":"2.0","method":"public/get_combos","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 = \
{"id":2,"jsonrpc":"2.0","method":"public/get_combos","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": 2,
  "result": [
    {
      "state_timestamp": 1650636265101,
      "state": "active",
      "legs": [
        {
          "instrument_name": "BTC-29APR22-39300-C",
          "amount": 1
        },
        {
          "instrument_name": "BTC-29APR22-39600-C",
          "amount": -1
        }
      ],
      "id": "BTC-CS-29APR22-39300_39600",
      "instrument_id": 28,
      "creation_timestamp": 1650636235000
    },
    {
      "state_timestamp": 1650620605150,
      "state": "active",
      "legs": [
        {
          "instrument_name": "BTC-PERPETUAL",
          "amount": -1
        },
        {
          "instrument_name": "BTC-29APR22",
          "amount": 1
        }
      ],
      "id": "BTC-FS-29APR22_PERP",
      "instrument_id": 27,
      "creation_timestamp": 1650620575000
    }
  ]
}

Retrieves information about active combos

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all

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
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  id string Unique combo identifier
  ›  instrument_id integer Instrument ID
  ›  legs array of object
  ›    ›  amount integer Size multiplier of a leg. A negative value indicates that the trades on given leg are in opposite direction to the combo trades they originate from
  ›    ›  instrument_name string Unique instrument identifier
  ›  state string Combo state: "rfq", "active", "inactive"
  ›  state_timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/create_combo

curl -X GET "https://test.deribit.com/api/v2/private/create_combo?trades=%5B%7B%22amount%22%3A%221%22%2C%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-29APR22-37500-C%22%7D%2C%7B%22amount%22%3A%221%22%2C%22direction%22%3A%22sell%22%2C%22instrument_name%22%3A%22BTC-29APR22-37500-P%22%7D%5D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":6,"jsonrpc":"2.0","method":"private/create_combo","params":{"trades":[{"amount":"1","direction":"buy","instrument_name":"BTC-29APR22-37500-C"},{"amount":"1","direction":"sell","instrument_name":"BTC-29APR22-37500-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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":6,"jsonrpc":"2.0","method":"private/create_combo","params":{"trades":[{"amount":"1","direction":"buy","instrument_name":"BTC-29APR22-37500-C"},{"amount":"1","direction":"sell","instrument_name":"BTC-29APR22-37500-P"}]}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "state_timestamp": 1650960943922,
    "state": "rfq",
    "legs": [
      {
        "instrument_name": "BTC-29APR22-37500-C",
        "amount": 1
      },
      {
        "instrument_name": "BTC-29APR22-37500-P",
        "amount": -1
      }
    ],
    "id": "BTC-REV-29APR22-37500",
    "instrument_id": 52,
    "creation_timestamp": 1650960943000
  }
}

Verifies and creates a combo book or returns an existing combo matching given trades

Scope: trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
trades true array of objects List of trades used to create a combo
  ›  instrument_name true string Instrument name
  ›  amount false number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  direction true string buy
sell		 Direction of trade from the maker perspective

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  id string Unique combo identifier
  ›  instrument_id integer Instrument ID
  ›  legs array of object
  ›    ›  amount integer Size multiplier of a leg. A negative value indicates that the trades on given leg are in opposite direction to the combo trades they originate from
  ›    ›  instrument_name string Unique instrument identifier
  ›  state string Combo state: "rfq", "active", "inactive"
  ›  state_timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/get_leg_prices

curl -X GET "https://test.deribit.com/api/v2/private/get_leg_prices?legs=%5B%7B%22amount%22%3A2%2C%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-1NOV24-67000-C%22%7D%2C%7B%22amount%22%3A2%2C%22direction%22%3A%22sell%22%2C%22instrument_name%22%3A%22BTC-1NOV24-66000-C%22%7D%5D&price=5.99999999999999977796e-01" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/get_leg_prices","params":{"legs":[{"amount":2,"direction":"buy","instrument_name":"BTC-1NOV24-67000-C"},{"amount":2,"direction":"sell","instrument_name":"BTC-1NOV24-66000-C"}],"price":0.6}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/get_leg_prices","params":{"legs":[{"amount":2,"direction":"buy","instrument_name":"BTC-1NOV24-67000-C"},{"amount":2,"direction":"sell","instrument_name":"BTC-1NOV24-66000-C"}],"price":0.6}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "legs": [
      {
        "ratio": 1,
        "instrument_name": "BTC-1NOV24-67000-C",
        "price": 0.6001,
        "direction": "buy"
      },
      {
        "ratio": 1,
        "instrument_name": "BTC-1NOV24-66000-C",
        "price": 0.0001,
        "direction": "sell"
      }
    ],
    "amount": 2
  }
}

This method returns individual leg prices for a given combo structure based on an aggregated price of the strategy and the mark prices of the individual legs. Please note that leg prices change dynamically with mark price fluctuations, and the algorithm is calibrated only for conventional option structures and future spreads. This method supports both inverse strategies and known linear structures within a single currency pair.

Try in API console

Parameters

Parameter Required Type Enum Description
legs true array of objects List of legs for which the prices will be calculated
  ›  instrument_name true string Instrument name
  ›  amount true number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  direction true string buy
sell		 Direction of selected leg
price true number Price for the whole leg structure

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 This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  legs array of object
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a leg
  ›    ›  ratio integer Ratio of amount between legs

Block Trade

/private/approve_block_trade

curl -X GET "https://test.deribit.com/api/v2/private/approve_block_trade?nonce=bt-468nha&role=maker&timestamp=1711468813551" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/approve_block_trade","params":{"nonce":"bt-468nha","role":"maker","timestamp":1711468813551}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/approve_block_trade","params":{"nonce":"bt-468nha","role":"maker","timestamp":1711468813551}}

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

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

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

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

Used to approve a pending block trade. nonce and timestamp are used to identify the block trade while role should be opposite to the trading counterparty.

To use a block trade approval feature the additional API key setting feature called: enabled_features: block_trade_approval is required. This key has to be given to broker/registered partner who performs the trades on behalf of the user for the feature to be active. If the user wants to approve the trade, he has to approve it from different API key with doesn't have this feature enabled.

Scope: block_trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
timestamp true integer Timestamp, shared with other party (milliseconds since the UNIX epoch)
nonce true string Nonce, shared with other party
role true string maker
taker		 Describes if user wants to be maker or taker of trades

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

curl -X GET "https://test.deribit.com/api/v2/private/execute_block_trade?counterparty_signature=1590485595899.1Mn52L_Q.lNyNBzXXo-_QBT_wDuMgnhA7uS9tBqdQ5TLN6rxbuoAiQhyaJYGJrm5IV_9enp9niY_x8D60AJLm3yEKPUY1Dv3T0TW0n5-ADPpJF7Fpj0eVDZpZ6QCdX8snBWrSJ0TtqevnO64RCBlN1dIm2T70PP9dlhiqPDAUYI4fpB1vLYI&nonce=bszyprbq&role=maker&timestamp=1590485535899&trades=%5B%7B%22amount%22%3A200000%2C%22direction%22%3A%22sell%22%2C%22instrument_name%22%3A%22BTC-PERPETUAL%22%2C%22price%22%3A8.9e3%7D%2C%7B%22amount%22%3A5.0%2C%22direction%22%3A%22sell%22%2C%22instrument_name%22%3A%22BTC-28MAY20-9000-C%22%2C%22price%22%3A0.0133%7D%5D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"jsonrpc":"2.0","method":"private/execute_block_trade","params":{"counterparty_signature":"1590485595899.1Mn52L_Q.lNyNBzXXo-_QBT_wDuMgnhA7uS9tBqdQ5TLN6rxbuoAiQhyaJYGJrm5IV_9enp9niY_x8D60AJLm3yEKPUY1Dv3T0TW0n5-ADPpJF7Fpj0eVDZpZ6QCdX8snBWrSJ0TtqevnO64RCBlN1dIm2T70PP9dlhiqPDAUYI4fpB1vLYI","nonce":"bszyprbq","role":"maker","timestamp":1590485535899,"trades":[{"amount":200000,"direction":"sell","instrument_name":"BTC-PERPETUAL","price":8.9e3},{"amount":5.0,"direction":"sell","instrument_name":"BTC-28MAY20-9000-C","price":0.0133}]}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"jsonrpc":"2.0","method":"private/execute_block_trade","params":{"counterparty_signature":"1590485595899.1Mn52L_Q.lNyNBzXXo-_QBT_wDuMgnhA7uS9tBqdQ5TLN6rxbuoAiQhyaJYGJrm5IV_9enp9niY_x8D60AJLm3yEKPUY1Dv3T0TW0n5-ADPpJF7Fpj0eVDZpZ6QCdX8snBWrSJ0TtqevnO64RCBlN1dIm2T70PP9dlhiqPDAUYI4fpB1vLYI","nonce":"bszyprbq","role":"maker","timestamp":1590485535899,"trades":[{"amount":200000,"direction":"sell","instrument_name":"BTC-PERPETUAL","price":8.9e3},{"amount":5.0,"direction":"sell","instrument_name":"BTC-28MAY20-9000-C","price":0.0133}]}}

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

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

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

{
  "jsonrpc":"2.0",
  "result":{
    "trades":[
      {
        "trade_seq":30289730,
        "trade_id":"48079573",
        "timestamp":1590485535978,
        "tick_direction":0,
        "state":"filled",
        "reduce_only":false,
        "price":8900.0,
        "post_only":false,
        "order_type":"limit",
        "order_id":"4009043192",
        "matching_id":"None",
        "mark_price":8895.19,
        "liquidity":"M",
        "instrument_name":"BTC-PERPETUAL",
        "index_price":8900.45,
        "fee_currency":"BTC",
        "fee":-0.00561798,
        "direction":"sell",
        "block_trade_id":"6165",
        "amount":200000.0
      },
      {
        "underlying_price":8902.86,
        "trade_seq":1,
        "trade_id":"48079574",
        "timestamp":1590485535979,
        "tick_direction":1,
        "state":"filled",
        "reduce_only":false,
        "price":0.0133,
        "post_only":false,
        "order_type":"limit",
        "order_id":"4009043194",
        "matching_id":"None",
        "mark_price":0.01831619,
        "liquidity":"M",
        "iv":62.44,
        "instrument_name":"BTC-28MAY20-9000-C",
        "index_price":8900.45,
        "fee_currency":"BTC",
        "fee":0.002,
        "direction":"sell",
        "block_trade_id":"6165",
        "amount":5.0
      }
    ],
    "timestamp":1590485535980,
    "id":"6165"
  }
}

Creates block trade

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

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

Scope: block_trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
timestamp true integer Timestamp, shared with other party (milliseconds since the UNIX epoch)
nonce true string Nonce, shared with other party
role true string maker
taker		 Describes if user wants to be maker or taker of trades
trades true array of objects List of trades for block trade
  ›  instrument_name true string Instrument name
  ›  price true number Price for trade
  ›  amount false number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  direction true string buy
sell		 Direction of trade from the maker perspective
counterparty_signature true string Signature of block trade generated by private/verify_block_trade_method

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  app_name string The name of the application that executed the block trade on behalf of the user (optional).
  ›  broker_code string Broker code associated with the broker block trade.
  ›  broker_name string Name of the broker associated with the block trade.
  ›  id string Block trade id
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/get_block_trade

curl -X GET "https://test.deribit.com/api/v2/private/get_block_trade?id=61" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"jsonrpc":"2.0","method":"private/get_block_trade","params":{"id":"61"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"jsonrpc":"2.0","method":"private/get_block_trade","params":{"id":"61"}}

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

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

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

{
  "jsonrpc": "2.0",
  "result": {
    "trades": [
      {
        "trade_seq": 37,
        "trade_id": "92437",
        "timestamp": 1565089523719,
        "tick_direction": 3,
        "state": "filled",
        "price": 0.0001,
        "order_type": "limit",
        "order_id": "343062",
        "matching_id": null,
        "liquidity": "T",
        "iv": 0,
        "instrument_name": "BTC-9AUG19-10250-C",
        "index_price": 11738,
        "fee_currency": "BTC",
        "fee": 0.00025,
        "direction": "sell",
        "block_trade_id": "61",
        "amount": 10
      },
      {
        "trade_seq": 25350,
        "trade_id": "92435",
        "timestamp": 1565089523719,
        "tick_direction": 3,
        "state": "filled",
        "price": 11590,
        "order_type": "limit",
        "order_id": "343058",
        "matching_id": null,
        "liquidity": "T",
        "instrument_name": "BTC-PERPETUAL",
        "index_price": 11737.98,
        "fee_currency": "BTC",
        "fee": 0.00000164,
        "direction": "buy",
        "block_trade_id": "61",
        "amount": 190
      }
    ],
    "timestamp": 1565089523720,
    "id": "61"
  }
}

Returns information about the users block trade

Scope: block_trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
id true string Block trade id

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  app_name string The name of the application that executed the block trade on behalf of the user (optional).
  ›  broker_code string Broker code associated with the broker block trade.
  ›  broker_name string Name of the broker associated with the block trade.
  ›  id string Block trade id
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/get_block_trade_requests

curl -X GET "https://test.deribit.com/api/v2/private/get_block_trade_requests?broker_code=jpqYKgg1" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/get_block_trade_requests","params":{"broker_code":"jpqYKgg1"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/get_block_trade_requests","params":{"broker_code":"jpqYKgg1"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "timestamp": 1742824052538,
      "state": {
        "timestamp": 1742824052539,
        "value": "initial"
      },
      "username": "Trader",
      "user_id": 8,
      "role": "taker",
      "trades": [
        {
          "amount": 100000,
          "direction": "buy",
          "price": 87516.83,
          "instrument_name": "BTC-PERPETUAL"
        }
      ],
      "broker_code": "jpqYKgg1",
      "broker_name": "Test Broker",
      "counterparty_state": {
        "timestamp": 1742824052538,
        "value": "approved"
      },
      "nonce": "29rKkuD3NSBPet4njrpNWEuHBm9s"
    }
  ]
}

Provides a list of block trade requests including pending approvals, declined trades, and expired trades. timestamp and nonce received in response can be used to approve or reject the pending block trade.

To use a block trade approval feature the additional API key setting feature called: enabled_features: block_trade_approval is required. This key has to be given to broker/registered partner who performs the trades on behalf of the user for the feature to be active. If the user wants to approve the trade, he has to approve it from different API key with doesn't have this feature enabled.

Only broker clients can use broker_code to query for their broker block trade requests.

Scope: block_trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
broker_code false string Broker code to filter block trade requests. Only broker clients can use broker_code to query for their executed broker block trades.

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
  ›  app_name string The name of the application that executed the block trade on behalf of the user (optional).
  ›  broker_code string Broker code associated with the broker block trade.
  ›  broker_name string Name of the broker associated with the block trade.
  ›  combo_id string Combo instrument identifier
  ›  counterparty_state object State of the pending block trade for the other party (optional).
  ›    ›  timestamp integer State timestamp.
  ›    ›  value string State value.
  ›  nonce string Nonce that can be used to approve or reject pending block trade.
  ›  role string Trade role of the user: maker or taker
  ›  state object State of the pending block trade for current user.
  ›    ›  timestamp integer State timestamp.
  ›    ›  value string State value.
  ›  timestamp integer Timestamp that can be used to approve or reject pending block trade.
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price in base currency
  ›  user_id integer Unique user identifier
  ›  username string Username of the user who initiated the block trade.

/private/get_block_trades

curl -X GET "https://test.deribit.com/api/v2/private/get_block_trades?count=1&currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"jsonrpc":"2.0","method":"private/get_block_trades","params":{"count":1,"currency":"BTC"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"jsonrpc":"2.0","method":"private/get_block_trades","params":{"count":1,"currency":"BTC"}}

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

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

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

{
  "jsonrpc": "2.0",
  "result": [
    {
      "trades": [
        {
          "trade_seq": 4,
          "trade_id": "92462",
          "timestamp": 1565093070164,
          "tick_direction": 2,
          "state": "filled",
          "price": 0.0151,
          "order_type": "limit",
          "order_id": "343121",
          "matching_id": null,
          "liquidity": "M",
          "iv": 72.38,
          "instrument_name": "BTC-9AUG19-11500-P",
          "index_price": 11758.65,
          "fee_currency": "BTC",
          "fee": 0,
          "direction": "sell",
          "block_trade_id": "66",
          "amount": 2.3
        },
        {
          "trade_seq": 41,
          "trade_id": "92460",
          "timestamp": 1565093070164,
          "tick_direction": 2,
          "state": "filled",
          "price": 11753,
          "order_type": "limit",
          "order_id": "343117",
          "matching_id": null,
          "liquidity": "M",
          "instrument_name": "BTC-9AUG19",
          "index_price": 11758.65,
          "fee_currency": "BTC",
          "fee": 0,
          "direction": "sell",
          "block_trade_id": "66",
          "amount": 50
        }
      ],
      "timestamp": 1565093070165,
      "id": "66"
    }
  ]
}

Returns list of users block trades. If currency is not provided, returns block trades for all currencies. block_rfq_id can be provided to receive block trades related to that particular Block RFQ.

Scope: block_trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency false string BTC
ETH
USDC
USDT
EURR		 The currency symbol
count false integer Number of requested items, default - 20
start_id false string Response will contain block trades older than the one provided in this field
end_id false string The id of the oldest block trade to be returned, start_id is required with end_id
block_rfq_id false integer ID of the Block RFQ
broker_code false string Broker code to filter block trades. Only broker clients can use broker_code to filter broker block trades. Use any for all block trades.

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
  ›  app_name string The name of the application that executed the block trade on behalf of the user (optional).
  ›  broker_code string Broker code associated with the broker block trade.
  ›  broker_name string Name of the broker associated with the block trade.
  ›  id string Block trade id
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

/private/get_broker_trade_requests

curl -X GET "https://test.deribit.com/api/v2/private/get_broker_trade_requests?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":7,"jsonrpc":"2.0","method":"private/get_broker_trade_requests","params":{}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": [
    {
      "timestamp": 1742824052547,
      "state": "activated",
      "trades": [
        {
          "amount": 100000,
          "direction": "buy",
          "price": 87516.83,
          "instrument_name": "BTC-PERPETUAL"
        }
      ],
      "maker": {
        "state": "initial",
        "client_id": 1,
        "user_id": "***009",
        "client_name": "Test Client",
        "client_link_name": "Test Client 2",
        "client_link_id": 2
      },
      "taker": {
        "state": "initial",
        "client_id": 1,
        "user_id": "***008",
        "client_name": "Test Client",
        "client_link_name": "Test Client 1",
        "client_link_id": 1
      },
      "nonce": "3WqPoAsmde9aXCSEBVUmi2XxGkgA"
    },
    {
      "timestamp": 1742824052538,
      "state": "activated",
      "trades": [
        {
          "amount": 100000,
          "direction": "buy",
          "price": 87516.83,
          "instrument_name": "BTC-PERPETUAL"
        }
      ],
      "maker": {
        "state": "approved",
        "client_id": 1,
        "user_id": "***009",
        "client_name": "Test Client",
        "client_link_name": "Test Client 2",
        "client_link_id": 2
      },
      "taker": {
        "state": "initial",
        "client_id": 1,
        "user_id": "***008",
        "client_name": "Test Client",
        "client_link_name": "Test Client 1",
        "client_link_id": 1
      },
      "nonce": "29rKkuD3NSBPet4njrpNWEuHBm9s"
    }
  ]
}

Broker Method Provides a list of broker block trade requests including pending approvals, declined trades, and expired trades. timestamp and nonce received in response can be used to approve or reject the pending broker block trade.

Scope: block_trade:read

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
  ›  maker object
  ›    ›  client_id integer ID of a client; available to broker. Represents a group of users under a common name.
  ›    ›  client_link_id integer ID assigned to a single user in a client; available to broker.
  ›    ›  client_link_name string Name of the linked user within the client; available to broker.
  ›    ›  client_name string Name of the client; available to broker.
  ›    ›  state string State of the request from the maker side: initial, approved, or rejected.
  ›    ›  user_id string Obscured user id of the maker.
  ›  nonce string Nonce for approving or rejecting the broker block trade request.
  ›  state string State of the broker block trade request.
  ›  taker object
  ›    ›  client_id integer ID of a client; available to broker. Represents a group of users under a common name.
  ›    ›  client_link_id integer ID assigned to a single user in a client; available to broker.
  ›    ›  client_link_name string Name of the linked user within the client; available to broker.
  ›    ›  client_name string Name of the client; available to broker.
  ›    ›  state string State of the request from the taker side: initial, approved, or rejected.
  ›    ›  user_id string Obscured user id of the taker.
  ›  timestamp integer Timestamp of the broker block trade request (milliseconds since the UNIX epoch).
  ›  trades array of object
  ›    ›  amount number Trade amount.
  ›    ›  direction string Trade direction (buy or sell).
  ›    ›  instrument_name string Name of the traded instrument.
  ›    ›  price number Trade price.

/private/get_broker_trades

curl -X GET "https://test.deribit.com/api/v2/private/get_broker_trades?count=1&currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"jsonrpc":"2.0","method":"private/get_broker_trades","params":{"count":1,"currency":"BTC"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"jsonrpc":"2.0","method":"private/get_broker_trades","params":{"count":1,"currency":"BTC"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "history": [
      {
        "id": "BLOCK-7",
        "timestamp": 1747239767111,
        "trades": [
          {
            "timestamp": 1747239767111,
            "amount": 100000,
            "direction": "buy",
            "price": 102079.75,
            "index_price": 102079.75,
            "instrument_name": "BTC-PERPETUAL",
            "trade_seq": 7,
            "mark_price": 102079.75,
            "tick_direction": 1,
            "contracts": 10000,
            "trade_id": "7",
            "block_trade_id": "BLOCK-7",
            "block_trade_leg_count": 1
          }
        ],
        "maker": {
          "user_id": "****009",
          "client_id": 2,
          "client_name": "Test Client 2",
          "client_link_name": "Test Client 2 l",
          "client_link_id": 2
        },
        "taker": {
          "user_id": "****008",
          "client_id": 1,
          "client_name": "Test Client 1",
          "client_link_name": "Test Client 1 l",
          "client_link_id": 1
        }
      }
    ],
    "next_start_id": 6
  }
}

Broker Method Returns list of broker block trades. If currency is not provided, returns broker block trades for all currencies.

Scope: block_trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency false string BTC
ETH
USDC
USDT
EURR		 The currency symbol
count false integer Number of requested items, default - 20
start_id false string Response will contain block trades older than the one provided in this field
end_id false string The id of the oldest block trade to be returned, start_id is required with end_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
  ›  history array of object
  ›    ›  id string Unique identifier of the block trade history entry.
  ›    ›  maker object
  ›    ›    ›  client_id integer ID of a client; available to broker. Represents a group of users under a common name.
  ›    ›    ›  client_link_id integer ID assigned to a single user in a client; available to broker.
  ›    ›    ›  client_link_name string Name of the linked user within the client; available to broker.
  ›    ›    ›  client_name string Name of the client; available to broker.
  ›    ›    ›  user_id integer Obscured user id of the maker.
  ›    ›  taker object
  ›    ›    ›  client_id integer ID of a client; available to broker. Represents a group of users under a common name.
  ›    ›    ›  client_link_id integer ID assigned to a single user in a client; available to broker.
  ›    ›    ›  client_link_name string Name of the linked user within the client; available to broker.
  ›    ›    ›  client_name string Name of the client; available to broker.
  ›    ›    ›  user_id integer Obscured user id of the taker.
  ›    ›  timestamp integer Timestamp of the block trade history entry (milliseconds since the UNIX epoch).
  ›    ›  trades array of object
  ›    ›    ›  app_name string The name of the application that executed the block trade on behalf of the user (optional).
  ›    ›    ›  broker_code string Broker code associated with the broker block trade.
  ›    ›    ›  broker_name string Name of the broker associated with the block trade.
  ›    ›    ›  id string Block trade id
  ›    ›    ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›    ›  trades array of object
  ›    ›    ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›    ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›    ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›    ›    ›  api boolean true if user order was created with API
  ›    ›    ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›    ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›    ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›    ›    ›  post_only string true if user order is post-only
  ›    ›    ›    ›  direction string Direction: buy, or sell
  ›    ›    ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›    ›    ›  mmp boolean true if user order is MMP
  ›    ›    ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›    ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›    ›    ›  index_price number Index Price at the moment of trade
  ›    ›    ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›    ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›    ›    ›  price number Price in base currency
  ›    ›    ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›    ›    ›  matching_id string Always null
  ›    ›    ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›    ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›    ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›    ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›    ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›    ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›    ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›    ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›    ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›    ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›    ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›    ›    ›  reduce_only string true if user order is reduce-only
  ›    ›    ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›    ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›    ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›    ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›    ›    ›  instrument_name string Unique instrument identifier
  ›    ›    ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)
  ›  next_start_id integer The next start ID for pagination.

/private/get_pending_block_trades

curl -X GET "https://test.deribit.com/api/v2/private/get_pending_block_trades?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":6,"jsonrpc":"2.0","method":"private/get_pending_block_trades","params":{}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":6,"jsonrpc":"2.0","method":"private/get_pending_block_trades","params":{}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": [
    {
      "nonce": "bt-468nha",
      "app_name": "test",
      "trades": [
        {
          "instrument_name": "BTC-PERPETUAL",
          "price": 70246.66,
          "direction": "buy",
          "amount": 10
        }
      ],
      "role": "maker",
      "user_id": 7,
      "state": {
        "value": "initial",
        "timestamp": 1711468813552
      },
      "timestamp": 1711468813551
    }
  ]
}

DEPRECATED: This method is deprecated. Please use private/get_block_trade_requests instead.

Provides a list of pending block trade approvals. timestamp and nonce received in response can be used to approve or reject the pending block trade.

To use a block trade approval feature the additional API key setting feature called: enabled_features: block_trade_approval is required. This key has to be given to broker/registered partner who performs the trades on behalf of the user for the feature to be active. If the user wants to approve the trade, he has to approve it from different API key with doesn't have this feature enabled.

Scope: block_trade:read

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
  ›  app_name string The name of the application that executed the block trade on behalf of the user (optional).
  ›  broker_code string Broker code associated with the broker block trade.
  ›  broker_name string Name of the broker associated with the block trade.
  ›  combo_id string Combo instrument identifier
  ›  counterparty_state object State of the pending block trade for the other party (optional).
  ›    ›  timestamp integer State timestamp.
  ›    ›  value string State value.
  ›  nonce string Nonce that can be used to approve or reject pending block trade.
  ›  role string Trade role of the user: maker or taker
  ›  state object State of the pending block trade for current user.
  ›    ›  timestamp integer State timestamp.
  ›    ›  value string State value.
  ›  timestamp integer Timestamp that can be used to approve or reject pending block trade.
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price in base currency
  ›  user_id integer Unique user identifier
  ›  username string Username of the user who initiated the block trade.

/private/invalidate_block_trade_signature

curl -X GET "https://test.deribit.com/api/v2/private/invalidate_block_trade_signature?signature=1565173369982.1M9tO0Q-.z9n9WyZUU5op9pEz6Jtd2CI71QxQMMsCZAexnIfK9HQRT1pKH3clxeIbY7Bqm-yMcWIoE3IfCDPW5VEdiN-6oS0YkKUyXPD500MUf3ULKhfkmH81EZs" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"jsonrpc":"2.0","method":"private/invalidate_block_trade_signature","params":{"signature":"1565173369982.1M9tO0Q-.z9n9WyZUU5op9pEz6Jtd2CI71QxQMMsCZAexnIfK9HQRT1pKH3clxeIbY7Bqm-yMcWIoE3IfCDPW5VEdiN-6oS0YkKUyXPD500MUf3ULKhfkmH81EZs"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"jsonrpc":"2.0","method":"private/invalidate_block_trade_signature","params":{"signature":"1565173369982.1M9tO0Q-.z9n9WyZUU5op9pEz6Jtd2CI71QxQMMsCZAexnIfK9HQRT1pKH3clxeIbY7Bqm-yMcWIoE3IfCDPW5VEdiN-6oS0YkKUyXPD500MUf3ULKhfkmH81EZs"}}

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

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

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

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

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

Scope: block_trade:read_write

Try in API console

Parameters

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

Response

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

/private/reject_block_trade

curl -X GET "https://test.deribit.com/api/v2/private/reject_block_trade?nonce=bt-468nha&role=maker&timestamp=1711468813551" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/reject_block_trade","params":{"nonce":"bt-468nha","role":"maker","timestamp":1711468813551}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/reject_block_trade","params":{"nonce":"bt-468nha","role":"maker","timestamp":1711468813551}}

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

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

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

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

Used to reject a pending block trade. nonce and timestamp are used to identify the block trade while role should be opposite to the trading counterparty.

To use a block trade approval feature the additional API key setting feature called: enabled_features: block_trade_approval is required. This key has to be given to broker/registered partner who performs the trades on behalf of the user for the feature to be active. If the user wants to approve the trade, he has to approve it from different API key with doesn't have this feature enabled.

Scope: block_trade:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
timestamp true integer Timestamp, shared with other party (milliseconds since the UNIX epoch)
nonce true string Nonce, shared with other party
role true string maker
taker		 Describes if user wants to be maker or taker of trades

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

curl -X GET "https://test.deribit.com/api/v2/private/simulate_block_trade?role=maker&trades=%5B%7B%22amount%22%3A40%2C%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-PERPETUAL%22%2C%22price%22%3A11624%7D%2C%7B%22amount%22%3A1.2%2C%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-9AUG19-10250-P%22%2C%22price%22%3A0.0707%7D%5D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"jsonrpc":"2.0","method":"private/simulate_block_trade","params":{"role":"maker","trades":[{"amount":40,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":11624},{"amount":1.2,"direction":"buy","instrument_name":"BTC-9AUG19-10250-P","price":0.0707}]}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"jsonrpc":"2.0","method":"private/simulate_block_trade","params":{"role":"maker","trades":[{"amount":40,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":11624},{"amount":1.2,"direction":"buy","instrument_name":"BTC-9AUG19-10250-P","price":0.0707}]}}

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

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

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

{
  "jsonrpc":"2.0",
  "result":true
}

Checks if a block trade can be executed

Scope: block_trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
role false string maker
taker		 Describes if user wants to be maker or taker of trades
trades true array of objects List of trades for block trade
  ›  instrument_name true string Instrument name
  ›  price true number Price for trade
  ›  amount false number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  direction true string buy
sell		 Direction of trade from the maker perspective

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result boolean true if block trade can be executed, false otherwise

/private/verify_block_trade

curl -X GET "https://test.deribit.com/api/v2/private/verify_block_trade?nonce=okpdjkdo&role=maker&timestamp=1565172650935&trades=%5B%7B%22amount%22%3A40%2C%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-PERPETUAL%22%2C%22price%22%3A11624%7D%2C%7B%22amount%22%3A1.2%2C%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-9AUG19-10250-P%22%2C%22price%22%3A0.0707%7D%5D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"jsonrpc":"2.0","method":"private/verify_block_trade","params":{"nonce":"okpdjkdo","role":"maker","timestamp":1565172650935,"trades":[{"amount":40,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":11624},{"amount":1.2,"direction":"buy","instrument_name":"BTC-9AUG19-10250-P","price":0.0707}]}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"jsonrpc":"2.0","method":"private/verify_block_trade","params":{"nonce":"okpdjkdo","role":"maker","timestamp":1565172650935,"trades":[{"amount":40,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":11624},{"amount":1.2,"direction":"buy","instrument_name":"BTC-9AUG19-10250-P","price":0.0707}]}}

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

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

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

{
  "jsonrpc":"2.0",
  "result":{
    "signature":"1565172710935.1ESE83qh.g6fbgRd4VWagaJz7xdi2WaV-q-d3J0njoz1jZavuRudZJZif9uH8XdUAx1LHsu0E3e0ZG_xe1UPYlwo41xRVrkWU6OMgygDRafUkEmBuk9iLqjc9rh4"
  }
}

Verifies and creates block trade signature

Scope: block_trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
timestamp true integer Timestamp, shared with other party (milliseconds since the UNIX epoch)
nonce true string Nonce, shared with other party
role true string maker
taker		 Describes if user wants to be maker or taker of trades
trades true array of objects List of trades for block trade
  ›  instrument_name true string Instrument name
  ›  price true number Price for trade
  ›  amount false number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  direction true string buy
sell		 Direction of trade from the maker perspective

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  signature string Signature of block trade
It is valid only for 5 minutes around given timestamp

Block RFQ

/public/get_block_rfq_trades

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

var msg = 
{"id":1,"jsonrpc":"2.0","method":"public/get_block_rfq_trades","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 = \
{"id":1,"jsonrpc":"2.0","method":"public/get_block_rfq_trades","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": 1,
  "result": {
    "continuation": "1739739009234:6570",
    "block_rfqs": [
      {
        "id": 6611,
        "timestamp": 1739803305362,
        "combo_id": "BTC-CS-28FEB25-100000_106000",
        "legs": [
          {
            "price": 0.1,
            "direction": "buy",
            "instrument_name": "BTC-28FEB25-100000-C",
            "ratio": 1
          },
          {
            "price": 0.05,
            "direction": "sell",
            "instrument_name": "BTC-28FEB25-106000-C",
            "ratio": 1
          }
        ],
        "amount": 12.5,
        "direction": "sell",
        "mark_price": 0.010356754,
        "trades": [
          {
            "price": 0.05,
            "amount": 12.5,
            "direction": "sell",
            "hedge_amount": 50
          }
        ],
        "hedge": {
          "price": 96000,
          "amount": 50,
          "direction": "sell",
          "instrument_name": "BTC-PERPETUAL"
        }
      },
      {
        "id": 6600,
        "timestamp": 1739774397766,
        "combo_id": "BTC-CS-28FEB25-100000_106000",
        "legs": [
          {
            "price": 0.1,
            "direction": "buy",
            "instrument_name": "BTC-28FEB25-100000-C",
            "ratio": 1
          },
          {
            "price": 0.05,
            "direction": "sell",
            "instrument_name": "BTC-28FEB25-106000-C",
            "ratio": 1
          }
        ],
        "amount": 12.5,
        "direction": "sell",
        "mark_price": 0.007458089,
        "trades": [
          {
            "price": 0.05,
            "amount": 12.5,
            "direction": "sell",
            "hedge_amount": 50
          }
        ],
        "hedge": {
          "price": 96000,
          "amount": 50,
          "direction": "sell",
          "instrument_name": "BTC-PERPETUAL"
        }
      },
      {
        "id": 6579,
        "timestamp": 1739743922308,
        "combo_id": "BTC-CS-17FEB25-89000_90000",
        "legs": [
          {
            "price": 0.08,
            "direction": "buy",
            "instrument_name": "BTC-17FEB25-89000-C",
            "ratio": 1
          },
          {
            "price": 0.075,
            "direction": "sell",
            "instrument_name": "BTC-17FEB25-90000-C",
            "ratio": 1
          }
        ],
        "amount": 12.5,
        "direction": "sell",
        "mark_price": 0.010314468,
        "trades": [
          {
            "price": 0.005,
            "amount": 12.5,
            "direction": "sell"
          }
        ]
      }
    ]
  }
}

This method returns a list of recent Block RFQs trades. Can be optionally filtered by currency.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all
continuation false integer The continuation parameter specifies the starting point for fetching historical Block RFQs. When provided, the endpoint returns Block RFQs, starting from the specified ID and continuing backward (e.g., if continuation is 50, results will include Block RFQs of ID 49, 48, etc.)
count false integer Count of Block RFQs returned

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  block_rfqs array of object
  ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›  combo_id string Unique combo identifier
  ›    ›  direction string Direction: buy, or sell
  ›    ›  hedge object
  ›    ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›    ›  direction string Direction: buy, or sell
  ›    ›    ›  instrument_name string Unique instrument identifier
  ›    ›    ›  price number Price for a hedge leg
  ›    ›  id integer ID of the Block RFQ
  ›    ›  legs array of object
  ›    ›    ›  direction string Direction: buy, or sell
  ›    ›    ›  instrument_name string Unique instrument identifier
  ›    ›    ›  price number Price for a leg
  ›    ›    ›  ratio integer Ratio of amount between legs
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  trades array of object
  ›    ›    ›  amount number Trade amount. For options, linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›    ›  direction string Direction: buy, or sell
  ›    ›    ›  hedge_amount number Amount of the hedge leg. For linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›    ›  price number Price in base currency
  ›  continuation string Continuation token for pagination. NULL when no continuation. Consists of timestamp and block_rfq_id.

/private/accept_block_rfq

curl -X GET "https://test.deribit.com/api/v2/private/accept_block_rfq?amount=100&block_rfq_id=1&direction=buy&legs=%5B%7B%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-8NOV24-70000-C%22%2C%22ratio%22%3A1%7D%2C%7B%22direction%22%3A%22sell%22%2C%22instrument_name%22%3A%22BTC-8NOV24-72000-C%22%2C%22ratio%22%3A1%7D%5D&price=1.00000000000000002082e-02&time_in_force=fill_or_kill" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/accept_block_rfq","params":{"amount":100,"block_rfq_id":1,"direction":"buy","legs":[{"direction":"buy","instrument_name":"BTC-8NOV24-70000-C","ratio":1},{"direction":"sell","instrument_name":"BTC-8NOV24-72000-C","ratio":1}],"price":0.01,"time_in_force":"fill_or_kill"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/accept_block_rfq","params":{"amount":100,"block_rfq_id":1,"direction":"buy","legs":[{"direction":"buy","instrument_name":"BTC-8NOV24-70000-C","ratio":1},{"direction":"sell","instrument_name":"BTC-8NOV24-72000-C","ratio":1}],"price":0.01,"time_in_force":"fill_or_kill"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "id": "BLOCK-423",
      "timestamp": 1730798381504,
      "trades": [
        {
          "timestamp": 1730798381502,
          "state": "filled",
          "fee": 1.5e-7,
          "amount": 100,
          "direction": "buy",
          "price": 69696.8,
          "index_price": 70000,
          "profit_loss": 0,
          "instrument_name": "BTC-8NOV24-70000-C",
          "trade_seq": 113,
          "mark_price": 0.03,
          "order_id": "2899",
          "matching_id": null,
          "tick_direction": 2,
          "combo_id": "BTC-CS-8NOV24-70000_72000",
          "block_rfq_id": 1,
          "api": true,
          "contracts": 100,
          "post_only": false,
          "block_trade_id": "BLOCK-423",
          "trade_id": "771",
          "order_type": "limit",
          "mmp": false,
          "risk_reducing": false,
          "reduce_only": false,
          "block_trade_leg_count": 2,
          "self_trade": false,
          "fee_currency": "BTC",
          "liquidity": "T"
        },
       {
          "timestamp": 1730798381502,
          "state": "filled",
          "fee": 1.5e-7,
          "amount": 100,
          "direction": "sell",
          "price": 69677.4,
          "index_price": 70000,
          "profit_loss": 0,
          "instrument_name": "BTC-8NOV24-72000-C",
          "trade_seq": 113,
          "mark_price": 0.02,
          "order_id": "2900",
          "matching_id": null,
          "tick_direction": 2,
          "combo_id": "BTC-CS-8NOV24-70000_72000",
          "block_rfq_id": 548,
          "api": true,
          "contracts": 100,
          "post_only": false,
          "block_trade_id": "BLOCK-423",
          "trade_id": "772",
          "order_type": "limit",
          "mmp": false,
          "risk_reducing": false,
          "reduce_only": false,
          "block_trade_leg_count": 2,
          "self_trade": false,
          "fee_currency": "BTC",
          "liquidity": "T"
        }
      ]
    }
  ]
}

Taker method

This method allows Block RFQ taker to accept the response by sending a single crossing price. The order can be either filled immediately (fill_or_kill) or remain active until cancelled (good_til_cancelled). Please note that after Block RFQ creation, a grace period of 5 seconds begins, during which the taker cannot see quotes or trade the Block RFQ.

Scope: block_rfq:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
block_rfq_id true integer ID of the Block RFQ
price true number Maximum acceptable price for execution
amount true number This value multiplied by the ratio of a leg gives trade size on that leg.
direction true string buy
sell		 Direction of the trade from the taker perspective
hedge false object Hedge leg of the Block RFQ. There is only one hedge leg allowed per Block RFQ
  ›    ›  instrument_name true string Instrument name
  ›    ›  direction true string buy
sell		 Direction of selected leg. Must match the direction of the corresponding leg in the Block RFQ
  ›    ›  price true number Hedge leg price
  ›    ›  amount true number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
legs true array of objects List of legs used to trade Block RFQ
  ›  instrument_name true string Instrument name
  ›  direction true string buy
sell		 Direction of selected leg. Must match the direction of the corresponding leg in the Block RFQ
  ›  ratio true integer Ratio of amount between legs
time_in_force true string fill_or_kill
good_til_cancelled		 Specifies how long the order should remain active

Response

Name Type Description
block_trades array of object
  ›  app_name string The name of the application that executed the block trade on behalf of the user (optional).
  ›  broker_code string Broker code associated with the broker block trade.
  ›  broker_name string Name of the broker associated with the block trade.
  ›  id string Block trade id
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)
trade_trigger object
  ›  direction string
  ›  price number
  ›  state string

/private/add_block_rfq_quote

curl -X GET "https://test.deribit.com/api/v2/private/add_block_rfq_quote?amount=10000&block_rfq_id=3&direction=buy&execution_instruction=any_part_of&expires_at=1745312540321&hedge=%7B%22amount%22%3A10%2C%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-PERPETUAL%22%2C%22price%22%3A70000%7D&label=example_quote&legs=%5B%7B%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-15NOV24%22%2C%22price%22%3A69600%2C%22ratio%22%3A%221%22%7D%5D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/add_block_rfq_quote","params":{"amount":10000,"block_rfq_id":3,"direction":"buy","execution_instruction":"any_part_of","expires_at":1745312540321,"hedge":{"amount":10,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":70000},"label":"example_quote","legs":[{"direction":"buy","instrument_name":"BTC-15NOV24","price":69600,"ratio":"1"}]}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/add_block_rfq_quote","params":{"amount":10000,"block_rfq_id":3,"direction":"buy","execution_instruction":"any_part_of","expires_at":1745312540321,"hedge":{"amount":10,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":70000},"label":"example_quote","legs":[{"direction":"buy","instrument_name":"BTC-15NOV24","price":69600,"ratio":"1"}]}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "label": "example_quote",
    "amount": 10000,
    "direction": "buy",
    "price": 69600,
    "legs": [
      {
        "direction": "buy",
        "price": 69600,
        "instrument_name": "BTC-15NOV24",
        "ratio": 1
      }
    ],
    "creation_timestamp": 1731076586371,
    "block_rfq_id": 3,
    "replaced": false,
    "filled_amount": 0,
    "hedge": {
      "amount": 10,
      "direction": "buy",
      "price": 70000,
      "instrument_name": "BTC-PERPETUAL"
    },
    "last_update_timestamp": 1731076586371,
    "block_rfq_quote_id": 8,
    "quote_state": "open"
  }
}

Maker method

This method adds quote to the existing Block RFQ. To calculate individual leg prices, the private/get_leg_prices endpoint can be utilized.

Scope: block_rfq:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
label false string User defined label for the Block RFQ quote (maximum 64 characters). Used to identify quotes of a selected Block RFQ
block_rfq_id true integer ID of the Block RFQ
amount true number This value multiplied by the ratio of a leg gives trade size on that leg.
direction true string buy
sell		 Direction of trade from the maker perspective
legs true array of objects List of legs used for Block RFQ quote
  ›  instrument_name true string Instrument name
  ›  price true number Price for trade
  ›  ratio true integer Ratio of amount between legs
  ›  direction true string buy
sell		 Direction of selected leg. Must match the direction of the corresponding leg in the Block RFQ
hedge false object Hedge leg of the Block RFQ. There is only one hedge leg allowed per Block RFQ
  ›    ›  instrument_name true string Instrument name
  ›    ›  direction true string buy
sell		 Direction of selected leg. Must match the direction of the corresponding leg in the Block RFQ
  ›    ›  price true number Hedge leg price
  ›    ›  amount true number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
execution_instruction false string all_or_none
any_part_of

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount. Additionally, 'any_part_of' quotes have priority over 'all_or_none' quotes at the same price level.
price false number Aggregated price used for quoting future spreads.
expires_at false integer The timestamp when the quote expires (milliseconds since the Unix epoch)

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  app_name string The name of the application that placed the quote on behalf of the user (optional).
  ›  block_rfq_id integer ID of the Block RFQ
  ›  block_rfq_quote_id integer ID of the Block RFQ quote
  ›  creation_timestamp integer The timestamp when quote was created (milliseconds since the Unix epoch)
  ›  direction string Direction of trade from the maker perspective
  ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›  filled_amount number Filled amount of the quote. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  hedge object
  ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a hedge leg
  ›  label string User defined label for the quote (maximum 64 characters)
  ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›  legs array of object
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a leg
  ›    ›  ratio integer Ratio of amount between legs
  ›  price number Price of a quote
  ›  quote_state string State of the quote
  ›  quote_state_reason string Reason of quote cancellation
  ›  replaced boolean true if the quote was edited, otherwise false.

/private/cancel_all_block_rfq_quotes

curl -X GET "https://test.deribit.com/api/v2/private/cancel_all_block_rfq_quotes?block_rfq_id=154" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":24,"jsonrpc":"2.0","method":"private/cancel_all_block_rfq_quotes","params":{"block_rfq_id":154}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":24,"jsonrpc":"2.0","method":"private/cancel_all_block_rfq_quotes","params":{"block_rfq_id":154}}

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

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

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

{
  "jsonrpc": "2.0",
  "result": 1
}

Maker method

This method cancels all user quotes in all Block RFQs. Optionally cancels all quotes in a specific RFQ if the block_rfq_id is provided.

Scope: block_rfq:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
block_rfq_id false integer ID of the Block RFQ
detailed false boolean When detailed is set to true output format is changed. See description. Default: false

Response

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

/private/cancel_block_rfq

curl -X GET "https://test.deribit.com/api/v2/private/cancel_block_rfq?block_rfq_id=366" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/cancel_block_rfq","params":{"block_rfq_id":366}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/cancel_block_rfq","params":{"block_rfq_id":366}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "creation_timestamp": 1729855159611,
    "block_rfq_id": 366,
    "expiration_timestamp": 1729855459611,
    "role": "taker",
    "asks": [],
    "bids": [],
    "makers": [],
    "amount": 100000,
    "legs": [
      {
        "ratio": 1,
        "instrument_name": "BTC-1NOV24",
        "direction": "sell"
      },
      {
        "ratio": 1,
        "instrument_name": "BTC-PERPETUAL",
        "direction": "buy"
      }
    ],
    "combo_id": "BTC-FS-1NOV24_PERP",
    "state": "cancelled",
    "label": "example"
  }
}

Taker method

This method cancels a Block RFQ using the specified block_rfq_id.

Scope: block_rfq:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
block_rfq_id true integer ID of the Block RFQ

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 This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  app_name string The name of the application that created the Block RFQ on behalf of the user (optional, visible only to taker).
  ›  asks array of object
  ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›    ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›    ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›    ›  makers array of string Maker of the quote
  ›    ›  price number Price of a quote
  ›  bids array of object
  ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›    ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›    ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›    ›  makers array of string Maker of the quote
  ›    ›  price number Price of a quote
  ›  block_rfq_id integer ID of the Block RFQ
  ›  combo_id string Unique combo identifier
  ›  creation_timestamp integer The timestamp when Block RFQ was created (milliseconds since the Unix epoch)
  ›  disclosed boolean Indicates whether the RFQ was created as non-anonymous, meaning taker and maker aliases are visible to counterparties.
  ›  expiration_timestamp integer The timestamp when the Block RFQ will expire (milliseconds since the UNIX epoch)
  ›  hedge object
  ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a hedge leg
  ›  included_in_taker_rating boolean Indicates whether the RFQ is included in the taker's rating calculation. Present only for closed RFQs created by the requesting taker.
  ›  index_prices array of number A list of index prices for the underlying instrument(s) at the time of trade execution.
  ›  label string User defined label for the Block RFQ (maximum 64 characters)
  ›  legs array of object
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  ratio integer Ratio of amount between legs
  ›  makers array of string List of targeted Block RFQ makers
  ›  mark_price number The mark price for the instrument
  ›  min_trade_amount number Minimum amount for trading
  ›  role string Role of the user in Block RFQ
  ›  state string State of the Block RFQ
  ›  taker_rating string Rating of the taker
  ›  trade_trigger object Contains information about the trade trigger state
  ›    ›  cancel_reason string Reason for cancellation, present only when state is cancelled
  ›    ›  direction string Direction of the trade trigger
  ›    ›  price number Price of the trade trigger
  ›    ›  state string Trade trigger state: "untriggered" or "cancelled"
  ›  trades array of object
  ›    ›  amount number Trade amount. For options, linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  hedge_amount number Amount of the hedge leg. For linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›  maker string Alias of the maker (optional)
  ›    ›  price number Price in base currency

/private/cancel_block_rfq_quote

curl -X GET "https://test.deribit.com/api/v2/private/cancel_block_rfq_quote?block_rfq_id=3&label=example_quote" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/cancel_block_rfq_quote","params":{"block_rfq_id":3,"label":"example_quote"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/cancel_block_rfq_quote","params":{"block_rfq_id":3,"label":"example_quote"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "label": "example_quote",
    "amount": 20000,
    "direction": "buy",
    "price": 74600,
    "legs": [
      {
        "direction": "buy",
        "price": 74600,
        "instrument_name": "BTC-15NOV24",
        "ratio": 1
      }
    ],
    "creation_timestamp": 1731076586371,
    "block_rfq_id": 3,
    "replaced": false,
    "filled_amount": 0,
    "last_update_timestamp": 1731076655746,
    "hedge": {
      "amount": 10,
      "direction": "buy",
      "price": 70000,
      "instrument_name": "BTC-PERPETUAL"
    },
    "block_rfq_quote_id": 8,
    "quote_state": "cancelled"
  }
}

Maker method

This method cancels a Block RFQ quote using the specified block_rfq_quote_id. Alternatively, user can use a combination of block_rfq_id and label to cancel the quote.

Scope: block_rfq:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
block_rfq_quote_id false integer ID of the Block RFQ quote
label false string User defined label for the Block RFQ quote (maximum 64 characters). Used to identify quotes of a selected Block RFQ
block_rfq_id false integer ID of the Block RFQ

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 This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  app_name string The name of the application that placed the quote on behalf of the user (optional).
  ›  block_rfq_id integer ID of the Block RFQ
  ›  block_rfq_quote_id integer ID of the Block RFQ quote
  ›  creation_timestamp integer The timestamp when quote was created (milliseconds since the Unix epoch)
  ›  direction string Direction of trade from the maker perspective
  ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›  filled_amount number Filled amount of the quote. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  hedge object
  ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a hedge leg
  ›  label string User defined label for the quote (maximum 64 characters)
  ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›  legs array of object
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a leg
  ›    ›  ratio integer Ratio of amount between legs
  ›  price number Price of a quote
  ›  quote_state string State of the quote
  ›  quote_state_reason string Reason of quote cancellation
  ›  replaced boolean true if the quote was edited, otherwise false.

/private/cancel_block_rfq_trigger

curl -X GET "https://test.deribit.com/api/v2/private/cancel_block_rfq_trigger?block_rfq_id=123" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/cancel_block_rfq_trigger","params":{"block_rfq_id":123}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/cancel_block_rfq_trigger","params":{"block_rfq_id":123}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "creation_timestamp": 1730798381504,
    "expiration_timestamp": 1730798481504,
    "block_rfq_id": 123,
    "role": "taker",
    "state": "open",
    "taker_rating": "1-2",
    "makers": ["maker1", "maker2"],
    "amount": 100,
    "min_trade_amount": 10,
    "legs": [
      {
        "instrument_name": "BTC-8NOV24-70000-C",
        "ratio": 1
      },
      {
        "instrument_name": "BTC-8NOV24-72000-C",
        "ratio": 1
      }
    ],
    "combo_id": "BTC-CS-8NOV24-70000_72000",
    "label": "My Block RFQ",
    "app_name": "Example Application",
    "mark_price": 0.025,
    "disclosed": false,
    "trade_trigger": {
      "state": "cancelled",
      "price": 0.01,
      "direction": "buy",
      "cancel_reason": "User cancelled"
    }
  }
}

Taker method

This method allows Block RFQ taker to cancel an active trigger for a Block RFQ. The response includes the full Block RFQ object with the trade trigger state set to cancelled.

Scope: block_rfq:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
block_rfq_id true integer ID of the Block RFQ

Response

Name Type Description
amount number This value multiplied by the ratio of a leg gives trade size on that leg.
app_name string The name of the application that created the Block RFQ on behalf of the user (optional, visible only to taker).
asks array of object
  ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›  makers array of string Maker of the quote
  ›  price number Price of a quote
bids array of object
  ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›  makers array of string Maker of the quote
  ›  price number Price of a quote
block_rfq_id integer ID of the Block RFQ
combo_id string Unique combo identifier
creation_timestamp integer The timestamp when Block RFQ was created (milliseconds since the Unix epoch)
disclosed boolean Indicates whether the RFQ was created as non-anonymous, meaning taker and maker aliases are visible to counterparties.
expiration_timestamp integer The timestamp when the Block RFQ will expire (milliseconds since the UNIX epoch)
hedge object
  ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  direction string Direction: buy, or sell
  ›  instrument_name string Unique instrument identifier
  ›  price number Price for a hedge leg
included_in_taker_rating boolean Indicates whether the RFQ is included in the taker's rating calculation. Present only for closed RFQs created by the requesting taker.
index_prices array of number A list of index prices for the underlying instrument(s) at the time of trade execution.
label string User defined label for the Block RFQ (maximum 64 characters)
legs array of object
  ›  direction string Direction: buy, or sell
  ›  instrument_name string Unique instrument identifier
  ›  ratio integer Ratio of amount between legs
makers array of string List of targeted Block RFQ makers
mark_price number The mark price for the instrument
min_trade_amount number Minimum amount for trading
role string Role of the user in Block RFQ
state string State of the Block RFQ
taker_rating string Rating of the taker
trade_trigger object Contains information about the trade trigger state
  ›  cancel_reason string Reason for cancellation, present only when state is cancelled
  ›  direction string Direction of the trade trigger
  ›  price number Price of the trade trigger
  ›  state string Trade trigger state: "untriggered" or "cancelled"
trades array of object
  ›  amount number Trade amount. For options, linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›  direction string Direction: buy, or sell
  ›  hedge_amount number Amount of the hedge leg. For linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›  maker string Alias of the maker (optional)
  ›  price number Price in base currency

/private/create_block_rfq

curl -X GET "https://test.deribit.com/api/v2/private/create_block_rfq?hedge=%7B%22amount%22%3A10%2C%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-PERPETUAL%22%2C%22price%22%3A70000%7D&label=example&legs=%5B%7B%22amount%22%3A20000%2C%22direction%22%3A%22sell%22%2C%22instrument_name%22%3A%22BTC-15NOV24%22%7D%5D&makers=%5B%22MAKER1%22%5D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/create_block_rfq","params":{"hedge":{"amount":10,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":70000},"label":"example","legs":[{"amount":20000,"direction":"sell","instrument_name":"BTC-15NOV24"}],"makers":["MAKER1"]}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/create_block_rfq","params":{"hedge":{"amount":10,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":70000},"label":"example","legs":[{"amount":20000,"direction":"sell","instrument_name":"BTC-15NOV24"}],"makers":["MAKER1"]}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "label": "example",
    "state": "created",
    "amount": 20000,
    "role": "taker",
    "bids": [],
    "asks": [],
    "combo_id": "BTC-15NOV24",
    "legs": [
      {
        "direction": "sell",
        "instrument_name": "BTC-15NOV24",
        "ratio": 1
      }
    ],
    "creation_timestamp": 1731062187555,
    "block_rfq_id": 507,
    "expiration_timestamp": 1731062487555,
    "hedge": {
      "amount": 10,
      "direction": "buy",
      "price": 70000,
      "instrument_name": "BTC-PERPETUAL"
    },
    "makers": [
      "MAKER1"
    ]
  }
}

Taker method

This method creates a new Block RFQ.

Scope: block_rfq:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
legs true array of objects List of legs used to create Block RFQ
  ›  instrument_name true string Instrument name
  ›  amount true number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  direction true string buy
sell		 Direction of selected leg
hedge false object Hedge leg of the Block RFQ. There is only one hedge leg allowed per Block RFQ
  ›    ›  instrument_name true string Instrument name
  ›    ›  direction true string buy
sell		 Direction of selected leg
  ›    ›  price true number Hedge leg price
  ›    ›  amount true number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
label false string User defined label for the Block RFQ (maximum 64 characters)
makers false array List of targeted Block RFQ makers. Only those makers will be notified about created Block RFQ. If the list is empty, all available makers will be targeted.
disclosed false boolean Determines whether the RFQ is non-anonymous, revealing both taker and maker aliases. It can be set to false (anonymous mode) only when at least 5 makers are targeted. Default value is true.

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 This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  app_name string The name of the application that created the Block RFQ on behalf of the user (optional, visible only to taker).
  ›  asks array of object
  ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›    ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›    ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›    ›  makers array of string Maker of the quote
  ›    ›  price number Price of a quote
  ›  bids array of object
  ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›    ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›    ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›    ›  makers array of string Maker of the quote
  ›    ›  price number Price of a quote
  ›  block_rfq_id integer ID of the Block RFQ
  ›  combo_id string Unique combo identifier
  ›  creation_timestamp integer The timestamp when Block RFQ was created (milliseconds since the Unix epoch)
  ›  disclosed boolean Indicates whether the RFQ was created as non-anonymous, meaning taker and maker aliases are visible to counterparties.
  ›  expiration_timestamp integer The timestamp when the Block RFQ will expire (milliseconds since the UNIX epoch)
  ›  hedge object
  ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a hedge leg
  ›  included_in_taker_rating boolean Indicates whether the RFQ is included in the taker's rating calculation. Present only for closed RFQs created by the requesting taker.
  ›  index_prices array of number A list of index prices for the underlying instrument(s) at the time of trade execution.
  ›  label string User defined label for the Block RFQ (maximum 64 characters)
  ›  legs array of object
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  ratio integer Ratio of amount between legs
  ›  makers array of string List of targeted Block RFQ makers
  ›  mark_price number The mark price for the instrument
  ›  min_trade_amount number Minimum amount for trading
  ›  role string Role of the user in Block RFQ
  ›  state string State of the Block RFQ
  ›  taker_rating string Rating of the taker
  ›  trade_trigger object Contains information about the trade trigger state
  ›    ›  cancel_reason string Reason for cancellation, present only when state is cancelled
  ›    ›  direction string Direction of the trade trigger
  ›    ›  price number Price of the trade trigger
  ›    ›  state string Trade trigger state: "untriggered" or "cancelled"
  ›  trades array of object
  ›    ›  amount number Trade amount. For options, linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  hedge_amount number Amount of the hedge leg. For linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›  maker string Alias of the maker (optional)
  ›    ›  price number Price in base currency

/private/edit_block_rfq_quote

curl -X GET "https://test.deribit.com/api/v2/private/edit_block_rfq_quote?amount=20000&block_rfq_id=3&direction=buy&execution_instruction=any_part_of&hedge=%7B%22amount%22%3A10%2C%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-PERPETUAL%22%2C%22price%22%3A70000%7D&label=example_quote&legs=%5B%7B%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-15NOV24%22%2C%22price%22%3A74600%2C%22ratio%22%3A%221%22%7D%5D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/edit_block_rfq_quote","params":{"amount":20000,"block_rfq_id":3,"direction":"buy","execution_instruction":"any_part_of","hedge":{"amount":10,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":70000},"label":"example_quote","legs":[{"direction":"buy","instrument_name":"BTC-15NOV24","price":74600,"ratio":"1"}]}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/edit_block_rfq_quote","params":{"amount":20000,"block_rfq_id":3,"direction":"buy","execution_instruction":"any_part_of","hedge":{"amount":10,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":70000},"label":"example_quote","legs":[{"direction":"buy","instrument_name":"BTC-15NOV24","price":74600,"ratio":"1"}]}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "label": "example_quote",
    "amount": 20000,
    "direction": "buy",
    "price": 74600,
    "legs": [
      {
        "direction": "buy",
        "price": 74600,
        "instrument_name": "BTC-15NOV24",
        "ratio": 1
      }
    ],
    "creation_timestamp": 1731076586371,
    "block_rfq_id": 3,
    "replaced": true,
    "filled_amount": 0,
    "last_update_timestamp": 1731076638591,
    "hedge": {
      "amount": 10,
      "direction": "buy",
      "price": 70000,
      "instrument_name": "BTC-PERPETUAL"
    },
    "block_rfq_quote_id": 8,
    "quote_state": "open"
  }
}

Maker method

This method edits a Block RFQ quote using the specified block_rfq_quote_id. Alternatively, user can use a combination of block_rfq_id and label to edit the quote.

Scope: block_rfq:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
legs true array of objects List of legs used for Block RFQ quote
  ›  instrument_name true string Instrument name
  ›  price true number Price for trade
  ›  ratio true integer Ratio of amount between legs
  ›  direction true string buy
sell		 Direction of selected leg. Must match the direction of the corresponding leg in the Block RFQ
amount true number This value multiplied by the ratio of a leg gives trade size on that leg.
block_rfq_quote_id false integer ID of the Block RFQ quote
label false string User defined label for the Block RFQ quote (maximum 64 characters). Used to identify quotes of a selected Block RFQ
hedge false object Hedge leg of the Block RFQ. There is only one hedge leg allowed per Block RFQ
  ›    ›  instrument_name true string Instrument name
  ›    ›  direction true string buy
sell		 Direction of selected leg. Must match the direction of the corresponding leg in the Block RFQ
  ›    ›  price true number Hedge leg price
  ›    ›  amount true number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
block_rfq_id false integer ID of the Block RFQ
price false number Aggregated price used for quoting future spreads.

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 This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  app_name string The name of the application that placed the quote on behalf of the user (optional).
  ›  block_rfq_id integer ID of the Block RFQ
  ›  block_rfq_quote_id integer ID of the Block RFQ quote
  ›  creation_timestamp integer The timestamp when quote was created (milliseconds since the Unix epoch)
  ›  direction string Direction of trade from the maker perspective
  ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›  filled_amount number Filled amount of the quote. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  hedge object
  ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a hedge leg
  ›  label string User defined label for the quote (maximum 64 characters)
  ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›  legs array of object
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a leg
  ›    ›  ratio integer Ratio of amount between legs
  ›  price number Price of a quote
  ›  quote_state string State of the quote
  ›  quote_state_reason string Reason of quote cancellation
  ›  replaced boolean true if the quote was edited, otherwise false.

/private/get_block_rfq_makers

curl -X GET "https://test.deribit.com/api/v2/private/get_block_rfq_makers?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/get_block_rfq_makers","params":{}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/get_block_rfq_makers","params":{}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
  "MAKER1",
  "MAKER2",
  "MAKER3"
  ]
 }

This method returns a list of all available Block RFQ makers.

Scope: block_rfq:read

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 A list of available makers.

/private/get_block_rfq_quotes

curl -X GET "https://test.deribit.com/api/v2/private/get_block_rfq_quotes?block_rfq_id=1" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/get_block_rfq_quotes","params":{"block_rfq_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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/get_block_rfq_quotes","params":{"block_rfq_id":1}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "label": "example_quote",
    "amount": 20000,
    "direction": "buy",
    "price": 74600,
    "legs": [
      {
        "direction": "buy",
        "price": 74600,
        "instrument_name": "BTC-15NOV24",
        "ratio": 1
      }
    ],
    "creation_timestamp": 1731076586371,
    "block_rfq_id": 1,
    "replaced": false,
    "filled_amount": 0,
    "last_update_timestamp": 1731076638591,
    "hedge": {
      "amount": 10,
      "direction": "buy",
      "price": 70000,
      "instrument_name": "BTC-PERPETUAL"
    },
    "block_rfq_quote_id": 8,
    "quote_state": "open",
    "execution_instruction": "all_or_none"
  }
 }

Maker method

This method retrieves all open quotes for Block RFQs. When a block_rfq_id is specified, only the open quotes for that particular Block RFQ will be returned. When a label is specified, all quotes with this label are returned. block_rfq_quote_id returns one specific quote.

Scope: block_rfq:read

Try in API console

Parameters

Parameter Required Type Enum Description
block_rfq_id false integer ID of the Block RFQ
label false string User defined label for the Block RFQ quote (maximum 64 characters). Used to identify quotes of a selected Block RFQ
block_rfq_quote_id false integer ID of the Block RFQ quote

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  app_name string The name of the application that placed the quote on behalf of the user (optional).
  ›  block_rfq_id integer ID of the Block RFQ
  ›  block_rfq_quote_id integer ID of the Block RFQ quote
  ›  creation_timestamp integer The timestamp when quote was created (milliseconds since the Unix epoch)
  ›  direction string Direction of trade from the maker perspective
  ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›  filled_amount number Filled amount of the quote. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  hedge object
  ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a hedge leg
  ›  label string User defined label for the quote (maximum 64 characters)
  ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›  legs array of object
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a leg
  ›    ›  ratio integer Ratio of amount between legs
  ›  price number Price of a quote
  ›  quote_state string State of the quote
  ›  quote_state_reason string Reason of quote cancellation
  ›  replaced boolean true if the quote was edited, otherwise false.

/private/get_block_rfq_user_info

curl -X GET "https://test.deribit.com/api/v2/private/get_block_rfq_user_info?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/get_block_rfq_user_info","params":{}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/get_block_rfq_user_info","params":{}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "parent": {
      "identity": "MAKER1",
      "is_maker": true
    },
    "users": [
      {
        "user_id": 1,
        "taker_rating": 98.5,
        "identity": "TAKER1",
        "is_maker": false
      },
      {
        "user_id": 2,
        "taker_rating": 97.0
      }
    ]
  }
}

Returns identity and rating information for the requesting account and its subaccounts. Includes both group-level and individual user-level alias data, if available.

Scope: block_rfq:read

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
  ›  parent object Parent Identity (group alias), representing the overall account group (main + subaccounts).
  ›    ›  identity string Group-level alias identifying the account group as a whole.
  ›    ›  is_maker boolean Indicates whether the Parent Identity has maker scope.
  ›  users array of object
  ›    ›  identity string Specific alias identifying this account individually.
  ›    ›  is_maker boolean Indicates whether this account has maker scope.
  ›    ›  taker_rating number Taker rating associated with this account, if available.
  ›    ›  user_id integer Unique user identifier

/private/get_block_rfqs

curl -X GET "https://test.deribit.com/api/v2/private/get_block_rfqs?count=20&role=maker&state=open" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/get_block_rfqs","params":{"count":20,"role":"maker","state":"open"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/get_block_rfqs","params":{"count":20,"role":"maker","state":"open"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "continuation": null,
    "block_rfqs": [
      {
        "state": "open",
        "amount": 40000,
        "role": "maker",
        "combo_id": "BTC-15NOV24",
        "legs": [
          {
            "direction": "sell",
            "instrument_name": "BTC-15NOV24",
            "ratio": 1
          }
        ],
        "creation_timestamp": 1731062457741,
        "block_rfq_id": 508,
        "expiration_timestamp": 1731062757741,
        "hedge": {
          "amount": 10,
          "direction": "buy",
          "price": 70000,
          "instrument_name": "BTC-PERPETUAL"
        },
        "taker_rating": "1-2"
      }
    ]
  }
}

This method returns a list of Block RFQs that were either created by the user or assigned to them as a maker, sorted in descending order. trades and mark_price are only visible for the filled Block RFQ. When a block_rfq_id is specified, only that particular Block RFQ will be returned. If called by a taker, response will additionally include makers list and label if previously provided. If called by the maker, the trades will include the maker's alias, but only for trades in which this maker participated. Can be optionally filtered by currency.

Scope: block_rfq:read

Try in API console

Parameters

Parameter Required Type Enum Description
count false integer Count of Block RFQs returned
state false string open
filled
traded
cancelled
expired
closed		 State of Block RFQ
role false string any
taker
maker		 Role of the user in Block RFQ. When the any role is selected, the method returns all Block RFQs in which the user has participated, either as the taker or as a maker
continuation false integer The continuation parameter specifies the starting point for fetching historical Block RFQs. When provided, the endpoint returns Block RFQs, starting from the specified ID and continuing backward (e.g., if continuation is 50, results will include Block RFQs of ID 49, 48, etc.)
block_rfq_id false integer ID of the Block RFQ
currency false string BTC
ETH
USDC
USDT
any		 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
  ›  block_rfqs array of object
  ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›  app_name string The name of the application that created the Block RFQ on behalf of the user (optional, visible only to taker).
  ›    ›  asks array of object
  ›    ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›    ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›    ›    ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›    ›    ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›    ›    ›  makers array of string Maker of the quote
  ›    ›    ›  price number Price of a quote
  ›    ›  bids array of object
  ›    ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›    ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›    ›    ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›    ›    ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›    ›    ›  makers array of string Maker of the quote
  ›    ›    ›  price number Price of a quote
  ›    ›  block_rfq_id integer ID of the Block RFQ
  ›    ›  combo_id string Unique combo identifier
  ›    ›  creation_timestamp integer The timestamp when Block RFQ was created (milliseconds since the Unix epoch)
  ›    ›  disclosed boolean Indicates whether the RFQ was created as non-anonymous, meaning taker and maker aliases are visible to counterparties.
  ›    ›  expiration_timestamp integer The timestamp when the Block RFQ will expire (milliseconds since the UNIX epoch)
  ›    ›  hedge object
  ›    ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›    ›  direction string Direction: buy, or sell
  ›    ›    ›  instrument_name string Unique instrument identifier
  ›    ›    ›  price number Price for a hedge leg
  ›    ›  included_in_taker_rating boolean Indicates whether the RFQ is included in the taker's rating calculation. Present only for closed RFQs created by the requesting taker.
  ›    ›  index_prices array of number A list of index prices for the underlying instrument(s) at the time of trade execution.
  ›    ›  label string User defined label for the Block RFQ (maximum 64 characters)
  ›    ›  legs array of object
  ›    ›    ›  direction string Direction: buy, or sell
  ›    ›    ›  instrument_name string Unique instrument identifier
  ›    ›    ›  ratio integer Ratio of amount between legs
  ›    ›  makers array of string List of targeted Block RFQ makers
  ›    ›  mark_price number The mark price for the instrument
  ›    ›  min_trade_amount number Minimum amount for trading
  ›    ›  role string Role of the user in Block RFQ
  ›    ›  state string State of the Block RFQ
  ›    ›  taker_rating string Rating of the taker
  ›    ›  trade_trigger object Contains information about the trade trigger state
  ›    ›    ›  cancel_reason string Reason for cancellation, present only when state is cancelled
  ›    ›    ›  direction string Direction of the trade trigger
  ›    ›    ›  price number Price of the trade trigger
  ›    ›    ›  state string Trade trigger state: "untriggered" or "cancelled"
  ›    ›  trades array of object
  ›    ›    ›  amount number Trade amount. For options, linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›    ›  direction string Direction: buy, or sell
  ›    ›    ›  hedge_amount number Amount of the hedge leg. For linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›    ›  maker string Alias of the maker (optional)
  ›    ›    ›  price number Price in base currency
  ›  continuation string Continuation token for pagination.

/private/trade_block_rfq

curl -X GET "https://test.deribit.com/api/v2/private/trade_block_rfq?amount=100&block_rfq_id=1&direction=buy&legs=%5B%7B%22direction%22%3A%22buy%22%2C%22instrument_name%22%3A%22BTC-8NOV24-70000-C%22%2C%22ratio%22%3A1%7D%2C%7B%22direction%22%3A%22sell%22%2C%22instrument_name%22%3A%22BTC-8NOV24-72000-C%22%2C%22ratio%22%3A1%7D%5D&price=1.00000000000000002082e-02" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/trade_block_rfq","params":{"amount":100,"block_rfq_id":1,"direction":"buy","legs":[{"direction":"buy","instrument_name":"BTC-8NOV24-70000-C","ratio":1},{"direction":"sell","instrument_name":"BTC-8NOV24-72000-C","ratio":1}],"price":0.01}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/trade_block_rfq","params":{"amount":100,"block_rfq_id":1,"direction":"buy","legs":[{"direction":"buy","instrument_name":"BTC-8NOV24-70000-C","ratio":1},{"direction":"sell","instrument_name":"BTC-8NOV24-72000-C","ratio":1}],"price":0.01}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "id": "BLOCK-423",
      "timestamp": 1730798381504,
      "trades": [
        {
          "timestamp": 1730798381502,
          "state": "filled",
          "fee": 1.5e-7,
          "amount": 100,
          "direction": "buy",
          "price": 69696.8,
          "index_price": 70000,
          "profit_loss": 0,
          "instrument_name": "BTC-8NOV24-70000-C",
          "trade_seq": 113,
          "mark_price": 0.03,
          "order_id": "2899",
          "matching_id": null,
          "tick_direction": 2,
          "combo_id": "BTC-CS-8NOV24-70000_72000",
          "block_rfq_id": 1,
          "api": true,
          "contracts": 100,
          "post_only": false,
          "block_trade_id": "BLOCK-423",
          "trade_id": "771",
          "order_type": "limit",
          "mmp": false,
          "risk_reducing": false,
          "reduce_only": false,
          "block_trade_leg_count": 2,
          "self_trade": false,
          "fee_currency": "BTC",
          "liquidity": "T"
        },
       {
          "timestamp": 1730798381502,
          "state": "filled",
          "fee": 1.5e-7,
          "amount": 100,
          "direction": "sell",
          "price": 69677.4,
          "index_price": 70000,
          "profit_loss": 0,
          "instrument_name": "BTC-8NOV24-72000-C",
          "trade_seq": 113,
          "mark_price": 0.02,
          "order_id": "2900",
          "matching_id": null,
          "tick_direction": 2,
          "combo_id": "BTC-CS-8NOV24-70000_72000",
          "block_rfq_id": 548,
          "api": true,
          "contracts": 100,
          "post_only": false,
          "block_trade_id": "BLOCK-423",
          "trade_id": "772",
          "order_type": "limit",
          "mmp": false,
          "risk_reducing": false,
          "reduce_only": false,
          "block_trade_leg_count": 2,
          "self_trade": false,
          "fee_currency": "BTC",
          "liquidity": "T"
        }
      ]
    }
  ]
}

Taker method (Deprecated)

This method is deprecated and will be removed in the future. Please use private/accept_block_rfq instead.

This method allows Block RFQ taker to trade with the response by sending a single crossing price. Please note that after Block RFQ creation, a grace period of 5 seconds begins, during which the taker cannot see quotes or trade the Block RFQ.

Scope: block_rfq:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
block_rfq_id true integer ID of the Block RFQ
price true number Maximum acceptable price for execution
amount true number This value multiplied by the ratio of a leg gives trade size on that leg.
direction true string buy
sell		 Direction of the trade from the taker perspective
hedge false object Hedge leg of the Block RFQ. There is only one hedge leg allowed per Block RFQ
  ›    ›  instrument_name true string Instrument name
  ›    ›  direction true string buy
sell		 Direction of selected leg. Must match the direction of the corresponding leg in the Block RFQ
  ›    ›  price true number Hedge leg price
  ›    ›  amount true number It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
legs true array of objects List of legs used to trade Block RFQ
  ›  instrument_name true string Instrument name
  ›  direction true string buy
sell		 Direction of selected leg. Must match the direction of the corresponding leg in the Block RFQ
  ›  ratio true integer Ratio of amount between legs

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
  ›  app_name string The name of the application that executed the block trade on behalf of the user (optional).
  ›  broker_code string Broker code associated with the broker block trade.
  ›  broker_name string Name of the broker associated with the block trade.
  ›  id string Block trade id
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

Wallet

/private/add_to_address_book

curl -X GET "https://test.deribit.com/api/v2/private/add_to_address_book?address=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj&agreed=true&beneficiary_address=NL%2C+Amsterdam%2C+Street%2C+1&beneficiary_first_name=John&beneficiary_last_name=Doe&beneficiary_vasp_did=did%3Aexample%3A123456789abcdefghi&beneficiary_vasp_name=Money%60s+Gone&currency=BTC&label=Main+address&personal=false&type=withdrawal" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":42,"jsonrpc":"2.0","method":"private/add_to_address_book","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","agreed":true,"beneficiary_address":"NL, Amsterdam, Street, 1","beneficiary_first_name":"John","beneficiary_last_name":"Doe","beneficiary_vasp_did":"did:example:123456789abcdefghi","beneficiary_vasp_name":"Money`s Gone","currency":"BTC","label":"Main address","personal":false,"type":"withdrawal"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":42,"jsonrpc":"2.0","method":"private/add_to_address_book","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","agreed":True,"beneficiary_address":"NL, Amsterdam, Street, 1","beneficiary_first_name":"John","beneficiary_last_name":"Doe","beneficiary_vasp_did":"did:example:123456789abcdefghi","beneficiary_vasp_name":"Money`s Gone","currency":"BTC","label":"Main address","personal":False,"type":"withdrawal"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj",
    "creation_timestamp": 1536569522277,
    "currency": "BTC",
    "type": "withdrawal",
    "label": "Main address",
    "beneficiary_vasp_name": "Money`s Gone",
    "beneficiary_vasp_did": "did:example:123456789abcdefghi",
    "beneficiary_first_name": "John",
    "beneficiary_last_name": "Doe",
    "beneficiary_address": "NL, Amsterdam, Street, 1",
    "agreed": true,
    "personal": false,
    "info_required": false
  }
}

Adds new entry to address book of given type

Scope: wallet:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
STETH
ETHW
USDC
USDT
EURR
MATIC
SOL
XRP
USYC
PAXG
BNB
USDE		 The currency symbol
type true string transfer
withdrawal
deposit_source		 Address book type
address true string Address in currency format
label true string Label of the address book entry
beneficiary_vasp_name true string Name of beneficiary VASP
beneficiary_vasp_did true string DID of beneficiary VASP
beneficiary_vasp_website false string Website of the beneficiary VASP. Required if the address book entry is associated with a VASP that is not included in the list of known VASPs
beneficiary_first_name false string First name of beneficiary (if beneficiary is a person)
beneficiary_last_name false string First name of beneficiary (if beneficiary is a person)
beneficiary_company_name false string Beneficiary company name (if beneficiary is a company)
beneficiary_address true string Geographical address of the beneficiary
agreed true boolean Indicates that the user agreed to shared provided information with 3rd parties
personal true boolean The user confirms that he provided address belongs to him and he has access to it via an un-hosted wallet software
extra_currencies false array The user can pass a list of currencies to add the address for. It is currently available ONLY for ERC20 currencies. Without passing this paramater for an ERC20 currency, the address will be added to ALL of the ERC20 currencies.

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
  ›  agreed boolean Indicates that the user agreed to shared provided information with 3rd parties
  ›  beneficiary_address string Geographical address of the beneficiary
  ›  beneficiary_company_name string Company name of the beneficiary (if beneficiary is a company)
  ›  beneficiary_first_name string First name of the beneficiary (if beneficiary is a person)
  ›  beneficiary_last_name string Last name of the beneficiary (if beneficiary is a person)
  ›  beneficiary_vasp_did string DID of beneficiary VASP
  ›  beneficiary_vasp_name string Name of beneficiary VASP
  ›  beneficiary_vasp_website string Website of the beneficiary VASP
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  info_required boolean Signalises that addition information regarding the beneficiary of the address is required
  ›  label string Label of the address book entry
  ›  personal boolean The user confirms that he provided address belongs to him and he has access to it via an un-hosted wallet software
  ›  requires_confirmation boolean If address requires email confirmation for withdrawals
  ›  requires_confirmation_change boolean If email confirmation change is in progress
  ›  status string Wallet address status, values: [admin_locked, waiting, confirmed, ready]
  ›  type string Address book type
  ›  waiting_timestamp boolean Timestamp when the address will be ready

/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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":9187,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":9187,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

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

Scope: wallet:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
id true integer Id of transfer

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 (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  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, insufficient_funds, withdrawal_limit otherwise rejection reason
  ›  type string Type of transfer: user - sent to user, subaccount - sent to subaccount
  ›  updated_timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/cancel_withdrawal

curl -X GET "https://test.deribit.com/api/v2/private/cancel_withdrawal?currency=BTC&id=1" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":7420,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":7420,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

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

Scope: wallet:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 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 (milliseconds since the Unix epoch) of withdrawal confirmation, null when not confirmed
  ›  created_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  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 (milliseconds since the Unix epoch)

/private/create_deposit_address

curl -X GET "https://test.deribit.com/api/v2/private/create_deposit_address?currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":7538,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":7538,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

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

Creates deposit address in currency

Scope: wallet:read_write

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object Object if address is created, null otherwise
  ›  address string Address in proper format for currency
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  type string Address type/purpose, allowed values : deposit, withdrawal, transfer

/private/delete_address_beneficiary

curl -X GET "https://test.deribit.com/api/v2/private/delete_address_beneficiary?address=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj&currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":42,"jsonrpc":"2.0","method":"private/delete_address_beneficiary","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","currency":"BTC"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":42,"jsonrpc":"2.0","method":"private/delete_address_beneficiary","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","currency":"BTC"}}

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

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

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

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

Deletes address beneficiary information

Scope: wallet:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
STETH
ETHW
USDC
USDT
EURR
MATIC
SOL
XRP
USYC
PAXG
BNB
USDE		 The currency symbol
address true string Address in currency format
tag false string Tag for XRP addresses

Response

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

/private/get_address_beneficiary

curl -X GET "https://test.deribit.com/api/v2/private/get_address_beneficiary?address=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj&currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":42,"jsonrpc":"2.0","method":"private/get_address_beneficiary","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","currency":"BTC"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":42,"jsonrpc":"2.0","method":"private/get_address_beneficiary","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","currency":"BTC"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "currency": "BTC",
    "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj",
    "user_id": 1016,
    "agreed": true,
    "personal": false,
    "unhosted": false,
    "beneficiary_vasp_name": "Money's Gone",
    "beneficiary_vasp_did": "did:example:123456789abcdefghi",
    "beneficiary_vasp_website": "https://example.com",
    "beneficiary_first_name": "John",
    "beneficiary_last_name": "Doe",
    "beneficiary_company_name": "Example Corp",
    "beneficiary_address": "NL, Amsterdam, Street, 1",
    "created": 1536569522277,
    "updated": 1536569522277
  }
}

Retrieves address beneficiary information

Scope: wallet:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
STETH
ETHW
USDC
USDT
EURR
MATIC
SOL
XRP
USYC
PAXG
BNB
USDE		 The currency symbol
address true string Address in currency format
tag false string Tag for XRP addresses

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
  ›  agreed boolean Indicates that the user agreed to shared provided information with 3rd parties
  ›  beneficiary_address string Geographical address of the beneficiary
  ›  beneficiary_company_name string Company name of the beneficiary (if beneficiary is a company)
  ›  beneficiary_first_name string First name of the beneficiary (if beneficiary is a person)
  ›  beneficiary_last_name string Last name of the beneficiary (if beneficiary is a person)
  ›  beneficiary_vasp_did string DID of beneficiary VASP
  ›  beneficiary_vasp_name string Name of beneficiary VASP
  ›  beneficiary_vasp_website string Website of the beneficiary VASP
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  personal boolean The user confirms that he provided address belongs to him and he has access to it via an un-hosted wallet software
  ›  tag string Tag for XRP addresses (optional)
  ›  unhosted boolean Indicates if the address belongs to an unhosted wallet
  ›  update_timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/get_address_book

curl -X GET "https://test.deribit.com/api/v2/private/get_address_book?currency=BTC&type=withdrawal" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":31,"jsonrpc":"2.0","method":"private/get_address_book","params":{"currency":"BTC","type":"withdrawal"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":31,"jsonrpc":"2.0","method":"private/get_address_book","params":{"currency":"BTC","type":"withdrawal"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 31,
  "result": [
    {
      "waiting_timestamp": 1720252232860,
      "creation_timestamp": 1719993033041,
      "requires_confirmation_change": false,
      "personal": true,
      "info_required": false,
      "beneficiary_first_name": "John",
      "beneficiary_last_name": "Doe",
      "beneficiary_address": "NL, Amsterdam, Street, 1",
      "requires_confirmation": true,
      "currency": "BTC",
      "agreed": true,
      "address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz",
      "type": "withdrawal",
      "status": "waiting",
      "label": "Main Address"
    },
    {
      "waiting_timestamp": 1720252232760,
      "creation_timestamp": 1719993032041,
      "requires_confirmation_change": false,
      "personal": true,
      "info_required": false,
      "beneficiary_company_name": "MyCompany",
      "beneficiary_address": "NL, Haarlem, Street, 5",
      "requires_confirmation": false,
      "currency": "BTC",
      "agreed": true,
      "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj",
      "type": "withdrawal",
      "status": "waiting",
      "label": "One More Address"
    }
  ]
}

Retrieves address book of given type

Scope: wallet:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
STETH
ETHW
USDC
USDT
EURR
MATIC
SOL
XRP
USYC
PAXG
BNB
USDE		 The currency symbol
type true string transfer
withdrawal
deposit_source		 Address book type

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
  ›  address string Address in proper format for currency
  ›  agreed boolean Indicates that the user agreed to shared provided information with 3rd parties
  ›  beneficiary_address string Geographical address of the beneficiary
  ›  beneficiary_company_name string Company name of the beneficiary (if beneficiary is a company)
  ›  beneficiary_first_name string First name of the beneficiary (if beneficiary is a person)
  ›  beneficiary_last_name string Last name of the beneficiary (if beneficiary is a person)
  ›  beneficiary_vasp_did string DID of beneficiary VASP
  ›  beneficiary_vasp_name string Name of beneficiary VASP
  ›  beneficiary_vasp_website string Website of the beneficiary VASP
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  info_required boolean Signalises that addition information regarding the beneficiary of the address is required
  ›  label string Label of the address book entry
  ›  personal boolean The user confirms that he provided address belongs to him and he has access to it via an un-hosted wallet software
  ›  requires_confirmation boolean If address requires email confirmation for withdrawals
  ›  requires_confirmation_change boolean If email confirmation change is in progress
  ›  status string Wallet address status, values: [admin_locked, waiting, confirmed, ready]
  ›  type string Address book type
  ›  waiting_timestamp boolean Timestamp when the address will be ready

/private/get_current_deposit_address

curl -X GET "https://test.deribit.com/api/v2/private/get_current_deposit_address?currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":3461,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":3461,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

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

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

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

Retrieve deposit address for currency

Scope: wallet:read

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object Object if address is created, null otherwise
  ›  address string Address in proper format for currency
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":5611,"jsonrpc":"2.0","method":"private/get_deposits","params":{"count":10,"currency":"BTC","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Scope: wallet:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 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
  ›    ›  clearance_state string Clearance state, allowed values : in_progress, pending_admin_decision, pending_user_input, success, failed, cancelled, refund_initiated, refunded
  ›    ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  note string
  ›    ›  received_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  refund_transaction_id string Transaction id in proper format for currency, null if id is not available
  ›    ›  source_address string Address in proper format for currency
  ›    ›  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 (milliseconds since the Unix epoch)

/private/get_transfers

curl -X GET "https://test.deribit.com/api/v2/private/get_transfers?count=10&currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":7606,"jsonrpc":"2.0","method":"private/get_transfers","params":{"count":10,"currency":"BTC"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Retrieve the user's transfers list

Scope: wallet:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 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 (milliseconds since the Unix epoch)
  ›    ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  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, insufficient_funds, withdrawal_limit otherwise rejection reason
  ›    ›  type string Type of transfer: user - sent to user, subaccount - sent to subaccount
  ›    ›  updated_timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/get_withdrawals

curl -X GET "https://test.deribit.com/api/v2/private/get_withdrawals?count=10&currency=BTC&offset=0" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2745,"jsonrpc":"2.0","method":"private/get_withdrawals","params":{"count":10,"currency":"BTC","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Scope: wallet:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 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 (milliseconds since the Unix epoch) of withdrawal confirmation, null when not confirmed
  ›    ›  created_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  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 (milliseconds since the Unix epoch)

/private/list_address_beneficiaries

curl -X GET "https://test.deribit.com/api/v2/private/list_address_beneficiaries?currency=BTC&limit=10" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":42,"jsonrpc":"2.0","method":"private/list_address_beneficiaries","params":{"currency":"BTC","limit":10}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":42,"jsonrpc":"2.0","method":"private/list_address_beneficiaries","params":{"currency":"BTC","limit":10}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "data": [
      {
        "currency": "BTC",
        "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj",
        "user_id": 1026,
        "agreed": true,
        "personal": false,
        "unhosted": false,
        "beneficiary_vasp_name": "Money's Gone",
        "beneficiary_vasp_did": "did:example:123456789abcdefghi",
        "beneficiary_vasp_website": "https://example.com",
        "beneficiary_first_name": "John",
        "beneficiary_last_name": "Doe",
        "beneficiary_company_name": "Example Corp",
        "beneficiary_address": "NL, Amsterdam, Street, 1",
        "created": 1536569522277,
        "updated": 1536569522277
      }
    ],
    "continuation": "xY7T6cutS3t2B9YtaDkE6TS379oKnkzTvmEDUnEUP2Msa9xKWNNaT",
    "count": 1
  }
}

Lists address beneficiaries with optional filtering and pagination

Scope: wallet:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency false string BTC
ETH
STETH
ETHW
USDC
USDT
EURR
MATIC
SOL
XRP
USYC
PAXG
BNB
USDE		 The currency symbol
address false string Address in currency format
tag false string Tag for XRP addresses
created_before false integer Filter by creation timestamp (before)
created_after false integer Filter by creation timestamp (after)
updated_before false integer Filter by update timestamp (before)
updated_after false integer Filter by update timestamp (after)
personal false boolean Filter by personal wallet flag
unhosted false boolean Filter by unhosted wallet flag
beneficiary_vasp_name false string Filter by beneficiary VASP name
beneficiary_vasp_did false string Filter by beneficiary VASP DID
beneficiary_vasp_website false string Website of the beneficiary VASP. Required if the address book entry is associated with a VASP that is not included in the list of known VASPs
limit false integer Maximum number of results to return
continuation false string Continuation token for pagination

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  continuation string Continuation token for pagination.
  ›  count integer Total number of results available
  ›  data array of object
  ›    ›  address string Address in proper format for currency
  ›    ›  agreed boolean Indicates that the user agreed to shared provided information with 3rd parties
  ›    ›  beneficiary_address string Geographical address of the beneficiary
  ›    ›  beneficiary_company_name string Company name of the beneficiary (if beneficiary is a company)
  ›    ›  beneficiary_first_name string First name of the beneficiary (if beneficiary is a person)
  ›    ›  beneficiary_last_name string Last name of the beneficiary (if beneficiary is a person)
  ›    ›  beneficiary_vasp_did string DID of beneficiary VASP
  ›    ›  beneficiary_vasp_name string Name of beneficiary VASP
  ›    ›  beneficiary_vasp_website string Website of the beneficiary VASP
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  personal boolean The user confirms that he provided address belongs to him and he has access to it via an un-hosted wallet software
  ›    ›  tag string Tag for XRP addresses (optional)
  ›    ›  unhosted boolean Indicates if the address belongs to an unhosted wallet
  ›    ›  update_timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/remove_from_address_book

curl -X GET "https://test.deribit.com/api/v2/private/remove_from_address_book?address=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj&currency=BTC&type=transfer" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":42,"jsonrpc":"2.0","method":"private/remove_from_address_book","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","currency":"BTC","type":"transfer"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":42,"jsonrpc":"2.0","method":"private/remove_from_address_book","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","currency":"BTC","type":"transfer"}}

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

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

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

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

Removes address book entry

Scope: wallet:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
STETH
ETHW
USDC
USDT
EURR
MATIC
SOL
XRP
USYC
PAXG
BNB
USDE		 The currency symbol
type true string transfer
withdrawal
deposit_source		 Address book type
address true string Address in currency format, it must be in address book

Response

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

/private/save_address_beneficiary

curl -X GET "https://test.deribit.com/api/v2/private/save_address_beneficiary?address=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj&agreed=true&beneficiary_address=NL%2C+Amsterdam%2C+Street%2C+1&beneficiary_company_name=Example+Corp&beneficiary_first_name=John&beneficiary_last_name=Doe&beneficiary_vasp_did=did%3Aexample%3A123456789abcdefghi&beneficiary_vasp_name=Money%27s+Gone&beneficiary_vasp_website=https%3A%2F%2Fexample.com&currency=BTC&personal=false&unhosted=false" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":42,"jsonrpc":"2.0","method":"private/save_address_beneficiary","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","agreed":true,"beneficiary_address":"NL, Amsterdam, Street, 1","beneficiary_company_name":"Example Corp","beneficiary_first_name":"John","beneficiary_last_name":"Doe","beneficiary_vasp_did":"did:example:123456789abcdefghi","beneficiary_vasp_name":"Money's Gone","beneficiary_vasp_website":"https://example.com","currency":"BTC","personal":false,"unhosted":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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":42,"jsonrpc":"2.0","method":"private/save_address_beneficiary","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","agreed":True,"beneficiary_address":"NL, Amsterdam, Street, 1","beneficiary_company_name":"Example Corp","beneficiary_first_name":"John","beneficiary_last_name":"Doe","beneficiary_vasp_did":"did:example:123456789abcdefghi","beneficiary_vasp_name":"Money's Gone","beneficiary_vasp_website":"https://example.com","currency":"BTC","personal":False,"unhosted":false}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "currency": "BTC",
    "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj",
    "user_id": 1016,
    "agreed": true,
    "personal": false,
    "unhosted": false,
    "beneficiary_vasp_name": "Money's Gone",
    "beneficiary_vasp_did": "did:example:123456789abcdefghi",
    "beneficiary_vasp_website": "https://example.com",
    "beneficiary_first_name": "John",
    "beneficiary_last_name": "Doe",
    "beneficiary_company_name": "Example Corp",
    "beneficiary_address": "NL, Amsterdam, Street, 1",
    "created": 1536569522277,
    "updated": 1536569522277
  }
}

Saves address beneficiary information

Scope: wallet:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
STETH
ETHW
USDC
USDT
EURR
MATIC
SOL
XRP
USYC
PAXG
BNB
USDE		 The currency symbol
address true string Address in currency format
tag false string Tag for XRP addresses
agreed true boolean Indicates that the user agreed to shared provided information with 3rd parties
personal true boolean The user confirms that he provided address belongs to him and he has access to it via an un-hosted wallet software
unhosted true boolean Indicates if the address belongs to an unhosted wallet
beneficiary_vasp_name true string Name of beneficiary VASP
beneficiary_vasp_did true string DID of beneficiary VASP
beneficiary_vasp_website false string Website of the beneficiary VASP. Required if the address book entry is associated with a VASP that is not included in the list of known VASPs
beneficiary_first_name false string First name of beneficiary (if beneficiary is a person)
beneficiary_last_name false string First name of beneficiary (if beneficiary is a person)
beneficiary_company_name false string Beneficiary company name (if beneficiary is a company)
beneficiary_address true string Geographical address of the beneficiary

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
  ›  agreed boolean Indicates that the user agreed to shared provided information with 3rd parties
  ›  beneficiary_address string Geographical address of the beneficiary
  ›  beneficiary_company_name string Company name of the beneficiary (if beneficiary is a company)
  ›  beneficiary_first_name string First name of the beneficiary (if beneficiary is a person)
  ›  beneficiary_last_name string Last name of the beneficiary (if beneficiary is a person)
  ›  beneficiary_vasp_did string DID of beneficiary VASP
  ›  beneficiary_vasp_name string Name of beneficiary VASP
  ›  beneficiary_vasp_website string Website of the beneficiary VASP
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  personal boolean The user confirms that he provided address belongs to him and he has access to it via an un-hosted wallet software
  ›  tag string Tag for XRP addresses (optional)
  ›  unhosted boolean Indicates if the address belongs to an unhosted wallet
  ›  update_timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/set_clearance_originator

curl -X GET "https://test.deribit.com/api/v2/private/set_clearance_originator?deposit_id=%7B%22address%22%3A%222NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz%22%2C%22currency%22%3A%22BTC%22%2C%22tx_hash%22%3A%22230669110fdaf0a0dbcdc079b6b8b43d5af29cc73683835b9bc6b3406c065fda%22%2C%22user_id%22%3A123%7D&originator=%7B%22address%22%3A%22NL%2C+Amsterdam%2C+Street%2C+1%22%2C%22company_name%22%3A%22Company+Name%22%2C%22first_name%22%3A%22First%22%2C%22is_personal%22%3Afalse%2C%22last_name%22%3A%22Last%22%7D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/set_clearance_originator","params":{"deposit_id":{"address":"2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz","currency":"BTC","tx_hash":"230669110fdaf0a0dbcdc079b6b8b43d5af29cc73683835b9bc6b3406c065fda","user_id":123},"originator":{"address":"NL, Amsterdam, Street, 1","company_name":"Company Name","first_name":"First","is_personal":false,"last_name":"Last"}}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/set_clearance_originator","params":{"deposit_id":{"address":"2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz","currency":"BTC","tx_hash":"230669110fdaf0a0dbcdc079b6b8b43d5af29cc73683835b9bc6b3406c065fda","user_id":123},"originator":{"address":"NL, Amsterdam, Street, 1","company_name":"Company Name","first_name":"First","is_personal":False,"last_name":"Last"}}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "currency": "BTC",
    "user_id": 123,
    "address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz",
    "amount": 0.4,
    "state": "completed",
    "transaction_id": "230669110fdaf0a0dbcdc079b6b8b43d5af29cc73683835b9bc6b3406c065fda",
    "source_address": "A3BqqD5GRJ8wHy1PYyCXTe9ke5226Fha123",
    "received_timestamp": 1550574558607,
    "updated_timestamp": 1550574558807,
    "note": "Note",
    "clearance_state": "in_progress"
  }
}

Sets originator of the deposit

Scope: wallet:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
deposit_id true object Id of the deposit
  ›    ›  currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
  ›    ›  user_id true integer Id of a (sub)account
  ›    ›  address true string Address in currency format
  ›    ›  tx_hash true string Transaction id in a proper format for the currency
originator true object Information about the originator of the deposit
  ›    ›  is_personal true boolean If the user is the originator of the deposit
  ›    ›  company_name true string Company name of the originator if the originator is a legal entity
  ›    ›  first_name true string If the user is the originator of the deposit
  ›    ›  last_name true string Last name of the originator if the originator is a person
  ›    ›  address true string Geographical address of the originator

Response

Name Type Description
address string Address in proper format for currency
amount number Amount of funds in given currency
clearance_state string Clearance state, allowed values : in_progress, pending_admin_decision, pending_user_input, success, failed, cancelled, refund_initiated, refunded
currency string Currency, i.e "BTC", "ETH", "USDC"
note string
received_timestamp integer The timestamp (milliseconds since the Unix epoch)
refund_transaction_id string Transaction id in proper format for currency, null if id is not available
source_address string Address in proper format for currency
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 (milliseconds since the Unix epoch)

/private/submit_transfer_between_subaccounts

curl -X GET "https://test.deribit.com/api/v2/private/submit_transfer_between_subaccounts?amount=1.21234000000000001762e%2B01&currency=ETH&destination=20&source=10" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":210,"jsonrpc":"2.0","method":"private/submit_transfer_between_subaccounts","params":{"amount":12.1234,"currency":"ETH","destination":20,"source":10}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":210,"jsonrpc":"2.0","method":"private/submit_transfer_between_subaccounts","params":{"amount":12.1234,"currency":"ETH","destination":20,"source":10}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 210,
  "result": {
    "updated_timestamp": 1550226218504,
    "type": "subaccount",
    "state": "confirmed",
    "other_side": "MySubAccount",
    "id": 1,
    "direction": "payment",
    "currency": "ETH",
    "created_timestamp": 1550226218504,
    "amount": 12.1234
  }
}

Transfer funds between two (sub)accounts.

Scope: wallets:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
amount true number Amount of funds to be transferred
destination true integer Id of destination subaccount. Can be found in My Account >> Subaccounts tab
source false integer Id of the source (sub)account. Can be found in My Account >> Subaccounts tab. By default, it is the Id of the account which made the request. However, if a different "source" is specified, the user must possess the mainaccount scope, and only other subaccounts can be designated as the source.

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 (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  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, insufficient_funds, withdrawal_limit otherwise rejection reason
  ›  type string Type of transfer: user - sent to user, subaccount - sent to subaccount
  ›  updated_timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/submit_transfer_to_subaccount

curl -X GET "https://test.deribit.com/api/v2/private/submit_transfer_to_subaccount?amount=1.21234000000000001762e%2B01&currency=ETH&destination=20" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":210,"jsonrpc":"2.0","method":"private/submit_transfer_to_subaccount","params":{"amount":12.1234,"currency":"ETH","destination":20}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":210,"jsonrpc":"2.0","method":"private/submit_transfer_to_subaccount","params":{"amount":12.1234,"currency":"ETH","destination":20}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 210,
  "result": {
    "updated_timestamp": 1550226218504,
    "type": "subaccount",
    "state": "confirmed",
    "other_side": "MySubAccount",
    "id": 1,
    "direction": "payment",
    "currency": "ETH",
    "created_timestamp": 1550226218504,
    "amount": 12.1234
  }
}

Transfer funds to subaccount.

Scope: wallets:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
amount true number Amount of funds to be transferred
destination true integer Id of destination subaccount. Can be found in My Account >> Subaccounts tab

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 (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  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, insufficient_funds, withdrawal_limit otherwise rejection reason
  ›  type string Type of transfer: user - sent to user, subaccount - sent to subaccount
  ›  updated_timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/submit_transfer_to_user

curl -X GET "https://test.deribit.com/api/v2/private/submit_transfer_to_user?amount=1.34559999999999995168e%2B01&currency=ETH&destination=0x4aa0753d798d668056920094d65321a8e8913e26" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":9421,"jsonrpc":"2.0","method":"private/submit_transfer_to_user","params":{"amount":13.456,"currency":"ETH","destination":"0x4aa0753d798d668056920094d65321a8e8913e26"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":9421,"jsonrpc":"2.0","method":"private/submit_transfer_to_user","params":{"amount":13.456,"currency":"ETH","destination":"0x4aa0753d798d668056920094d65321a8e8913e26"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 9421,
  "result": {
    "updated_timestamp": 1550232862350,
    "type": "user",
    "state": "prepared",
    "other_side": "0x4aa0753d798d668056920094d65321a8e8913e26",
    "id": 3,
    "direction": "payment",
    "currency": "ETH",
    "created_timestamp": 1550232862350,
    "amount": 13.456
  }
}

Transfer funds to another user.

Scope: wallet:read_write and mainaccount

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
amount true number Amount of funds to be transferred
destination true string Destination wallet's address taken from address book

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 (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  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, insufficient_funds, withdrawal_limit otherwise rejection reason
  ›  type string Type of transfer: user - sent to user, subaccount - sent to subaccount
  ›  updated_timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/update_in_address_book

curl -X GET "https://test.deribit.com/api/v2/private/update_in_address_book?address=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj&agreed=true&beneficiary_address=NL%2C+Amsterdam%2C+Street%2C+1&beneficiary_first_name=John&beneficiary_last_name=Doe&beneficiary_vasp_did=did%3Aexample%3A123456789abcdefghi&beneficiary_vasp_name=Money%60s+Gone&currency=BTC&label=Main+address&personal=false&type=withdrawal" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":42,"jsonrpc":"2.0","method":"private/update_in_address_book","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","agreed":true,"beneficiary_address":"NL, Amsterdam, Street, 1","beneficiary_first_name":"John","beneficiary_last_name":"Doe","beneficiary_vasp_did":"did:example:123456789abcdefghi","beneficiary_vasp_name":"Money`s Gone","currency":"BTC","label":"Main address","personal":false,"type":"withdrawal"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":42,"jsonrpc":"2.0","method":"private/update_in_address_book","params":{"address":"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf0uyj","agreed":True,"beneficiary_address":"NL, Amsterdam, Street, 1","beneficiary_first_name":"John","beneficiary_last_name":"Doe","beneficiary_vasp_did":"did:example:123456789abcdefghi","beneficiary_vasp_name":"Money`s Gone","currency":"BTC","label":"Main address","personal":False,"type":"withdrawal"}}

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

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

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

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

Allows to provide beneficiary information for the address

Scope: wallet:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
STETH
ETHW
USDC
USDT
EURR
MATIC
SOL
XRP
USYC
PAXG
BNB
USDE		 The currency symbol
type true string transfer
withdrawal
deposit_source		 Address book type
address true string Address in currency format, it must be in address book
beneficiary_vasp_name true string Name of beneficiary VASP
beneficiary_vasp_did true string DID of beneficiary VASP
beneficiary_vasp_website false string Website of the beneficiary VASP. Required if the address book entry is associated with a VASP that is not included in the list of known VASPs
beneficiary_first_name false string First name of beneficiary (if beneficiary is a person)
beneficiary_last_name false string First name of beneficiary (if beneficiary is a person)
beneficiary_company_name false string Beneficiary company name (if beneficiary is a company)
beneficiary_address true string Geographical address of the beneficiary
agreed true boolean Indicates that the user agreed to shared provided information with 3rd parties
personal true boolean The user confirms that he provided address belongs to him and he has access to it via an un-hosted wallet software
label true string Label of the address book entry

Response

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

/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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":6931,"jsonrpc":"2.0","method":"private/withdraw","params":{"address":"2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBz","amount":0.4,"currency":"BTC","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Scope: wallet:read_write and mainaccount

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 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

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 (milliseconds since the Unix epoch) of withdrawal confirmation, null when not confirmed
  ›  created_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  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 (milliseconds since the Unix epoch)

Account management

/public/get_announcements

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

var msg = 
{"id":7661,"jsonrpc":"2.0","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 = \
{"id":7661,"jsonrpc":"2.0","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_timestamp": 1550058362418,
      "important": false,
      "id": 1550058362418,
      "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    }
  ]
}

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

Try in API console

Parameters

Parameter Required Type Enum Description
start_timestamp false integer The most recent timestamp to return the results for (milliseconds since the UNIX epoch)
count false integer Maximum count of returned announcements

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  body string The HTML body of the announcement
  ›  confirmation boolean Whether the user confirmation is required for this announcement
  ›  id number A unique identifier for the announcement
  ›  important boolean Whether the announcement is marked as important
  ›  publication_timestamp integer The timestamp (milliseconds since the Unix epoch) of announcement publication
  ›  title string The title of the announcement

/private/change_api_key_name

curl -X GET "https://test.deribit.com/api/v2/private/change_api_key_name?id=3&name=KeyName3" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2453,"jsonrpc":"2.0","method":"private/change_api_key_name","params":{"id":3,"name":"KeyName3"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2453,"jsonrpc":"2.0","method":"private/change_api_key_name","params":{"id":3,"name":"KeyName3"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 2453,
  "result": {
    "timestamp": 1560242482758,
    "max_scope": "account:read_write block_trade:read trade:read_write wallet:read_write",
    "id": 3,
    "enabled": true,
    "default": false,
    "client_secret": "B6RsF9rrLY5ezEGBQkyLlV-UC7whyPJ34BMA-kKYpes",
    "client_id": "1sXMQBhM",
    "name": "KeyName3"
  }
}

Changes name for key with given id. Important notes.

Scope: account:read_write

Try in API console

Parameters

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

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret or MD5 fingerprint of public key used for authentication
  ›  default boolean Informs whether this api key is default (field is deprecated and will be removed in the future)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  enabled_features array of string List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval. Methods that use block_rfq scope are not affected by Block Trade approval feature
  ›  id integer key identifier
  ›  ip_whitelist array List of IP addresses whitelisted for a selected key
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none], block_rfq:[read, read_write, none]. If scope is not provided, its value is set as none.

Please check details described in Access scope
  ›  name string Api key name that can be displayed in transaction log
  ›  public_key string PEM encoded public key (Ed25519/RSA) used for asymmetric signatures (optional)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/change_margin_model

curl -X GET "https://test.deribit.com/api/v2/private/change_margin_model?margin_model=cross_pm&user_id=3" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/change_margin_model","params":{"margin_model":"cross_pm","user_id":3}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/change_margin_model","params":{"margin_model":"cross_pm","user_id":3}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "old_state": {
        "maintenance_margin_rate": 0,
        "initial_margin_rate": 0,
        "available_balance": 0
      },
      "new_state": {
        "maintenance_margin_rate": 0,
        "initial_margin_rate": 0,
        "available_balance": 0
      },
      "currency": "eth"
    },
    {
      "old_state": {
        "maintenance_margin_rate": 0.02862727,
        "initial_margin_rate": 0.45407615,
        "available_balance": 0.553590509
      },
      "new_state": {
        "maintenance_margin_rate": 0.02710204,
        "initial_margin_rate": 0.03252245,
        "available_balance": 0.98106428
      },
      "currency": "btc"
    }
  ]
}

Change margin model

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
user_id false integer Id of a (sub)account - by default current user id is used
margin_model true string cross_pm
cross_sm
segregated_pm
segregated_sm		 Margin model
dry_run false boolean If true request returns the result without switching the margining model. 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
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  new_state object Represents portfolio state after change
  ›    ›  available_balance number Available balance after change
  ›    ›  initial_margin_rate number Initial margin rate after change
  ›    ›  maintenance_margin_rate number Maintenance margin rate after change
  ›  old_state object Represents portfolio state before change
  ›    ›  available_balance number Available balance before change
  ›    ›  initial_margin_rate number Initial margin rate before change
  ›    ›  maintenance_margin_rate number Maintenance margin rate before change

/private/change_scope_in_api_key

curl -X GET "https://test.deribit.com/api/v2/private/change_scope_in_api_key?id=3&max_scope=account%3Aread_write+wallet%3Aread_write+block_trade%3Aread+trade%3Aread_write" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2453,"jsonrpc":"2.0","method":"private/change_scope_in_api_key","params":{"id":3,"max_scope":"account:read_write wallet:read_write block_trade:read trade:read_write"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2453,"jsonrpc":"2.0","method":"private/change_scope_in_api_key","params":{"id":3,"max_scope":"account:read_write wallet:read_write block_trade:read trade:read_write"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 2453,
  "result": {
    "timestamp": 1560242482758,
    "max_scope": "account:read_write block_trade:read trade:read_write wallet:read_write",
    "id": 3,
    "enabled": true,
    "default": false,
    "client_secret": "B6RsF9rrLY5ezEGBQkyLlV-UC7whyPJ34BMA-kKYpes",
    "client_id": "1sXMQBhM",
    "name": ""
  }
}

Changes scope for key with given id. Important notes.

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
max_scope true string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none]. If scope is not provided, its value is set as none.

Please check details described in Access scope
id true integer Id of key

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret or MD5 fingerprint of public key used for authentication
  ›  default boolean Informs whether this api key is default (field is deprecated and will be removed in the future)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  enabled_features array of string List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval. Methods that use block_rfq scope are not affected by Block Trade approval feature
  ›  id integer key identifier
  ›  ip_whitelist array List of IP addresses whitelisted for a selected key
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none], block_rfq:[read, read_write, none]. If scope is not provided, its value is set as none.

Please check details described in Access scope
  ›  name string Api key name that can be displayed in transaction log
  ›  public_key string PEM encoded public key (Ed25519/RSA) used for asymmetric signatures (optional)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

/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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":3964,"jsonrpc":"2.0","method":"private/change_subaccount_name","params":{"name":"new_user_1_1","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

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

Change the user name for a subaccount

Scope: account:read_write and mainaccount

Try in API console

Parameters

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

Response

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

/private/create_api_key

curl -X GET "https://test.deribit.com/api/v2/private/create_api_key?max_scope=account%3Aread+trade%3Aread+block_trade%3Aread_write+wallet%3Anone&name=Public+key+1&public_key=-----BEGIN+PUBLIC+KEY-----%0AMCowBQYDK2VwAyEAM7FWhKquNqLmTOV4hfYT5r3AjrYiORTT6Tn5HIfFNV8%3D%0A-----END+PUBLIC+KEY-----" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":8974,"jsonrpc":"2.0","method":"private/create_api_key","params":{"max_scope":"account:read trade:read block_trade:read_write wallet:none","name":"Public key 1","public_key":"-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAM7FWhKquNqLmTOV4hfYT5r3AjrYiORTT6Tn5HIfFNV8=\n-----END PUBLIC KEY-----"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":8974,"jsonrpc":"2.0","method":"private/create_api_key","params":{"max_scope":"account:read trade:read block_trade:read_write wallet:none","name":"Public key 1","public_key":"-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAM7FWhKquNqLmTOV4hfYT5r3AjrYiORTT6Tn5HIfFNV8=\n-----END PUBLIC KEY-----"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 8974,
  "result": {
    "timestamp": 1560238048714,
    "max_scope": "account:read block_trade:read_write trade:read wallet:none",
    "id": 5,
    "enabled": true,
    "enabled_features": [],
    "default": false,
    "public_key": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAM7FWhKquNqLmTOV4hfYT5r3AjrYiORTT6Tn5HIfFNV8=\n-----END PUBLIC KEY-----",
    "client_secret": "9c:6d:c9:02:fd:9f:75:6e:14:bb:71:c5:74:95:86:c8",
    "client_id": "wcVoQGam",
    "name": ""
  }
}

Creates a new api key with a given scope. Important notes

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
max_scope true string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none]. If scope is not provided, its value is set as none.

Please check details described in Access scope
name false string Name of key (only letters, numbers and underscores allowed; maximum length - 16 characters)
public_key false string ED25519 or RSA PEM Encoded public key that should be used to create asymmetric API Key for signing requests/authentication requests with user's private key.
enabled_features false array List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval. Methods that use block_rfq scope are not affected by Block Trade approval feature

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret or MD5 fingerprint of public key used for authentication
  ›  default boolean Informs whether this api key is default (field is deprecated and will be removed in the future)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  enabled_features array of string List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval. Methods that use block_rfq scope are not affected by Block Trade approval feature
  ›  id integer key identifier
  ›  ip_whitelist array List of IP addresses whitelisted for a selected key
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none], block_rfq:[read, read_write, none]. If scope is not provided, its value is set as none.

Please check details described in Access scope
  ›  name string Api key name that can be displayed in transaction log
  ›  public_key string PEM encoded public key (Ed25519/RSA) used for asymmetric signatures (optional)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/create_subaccount

curl -X GET "https://test.deribit.com/api/v2/private/create_subaccount?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":5414,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

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

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

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

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

{
    "jsonrpc": "2.0",
    "id": 5414,
    "result": {
        "email": "[email protected]",
        "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",
        "security_keys_enabled": false,
        "type": "subaccount",
        "username": "user_1_4"
    }
}

Create a new subaccount

Scope: account:read_write and mainaccount

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
  ›    ›    ›  additional_reserve number The account's balance reserved in other orders
  ›    ›    ›  available_funds number
  ›    ›    ›  available_withdrawal_funds number
  ›    ›    ›  balance number
  ›    ›    ›  currency string
  ›    ›    ›  equity number
  ›    ›    ›  initial_margin number
  ›    ›    ›  maintenance_margin number
  ›    ›    ›  margin_balance number
  ›    ›    ›  spot_reserve number
  ›    ›  eth object
  ›    ›    ›  additional_reserve number The account's balance reserved in other orders
  ›    ›    ›  available_funds number
  ›    ›    ›  available_withdrawal_funds number
  ›    ›    ›  balance number
  ›    ›    ›  currency string
  ›    ›    ›  equity number
  ›    ›    ›  initial_margin number
  ›    ›    ›  maintenance_margin number
  ›    ›    ›  margin_balance number
  ›    ›    ›  spot_reserve number
  ›  receive_notifications boolean When true - receive all notification emails on the main email
  ›  security_keys_enabled boolean Whether the Security Keys authentication is enabled
  ›  system_name string System generated user nickname
  ›  type string Account type
  ›  username string Account name (given by user)

/private/disable_api_key

curl -X GET "https://test.deribit.com/api/v2/private/disable_api_key?id=3" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2861,"jsonrpc":"2.0","method":"private/disable_api_key","params":{"id":3}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2861,"jsonrpc":"2.0","method":"private/disable_api_key","params":{"id":3}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 2861,
  "result": {
    "timestamp": 1560242676023,
    "max_scope": "account:read_write block_trade:read trade:read_write wallet:read_write",
    "id": 3,
    "enabled": false,
    "default": false,
    "client_secret": "B6RsF9rrLY5ezEGBQkyLlV-UC7whyPJ34BMA-kKYpes",
    "client_id": "1sXMQBhM",
    "name": ""
  }
}

Disables api key with given id. Important notes.

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
id true integer Id of key

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret or MD5 fingerprint of public key used for authentication
  ›  default boolean Informs whether this api key is default (field is deprecated and will be removed in the future)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  enabled_features array of string List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval. Methods that use block_rfq scope are not affected by Block Trade approval feature
  ›  id integer key identifier
  ›  ip_whitelist array List of IP addresses whitelisted for a selected key
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none], block_rfq:[read, read_write, none]. If scope is not provided, its value is set as none.

Please check details described in Access scope
  ›  name string Api key name that can be displayed in transaction log
  ›  public_key string PEM encoded public key (Ed25519/RSA) used for asymmetric signatures (optional)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/edit_api_key

curl -X GET "https://test.deribit.com/api/v2/private/edit_api_key?id=3&max_scope=account%3Aread_write+wallet%3Aread_write+block_trade%3Aread+trade%3Aread_write&name=NewKeyName" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2453,"jsonrpc":"2.0","method":"private/edit_api_key","params":{"id":3,"max_scope":"account:read_write wallet:read_write block_trade:read trade:read_write","name":"NewKeyName"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2453,"jsonrpc":"2.0","method":"private/edit_api_key","params":{"id":3,"max_scope":"account:read_write wallet:read_write block_trade:read trade:read_write","name":"NewKeyName"}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 2453,
  "result": {
    "timestamp": 1560242482758,
    "max_scope": "account:read_write block_trade:read trade:read_write wallet:read_write",
    "id": 3,
    "enabled": true,
    "default": false,
    "client_secret": "B6RsF9rrLY5ezEGBQkyLlV-UC7whyPJ34BMA-kKYpes",
    "client_id": "1sXMQBhM",
    "name": "NewKeyName"
  }
}

Edits existing API key. At least one parameter is required. Important notes

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
id true integer Id of key
max_scope true string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none]. If scope is not provided, its value is set as none.

Please check details described in Access scope
name false string Name of key (only letters, numbers and underscores allowed; maximum length - 16 characters)
enabled false boolean Enables/disables the API key. true to enable, false to disable
enabled_features false array List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval. Methods that use block_rfq scope are not affected by Block Trade approval feature
ip_whitelist false array Whitelist provided IP address on a selected key

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret or MD5 fingerprint of public key used for authentication
  ›  default boolean Informs whether this api key is default (field is deprecated and will be removed in the future)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  enabled_features array of string List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval. Methods that use block_rfq scope are not affected by Block Trade approval feature
  ›  id integer key identifier
  ›  ip_whitelist array List of IP addresses whitelisted for a selected key
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none], block_rfq:[read, read_write, none]. If scope is not provided, its value is set as none.

Please check details described in Access scope
  ›  name string Api key name that can be displayed in transaction log
  ›  public_key string PEM encoded public key (Ed25519/RSA) used for asymmetric signatures (optional)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/enable_affiliate_program

curl -X GET "https://test.deribit.com/api/v2/private/enable_affiliate_program?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":24,"jsonrpc":"2.0","method":"private/enable_affiliate_program","params":{}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":24,"jsonrpc":"2.0","method":"private/enable_affiliate_program","params":{}}

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

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

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

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

Enables affiliate program for user

Scope: account:read_write

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_api_key

curl -X GET "https://test.deribit.com/api/v2/private/enable_api_key?id=3" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":8580,"jsonrpc":"2.0","method":"private/enable_api_key","params":{"id":3}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":8580,"jsonrpc":"2.0","method":"private/enable_api_key","params":{"id":3}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 8580,
  "result": {
    "timestamp": 1560242634599,
    "max_scope": "account:read_write block_trade:read trade:read_write wallet:read_write",
    "id": 3,
    "enabled": true,
    "default": false,
    "client_secret": "B6RsF9rrLY5ezEGBQkyLlV-UC7whyPJ34BMA-kKYpes",
    "client_id": "1sXMQBhM",
    "name": ""
  }
}

Enables api key with given id. Important notes.

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
id true integer Id of key

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret or MD5 fingerprint of public key used for authentication
  ›  default boolean Informs whether this api key is default (field is deprecated and will be removed in the future)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  enabled_features array of string List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval. Methods that use block_rfq scope are not affected by Block Trade approval feature
  ›  id integer key identifier
  ›  ip_whitelist array List of IP addresses whitelisted for a selected key
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none], block_rfq:[read, read_write, none]. If scope is not provided, its value is set as none.

Please check details described in Access scope
  ›  name string Api key name that can be displayed in transaction log
  ›  public_key string PEM encoded public key (Ed25519/RSA) used for asymmetric signatures (optional)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/get_access_log

curl -X GET "https://test.deribit.com/api/v2/private/get_access_log?count=3&offset=0" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/get_access_log","params":{"count":3,"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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/get_access_log","params":{"count":3,"offset":0}}

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

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

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

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "records_total": 34,
      "data": [
        {
          "timestamp": 1575876682576,
          "result": "success",
          "ip": "127.0.0.1",
          "id": 45,
          "country": "Local Country",
          "city": "Local Town"
        },
        {
          "timestamp": 1575876459309,
          "result": "success",
          "ip": "127.0.0.1",
          "id": 44,
          "country": "Local Country",
          "city": "Local Town"
        },
        {
          "timestamp": 1575546252774,
          "result": "disabled_tfa",
          "ip": "127.0.0.1",
          "id": 43,
          "country": "Local Country",
          "city": "Local Town"
        }
      ]
    },
    "usIn": 1575903572350348,
    "usOut": 1575903572351765,
    "usDiff": 1417,
    "testnet": false
  }

Lists access logs for the user

Scope: account:read

Try in API console

Parameters

Parameter Required Type Enum Description
offset false integer The offset for pagination, default - 0
count false integer Number of requested items, default - 10

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  city string City where the IP address is registered (estimated)
  ›  country string Country where the IP address is registered (estimated)
  ›  data object or string Optional, additional information about action, type depends on log value
  ›  id integer Unique identifier
  ›  ip string IP address of source that generated action
  ›  log string Action description, values: changed_email - email was changed; changed_password - password was changed; disabled_tfa - TFA was disabled; enabled_tfa - TFA was enabled, success - successful login; failure - login failure; enabled_subaccount_login - login was enabled for subaccount (in data - subaccount uid); disabled_subaccount_login - login was disabled for subbaccount (in data - subbacount uid);new_api_key - API key was created (in data key client id); removed_api_key - API key was removed (in data key client id); changed_scope - scope of API key was changed (in data key client id); changed_whitelist - whitelist of API key was edited (in data key client id); disabled_api_key - API key was disabled (in data key client id); enabled_api_key - API key was enabled (in data key client id); reset_api_key - API key was reset (in data key client id)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/get_account_summaries

curl -X GET "https://test.deribit.com/api/v2/private/get_account_summaries?extended=true" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2515,"jsonrpc":"2.0","method":"private/get_account_summaries","params":{"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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2515,"jsonrpc":"2.0","method":"private/get_account_summaries","params":{"extended":True}}

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

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

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

{
  "jsonrpc": "2.0",
  "id": 2515,
  "result": {
    "id": 10,
    "email": "[email protected]",
    "system_name": "user",
    "username": "user",
    "block_rfq_self_match_prevention":true,
    "creation_timestamp": 1687352432143,
    "type": "main",
    "referrer_id": null,
    "login_enabled": false,
    "security_keys_enabled": false,
    "mmp_enabled": false,
    "interuser_transfers_enabled": false,
    "self_trading_reject_mode": "cancel_maker",
    "self_trading_extended_to_subaccounts": false,
    "summaries": [{
        "currency": "BTC",
        "delta_total_map": {
          "btc_usd": 31.594357699
        },
        "margin_balance": 302.62729214,
        "futures_session_rpl": -0.03258105,
        "options_session_rpl": 0,
        "estimated_liquidation_ratio_map": {
          "btc_usd": 0.1009872222854525
        },
        "session_upl": 0.05271555,
        "estimated_liquidation_ratio": 0.10098722,
        "options_gamma_map": {
          "btc_usd": 0.00001
        },
        "options_vega": 0.0858,
        "options_value": -0.0086,
        "available_withdrawal_funds": 301.35396172,
        "projected_delta_total": 32.613978,
        "maintenance_margin": 0.8857841,
        "total_pl": -0.33084225,
        "limits": {
          "limits_per_currency": false,
          "non_matching_engine": {
            "burst": 1500,
            "rate": 1000
          },
          "matching_engine": {
            "trading": { "total": { "burst": 250, "rate": 200 } },
            "spot": { "burst": 250, "rate": 200 },
            "quotes": { "burst": 500, "rate": 500 },
            "max_quotes": { "burst": 10, "rate": 10 },
            "guaranteed_quotes": { "burst": 2, "rate": 2 },
            "cancel_all": { "burst": 250, "rate": 200 }
          }
        },
        "projected_maintenance_margin": 0.7543841,
        "available_funds": 301.38059622,
        "options_delta": -1.01962,
        "balance": 302.60065765,
        "equity": 302.61869214,
        "futures_session_upl": 0.05921555,
        "fee_balance": 0,
        "options_session_upl": -0.0065,
        "projected_initial_margin": 1.01529592,
        "options_theta": 15.97071,
        "portfolio_margining_enabled": false,
        "cross_collateral_enabled": false,
        "margin_model": "segregated_sm",
        "options_vega_map": {
          "btc_usd": 0.0858
        },
        "futures_pl": -0.32434225,
        "options_pl": -0.0065,
        "initial_margin": 1.24669592,
        "spot_reserve": 0,
        "delta_total": 31.602958,
        "options_gamma": 0.00001,
        "session_rpl": -0.03258105,
        "fees": [
          {
            "value": {
              "default": {
                "type": "fixed",
                "taker": 0.00035,
                "maker": -0.0001
              },
              "block_trade": 0.3
            },
            "kind": "perpetual",
            "index_name": "btc_usd"
          },
          {
            "value": {
              "default": {
                "type": "relative",
                "taker": 0.625,
                "maker": 0.625
              },
              "block_trade": 0.625
            },
            "kind": "option",
            "index_name": "btc_usd"
          },
          {
            "value": {
              "default": {
                "type": "fixed",
                "taker": 0.00035,
                "maker": -0.0001
              },
              "block_trade": 0.3
            },
            "kind": "future",
            "index_name": "btc_usd"
          }
        ]
      },

      {
        "currency": "ETH",
        "futures_session_upl": 0,
        "portfolio_margining_enabled": false,
        "available_funds": 99.999598,
        "initial_margin": 0.000402,
        "futures_session_rpl": 0,
        "options_gamma": 0,
        "balance": 100,
        "options_vega_map": {},
        "session_upl": 0,
        "fee_balance": 0,
        "delta_total_map": {
          "eth_usd": 0
        },
        "projected_maintenance_margin": 0,
        "options_gamma_map": {},
        "projected_delta_total": 0,
        "margin_model": "segregated_sm",
        "futures_pl": 0,
        "options_theta": 0,
        "limits": {
          "limits_per_currency": false,
          "non_matching_engine": {
            "burst": 1500,
            "rate": 1000
          },
          "matching_engine": {
            "trading": { "total": { "burst": 250, "rate": 200 } },
            "spot": { "burst": 250, "rate": 200 },
            "quotes": { "burst": 500, "rate": 500 },
            "max_quotes": { "burst": 10, "rate": 10 },
            "guaranteed_quotes": { "burst": 2, "rate": 2 },
            "cancel_all": { "burst": 250, "rate": 200 }
          }
        },
        "options_delta": 0,
        "equity": 100,
        "projected_initial_margin": 0.0002,
        "estimated_liquidation_ratio_map": {
          "eth_usd": 0
        },
        "spot_reserve": 0.0002,
        "cross_collateral_enabled": false,
        "available_withdrawal_funds": 99.999597,
        "delta_total": 0,
        "options_session_upl": 0,
        "maintenance_margin": 0,
        "options_theta_map": {},
        "additional_reserve": 0,
        "estimated_liquidation_ratio": 0,
        "options_pl": 0,
        "options_session_rpl": 0,
        "options_vega": 0,
        "total_pl": 0,
        "session_rpl": 0,
        "options_value": 0,
        "margin_balance": 100,
        "fees": [
          {
            "value": {
              "default": {
                "type": "fixed",
                "taker": 0.00025,
                "maker": -0.00005
              },
              "block_trade": 0.2
            },
            "kind": "perpetual",
            "index_name": "eth_usd"
          },
          {
            "value": {
              "default": {
                "type": "relative",
                "taker": 0.5,
                "maker": 0.5
              },
              "block_trade": 0.5
            },
            "kind": "option",
            "index_name": "eth_usd"
          },
          {
            "value": {
              "default": {
                "type": "fixed",
                "taker": 0.00025,
                "maker": -0.00005
              },
              "block_trade": 0.2
            },
            "kind": "future",
            "index_name": "eth_usd"
          }
        ]
      }
    ]
  }
}

Retrieves a per-currency list of user account summaries. To read subaccount summary use subaccount_id parameter.

Scope: account:read

Try in API console

Parameters

Parameter Required Type Enum Description
subaccount_id false integer The user id for the subaccount
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
  ›  block_rfq_self_match_prevention string When Block RFQ Self Match Prevention is enabled, it ensures that RFQs cannot be executed between accounts that belong to the same legal entity. This setting is independent of the general self-match prevention settings and must be configured separately.
  ›  creation_timestamp integer Time at which the account was created (milliseconds since the Unix epoch; available when parameter extended = true)
  ›  email string User email (available when parameter extended = true)
  ›  id integer Account id (available when parameter extended = true)
  ›  interuser_transfers_enabled boolean true when the inter-user transfers are enabled for user (available when parameter extended = true)
  ›  login_enabled boolean Whether account is loginable using email and password (available when parameter extended = true and account is a subaccount)
  ›  mmp_enabled boolean Whether MMP is enabled (available when parameter extended = true)
  ›  referrer_id string Optional identifier of the referrer (of the affiliation program, and available when parameter extended = true), which link was used by this account at registration. It coincides with suffix of the affiliation link path after /reg-
  ›  security_keys_enabled boolean Whether Security Key authentication is enabled (available when parameter extended = true)
  ›  self_trading_extended_to_subaccounts string true if self trading rejection behavior is applied to trades between subaccounts (available when parameter extended = true)
  ›  self_trading_reject_mode string Self trading rejection behavior - reject_taker or cancel_maker (available when parameter extended = true)
  ›  summaries array of object Aggregated list of per-currency account summaries
  ›    ›  options_pl number Options profit and Loss
  ›    ›  projected_delta_total number The sum of position deltas without positions that will expire during closest expiration
  ›    ›  options_theta_map object Map of options' thetas per index
  ›    ›  has_non_block_chain_equity boolean Optional field returned with value true when user has non block chain equity that is excluded from proof of reserve calculations
  ›    ›  total_margin_balance_usd number Optional (only for users using cross margin). The account's total margin balance in all cross collateral currencies, expressed in USD
  ›    ›  limits object Returned object is described in separate document.
  ›    ›  total_delta_total_usd number Optional (only for users using cross margin). The account's total delta total in all cross collateral currencies, expressed in USD
  ›    ›  available_withdrawal_funds number The account's available to withdrawal funds
  ›    ›  options_session_rpl number Options session realized profit and Loss
  ›    ›  futures_session_rpl number Futures session realized profit and Loss
  ›    ›  total_pl number Profit and loss
  ›    ›  spot_reserve number The account's balance reserved in active spot orders
  ›    ›  fees array of object List of fee objects for all currency pairs and instrument types related to the currency (available when parameter extended = true and user has any discounts)
  ›    ›    ›  index_name string The currency pair this fee applies to
  ›    ›    ›  kind string Instrument type (e.g., future, perpetual, option)
  ›    ›    ›  value object
  ›    ›    ›    ›  block_trade number Block trade fee (if applicable)
  ›    ›    ›    ›  default object
  ›    ›    ›    ›    ›  maker number Maker fee
  ›    ›    ›    ›    ›  taker number Taker fee
  ›    ›    ›    ›    ›  type string Fee calculation type (e.g., fixed, relative)
  ›    ›    ›    ›  settlement number Settlement fee
  ›    ›  additional_reserve number The account's balance reserved in other orders
  ›    ›  options_session_upl number Options session unrealized profit and Loss
  ›    ›  cross_collateral_enabled boolean When true cross collateral is enabled for user
  ›    ›  options_value number Options value
  ›    ›  options_vega_map object Map of options' vegas per index
  ›    ›  maintenance_margin number The maintenance margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›    ›  futures_session_upl number Futures session unrealized profit and Loss
  ›    ›  portfolio_margining_enabled boolean true when portfolio margining is enabled for user
  ›    ›  futures_pl number Futures profit and Loss
  ›    ›  options_gamma_map object Map of options' gammas per index
  ›    ›  currency string Currency of the summary
  ›    ›  options_delta number Options summary delta
  ›    ›  initial_margin number The account's initial margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›    ›  projected_maintenance_margin number Projected maintenance margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›    ›  available_funds number The account's available funds. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›    ›  equity number The account's current equity
  ›    ›  margin_model string Name of user's currently enabled margin model
  ›    ›  balance number The account's balance
  ›    ›  session_upl number Session unrealized profit and loss
  ›    ›  margin_balance number The account's margin balance. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›    ›  deposit_address string The deposit address for the account (if available)
  ›    ›  options_theta number Options summary theta
  ›    ›  total_initial_margin_usd number Optional (only for users using cross margin). The account's total initial margin in all cross collateral currencies, expressed in USD
  ›    ›  estimated_liquidation_ratio number Estimated Liquidation Ratio is returned only for users without portfolio margining enabled. Multiplying it by future position's market price returns its estimated liquidation price. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›    ›  session_rpl number Session realized profit and loss
  ›    ›  fee_balance number The account's fee balance (it can be used to pay for fees)
  ›    ›  total_maintenance_margin_usd number Optional (only for users using cross margin). The account's total maintenance margin in all cross collateral currencies, expressed in USD
  ›    ›  options_vega number Options summary vega
  ›    ›  projected_initial_margin number Projected initial margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›    ›  options_gamma number Options summary gamma
  ›    ›  total_equity_usd number Optional (only for users using cross margin). The account's total equity in all cross collateral currencies, expressed in USD
  ›    ›  delta_total number The sum of position deltas
  ›  system_name string System generated user nickname (available when parameter extended = true)
  ›  type string Account type (available when parameter extended = true)
  ›  username string Account name (given by user) (available when parameter extended = true)

/private/get_account_summary

curl -X GET "https://test.deribit.com/api/v2/private/get_account_summary?currency=BTC&extended=true" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2515,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2515,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 2515,
  "result": {
    "delta_total_map": {
      "btc_usd": 31.594357699
    },
    "margin_balance": 302.62729214,
    "futures_session_rpl": -0.03258105,
    "options_session_rpl": 0,
    "estimated_liquidation_ratio_map": {
      "btc_usd": 0.1009872222854525
    },
    "session_upl": 0.05271555,
    "email": "[email protected]",
    "system_name": "user",
    "username": "user",
    "interuser_transfers_enabled": false,
    "id": 10,
    "estimated_liquidation_ratio": 0.10098722,
    "options_gamma_map": {
      "btc_usd": 0.00001
    },
    "options_vega": 0.0858,
    "options_value": -0.0086,
    "available_withdrawal_funds": 301.35396172,
    "projected_delta_total": 32.613978,
    "maintenance_margin": 0.8857841,
    "total_pl": -0.33084225,
    "limits": {
      "limits_per_currency": false,
      "non_matching_engine": {
        "burst": 1500,
        "rate": 1000
      },
      "matching_engine": {
        "trading": { "total": { "burst": 250, "rate": 200 } },
        "spot": { "burst": 250, "rate": 200 },
        "quotes": { "burst": 500, "rate": 500 },
        "max_quotes": { "burst": 10, "rate": 10 },
        "guaranteed_quotes": { "burst": 2, "rate": 2 },
        "cancel_all": { "burst": 250, "rate": 200 }
      }
    },
    "options_theta_map": {
      "btc_usd": 15.97071
    },
    "projected_maintenance_margin": 0.7543841,
    "available_funds": 301.38059622,
    "login_enabled": false,
    "options_delta": -1.01962,
    "balance": 302.60065765,
    "security_keys_enabled": false,
    "referrer_id": null,
    "mmp_enabled": false,
    "equity": 302.61869214,
    "block_rfq_self_match_prevention":true,
    "futures_session_upl": 0.05921555,
    "fee_balance": 0,
    "currency": "BTC",
    "options_session_upl": -0.0065,
    "projected_initial_margin": 1.01529592,
    "options_theta": 15.97071,
    "creation_timestamp": 1687352432143,
    "self_trading_extended_to_subaccounts": false,
    "portfolio_margining_enabled": false,
    "cross_collateral_enabled": false,
    "margin_model": "segregated_sm",
    "options_vega_map": {
      "btc_usd": 0.0858
    },
    "futures_pl": -0.32434225,
    "options_pl": -0.0065,
    "type": "main",
    "self_trading_reject_mode": "cancel_maker",
    "initial_margin": 1.24669592,
    "spot_reserve": 0,
    "delta_total": 31.602958,
    "options_gamma": 0.00001,
    "session_rpl": -0.03258105,
    "fees": [
      {
        "value": {
          "default": {
            "type": "fixed",
            "taker": 0.00035,
            "maker": -0.0001
          },
          "block_trade": 0.3
        },
        "kind": "perpetual",
        "index_name": "btc_usd"
      },
      {
        "value": {
          "default": {
            "type": "relative",
            "taker": 0.625,
            "maker": 0.625
          },
          "block_trade": 0.625
        },
        "kind": "option",
        "index_name": "btc_usd"
      },
      {
        "value": {
          "default": {
            "type": "fixed",
            "taker": 0.00035,
            "maker": -0.0001
          },
          "block_trade": 0.3
        },
        "kind": "future",
        "index_name": "btc_usd"
      }
    ]
  }
}

Retrieves user account summary. To read subaccount summary use subaccount_id parameter.

Scope: account:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
STETH
ETHW
USDC
USDT
EURR
MATIC
SOL
XRP
USYC
PAXG
BNB
USDE		 The currency symbol
subaccount_id false integer The user id for the subaccount
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_pl number Options profit and Loss
  ›  projected_delta_total number The sum of position deltas without positions that will expire during closest expiration
  ›  options_theta_map object Map of options' thetas per index
  ›  has_non_block_chain_equity boolean Optional field returned with value true when user has non block chain equity that is excluded from proof of reserve calculations
  ›  total_margin_balance_usd number Optional (only for users using cross margin). The account's total margin balance in all cross collateral currencies, expressed in USD
  ›  limits object Returned object is described in separate document.
  ›  type string Account type (available when parameter extended = true)
  ›  total_delta_total_usd number Optional (only for users using cross margin). The account's total delta total in all cross collateral currencies, expressed in USD
  ›  available_withdrawal_funds number The account's available to withdrawal funds
  ›  options_session_rpl number Options session realized profit and Loss
  ›  futures_session_rpl number Futures session realized profit and Loss
  ›  total_pl number Profit and loss
  ›  spot_reserve number The account's balance reserved in active spot orders
  ›  fees array of object List of fee objects for all currency pairs and instrument types related to the currency (available when parameter extended = true and user has any discounts)
  ›    ›  index_name string The currency pair this fee applies to
  ›    ›  kind string Type of the instruments the fee applies to - future for future instruments (excluding perpetual), perpetual for future perpetual instruments, option for options
  ›    ›  value object
  ›    ›    ›  block_trade number Block trade fee (if applicable)
  ›    ›    ›  default object
  ›    ›    ›    ›  maker number Maker fee
  ›    ›    ›    ›  taker number Taker fee
  ›    ›    ›    ›  type string Fee type - relative if fee is calculated as a fraction of base instrument fee, fixed if fee is calculated solely using user fee
  ›    ›    ›  settlement number Settlement fee
  ›  additional_reserve number The account's balance reserved in other orders
  ›  options_session_upl number Options session unrealized profit and Loss
  ›  cross_collateral_enabled boolean When true cross collateral is enabled for user
  ›  id integer Account id (available when parameter extended = true)
  ›  options_value number Options value
  ›  creation_timestamp integer Time at which the account was created (milliseconds since the Unix epoch; available when parameter extended = true)
  ›  email string User email (available when parameter extended = true)
  ›  options_vega_map object Map of options' vegas per index
  ›  maintenance_margin number The maintenance margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  mmp_enabled boolean Whether MMP is enabled (available when parameter extended = true)
  ›  futures_session_upl number Futures session unrealized profit and Loss
  ›  portfolio_margining_enabled boolean true when portfolio margining is enabled for user
  ›  futures_pl number Futures profit and Loss
  ›  options_gamma_map object Map of options' gammas per index
  ›  currency string The selected currency
  ›  options_delta number Options summary delta
  ›  initial_margin number The account's initial margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  projected_maintenance_margin number Projected maintenance margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  available_funds number The account's available funds. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  referrer_id string Optional identifier of the referrer (of the affiliation program, and available when parameter extended = true), which link was used by this account at registration. It coincides with suffix of the affiliation link path after /reg-
  ›  login_enabled boolean Whether account is loginable using email and password (available when parameter extended = true and account is a subaccount)
  ›  equity number The account's current equity
  ›  margin_model string Name of user's currently enabled margin model
  ›  balance number The account's balance
  ›  session_upl number Session unrealized profit and loss
  ›  margin_balance number The account's margin balance. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  security_keys_enabled boolean Whether Security Key authentication is enabled (available when parameter extended = true)
  ›  deposit_address string The deposit address for the account (if available)
  ›  options_theta number Options summary theta
  ›  self_trading_extended_to_subaccounts string true if self trading rejection behavior is applied to trades between subaccounts (available when parameter extended = true)
  ›  interuser_transfers_enabled boolean true when the inter-user transfers are enabled for user (available when parameter extended = true)
  ›  total_initial_margin_usd number Optional (only for users using cross margin). The account's total initial margin in all cross collateral currencies, expressed in USD
  ›  estimated_liquidation_ratio number Estimated Liquidation Ratio is returned only for users without portfolio margining enabled. Multiplying it by future position's market price returns its estimated liquidation price. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  session_rpl number Session realized profit and loss
  ›  fee_balance number The account's fee balance (it can be used to pay for fees)
  ›  total_maintenance_margin_usd number Optional (only for users using cross margin). The account's total maintenance margin in all cross collateral currencies, expressed in USD
  ›  options_vega number Options summary vega
  ›  projected_initial_margin number Projected initial margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  self_trading_reject_mode string Self trading rejection behavior - reject_taker or cancel_maker (available when parameter extended = true)
  ›  system_name string System generated user nickname (available when parameter extended = true)
  ›  options_gamma number Options summary gamma
  ›  username string Account name (given by user) (available when parameter extended = true)
  ›  total_equity_usd number Optional (only for users using cross margin). The account's total equity in all cross collateral currencies, expressed in USD
  ›  delta_total number The sum of position deltas

/private/get_affiliate_program_info

curl -X GET "https://test.deribit.com/api/v2/private/get_affiliate_program_info?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2,"jsonrpc":"2.0","method":"private/get_affiliate_program_info","params":{}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2,"jsonrpc":"2.0","method":"private/get_affiliate_program_info","params":{}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "received": {
      "eth": 0.00004,
      "btc": 0.000001
    },
    "number_of_affiliates": 1,
    "link": "https://www.deribit.com/reg-xxx.zxyq",
    "is_enabled": true
  }
}

Retrieves user`s affiliates count, payouts and link.

Scope: account:read

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
  ›  is_enabled boolean Status of affiliate program
  ›  link string Affiliate link
  ›  number_of_affiliates number Number of affiliates
  ›  received object
  ›    ›  btc number Total payout received in BTC
  ›    ›  eth number Total payout received in ETH

/private/get_email_language

curl -X GET "https://test.deribit.com/api/v2/private/get_email_language?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":9265,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":9265,"jsonrpc":"2.0","method":"private/get_email_language","params":{}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 9265,
  "result": "en"
}

Retrieves the language to be used for emails.

Scope: account:read

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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":3022,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":3022,"jsonrpc":"2.0","method":"private/get_new_announcements","params":{}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 3022,
  "result": [
    {
      "title": "Example announcement",
      "publication_timestamp": 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.

Scope: account:read

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
  ›  confirmation boolean Whether the user confirmation is required for this announcement
  ›  id number A unique identifier for the announcement
  ›  important boolean Whether the announcement is marked as important
  ›  publication_timestamp integer The timestamp (milliseconds since the Unix epoch) of announcement publication
  ›  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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":404,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":404,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 404,
  "result": {
      "average_price": 0,
      "delta": 0,
      "direction": "buy",
      "estimated_liquidation_price": 0,
      "floating_profit_loss": 0,
      "index_price": 3555.86,
      "initial_margin": 0,
      "instrument_name": "BTC-PERPETUAL",
      "interest_value" : 1.7362511643080387,
      "leverage": 100,
      "kind": "future",
      "maintenance_margin": 0,
      "mark_price": 3556.62,
      "open_orders_margin": 0.000165889,
      "realized_profit_loss": 0,
      "settlement_price": 3555.44,
      "size": 0,
      "size_currency": 0,
      "total_profit_loss": 0
  }
}

Retrieve user position.

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  average_price number Average price of trades that built this position
  ›  average_price_usd number Only for options, average price in USD
  ›  delta number Delta parameter
  ›  direction string Direction: buy, sell or zero
  ›  estimated_liquidation_price number Estimated liquidation price, added only for futures, for users with segregated_sm margin model
  ›  floating_profit_loss number Floating profit or loss
  ›  floating_profit_loss_usd number Only for options, floating profit or loss in USD
  ›  gamma number Only for options, Gamma parameter
  ›  index_price number Current index price
  ›  initial_margin number Initial margin
  ›  instrument_name string Unique instrument identifier
  ›  interest_value number Value used to calculate realized_funding (perpetual only)
  ›  kind string Instrument kind: "future", "option", "spot", "future_combo", "option_combo"
  ›  leverage integer Current available leverage for future position
  ›  maintenance_margin number Maintenance margin
  ›  mark_price number Current mark price for position's instrument
  ›  open_orders_margin number Open orders margin
  ›  realized_funding number Realized Funding in current session included in session realized profit or loss, only for positions of perpetual instruments
  ›  realized_profit_loss number Realized profit or loss
  ›  settlement_price number Optional (not added for spot). 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
  ›  theta number Only for options, Theta parameter
  ›  total_profit_loss number Profit or loss from position
  ›  vega number Only for options, Vega parameter

/private/get_positions

curl -X GET "https://test.deribit.com/api/v2/private/get_positions?currency=BTC&kind=future" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2236,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2236,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 2236,
  "result": [
      {
          "average_price": 7440.18,
          "delta": 0.006687487,
          "direction": "buy",
          "estimated_liquidation_price": 1.74,
          "floating_profit_loss": 0,
          "index_price": 7466.79,
          "initial_margin": 0.000197283,
          "instrument_name": "BTC-PERPETUAL",
          "interest_value" : 1.7362511643080387,
          "kind": "future",
          "leverage": 34,
          "maintenance_margin": 0.000143783,
          "mark_price": 7476.65,
          "open_orders_margin": 0.000197288,
          "realized_funding": -1e-8,
          "realized_profit_loss": -9e-9,
          "settlement_price": 7476.65,
          "size": 50,
          "size_currency": 0.006687487,
          "total_profit_loss": 0.000032781
      }
  ]
}

Retrieve user positions. To retrieve subaccount positions, use subaccount_id parameter.

Scope: trade:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency false string BTC
ETH
USDC
USDT
EURR
any
kind false string future
option
spot
future_combo
option_combo		 Kind filter on positions
subaccount_id false 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 array of object
  ›  average_price number Average price of trades that built this position
  ›  average_price_usd number Only for options, average price in USD
  ›  delta number Delta parameter
  ›  direction string Direction: buy, sell or zero
  ›  estimated_liquidation_price number Estimated liquidation price, added only for futures, for users with segregated_sm margin model
  ›  floating_profit_loss number Floating profit or loss
  ›  floating_profit_loss_usd number Only for options, floating profit or loss in USD
  ›  gamma number Only for options, Gamma parameter
  ›  index_price number Current index price
  ›  initial_margin number Initial margin
  ›  instrument_name string Unique instrument identifier
  ›  interest_value number Value used to calculate realized_funding (perpetual only)
  ›  kind string Instrument kind: "future", "option", "spot", "future_combo", "option_combo"
  ›  leverage integer Current available leverage for future position
  ›  maintenance_margin number Maintenance margin
  ›  mark_price number Current mark price for position's instrument
  ›  open_orders_margin number Open orders margin
  ›  realized_funding number Realized Funding in current session included in session realized profit or loss, only for positions of perpetual instruments
  ›  realized_profit_loss number Realized profit or loss
  ›  settlement_price number Optional (not added for spot). 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
  ›  theta number Only for options, Theta parameter
  ›  total_profit_loss number Profit or loss from position
  ›  vega number Only for options, Vega parameter

/private/get_subaccounts

curl -X GET "https://test.deribit.com/api/v2/private/get_subaccounts?with_portfolio=true" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":4947,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":4947,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
    "jsonrpc": "2.0",
    "id": 4947,
    "result": [
        {
            "email": "[email protected]",
            "id": 2,
            "is_password": true,
            "margin_model": "segregated_sm",
            "login_enabled": true,
            "portfolio": {
                "eth": {
                    "additional_reserve": 0,
                    "spot_reserve": 0,
                    "available_funds": 5,
                    "available_withdrawal_funds": 5,
                    "balance": 5,
                    "currency": "eth",
                    "equity": 5,
                    "initial_margin": 0,
                    "maintenance_margin": 0,
                    "margin_balance": 5
                },
                "btc": {
                    "additional_reserve": 0,
                    "spot_reserve": 0,
                    "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",
            "security_keys_enabled": false,
            "security_keys_assignments": [],
            "type": "main",
            "username": "user_1"
        },
        {
            "email": "[email protected]",
            "id": 7,
            "is_password": true,
            "margin_model": "cross_pm",
            "login_enabled": false,
            "portfolio": {
                "eth": {
                    "additional_reserve": 0,
                    "spot_reserve": 0,
                    "available_funds": 0,
                    "available_withdrawal_funds": 0,
                    "balance": 0,
                    "currency": "eth",
                    "equity": 0,
                    "initial_margin": 0,
                    "maintenance_margin": 0,
                    "margin_balance": 0
                },
                "btc": {
                    "additional_reserve": 0,
                    "spot_reserve": 0,
                    "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",
            "security_keys_enabled": false,
            "security_keys_assignments": [],
            "type": "subaccount",
            "username": "user_1_1"
        }
    ]
}

Get information about subaccounts. When called from subaccount, the response will include limited details for the main account and details for the subaccount initiating the request. The portfolio information will be included in the response only if the with_portfolio parameter is set to true.

Scope: account:read

Try in API console

Parameters

Parameter Required Type Enum Description
with_portfolio false boolean Portfolio flag: true for portfolio information, false for subaccount information only. false by default

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
  ›  margin_model string Margin model
  ›  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
  ›    ›    ›  additional_reserve number The account's balance reserved in other orders
  ›    ›    ›  available_funds number
  ›    ›    ›  available_withdrawal_funds number
  ›    ›    ›  balance number
  ›    ›    ›  currency string
  ›    ›    ›  equity number
  ›    ›    ›  initial_margin number
  ›    ›    ›  maintenance_margin number
  ›    ›    ›  margin_balance number
  ›    ›    ›  spot_reserve number
  ›    ›  eth object
  ›    ›    ›  additional_reserve number The account's balance reserved in other orders
  ›    ›    ›  available_funds number
  ›    ›    ›  available_withdrawal_funds number
  ›    ›    ›  balance number
  ›    ›    ›  currency string
  ›    ›    ›  equity number
  ›    ›    ›  initial_margin number
  ›    ›    ›  maintenance_margin number
  ›    ›    ›  margin_balance number
  ›    ›    ›  spot_reserve number
  ›  proof_id string hashed identifier used in the Proof Of Liability for the subaccount. This identifier allows you to find your entries in the Deribit Proof-Of-Reserves files. IMPORTANT: Keep it secret to not disclose your entries in the Proof-Of-Reserves.
  ›  proof_id_signature string signature used as a base string for proof_id hash. IMPORTANT: Keep it secret to not disclose your entries in the Proof-Of-Reserves.
  ›  receive_notifications boolean When true - receive all notification emails on the main email
  ›  security_keys_assignments array Names of assignments with Security Keys assigned
  ›  security_keys_enabled boolean Whether the Security Keys authentication is enabled
  ›  system_name string System generated user nickname
  ›  type string
  ›  username string

/private/get_subaccounts_details

curl -X GET "https://test.deribit.com/api/v2/private/get_subaccounts_details?currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"method":"private/get_subaccounts_details","params":{"currency":"BTC"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"method":"private/get_subaccounts_details","params":{"currency":"BTC"}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc":"2.0",
  "result":[
    {
      "uid": 3,
      "positions": [
        {
          "total_profit_loss": -0.000118183,
          "size_currency": 0.004152776,
          "size": 200.0,
          "settlement_price": 48150.36,
          "realized_profit_loss": -8.79e-7,
          "realized_funding": -8.8e-7,
          "open_orders_margin": 0.0,
          "mark_price": 48160.55,
          "maintenance_margin": 0.000089286,
          "leverage": 34,
          "kind": "future",
          "instrument_name": "BTC-PERPETUAL",
          "initial_margin": 0.000122508,
          "index_price": 47897.12,
          "floating_profit_loss": -0.00003451,
          "estimated_liquidation_price": 2.33,
          "direction": "buy",
          "delta": 0.004152776,
          "average_price": 49571.3
        }
      ]
    }, {
      "uid":10,
      "positions": [
        {
          "total_profit_loss":0.000037333,
          "size_currency":-0.001308984,
          "size":-60.0,
          "settlement_price":47886.98,
          "realized_profit_loss":0.0,
          "open_orders_margin":0.0,
          "mark_price":45837.07,
          "maintenance_margin":0.000028143,
          "leverage":34,
          "kind":"future",
          "instrument_name":"BTC-3SEP21",
          "initial_margin":0.000038615,
          "index_price":47897.12,
          "floating_profit_loss":0.000037333,
          "estimated_liquidation_price":null,
          "direction":"sell",
          "delta":-0.001308984,
          "average_price":47182.76
        }
      ]
    }
  ]
}

Get subaccounts positions

Scope: account:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
with_open_orders false boolean Optional parameter to ask for open orders list, 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
  ›  open_orders array of object
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  order_id string Unique order identifier
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  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.
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  primary_order_id string Unique order identifier
  ›  positions array of object
  ›    ›  average_price number Average price of trades that built this position
  ›    ›  average_price_usd number Only for options, average price in USD
  ›    ›  delta number Delta parameter
  ›    ›  direction string Direction: buy, sell or zero
  ›    ›  floating_profit_loss number Floating profit or loss
  ›    ›  floating_profit_loss_usd number Only for options, floating profit or loss in USD
  ›    ›  gamma number Only for options, Gamma parameter
  ›    ›  index_price number Current index price
  ›    ›  initial_margin number Initial margin
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  interest_value number Value used to calculate realized_funding (perpetual only)
  ›    ›  kind string Instrument kind: "future", "option", "spot", "future_combo", "option_combo"
  ›    ›  leverage integer Current available leverage for future position
  ›    ›  maintenance_margin number Maintenance margin
  ›    ›  mark_price number Current mark price for position's instrument
  ›    ›  realized_funding number Realized Funding in current session included in session realized profit or loss, only for positions of perpetual instruments
  ›    ›  realized_profit_loss number Realized profit or loss
  ›    ›  settlement_price number Optional (not added for spot). 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
  ›    ›  theta number Only for options, Theta parameter
  ›    ›  total_profit_loss number Profit or loss from position
  ›    ›  vega number Only for options, Vega parameter
  ›  uid integer Account/Subaccount identifier

/private/get_transaction_log

curl -X GET "https://test.deribit.com/api/v2/private/get_transaction_log?count=5&currency=BTC&end_timestamp=1613660407000&start_timestamp=1613657734000" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":4,"jsonrpc":"2.0","method":"private/get_transaction_log","params":{"count":5,"currency":"BTC","end_timestamp":"1613660407000","start_timestamp":"1613657734000"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":4,"jsonrpc":"2.0","method":"private/get_transaction_log","params":{"count":5,"currency":"BTC","end_timestamp":"1613660407000","start_timestamp":"1613657734000"}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "logs": [
      {
        "username": "TestUser",
        "user_seq": 6009,
        "user_id": 7,
        "type": "transfer",
        "trade_id": null,
        "timestamp": 1613659830333,
        "side": "-",
        "price": null,
        "position": null,
        "order_id": null,
        "interest_pl": null,
        "instrument_name": null,
        "info": {
          "transfer_type": "subaccount",
          "other_user_id": 27,
          "other_user": "Subaccount"
        },
        "id": 61312,
        "equity": 3000.9275869,
        "currency": "BTC",
        "commission": 0,
        "change": -2.5,
        "cashflow": -2.5,
        "balance": 3001.22270418
      },
      {
        "username": "TestUser",
        "user_seq": 6008,
        "user_id": 7,
        "type": "settlement",
        "trade_id": null,
        "total_interest_pl": 0.00001243,
        "timestamp": 1613659544153,
        "side": "long",
        "session_upl": 0.00220172,
        "session_rpl": -0.00004467,
        "price_currency": "USD",
        "price": 51807.07,
        "position": 1520,
        "order_id": null,
        "interest_pl": 0.00000993,
        "instrument_name": "BTC-PERPETUAL",
        "info": {
          "settlement_price": 51807,
          "floating_pl": 0.00220172
        },
        "id": 61311,
        "equity": 3003.42821428,
        "currency": "BTC",
        "commission": null,
        "change": 0.00215706,
        "cashflow": 0.00215706,
        "balance": 3003.72270418,
        "amount": 1520
      },
      {
        "username": "TestUser",
        "user_seq": 6007,
        "user_id": 7,
        "type": "deposit",
        "trade_id": null,
        "timestamp": 1613657828414,
        "side": "-",
        "price": null,
        "position": null,
        "order_id": null,
        "interest_pl": null,
        "instrument_name": null,
        "info": {
          "transaction": "de6eba075855f32c9510f338d3ca0900376cedcb9f7b142caccfbdc292d3237e",
          "deposit_type": "wallet",
          "addr": "2N8prMvpZHr8aYqodX3S4yhz5wMxjY8La3p"
        },
        "id": 61291,
        "equity": 3003.4876111,
        "currency": "BTC",
        "commission": 0,
        "change": 0.65,
        "cashflow": 0.65,
        "balance": 3003.72054712
      },
      {
        "username": "TestUser",
        "user_seq": 6006,
        "user_role": "maker",
        "user_id": 7,
        "type": "trade",
        "ip": "11.222.33.44",
        "trade_id": "28349",
        "timestamp": 1613657734620,
        "side": "open buy",
        "profit_as_cashflow": false,
        "price_currency": "BTC",
        "price": 0.1537,
        "position": 0.7,
        "order_id": "67546",
        "mark_price": 0.04884653215049635,
        "interest_pl": 0,
        "instrument_name": "BTC-19FEB21-49200-C",
        "info": "Source: api",
        "id": 61289,
        "equity": 3002.83270455,
        "currency": "BTC",
        "commission": 0,
        "change": -0.10759,
        "cashflow": -0.10759,
        "balance": 3003.07054712,
        "amount": 0.7
      },
      {
        "username": "TestUser",
        "user_seq": 6005,
        "user_role": "maker",
        "user_id": 7,
        "type": "trade",
        "trade_id": "28349",
        "timestamp": 1613657734620,
        "side": "close buy",
        "profit_as_cashflow": false,
        "price_currency": "BTC",
        "price": 0.1537,
        "position": 0,
        "order_id": "67546",
        "mark_price": 0.04884653215049635,
        "interest_pl": 0,
        "instrument_name": "BTC-19FEB21-49200-C",
        "info": "Source: api",
        "id": 61288,
        "equity": 3002.83270455,
        "currency": "BTC",
        "commission": 0,
        "change": -0.04611,
        "cashflow": -0.04611,
        "balance": 3003.17813712,
        "amount": 0.3
      }
    ],
    "continuation": 61282
  }
}

Retrieve the latest user trades that have occurred for a specific instrument and within a given time range.

Scope: account:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
STETH
ETHW
USDC
USDT
EURR
MATIC
SOL
XRP
USYC
PAXG
BNB
USDE		 The currency symbol
start_timestamp true integer The earliest timestamp to return result from (milliseconds since the UNIX epoch)
end_timestamp true integer The most recent timestamp to return result from (milliseconds since the UNIX epoch)
query false string The following keywords can be used to filter the results: trade, maker, taker, open, close, liquidation, buy, sell, withdrawal, delivery, settlement, deposit, transfer, option, future, correction, block_trade, swap. Plus withdrawal or transfer addresses
count false integer Number of requested items, default - 100
subaccount_id false integer Id of a subaccount
continuation false integer Continuation token for pagination

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  continuation integer Continuation token for pagination. NULL when no continuation.
  ›  logs array of object
  ›    ›  change number Change in cash balance. For trades: fees and options premium paid/received. For settlement: Futures session PNL and perpetual session funding.
  ›    ›  cashflow number For futures and perpetual contracts: Realized session PNL (since last settlement). For options: the amount paid or received for the options traded.
  ›    ›  user_id integer Unique user identifier
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  type string Transaction category/type. The most common are: trade, deposit, withdrawal, settlement, delivery, transfer, swap, correction. New types can be added any time in the future
  ›    ›  order_id string Unique order identifier
  ›    ›  position number Updated position size after the transaction
  ›    ›  side string One of: short or long in case of settlements, close sell or close buy in case of deliveries, open sell, open buy, close sell, close buy in case of trades
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  interest_pl number Actual funding rate of trades and settlements on perpetual instruments
  ›    ›  user_role string Trade role of the user: maker or taker
  ›    ›  fee_role string Fee role of the user: maker or taker. Can be different from trade role of the user when iceberg order was involved in matching.
  ›    ›  id integer Unique identifier
  ›    ›  index_price number The index price for the instrument during the delivery
  ›    ›  info object Additional information regarding transaction. Strongly dependent on the log entry type
  ›    ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  price number Settlement/delivery price or the price level of the traded contracts
  ›    ›  user_seq integer Sequential identifier of user transaction
  ›    ›  settlement_price number The settlement price for the instrument during the delivery
  ›    ›  price_currency string Currency symbol associated with the price field value
  ›    ›  equity number Updated equity value after the transaction
  ›    ›  total_interest_pl number Total session funding rate
  ›    ›  balance number Cash balance after the transaction
  ›    ›  session_upl number Session unrealized profit and loss
  ›    ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  profit_as_cashflow boolean Indicator informing whether the cashflow is waiting for settlement or not
  ›    ›  commission number Commission paid so far (in base currency)
  ›    ›  session_rpl number Session realized profit and loss
  ›    ›  mark_price number Market price during the trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  ip string The IP address from which the trade was initiated
  ›    ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  username string System name or user defined subaccount alias
  ›    ›  instrument_name string Unique instrument identifier

/private/get_user_locks

curl -X GET "https://test.deribit.com/api/v2/private/get_user_locks?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":74,"method":"private/get_user_locks","params":{}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":74,"method":"private/get_user_locks","params":{}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "id":74,
  "result":[
    {
      "message":"locked in one currency",
      "locked":true,
      "currency":"BTC"
    },
    {
      "locked":false,
      "currency":"ETH"
    },
    {
      "locked":false,
      "currency":"USDC"
    },
    {
      "locked":false,
      "currency":"SOL"
    }
  ]
}

Retrieves information about locks on user account

Scope: account:read

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
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  enabled boolean Value is set to 'true' when user account is locked in currency
  ›  message text Optional information for user why his account is locked

/private/list_api_keys

curl -X GET "https://test.deribit.com/api/v2/private/list_api_keys?" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2553,"jsonrpc":"2.0","method":"private/list_api_keys"};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2553,"jsonrpc":"2.0","method":"private/list_api_keys"}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 2553,
  "result": [
    {
      "timestamp": 1560236001108,
      "max_scope": "account:read block_trade:read trade:read_write wallet:read",
      "id": 1,
      "enabled": false,
      "default": false,
      "client_secret": "SjM57m1T2CfXZ4vZ76X1APjqRlJdtzHI8IwVXoQnfoM",
      "client_id": "TiA4AyLPq3",
      "name": "",
      "enabled_features": []
    },
    {
      "timestamp": 1560236287708,
      "max_scope": "account:read_write block_trade:read_write trade:read_write wallet:read_write",
      "id": 2,
      "enabled": true,
      "default": true,
      "client_secret": "mwNOvbUVyQczytQ5IVM8CbzmgqNJ81WvLKfu6MXcJPs",
      "client_id": "aD-KFx-H",
      "name": "",
      "enabled_features": []
    }
  ]
}

Retrieves list of api keys. Important notes.

Scope: account:read

Try in API console

Parameters

This method takes no parameters

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret or MD5 fingerprint of public key used for authentication
  ›  default boolean Informs whether this api key is default (field is deprecated and will be removed in the future)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  enabled_features array of string List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval. Methods that use block_rfq scope are not affected by Block Trade approval feature
  ›  id integer key identifier
  ›  ip_whitelist array List of IP addresses whitelisted for a selected key
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none], block_rfq:[read, read_write, none]. If scope is not provided, its value is set as none.

Please check details described in Access scope
  ›  name string Api key name that can be displayed in transaction log
  ›  public_key string PEM encoded public key (Ed25519/RSA) used for asymmetric signatures (optional)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

/private/list_custody_accounts

curl -X GET "https://test.deribit.com/api/v2/private/list_custody_accounts?currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2515,"jsonrpc":"2.0","method":"private/list_custody_accounts","params":{"currency":"BTC"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2515,"jsonrpc":"2.0","method":"private/list_custody_accounts","params":{"currency":"BTC"}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 2515,
  "result": [{
    "name": "copper",
    "currency": "BTC",
    "client_id": "4KVcFrrzmXBR",
    "external_id": "24f97d44-1d72-4641-8527-811268a0bdd3",
    "balance": 0.5,
    "withdrawals_require_security_key": false,
    "pending_withdrawal_balance": 0.1,
    "auto_deposit":false
  }]
}

Retrieves user custody accounts list.

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result array of object Custody account
  ›  auto_deposit boolean When set to 'true' all new funds added to custody balance will be automatically transferred to trading balance
  ›  balance number Amount of funds in given currency
  ›  client_id string API key 'client id' used to reserve/release funds in custody platform, requires scope 'custody:read_write'
  ›  currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  deposit_address string Address that can be used for deposits
  ›  external_id string User ID in external systems
  ›  name string Custody name
  ›  pending_withdrawal_addres string New withdrawal address that will be used after 'withdrawal_address_change'
  ›  pending_withdrawal_balance number Amount of funds in given currency
  ›  withdrawal_address string Address that is used for withdrawals
  ›  withdrawal_address_change number UNIX timestamp after when new withdrawal address will be used for withdrawals

/private/pme/simulate

curl -X GET "https://test.deribit.com/api/v2/private/pme/simulate?currency=BTC" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":2255,"jsonrpc":"2.0","method":"private/pme/simulate","params":{"currency":"BTC"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":2255,"jsonrpc":"2.0","method":"private/pme/simulate","params":{"currency":"BTC"}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 2255,
  "result": {
    "model_params": {
      "currency_pair": {
        "btc_usd": {
          "extended_table_factor": 1,
          "m_inc": 0.00005,
          "min_volatility_for_shock_up": 0.5,
          "max_delta_shock": 0.1,
          "delta_total_liq_shock_threshold": 20000000,
          "volatility_range_down": 0.25,
          "volatility_range_up": 0.5,
          "long_term_vega_power": 0.13,
          "short_term_vega_power": 0.3,
          "price_range": 0.16
        }
      },
      "currency": {
        "usd": {
          "max_offsetable_pnl": 0,
          "annualised_move_risk": 0.1,
          "extended_dampener": 25000,
          "min_annualised_move": 0.01,
          "haircut": 0,
          "equity_side_impact": "none",
          "pnl_offset": 0,
          "correlation_set": false
        },
        "btc": {
          "max_offsetable_pnl": 0,
          "annualised_move_risk": 0.075,
          "extended_dampener": 100000,
          "min_annualised_move": 0.01,
          "haircut": 0,
          "equity_side_impact": "both",
          "pnl_offset": 0,
          "correlation_set": false
        }
      },
      "general": {
        "mm_factor": 0.8,
        "buckets_count": 4,
        "vol_scenarios_count": 3,
        "timestamp": 1718619740501
      }
    },
    "aggregated_risk_vectors": {
      "btc_btc": {
        "standard": [
          -0.05968587238095239,
          -0.05968587238095239,
          -0.05968587238095239,
          -0.04272965863636364,
          -0.04272965863636364,
          -0.04272965863636364,
          -0.02724789826086957,
          -0.02724789826086957,
          -0.02724789826086957,
          -0.013056284583333334,
          -0.013056284583333334,
          -0.013056284583333334,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "extended": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ]
      }
    },
    "initial_risk_vectors": {
      "BTC-PERPETUAL": {
        "standard": [
          -0.05991206933333334,
          -0.05991206933333334,
          -0.05991206933333334,
          -0.04289159509090909,
          -0.04289159509090909,
          -0.04289159509090909,
          -0.027351162086956524,
          -0.027351162086956524,
          -0.027351162086956524,
          -0.013105765166666668,
          -0.013105765166666668,
          -0.013105765166666668,
          0,
          0,
          0,
          0.012097629384615385,
          0.012097629384615385,
          0.012097629384615385,
          0.023299138074074074,
          0.023299138074074074,
          0.023299138074074074,
          0.033700538999999995,
          0.033700538999999995,
          0.033700538999999995,
          0.043384601931034494,
          0.043384601931034494,
          0.043384601931034494
        ],
        "extended": [
          -0.05991206933333334,
          -0.05991206933333334,
          0.04338460193103449,
          0.04338460193103449,
          0.04338460193103449,
          0.04338460193103449,
          0.04338460193103449,
          0.04338460193103449
        ]
      },
      "BTC-28JUN24": {
        "standard": [
          0.0002261969523809524,
          0.0002261969523809524,
          0.0002261969523809524,
          0.00016193645454545456,
          0.00016193645454545456,
          0.00016193645454545456,
          0.00010326382608695652,
          0.00010326382608695652,
          0.00010326382608695652,
          0.00004948058333333334,
          0.00004948058333333334,
          0.00004948058333333334,
          0,
          0,
          0,
          -0.00004567438461538462,
          -0.00004567438461538462,
          -0.00004567438461538462,
          -0.00008796548148148148,
          -0.00008796548148148148,
          -0.00008796548148148148,
          -0.0001272357857142857,
          -0.0001272357857142857,
          -0.0001272357857142857,
          -0.00016379779310344832,
          -0.00016379779310344832,
          -0.00016379779310344832
        ],
        "extended": [
          0.0002261969523809524,
          0.0002261969523809524,
          -0.0001637977931034483,
          -0.0001637977931034483,
          -0.0001637977931034483,
          -0.0001637977931034483,
          -0.0001637977931034483,
          -0.0001637977931034483
        ]
      }
    },
    "margins": {
      "btc": {
        "initial_margin_details": {
          "risk_matrix_margin_details": {
            "delta_shock": 0,
            "roll_shock": 0.00315725898,
            "worst_case_bucket": {
              "bucket": 1,
              "side": "left",
              "source": "standard",
              "index": 1
            },
            "worst_case": 0.05968587238095239,
            "correlation_contingency": 0
          },
          "risk_matrix_margin": 0.06284313098,
          "spot_margin": 0,
          "mmp_margin": 0.06,
          "open_orders_margin": 0.000018212
        },
        "initial_margin": 0.122861343,
        "maintenance_margin": 0.050274504784
      }
    },
    "portfolio": {
      "currency": {},
      "position": {
        "BTC-PERPETUAL": 0.314538364,
        "BTC-28JUN24": -0.001187534
      }
    },
    "index_price": {
      "btc_usd": 65666.19
    },
    "ticker": {
      "BTC-PERPETUAL": {
        "mark_price": 65910.57,
        "index_price": 65666.19
      },
      "BTC-28JUN24": {
        "mark_price": 67371.75,
        "index_price": 65666.19
      }
    }
  }
}

Calculates the Extended Risk Matrix and margin information for the selected currency or against the entire Cross-Collateral portfolio.

Scope: account:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
CROSS		 The currency for which the Extended Risk Matrix will be calculated. Use CROSS for Cross Collateral simulation.
add_positions false boolean If true, adds simulated positions to current positions, otherwise uses only simulated positions. By default true
simulated_positions false object Object with positions in following form: {InstrumentName1: Position1, InstrumentName2: Position2...}, for example {"BTC-PERPETUAL": -1.0} (or corresponding URI-encoding for GET). Size in base currency.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object Simulation details

/private/remove_api_key

curl -X GET "https://test.deribit.com/api/v2/private/remove_api_key?id=2" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":8190,"jsonrpc":"2.0","method":"private/remove_api_key","params":{"id":2}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":8190,"jsonrpc":"2.0","method":"private/remove_api_key","params":{"id":2}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 8190,
  "result": "ok"
}

Removes api key. Important notes.

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
id true integer Id of key

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result string Result of method execution. ok in case of success

/private/remove_subaccount

curl -X GET "https://test.deribit.com/api/v2/private/remove_subaccount?subaccount_id=120" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":6,"jsonrpc":"2.0","method":"private/remove_subaccount","params":{"subaccount_id":120}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":6,"jsonrpc":"2.0","method":"private/remove_subaccount","params":{"subaccount_id":120}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": "ok"
}

Remove empty subaccount.

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
subaccount_id 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/reset_api_key

curl -X GET "https://test.deribit.com/api/v2/private/reset_api_key?id=3" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":6524,"jsonrpc":"2.0","method":"private/reset_api_key","params":{"id":3}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":6524,"jsonrpc":"2.0","method":"private/reset_api_key","params":{"id":3}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 6524,
  "result": {
    "timestamp": 1560238942222,
    "max_scope": "account:read block_trade:read trade:read wallet:read",
    "id": 3,
    "enabled": true,
    "default": false,
    "client_secret": "P9Z_c73KaBPwpoTVfsXzehAhjhdJn5kM7Zlz_hhDhE8",
    "client_id": "IY2D68DS",
    "name": ""
  }
}

Resets secret in api key. Important notes.

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
id true integer Id of key

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object
  ›  client_id string Client identifier used for authentication
  ›  client_secret string Client secret or MD5 fingerprint of public key used for authentication
  ›  default boolean Informs whether this api key is default (field is deprecated and will be removed in the future)
  ›  enabled boolean Informs whether api key is enabled and can be used for authentication
  ›  enabled_features array of string List of enabled advanced on-key features. Available options:
- restricted_block_trades: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key
- block_trade_approval: Block trades created using this API key require additional user approval. Methods that use block_rfq scope are not affected by Block Trade approval feature
  ›  id integer key identifier
  ›  ip_whitelist array List of IP addresses whitelisted for a selected key
  ›  max_scope string Describes maximal access for tokens generated with given key, possible values: trade:[read, read_write, none], wallet:[read, read_write, none], account:[read, read_write, none], block_trade:[read, read_write, none], block_rfq:[read, read_write, none]. If scope is not provided, its value is set as none.

Please check details described in Access scope
  ›  name string Api key name that can be displayed in transaction log
  ›  public_key string PEM encoded public key (Ed25519/RSA) used for asymmetric signatures (optional)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

/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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":5147,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":5147,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 5147,
  "result": "ok"
}

Marks an announcement as read, so it will not be shown in get_new_announcements.

Scope: account:read_write

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_disabled_trading_products

curl -X GET "https://test.deribit.com/api/v2/private/set_disabled_trading_products?trading_products=%5B%22future_combos%22%2C%22option_combos%22%2C%22spots%22%5D&user_id=1" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"jsonrpc":"2.0","method":"private/set_disabled_trading_products","params":{"trading_products":["future_combos","option_combos","spots"],"user_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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"jsonrpc":"2.0","method":"private/set_disabled_trading_products","params":{"trading_products":["future_combos","option_combos","spots"],"user_id":1}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "result": "ok"
}

Configure disabled trading products for subaccounts. Only main accounts can modify this for subaccounts.

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
user_id true integer Id of a (sub)account
trading_products true array List of available trading products. Available products: perpetual, futures, options, future_combos, option_combos, spots

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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1667,"jsonrpc":"2.0","method":"private/set_email_for_subaccount","params":{"email":"[email protected]","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1667,"jsonrpc":"2.0","method":"private/set_email_for_subaccount","params":{"email":"[email protected]","sid":7}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
    "jsonrpc": "2.0",
    "id": 1667,
    "result": "ok"
}

Assign an email address to a subaccount. User will receive an email with a confirmation link.

Scope: account:read_write

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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":3269,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":3269,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "id": 3269,
  "result": "ok"
}

Changes the language to be used for emails.

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
language true string The abbreviated language name. Valid values include "en", "ko", "zh", "ja", "ru"

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_self_trading_config

curl -X GET "https://test.deribit.com/api/v2/private/set_self_trading_config?block_rfq_self_match_prevention=true&extended_to_subaccounts=true&mode=cancel_maker" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":1,"jsonrpc":"2.0","method":"private/set_self_trading_config","params":{"block_rfq_self_match_prevention":true,"extended_to_subaccounts":true,"mode":"cancel_maker"}};
var ws = new WebSocket('wss://test.deribit.com/ws/api/v2');
ws.onmessage = function (e) {
    // do something with the response...
    console.log('received from server : ', e.data);
};
ws.onopen = function () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":1,"jsonrpc":"2.0","method":"private/set_self_trading_config","params":{"block_rfq_self_match_prevention":True,"extended_to_subaccounts":true,"mode":"cancel_maker"}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
  "jsonrpc": "2.0",
  "result": "ok"
}

Configure self trading behavior

Scope: account:read_write

Try in API console

Parameters

Parameter Required Type Enum Description
mode true string reject_taker
cancel_maker		 Self trading prevention behavior: reject_taker (reject the incoming order), cancel_maker (cancel the matched order in the book)
extended_to_subaccounts true boolean If value is true trading is prevented between subaccounts of given account, otherwise they are treated separately
block_rfq_self_match_prevention false boolean When Block RFQ Self Match Prevention is enabled, it ensures that RFQs cannot be executed between accounts that belong to the same legal entity. This setting is independent of the general self-match prevention settings and must be configured separately.

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/simulate_portfolio

curl -X GET "https://test.deribit.com/api/v2/private/simulate_portfolio?add_positions=true&currency=BTC&simulated_positions=%7B%22BTC-PERPETUAL%22%3A1.0%7D" \
-H "Authorization: Bearer 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":22222,"jsonrpc":"2.0","method":"private/simulate_portfolio","params":{"add_positions":true,"currency":"BTC","simulated_positions":{"BTC-PERPETUAL":1.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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":22222,"jsonrpc":"2.0","method":"private/simulate_portfolio","params":{"add_positions":True,"currency":"BTC","simulated_positions":{"BTC-PERPETUAL":1.0}}}

async def call_api(msg):
   async with websockets.connect('wss://test.deribit.com/ws/api/v2') as websocket:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
      "projected_initial_margin": 37662472.03416069,
      "initial_margin": 37662472.03416069,
      "total_pl": 40419.10179263,
      "additional_reserve": 0,
      "available_withdrawal_funds": 115871741.76065847,
      "options_pl": 921.55562578,
      "delta_total_map": {
        "btc_usd": 68024.519462366
      },
      "available_subaccount_transfer_funds": 0,
      "projected_delta_total": 69080.932029,
      "projected_maintenance_margin": 30129215.84817124,
      "total_equity_usd": 13075634611389.318,
      "options_gamma": -0.03907,
      "currency": "BTC",
      "options_theta": 142583.29246,
      "spot_reserve": 0,
      "total_initial_margin_usd": 3139528603778.822,
      "options_vega": -39322.23046,
      "margin_balance": 153534213.79481918,
      "futures_session_rpl": 1.309136,
      "options_gamma_map": {
        "btc_usd": -0.03907
      },
      "available_funds": 115871741.76065847,
      "futures_pl": 39497.54616685,
      "cross_collateral_enabled": true,
      "delta_total": 69080.932029,
      "options_session_rpl": 0,
      "total_margin_balance_usd": 12798550648250.61,
      "options_value": -1056.41256672,
      "options_session_upl": -174.67960675,
      "maintenance_margin": 30129215.84817124,
      "total_maintenance_margin_usd": 2511559381417.215,
      "options_vega_map": {
        "btc_usd": -39322.23046
      },
      "session_rpl": 1.309136,
      "locked_balance": 0,
      "session_upl": -339.16214185,
      "margin_model": "cross_pm",
      "portfolio_margining_enabled": true,
      "equity": 150075253.91354558,
      "balance": 150076473.4995114,
      "total_delta_total_usd": 6157454218.3753195,
      "fee_balance": 0,
      "options_delta": 2883.38481,
      "options_theta_map": {
        "btc_usd": 142583.29246
      },
      "futures_session_upl": -164.48253509
    },
    "usIn": 1742210019774525,
    "usOut": 1742210019788175,
    "usDiff": 13650,
    "testnet": true
  }

Calculates portfolio margin info for simulated position or current position of the user. This request has a special restricted rate limit (not more than once per a second).

Scope: account:read

Try in API console

Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR		 The currency symbol
add_positions false boolean If true, adds simulated positions to current positions, otherwise uses only simulated positions. By default true
simulated_positions false object Object with positions in following form: {InstrumentName1: Position1, InstrumentName2: Position2...}, for example {"BTC-PERPETUAL": -1000.0} (or corresponding URI-encoding for GET). For futures in USD, for options in base currency.

Response

Name Type Description
id integer The id that was sent in the request
jsonrpc string The JSON-RPC version (2.0)
result object Portfolio details

/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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":9995,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":9995,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
    "jsonrpc": "2.0",
    "id": 9995,
    "result": "ok"
}

Enable or disable sending of notifications for the subaccount.

Scope: account:read_write

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 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP" \
-H "Content-Type: application/json"

var msg = 
{"id":938,"jsonrpc":"2.0","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 () {
    // ------------------- 
    // Before sending message, make sure that your connection
    // is authenticated (use public/auth call before) 
    // ------------------- 
    ws.send(JSON.stringify(msg));
};

import asyncio
import websockets
import json

msg = \
{"id":938,"jsonrpc":"2.0","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:
       ###############
       # Before sending message, make sure that your connection
       # is authenticated (use public/auth call before) 
       ###############
       await websocket.send(msg)
       while websocket.open:
           response = await websocket.recv()
           # do something with the response...
           print(response)

asyncio.get_event_loop().run_until_complete(call_api(json.dumps(msg)))

The above command returns JSON structured like this (real example):

{
    "jsonrpc": "2.0",
    "id": 938,
    "result": "ok"
}

Enable or disable login for a subaccount. If login is disabled and a session for the subaccount exists, this session will be terminated.

Scope: account:read_write

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

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
  ›  label string The same label as given when subscribing to notifications (present only when provided in private/subscribe; only for private channels)
  ›  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": "public/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": "public/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": {
            "action": "new",
            "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
            "id": 1532593832021,
            "important": true,
            "publication_timestamp": 1532593832021,
            "title": "Example announcement"
        }
    }
}

General announcements concerning the Deribit platform.

Try in API console

Channel Parameters

This channel takes no parameters

Response

Name Type Description
data object
  ›  action string Action taken by the platform administrators. Published a new announcement, or deleted the old one
  ›  body string HTML-formatted announcement body
  ›  confirmation boolean Whether the user confirmation is required for this announcement
  ›  id integer Announcement's identifier
  ›  important boolean Whether the announcement is marked as important
  ›  publication_timestamp integer The timestamp (milliseconds since the Unix epoch) of announcement publication
  ›  title string Announcement's title
  ›  unread integer The number of previous unread announcements (optional, only for authorized users).

block_rfq.maker.quotes.{currency}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["block_rfq.maker.quotes.any"]}
    };
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": ["block_rfq.maker.quotes.any"]}
    }

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":"block_rfq.maker.quotes.any","data":[{"amount":25,"block_rfq_id":724,"block_rfq_quote_id":1301,"creation_timestamp":1731665928291,"direction":"buy","filled_amount":0,"label":"example_quote","last_update_timestamp":1731665928291,"legs":[{"direction":"buy","instrument_name":"BTC-16NOV24-82000-C","price":10,"ratio":1}],"price":10,"quote_state":"open","replaced":false}]}}

Get notification about state of your Block RFQ quotes

Try in API console

Channel Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all

Response

Name Type Description
data array of object
  ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  app_name string The name of the application that placed the quote on behalf of the user (optional).
  ›  block_rfq_id integer ID of the Block RFQ
  ›  block_rfq_quote_id integer ID of the Block RFQ quote
  ›  creation_timestamp integer The timestamp when quote was created (milliseconds since the Unix epoch)
  ›  direction string Direction of trade from the maker perspective
  ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›  filled_amount number Filled amount of the quote. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.
  ›  hedge object
  ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a hedge leg
  ›  label string User defined label for the quote (maximum 64 characters)
  ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›  legs array of object
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a leg
  ›    ›  ratio integer Ratio of amount between legs
  ›  price number Price of a quote
  ›  quote_state string State of the quote
  ›  quote_state_reason string Reason of quote cancellation
  ›  replaced boolean true if the quote was edited, otherwise false.

block_rfq.maker.{currency}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["block_rfq.maker.btc"]}
    };
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": ["block_rfq.maker.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 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":"block_rfq.maker.btc","data":{"amount":25,"block_rfq_id":722,"combo_id":"BTC-18NOV24-82000-C","creation_timestamp":1731664676443,"expiration_timestamp":1731664976443,"legs":[{"direction":"buy","instrument_name":"BTC-18NOV24-82000-C","ratio":1}],"role":"maker","state":"open","taker_rating":"1-2"}}}

Get notification when new Block RFQ is created

Try in API console

Channel Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all

Response

Name Type Description
data object
  ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  app_name string The name of the application that created the Block RFQ on behalf of the user (optional, visible only to taker).
  ›  asks array of object
  ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›    ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›    ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›    ›  makers array of string Maker of the quote
  ›    ›  price number Price of a quote
  ›  bids array of object
  ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›    ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›    ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›    ›  makers array of string Maker of the quote
  ›    ›  price number Price of a quote
  ›  block_rfq_id integer ID of the Block RFQ
  ›  combo_id string Unique combo identifier
  ›  creation_timestamp integer The timestamp when Block RFQ was created (milliseconds since the Unix epoch)
  ›  disclosed boolean Indicates whether the RFQ was created as non-anonymous, meaning taker and maker aliases are visible to counterparties.
  ›  expiration_timestamp integer The timestamp when the Block RFQ will expire (milliseconds since the UNIX epoch)
  ›  hedge object
  ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a hedge leg
  ›  included_in_taker_rating boolean Indicates whether the RFQ is included in the taker's rating calculation. Present only for closed RFQs created by the requesting taker.
  ›  index_prices array of number A list of index prices for the underlying instrument(s) at the time of trade execution.
  ›  label string User defined label for the Block RFQ (maximum 64 characters)
  ›  legs array of object
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  ratio integer Ratio of amount between legs
  ›  makers array of string List of targeted Block RFQ makers
  ›  mark_price number The mark price for the instrument
  ›  min_trade_amount number Minimum amount for trading
  ›  role string Role of the user in Block RFQ
  ›  state string State of the Block RFQ
  ›  taker_rating string Rating of the taker
  ›  trade_trigger object Contains information about the trade trigger state
  ›    ›  cancel_reason string Reason for cancellation, present only when state is cancelled
  ›    ›  direction string Direction of the trade trigger
  ›    ›  price number Price of the trade trigger
  ›    ›  state string Trade trigger state: "untriggered" or "cancelled"
  ›  trades array of object
  ›    ›  amount number Trade amount. For options, linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  hedge_amount number Amount of the hedge leg. For linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›  maker string Alias of the maker (optional)
  ›    ›  price number Price in base currency

block_rfq.taker.{currency}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["block_rfq.taker.btc"]}
    };
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": ["block_rfq.taker.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 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":"block_rfq.taker.btc","data":{"amount":10000,"asks":[],"bids":[{"amount":10000,"execution_instruction":"any_part_of","last_update_timestamp":1740047910507,"makers":["ANONYMOUS"],"price":291664.14}],"block_rfq_id":321,"combo_id":null,"creation_timestamp":1740047910438,"disclosed":false,"expiration_timestamp":1740048210438,"label":"example","legs":[{"direction":"buy","instrument_name":"BTC-21FEB25","ratio":1},{"direction":"buy","instrument_name":"BTC-28FEB25","ratio":1},{"direction":"buy","instrument_name":"BTC-PERPETUAL","ratio":1}],"makers":["MAKER1","MAKER2"],"min_trade_amount":10,"role":"taker","state":"open","taker_rating":"1-2"}}}

Get notification about state of your Block RFQ. trades are only visible if the Block RFQ was filled. Please note that after Block RFQ creation, a grace period of 5 seconds begins, during which the taker cannot see quotes or trade the Block RFQ.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all

Response

Name Type Description
data object
  ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  app_name string The name of the application that created the Block RFQ on behalf of the user (optional, visible only to taker).
  ›  asks array of object
  ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›    ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›    ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›    ›  makers array of string Maker of the quote
  ›    ›  price number Price of a quote
  ›  bids array of object
  ›    ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›    ›  execution_instruction string

Execution instruction of the quote. Default - any_part_of

  • "all_or_none (AON)" - The quote can only be filled entirely or not at all, ensuring that its amount matches the amount specified in the Block RFQ. Additionally, 'all_or_none' quotes have priority over 'any_part_of' quotes at the same price level.
  • "any_part_of (APO)" - The quote can be filled either partially or fully, with the filled amount potentially being less than the Block RFQ amount.
  ›    ›  expires_at integer The timestamp when the quote expires (milliseconds since the Unix epoch), equal to the earliest expiry of placed quotes
  ›    ›  last_update_timestamp integer Timestamp of the last update of the quote (milliseconds since the UNIX epoch)
  ›    ›  makers array of string Maker of the quote
  ›    ›  price number Price of a quote
  ›  block_rfq_id integer ID of the Block RFQ
  ›  combo_id string Unique combo identifier
  ›  creation_timestamp integer The timestamp when Block RFQ was created (milliseconds since the Unix epoch)
  ›  disclosed boolean Indicates whether the RFQ was created as non-anonymous, meaning taker and maker aliases are visible to counterparties.
  ›  expiration_timestamp integer The timestamp when the Block RFQ will expire (milliseconds since the UNIX epoch)
  ›  hedge object
  ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a hedge leg
  ›  included_in_taker_rating boolean Indicates whether the RFQ is included in the taker's rating calculation. Present only for closed RFQs created by the requesting taker.
  ›  index_prices array of number A list of index prices for the underlying instrument(s) at the time of trade execution.
  ›  label string User defined label for the Block RFQ (maximum 64 characters)
  ›  legs array of object
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  ratio integer Ratio of amount between legs
  ›  makers array of string List of targeted Block RFQ makers
  ›  mark_price number The mark price for the instrument
  ›  min_trade_amount number Minimum amount for trading
  ›  role string Role of the user in Block RFQ
  ›  state string State of the Block RFQ
  ›  taker_rating string Rating of the taker
  ›  trade_trigger object Contains information about the trade trigger state
  ›    ›  cancel_reason string Reason for cancellation, present only when state is cancelled
  ›    ›  direction string Direction of the trade trigger
  ›    ›  price number Price of the trade trigger
  ›    ›  state string Trade trigger state: "untriggered" or "cancelled"
  ›  trades array of object
  ›    ›  amount number Trade amount. For options, linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  hedge_amount number Amount of the hedge leg. For linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›  maker string Alias of the maker (optional)
  ›    ›  price number Price in base currency

block_rfq.trades.{currency}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["block_rfq.trades.any"]}
    };
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": ["block_rfq.trades.any"]}
    }

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":"block_rfq.trades.any","data":{"amount":50,"combo_id":"BTC-PERPETUAL","direction":"sell","id":939,"legs":[{"direction":"buy","instrument_name":"BTC-PERPETUAL","price":95318.72,"ratio":1}],"mark_price":95318.72,"timestamp":1739869829823,"trades":[{"amount":50,"direction":"sell","price":95318.72}]}}}

Get notification about recent Block RFQ trades

Try in API console

Channel Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all

Response

Name Type Description
data array of object
  ›  amount number This value multiplied by the ratio of a leg gives trade size on that leg.
  ›  combo_id string Unique combo identifier
  ›  direction string Direction: buy, or sell
  ›  hedge object
  ›    ›  amount integer It represents the requested hedge leg size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a hedge leg
  ›  id integer ID of the Block RFQ
  ›  legs array of object
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price for a leg
  ›    ›  ratio integer Ratio of amount between legs
  ›  mark_price number Mark Price at the moment of trade
  ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›  trades array of object
  ›    ›  amount number Trade amount. For options, linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  hedge_amount number Amount of the hedge leg. For linear futures, linear perpetuals and spots the amount is denominated in the underlying base currency coin. The inverse perpetuals and inverse futures are denominated in USD units.
  ›    ›  price number Price in base currency

block_trade_confirmations

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["block_trade_confirmations"]}
    };
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": ["block_trade_confirmations"]}
    }

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":"block_trade_confirmations","data":{"nonce":"bt-jdqv98","role":"maker","state":{"timestamp":1711468632693,"value":"rejected"},"timestamp":1711468468131,"trades":[{"amount":10,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":70246.66}],"user_id":7}}}

Provides notifications regarding block trade approval

Try in API console

Channel Parameters

This channel takes no parameters

Response

Name Type Description
data object
  ›  app_name string The name of the application that executed the block trade on behalf of the user (optional).
  ›  broker_code string Broker code associated with the broker block trade.
  ›  broker_name string Name of the broker associated with the block trade.
  ›  combo_id string Combo instrument identifier
  ›  counterparty_state object State of the pending block trade for the other party (optional).
  ›    ›  timestamp integer State timestamp.
  ›    ›  value string State value.
  ›  nonce string Nonce that can be used to approve or reject pending block trade.
  ›  role string Trade role of the user: maker or taker
  ›  state object State of the pending block trade for current user.
  ›    ›  timestamp integer State timestamp.
  ›    ›  value string State value.
  ›  timestamp integer Timestamp that can be used to approve or reject pending block trade.
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price in base currency
  ›  user_id integer Unique user identifier
  ›  username string Username of the user who initiated the block trade.

block_trade_confirmations.{currency}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["block_trade_confirmations.btc"]}
    };
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": ["block_trade_confirmations.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 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":"block_trade_confirmations.btc","data":{"nonce":"bt-jdqv98","role":"maker","state":{"timestamp":1711468632693,"value":"rejected"},"timestamp":1711468468131,"trades":[{"amount":10,"direction":"buy","instrument_name":"BTC-PERPETUAL","price":70246.66}],"user_id":7}}}

Provides notifications regarding block trade approval. Supports filtering by currency.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all

Response

Name Type Description
data object
  ›  app_name string The name of the application that executed the block trade on behalf of the user (optional).
  ›  broker_code string Broker code associated with the broker block trade.
  ›  broker_name string Name of the broker associated with the block trade.
  ›  combo_id string Combo instrument identifier
  ›  counterparty_state object State of the pending block trade for the other party (optional).
  ›    ›  timestamp integer State timestamp.
  ›    ›  value string State value.
  ›  nonce string Nonce that can be used to approve or reject pending block trade.
  ›  role string Trade role of the user: maker or taker
  ›  state object State of the pending block trade for current user.
  ›    ›  timestamp integer State timestamp.
  ›    ›  value string State value.
  ›  timestamp integer Timestamp that can be used to approve or reject pending block trade.
  ›  trades array of object
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  direction string Direction: buy, or sell
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  price number Price in base currency
  ›  user_id integer Unique user identifier
  ›  username string Username of the user who initiated the block trade.

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.100.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.100.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 next notifications like this:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"book.ETH-PERPETUAL.100.1.100ms","data":{"asks":[[161,20]],"bids":[[160,40]],"change_id":109615,"instrument_name":"ETH-PERPETUAL","timestamp":1554375447971}}}

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 subscription).

amount indicates the amount of all orders at price level. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.

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
25
100
250		 Group prices (by rounding). Use none for no grouping.
For ETH cryptocurrency, real group is divided by 100.0, e.g. given value 5 means using 0.05

Allowed values for BTC - none, 1, 2, 5, 10
Allowed values for ETH - none, 5, 10, 25, 100, 250
depth true integer 1
10
20		 Number of price levels to be included.
interval true string 100ms
agg2		 Frequency of notifications. Events will be aggregated over this interval.

Response

Name Type Description
data object
  ›  asks array of [price, amount] List of asks
  ›  bids array of [price, amount] List of bids
  ›  change_id integer id of the notification
  ›  instrument_name string Unique instrument identifier
  ›  timestamp integer The timestamp of last change (milliseconds since the Unix epoch)

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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"book.BTC-PERPETUAL.100ms","data":{"asks":[["new",5042.64,40],["new",5043.3,40]],"bids":[["new",5042.34,30],["new",5041.94,20]],"change_id":297217,"instrument_name":"BTC-PERPETUAL","timestamp":1554373962454,"type":"snapshot"}}}

This subscription will send next notifications like this:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"book.BTC-PERPETUAL.100ms","data":{"asks":[],"bids":[["delete",5041.94,0],["delete",5042.34,0]],"change_id":297218,"instrument_name":"BTC-PERPETUAL","prev_change_id":297217,"timestamp":1554373911330,"type":"change"}}}

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
agg2		 Frequency of notifications. Events will be aggregated over this interval.

Response

Name Type Description
data object
  ›  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 Identifier of the notification
  ›  instrument_name string Unique instrument identifier
  ›  prev_change_id integer Identifier of the previous notification (it's not included for the first notification)
  ›  timestamp integer The timestamp of last change (milliseconds since the Unix epoch)
  ›  type string Type of notification: snapshot for initial, change for others

chart.trades.{instrument_name}.{resolution}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["chart.trades.BTC-PERPETUAL.1"]}
    };
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": ["chart.trades.BTC-PERPETUAL.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 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":"chart.trades.BTC-PERPETUAL.1","data":{"close":8791.25,"cost":460,"high":8870.31,"low":8788.25,"open":8869.79,"tick":1573645080000,"volume":0.05219351}}}

Publicly available market data used to generate a TradingView candle chart. During a single resolution period, many events can be sent, each with updated values for the recent period.

NOTICE When there is no trade during the requested resolution period (e.g. 1 minute), then a filling sample is generated which uses data from the last available trade candle (open and close values).

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
resolution true string 1
3
5
10
15
30
60
120
180
360
720
1D		 Chart bars resolution given in full minutes or keyword 1D (only some specific resolutions are supported)

Response

Name Type Description
data object
  ›  close number The close price for the candle
  ›  cost number Cost data for the candle
  ›  high number The highest price level for the candle
  ›  low number The lowest price level for the candle
  ›  open number The open price for the candle'
  ›  tick integer The timestamp (milliseconds since the Unix epoch)
  ›  volume number Volume data for the candle

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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"deribit_price_index.btc_usd","data":{"index_name":"btc_usd","price":3937.89,"timestamp":1550588002899}}}

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
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
btc_usdc
btcdvol_usdc
buidl_usdc
doge_usdc
dot_usdc
eurr_usdc
eth_usdc
ethdvol_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
steth_usdc
ton_usdc
trump_usdc
trx_usdc
uni_usdc
usde_usdc
usyc_usdc
xrp_usdc
btc_usdt
eth_usdt
eurr_usdt
sol_usdt
steth_usdt
usdc_usdt
usde_usdt
btc_eurr
btc_usde
btc_usyc
eth_btc
eth_eurr
eth_usde
eth_usyc
steth_eth
paxg_btc		 Index identifier, matches (base) cryptocurrency with quote currency

Response

Name Type Description
data object
  ›  index_name string Index identifier, matches (base) cryptocurrency with quote currency
  ›  price number Current index price
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"deribit_price_ranking.btc_usd","data":[{"enabled":true,"identifier":"bitfinex","original_price":41160.5,"price":41160.5,"timestamp":1702465142997,"weight":14.285714},{"enabled":true,"identifier":"bitstamp","original_price":41119,"price":41119,"timestamp":1702465143045,"weight":14.285714},{"enabled":true,"identifier":"coinbase","original_price":41115.53,"price":41115.53,"timestamp":1702465139000,"weight":14.285714},{"enabled":true,"identifier":"gemini","original_price":41116.42,"price":41116.42,"timestamp":1702465142921,"weight":14.285714},{"enabled":true,"identifier":"itbit","original_price":41108.88,"price":41108.88,"timestamp":1702465141954,"weight":14.285714},{"enabled":true,"identifier":"kraken","original_price":41108.35,"price":41108.35,"timestamp":1702465142906,"weight":14.285714},{"enabled":true,"identifier":"okcoin","original_price":41139.82,"price":41139.82,"timestamp":1702465138000,"weight":14.285714}]}}

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
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
btc_usdc
btcdvol_usdc
buidl_usdc
doge_usdc
dot_usdc
eurr_usdc
eth_usdc
ethdvol_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
steth_usdc
ton_usdc
trump_usdc
trx_usdc
uni_usdc
usde_usdc
usyc_usdc
xrp_usdc
btc_usdt
eth_usdt
eurr_usdt
sol_usdt
steth_usdt
usdc_usdt
usde_usdt
btc_eurr
btc_usde
btc_usyc
eth_btc
eth_eurr
eth_usde
eth_usyc
steth_eth
paxg_btc		 Index identifier, matches (base) cryptocurrency with quote currency

Response

Name Type Description
data array of object
  ›  enabled boolean Stock exchange status
  ›  identifier string Stock exchange identifier
  ›  original_price number Index price retrieved from stock's data
  ›  price number Adjusted stock exchange index price, used for Deribit price index calculations
  ›  timestamp integer The timestamp of the last update from stock exchange (milliseconds since the UNIX epoch)
  ›  weight number The weight of the ranking given in percent

deribit_price_statistics.{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_statistics.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_statistics.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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"deribit_price_statistics.btc_usd","data":{"change24h":1009.61,"high24h":59311.42,"high_volatility":false,"index_name":"btc_usd","low24h":58012.08}}}

This subscription provides basic statistics about Deribit Index

Try in API console

Channel Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
btc_usdc
btcdvol_usdc
buidl_usdc
doge_usdc
dot_usdc
eurr_usdc
eth_usdc
ethdvol_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
steth_usdc
ton_usdc
trump_usdc
trx_usdc
uni_usdc
usde_usdc
usyc_usdc
xrp_usdc
btc_usdt
eth_usdt
eurr_usdt
sol_usdt
steth_usdt
usdc_usdt
usde_usdt
btc_eurr
btc_usde
btc_usyc
eth_btc
eth_eurr
eth_usde
eth_usyc
steth_eth
paxg_btc		 Index identifier, matches (base) cryptocurrency with quote currency

Response

Name Type Description
data object
  ›  change24h number The price index change calculated between the first and last point within most recent 24 hours window
  ›  high24h number The highest recorded price within the last 24 hours
  ›  high_volatility boolean Indicates the high volatility periods on the market. The value true is set when the price index value drastically changed within the last 5 minutes
  ›  index_name string Index identifier, matches (base) cryptocurrency with quote currency
  ›  low24h number The lowest recorded price within the last 24 hours

deribit_volatility_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_volatility_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_volatility_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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"deribit_volatility_index.btc_usd","data":{"index_name":"btc_usd","timestamp":1619777946007,"volatility":129.36}}}

Provides volatility index subscription

Try in API console

Channel Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd		 Index identifier supported for DVOL

Response

Name Type Description
data object
  ›  index_name string Index identifier supported for DVOL
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  volatility number Value of the corresponding volatility

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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"estimated_expiration_price.btc_usd","data":{"is_estimated":false,"price":3939.73,"seconds":180929}}}

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
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
btc_usdc
btcdvol_usdc
buidl_usdc
doge_usdc
dot_usdc
eurr_usdc
eth_usdc
ethdvol_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
steth_usdc
ton_usdc
trump_usdc
trx_usdc
uni_usdc
usde_usdc
usyc_usdc
xrp_usdc
btc_usdt
eth_usdt
eurr_usdt
sol_usdt
steth_usdt
usdc_usdt
usde_usdt
btc_eurr
btc_usde
btc_usyc
eth_btc
eth_eurr
eth_usde
eth_usyc
steth_eth
paxg_btc		 Index identifier, matches (base) cryptocurrency with quote currency

Response

Name Type Description
data object
  ›  is_estimated boolean When true then price is given as an estimated value, otherwise it's current index price
  ›  left_ticks number number of time ticks that are left until expiration (field added when price is estimated)
  ›  price number Index current or estimated price
  ›  seconds integer Number of seconds till finalizing the nearest instrument
  ›  total_ticks number number of total time ticks (field added when price is estimated)

incremental_ticker.{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": ["incremental_ticker.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": ["incremental_ticker.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 first notification like this:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"incremental_ticker.BTC-PERPETUAL","data":{"best_ask_amount":100,"best_ask_price":36443,"best_bid_amount":5000,"best_bid_price":36442.5,"current_funding":0,"estimated_delivery_price":36441.64,"funding_8h":2.11e-5,"index_price":36441.64,"instrument_name":"BTC-PERPETUAL","last_price":36457.5,"mark_price":36446.51,"max_price":36991.72,"min_price":35898.37,"open_interest":502097590,"settlement_price":36169.49,"state":"open","stats":{"high":36824.5,"low":35213.5,"price_change":0.7229,"volume":7871.02139035,"volume_usd":284061480},"timestamp":1623060194301,"type":"snapshot"}}}

This subscription will send next notifications like this:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"incremental_ticker.BTC-PERPETUAL","data":{"best_ask_amount":120,"best_bid_amount":300,"best_bid_price":36452.5,"funding_8h":3.11e-5,"index_price":36442.64,"instrument_name":"BTC-PERPETUAL","mark_price":36448.61,"stats":{"volume":7872.02139035,"volume_usd":284073480},"timestamp":1623060199024,"type":"change"}}}

Notifies about changes in instrument ticker (key information about the instrument).

The first notification will contain the whole ticker. After that there will only be information about changes in the ticker.

This event is sent at most once per second.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

Name Type Description
data object
  ›  ask_iv number (Only for option) implied volatility for best ask
  ›  best_ask_amount number It represents the requested order size of all best asks
  ›  best_ask_price number The current best ask price, null if there aren't any asks
  ›  best_bid_amount number It represents the requested order size of all best bids
  ›  best_bid_price number The current best bid price, null if there aren't any bids
  ›  bid_iv number (Only for option) implied volatility for best bid
  ›  current_funding number Current funding (perpetual only)
  ›  delivery_price number The settlement price for the instrument. Only when state = closed
  ›  estimated_delivery_price number Estimated delivery price for the market. For more details, see Contract Specification > General Documentation > Expiration Price
  ›  funding_8h number Funding 8h (perpetual only)
  ›  greeks object Only for options
  ›    ›  delta number (Only for option) The delta value for the option
  ›    ›  gamma number (Only for option) The gamma value for the option
  ›    ›  rho number (Only for option) The rho value for the option
  ›    ›  theta number (Only for option) The theta value for the option
  ›    ›  vega number (Only for option) The vega value for the option
  ›  index_price number Current index price
  ›  instrument_name string Unique instrument identifier
  ›  interest_rate number Interest rate used in implied volatility calculations (options only)
  ›  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 inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  settlement_price number Optional (not added for spot). The settlement price for the instrument. Only when state = open
  ›  state string The state of the order book. Possible values are open and closed.
  ›  stats object
  ›    ›  high number Highest price during 24h
  ›    ›  low number Lowest price during 24h
  ›    ›  price_change number 24-hour price change expressed as a percentage, null if there weren't any trades
  ›    ›  volume number Volume during last 24h in base currency
  ›    ›  volume_usd number Volume in usd (futures only)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  type string Type of notification: snapshot for initial, change for others.
  ›  underlying_index number Name of the underlying future, or index_price (options only)
  ›  underlying_price number Underlying price for implied volatility calculations (options only)

instrument.state.{kind}.{currency}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["instrument.state.any.any"]}
    };
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": ["instrument.state.any.any"]}
    }

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":"instrument.state.any.any","data":{"instrument_name":"BTC-22MAR19","state":"created","timestamp":1553080940000}}}

Get notifications about new or terminated instruments of given kind in given currency. (Please note that our system does not send notifications when currencies are locked. Users are advised to subscribe to the platform_state channel to monitor the state of currencies actively.)

Try in API console

Channel Parameters

Parameter Required Type Enum Description
kind true string future
option
spot
future_combo
option_combo
any		 Instrument kind or "any" for all
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all

Response

Name Type Description
data object
  ›  instrument_name string Unique instrument identifier
  ›  state string State of instrument - possible values: created, started, settled, closed, deactivated, terminated
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"markprice.options.btc_usd","data":[{"instrument_name":"BTC-2JUN21-37000-P","iv":0.9,"mark_price":0.0333,"timestamp":1622470378005},{"instrument_name":"BTC-4JUN21-40500-P","iv":0.9,"mark_price":0.117,"timestamp":1622470378005},{"instrument_name":"BTC-4JUN21-38250-C","iv":0.9,"mark_price":0.0177,"timestamp":1622470378005},{"instrument_name":"BTC-1JUN21-37000-C","iv":0.9,"mark_price":0.0098,"timestamp":1622470378005},{"instrument_name":"BTC-4JUN21-36500-P","iv":0.9,"mark_price":0.0371,"timestamp":1622470378005}]}}

Provides information about options markprices.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
btc_usdc
btcdvol_usdc
buidl_usdc
doge_usdc
dot_usdc
eurr_usdc
eth_usdc
ethdvol_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
steth_usdc
ton_usdc
trump_usdc
trx_usdc
uni_usdc
usde_usdc
usyc_usdc
xrp_usdc
btc_usdt
eth_usdt
eurr_usdt
sol_usdt
steth_usdt
usdc_usdt
usde_usdt
btc_eurr
btc_usde
btc_usyc
eth_btc
eth_eurr
eth_usde
eth_usyc
steth_eth
paxg_btc		 Index identifier, matches (base) cryptocurrency with quote currency

Response

Name Type Description
data 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
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"perpetual.BTC-PERPETUAL.raw","data":{"index_price":7872.88,"interest":0.004999511380756577,"timestamp":1571386349530}}}

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 agg2
100ms
raw		 Frequency of notifications. Events will be aggregated over this interval. The value raw means no aggregation will be applied (Please note that raw interval is only available to authorized users)

Response

Name Type Description
data object
  ›  index_price number Current index price
  ›  interest number Current interest
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

platform_state

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["platform_state"]}
    };
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": ["platform_state"]}
    }

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":"platform_state","data":{"locked":true,"price_index":"sol_usdc"}}}

Information about platform state.

Try in API console

Channel Parameters

This channel takes no parameters

Response

Name Type Description
data object
  ›  locked boolean Value is set to 'true' when index is locked on platform, sent only with price_index field
  ›  maintenance boolean Value is set to true when the maintenance break begins
  ›  price_index string Name of index that is locked or unlocked, sent only with locked field

platform_state.public_methods_state

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["platform_state.public_methods_state"]}
    };
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": ["platform_state.public_methods_state"]}
    }

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":"platform_state.public_methods_state","data":{"allow_unauthenticated_public_requests":true}}}

Information whether unauthorized public requests are allowed

Try in API console

Channel Parameters

This channel takes no parameters

Response

Name Type Description
data object
  ›  allow_unauthenticated_public_requests boolean Value is set to 'true' when unauthorized public requests are allowed

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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"quote.BTC-PERPETUAL","data":{"best_ask_amount":50,"best_ask_price":3996.61,"best_bid_amount":40,"best_bid_price":3914.97,"instrument_name":"BTC-PERPETUAL","timestamp":1550658624149}}}

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
data object
  ›  best_ask_amount number It represents the requested order size of all best asks
  ›  best_ask_price number The current best ask price, null if there aren't any asks
  ›  best_bid_amount number It represents the requested order size of all best bids
  ›  best_bid_price number The current best bid price, null if there aren't any bids
  ›  instrument_name string Unique instrument identifier
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

rfq.{currency}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["rfq.btc"]}
    };
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": ["rfq.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 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":"rfq.btc","data":{"amount":null,"instrument_name":"BTC-PERPETUAL","last_rfq_tstamp":1634816143836,"side":null,"state":true}}}

Get notifications about RFQs for instruments in given currency.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all

Response

Name Type Description
data object
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  instrument_name string Unique instrument identifier
  ›  is_new_instrument boolean true for newly created instruments (optional)
  ›  last_rfq_timestamp integer The timestamp of last RFQ (milliseconds since the Unix epoch)
  ›  side string Side - buy or sell
  ›  state boolean true when RFQ is active, false when inactive

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,
     "params": {
        "channels": ["ticker.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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"ticker.BTC-PERPETUAL.raw","data":{"best_ask_amount":100,"best_ask_price":36443,"best_bid_amount":5000,"best_bid_price":36442.5,"current_funding":0,"estimated_delivery_price":36441.64,"funding_8h":2.11e-5,"index_price":36441.64,"instrument_name":"BTC-PERPETUAL","interest_value":1.7362511643080387,"last_price":36457.5,"mark_price":36446.51,"max_price":36991.72,"min_price":35898.37,"open_interest":502097590,"settlement_price":36169.49,"state":"open","stats":{"high":36824.5,"low":35213.5,"price_change":0.7229,"volume":7871.02139035,"volume_usd":284061480},"timestamp":1623060194301}}}

Key information about the instrument

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
interval true string agg2
100ms
raw		 Frequency of notifications. Events will be aggregated over this interval. The value raw means no aggregation will be applied (Please note that raw interval is only available to authorized users)

Response

Name Type Description
data object
  ›  ask_iv number (Only for option) implied volatility for best ask
  ›  best_ask_amount number It represents the requested order size of all best asks
  ›  best_ask_price number The current best ask price, null if there aren't any asks
  ›  best_bid_amount number It represents the requested order size of all best bids
  ›  best_bid_price number The current best bid price, null if there aren't any bids
  ›  bid_iv number (Only for option) implied volatility for best bid
  ›  current_funding number Current funding (perpetual only)
  ›  delivery_price number The settlement price for the instrument. Only when state = closed
  ›  estimated_delivery_price number Estimated delivery price for the market. For more details, see Contract Specification > General Documentation > Expiration Price
  ›  funding_8h number Funding 8h (perpetual only)
  ›  greeks object Only for options
  ›    ›  delta number (Only for option) The delta value for the option
  ›    ›  gamma number (Only for option) The gamma value for the option
  ›    ›  rho number (Only for option) The rho value for the option
  ›    ›  theta number (Only for option) The theta value for the option
  ›    ›  vega number (Only for option) The vega value for the option
  ›  index_price number Current index price
  ›  instrument_name string Unique instrument identifier
  ›  interest_rate number Interest rate used in implied volatility calculations (options only)
  ›  interest_value number Value used to calculate realized_funding in positions (perpetual only)
  ›  last_price number The price for the last trade
  ›  mark_iv number (Only for option) implied volatility for mark price
  ›  mark_price number The mark price for the instrument
  ›  max_price number The maximum price for the future. Any buy orders you submit higher than this price, will be clamped to this maximum.
  ›  min_price number The minimum price for the future. Any sell orders you submit lower than this price will be clamped to this minimum.
  ›  open_interest number The total amount of outstanding contracts in the corresponding amount units. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  settlement_price number Optional (not added for spot). The settlement price for the instrument. Only when state = open
  ›  state string The state of the order book. Possible values are open and closed.
  ›  stats object
  ›    ›  high number Highest price during 24h
  ›    ›  low number Lowest price during 24h
  ›    ›  price_change number 24-hour price change expressed as a percentage, null if there weren't any trades
  ›    ›  volume number Volume during last 24h in base currency
  ›    ›  volume_usd number Volume in usd (futures only)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  underlying_index number Name of the underlying future, or index_price (options only)
  ›  underlying_price number Underlying price for implied volatility calculations (options only)

trades.{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": ["trades.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": ["trades.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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"trades.BTC-PERPETUAL.raw","data":[{"amount":10,"direction":"sell","index_price":8955.88,"instrument_name":"BTC-PERPETUAL","mark_price":8948.9,"price":8950,"tick_direction":2,"timestamp":1590484512188,"trade_id":"48079269","trade_seq":30289442}]}}

Get notifications about trades for an instrument.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
interval true string agg2
100ms
raw		 Frequency of notifications. Events will be aggregated over this interval. The value raw means no aggregation will be applied (Please note that raw interval is only available to authorized users)

Response

Name Type Description
data object
  ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›  block_trade_leg_count integer Block trade leg count - when trade was part of a block trade
  ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›  direction string Direction: buy, or sell
  ›  index_price number Index Price at the moment of trade
  ›  instrument_name string Unique instrument identifier
  ›  iv number Option implied volatility for the price (Option only)
  ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›  mark_price number Mark Price at the moment of trade
  ›  price number Price in base currency
  ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›  trade_id string Unique (per currency) trade identifier
  ›  trade_seq integer The sequence number of the trade within instrument

trades.{kind}.{currency}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "public/subscribe",
     "id": 42,
     "params": {
        "channels": ["trades.option.BTC.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": ["trades.option.BTC.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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"trades.option.BTC.raw","data":[{"amount":3,"direction":"sell","index_price":8956.17,"instrument_name":"BTC-27MAY20-9000-C","iv":47.58,"mark_price":0.01062686,"price":0.0075,"tick_direction":2,"timestamp":1590484589306,"trade_id":"48079289","trade_seq":2}]}}

Get notifications about trades in any instrument of a given kind and given currency.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
kind true string future
option
spot
future_combo
option_combo		 Instrument kind, "future" or "option"
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all
interval true string agg2
100ms
raw		 Frequency of notifications. Events will be aggregated over this interval. The value raw means no aggregation will be applied (Please note that raw interval is only available to authorized users)

Response

Name Type Description
data array of object
  ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›  block_trade_leg_count integer Block trade leg count - when trade was part of a block trade
  ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›  direction string Direction: buy, or sell
  ›  index_price number Index Price at the moment of trade
  ›  instrument_name string Unique instrument identifier
  ›  iv number Option implied volatility for the price (Option only)
  ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›  mark_price number Mark Price at the moment of trade
  ›  price number Price in base currency
  ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›  trade_id string Unique (per currency) trade identifier
  ›  trade_seq integer The sequence number of the trade within instrument

user.access_log

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.access_log"]}
    };
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": ["user.access_log"]}
    }

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":"user.access_log","data":{"city":"Pekin","country":"China","id":243343,"ip":"8.9.10.11","log":"success","timestamp":1632488963633}}}

Get notifications about security events related to the account

Try in API console

Channel Parameters

This method takes no parameters

Response

Name Type Description
data object
  ›  city string City where the IP address is registered (estimated)
  ›  country string Country where the IP address is registered (estimated)
  ›  data object or string Optional, additional information about action, type depends on log value
  ›  id integer Unique identifier
  ›  ip string IP address of source that generated action
  ›  log string Action description, values: changed_email - email was changed; changed_password - password was changed; disabled_tfa - TFA was disabled; enabled_tfa - TFA was enabled, success - successful login; failure - login failure; enabled_subaccount_login - login was enabled for subaccount (in data - subaccount uid); disabled_subaccount_login - login was disabled for subbaccount (in data - subbacount uid);new_api_key - API key was created (in data key client id); removed_api_key - API key was removed (in data key client id); changed_scope - scope of API key was changed (in data key client id); changed_whitelist - whitelist of API key was edited (in data key client id); disabled_api_key - API key was disabled (in data key client id); enabled_api_key - API key was enabled (in data key client id); reset_api_key - API key was reset (in data key client id)
  ›  timestamp integer The timestamp (milliseconds since the Unix epoch)

user.changes.{instrument_name}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.changes.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": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.changes.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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"user.changes.BTC-PERPETUAL.raw","data":{"instrument_name":"BTC-PERPETUAL","orders":[{"amount":10,"api":false,"average_price":17391,"creation_timestamp":1605780344032,"direction":"sell","filled_amount":10,"instrument_name":"BTC-PERPETUAL","is_liquidation":false,"is_rebalance":false,"label":"","last_update_timestamp":1605780344032,"max_show":10,"order_id":"3398016","order_state":"filled","order_type":"market","post_only":false,"price":15665.5,"reduce_only":false,"replaced":false,"time_in_force":"good_til_cancelled","web":true}],"positions":[{"average_price":15000,"delta":10.646886321,"direction":"buy","floating_profit_loss":0.906961435,"index_price":17501.88,"initial_margin":0.319750953,"instrument_name":"BTC-PERPETUAL","interest_value":1.7362511643080387,"kind":"future","leverage":33,"maintenance_margin":0.234575865,"mark_price":17391,"realized_funding":0.01235663,"realized_profit_loss":0.012454598,"settlement_price":16025.83,"size":185160,"size_currency":10.646886321,"total_profit_loss":1.69711368}],"trades":[{"amount":10,"direction":"sell","fee":1.6e-7,"fee_currency":"BTC","index_price":17501.88,"instrument_name":"BTC-PERPETUAL","liquidity":"T","mark_price":17391,"matching_id":null,"order_id":"3398016","order_type":"market","post_only":false,"price":17391,"profit_loss":4.898e-5,"reduce_only":false,"state":"filled","tick_direction":1,"timestamp":1605780344032,"trade_id":"1430914","trade_seq":866638}]}}}

Get notifications about the user's updates related to order, trades, etc. in an instrument.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
interval true string agg2
100ms
raw		 Frequency of notifications. Events will be aggregated over this interval. The value raw means no aggregation will be applied (Please note that raw interval is only available to authorized users)

Response

Name Type Description
data array of object
  ›  instrument_name string Unique instrument identifier
  ›  orders array of object
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  order_id string Unique order identifier
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  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.
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  primary_order_id string Unique order identifier
  ›  position array of object
  ›    ›  average_price number Average price of trades that built this position
  ›    ›  average_price_usd number Only for options, average price in USD
  ›    ›  delta number Delta parameter
  ›    ›  direction string Direction: buy, sell or zero
  ›    ›  floating_profit_loss number Floating profit or loss
  ›    ›  floating_profit_loss_usd number Only for options, floating profit or loss in USD
  ›    ›  gamma number Only for options, Gamma parameter
  ›    ›  index_price number Current index price
  ›    ›  initial_margin number Initial margin
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  interest_value number Value used to calculate realized_funding (perpetual only)
  ›    ›  kind string Instrument kind: "future", "option", "spot", "future_combo", "option_combo"
  ›    ›  leverage integer Current available leverage for future position
  ›    ›  maintenance_margin number Maintenance margin
  ›    ›  mark_price number Current mark price for position's instrument
  ›    ›  realized_funding number Realized Funding in current session included in session realized profit or loss, only for positions of perpetual instruments
  ›    ›  realized_profit_loss number Realized profit or loss
  ›    ›  settlement_price number Optional (not added for spot). 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
  ›    ›  theta number Only for options, Theta parameter
  ›    ›  total_profit_loss number Profit or loss from position
  ›    ›  vega number Only for options, Vega parameter
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

user.changes.{kind}.{currency}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.changes.future.BTC.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": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.changes.future.BTC.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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"user.changes.future.BTC.raw","data":{"instrument_name":"BTC-PERPETUAL","orders":[{"amount":10,"api":false,"average_price":17391,"creation_timestamp":1605780344032,"direction":"sell","filled_amount":10,"instrument_name":"BTC-PERPETUAL","is_liquidation":false,"is_rebalance":false,"label":"","last_update_timestamp":1605780344032,"max_show":10,"order_id":"3398016","order_state":"filled","order_type":"market","post_only":false,"price":15665.5,"reduce_only":false,"replaced":false,"time_in_force":"good_til_cancelled","web":true}],"positions":[{"average_price":15000,"delta":10.646886321,"direction":"buy","floating_profit_loss":0.906961435,"index_price":17501.88,"initial_margin":0.319750953,"instrument_name":"BTC-PERPETUAL","interest_value":1.7362511643080387,"kind":"future","leverage":33,"maintenance_margin":0.234575865,"mark_price":17391,"realized_funding":0.01235663,"realized_profit_loss":0.012454598,"settlement_price":16025.83,"size":185160,"size_currency":10.646886321,"total_profit_loss":1.69711368}],"trades":[{"amount":10,"direction":"sell","fee":1.6e-7,"fee_currency":"BTC","index_price":17501.88,"instrument_name":"BTC-PERPETUAL","liquidity":"T","mark_price":17391,"matching_id":null,"order_id":"3398016","order_type":"market","post_only":false,"price":17391,"profit_loss":4.898e-5,"reduce_only":false,"state":"filled","tick_direction":1,"timestamp":1605780344032,"trade_id":"1430914","trade_seq":866638}]}}}

Get notifications about changes in user's updates related to order, trades, etc. in instruments of a given kind and currency.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
kind true string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all
interval true string agg2
100ms
raw		 Frequency of notifications. Events will be aggregated over this interval. The value raw means no aggregation will be applied (Please note that raw interval is only available to authorized users)

Response

Name Type Description
data array of object
  ›  instrument_name string Unique instrument identifier
  ›  orders array of object
  ›    ›  quote boolean If order is a quote. Present only if true.
  ›    ›  triggered boolean Whether the trigger order has been triggered
  ›    ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›    ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›    ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›    ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›    ›  usd number Option price in USD (Only if advanced="usd")
  ›    ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›    ›  api boolean true if created with API
  ›    ›  average_price number Average fill price of the order
  ›    ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›    ›  order_id string Unique order identifier
  ›    ›  post_only boolean true for post-only orders only
  ›    ›  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.
  ›    ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›    ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›    ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›    ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›    ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›    ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›    ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›    ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›    ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›    ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›    ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›    ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›    ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›    ›  label string User defined label (up to 64 characters)
  ›    ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›    ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›    ›  web boolean true if created via Deribit frontend (optional)
  ›    ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›    ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›    ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›    ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›    ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›    ›  original_order_type string Original order type. Optional field
  ›    ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›    ›  trigger_price number Trigger price (Only for future trigger orders)
  ›    ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›    ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›    ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›    ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›    ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›    ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›    ›  primary_order_id string Unique order identifier
  ›  position array of object
  ›    ›  average_price number Average price of trades that built this position
  ›    ›  average_price_usd number Only for options, average price in USD
  ›    ›  delta number Delta parameter
  ›    ›  direction string Direction: buy, sell or zero
  ›    ›  floating_profit_loss number Floating profit or loss
  ›    ›  floating_profit_loss_usd number Only for options, floating profit or loss in USD
  ›    ›  gamma number Only for options, Gamma parameter
  ›    ›  index_price number Current index price
  ›    ›  initial_margin number Initial margin
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  interest_value number Value used to calculate realized_funding (perpetual only)
  ›    ›  kind string Instrument kind: "future", "option", "spot", "future_combo", "option_combo"
  ›    ›  leverage integer Current available leverage for future position
  ›    ›  maintenance_margin number Maintenance margin
  ›    ›  mark_price number Current mark price for position's instrument
  ›    ›  realized_funding number Realized Funding in current session included in session realized profit or loss, only for positions of perpetual instruments
  ›    ›  realized_profit_loss number Realized profit or loss
  ›    ›  settlement_price number Optional (not added for spot). 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
  ›    ›  theta number Only for options, Theta parameter
  ›    ›  total_profit_loss number Profit or loss from position
  ›    ›  vega number Only for options, Vega parameter
  ›  trades array of object
  ›    ›  trade_id string Unique (per currency) trade identifier
  ›    ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›    ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›    ›  api boolean true if user order was created with API
  ›    ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›    ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›    ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›    ›  post_only string true if user order is post-only
  ›    ›  direction string Direction: buy, or sell
  ›    ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›    ›  mmp boolean true if user order is MMP
  ›    ›  fee number User's fee in units of the specified fee_currency
  ›    ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  index_price number Index Price at the moment of trade
  ›    ›  label string User defined label (presented only when previously set for order by user)
  ›    ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›    ›  price number Price in base currency
  ›    ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›    ›  matching_id string Always null
  ›    ›  order_type string Order type: "limit, "market", or "liquidation"
  ›    ›  profit_loss number Profit and loss in base currency.
  ›    ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›    ›  iv number Option implied volatility for the price (Option only)
  ›    ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›    ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›    ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›    ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›    ›  mark_price number Mark Price at the moment of trade
  ›    ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›    ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›    ›  reduce_only string true if user order is reduce-only
  ›    ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›    ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›    ›  trade_seq integer The sequence number of the trade within instrument
  ›    ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›    ›  instrument_name string Unique instrument identifier
  ›    ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

user.combo_trades.{instrument_name}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.combo_trades.BTC-FS-2SEP22_PERP.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": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.combo_trades.BTC-FS-2SEP22_PERP.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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"user.combo_trades.BTC-FS-2SEP22_PERP.raw","data":[{"amount":10,"api":false,"direction":"sell","fee":0,"fee_currency":"BTC","index_price":20332.44,"instrument_name":"BTC-FS-2SEP22_PERP","legs":[{"amount":10,"api":false,"combo_id":"BTC-FS-2SEP22_PERP","combo_trade_id":"1154","direction":"buy","fee":5.0e-8,"fee_currency":"BTC","index_price":20332.44,"instrument_name":"BTC-PERPETUAL","liquidity":"T","mark_price":20220.61,"matching_id":null,"mmp":false,"order_id":"720078","order_type":"limit","post_only":false,"price":20008.5,"profit_loss":0,"reduce_only":false,"risk_reducing":false,"state":"filled","tick_direction":2,"timestamp":1661867454335,"trade_id":"1156","trade_seq":179},{"amount":10,"api":false,"combo_id":"BTC-FS-2SEP22_PERP","combo_trade_id":"1154","direction":"sell","fee":5.0e-8,"fee_currency":"BTC","index_price":20332.44,"instrument_name":"BTC-2SEP22","liquidity":"T","mark_price":20988.21,"matching_id":null,"mmp":false,"order_id":"720077","order_type":"limit","post_only":false,"price":21200.32,"profit_loss":0,"reduce_only":false,"risk_reducing":false,"state":"filled","tick_direction":0,"timestamp":1661867454335,"trade_id":"1155","trade_seq":159}],"liquidity":"T","mark_price":767.6,"matching_id":null,"mmp":false,"order_id":"720074","order_type":"limit","post_only":false,"price":1191.82,"profit_loss":null,"reduce_only":false,"risk_reducing":false,"state":"filled","tick_direction":2,"timestamp":1661867454334,"trade_id":"1154","trade_seq":39}]}}

Get notifications about the user's trades in an instrument (trades contain legs field).

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
interval true string agg2
100ms
raw		 Frequency of notifications. Events will be aggregated over this interval. The value raw means no aggregation will be applied (Please note that raw interval is only available to authorized users)

Response

Name Type Description
data array of object
  ›  trade_id string Unique (per currency) trade identifier
  ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  api boolean true if user order was created with API
  ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›  post_only string true if user order is post-only
  ›  direction string Direction: buy, or sell
  ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›  mmp boolean true if user order is MMP
  ›  fee number User's fee in units of the specified fee_currency
  ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›  index_price number Index Price at the moment of trade
  ›  label string User defined label (presented only when previously set for order by user)
  ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›  price number Price in base currency
  ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›  matching_id string Always null
  ›  order_type string Order type: "limit, "market", or "liquidation"
  ›  profit_loss number Profit and loss in base currency.
  ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›  iv number Option implied volatility for the price (Option only)
  ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›  mark_price number Mark Price at the moment of trade
  ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›  reduce_only string true if user order is reduce-only
  ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›  trade_seq integer The sequence number of the trade within instrument
  ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›  instrument_name string Unique instrument identifier
  ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

user.combo_trades.{kind}.{currency}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.combo_trades.future_combo.BTC.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": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.combo_trades.future_combo.BTC.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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"user.combo_trades.future_combo.BTC.raw","data":[{"amount":10,"api":false,"direction":"sell","fee":0,"fee_currency":"BTC","index_price":20332.44,"instrument_name":"BTC-FS-2SEP22_PERP","legs":[{"amount":10,"api":false,"combo_id":"BTC-FS-2SEP22_PERP","combo_trade_id":"1154","direction":"buy","fee":5.0e-8,"fee_currency":"BTC","index_price":20332.44,"instrument_name":"BTC-PERPETUAL","liquidity":"T","mark_price":20220.61,"matching_id":null,"mmp":false,"order_id":"720078","order_type":"limit","post_only":false,"price":20008.5,"profit_loss":0,"reduce_only":false,"risk_reducing":false,"state":"filled","tick_direction":2,"timestamp":1661867454335,"trade_id":"1156","trade_seq":179},{"amount":10,"api":false,"combo_id":"BTC-FS-2SEP22_PERP","combo_trade_id":"1154","direction":"sell","fee":5.0e-8,"fee_currency":"BTC","index_price":20332.44,"instrument_name":"BTC-2SEP22","liquidity":"T","mark_price":20988.21,"matching_id":null,"mmp":false,"order_id":"720077","order_type":"limit","post_only":false,"price":21200.32,"profit_loss":0,"reduce_only":false,"risk_reducing":false,"state":"filled","tick_direction":0,"timestamp":1661867454335,"trade_id":"1155","trade_seq":159}],"liquidity":"T","mark_price":767.6,"matching_id":null,"mmp":false,"order_id":"720074","order_type":"limit","post_only":false,"price":1191.82,"profit_loss":null,"reduce_only":false,"risk_reducing":false,"state":"filled","tick_direction":2,"timestamp":1661867454334,"trade_id":"1154","trade_seq":39}]}}

Get notifications about the user's trades in any instrument of a given kind and given currency (trades contain legs field).

Try in API console

Channel Parameters

Parameter Required Type Enum Description
kind true string future_combo
option_combo
combo		 Combo instrument kind, "combo" for any combo
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all
interval true string agg2
100ms
raw		 Frequency of notifications. Events will be aggregated over this interval. The value raw means no aggregation will be applied (Please note that raw interval is only available to authorized users)

Response

Name Type Description
data array of object
  ›  trade_id string Unique (per currency) trade identifier
  ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  api boolean true if user order was created with API
  ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›  post_only string true if user order is post-only
  ›  direction string Direction: buy, or sell
  ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›  mmp boolean true if user order is MMP
  ›  fee number User's fee in units of the specified fee_currency
  ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›  index_price number Index Price at the moment of trade
  ›  label string User defined label (presented only when previously set for order by user)
  ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›  price number Price in base currency
  ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›  matching_id string Always null
  ›  order_type string Order type: "limit, "market", or "liquidation"
  ›  profit_loss number Profit and loss in base currency.
  ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›  iv number Option implied volatility for the price (Option only)
  ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›  mark_price number Mark Price at the moment of trade
  ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›  reduce_only string true if user order is reduce-only
  ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›  trade_seq integer The sequence number of the trade within instrument
  ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›  instrument_name string Unique instrument identifier
  ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

user.lock

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.lock"]}
    };
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": ["user.lock"]}
    }

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":"user.lock","data":{"currency":"ALL","locked":true}}}

Get notification when account is locked/unlocked

Try in API console

Channel Parameters

This method takes no parameters

Response

Name Type Description
data object
  ›  currency string Currency on which account lock has changed, ALL if changed for all currencies
  ›  locked boolean Value is set to 'true' when user account is locked in currency

user.mmp_trigger.{index_name}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.mmp_trigger.any"]}
    };
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": ["user.mmp_trigger.any"]}
    }

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":"user.mmp_trigger.any","data":{"frozen_until":0,"index_name":"btc_usdc","mmp_group":"MassQuoteBot7"}}}

Triggered when one of mmp limits is crossed

Try in API console

Channel Parameters

Parameter Required Type Enum Description
index_name true string btc_usd
eth_usd
btc_usdc
eth_usdc
ada_usdc
algo_usdc
avax_usdc
bch_usdc
bnb_usdc
doge_usdc
dot_usdc
link_usdc
ltc_usdc
near_usdc
paxg_usdc
shib_usdc
sol_usdc
ton_usdc
trx_usdc
trump_usdc
uni_usdc
xrp_usdc
usde_usdc
buidl_usdc
btcdvol_usdc
ethdvol_usdc
btc_usdt
eth_usdt
all		 Index identifier of derivative instrument on the platform

Response

Name Type Description
data object
  ›  block_rfq boolean If true, indicates that the MMP trigger is for Block RFQ. Block RFQ MMP triggers are completely separate from normal order/quote MMP triggers.
  ›  frozen_until integer Timestamp (milliseconds since the UNIX epoch) until the user will be frozen - 0 means that the user is frozen until manual reset.
  ›  index_name string Index identifier of derivative instrument on the platform. For Block RFQ MMP, this will be "all" when triggered by trade count limit.
  ›  mmp_group string Triggered mmp group, this parameter is optional (appears only for Mass Quote orders trigger)

user.orders.{instrument_name}.raw

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.orders.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": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.orders.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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"user.orders.BTC-PERPETUAL.raw","data":{"amount":200,"api":false,"average_price":0,"creation_timestamp":1581507423789,"direction":"buy","filled_amount":0,"instrument_name":"BTC-PERPETUAL","is_liquidation":false,"is_rebalance":false,"label":"","last_update_timestamp":1581507423789,"max_show":200,"order_id":"5","order_state":"open","order_type":"limit","original_order_type":"market","post_only":false,"price":10502.52,"reduce_only":false,"replaced":false,"time_in_force":"good_til_cancelled"}}}

Get notifications about changes in user's orders for given instrument.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name

Response

Name Type Description
data object
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›  primary_order_id string Unique order identifier

user.orders.{instrument_name}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.orders.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": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.orders.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 next notifications like this:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"user.orders.BTC-PERPETUAL.100ms","data":[{"amount":200,"api":false,"average_price":0,"creation_timestamp":1581507159533,"direction":"buy","filled_amount":0,"instrument_name":"BTC-PERPETUAL","is_liquidation":false,"is_rebalance":false,"label":"","last_update_timestamp":1581507159533,"max_show":200,"order_id":"4","order_state":"open","order_type":"limit","original_order_type":"market","post_only":false,"price":10460.43,"reduce_only":false,"replaced":false,"time_in_force":"good_til_cancelled"}]}}

Get notifications about changes in user's orders for given instrument.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
interval true string 100ms
agg2		 Frequency of notifications. Events will be aggregated over this interval.

Response

Name Type Description
data array of object
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›  primary_order_id string Unique order identifier

user.orders.{kind}.{currency}.raw

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.orders.any.any.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": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.orders.any.any.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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"user.orders.any.any.raw","data":{"amount":200,"api":false,"average_price":0,"creation_timestamp":1581507583024,"direction":"buy","filled_amount":0,"instrument_name":"BTC-PERPETUAL","is_liquidation":false,"is_rebalance":false,"label":"","last_update_timestamp":1581507583024,"max_show":200,"order_id":"6","order_state":"open","order_type":"limit","original_order_type":"market","post_only":false,"price":10542.68,"reduce_only":false,"replaced":false,"time_in_force":"good_til_cancelled"}}}

Get notifications about changes in user's orders in instruments of a given kind and currency.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
kind true string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all

Response

Name Type Description
data object
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›  primary_order_id string Unique order identifier

user.orders.{kind}.{currency}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.orders.future.BTC.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": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.orders.future.BTC.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 next notifications like this:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"user.orders.future.BTC.100ms","data":[{"amount":120,"api":false,"average_price":0,"creation_timestamp":1550826337209,"direction":"buy","filled_amount":0,"instrument_name":"BTC-PERPETUAL","is_liquidation":false,"is_rebalance":false,"label":"","last_update_timestamp":1550826337209,"max_show":120,"order_id":"476137","order_state":"open","order_type":"limit","post_only":false,"price":3928.5,"reduce_only":false,"time_in_force":"good_til_cancelled"}]}}

Get notifications about changes in user's orders in instruments of a given kind and currency.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
kind true string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all
interval true string 100ms
agg2		 Frequency of notifications. Events will be aggregated over this interval.

Response

Name Type Description
data array of object
  ›  quote boolean If order is a quote. Present only if true.
  ›  triggered boolean Whether the trigger order has been triggered
  ›  mobile boolean optional field with value true added only when created with Mobile Application
  ›  app_name string The name of the application that placed the order on behalf of the user (optional).
  ›  implv number Implied volatility in percent. (Only if advanced="implv")
  ›  refresh_amount number The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders
  ›  usd number Option price in USD (Only if advanced="usd")
  ›  oto_order_ids array of string The Ids of the orders that will be triggered if the order is filled
  ›  api boolean true if created with API
  ›  average_price number Average fill price of the order
  ›  advanced string advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).
  ›  order_id string Unique order identifier
  ›  post_only boolean true for post-only orders only
  ›  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.
  ›  trigger string Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".
  ›  trigger_order_id string Id of the trigger order that created the order (Only for orders that were created by triggered orders).
  ›  direction string Direction: buy, or sell
  ›  contracts number It represents the order size in contract units. (Optional, may be absent in historical data).
  ›  is_secondary_oto boolean true if the order is an order that can be triggered by another order, otherwise not present.
  ›  replaced boolean true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.
  ›  mmp_group string Name of the MMP group supplied in the private/mass_quote request.
  ›  mmp boolean true if the order is a MMP order, otherwise false.
  ›  last_update_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  creation_timestamp integer The timestamp (milliseconds since the Unix epoch)
  ›  cancel_reason string Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement)
  ›  mmp_cancelled boolean true if order was cancelled by mmp trigger (optional)
  ›  quote_id string The same QuoteID as supplied in the private/mass_quote request.
  ›  order_state string Order state: "open", "filled", "rejected", "cancelled", "untriggered"
  ›  is_rebalance boolean Optional (only for spot). true if order was automatically created during cross-collateral balance restoration
  ›  reject_post_only boolean true if order has reject_post_only flag (field is present only when post_only is true)
  ›  label string User defined label (up to 64 characters)
  ›  is_liquidation boolean Optional (not added for spot). true if order was automatically created during liquidation
  ›  price number or string Price in base currency or "market_price" in case of open trigger market orders
  ›  web boolean true if created via Deribit frontend (optional)
  ›  time_in_force string Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"
  ›  trigger_reference_price number The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)
  ›  display_amount number The actual display amount of iceberg order. Absent for other types of orders.
  ›  order_type string Order type: "limit", "market", "stop_limit", "stop_market"
  ›  is_primary_otoco boolean true if the order is an order that can trigger an OCO pair, otherwise not present.
  ›  original_order_type string Original order type. Optional field
  ›  block_trade boolean true if order made from block_trade trade, added only in that case.
  ›  trigger_price number Trigger price (Only for future trigger orders)
  ›  oco_ref string Unique reference that identifies a one_cancels_others (OCO) pair.
  ›  trigger_offset number The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)
  ›  quote_set_id string Identifier of the QuoteSet supplied in the private/mass_quote request.
  ›  auto_replaced boolean Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.
  ›  reduce_only boolean Optional (not added for spot). 'true for reduce-only orders only'
  ›  amount number It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  risk_reducing boolean true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.
  ›  instrument_name string Unique instrument identifier
  ›  trigger_fill_condition string

The fill condition of the linked order (Only for linked order types), default: first_hit.

  • "first_hit" - any execution of the primary order will fully cancel/place all secondary orders.
  • "complete_fill" - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
  • "incremental" - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.
  ›  primary_order_id string Unique order identifier

user.portfolio.{currency}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.portfolio.btc"]}
    };
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": ["user.portfolio.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 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":"user.portfolio.btc","data":{"delta_total":31.602298,"options_gamma":1.0e-5,"projected_initial_margin":1.01529592,"options_vega":0.07976,"fee_balance":0,"session_rpl":-0.03311399,"estimated_liquidation_ratio":0.10098729,"options_theta":16.13825,"margin_balance":302.62675921,"session_upl":0.05341555,"balance":302.60065765,"margin_model":"segregated_sm","equity":302.6188592,"available_funds":301.38036328,"projected_maintenance_margin":0.7543841,"initial_margin":1.24639592,"options_delta":-1.01958,"currency":"BTC","options_gamma_map":{"btc_usd":1.0e-5},"futures_pl":-0.32434225,"portfolio_margining_enabled":false,"futures_session_upl":0.05921555,"maintenance_margin":0.8854841,"options_vega_map":{"btc_usd":0.07976},"options_value":-0.0079,"delta_total_map":{"btc_usd":31.594397699},"cross_collateral_enabled":false,"options_session_upl":-0.0058,"additional_reserve":0,"spot_reserve":0,"total_pl":-0.33014225,"futures_session_rpl":-0.03311399,"options_session_rpl":0,"estimated_liquidation_ratio_map":{"btc_usd":0.10098729140701267},"available_withdrawal_funds":301.35426172,"options_theta_map":{"btc_usd":16.13825},"projected_delta_total":32.613978,"options_pl":-0.0058}}}

Provides information about current user portfolio

Try in API console

Channel Parameters

Parameter Required Type Enum Description
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all

Response

Name Type Description
data object
  ›  options_pl number Options profit and Loss
  ›  projected_delta_total number The sum of position deltas without positions that will expire during closest expiration
  ›  options_theta_map object Map of options' thetas per index
  ›  total_margin_balance_usd number Optional (only for users using cross margin). The account's total margin balance in all cross collateral currencies, expressed in USD
  ›  total_delta_total_usd number Optional (only for users using cross margin). The account's total delta total in all cross collateral currencies, expressed in USD
  ›  available_withdrawal_funds number The account's available to withdrawal funds
  ›  estimated_liquidation_ratio_map object Map of Estimated Liquidation Ratio per index, it is returned only for users with segregated_sm margin model. Multiplying it by future position's market price returns its estimated liquidation price.
  ›  options_session_rpl number Options session realized profit and Loss
  ›  futures_session_rpl number Futures session realized profit and Loss
  ›  total_pl number Profit and loss
  ›  additional_reserve number The account's balance reserved in other orders
  ›  options_session_upl number Options session unrealized profit and Loss
  ›  cross_collateral_enabled boolean When true cross collateral is enabled for user
  ›  delta_total_map object Map of position sum's per index
  ›  options_value number Options value
  ›  options_vega_map object Map of options' vegas per index
  ›  maintenance_margin number The maintenance margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  futures_session_upl number Futures session unrealized profit and Loss
  ›  portfolio_margining_enabled boolean When true portfolio margining is enabled for user
  ›  futures_pl number Futures profit and Loss
  ›  options_gamma_map object Map of options' gammas per index
  ›  currency string The selected currency
  ›  options_delta number Options summary delta
  ›  initial_margin number The account's initial margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  projected_maintenance_margin number Projected maintenance margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  available_funds number The account's available funds. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  equity number The account's current equity
  ›  margin_model string Name of user's currently enabled margin model
  ›  balance number The account's balance
  ›  session_upl number Session unrealized profit and loss
  ›  margin_balance number The account's margin balance. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  options_theta number Options summary theta
  ›  total_initial_margin_usd number Optional (only for users using cross margin). The account's total initial margin in all cross collateral currencies, expressed in USD
  ›  estimated_liquidation_ratio number [DEPRECATED] Estimated Liquidation Ratio is returned only for users with segregated_sm margin model. Multiplying it by future position's market price returns its estimated liquidation price. Use estimated_liquidation_ratio_map instead.
  ›  session_rpl number Session realized profit and loss
  ›  fee_balance number The account's fee balance (it can be used to pay for fees)
  ›  total_maintenance_margin_usd number Optional (only for users using cross margin). The account's total maintenance margin in all cross collateral currencies, expressed in USD
  ›  options_vega number Options summary vega
  ›  projected_initial_margin number Projected initial margin. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.
  ›  options_gamma number Options summary gamma
  ›  total_equity_usd number Optional (only for users using cross margin). The account's total equity in all cross collateral currencies, expressed in USD
  ›  delta_total number The sum of position deltas

user.trades.{instrument_name}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.trades.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": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.trades.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:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"user.trades.BTC-PERPETUAL.raw","data":[{"amount":20,"direction":"sell","fee":1.68e-6,"fee_currency":"BTC","index_price":8956.73,"instrument_name":"BTC-PERPETUAL","liquidity":"T","mark_price":8952.86,"matching_id":null,"order_id":"4008965646","order_type":"market","post_only":false,"price":8954,"reduce_only":false,"state":"filled","tick_direction":0,"timestamp":1590484156350,"trade_id":"48079254","trade_seq":30289432},{"amount":20,"direction":"sell","fee":1.68e-6,"fee_currency":"BTC","index_price":8956.73,"instrument_name":"BTC-PERPETUAL","liquidity":"T","mark_price":8952.86,"matching_id":null,"order_id":"4008965646","order_type":"market","post_only":false,"price":8954,"reduce_only":false,"state":"filled","tick_direction":1,"timestamp":1590484156350,"trade_id":"48079255","trade_seq":30289433}]}}

Get notifications about the user's trades in an instrument.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
instrument_name true string Instrument name
interval true string agg2
100ms
raw		 Frequency of notifications. Events will be aggregated over this interval. The value raw means no aggregation will be applied (Please note that raw interval is only available to authorized users)

Response

Name Type Description
data array of object
  ›  trade_id string Unique (per currency) trade identifier
  ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  api boolean true if user order was created with API
  ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›  post_only string true if user order is post-only
  ›  direction string Direction: buy, or sell
  ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›  mmp boolean true if user order is MMP
  ›  fee number User's fee in units of the specified fee_currency
  ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›  index_price number Index Price at the moment of trade
  ›  label string User defined label (presented only when previously set for order by user)
  ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›  price number Price in base currency
  ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›  matching_id string Always null
  ›  order_type string Order type: "limit, "market", or "liquidation"
  ›  profit_loss number Profit and loss in base currency.
  ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›  iv number Option implied volatility for the price (Option only)
  ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›  mark_price number Mark Price at the moment of trade
  ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›  reduce_only string true if user order is reduce-only
  ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›  trade_seq integer The sequence number of the trade within instrument
  ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›  instrument_name string Unique instrument identifier
  ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

user.trades.{kind}.{currency}.{interval}

Subscriptions are only available via websockets.

// To subscribe to this channel:
var msg = 
    {"jsonrpc": "2.0",
     "method": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.trades.future.BTC.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": "private/subscribe",
     "id": 42,
     "params": {
        "channels": ["user.trades.future.BTC.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 next notifications like this:

{"jsonrpc":"2.0","method":"subscription","params":{"channel":"user.trades.future.BTC.100ms","data":[{"amount":8940,"direction":"sell","fee":4.9961e-4,"fee_currency":"BTC","index_price":8953.53,"instrument_name":"BTC-25SEP20","liquidity":"T","mark_price":8970.03,"matching_id":null,"order_id":"4008978075","order_type":"limit","post_only":false,"price":8947,"reduce_only":false,"state":"filled","tick_direction":2,"timestamp":1590484255886,"trade_id":"48079262","trade_seq":74405}]}}

Get notifications about the user's trades in any instrument of a given kind and given currency.

Try in API console

Channel Parameters

Parameter Required Type Enum Description
kind true string future
option
spot
future_combo
option_combo
combo
any		 Instrument kind, "combo" for any combo or "any" for all
currency true string BTC
ETH
USDC
USDT
EURR
any		 The currency symbol or "any" for all
interval true string agg2
100ms
raw		 Frequency of notifications. Events will be aggregated over this interval. The value raw means no aggregation will be applied (Please note that raw interval is only available to authorized users)

Response

Name Type Description
data array of object
  ›  trade_id string Unique (per currency) trade identifier
  ›  tick_direction integer Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
  ›  fee_currency string Currency, i.e "BTC", "ETH", "USDC"
  ›  api boolean true if user order was created with API
  ›  advanced string Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)
  ›  order_id string Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
  ›  liquidity string Describes what was role of users order: "M" when it was maker order, "T" when it was taker order
  ›  post_only string true if user order is post-only
  ›  direction string Direction: buy, or sell
  ›  contracts number Trade size in contract units (optional, may be absent in historical trades)
  ›  mmp boolean true if user order is MMP
  ›  fee number User's fee in units of the specified fee_currency
  ›  quote_id string QuoteID of the user order (optional, present only for orders placed with private/mass_quote)
  ›  index_price number Index Price at the moment of trade
  ›  label string User defined label (presented only when previously set for order by user)
  ›  block_trade_id string Block trade id - when trade was part of a block trade
  ›  price number Price in base currency
  ›  combo_id string Optional field containing combo instrument name if the trade is a combo trade
  ›  matching_id string Always null
  ›  order_type string Order type: "limit, "market", or "liquidation"
  ›  profit_loss number Profit and loss in base currency.
  ›  timestamp integer The timestamp of the trade (milliseconds since the UNIX epoch)
  ›  iv number Option implied volatility for the price (Option only)
  ›  state string Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)
  ›  underlying_price number Underlying price for implied volatility calculations (Options only)
  ›  block_rfq_quote_id integer ID of the Block RFQ quote - when trade was part of the Block RFQ
  ›  quote_set_id string QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)
  ›  mark_price number Mark Price at the moment of trade
  ›  block_rfq_id integer ID of the Block RFQ - when trade was part of the Block RFQ
  ›  combo_trade_id number Optional field containing combo trade identifier if the trade is a combo trade
  ›  reduce_only string true if user order is reduce-only
  ›  amount number Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures and it is the underlying base currency coin.
  ›  liquidation string Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation
  ›  trade_seq integer The sequence number of the trade within instrument
  ›  risk_reducing boolean true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)
  ›  instrument_name string Unique instrument identifier
  ›  legs array Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events)

RPC Error Codes

Error Code Short message Description
0 or absent Success, No error.
10000 "authorization_required" Authorization issue, invalid or absent signature etc.
10001 "error" Some general failure, no public information available.
10002 "qty_too_low" Order quantity is too low.
10003 "order_overlap" Rejection, order overlap is found and self-trading is not enabled.
10004 "order_not_found" Attempt to operate with order that can't be found by specified id or label.
10005 "price_too_low <Limit>" Price is too low, <Limit> defines current limit for the operation.
10006 "price_too_low4idx <Limit>" Price is too low for current index, <Limit> defines current bottom limit for the operation.
10007 "price_too_high <Limit>" Price is too high, <Limit> defines current up limit for the operation.
10009 "not_enough_funds" Account has not enough funds for the operation.
10010 "already_closed" Attempt of doing something with closed order.
10011 "price_not_allowed" This price is not allowed for some reason.
10012 "book_closed" Operation for an instrument which order book had been closed.
10013 "pme_max_total_open_orders <Limit>" Total limit of open orders has been exceeded, it is applicable for PME users.
10014 "pme_max_future_open_orders <Limit>" Limit of count of futures' open orders has been exceeded, it is applicable for PME users.
10015 "pme_max_option_open_orders <Limit>" Limit of count of options' open orders has been exceeded, it is applicable for PME users.
10016 "pme_max_future_open_orders_size <Limit>" Limit of size for futures has been exceeded, it is applicable for PME users.
10017 "pme_max_option_open_orders_size <Limit>" Limit of size for options has been exceeded, it is applicable for PME users.
10018 "non_pme_max_future_position_size <Limit>" Limit of size for futures has been exceeded, it is applicable for non-PME users.
10019 "locked_by_admin" Trading is temporary locked by the admin.
10020 "invalid_or_unsupported_instrument" Instrument name is not valid.
10021 "invalid_amount" Amount is not valid.
10022 "invalid_quantity" quantity was not recognized as a valid number (for API v1).
10023 "invalid_price" price was not recognized as a valid number.
10024 "invalid_max_show" max_show parameter was not recognized as a valid number.
10025 "invalid_order_id" Order id is missing or its format was not recognized as valid.
10026 "price_precision_exceeded" Extra precision of the price is not supported.
10027 "non_integer_contract_amount" Futures contract amount was not recognized as integer.
10028 "too_many_requests" Allowed request rate has been exceeded.
10029 "not_owner_of_order" Attempt to operate with not own order.
10030 "must_be_websocket_request" REST request where Websocket is expected.
10031 "invalid_args_for_instrument" Some of the arguments are not recognized as valid.
10032 "whole_cost_too_low" Total cost is too low.
10033 "not_implemented" Method is not implemented yet.
10034 "trigger_price_too_high" Trigger price is too high.
10035 "trigger_price_too_low" Trigger price is too low.
10036 "invalid_max_show_amount" Max Show Amount is not valid.
10037 "non_pme_total_short_options_positions_size <Limit>" Limit of total size for short options positions has been exceeded, it is applicable for non-PME users.
10038 "pme_max_risk_reducing_orders <Limit>" Limit of open risk reducing orders has been reached, it is applicable for PME users.
10039 "not_enough_funds_in_currency <Currency>" Returned when the user does not have sufficient spot reserves to complete the spot trade or when an option order would negatively impact the non-cross portfolio margin balance of Cross SM user.
10040 "retry" Request can't be processed right now and should be retried.
10041 "settlement_in_progress" Settlement is in progress. Every day at settlement time for several seconds, the system calculates user profits and updates balances. That time trading is paused for several seconds till the calculation is completed.
10043 "price_wrong_tick" Price has to be rounded to an instrument tick size.
10044 "trigger_price_wrong_tick" Trigger Price has to be rounded to an instrument tick size.
10045 "can_not_cancel_liquidation_order" Liquidation order can't be cancelled.
10046 "can_not_edit_liquidation_order" Liquidation order can't be edited.
10047 "matching_engine_queue_full" Reached limit of pending Matching Engine requests for user.
10048 "not_on_this_server" The requested operation is not available on this server.
10049 "cancel_on_disconnect_failed" Enabling Cancel On Disconnect for the connection failed.
10066 "too_many_concurrent_requests" The client has sent too many public requests that have not yet been executed.
10072 "disabled_while_position_lock" Spot trading is disabled for users in reduce only mode.
11008 "already_filled" This request is not allowed in regards to the filled order.
11013 "max_spot_open_orders" Total limit of open orders on spot instruments has been exceeded.
11021 "post_only_price_modification_not_possible" Price modification for post only order is not possible.
11022 "max_spot_order_quantity" Limit of quantity per currency for spot instruments has been exceeded.
11029 "invalid_arguments" Some invalid input has been detected.
11030 "other_reject <Reason>" Some rejects which are not considered as very often, more info may be specified in <Reason>.
11031 "other_error <Error>" Some errors which are not considered as very often, more info may be specified in <Error>.
11035 "no_more_triggers <Limit>" Allowed amount of trigger orders has been exceeded.
11036 "invalid_trigger_price" Invalid trigger price (too high or too low) in relation to the last trade, index or market price.
11037 "outdated_instrument_for_IV_order" Instrument already not available for trading.
11038 "no_adv_for_futures" Advanced orders are not available for futures.
11039 "no_adv_postonly" Advanced post-only orders are not supported yet.
11041 "not_adv_order" Advanced order properties can't be set if the order is not advanced.
11042 "permission_denied" Permission for the operation has been denied.
11043 "bad_argument" Bad argument has been passed.
11044 "not_open_order" Attempt to do open order operations with the not open order.
11045 "invalid_event" Event name has not been recognized.
11046 "outdated_instrument" At several minutes to instrument expiration, corresponding advanced implied volatility orders are not allowed.
11047 "unsupported_arg_combination" The specified combination of arguments is not supported.
11048 "wrong_max_show_for_option" Wrong Max Show for options.
11049 "bad_arguments" Several bad arguments have been passed.
11050 "bad_request" Request has not been parsed properly.
11051 "system_maintenance" System is under maintenance.
11052 "subscribe_error_unsubscribed" Subscription error. However, subscription may fail without this error, please check the list of subscribed channels returned, as some channels can be not subscribed due to wrong input or lack of permissions.
11053 "transfer_not_found" Specified transfer is not found.
11054 "post_only_reject" Request rejected due to reject_post_only flag.
11055 "post_only_not_allowed" Post only flag not allowed for given order type.
11056 "unauthenticated_public_requests_temporarily_disabled" Request rejected because of unauthenticated public requests were temporarily disabled.
11090 "invalid_addr" Invalid address.
11091 "invalid_transfer_address" Invalid address for the transfer.
11092 "address_already_exist" The address already exists.
11093 "max_addr_count_exceeded" Limit of allowed addresses has been reached.
11094 "internal_server_error" Some unhandled error on server. Please report to admin. The details of the request will help to locate the problem.
11095 "disabled_deposit_address_creation" Deposit address creation has been disabled by admin.
11096 "address_belongs_to_user" Withdrawal instead of transfer.
11097 "no_deposit_address" Deposit address not specified.
11098 "account_locked" Account locked.
12001 "too_many_subaccounts" Limit of subbacounts is reached.
12002 "wrong_subaccount_name" The input is not allowed as the name of subaccount.
12003 "login_over_limit" The number of failed login attempts is limited.
12004 "registration_over_limit" The number of registration requests is limited.
12005 "country_is_banned" The country is banned (possibly via IP check).
12100 "transfer_not_allowed" Transfer is not allowed. Possible wrong direction or other mistake.
12998 "security_key_authorization_over_limit" Too many failed security key authorizations. The client should wait for wait seconds to try again.
13004 "invalid_credentials" Invalid credentials have been used.
13005 "pwd_match_error" Password confirmation error.
13006 "security_error" Invalid Security Code.
13007 "user_not_found" User's security code has been changed or wrong.
13008 "request_failed" Request failed because of invalid input or internal failure.
13009 "unauthorized" Wrong or expired authorization token or bad signature. For example, please check the scope of the token, "connection" scope can't be reused for other connections.
13010 "value_required" Invalid input, missing value.
13011 "value_too_short" Input is too short.
13012 "unavailable_in_subaccount" Subaccount restrictions.
13013 "invalid_phone_number" Unsupported or invalid phone number.
13014 "cannot_send_sms" SMS sending failed -- phone number is wrong.
13015 "invalid_sms_code" Invalid SMS code.
13016 "invalid_input" Invalid input.
13018 "invalid_content_type" Invalid content type of the request.
13019 "orderbook_closed" Closed, expired order book.
13020 "not_found" Instrument is not found, invalid instrument name.
13021 "forbidden" Not enough permissions to execute the request, forbidden.
13025 "method_switched_off_by_admin" API method temporarily switched off by the administrator.
13028 "temporarily_unavailable" The requested service is not responding or processing the response takes too long.
13030 "mmp_trigger" Order has been rejected due to the MMP trigger.
13031 "verification_required" API method allowed only for verified users.
13032 "non_unique_order_label" Request allowed only for orders uniquely identified by given label, more than one match was foun.
13034 "no_more_security_keys_allowed" Maximal number of tokens allowed reached.
13035 "active_combo_limit_reached" Limit of active combo books was reached. The client should wait some time before retrying the request.
13036 "unavailable_for_combo_books" Action is temporarily unavailable for combo books.
13037 "incomplete_KYC_data" KYC verification data is insufficient for external service provider.
13040 "mmp_required" User is not a MMP user.
13042 "cod_not_enabled" Cancel-on-Disconnect is not enabled for the connection.
13043 "quotes_frozen" Quotes are still frozen after previous cancel.
13403 "scope_exceeded" Error returned after the user tried to edit / delete an API key using an authorized key connection with insufficient scope.
13503 "unavailable" Method is currently not available.
13666 "request_cancelled_by_user" Request was cancelled by the user with other api request.
13777 "replaced" Edit request was replaced by other one.
13778 "raw_subscriptions_not_available_for_unauthorized" Raw subscriptions are not available for unauthorized requests.
13780 "move_positions_over_limit" The client cannot execute the request yet, and should wait for wait seconds to try again.
13781 "coupon_already_used" The coupon has already been used by current account.
13791 "KYC_transfer_already_initiated" Sharing of KYC data with a third party provider was already initiated.
13792 "incomplete_KYC_data" User's KYC data stored on the platform is insufficient for sharing according to third party provider.
13793 "KYC_data_inaccessible" User's KYC data is inaccessible at the moment. Client should try again later.
13888 "timed_out" Server did not manage to process request when it was valid (valid_until).
13901 "no_more_oto_orders" Total limit of open "one triggers other" orders has been exceeded.
13902 "mass_quotes_disabled" Mass Quotes feature disabled for this user and currency.
13903 "too_many_quotes" Number of quotes (in Mass Quotes requests) per second exceeded.
13904 "security_key_setup_required" Not allowed without a full security key setup.
13905 "too_many_quotes_per_block_rfq" Number of quotes for single block rfq exceeded.
13906 "too_many_quotes_per_block_rfq_side" Number of quotes per single block rfq side exceeded.
13907 "not_fully_filled" Block Rfq trade cannot be fully filled with matched quotes.
13907 "too_many_open_block_rfqs" Number of open block rfq by taker exceeds configured max amount.
13910 "quote_crossed" Quote placed by the maker crosses an already placed quote by the same maker.
13911 "max_broker_client_count" Number of broker client's exceeds allowed max amount.
13912 "broker_cannot_be_client" Broker accounts cannot be clients of other brokers.
13913 "broker_already_linked" User has already been linked to this broker.
13914 "user_is_a_broker_client" User is a client of a broker account.
13915 "user_is_not_a_broker" User account is not configured as broker account.
13916 "app_registered_to_broker" Application is registered to a broker.
13917 "account_quote_limit_crossed" Block Rfq quote limits set for the account were crossed.
13918 "inverse_future_cross_trading" Placed block rfq quote would cross trade inverse futures with block rfq quote limits set on the account.
13919 "client_of_main_account" Subaccounts of brokers cannot be linked to their own broker account.
-32602 "Invalid params" See JSON-RPC spec.
-32600 "request entity too large" Error thrown when body size in POST request or single frame in websocket connection frame exceeds the limit (32 kB).
-32601 "Method not found" See JSON-RPC spec.
-32700 "Parse error" See JSON-RPC spec.
-32000 "Missing params" See JSON-RPC spec.

FIX API

Deribit FIX API is a subset of FIX version 4.4, but also includes some tags from 5.0 version and several custom tags. Deribit uses the standard header and trailer structure for all messages. To enable the API, sign in and go to Account > Security > API Tab and use the checkbox. 'Client Secret' is the user's secret key provided by Deribit. Important Note: Do not reveal to anybody your 'Client Secret', as it can be used to gain full control over your account.

The FIX server can be reached at www.deribit.com:9881 (raw tcp) or www.deribit.com:9883 (ssl). The FIX server for the test network can be reached at test.deribit.com:9881 (raw tcp) or test.deribit.com:9883 (ssl).

Each request message can include:

Tag Name Type Required Comments
8 BeginString String Yes Identifies beginning of new message and protocol version. Must always be first in the message
9 BodyLength Length Yes Message length in bytes, not including fields BeginString(8), BodyLength(9) and CheckSum(10). The length must be calculated by counting the number of octets in the message up to and including the end of field delimiter (Start of Heading) of the field immediately preceding the CheckSum(10) field. Must always be the second in the message.

Please refer to FIX specification for more details
35 MsgType String Yes The type of the message. See below for available types
49 SenderCompID String Yes A user defined client name
56 TargetCompID String Yes Constant value: DERIBITSERVER
34 MsgSeqNum SeqNum Yes A sequence number for the message, starts with 1, and must be incremented by 1 for every message
52 SendingTime UTCTimestamp No The time the request is sent. This field is ignored by the server
10 CheckSum String Yes The checksum of all of all preceding messages. In order to calculate checksum, sum up the binary value of each octet up to and including the end of field delimiter (Start of Heading) of the field immediately preceding the CheckSum(10).

Afterwards calculate modulo 256 of that sum. The calculated modulo 256 checksum must then be encoded as an ISO 8859-1 three-octet representation of the decimal value.

For example, if the message length sum of character values has been calculated to be 274 then the modulo 256 value is 18 (256 + 18 = 274). This value would be encoded in the CheckSum(10) field as “10=018”.

CheckSum must always be the last field in the message.

Please refer to FIX specification Annex A for more details

Responses sent by the server will at least include:

Tag Name Type Comments
8 BeginString String Identifies beginning of new message and protocol version. Must always be first in the message
9 BodyLength Length Message length in bytes, not including fields BeginString(8), BodyLength(9) and CheckSum(10).

Please refer to FIX specification for more details
35 MsgType String The type of the message. See below for available types
49 SenderCompID String Constant value: DERIBITSERVER
56 TargetCompID String A user defined client name
34 MsgSeqNum SeqNum A server-chosen sequence number for the message
52 SendingTime UTCTimestamp The time the request is sent. This field is ignored by the server
10 CheckSum String The checksum of all of all preceding messages. Please refer to FIX specification Annex A for more details

Logon(A)

Logon(A) must be the first message sent by the client to initiate a session. If authentication succeeds, the exchange should echo the message back to the client. If authentication fails, the exchange will respond with a LogOut(5) message with an appropriate reason.

Arguments

Tag Name Type Required Comments
108 HeartBtInt int Yes Used to declare the timeout interval in seconds for generating heartbeats
95 RawDataLength Length No Number of bytes in raw data field. Not required, as the normal RawData is base64 text here
96 RawData data Yes The timestamp and a Base64 encoded nonce (see below)
553 Username String Yes API Client ID. This can be obtained from the API tab on your account settings
554 Password String Yes See below
9002 UseWordsafeTags Boolean No If present and set to Y, all of the tag numbers for our custom tags start at 5000 instead of 100000. For example, Volume24h(100087) would become 5078. This tag can be used due to the fact, that legacy software which implements FIX protocol, doesn't support the extended range for tags, which was defined in later protocol's revisions. This setting stays applied for the remainder of the connection
9001 CancelOnDisconnect Boolean No Boolean, to enable or disable session-level cancel on disconnect. Default - false(N)
9004 DeribitAppId String No Registered application Client ID. It is necessary for registered applications only
9005 DeribitAppSig String No Registered application Signature. It is necessary for registered applications only. It is calculated in a similar way to the Password(554) but with Application Secret instead of Client Secret: base64(sha256(RawData ++ application_secret)), see below
9007 DeribitSequential Boolean No Custom tag to adapt Deribit internal messaging to sequential FIX messaging. If the tag is present and set to Y, all messages, including order changes and notifications, are sent through a single queue. This eliminates the distinction between "request/response" and "notifications" queues, which typically handle messages separately. As a result, messages are sent in a sequential order without direct responses. This configuration may cause slower call-return information delivery compared to configurations that use two separate queues
9009 UnsubscribeExecutionReports Boolean No Custom tag. Default - false (N). If the tag is present and set to 'Y' this connection is unsubscribed from notificational Execution Reports about order changes. Only responses to order operation requests in this connection will be sent as Execution Reports, but no notifications such as orders from other connection or trades initiated by counterparty
9010 ConnectionOnlyExecutionReports Boolean No Custom tag. Default - false (N). If the tag is present and set to 'Y' this connection will receive notificational Execution Reports only for order created in this connection, it won't receive notification for orders created in other connections even within the same subaccount. This tag can be used to split Execution Reports between several connections to the same subaccount
9015 ReportFillsAsExecReports Boolean No Custom tag, default is false (N). If the tag is present and set to 'Y', then FillsGrp is not included into Execution Report, and reported as Execution Reports with ExecType = F(TRADE)
9018 DisplayIncrementSteps Boolean No Custom tag, default is false (N). If the tag is present and set to 'Y', then symbol entries will include the Price Increment steps of the Symbol (if applicable). See NoTickRules(1205) below

The RawData(96) tag contains a timestamp and a nonce, separated by an ASCII period (.). The timestamp needs to be a strictly increasing integer. We recommend using a timestamp in milliseconds. The nonce is composed of base64-encoded randomly chosen bytes. For safety reasons, it is important that the nonce is sufficiently long and sourced from a cryptographically secure random number generator. We recommend at least 32 bytes, but the nonce can be up to 512 bytes.

The Password(554) tag contains a base64 encoded SHA256 hash of the concatenation of the RawData(96) content and the cleint secret: base64(sha256(RawData ++ access_secret)), here ++ denotes operation of the concatenation.

Optional custom tag DeribitAppSig(9005) contains a base64 encoded SHA256 hash of the concatenation of the RawData(96) content and the Application secret: base64(sha256(RawData ++ application_secret)), here ++ denotes operation of the concatenation. This tag is used for registered applications only.

CancelOnDisconnect(9001) controls "Close on Disconnect". If this tag is not provided, the default setting from the account is used.

Response

When the login is successful, the server will echo back the request.

If the login was not successful, the server will respond with a Logout(5) message, and close the connection.

Logout(5)

Logout(5) can be sent by either party in order to terminate a session. The sending party should always wait for the echo of the logout request before they close the socket. Closing connections in any other way is considered abnormal behavior. Nonetheless, if CancelOnDisconnect(9001) was set at Logon, all orders will be cancelled at Logout.

Arguments

Tag Name Type Required Comments
58 text String No Free format text string specifying the logout reason. This is ignored by the server
9003 DontCancelOnDisconnect Boolean No If Y then it disables CancelOnDisconnect for this connection even if CancelOnDisconnect was enabled in Logon(A) or account settings. Default - false(N), no changes for CancelOnDisconnect flag

Heartbeat(0)

When either end of a FIX connection has not sent or received any data for HeartBtInt seconds (as specified in the Logon(A) message), it will transmit a Heartbeat(0) message. When either end of a FIX connection has not received any data for HeartBtInt seconds, it will transmit a TestRequest(1) message. If there is still no response, the session should be considered lost and corrective action should be initiated.

Arguments

Tag Name Type Required Comments
112 TestReqId String Varies The identifier when responding to the Test Request(1) message. When not responding to a Test Request(1) message, this tag can be left out

Response

When the heartbeat has been received successfully, the server will echo back the request as confirmation.

Test Request(1)

The Test Request(1) message forces a heartbeat from the opposing application. The opposing application responds with a Heartbeat(0) containing the TestReqID(112).

Arguments

Tag Name Type Required Comments
112 TestReqId String Yes Mirrors the original request ID

Resend Request(2)

The Resend Request(2) message is used by the server to initiate the retransmission of messages. This function is utilized if a sequence number gap is detected, if the receiving application lost a message, or as a function of the initialization process.

Arguments

Tag Name Type Required Comments
7 BeginSeqNo int Yes The first message to repeat
16 EndSeqNo int Yes The last message to repeat

Reject(3)

The Reject(3) message should be issued when a message is received but cannot be properly processed due to a session-level or data structure rule violation. An example of when a reject may be appropriate would be the receipt of a message with invalid basic data (e.g. missing tags) which successfully passes decryption.

Arguments

Tag Name Type Required Comments
45 RefSeqNum SeqNum Yes MsgSeqNum(34) of the rejected message
372 RefMsgType String No The MsgType(35) of the FIX message being referenced
373 SessionRejectReason int No Code to identity reason for rejection:
  • 6 = Incorrect data format for value
  • 11 = Invalid MsgType(35)
  • 99 = Other
58 Text String No Text string explaining the reason for rejection

Sequence Reset(4)

The Sequence Reset(4) is to recover from an out-of-sequence condition, to reestablish a FIX session after a sequence loss. The MsgSeqNum(34) in the header is ignored.

Arguments

Tag Name Type Required Comments
36 NewSeqNo SeqNum Yes New Sequence Number

Response

In reply to Sequence Reset(4), the exchange replies with Resend Request(2) with BeginSeqNo(7) and EndSeqNo(16) equal to the passed NewSeqNo(36) in case of success. In case of wrong arguments, the server replies with Resend Request(2) with BeginSeqNo(7) and EndSeqNo(16) equal to the current incoming sequence on the server.

The Sequence Reset (4) can only increase the sequence number. If a Sequence Reset(4) is received attempting to decrease the next expected sequence number the reply is Resend Request(2) with BeginSeqNo(7) and EndSeqNo(16) equal to the current incoming sequence on the server.

After sending the correct Sequence Reset(4), the client should start sending messages starting from the sequence number equal to the NewSeqNo(36) passed.

Security List Request(x)

The SecurityListRequest(x) message is used to return a list of securities (instruments) from the Deribit.

Arguments

Tag Name Type Required Comments
320 SecurityReqId String Yes A user-generated ID for this request. This can be used to match the request to the response
559 SecurityListRequestType int Yes 0 or 4 – in any case list of instruments is returned
263 SubscriptionRequestType int No Subscription Request Type to get notifications about new or terminated instruments. Valid values:
  • 0 = Snapshot,
  • 1 = Snapshot + Updates (Subscribe),
  • 2 = Disable previous Snapshot + Update Request (Unsubscribe)
9013 DisplayMulticastInstrumentID Boolean No Custom tag, default is false (N). If the tag is present and set to 'Y', then symbol entries will include the Multicast identifier of the Symbol (if applicable). See NoSecurityAltID(454) below
9018 DisplayIncrementSteps Boolean No Custom tag, default is false (N). If the tag is present and set to 'Y', then symbol entries will include the Price Increment steps of the Symbol (if applicable). See NoTickRules(1205) below
15 Currency String No First currency of the currency pair for limiting the resulted list. Required if SecondaryCurrency(5544) specified.
5544 SecondaryCurrency String No Second currency of the currency pair for limiting the resulted list. Default is USD if Currency(15) is specified. Current API doesn't support queries by SecondaryCurrency only, so Currency (15) is mandatory if SecondaryCurrency is present. In current implementation SecondaryCurrency is ignored in subscription when SubscriptionRequestType (263) = 1
167 SecurityType String No Optional parameter for limiting output by the SecurityType. Describes type of security.

Possible values:

  • FXSPOT for currency exchange spot
  • FUT for futures,
  • OPT for options,
  • FUTCO for future combo,
  • OPTCO for option combo
  • INDEX for indexes

Response

The server will respond with a Security List(y) message, where the SecurityReq(320) is equal to that of the request.

Security List(y)

The SecurityList(y) message is used to return a list of securities that matches the criteria specified in a Security List Request(x).

Arguments

Tag Name Type Required Comments
320 SecurityReqId String Yes The SecurityReqId(320) of the request that this is a response for
322 SecurityResponseID String Yes Identifier for the Security List(x) message
560 SecurityRequestResult int Yes 0 indicates a successful response. This is the only possible value in the Deribit FIX API
Group SecListGrp
146 NoRelatedSym NumInGroup No Specifies the number of repeating instruments specified
=>55 Symbol String No Common, "human understood" representation of the security, e.g., BTC-28JUL17, see instrument naming convention below for more details
=>107 SecurityDesc String No Free form security description: 'future', 'option', 'future_combo', 'option_combo' and various indexes
=>167 SecurityType String No Describes type of security.

Possible values:

  • FXSPOT for currency exchange spot
  • FUT for futures,
  • OPT for options,
  • FUTCO for future combo,
  • OPTCO for option combo
  • INDEX for indexes
=>201 PutOrCall int No Indicates whether an Option is for a put or call. Only for Options.

Possible values:

  • 0 = put,
  • 1 = call

=>202 StrikePrice Price No Strike price
=>947 StrikeCurrency String No Strike currency
=>15 Currency String No Currency
=>1524 PriceQuoteCurrency String No Quoting or counter currency
=>2576 InstrumentPricePrecision int No Number of decimal places for instrument prices (usually 4 for options, 2 for futures)
=>969 MinPriceIncrement float No Minimum price tick for a given Instrument
=>311 UnderlyingSymbol String No Underlying symbol for options
=>225 IssueDate UTCTimestamp No Date instrument was issued
=>541 MaturityDate UTCTimestamp No Expiration date, YYYYMMDD
=>1079 MaturityTime UTCTimestamp No Time of instruments expiration expressed in local time with offset to UTC specified
=>562 MinTradeVol Qty No The minimum trading volume for a security
=>63 SettlType String No Indicates order settlement period. E.g., M1 – month, W1 – week, W2 – 2 weeks etc
=>120 SettlCurrency Currency No Currency code of settlement denomination
=>479 CommCurrency Currency No Specifies currency to be used for Commission
=>231 ContractMultiplier float No Specifies the ratio or multiply factor to convert from contracts to total units
=>454 NoSecurityAltID NumInGroup No Number of alternate security identifier.

It is present only if Security List Request(x) has DisplayMulticastInstrumentID = Y
=>=>455 SecurityAltID String No The security identifier
=>=>456 SecurityAltIDSource String No Identifies the class or source of the SecurityAltID(455) value. Required if SecurityAltID is specified.

Possible values:

  • 101 = Multicast identifier
  • 102 = Combo instrument identifier
=>1205 NoTickRules NumInGroup No Number of price increment steps.

It is present only if Security List Request(x) has DisplayIncrementSteps = Y
=>=>1206 StartTickPriceRange Price No Above this price, the TickIncrement applies
=>=>1208 TickIncrement Price No Valid price increment for prices above the StartTickPriceRange
=>965 SecurityStatus String No (*) It is present in notifications about new or terminated instruments.

Possible values:

  • 1 = active/started,
  • 10 = published/created,
  • 4 = closed,
  • 2 = terminated/inactive,
  • 12 = settled

Instrument Naming convention

Based on the naming convention, instrument name consist of base currency, quote currency(called together a currency pair), contract expiration date (if the instrument isn't perpetual) and strike price(if the contract is an option).

For example:

ETH_USD-14SEP22-2000-P resembles an ETH-USD options contract that expires on 14 september 2022 with PUT strike price at 2000 USD. BTC_USD trading pair is treated as a default trading pair and doesn't have qoute currency provided in its name.

(*) SecurityStatus is present only in notification messages for subscription by SecurityListRequest with SubscriptionRequestType=1. The notifications for closed, settled or terminated status contain only the status and symbol name.

Market Data Request(V)

Market Data Request(V) can be used to request market data in snapshot or the incremental form. Deribit uses his message for order book requests and its change notification.

Arguments

Tag Name Type Required Comments
262 MdReqId String Yes Unique ID assigned to this request
263 SubscriptionRequestType int Yes Subscription Request Type. Valid values:
  • 0 = Snapshot,
  • 1 = Snapshot + Updates (Subscribe),
  • 2 = Disable previous Snapshot + Update Request (Unsubscribe)
264 MarketDepth int No See remark about MDUpdateType below
265 MDUpdateType int when SubscriptionRequestType=1 The type of update to subscribe to.

Valid values:

  • 0= full refresh,
  • 1= incremental refresh
9011 DeribitSkipBlockTrades Boolean No To skip block trades. If 9011=Y then block trades will not be reported. Default is N
9012 DeribitShowBlockTradeId Boolean No To show block trade id. If 9012=Y and 9012=N then block trades will include BlockTrade ID as TrdMatchID (880). Default is N
100007 DeribitTradeAmount int No Amount of trades returned in the snapshot response to request for snapshot of recent trades, default 20, maximum 1000
100008 DeribitSinceTimestamp int No UTC Timestamp in milliseconds (integer number of milliseconds), if specified, the response returns the trades happened since that timestamp, applicable to the request for recent trades snapshot
Group MDReqGrp
267 NoMdEntryTypes NumInGroup Yes Number of entry types in the request
=>269 MDEntryType int Yes

Valid values:

  • 0 = Bid (Bid side of the order book),
  • 1 = Offer (Ask side of the order book),
  • 2 = Trade (Info about recent trades)
Group InstrmtMDReqGrp
146 NoRelatedSym NumInGroup No Number of symbols requested. Necessary if more than 1 Symbol requested
=>55 Symbol String Yes Instrument symbol. See instrument naming convention for more details

When requesting a subscription (SubscriptionRequestType=1), the only supported combinations are:

If multiple instrument symbols are specified then the system responds with multiple market data messages corresponding to those instruments.

Response

If the server is unable to supply the requested data, it will respond with a Market Data Request Reject(Y) message.

If the request called for a snapshot (SubscriptionRequestType(263)=0), the server will respond with a Market Data - Snapshot/Full Refresh(W) message.

If the request called for a snapshot and subscription (SubscriptionRequestType(263)=1), the server will start sending Market Data - Incremental Refresh(X) messages.

Market Data Request Reject(Y)

If a Market Data Request(V) message is not accepted, the exchange responds with a Market Data Request Reject(Y) message

Arguments

Tag Name Type Required Comments
58 Text String No Free format text string
262 MDReqID String Yes ID of the original request
281 MDReqRejReason char Yes Reason for the rejection of a Market Data Request(V).

Possible reasons:

  • 0 = Unknown symbol
  • 1 = Duplicate MDReqID(262)
  • 2 = Insufficient Bandwidth
  • 3 = Insufficient Permissions
  • 4 = Unsupported SubscriptionRequestType(263)
  • 5 = Unsupported MarketDepth(264)
  • 6 = Unsupported MDUpdateType(265)
  • 7 = Unsupported AggregatedBook (266)
  • 8 = Unsupported MDEntryType(269)
  • 9 = Unsupported TradingSessionID(336)
  • A = Unsupported Scope(546)
  • B = Unsupported OpenCloseSettlFlag(286)
  • C = Unsupported MDImplicitDelete(547)
  • D = Insufficient credit

Market Data Snapshot/Full Refresh(W)

Market Data Snapshot/Full Refresh(W) is used as the response to a Market Data Request(V) message.

Arguments

Tag Name Type Required Comments
55 Symbol String Yes Instrument symbol. See instrument naming convention for more details
262 MDReqID String No ID of the original request, if it is applicable
311 UnderlyingSymbol String For options Underlying symbol
810 UnderlyingPx Price For options Price of the underlying instrument. Underlying instrument underlies the primary instrument
231 ContractMultiplier float No Specifies a multiply factor to convert from contracts to total units
201 PutOrCall int No Indicates whether an Option is for a put or call. Only for Options.

Possible values:

  • 0 = put,
  • 1 = call
100087 TradeVolume24h Qty No Defines 24h trade volume for the Symbol in the corresponding contract units
100090 MarkPrice Price No Defines mark price for the Symbol
746 OpenInterest float No Defines open interest for the Symbol
100092 CurrentFunding Price No Current funding (perpetual only)
100093 Funding8h Price No Funding in last 8h (perpetual only)
Group MDFullGrp
268 NoMDEntries NumInGroup Yes Repeating group. Specifies the number of entries in the group
=>269 MDEntryType int Yes Possible values:
  • 0 = Bid (Bid side of the order book),
  • 1 = Offer (Ask side of the order book),
  • 2 = Trade (in case of request for info about recent trades),
  • 3 = Index Value (value of Index for INDEX instruments like BTC-DERIBIT-INDEX),
  • 6 = Settlement Price(Estimated Delivery Price for INDEX instruments like BTC-DERIBIT-INDEX)
=>270 MDEntryPx Price No Price of an entry
=>271 MDEntrySize Qty No Size of an entry in Contract units corresponding to the ContractMultiplier in SecurityList
=>272 MDEntryDate UTCTimestamp No The timestamp for trade
=>100009 DeribitTradeId String No Id of the trade, in case of the request for trades
=>54 Side char No Side of trade.

Possible values:

  • 1 = Buy,
  • 2 = Sell
=>44 Price Price No For trades, this is the index price at the trade moment (Deribit index)
=>58 Text String No For trade - the trade sequence number
=>37 OrderId String No For trade – taker's matching order id
=>198 SecondaryOrderId String No For trade – maker's matching order id
=>39 OrdStatus char No For trade – order status.

Possible values:

  • 0 = New,
  • 1 = Partially filled,
  • 2 = Filled,
  • 4 = Cancelled
=>100010 DeribitLabel String No User defined max 64 grapheme clusters long, label of the order, in case of the request for trades. This tag operates on grapheme clusters. A grapheme cluster is a user-perceived character, which can be represented by several unicode codepoints. Please refer to Unicode specification for more details about the grapheme clusters
=>100091 DeribitLiquidation String No Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation. This field is hidden for public for the first hour after the trade in order to prevent traders from abusing this information.
=>880 TrdMatchID String No Only for trades. Block trade id - when trade was part of block trade. It can be included only if DeribitShowBlockTradeId(9012) is set to Y and DeribitSkipBlockTrades(9011) is set to N

CurrentFunding and Funding8h are present only in W message, not in X message below.

Market Data Incremental Refresh(X)

Market Data – Incremental Refresh(X) message is used for incremental updates in case of Market Data Request(V) for Snapshot + Subscribe

Arguments

Tag Name Type Required Comments
55 Symbol String Yes Instrument symbol. See instrument naming convention for more details
262 MDReqID String No ID of the original request, if it is applicable
231 ContractMultiplier float No Specifies a multiply factor to convert from contracts to total units
201 PutOrCall int No Indicates whether an Option is for a put or call. Only for Options.

Possible values:

  • 0 = put,
  • 1 = call
100087 TradeVolume24h Qty No Defines 24h trade volume for the Symbol in the corresponding contract units
100090 MarkPrice Price No Defines mark price for the Symbol
746 OpenInterest float No Defines open interest for the Symbol
Group MDIncGrp
268 NoMDEntries NumInGroup Yes Repeating group . Specifies the number of entries in the group
=>279 MDUpdateAction char Yes Type of Market Data update action. Valid values:
  • 0 = New,
  • 1 = Change,
  • 2 = Delete
=>269 MDEntryType int No Possible values:
  • 0 = Bid (Bid side of the order book),
  • 1 = Offer (Ask side of the order book),
  • 2 = Trade (In case of request for info about recent trades)
=>270 MDEntryPx Price No Price of an entry
=>271 MDEntrySize Qty No Size of an entry in Contract units corresponding to the ContractMultiplier in SecurityList
=>272 MDEntryDate UTCTimestamp No The timestamp for trade
=>100009 DeribitTradeId String No Id of the trade, in case of the request for trades
=>54 Side char No Side of trade.

Possible values:

  • 1 = Buy,
  • 2 = Sell
=>37 OrderId String No For trade – order id
=>198 SecondaryOrderId String No For trade – matching order id
=>39 OrdStatus char No For trade – order status.

Possible values:

  • 0 = New,
  • 1 = Partially filled,
  • 2 = Filled,
  • 4 = Cancelled
=>100010 DeribitLabel String No User defined max 64 grapheme clusters long, label of the order, in case of the request for trades. This tag operates on grapheme clusters. A grapheme cluster is a user-perceived character, which can be represented by several unicode codepoints. Please refer to Unicode specification for more details about the grapheme clusters
=>44 Price Price No For trades, this is the index price at the trade moment (Deribit index)
=>58 Text String No The trade sequence number
=>100091 DeribitLiquidation String No Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation. This field is hidden for public for the first hour after the trade in order to prevent traders from abusing this information.
=>880 TrdMatchID String No Only for trades. Block trade id - when trade was part of block trade. It can be included only if DeribitShowBlockTradeId(9012) is set to Y and DeribitSkipBlockTrades(9011) is set to N

New Order Single(D)

The NEW ORDER SINGLE(D) is used by the client to submit new orders to the exchange.

Arguments

Tag Name Type Required Comments
11 ClOrdID String Yes Unique identifier for the order, assigned by the client, max 64 grapheme clusters. This tag operates on grapheme clusters. A grapheme cluster is a user-perceived character, which can be represented by several unicode codepoints. Please refer to Unicode specification for more details about the grapheme clusters
54 Side char Yes Side of order.

Valid values:

  • 1 = Buy,
  • 2 = Sell
38 OrderQty Qty Yes Order quantity. Depends on QtyType. When QtyType is set to Units, the OrderQty is specified in USD for perpetual and inverse futures, in the underlying base currency coin for linear futures, or in the amount of cryptocurrency contracts for options. The system will automatically convert Units to Contracts when the order is placed Please, note that Quantity is by default defined in Contract units corresponding to the ContractMultiplier in SecurityList
44 Price Price Yes Price
55 Symbol String Yes Instrument symbol, e.g., BTC-1JAN16. See instrument naming convention for more details
62 ValidUntilTime UTCTimestamp No Indicates expiration time of indication message, in UTC
18 ExecInst MultipleCharValue No Currently is used to mark POST ONLY orders and REDUCE ONLY orders.

POST ONLY valid values:

  • 6 = "Participate don't initiate",
  • A = "No cross" (only together with 6, "6A" -- REJECT POST ONLY when the order is put to order the book unmodified or the request is rejected and order is cancelled),
REDUCE ONLY valid values:
  • E = "Do not increase - DNI"
40 OrdType Char No Order type.

Valid values:

  • 1 = Market,
  • 2 = Limit (by default),
  • K = Market With Left Over as Limit (market limit),
  • 4 = Stop limit (trailing stop),
  • J = Market If Touched (stop limit, if StopPx(99) is set),
  • S = Stop Limit on Bid or Offer (stop market, if StopPx(99) is set)
59 TimeInForce char No Specifies how long the order remains in effect. Absence of this field is interpreted as "Good 'Til Cancelled".

Valid values:

  • 0 = Good 'Til Day(GTD),
  • 1 = Good 'Til Cancelled(GTC),
  • 3 = Immediate or Cancel(IOC),
  • 4 = Fill or Kill(FOK)
99 StopPx Price No Price per unit of quantity
1138 DisplayQty Qty No The (max) quantity to be displayed in the orderbook. Setting the DisplayQty (1138) = 0 is interpreted as no hidden volume, i.e. the full order quantity is displayed to the market. Omitting the field gives the same result.
1088 RefreshQty Qty No Defines the quantity used to refresh DisplayQty.
854 QtyType Int No Type of quantity. Valid values:

  • 0 = Units,
  • 1 = Contracts

Default is Contracts.

When QtyType is Units, then for perpetual and inverse futures the OrderQty is in USD units, and for linear futures it is the underlying base currency coin, and for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH. The Units will be recalculated into the system's Contracts on server automatically when the order is placed.
211 PegOffsetValue Float No Amount (signed) added to the peg for a pegged order in the context of the PegOffsetType(836)
1094 PegPriceType Int No Needs to be set for Trailing Stop order. Valid value:

  • 8 = Trailing Stop Peg
100010 DeribitLabel String No A custom label for your order, max 64 grapheme clusters. Can be used by Order Cancel Request(F) to amend the order later on
100012 DeribitAdvOrderType char No Used to create advanced order for options. If it is present:
  • 0 = Implied Volatility Order (price defines fixed implied volatility in %),
  • 1 = USD Order (price defines fixed USD price of the option, advanced USD orders are not supported for linear options)
9008 DeribitMMProtection Boolean No Order Market Maker Protection (MMP) flag, default is N. Important: manual admin action is necessary to activate Market Maker Protection (MMP) for an account
5127 DeribitConditionTriggerMethod Int No Selects condition trigger method for algo orders. Valid values:

  • 1 = mark price,
  • 2 = trade,
  • 3 = index

Response

Upon receiving a new order, the exchange responds with the Execution Report(8) message communicating whether the order was accepted or rejected.

Tag Name Type Required Comments
527 SecondaryExecID String No ID of the last order change
37 OrderId String No Unique identifier of the order, assigned by the Deribit
11 ClOrdID String No Deribit replaces this field with the own value assigned by the server (it is not the ClOrdID(11) from New Order Single(D))
41 OrigClOrdId String No The original value assigned by the client in the New Order Single(D) message
39 OrdStatus char Yes For trade – order status.

Possible values:

  • 0 = New,
  • 1 = Partially filled,
  • 2 = Filled,
  • 4 = Cancelled
  • 8 = Rejected
54 Side char Yes Side of order.

Possible values:

  • 1 = Buy,
  • 2 = Sell
60 TransactTime UTCTimestamp Yes Timestamp when the transaction represented by this Execution Report(8) message occurred. Fix timestamp
12 Commission float No Deprecated. Always 0
151 LeavesQty Qty Yes Order quantity open for further execution (LeavesQty = OrderQty - CumQty) in Contract units corresponding to the ContractMultiplier in SecurityList
14 CumQty Qty Yes Total executed quantity or 0.0 in Contract units corresponding to the ContractMultiplier in SecurityList
38 OrderQty Qty Yes Order quantity in Contract units corresponding to the ContractMultiplier in SecurityList
40 OrdType Char No Order type.

Valid values:

  • 1 = Market,
  • 2 = Limit,
  • K = Market With Left Over as Limit (market limit),
  • 4 = Stop limit (trailing stop),
  • J = Market If Touched (stop limit, if StopPx(99) is set),
  • S = Stop Limit on Bid or Offer (stop market, if StopPx(99) is set)
44 Price Price Yes Price
150 ExecType char No Describes the specific Execution Report.

Possible values:

  • I = equal to (Order Status),
  • 7 = (Stopped) for triggered stop orders,
  • 8 = Rejected,
  • 3 = (Done for day) for GTD orders,
  • C = (Expired) for the orders expired at delivery
18 ExecInst MultipleValueString No Currently is used to mark POST ONLY orders and REDUCE ONLY orders.

POST ONLY Possible values:

  • 6 = "Participate don't initiate",
  • A = "No cross" (only together with 6, "6A" -- REJECT POST ONLY when the order is put to the order book unmodified or the request is rejected and order is cancelled),
REDUCE ONLY possible values:
  • E = " Do not increase - DNI"
103 OrdRejReason int Yes Possible reasons:
  • 0 = no reject (the request has been accepted)
  • 1 = Unknown symbol
  • 2 = Exchange closed
  • 3 = Order exceeds limit
  • 4 = Too late to enter
  • 5 = Unknown order
  • 6 = Duplicate Order (e.g. dupe ClOrdID(11))
  • 7 = Duplicate of a verbally communicated order
  • 8 = Stale order
  • 9 = Trade along required
  • 10 = Invalid Investor ID
  • 11 = Unsupported order characteristic
  • 12 = Surveillance Option
  • 13 = Incorrect quantity
  • 14 = Incorrect allocated quantity
  • 15 = Unknown account(s)
  • 16 = Price exceeds current price band
  • 18 = Invalid price increment
  • 99 = Other

Note: Values 3, 4, and 5 will be used when rejecting an order due to pre-allocation information errors.
58 Text String No Free format text string, usually exceptions
207 SecurityExchange String No "Deribit"
55 Symbol String Yes Instrument symbol
99 StopPx Price No Price per unit of quantity
854 QtyType int No Type of quantity specified in a quantity. Currently only 1 - Contracts
211 PegOffsetValue Float No Amount (signed) added to the peg for a pegged order in the context of the PegOffsetType(836)
1094 PegPriceType Int No Needs to be set for Trailing Stop order. Valid value:

  • 8 = Trailing Stop Peg
231 ContractMultiplier float No Specifies a multiply factor to convert from contracts to total units
6 AvgPx float No Average execution price or 0.0 if not executed yet or rejected
1138 DisplayQty Qty No The (max) quantity to be displayed in the orderbook.
9008 DeribitMMProtection Boolean No Order Market Maker Protection (MMP) flag. Important: manual admin action is necessary to activate Market Maker Protection (MMP) for an account
100012 DeribitAdvOrderType int No If it is present then it denotes advanced order for options.

Possible values:

  • 0 = Implied Volatility Order (price defines fixed implied volatility in %),
  • 1 = USD Order (price defines fixed USD price of the option, advanced USD orders are not supported for linear options)
1188 Volatility float No Volatility for Implied Volatility Orders (options orders with fixed volatility)
839 PeggedPrice Price No Value of fixed USD price for USD Orders (options orders with fixed USD price)
31 LastPx Price No Price of this last fill
32 LastQty Qty No Quantity bought/sold on this last fill
100010 DeribitLabel String No A custom label for your order, max 64 grapheme clusters. Can be used by Order Cancel Request(F) to amend the order later on
9019 MMPGroup String No A custom tag of MMP Group. This tag is present only for orders from Mass Quote.
9034 IsLiquidation Boolean No A custom tag, 9034=Y if the order was automatically created during liquidation.
9035 IsRebalance Boolean No A custom tag, 9035=Y if the order was automatically created during cross-collateral balance restoration.
9036 IsRiskReducing Boolean No A custom tag, 9036=Y if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users).
302 QuoteSetID String No identifier for the Quote Set. This tag is present only for orders from Mass Quote.
117 QuoteID String No identifier for the Quote. This tag is present only for orders from Mass Quote.
299 QuoteEntryID String No identifier for the Quote Entry. This tag is present only for orders from Mass Quote.
Group FillsGrp
1362 NoFills NumInGroup No Number of fill entries for the order
=>1363 FillExecID String No Unique identifier of execution, concatenated via '#' symbol and trade sequence number, e.g., BTC-28SEP18#38
=>1364 FillPx Price No Price of this partial fill
=>1365 FillQty Qty No Quantity bought/sold on this partial fill
=>1443 FillLiquidityInd int No Indicator to identify whether this fill was a result of a liquidity provider providing or liquidity taker taking the liquidity.

Possible values:

  • 1 = Added Liquidity,
  • 2 = Removed Liquidity

Order Cancel Request(F)

This message requests the cancellation of a particular order. If an order has been partially filled, only the remaining quantity can be cancelled. The request should be accepted only if an order can successfully be cancelled without executing further. The server generated identifiers should be used as OrigClOrdId.

From Release 1.3.10, it is possible to cancel orders by ClOrdID or DeribitLabel, and OrigClOrdId is not required anymore, however canceling orders by OrigClOrdId is noticeably faster.

IMPORTANT:

Arguments

Tag Name Type Required Comments
11 ClOrdID String Required if OrigClOrdId, DeribitLabel are absent Original order identifier assigned by the user. There must be the only open order with such ClOrdID
41 OrigClOrdId String Required if DeribitLabel, ClOrdID are absent Order identifier assigned by Deribit over the user one
100010 DeribitLabel String Required if OrigClOrdId, ClOrdID are absent A custom label for your order, max 64 grapheme clusters. There must be the only open order with this DeribitLabel otherwise use Order MassCancel Request(q). This tag operates on grapheme clusters. A grapheme cluster is a user-perceived character, which can be represented by several unicode codepoints. Please refer to Unicode specification for more details about the grapheme clusters
55 Symbol String Required if OrigClOrdId is absent Instrument symbol, e.g., BTC-1JAN16
15 Currency String No To speed up the search of the order by DeribitLabel or ClOrdID

Response on failure

Order Cancel Reject(9)

Order Cancel Reject(9) is issued by the exchange upon receipt of Order Cancel Request(F) message which cannot be executed.

Alongside tags listed below, Order Cancel Reject(9) also sends corresponding tag (ClOrdID, OrigClOrdId or DeribitLabel), used by the user to cancel the order in Order Cancel Request(F) or Order Cancel/Replace Request(G).

Tag Name Type Required Comments
52 SendingTime UTCTimestamp Yes Time of message transmission expressed in UTC
39 OrdStatus char No Order status. Present only if applicable.

Possible values:

  • 0 = New,
  • 1 = Partially filled,
  • 4 = Cancelled,
  • 6 = Pending cancel,
  • 8 = Rejected
58 Text String No Text string explaining the reason for rejection
41 OrigClOrdId String No Original order identifier assigned by the user
11 ClOrdID String No Order identifier assigned by Deribit
100010 DeribitLabel String No A custom label for your order

Response on success

The following Execution Report(8) is sent by the exchange upon successfully processing a cancel request.

Tag Name Type Required Comments
52 SendingTime UTCTimestamp Yes Time of message transmission expressed in UTC
11 ClOrdID String No Deribit replaces this field with the own value assigned by the server (it is not the client id from New Order Single(D))
41 OrigClOrdId String No The original value assigned by the client in the New Order Single(D) message
150 ExecType char No Describes the specific Execution Report.

Possible values:

  • 4 = Cancelled,
  • 6 = Pending Cancel
39 OrdStatus char Yes For trade – order status.

Possible values:

  • 0 = New,
  • 1 = Partially filled,
  • 4 = Cancelled,
  • 6 = Pending cancel,
  • 8 = Rejected
58 Text String Yes Text string describing the result

This brief Execution Report comes faster and just indicates that the order was cancelled. Besides this brief report, the server always sends the last state of the cancelled order as another Execution Report with Text="notification" and all details about the cancelled order.

MMP orders: if the Market Maker Protection (MMP) order was cancelled by user request the DeribitMMProtection (9008) flag is removed from the notification Execution Report. Presence of the DeribitMMProtection (9008) flag in the Execution Report with status "cancelled" means that the order has been cancelled by Market Maker Protection (MMP).

Order Mass Cancel Request(q)

Order Mass Cancel Request(q) message will trigger cancellation of a group of orders.

From Release 1.3.10, it is possible to cancel orders by DeribitLabel, and the option 10 of the MassCancelRequestType(530) has been added.

Arguments

Tag Name Type Required Comments
11 ClOrdID String Yes Unique ID of Order Mass Cancel Request(q) as assigned by the client, max 64 grapheme clusters. This tag operates on grapheme clusters. A grapheme cluster is a user-perceived character, which can be represented by several unicode codepoints. Please refer to Unicode specification for more details about the grapheme clusters
530 MassCancelRequestType int Yes Specifies the type of cancellation requested.

Valid values:

  • 7 = all orders,
  • 5 = orders by security type,
  • 1 = orders by symbol,
  • 10 = orders by DeribitLabel
100010 DeribitLabel String if MassCancelRequestType(530)=10 A custom label for your order, max 64 grapheme clusters. Can be used by Order Cancel Request(F) to amend the order later on. Equivalent of REST/WS cancel_by_label
167 SecurityType String If MassCancelRequestType(530)=5 Describes type of security.

Possible values:

  • FUT for futures,
  • OPT for options,
  • FUTCO for future combo,
  • OPTCO for option combo
55 Symbol String If MassCancelRequestType(530)=1 The symbols for which to cancel all orders
15 Currency String No To cancel only certain currency if it is applicable. See Security List Request(x)
9031 FreezeQuotes Boolean No Whether or not to reject incoming quotes for 1 second after cancelling

Response

After the cancellation, the server responds with an Order Mass Cancel Report(r).

Order Mass Cancel Report(r)

Tag Name Type Required Comments
11 ClOrdID String No Unique Identifier assigned by the client in the Order Mass Cancel Request(q)
37 OrderID String No Unique ID assigned by Deribit for this order
530 MassCancelRequestType int Yes Specifies the type of cancellation request.

Possible values:

  • 7 = all orders,
  • 5 = orders by security type,
  • 1 = orders by symbol,
  • 10 = orders by DeribitLabel
  • 11 = quote cancel -- response to Quote Cancel (Z) request used in mass quoting
531 MassCancelResponse int No If successful, echoes the MassCancelRequestType(530)
298 QuoteCancelType int No May be present in case of reply to Quote Cancel (Z) request. 1 = Cancel for Symbol(55), 2 = Cancel for SecurityType (167), 4 = Cancel All Quotes, 5 = for Currency (5), 6 = for QuoteSetID (302), 7 = for Delta range
58 Text String No 'success', if deletion was successful
532 MassCancelRejectReason String No Reason why deletion failed.

Possible values:

  • 1 = Unknown security,
  • 5 = Unknown security type
533 TotalAffectedOrders int No Total number of orders affected by Order Mass Cancel Request(q)
Group AffectedOrdGrp
534 NoAffectedOrders int No Optional field used to indicate the number of order identifiers for orders affected by the Order Mass Cancel Request(q)
=>41 OrigClOrdID String No Required if NoAffectedOrders(534) > 0. Indicates the client order id of an order affected by the Order Mass Cancel Request(q)

Order Mass Status Request(AF)

Order Mass Status Request(AF) message requests the status of currently open orders. The exchange should respond with a series of Execution Reports(8) messages detailing orders.

Arguments

Tag Name Type Required Comments
584 MassStatusReqID String Yes Client-assigned unique ID of this request
585 MassStatusReqType String Yes Specifies the scope of the mass status request. (see below)
9014 MassStatusReqIDType int No For MassStatusReqType=7, it defines which ID or label represents the MassStatusReqID: 0 = OrigClOrdID, 1 = ClOrdId, 2 = DeribitLabel. Default is 0
11 Currency String Required if MassStatusReqIDType is 1 or 2 and Symbol is missing To search the order by DeribitLabel or ClOrdID
55 Symbol String Required if MassStatusReqIDType is 1 or 2 and Currency is missing If Currency is not specified, to search the order by DeribitLabel or ClOrdID
<!-- 9039 OrderHistoryIncludeUnfilled Boolean No
9040 OrderHistoryOffset Integer No The offset for pagination, default - 0. This tag may be used only for MassStatusReqType=10.
911 TotNumReports int No For historical request (MassStatusReqType=10), it defines the number of requested items, default - 100. Maximum value is 1000.

This message can be used in two ways: to request status of all your open orders, or to request the status of a single order(This also applies to closed orders).

To request the status of all orders, choose a random MassStatusRequestId, and set MassStatusReqType=7. The server will respond with a series of Execution Reports(8) messages, where the first message contains MassStatusReqType=7

To request the status of a specific order: set MassStatusReqType=1, and set MassStatusReqId to the order ID. Please keep in mind this message also applies to closed orders.

It is allowed to request status for an order (or several orders) by ClOrdID or DeribitLabel for example when connection is broken and server-side generated ID-s are not received. In that case set MassStatusReqType=7 and set MassStatusReqIDType=1 for the search by ClOrdID or use MassStatusReqIDType=2 for the search by DeribitLabel. In both cases Currency or Symbol are required for such a search.

Response

When the client requests the status of current orders, the exchange should reply with a series of special Execution Reports(8), one for every order requested.

Tag Name Type Required Comments
37 OrderId String No Unique identifier for Order as assigned by the Deribit
11 ClOrdID String No Deribit replaces this field with the own value assigned by the server (it is not the client id from New Order Single(D))
41 OrigClOrdId String No The original value assigned by the client in the New Order Single(D) message
39 OrdStatus char Yes For trade – order status.

Possible values:

  • 0 = New,
  • 1 = Partially filled,
  • 2 = Filled,
  • 4 = Cancelled
  • 8 = Rejected
54 Side char Yes Side of order.

Possible values:

  • 1 = Buy,
  • 2 = Sell
60 TransactTime UTCTimestamp Yes Timestamp when the transaction represented by this Execution Report occurred. Fix timestamp
12 Commission float No Deprecated. Always 0
151 LeavesQty Qty Yes Order quantity open for further execution (LeavesQty = OrderQty - CumQty) in Contract units corresponding to the ContractMultiplier in SecurityList
14 CumQty Qty Yes Total executed quantity or 0.0 in Contract units corresponding to the ContractMultiplier in SecurityList
38 OrderQty Qty Yes Order quantity in Contract units corresponding to the ContractMultiplier in SecurityList
40 OrdType char Yes Order type.

Possible values:

  • 1 = Market,
  • 2 = Limit (by default),
  • 4 = Stop Limit,
  • S = Stop Market
44 Price Price Yes Price
150 ExecType char No Describes the specific Execution Report.

Possible values:

  • I = equal to (Order Status),
  • 7 = (Stopped) for triggered stop orders,
  • 8 = Rejected,
  • 3 = (Done for day) for GTD orders,
  • C = (Expired) for the orders expired at delivery
18 ExecInst MultipleCharValue No CCurrently is used to mark POST ONLY orders and REDUCE ONLY orders.

POST ONLY possible values:

  • 6 = "Participate don't initiate",
  • A = "No cross" (only together with 6, "6A" -- REJECT POST ONLY when the order is put to the order book unmodified or the request is rejected and order is cancelled),
REDUCE ONLY possible values:
  • E = " Do not increase - DNI"
103 OrdRejReason int Yes Possible reasons:
  • 0 = no reject (the request has been accepted)
  • 1 = Unknown symbol
  • 2 = Exchange closed
  • 3 = Order exceeds limit
  • 4 = Too late to enter
  • 5 = Unknown order
  • 6 = Duplicate Order (e.g. dupe ClOrdID(11))
  • 7 = Duplicate of a verbally communicated order
  • 8 = Stale order
  • 9 = Trade along required
  • 10 = Invalid Investor ID
  • 11 = Unsupported order characteristic
  • 12 = Surveillance Option
  • 13 = Incorrect quantity
  • 14 = Incorrect allocated quantity
  • 15 = Unknown account(s)
  • 16 = Price exceeds current price band
  • 18 = Invalid price increment
  • 99 = Other

Note: Values 3, 4, and 5 will be used when rejecting an order due to pre-allocation information errors.
58 Text String No Free format text string, usually exceptions
207 SecurityExchange String No "Deribit"
55 Symbol String Yes Instrument symbol
854 QtyType String No Type of quantity specified in a quantity. Currently only 1 - Contracts
231 ContractMultiplier float No Specifies a multiply factor to convert from contracts to total units
6 AvgPx float No Average execution price or 0.0 if not executed yet or rejected
1138 DisplayQty Qty No The (max) quantity to be displayed in the orderbook. Contract units corresponding to the ContractMultiplier in SecurityList
9008 DeribitMMProtection Boolean No Order Market Maker Protection (MMP) flag. Important: manual admin action is necessary to activate Market Maker Protection MMP for an account
100012 DeribitAdvOrderType char No If it is present then it denotes advanced order for options.

Possible values:

  • 0 = Implied Volatility Order (price defines fixed implied volatility in %),
  • 1 = USD Order (price defines fixed USD price of the option, advanced USD orders are not supported for linear options)
1188 Volatility float No Volatility for Implied Volatility Orders (options orders with fixed volatility)
839 PeggedPrice Price No Value of fixed USD price for USD Orders (options orders with fixed USD price)
31 LastPx Price No Price of this last fill
32 LastQty Qty No Quantity bought/sold on this last fill.
100010 DeribitLabel String No A custom label for your order, max 64 grapheme clusters. Can be used by Order Cancel Request(F) to amend the order later on. This tag operates on grapheme clusters. A grapheme cluster is a user-perceived character, which can be represented by several unicode codepoints. Please refer to Unicode specification for more details about the grapheme clusters
9019 MMPGroup String No A custom tag of MMP Group. This tag is present only for orders from Mass Quote
302 QuoteSetID String No identifier for the Quote Set. This tag is present only for orders from Mass Quote.
117 QuoteID String No identifier for the Quote. This tag is present only for orders from Mass Quote.
299 QuoteEntryID String No identifier for the Quote Entry. This tag is present only for orders from Mass Quote.
Group FillsGrp
1362 NoFills NumInGroup No Number of fill entries for the order
=>1363 FillExecID String No Unique identifier of execution, concatenated via '#' symbol and trade sequence number, e.g., BTC-28SEP18#38
=>1364 FillPx Price No Price of this partial fill
=>1365 FillQty Qty No Quantity bought/sold on this partial fill
=>1443 FillLiquidityInd int No Indicator to identify whether this fill was a result of a liquidity provider providing or liquidity taker taking the liquidity.

Possible values:

  • 1 = Added Liquidity,
  • 2 = Removed Liquidity

When responding to a MassStatusReqType=7 request, the server precedes the Execution Reports(8) messages with a special Execution Reports(8) message:

Tag Name Type Required Comments
584 MassStatusReqID String Yes The MassStatusReqID from the request. (Only for the first message response to a MassStatusReqType=7 request.)
585 MassStatusReqType int Yes The MassStatusReqType from the request. (Only for the first message response to a MassStatusReqType=7 request.)
911 TotNumReports int Yes The total number of reports following this initial report

Request For Positions(AN)

Request For Positions(AN) is used by the owner of a position to request a Position Report.

Arguments

Tag Name Type Required Comments
710 PosReqID String Yes Unique identifier for the Request for Positions(AN) as assigned by the submitter
724 PosReqType int Yes 0 = Positions (currently)
263 SubscriptionRequestType int No Subscription Request Type to get notifications about new or terminated instruments. Valid values:
  • 0 = Snapshot,
  • 1 = Snapshot + Updates (Subscribe),
  • 2 = Disable previous Snapshot + Update Request (Unsubscribe)
15 Currency String No To request for certain currency only. If it is missing, all currencies are reported

Response

The server will respond with a Position Report(AP) message.

Position Report(AP)

The Position Report(AP) message is returned by the holder of a position in response to a Request For Positions(AN) message.

Arguments

Tag Name Type Required Comments
721 PosMaintRptID String Yes Unique identifier for this position report
710 PosReqID String No Unique identifier for the Request for Positions associated with this report
724 PosReqType int No Used to specify the type of position request being made. 0 = Positions (currently)
728 PosReqResult int No Result of a Request for Position.

Possible values:

  • 0 = success,
  • 1 = unsupported request for positions,
  • 99 = other
Group PositionQty
702 NoPositions NumInGroup No Number of position entries following
=>703 PosType String No Type of quantity.

Possible values:

  • TQ = Transaction Quantity
=>704 LongQty Qty No Qty for long position (0 for short position) in Contract units corresponding to the ContractMultiplier in SecurityList
=>705 ShortQty Qty No Qty for short position (0 for long position) in Contract units corresponding to the ContractMultiplier in SecurityList
=>55 Symbol String No Instrument symbol
=>854 QtyType int No Type of quantity specified in a quantity. Currently only 1 - Contracts
=>231 ContractMultiplier float No Specifies a multiply factor to convert from contracts to total units
=>883 UnderlyingEndPrice Price No Mark price (reference price)
=>54 Side char No Side of order.

Possible values:

  • 1 = Buy,
  • 2 = Sell
=>730 SettlPrice Price No Average price
=>96 RawData String No Additional info, semi-colon separated: maintenance margin;initial margin;floating P/L
=>100088 DeribitLiquidationPrice Price No Estimated liquidation price
=>100089 DeribitSizeInCurrency Qty No Size in the underlying currency, for example BTC or ETH

User Request(BE)

This message is used to request a report on a user's status and user account info.

Arguments

Tag Name Type Required Comments
923 UserRequestID String Yes The request ID
924 UserRequestType int Yes Should be equal to 4 (Request individual user status), only UserRequestType=4 supported for now
553 Username String Yes API authenticated 'Client ID', user can request only own info, should be the same as for LOGON(A)
15 Currency String No Currency of the report. See Security List Request(x). Default is BTC.

If CROSS is given as currency and user has cross collateral enabled, only the following fields are returned:

  • 100001 DeribitUserEquity
  • 100003 DeribitUserInitialMargin
  • 100004 DeribitUserMaintenanceMargin
  • 100013 DeribitMarginBalance

Response

The server will respond with a User Response(BF) message.

User Response(BF)

This message is used to respond to a USER REQUEST(BE) message, it reports the status of the user and user's account info.

Response

Tag Name Type Required Comments
923 UserRequestID String Yes The request ID
553 Username String Yes User's API 'Client ID'
926 UserStatus int No 1 = logged in, current implementation accepts USER REQUEST-s only from logged in users
15 Currency String No Currency of the report. See Security List Request(x). Default is BTC.

If CROSS is given as currency and user has cross collateral enabled, only the following fields are returned:

  • 100001 DeribitUserEquity
  • 100003 DeribitUserInitialMargin
  • 100004 DeribitUserMaintenanceMargin
  • 100013 DeribitMarginBalance
100001 DeribitUserEquity float No Equity of the user
100002 DeribitUserBalance float No Balance of the user
100003 DeribitUserInitialMargin float No Initial margin of the user
100004 DeribitUserMaintenanceMargin float No Maintenance margin of the user
100005 DeribitUnrealizedPl float No Unrealized P/L of the user
100006 DeribitRealizedPl float No Realized P/L of the user
100011 DeribitTotalPl float No Total P/L of the user
100013 DeribitMarginBalance float No Margin Balance

Order Cancel/Replace Request(G)

To change/edit the parameters of an existing order

From Release 1.3.10, it is possible to amend order by ClOrdID or DeribitLabel, and OrigClOrdId is not required anymore, however amending orders by OrigClOrdId is noticeably faster.

IMPORTANT:

Arguments

Tag Name Type Required Comments
11 ClOrdID String Required if DeribitLabel, OrigClOrdId are absent Original order identifier assigned by the user, max 64 grapheme clusters. This tag operates on grapheme clusters. A grapheme cluster is a user-perceived character, which can be represented by several unicode codepoints. Please refer to Unicode specification for more details about the grapheme clusters
41 OrigClOrdId String Required if DeribitLabel, ClOrdID are absent Order identifier assigned by Deribit over the user one
100010 DeribitLabel String Required if OrigClOrdId, ClOrdID are absent A custom label for your order, max 64 grapheme clusters. Can be used by Order Cancel Request(F) to amend the order later on
55 Symbol String Yes Instrument symbol, e.g., BTC-1JAN16
62 ValidUntilTime UTCTimestamp No Indicates expiration time of indication message, in UTC
15 Currency String No To speed up the search of the order by DeribitLabel or ClOrdID
54 Side char Yes Should match the original order's side.

Valid values:

  • 1 = Buy,
  • 2 = Sell
38 OrderQty Qty Yes Order quantity. Depends on QtyType. When QtyType is set to Units, the OrderQty is specified in USD for perpetual and inverse futures, in the underlying base currency coin for linear futures, or in the amount of cryptocurrency contracts for options. The system will automatically convert Units to Contracts when the order is placed Please, note that Quantity is by default defined in Contract units corresponding to the ContractMultiplier in SecurityList
40 OrdType char No Currently 2 - 'limit'
44 Price Price No Order price (for advanced options orders it could be volatility or USD value if applicable)
18 ExecInst MultipleCharValue No Currently is used to mark POST ONLY orders and REDUCE ONLY orders.

POST ONLY valid values:

  • 6 = "Participate don't initiate",
  • A = "No cross" (only together with 6, "6A" -- REJECT POST ONLY when the order is put to order the book unmodified or the request is rejected and order is cancelled),
REDUCE ONLY valid values:
  • E = " Do not increase - DNI"
854 QtyType Int No Type of quantity. Valid values:

  • 0 = Units,
  • 1 = Contracts

Default is Contracts.

When QtyType is Units, then for perpetual and inverse futures the OrderQty is in USD units, and for linear futures it is the underlying base currency coin, and for options it is the amount of corresponding cryptocurrency contracts, e.g., BTC or ETH. The Units will be recalculated into the system's Contracts on server automatically when the order is placed.
1138 DisplayQty Qty No The (max) quantity to be displayed in the orderbook.
9008 DeribitMMProtection Boolean No Order Market Maker Protection (MMP) flag, if it is absent then the current MMP flag of the order is not changed. N removes the flag if it is set. Important: manual admin action is necessary to activate Market Maker Protection (MMP) for an account

Response

See New Order Single(D) response

Execution Reports(8) about order changes

Notification

The report Execution Reports(8) is similar to New Order Single or Cancel/Replace responses

Tag Name Type Required Comments
527 SecondaryExecID String No ID of the order change, may be absent in case of status reports
37 OrderId String No Unique identifier for Order as assigned by the Deribit
11 ClOrdID String No Deribit replaces this field with the own value assigned by the server (it is not the client id from New Order Single(D))
41 OrigClOrdId String No The original value assigned by the client in the New Order Single(D) message
39 OrdStatus char Yes For trade – order status.

Possible values:

  • 0 = New,
  • 1 = Partially filled,
  • 2 = Filled,
  • 4 = Cancelled
  • 8 = Rejected
54 Side char Yes Side of order.

Possible values:

  • 1 = Buy,
  • 2 = Sell
60 TransactTime UTCTimestamp Yes Time the transaction represented by this Execution Report occurred. Fix timestamp
12 Commission float No Deprecated. Always 0
151 LeavesQty Qty Yes Order quantity open for further execution (LeavesQty = OrderQty - CumQty) in Contract units corresponding to the ContractMultiplier in SecurityList
14 CumQty Qty Yes Total executed quantity or 0.0 in Contract units corresponding to the ContractMultiplier in SecurityList
38 OrderQty Qty Yes Order quantity in Contract units corresponding to the ContractMultiplier in SecurityList
5127 ConditionTriggerMethod int No Trigger for a stop order.

Possible values:

  • 1 = Mark Price,
  • 2 = Last Price,
  • 3 = corresponding Index Price
40 OrdType char Yes Order type.

Possible values:

  • 1 = Market,
  • 2 = Limit,
  • 4 = Stop Limit,
  • S = Stop Market (default: limit)
44 Price Price No Price, maybe be absent for Market and Stop Market orders
150 ExecType char No Describes the specific Execution Report.

Possible values:

  • I = equal to (Order Status),
  • 7 = (Stopped) for triggered stop orders,
  • 8 = Rejected,
  • 3 = (Done for day) for GTD orders,
  • C = (Expired) for the orders expired at delivery
18 ExecInst MultipleValueString No Currently is used to mark POST ONLY orders and REDUCE ONLY orders.

POST ONLY possible values:

  • 6 = "Participate don't initiate",
  • A = "No cross" (only together with 6, "6A" -- REJECT POST ONLY when the order is put to the order book unmodified or the request is rejected and order is cancelled),
REDUCE ONLY possible values:
  • E = " Do not increase - DNI"
99 StopPx Price No Stop price for stop limit orders
103 OrdRejReason int Yes Possible reasons:
  • 0 = no reject (the request has been accepted)
  • 1 = Unknown symbol
  • 2 = Exchange closed
  • 3 = Order exceeds limit
  • 4 = Too late to enter
  • 5 = Unknown order
  • 6 = Duplicate Order (e.g. dupe ClOrdID(11))
  • 7 = Duplicate of a verbally communicated order
  • 8 = Stale order
  • 9 = Trade along required
  • 10 = Invalid Investor ID
  • 11 = Unsupported order characteristic
  • 12 = Surveillance Option
  • 13 = Incorrect quantity
  • 14 = Incorrect allocated quantity
  • 15 = Unknown account(s)
  • 16 = Price exceeds current price band
  • 18 = Invalid price increment
  • 99 = Other

Note: Values 3, 4, and 5 will be used when rejecting an order due to pre-allocation information errors.
58 Text String No Free format text string, usually exceptions
207 SecurityExchange String No "Deribit"
55 Symbol String Yes Instrument symbol
854 QtyType int No Type of quantity specified in a quantity. Currently only 1 - Contracts
231 ContractMultiplier float No Specifies a multiply factor to convert from contracts to total units
6 AvgPx float No Average execution price or 0.0 if not executed yet or rejected
1138 DisplayQty Qty No The (max) quantity to be displayed in the orderbook.
100012 DeribitAdvOrderType int No If it is present then it denotes advanced order for options.

Possible values:

  • 0 = Implied Volatility Order (price defines fixed implied volatility in %),
  • 1 = USD Order (price defines fixed USD price of the option, advanced USD orders are not supported for linear options)
1188 Volatility float No Volatility for Implied Volatility Orders (options orders with fixed volatility)
839 PeggedPrice Price No Value of fixed USD price for USD Orders (options orders with fixed USD price)
31 LastPx Price No Price of this last fill
32 LastQty Qty No Quantity bought/sold on this last fill
880 TrdMatchID String No Identifier assigned to a trade by a matching system. It can be present for trade execution reports if Logon 9015=Y
100010 DeribitLabel String No A custom label for your order, max 64 grapheme clusters. Can be used by Order Cancel Request(F) to amend the order later on. This tag operates on grapheme clusters. A grapheme cluster is a user-perceived character, which can be represented by several unicode codepoints. Please refer to Unicode specification for more details about the grapheme clusters
9008 DeribitMMProtection Boolean No Order Market Maker Protection (MMP) flag
9019 MMPGroup String No A custom tag of MMP Group. This tag is present only for orders from Mass Quote
302 QuoteSetID String No identifier for the Quote Set. This tag is present only for orders from Mass Quote.
117 QuoteID String No identifier for the Quote. This tag is present only for orders from Mass Quote.
299 QuoteEntryID String No identifier for the Quote Entry. This tag is present only for orders from Mass Quote.
Group FillsGrp
1362 NoFills NumInGroup No Number of fill entries for the order
=>1363 FillExecID String No Unique identifier of execution, concatenated via '#' symbol and trade sequence number, e.g., BTC-28SEP18#38
=>1364 FillPx Price No Price of this partial fill
=>1365 FillQty Qty No Quantity bought/sold on this partial fill
=>1443 FillLiquidityInd int No Indicator to identify whether this fill was a result of a liquidity provider providing or liquidity taker taking the liquidity.

Possible values:

  • 1 = Added Liquidity,
  • 2 = Removed Liquidity

Security Status Request(e)

This message provides for the ability to request the status of a security.

Arguments

Tag Name Type Required Comments
324 SecurityStatusReqID String Yes ID of the request
55 Symbol String Yes Instrument symbol. See instrument naming convention for more details
263 SubscriptionRequestType char Yes 0 = Snapshot, 1 = Snapshot + Updates (Subscribe), 2 = Unsubscribe

(Please note that our system does not send notifications when currencies are locked. Users are advised to subscribe to the platform_state channel to monitor the state of currencies actively.)

Response

The server will respond with a Security Status (f) message.

Security Status (f)

The Security Status (f) message provides for the ability to report changes in status to a security.

Response

Tag Name Type Required Comments
324 SecurityStatusReqID String No ID of the request
55 Symbol String Yes Instrument symbol
326 SecurityTradingStatus int No Identifies the trading status.

Possible values:

  • 7 = Ready to trade,
  • 8 = Not Available for trading,
  • 20 = Unknown or Invalid
330 BuyVolume float No Volume in buy contracts, absent if there weren't any trades
331 SellVolume float No Volume in sell contracts, absent if there weren't any trades
332 HighPx Price No Price of the 24h highest trade, absent if there weren't any trades
333 LowPx Price No Price of the 24h lowest trade, absent if there weren't any trades
31 LastPx Price No The price of the latest trade, absent if there weren't any trades
58 Text String No Explanatory text string of SubscriptionRequestType outcome.

Possible values:

  • success = Snapshot successfully provided,
  • subscribed = Subscription confirmed,
  • unsubscribed = Subscription cancelled

MMProtection Limits (MM)

Important: manual admin action is necessary to activate Market Maker Protection (MMP) for an account. The MMProtection Limits (MM) message can be used to set or get the limits for Market Maker Protection (MMP) for a currency pair.

Arguments

Tag Name Type Required Comments
20114 ProtectionRequestID String Yes Unique identifier assigned by the requestor. Will be returned in responses
15 Currency String Yes First currency of the currency pair to set or get MMP for e.g. BTC, ETH
5544 SecondaryCurrency String No Secondary currency of the currency pair to set or get MMP for. e.g. USD, USDC, defaults to USD if not provided
20110 ProtectionQtyLimit float No Specify the limit of the total traded contracts per underlying within the exposure time interval when market maker protection is triggered. When this value is met or exceeded the system automatically removes the quotes for the instruments connected to the underlying
20111 ProtectionDeltaLimit float No The limit of the delta value per underlying within the exposure time interval when market maker protection is triggered. When this value is met or exceeded the system automatically removes the quotes for the instruments connected to the underlying
20112 FrozenLimit float Yes Time interval in seconds when quotes are rejected after market maker protection has been triggered
20116 IntervalLength int Yes Interval Length in seconds
20118 ProtectionVegaLimit float No The limit of the vega value per underlying within the exposure time interval when market maker protection is triggered. When this value is met or exceeded the system automatically removes the quotes for the instruments connected to the underlying
9019 MMPGroup String No A custom tag of MMP Group

MMProtection Limits Result/Reject (MR)

Important: manual admin action is necessary to activate Market Maker Protection (MMP) for an account. This message is sent by the server in reply to MMProtection Limits (MM) or MMProtectionReset (MZ)

Response

Tag Name Type Required Comments
20114 ProtectionRequestID String Yes Identifier taken from corresponding MM or MZ message
20117 ProtectionRequestResult Boolean Yes Y = applied or succeeded, N = rejected
58 Text String No Text describes reject reason or equal to "success"

MMProtection Reset (MZ)

Important: manual admin action is necessary to activate Market Maker Protection (MMP) for an account. This message resets Market Maker Protection (MMP) after triggering.

Arguments

Tag Name Type Required Comments
20114 ProtectionRequestID String Yes Unique identifier assigned by the requestor. Will be returned in responses
15 Currency String Yes First currency of the currency pair to reset MMP for. e.g. BTC, ETH
5544 SecondaryCurrency String No Secondary currency of the currency pair to reset MMP for. e.g. USD, USDC, defaults to USD if not provided
9019 MMPGroup String No A custom tag of MMP Group

Response

The server sends MMProtection Result (MR) message as a response.

Security Definition Request (c)

Request a specific Security to be traded with the second party. The request security is defined as a multileg security made up of two or more instrument legs. Also it can be used to query a list of combo-instrument securities offered by a trading parties. (this method is FIX equivalent of private/create_combo, public/get_combo_ids and private/get_combo_details request for WS/HTTPS end-points depending on SecurityRequestType (321) tag value).

Arguments

Tag Name Type Required Comments
320 SecurityReqID String Yes Request identifier
321 SecurityRequestType int Yes Type of Security Definition Request(c).

Valid values:

  • 0 = Request Security details, specifications by SecurityId,
  • 1 = Request Security identity for the specifications provided, the combo-instrument will be created if necessary.
  • 3 = Request list of existing combo-instruments
15 Currency String Yes Required is SecurityRequestType = 3, examples: BTC, ETH
48 SecurityID String No Required if SecurityRequestType = 0. Identifies combo instrument.
Group InstrmtLegGrp
555 NoLegs int Yes Number of legs that make up the Security
=>600 LegSymbol String No Non-combo instrument name
=>624 LegSide char No Valid values:
  • 1 = Buy,
  • 2 = Sell
=>623 LegRatioQty int No Positive integer for the strategy

Response

The server sends Security Definition (d) message as a response, or rejects the request

Security Definition (d)

The Security Definition message is used for the following:

Tag Name Type Required Comments
320 SecurityReqID String Yes Request identifier
322 SecurityResponseID sting Yes Equal to the SecurityReqID
323 SecurityResponseType int Yes Type of Security Definition response.

Valid values:

  • 2 = accept security proposal with possible revisions as indicated in the message,
  • 5 = reject proposal
55 Symbol String No Common, "human understood" representation of the security
48 SecurityID String No Takes precedence in identifying security to counterparty.
22 SecurityIDSource String No 101 = Multi-cast identifier, 102 = Combo instrument identifier
225 IssueDate UTCTimestamp No Creation timestamp
873 DatedDate UTCTimestamp No State timestamp
58 Text String No Explanatory text string
Group UnderlyingInstrument
711 NoUnderlyings int No Number of underlying items in the group, if applicable. Underlying group is present in reply to Security Definition Request (c) with SecurityRequestType(321) = 3
=>311 UnderlyingSymbol String No Combo-instrument symbols in reply to Security Definition Request (c) with SecurityRequestType(321) = 3
965 SecurityStatus String No Denotes the current state of the Instrument.

Valid values:

  • 1 = Active,
  • 2 = Inactive,
  • 3 = RFQ,
  • 4 = Closed,
  • 12 = Archivized
Group InstrmtLegGrp
555 NoLegs int Yes Number of legs that make up the Security
=>600 LegSymbol String No Non-combo instrument name
=>623 LegRatioQty int No Positive or negative adjusted to the strategy definition

Quote Request (R)

The message for requesting for quotes from Deribit RFQ market. The request can be used as the equivalent of WS/REST private/send_rfq, as well as can be received via RFQ subscription or in the snapshots.

Tag Name Type Required Comments
131 QuoteReqID String Yes Request identifier
58 Text String No Explanatory text string
387 TotalVolumeTraded Qty No Traded volume
60 TransactTime UTCTimestamp No Update time (last trade or when requested)
Group QuotReqGrp
146 NoRelatedSym int Yes Number of related symbols in Request. Currently it must be equal to 1, only 1 symbol is supported for now
=>55 Symbol String No Common, "human understood" representation of the security
=>167 SecurityType String No Describes type of security.

Valid values:

  • FUT for futures,
  • OPT for options,
  • FUTCO for future combo,
  • OPTCO for option combo
=>54 Side char No Side of order.

Valid values:

  • 1 = Buy,
  • 2 = Sell
=>38 OrderQty Qty No Order quantity in contracts

Response

In case of success, the response will be a Quote Status Report (AI). If the request fails, the Quote Request Reject (AG) will be sent, or session level Reject(3) if processing of request is impossible.

Quote Request Reject (AG)

Tag Name Type Required Comments
131 QuoteReqID String Yes Request identifier
658 QuoteRequestRejectReason int Yes Reason QuoteRequest (R) was rejected:
  • 101 = exceeded rate limit,
  • 102 = service unavailable temporary,
  • 3 = limit exceeded,
  • 1 = non-implemented feature requested,
  • 6 = account is not authorized to request quote,
  • 99 = other reason of reject
58 Text String No Text describes the reject reason.

Possible values:

  • 1 = missing or unknown symbol,
  • 3 = quote request exceeds limit,
  • 6 = account is locked,
  • 99 = other reason,
  • 101 = rate limit exceeded,
  • 102 = temporary unavailable
Group QuotReqRjctGrp
146 NoRelatedSym int Yes Number of related symbols in Request
=>55 Symbol String No Common, "human understood" representation of the security

Quote Status Report (AI)

The message is used in response to Quote Request (R) and also for reporting expired quotes when a user subscribes for quotes via RFQ Request (AH).

Tag Name Type Required Comments
131 QuoteReqID String No Request identifier which triggered the report, if applicable
117 QuoteID int No Unique identifier for quote
297 QuoteStatus int Yes Identifies the status of the quote acknowledgement.

Possible values:

  • 0 = Accepted,
  • 7 = Expired
55 Symbol String No Common, "human understood" representation of the security
54 Side int No Side of order.

Possible values:

  • 1 = Buy,
  • 2 = Sell
60 TransactTime UTCTimestamp No Timestamp for last trade or quote creation
58 Text String No Explanatory text string

RFQ Request (AH)

RFQ request is sent by trader interested in receiving quote requests from other traders. It is possible to subscribe for new quotes as well as to get a snapshot of the current quotes in the system.

Tag Name Type Required Comments
644 RFQReqID String Yes Request ID
15 Currency Currency Yes Base currency which quotes requester is interested in
167 SecurityType String No Describes type of security.

Valid values:

  • FUT for futures,
  • OPT for options,
  • FUTCO for future combo,
  • OPTCO for option combo
263 SubscriptionRequestType char No Subscription Request Type to get notifications about new or terminated instruments. Valid values:
  • 0 = Snapshot,
  • 1 = Snapshot + Updates (Subscribe),
  • 2 = Disable previous Snapshot + Update Request (Unsubscribe)

Response

RFQ request can be used to request existing Quote Requests (R) as well as to subscribe for new Quote Requests (R) and Quote Status Reports (AI) about expiration of the requests.

TradeCaptureReportRequest (AD)

Request one or more trade capture reports based upon selection criteria provided on the trade capture report request.

Tag Name Type Required Comments
568 TradeRequestID String Yes Identifier for the trade request
569 TradeRequestType Int Yes Describes request type.

Valid value:

  • 0 for all trades
55 Symbol String Yes Common, "human understood" representation of the security, e.g., BTC-28JUL17, see instrument naming convention for more details
263 SubscriptionRequestType char No Used to subscribe / unsubscribe for trade capture reports If the field is absent, the value 1 will be the default (subscription). Valid values:

  • 1 = Subscribe
  • 2 = Unsubscribe
(Note: 0 = Snapshot is not implemented for now)

TradeCaptureReportRequestAck (AQ)

The Trade Capture Request Ack message is used to: * Provide an acknowledgement to a Trade Capture Report Request in the case where the Trade Capture Report Request is used to specify a subscription. * The Trade Capture Request was invalid for some business reason, such as the request is not authorized, invalid or unknown instrument, party, trading session, etc.

Tag Name Type Required Comments
568 TradeRequestID String Yes Identifier for the trade request
569 TradeRequestType Int Yes Describes request type.

Valid value:

  • 0 for all trades
571 TradeRequestResult Int Yes Result of Trade Request.

Valid values:

  • 0 - Successful
  • 2 - Invalid type of trade requested
750 TradeRequestStatus Int Yes Status of Trade Request.

Valid values:

  • 0 - Accepted
  • 2 - Rejected
55 Symbol String Yes Common, "human understood" representation of the security, e.g., BTC-28JUL17, see instrument naming convention for more details

TradeCaptureReport (AE)

Used to report trades between counterparties.

Tag Name Type Required Comments
568 TradeRequestId String No Request ID if the Trade Capture Report is in response to a Trade Capture Report Request
570 PreviouslyReported Boolean Yes Indicates if the trade capture report was previously reported to the counterparty
55 Symbol String Yes Common, "human understood" representation of the security, e.g., BTC-28JUL17, see instrument naming convention for more details
32 LastQty Qty Yes Trade Quantity
31 LastPx Price Yes Trade Price
1003 TradeId String Yes The unique ID assigned to the trade
1040 SecondaryTradeId String No Block Trade ID or Combo Trade ID
75 TradeDate LocalMktDate Yes Indicates date of trade referenced in this message in YYYYMMDD format.
60 TransactTime UTCTimestamp Yes Time of execution/order creation (expressed in UTC (Universal Time Coordinated, also known as "GMT")
555 NoLegs NumInGroup No Number of legs. Identifies a Multi-leg Execution if present and non-zero.
=>600 LegSymbol String No Multileg instrument's individual security's Symbol.
=>687 LegQty Qty Yes Quantity of the leg
=>566 LegPrice Price Yes Price for leg of a multileg
=>624 LegSide Char Yes The side of this individual leg (multileg security).

Valid values:

  • 1 - Buy
  • 2- Sell
552 NoSides NumInGroup Yes Number of sides
=>54 Side Char Yes Side of order.

Valid values:

  • 1 - Buy
  • 2- Sell
=>37 OrderId String Yes Unique identifier for Order as assigned by sell-side
=>12 Commission Amt Yes Commission deducted from the requesting party
=>479 CommCurrency Currency Yes Specifies currency to be use for Commission <12>

Mass Quote (i)

Place buy and/or sell orders on one or more instruments. This endpoint can only be used after approval from the administrators. The repeating group structure follows the standard FIX specification, as follows:

Tag Name Type Required Comments
117 QuoteID String Yes Identifier of a mass quote message. Can be used to match trades to requests. We recommend using an incrementing counter.
9019 MMPGroup String Yes Custom tag of the MMP group. An MMP group has to be used and only one quote can exist per instrument per side per MMP group.
62 ValidUntilTime UTCTimestamp No Indicates expiration time of indication for the request, in UTC.
296 NoQuoteSets NumInGroup Yes The number of QuoteSets in the repeating group.
=> 302 QuoteSetID String Yes Identifier for the QuoteSet. Can be used in Quote Cancel (Z).
=> 304 TotNoQuoteEntries int No Total number of quotes for the quote set. IMPORTANT: For now, splitting QuoteSets over several messages is not supported.
=> 295 NoQuoteEntries NumInGroup Yes Number of quotes in the QuoteSet repeating group.
=> => 299 QuoteEntryID String Yes Identifier of the quote. It is echoed in the Mass Quote Acknowledgement (b).
=> => 55 Symbol String Yes Common, "human understood" representation of the security, e.g., BTC-28JUL17, see instrument naming convention for more details.
=> => 132 BidPx Price No Bid price. If no price is supplied, only the quantity is amended.
=> => 133 OfferPx Price No Offer price. If no price is supplied, only the quantity is amended.
=> => 134 BidSize Qty No Bid quantity in contracts. If no quantity is supplied, only the price is amended.
=> => 135 OfferSize Qty No Offer quantity in contracts. If no quantity is supplied, only the price is amended.
=> => 18 ExecInst MultipleCharValue No Supports post-only and post-only-reject, see NewOrderSingle (D).

Mass Quote (i) requires Cancel On Disconnect enabled and MMP.

Request example:

MassQuote QuoteID="MyQuote1" 9019="default" NoQuote_sets=1 QuoteSetID=1 TotNoQuoteEntries=2 NoQuoteEntries=2 QuoteEntry_id=1 Symbol="BTC-PERPETUAL" BidPx=41000.0 OfferPx=42000.0 BidSize=10.0 OfferSize=10.0 QuoteEntryID=2 Symbol="BTC-29DEC23" BidPx=41500.0 BidSize=5.0

In reply to Mass Quote (i), the server sends Mass Quote Acknowledgement (b) message as well as corresponding Execution Report-s (8). The reports and acknowledgement are send asynchronously and via different queues, so the precedence of acknowledgement message is not guaranteed.

Mass Quote Acknowledgement (b)

Mass Quote Acknowledgement (b) is a reply to a Mass Quote (i) message. The message contains orders, trades and possible errors resulting from the Mass Quote (i) message. The QuoteEntries are not grouped by QuoteSets for performance reasons, only marked with QuoteSetIDs.

Tag Name Type Required Comments
117 QuoteID String No The same QuoteID as supplied in the Mass Quote (i) message.
297 QuoteStatus int Yes Status of the mass quote as a whole. 0 = Accepted, 5 = Rejected
300 QuoteRejectReason int No Reason Mass Quote (i) was rejected. 1 = Unknown symbol (Security), 2 = Exchange(Security) closed, 3 = Mass Quote (i) size exceeds limit, 4 = Timed out (Too late to enter), 9 = Not allowed to quote security, 99 = Other
295 NoQuoteEntries NumInGroup No Number of quotes in the repeating group.
=> 299 QuoteEntryID String No Echoed from the Mass Quote (i) message for orders. For trades, it is the trade ID.
=> 9020 QuoteEntryType int No 0 = order, 1 = trade, 2 = error
=> 302 QuoteSetID String No Identifier of the QuoteSet supplied in Mass Quote (i). Only present for orders.
=> 1167 QuoteEntryStatus int No Status of individual Quote Entry. 0 = Accepted, 5 = Rejected, 17 = Cancelled, 0 = Accepted, 5 = Rejected, 17 = Cancelled, 18 = Cancelled by MMP, 19 = Replaced, 20 = Filled, 21 = Open, 22 = Closed, 23 = Triggered, 24 = Untriggered, 25 = Unknown
=> 55 Symbol String No Common, "human understood" representation of the security, e.g., BTC-28JUL17, see instrument naming convention for more details.
=> 54 Side char No Side of the entry.
=> 192 OrderQty2 Qty No Size of the trade in contracts, in case of a trade.
=> 37 OrderId String No Unique identifier of the quote, assigned by the exchange. It follows the format of OrderIDs for regular orders.
=> 60 TransactTime UTCTimestamp No Timestamp of the transaction.
=> 132 BidPx Price No Bid price.
=> 134 BidSize Qty No Bid quantity in contracts.
=> 133 OfferPx Price No Offer price.
=> 135 OfferSize Qty No Offer quantity in contracts.
=> 368 QuoteEntryRejectReason int No RPC error code, in case of an error.
=> 58 Text String No The error description, in case of an error.

Quote Cancel (Z)

The Quote Cancel (Z) message is used by an originator of quotes to cancel his quotes and related orders.

The Quote Cancel message supports cancelation of: * All quotes * Quotes for a specific symbol * All quotes for a security kind (like futures, options) * By QuoteSetID * By base Currency of the instruments * By Delta range

The canceling is accomplished by indicating the type of cancelation in the QuoteCancelType (298) field and optional additional parameters.

The message is equivalent of the private/cancel_quotes and shares the same semantic, so it is quite different from the other exchanges. The same as the Websockets "alter-ego" it is acknowledged only via list (possibly empty) of cancelled orders, namely as the Order Mass Cancel Report (r) with ClOrdID equal to the QuoteMsgID of the request, with the affected order ID's and subsequent Execution Report (8)-s for each individual cancelled order if there are any.

Tag Name Type Required Comments
1166 QuoteMsgID String No Optionally used to supply a message identifier for a quote cancel.
298 QuoteCancelType int No Default is 4. Identifies the type of Quote Cancel (Z) request. 1 = Cancel for Symbol(55), 2 = Cancel for SecurityType (167), 4 = Cancel All Quotes, 5 = for Currency (5), 6 = for QuoteSetID (302), 7 = for Delta range defined by MinDelta and MaxDelta see below
55 Symbol String Required if QuoteCancelType = 1 Common, "human understood" representation of the security, e.g., BTC-28JUL17, see instrument naming convention for more details.
15 Currency String if QuoteCancelType = 2, 5 or 7 Currency
9031 FreezeQuotes Boolean No Whether or not to reject incoming quotes for 1 second after cancelling
167 SecurityType String If QuoteCancelType=2 Describes type of security.

Possible values:

  • FUT for futures,
  • OPT for options,
  • FUTCO for future combo,
  • OPTCO for option combo
  • SPOT for spot
302 QuoteSetID String Required if QuoteCancelType = 6 Identifier for the Quote Set
9032 MinDelta float Required if QuoteCancelType = 7 Min Delta to cancel by delta range
9033 MaxDelta float Required if QuoteCancelType = 7 Max Delta to cancel by delta range

Changes Log

Release 10.06.2025

Release 06.03.2025

Release 04.02.2025

Release 08.08.24

Release 03.07.24

Release 04.06.24

Release 09.03.24

Release 13.02.24

Release 12.12.23

Release 1.3.21

Release 1.3.20

Release 1.3.19

Release 1.3.18

Release 1.3.17

Release 1.3.16

Release 1.3.16

Release 1.3.15

Release 1.3.14

Release 1.3.13

Added combo API:

Added RFQ API:

Release 1.3.12

Release 1.3.11

Release 1.3.10

Release 1.3.09

Release 1.3.08

Release 1.3.07

Release 1.3.06

Release 1.3.05

Release 1.3.04

Release 1.3.03

Release 1.3.02

Release 1.3.01

Release 1.3.00

shell javascript python