Public APIs

Public APIs

Creating a Request

All REST requests must contain the following headers:

BB-ACCESS-KEY The api key as a string.

BB-ACCESS-SIGN The base64-encoded signature (see Signing a Message).

BB-ACCESS-TIMESTAMP A timestamp for your request.

All request bodies should have content type application/json and be valid JSON.

Signing a Message:

The BB-ACCESS-SIGN header is generated by creating a sha256 HMAC using the base64-decoded secret key on the prehash string timestamp + method + requestPath + body (where + represents string concatenation) and base64-encode the output. The timestamp value is the same as the BB-ACCESS-TIMESTAMP header. The body is the request body string or omitted if there is no request body (typically for GET requests).

Selecting a Timestamp:

The CB-ACCESS-TIMESTAMP header MUST be number of seconds since Unix Epoch in UTC. Decimal values are allowed. Your timestamp must be within 30 seconds of the api service time or your request will be considered expired and rejected. We recommend using the time endpoint to query for the API server time if you believe there many be time skew between your server and the API servers.

Example (Python code):

                                    class shivexexchangeAuth(AuthBase):

                                    def __init__(self, api_key, secret_key):
                                        self.api_key = api_key
                                        self.secret_key = secret_key
                                    def __call__(self, request):
                                        timestamp = str(time.time())
                                        message = timestamp + request.method.lower() + request.path_url + (request.body or '')
                                        hmac_key = base64.b64decode(self.secret_key)
                                        signature =, message, hashlib.sha256)
                                        signature_b64 = signature.digest().encode('base64').rstrip('\n')
                                            'BB-ACCESS-SIGN': signature_b64,
                                            'BB-ACCESS-TIMESTAMP': timestamp,
                                            'BB-ACCESS-KEY': self.api_key,
                                            'Content-Type': 'application/json'
                                        return request
                                api_url = ''
                                auth = shivexexchangeAuth(API_KEY, API_SECRET)
                                # Get accounts
                                r = requests.get(api_url + 'profile/me', auth=auth)
                                print r.json()

The API base endpoint:

Methods list:

  • profile/me
  • profile/edit
  • profile/verify

Methods details:

1. profile/me


Method: GET

Returns the currently logged profile data

The returning data fields: user_id, first_name, last_name, username, email, phone, language, country, city, bio, verified(1/0), created (YYYY-mm-dd), moderator, chat_status


{"success":true,"response":{"id":"4004","user_id":"NJOR5E","first_name":"Eugeneus","last_name":"","username":null,"email":"","phone":"380637312675","language":"english","country":null,"city":null,"address":null,"bio":"","verified":"0","created":"2021-08-26 13:12:45","moderator":null,"chat_status":"1"}}

2. profile/edit


Method: PUT

Update the currently logged profile with new data

The user data fields available to update:

first_name, last_name, username, email, phone, language, country, city, address, bio

The example of request body::

{"first_name":"Test First Name","last_name":"Test Last Name","username":"Test Username"}

The returning data: success = true/false and error list if exists

Possible errors: No user field listed

3. profile/verify


Method: POST

Verify profile with following data:

  • verify_type: required. Supported values: passport, driving_license, nid
  • first_name: required. The first name
  • gender: required. Supported values (1 - male, 2 - female)
  • id_number: required. Passport/NID/License Number
  • document1: optional. The base64 encoded document body of Passport Cover (for verify_type = passport) or Driving License (for verify_type = driver_license). The supported document formats: jpg, png, jpeg, pdf
  • document2: optional. The base64 encoded document body of Passport Inner (for verify_type = passport only). The supported document formats: jpg, png, jpeg, pdf

The returning data: success = true/false and error list if exists:

Possible errors:

  • Verification is already in process.
  • Verification is cancelled before.
  • Verification is already completed.
  • verify_type should have one of following value: passport, driving_license, nid.
  • gender should have one of following value: 1, 2.
  • document1(2) allowed document types: png,jpg,pdf.

The basic errors:

  • The required content-type is application/json
  • Empty BB-API-KEY header
  • Empty BB-ACCESS-SIGN header
  • Empty BB-ACCESS-TIMESTAMP header
  • BB-ACCESS-TIMESTAMP expired - when timestamp is older more than 30 sec before current time.
  • Unrecognized method. Currently supported: GET,POST,PUT.
  • Invalid request body - the request body cannot be parsed as JSON
  • Invalid Api Key - user cannot be found by BB-API-KEY header value.
  • Invalid Signature - the BB-ACCESS-SIGN header value does not match to signature calculated based on request.