Deribit is keen to build an ecosystem of partners each with their own value add and expertise. The assumption is that the end client opens an account with Deribit and entitles the Registered Partner to send orders to Deribit on his or her behalf.

Process

Deribit is able to offer 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 would send orders on behalf of their clients to Deribit. As Deribit will only see executions by those clients, the partner needs to add a signature to these orders in order for Deribit to recognize them and send rebates based on the fees generated by those clients. Alternatively for REST and in 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 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 specs in the Registered Partner Application Model

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

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

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

6 Partner signs partnership agreement

7 Deribit activates production revenue sharing

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 special access token that will allow identification of the source of the request as partner application. Second is suitable for applications that already depend on API keys provided by users - the application needs to include additional signature so Deribit is able to 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, details are explained further:

1. Acquiring access token

In order for Deribit to create the setup we would need the following from the partner:

1. The Partner Deribit account where the rebates should be received

2. Partner Redirect URL(s)

3. Partner Domain

Authorization overview

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

• Implicit grant
• Authorization code
• 'app_user' grant type
  

First two use /app_authorization endpoint in initial step.

Required parameters:

• response_type - token for implicit grant and code for authorization code
• client_id - client ID received after registration
• redirect_uri - where the response should be redirected (must be one of the URIs given at the registration)
• scope - space-separated list of name:type pairs where name is one of: account, wallet, trade, block_trade, and type is read or read_write
• state - a value that will be returned with the response and should be verified by the client

Optional parameters:

• user_id - makes initial selection of user in consent form, must identify current user or one of their subaccounts, allows skipping the form if user changed current account (this value is received with token in authorization code flow)
• show - if true, forces showing consent form, even if user already authorized the application

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 authorization code method, so applications are encouraged to use "authorization code" method if possible.

Steps:

1. User is redirected by the client to /app_authorization endpoint with response_type=token. For example:

https://test.deribit.com/app_authorization?client_id=oKtyW608&redirect_uri=localhost%3A8321%2Fcb&scope=trade%3Aread_write%20account%3Aread&state=0&response_type=token

2. User grants access to the application.

3. User is redirected to redirect_uri with following parameters passed in URI fragment (after #): access_token, refresh_token, token_type, expires_in, state.
   

localhost:8321/cb#state=0&access_token=1567681835306.1P66aopy.d5bP32TzVWySRWRJRCp8k12DTB2XvD2kubl7KQYu7TH3W8DrQkbfhy3pkp-saoAJ3QOOOS6keArX2LdPtg_eMiVYhJkxcoYxmol-XMYPp7V5ooJ1f-Ti9v-Ln2gMCdLcg6_c7eaPInZdjprozs0dPK5U3CBPSpUBgIXE4A_niTTeLamgQkrsQLpuF9OpLGhfAQxJbALMsr0F6T81AWZ5heIOtiN4FU836iv0Wdrq3lLjC-MeoCJ-0fEWvz9XQ9D08LHUPoks&refresh_token=1568615874421.1CL4Rqm5.UPCwi6aRYWHAq3h5dvx8vQCycC6Kr36P0d7cZ0gDzb3ofPK46Ka8U1RmLt_Wcsul4XA-e-O0m6QV_OMq99VySPxWfO-fZ0nIPktN5m0MjWqf9peSJ4ePzGEReogm2WR8pDb6THAanmUOFEzj1e-4Doa2krFL7oaifDMte5mbOgti-phudF8mRZodL9vrBqu6Za2RnTWT-nH0E2ZxYB0aPpu7MiG9BEoah9AzkVGbuv26r-iUfLue_SBppYIBVj5r9kR3Z_JSu71On_CoEdrIlwtkr87ZAFY&expires_in=900&token_type=bearer

1.2 Authorization code

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

Steps:

1. User is redirected by the client to /app_authorization endpoint with response_type=code.

2. User grants access to the application.

3. User is redirected to redirect_uri with following parameters passed in query string (after ?): code, state.For example:

localhost:8321/cb#code=99KCas2FyFs8miQnTqE6MzTxRkZGqkegJrycm5XWOHE&state=0

4. Standard /public/auth method is used to retrieve access token (described here), but client has to be authorized using APP-DERI-HMAC-SHA256 method (that is identical to DERI-HMAC-SHA256 described here, using AppId and AppSecret (in place of ClientId and ClientSecret values) received after the registration) and, in this case, it's limited to POST requests.
   

Three parameters must be passed to the /public/auth method:

• grant_type - must be authorization_code,
• code - retrieved in previous step,
• redirect_uri - the same URI as used in previous steps.

Example request body (whitespaces added for readability):

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

Response is in the same form as described here.

1.2.1 Regaining access - grant type app_user

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

• grant_type - must be app_user,
• user_id - returned along the token in authorization code public/auth method response.

Example request:

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

user_id is unique application user ID, so the application has to be authorized to use it in 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 ones because it requires the user to provide api key to the application which then 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, application needs to be authorized using APP-DERI-HMAC-SHA256 method.

2 Signature authorization

Below methods use API keys provided by users and client id and secret, provided to application by Deribit after registration, to generate signatures that have to be send with the requests. Currently only for REST and FIX.

2.1 partner header

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

1. 1. Construct deri-hmac-sha256 authorization header as described here (Deribit signature credentials) using ClientId and ClientSecret provided by user.
   2. Construct partner header with value of form:

partner: id=${AppId},sig=${AppSig}

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

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

authorization: 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 user has to be authorized using deri-hmac-sha256 authorization header.

2.2 FIX - tags 9004 and 9005

As an alternative for "partner" header for FIX applications we provide 2 custom tags 9004 and 9005 in Logon(A) message.