How to authenticate with Deribit’s API (Python)

Updated: 08/07/2020, 13:09 CET

This tutorial will walk you through how to authenticate your programmatic application with the Deribit API using Python.

This guide is suitable for beginners as well as advanced users alike!

There are three authentication protocols offered by Deribit including JSON-RPC over Websockets, JSON-RPC over HTTP, and FIX (Financial Information eXchange).

We will seek to cover all possible means and methods, but in the beginning, we will focus upon the JSON-RPC over Websockets protocol.

The example code was developed in a Linux environment, Ubuntu 20.04, and care has been taken as so it can be run easily across all operating systems (Windows, macOS, Linux).

In this guide, we will not discuss the architecture of the application or a solution, but rather focus upon authenticating and maintaining a connection with Deribit’s API using your API Key.

In this guide, we will:

  1. Walk through the creation of your API Keys.
  2. Run the Authentication Code Examples.
  3. Discuss possible implementation pathways for further Deribit API endpoints.

To complete this guide, you will need:

  • A Python environment installed on your system. Anaconda is a great place to start if you are new to Python and using Windows. If you are using macOS or Linux, you can install python directly using your terminal.
  • An IDE like VSCode or Pycharm (Pycharm for Anaconda).
  • A Deribit testnet account.
  • The Deribit API Documentation open at all times. It is the single best resource and reference for any API question now and in the future.
1

The creation of your API Keys

1. Login with your Deribit testnet account to Deribit’s testnet.

You need a separate account between the live exchange and the testnet.

Create a Deribit testnet account.

The API calls and created programmatic applications are the same between the live exchange and testnet. The testnet is an ideal sandbox to test applications, learn Deribit’s API, and construct specific solutions all without risking your capital.

2. In the top right-hand corner of the webpage, click the drop-down menu of your username and click the “Settings” menu item.

3. Select the tab titled “Api” and click the button titled “Add a new key”.

The button is to the right in the centre of the screen.

You can create up to 8 API Keys per Sub-Account.

4. Choose “read_write” from the dropdown menu for each parameter and then click “Add a new key”.

As we are using the testnet, there is no risk to any real capital and we can make mistakes without causing any lasting harm.

Your API Key allows your program to manage nearly all aspects of your Deribit account. When you create your API Key you can choose what privileges and actions each key has which directly control what actions can be completed using your API Key.

It is always a good idea to operate with the “least privilege” principle to avoid any lasting mistakes being made or unexpected actions.

It is strongly recommended you thoroughly test code using the testnet first before using the live exchange as to avoid any mistakes. Mistakes as a result of errant code are entirely your responsibility and cannot be reversed. 

We suggest you give the API Keys recognizable names. The trades and mutations made by the API Key will show in the transaction log and when you are using multiple API Keys it is very easy to see which API Key is responsible.

5. You have now created your API Key!

Your API Key is composed of a  “Client Id” and a  “Client Secret”.

Your API Keys will be different to the one present in the example.

Each API Key is unique to your account and allows Deribit to know which account is communicating with us.

Important Note: It is very important to be aware of the “Automatically enable COD (close all orders on disconnect) on all API connections”. If enabled, this option will automatically cancel all of your open orders when you disconnect. There are a large number of situations where this is extremely useful, but it can also be frustrating if you are not aware of this behavior and your application disconnects from Deribit’s API.
2

Authenticating your application with the Deribit API

Using the provided Code Example
While the provided example is written in Python, the same steps apply across all programming languages!

Summary of Authentication Steps:

  1. Initialize the connection by sending a /public/auth API request with a correctly formatted Client Signature.
  2. Set a Heartbeat, using /public/set_heartbeat, and respond appropriately to ensure your connection does not become “stale” and disconnected by the Deribit API.
  3. Use the “refresh_token” provided during each authentication to re-authenticate your application before the time value specified in the “expires_in” authentication response key.

Websocket Connection URLs: 

Live:
Copy to Clipboard
Test:
Copy to Clipboard

1. Ensure that you have installed the Python package Websockets using pip, Conda, or your package manager of choice.

Useful Command: The ‘pip list’ command will return all of your presently installed packages.

Running something similar to ‘pip install websocket_client’ will install the package into your python environment.

2. Open your IDE (for example, VsCode or Pycharm) and open the Code Example, available on Github, locally.

The provided example code is designed to be a soft introduction to using the Deribit API and to allow anyone to get up and running very quickly.

It is not an example of how things must be or the only solution. It is designed for beginners and experts alike to help colour the API Documentation.

The provided code is an example only and Deribit is not responsible for any actions as a result of running, using, or deploying the provided example.

Keep in mind this Github will be updated quite quickly and the contents are likely to change.

3. In the just-opened Code Example project, navigate to the “User-Credentials” folder and open the “UserCredentials.py” file.

4. Replace the existing values mapped to the “Client_Id” and “Client_Secret” variables.

Use the “Client_Id” and “Client_Secret” values of your API Key we created at the end of the previous section.

Remember to save the file!

5. Navigate to and open the “JSON-RPC_Websockets-Example.py” file in the “JSON-RPC_Websockets” directory (folder).

6. On Line 14, update the existing directory path with the path to your “User-Credentials” folder.

This is the folder path available using Windows Explorer for example.

Remember to save the file!

7. Run the file “JSON-RPC_Websockets-Example.py”.

This will produce a similar output to the following image.

Running this example code will:

This example also produces an output of the present positions in your portfolio using the /private/get_positions endpoint.

We encourage you to pull apart the code and try things line by line.

Key Code to note:

  • The “scope” variable, on Line 234, allows you to choose between “read” and “read-write”. This is a choice between allowing your program to only “read” from your account or to be able to “write”, such as trading and withdrawing capital. This does not supersede the privileges granted to each API Key during creation, but limits the application’s authenticated scope. 
  • The “exchange_version” variable, on Line 236, allows you to choose between using the testnet and live exchange.
  • In the class “UserWebsocketEngine” you can update the “self.seconds_delay” variable if you want to increase the speed at which your application requests from the API. Be careful though, we do have rate limits which specifically apply to requests that affect our matching engine.
The Deribit API Console is a fantastic resource. It allows you to test queries in a web interface and observe the raw requests and real responses returned.
3

Implementation Pathways with the Deribit API

JSON-RPC over Websockets Example Discussion

In the “on_message” function you can add other calls and make them dependant upon IF functions.

At this point, it’s great to check the API Documentation as so you can see what you can do and the solutions you could create.

You could for example:

At the present moment, you cannot submit actions for multiple instruments at the same time in the same API request. For example, this means you cannot submit multiple buy orders for different instruments at the same time. You can subscribe to multiple instruments at once though.

We will greatly update this guide as time passes and would love to hear your feedback in our Telegram Community!