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:
The Partner Deribit account where the rebates should be received
Partner Redirect URL(s)
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 andcode
for authorization codeclient_id
- client ID received after registrationredirect_uri
- where the response should be redirected (must be one of the URIs given at the registration)scope
- space-separated list ofname:type
pairs wherename
is one of:account
,wallet
,trade
,block_trade
, andtype
isread
orread_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
- iftrue
, 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:
- User is redirected by the client to
/app_authorization
endpoint withresponse_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
User grants access to the application.
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:
User is redirected by the client to
/app_authorization
endpoint withresponse_type=code
.User grants access to the application.
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
Standard
/public/auth
method is used to retrieve access token (described here), but client has to be authorized usingAPP-DERI-HMAC-SHA256
method (that is identical toDERI-HMAC-SHA256
described here, usingAppId
andAppSecret
(in place ofClientId
andClientSecret
values) received after the registration) and, in this case, it's limited toPOST
requests.
Three parameters must be passed to the /public/auth method:
grant_type
- must beauthorization_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 beapp_user
,user_id
- returned along the token in authorization codepublic/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:
- Construct
deri-hmac-sha256
authorization header as described here (Deribit signature credentials) usingClientId
andClientSecret
provided by user. - Construct
partner
header with value of form:
- Construct
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.