Skip to content

Latest commit

 

History

History
274 lines (187 loc) · 6.6 KB

Fairdesk-API-Common.md

File metadata and controls

274 lines (187 loc) · 6.6 KB

Table of Contents * Fairdesk Public API * General Public API Information

Fairdesk Public API

General API Information

  • Fairdesk provides HTTP Rest API for client to operate Orders, all endpoints return a JSON object.
  • Fairdesk provides WebSocket API for client to receive market data, order and position updates.
  • The default Rest API base endpoint is: https://api.fairdesk.com.
  • The WebSocket API url is: wss://www.fairdesk.com/.
  • The Testnet endpoints are https://api-testnet.fairdesk.com and wss://testnet.fairdesk.com

REST API Standards

Restful API Response

HTTP Return Codes

  • HTTP 401 return code when unauthenticated
  • HTTP 403 return code when lack of privilege.
  • HTTP 429 return code when breaking a request rate limit.
  • HTTP 5XX return codes for Fairdesk internal errors. Note: This doesn't mean the operation failed, the execution status is UNKNOWN and could be Succeeded.

Rest Response Format

  • All restful API except starting with /md shares same response format.
{
    "status": <code>,
    "error": <msg>,
    "data": <data>
}
Field Description
code 0 means success, non-zero means error
error when code is non-zero, it provides short error description
data operation dependent

Error Codes

Trading Error Codes

HTTP REST Request Header

Every PRIVATE HTTP Request must have the following Headers:

  • x-fairdesk-access-key: This is API-KEY (id field) from Fairdesk site.
  • x-fairdesk-request-expiry : This describes the Unix EPoch milliseconds to expire the request, normally it should be (Now() + 1 minute)
  • x-fairdesk-request-signature : This is HMAC SHA256 signature of the http request. Secret is API Secret, its formula is : HMacSha256( URL Path + QueryString + Expiry + body )

API Rate Limit Rules

  • private API requests are subject to 200 limit quota per minute
  • Every private API call consumes 1 quota

Endpoint Security Type

  • Each private API call must be signed and pass to server in HTTP header x-fairdesk-request-signature.
  • Endpoints use HMAC SHA256 signatures. The HMAC SHA256 signature is a keyed HMAC SHA256 operation. Use your apiSecret as the key and the string (URL Path + QueryString + Expiry + body) as the value for the HMAC operation.
  • apiSecret = Base64::urlDecode(API Secret)
  • The signature is case sensitive.

Signature Example 1: HTTP GET Request

Signature Example 2: HTTP POST Request

  • API REST Request URL: https://api.fairdesk.com/api/v1/private/account/config/adjust-leverage
  • Request Path: /api/v1/private/account/config/adjust-leverage
  • Request Query:
  • Request Body: { "symbol": "btcusdt", "isolated": true, "leverage": "120"}
  • Request Expire: 1649999999999
  • Signature: HMacSha256(/api/v1/private/account/config/adjust-leverage + 1649999999999 + { "symbol": "btcusdt", " isolated": true, "leverage": "120"})

Websocket Token

Create WebSocket Token

  • Request
POST /api/v1/private/token/create
  • Example Response
{
  "status": 0,
  "error": "OK",
  "data": {
    "apiKey": "YourAPIKeyName",
    "wsToken": "yourAPIWsToken",
    "expiry": 1649673693595
  }
}

this method is idempotent, call this method multiple times will generate the same websocket token

Refresh WebSocket Token

  • Request
POST /api/v1/private/token/refresh

If no upstanding ws token is valid, an error of "error-code.api.ws-token.not-created" is thrown.

  • Example Response
{
  "status": 0,
  "error": "OK",
  "data": {
    "apiKey": "YourAPIKeyName",
    "wsToken": "yourAPIWsToken",
    "expiry": 1649673693595
  }
}

Delete WebSocket Token

  • Request
DELETE /api/v1/private/token/delete
  • Success Response
{
  "status": 0,
  "error": "OK",
  "data": true
}

Websocket Stream:

Live Subscribing/Unsubscribing to streams

  • The following data can be sent through the websocket instance in order to subscribe/unsubscribe from streams. Examples can be seen below.
  • The id used in the JSON payloads is an unsigned INT used as an identifier to uniquely identify the messages going back and forth.
  • In the response, if the result received is null this means the request sent was a success for non-query requests ( e.g. Subscribing/Unsubscribing).

Subscribe to a stream

  • Request
 { "method": "SUBSCRIBE", "params": [ "btcusdt@depth10" ], "id": 1 }
  • Response
 { "result": null, "id": 1 }

Unsubscribe to a stream

  • Request
{ "method": "UNSUBSCRIBE", "params": [ "btcusdt@depth10" ], "id": 15 }
  • Response
 { "result": null, "id": 15 }

Listing Subscriptions

  • Request
 { "method": "LIST_SUBSCRIPTIONS", "id": 4 }
  • Response
 { "result": [ "btcusdt@depth10" ], "id": 4 }