Get started with API

Signing requests

First of all to use Calypso Public API you’ll need to contact Technical Support to generate a new pair of API keys (public and secret keys):

secret key example:
b823a6b9ea72408583cef9ec8d67fa52
public key example:
c529e14832b34b74972365cf7bf02430

API keys are used for authorization in requests to the Calypso API. After receiving API keys from our Technical Support team you can start sending requests to Calypso Public API.

All requests must contain the following headers:

Key	The api key as a string.
Sign	The HEX-encoded signature (see below).
Content-Type	All request bodies should have content type application/json and be valid JSON.

Sign — POST data (in the same format in which you want to send) encrypted with the method HMAC-SHA512 using secret key and the result object is converted to a HEX string.

The body is the request body string (in all cases this is JSON stringified request params object).

All the requests should also include the obligatory POST parameter timestamp with current unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past and not greater than 3 minutes in the future.

To create the sign:

1. Build the body of the request with correct timestamp

2. Encrypt the request body with method HMAC-SHA512 using the body as a message and the secret key as a key.

3. Convert bytes to string of hexadecimal digits.

Examples of sign building:

• Javascript

  JSX

  const crypto = require("crypto-js");
  
  signature = function (body, secretKey) {
          return crypto.HmacSHA512(body, secretKey).toString(crypto.enc.hex);
      };

• Python

  Python

  import hmac
  import hashlib
  
  def signature(body, secret_key):
      return hmac.new(secret_key.encode(), body.encode(), hashlib.sha512).hexdigest()

Example of api keys, body and correct sign for request:

Python

api_key = 'c529e14832b34b74972365cf7bf02430'
secret_key = 'b823a6b9ea72408583cef9ec8d67fa52'

data = '{"timestamp":1}'
sign = 'b16e9d45f49f2069becbc4f108b237bee588cfc353fe9501df103e692acbc68d482a10d34c12bea22fedde7e28e1b8e57a6a0a373b0e9a27c5257bd8b36e13b9'

Examples of timestamp building:

• Javascript

JavaScript

var timestamp = new Date().getTime();

• Python

Python

import time

timestamp = round(time.time() * 1000)

Handling Unknown Parameters in API

Backward Compatibility Principle

Our API follows the "Robustness Principle".

API Client Requirements

API client applications and integrations MUST ignore any unknown or unsupported parameters received in API responses.

Prohibited Actions

❌ NOT ALLOWED:

• Throwing exceptions/errors when unknown parameters are detected

• Stopping response processing due to new fields

• Validating responses against strict schemas that don't allow extensions

• Breaking functionality because of additional data

Why This Is Important?

Ensuring Backward Compatibility:

• API can add new features without breaking changes

• Old clients continue working with new API versions

• Gradual feature rollout without forced client updates

Business Benefits:

• Zero downtime updates - API updates don't require synchronous client updates

• Development flexibility - ability to A/B test new features

• Gradual migration - clients can update at their own pace

Handling Incoming Requests

Note: This rule applies specifically to API responses. For incoming requests to our API, clients should only send documented parameters, while our server will reject unknown parameters in requests according to our validation rules.