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!
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:
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.
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.
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.
Authenticating your application with the Deribit API
Summary of Authentication Steps:
- Initialize the connection by sending a /public/auth API request with a correctly formatted Client Signature.
- Set a Heartbeat, using /public/set_heartbeat, and respond appropriately to ensure your connection does not become “stale” and disconnected by the Deribit API.
- 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:
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.
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.
7. Run the file “JSON-RPC_Websockets-Example.py”.
This will produce a similar output to the following image.
Running this example code will:
- Authenticate your application with the Deribit API using your API Key.
- Set a Heartbeat as so your connection does not become “stale” and be disconnected by our API.
- Refreshes your Authentication against the Deribit API using the authentication generated “refresh_token”.
This example also produces an output of the present positions in your portfolio using the /private/get_positions endpoint.
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.
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:
- Pull live BTC and ETH instrument data by using the /public/subscribe endpoint.
- Pull the last trades by specific instrument and time by using the /private/get_last_trades_by_instrument_and_time endpoint.
- Submit a buy order by using the /private/buy endpoint.
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.