Registered Partner Model

Deribit is keen to build an ecosystem of partners to benefit from synergies created by combining individual expertise and value-added of each party. The assumption is that the client can open an account with Deribit and entitle the Registered Partner to send orders to Deribit on his or her behalf.

Process

Deribit offers partners an automated rebate payment for trades generated by the partner on behalf of their clients. All clients are, for that reason, required to have a Deribit account, and the partner will send orders on behalf of their clients to Deribit. As Deribit will only see executions by the end clients, the partner needs to add a signature to these orders for Deribit to recognize them and send rebates based on the fees generated by their clients. Alternatively, for REST and FIX, for the "implicit grant" and "authorization code" approach, the application can also use a special access token, which Deribit then uses internally to identify that order is sent by a certain application.

1. Partner confirms test account (for example partner@gmail.com) after which Deribit will create a Client ID and Secret according to specs in Registered Partner Application Model

2. Partner connects to Deribit in the test environment (test.deribit.com) according to specifications in the Registered Partner Application Model

3. The partner sends orders on behalf of another test account (for example endclient@hotmail.com)

4. Partner verifies next day, at 08:05 UTC to have received payment in their Deribit account (transaction log)

5. Once the test setup is verified, Partner creates an identical setup in production (new ID and secret required)

6. Deribit sends Production Credentials and notifies partner that by using these credentials the partner automatically acknowledges to have read, understood, and agreed to the terms and conditions of the programme.

7. Deribit activates revenue sharing on production

8. Partner logo and link can be added to our partner section

9. Deribit and partner announce partner integration via marketing channels like email newsletters and social media

Technical Setup - Authorization Overview

Deribit offers two workflows for partner applications to execute requests on behalf of Deribit users. First involves acquiring a special access token that will allow identification of the source of the request, such as partner application. Second is suitable for applications that already depend on API keys provided by users - the application, however, needs to include an additional signature so that Deribit can identify it as a source of the request.

Only REST/Websocket APIv2 and FIX API are supported.

Overview of authorization methods is presented in the following table, and additional details are explained further:

1. Acquiring Access Token

For Deribit to create this setup, we would need the following requirements:

Authorization Overview

There are three methods to acquire access tokens by external applications that can be used in REST and WS API:

First two use /app_authorization endpoint in the initial step.

Required parameters:

Optional parameters:

1.1 Implicit Grant

This method is intended for applications that are not able to securely store their secret, like client-side web applications. It's less secure than the authorization code method, so applications are encouraged to use the "authorization code" method if possible.

Steps:

Example:

https://test.deribit.com/app_authorization?client_id=oKtyW608&redirect_uri=localhost%3A83

21%2Fcb&scope=trade%3Aread_write%20account%3Aread&state=0&response_type=token

Redirect after user granted access:

localhost:8321/cb#state=0&access_token=1567681835306.1P66aopy.d5bP32TzVWySRWRJRCp8k12DTB2
XvD2kubl7KQYu7TH3W8DrQkbfhy3pkp-saoAJ3QOOOS6keArX2LdPtg_eMiVYhJkxcoYxmol-XMYPp7V5ooJ1f-Ti
9v-Ln2gMCdLcg6_c7eaPInZdjprozs0dPK5U3CBPSpUBgIXE4A_niTTeLamgQkrsQLpuF9OpLGhfAQxJbALMsr0F6
T81AWZ5heIOtiN4FU836iv0Wdrq3lLjC-MeoCJ-0fEWvz9XQ9D08LHUPoks&refresh_token=1568615874421.1
CL4Rqm5.UPCwi6aRYWHAq3h5dvx8vQCycC6Kr36P0d7cZ0gDzb3ofPK46Ka8U1RmLt_Wcsul4XA-e-O0m6QV_OMq9
9VySPxWfO-fZ0nIPktN5m0MjWqf9peSJ4ePzGEReogm2WR8pDb6THAanmUOFEzj1e-4Doa2krFL7oaifDMte5mbOg
ti-phudF8mRZodL9vrBqu6Za2RnTWT-nH0E2ZxYB0aPpu7MiG9BEoah9AzkVGbuv26r-iUfLue_SBppYIBVj5r9kR
3Z_JSu71On_CoEdrIlwtkr87ZAFY&expires_in=900&token_type=bearer

1.2 Authorization Code

This method requires secure storage of the client secret received after registration.

Steps:

Three parameters must be passed to the/public/authmethod:

Example request body (whitespaces added for readability):

{
    "method": "public/auth",
    "params": {
        "grant_type": "authorization_code",
        "code": "99KCas2FyFs8miQnTqE6MzTxRkZGqkegJrycm5XWOHE",
        "redirect_uri": "localhost:8321/cb"
    }
}

The response is in the same form as described here.

1.2.1 Regaining Access - grant type app_user

In case the application lost the token, or it's invalidated for any reason, to acquire a new one, without requiring user interaction, the application can use user_id returned in the final response of the authorization code flow. It utilizes public/auth with the following parameters:

Example request:

{
    "method": "public/auth",
    "params": {
        "grant_type": "app_user",
        "user_id": "FIx_37_l"
    }
}

user_id is a unique application user ID, so the application has to be authorized to use it in the public/auth method using APP-DERI-HMAC-SHA256 header.

1.3 Acquiring Access Token Using API Key Provided by User

This method is different than the previous two because it requires the user to provide API key to the application which then the application uses to acquire the token.

To acquire the access token, application calls /public/auth method with grant type app_user and parameters the same as in case of client_signature grant type:

{
    "method": "public/auth",
    "params": {
        "grant_type": "app_user",
        "client_id": "WOQ7igCg",
        "timestamp": 1588771838265,
        "signature": "c6f6e812d473582d4023ac2584a94406f15c55b1a7f627b375a6a702ca388800",
        "nonce": "abcd",
        "data": ""
    }
}

client_signature authorization is described here: Additional authorization method - signature credentials (WebSocket API).

Similarly to previous methods, the application needs to be authorized using APP-DERI-HMAC-SHA256 method.

2. Signature Authorization

Methods below use API keys that are provided by users, and client ID and secret provided to the application by Deribit after the registration, to generate signatures that have to be sent with the requests. Currently available only for REST and FIX.

2.1 Partner Header

When the user is authorized using deri-hmac-sha256 authorization header, an additional partner header can be used to identify the source of the request as the application registered on Deribit:

where AppSig is a signature calculated as in the previous step (with the same StringToSign value), but using ClientId (AppId) and ClientSecret of the application.

Alternatively, instead of the partner header, AppId and AppSig can be put in deri-hmac-sha256 authorization header as appid and appsig values.

Authorization example:

deri-hmac-sha256 id=h4jakxW6F4,ts=1569934139312,nonce=abcd,
sig=53150ab0fd7ecfcee65e8d338232fbe527f066baE2e01bcf8b992757283fcc26,
appid=WOQ7igCg,appsig=ba610e2b1b2551a24a910a0e411e32aa3e19913177d2376399377167b2e3f232

Note: This method can't be used to acquire access token as in previous methods - in each request, the user has to be authorized using deri-hmac-sha256 authorization header.

2.2 FIX - Tags 9004 and 9005

As an alternative to "partner" header for FIX applications, we provide two custom tags9004and9005in the Logon(A) message.