To connect, you must use a combination of the API Key and API Secret. These sets of credentials are specific to an account and cannot be generated by anyone except Zerocap. Zerocap will send you your credentials.

All REST requests must contain the following headers:

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

The timestamp header MUST be the number of seconds since Unix Epoch in UTC, as an integer. Decimal values are rejected with HTTP 401, and a timestamp in milliseconds is rejected as expired. Your timestamp must be within 30 seconds of the API service time or your request is considered expired and will be rejected with HTTP 408.

Get Time (GET /v2/systems/get_time) is the only endpoint that needs none of these headers. It returns the API server's Unix time in seconds as a string, for example {"server_time": "1792064965"}. It is the only way to check your clock against the API's clock, so call it before signing if your clock may drift.

If your API key was issued with an IP allow-list, REST requests from any other IP address are rejected with HTTP 401 Unauthorized IP address.

To connect to Websocket, the initial connection must contain the same headers as a REST request. After the connection is authenticated there is no further need to send the headers. See Websocket Overview.

Environments

Append the endpoint path to the base URL with a single /, for example https://sandbox-api.zerocap.com/v2/orders/get_instruments. A double slash (//v2/...) is answered with HTTP 401. In the Python SDK, pass env='prod' or env='sandbox'.

Example

import time
import hmac
import hashlib
import requests

api_key = ""
secret_key = ""
zerocap_url = "https://sandbox-api.zerocap.com/v2"  # production: https://dma-api.zerocap.com/v2

def hashing(secret_key, timestamp):
    return hmac.new(secret_key.encode("utf-8"), str(timestamp).encode("utf-8"), hashlib.sha256).hexdigest()

def get_headers():
    timestamp = int(time.time())  # whole seconds
    signature = hashing(secret_key, timestamp)
    headers = {
        'api-key': api_key,
        'signature': signature,
        'timestamp': str(timestamp)
    }
    return headers

def get_time():
    # Public endpoint: no authentication headers
    response = requests.get(zerocap_url + '/systems/get_time', timeout=30)
    return int(response.json()['server_time'])

def get_instruments():
    headers = get_headers()

    response = requests.get(zerocap_url + '/orders/get_instruments', headers=headers, timeout=30)
    result = response.json()
    return result

def run():
    print("clock offset (seconds):", get_time() - int(time.time()))
    print(get_instruments())

if __name__ == '__main__':
    run()

Errors

Authentication is checked before the request reaches the endpoint. These failures return a body with a single message:

Every other error has this shape:

{
    "error": {
        "code": 500,
        "description": "Too Many Requests"
    }
}

error.code is an application code, not the HTTP status: 400 and 429 responses carry "code": 500.

Rate limits

Each endpoint accepts up to 50 requests per second from each client IP address, counted separately for each endpoint. Requests over the limit are answered with HTTP 429 and {"error": {"code": 500, "description": "Too Many Requests"}}. Wait one second before retrying.