Introduction

Zoomex V3 Open API allow users to select different collections to build their API model.

• Copy Trade: You must be Master Trader to use this API.

Authentication

info

Please visit Zoomex's testnet or mainnet to generate an API key

info

The authentication of the v1 interface is different from v3. Please pay attention to using the corresponding signature method when calling, and refer to the call demo of each API for the corresponding method.

REST API Base Endpoint:

• Testnet:
  https://openapi-testnet.zoomex.com
• Mainnet:
  https://openapi.zoomex.com

caution

• All requests made to private endpoints MUST be authenticated.
• Requests made to public endpoints DO NOT require additional authentication.

Parameters for Authenticated Endpoints

The following parameters must be used for authentication:

• api_key - api key
• timestamp - UTC timestamp in milliseconds
• sign - a signature derived from the request's parameters
  

We also provide recv_window (unit in millisecond and default value is 5,000) to specify how long an HTTP request is valid. It is also used to prevent replay attacks.

A smaller recv_window is more secure, but your request may fail if the transmission time is greater than your recv_window.

caution

Please make sure that the timestamp parameter adheres to the following rule:
server_time - recv_window <= timestamp < server_time + 1000
server_time stands for Zoomex server time, which can be queried via the Server Time endpoint.

Create A Request

tip

To assist in diagnosing advanced network problems, you may consider adding cdn-request-id to your request headers. Its value should be unique for each request.

Basic steps:

1. timestamp + API key + (recv_window) + (queryString | jsonBodyString)

2. Use the HMAC_SHA256 or RSA_SHA256 algorithm to sign the string in step 1, and convert it to a hex string (HMAC_SHA256) / base64 (RSA_SHA256) to obtain the sign parameter.

3. Append the sign parameter to request header, and send the HTTP request. Note: the plain text for GET and POST requests is different. Please refer to blew examples.

4. Demo

   import requests
   import time
   import hashlib
   import hmac
   import uuid
   
   api_key='XXXXXXXX'
   secret_key='XXXXXXXX'
   httpClient=requests.Session()
   recv_window=str(5000)
   url="https://openapi-testnet.zoomex.com"
   
   def HTTP_Request(endPoint,method,payload,Info):
      global time_stamp
      time_stamp=str(int(time.time() * 10 ** 3))
      signature=genSignature(payload)
      headers = {
          'X-BAPI-API-KEY': api_key,
          'X-BAPI-SIGN': signature,
          'X-BAPI-SIGN-TYPE': '2',
          'X-BAPI-TIMESTAMP': time_stamp,
          'X-BAPI-RECV-WINDOW': recv_window,
          'Content-Type': 'application/json'
      }
      if(method=="POST"):
          response = httpClient.request(method, url+endPoint, headers=headers, data=payload)
      else:
          response = httpClient.request(method, url+endPoint+"?"+payload, headers=headers)
      print(response.text)
      print(Info + " Elapsed Time : " + str(response.elapsed))
   def genSignature(payload):
      param_str= time_stamp+ api_key + recv_window + payload
      hash = hmac.new(bytes(secret_key, "utf-8"), param_str.encode("utf-8"),hashlib.sha256)
      signature = hash.hexdigest()
      return signature
   
   #POST Create Order
   endpoint="/cloud/trade/v3/order/create"
   method="POST"
   orderLinkId=uuid.uuid4().hex
   params='{"category":"linear","symbol": "BTCUSDT","side": "Buy","positionIdx": 0,"orderType": "Market","qty": "0.001","price": "","timeInForce": "GTC","orderLinkId": "' + orderLinkId + '"}'
   HTTP_Request(endpoint,method,params,"Create")
   
   #GET history Orders
   endpoint="/cloud/trade/v3/order/history"
   method="GET"
   params='category=linear&symbol=BTCUSDT'
   HTTP_Request(endpoint,method,params,"history")

Common response parameters

Parameter	Type	Comments
retCode	number	Success/Error code
retMsg	string	Success/Error msg. Can be OK,success,Success for Success message
result	Object	Business data result
retExtInfo	Object	Extend info. Most of time, it is {}
time	number	Current timestamp (ms)

{
    "retCode": 0,
    "retMsg": "success",
    "result": {},
    "retExtInfo": {},
    "time": 1690180896378
}

tip

• Due to historical reasons, the attributes returned in the list object of the result object in the response body of the [Get Open Orders(real-time)] (./order/open order/#) start with uppercase letters. Please be careful when docking!