openAPI-StarEx

# Basic Information

# 1. Introduction

· Based on API categorization, most interfaces require an API Key for access. Please proceed to the User Center -> API Management to create your authorized application and obtain your API Key and API Secret Key.

· Please securely store your API Key and API Secret Key. If they are accidentally exposed, kindly delete the corresponding authorized application immediately.；

# 2. Application Permissions

· Permissions have three dimensions: Modules, Actions, and Resources. Please configure your permissions properly to enhance security and facilitate management；

# 2.1 Modules:

​Base module; ​Account module; ​Spot trading module; ​Spot market data module;

Other modules will be progressively introduced in future versions；

# 2.2 Actions:

Read allows you to retrieve corresponding data from modules；

​For example, reading the spot module provides trade history, while reading the account module offers transfer records；

Submit can be used to submit corresponding business requests to a module;

​For example, spot module's place market order, account module's initiate transfer application；

Attention: In the event of API Key and Api Secret Key leakage, if this authorized application is configured with [Submit] permissions, there's a risk of exposing data from this module;

​If [Submit] permissions are granted, there's a risk to the financial security of this module, hence meticulous configuration is required!

# 2.3 Resources

With regard to the differing functions of each module, corresponding resource permissions isolation is supported；

Module Name Resource Permission Type
Account Cryptocurrency e.g: USDT, BTC, ETH, etc.
Spot Trading Trading pairs e.g: BTC/USDT, ETH/USDT, etc.
... ... Please refer to [Resource Isolation Type] in each interface for specifics.

For example, after configuring resource permissions for the trading pair 【BTC/USDT】 within the Spot Trading module, the Api Key associated with this application will only possess the 【read or submit】 authorization for that specific trading pair within the Spot Trading module. It won't be able to perform read nor submit for other trading pairs；

# 3. Integration Guide

# 3.1 Basic API Information

​ 1. Interface base URL

  • https://api.starex.com

​ 2. All interface responses are in JSON format

​ 3. Both for requests and responses, all times and timestamps are in UNIX timestamps, measured in milliseconds；

​ 4. In a GET request, all parameters are transmitted through request parameters;

In a POST request, all parameters are transmitted through the request body;

# 3.2 Authentication

The server employs custom request headers to authenticate the received requests for validity and permissions；

Please populate them in each authentication-required request header according to the agreed authentication protocol；

Key(key) Value(value) Description
STAREX-APP-KEY-V1 Your authorized application's Api Key Used by the server to identify your authorized application
STAREX-SIGNATURE Signature computed according to agreed algorithm Used by the server to verify the integrity of your request
STAREX-TIMESTAMP Timestamp of your request Used by the server to check for network latency in your request
STAREX-TIMEOFFSET Network latency you can tolerate (in milliseconds) Optional, default is 3000 milliseconds

# 3.2.1 Signature

For the majority of API calls, a signature is required to ensure that the received request has not been intercepted or tampered with by malicious actors；

StarEX Open API employs the HmacSHA256 algorithm for signature creation;

a. Obtain your API request parameters and generate a String named 'param';

For GET requests, this is your request parameters; for POST requests, it's the request body. If there are no request parameters, 'param' is an empty string ("");

b. Concatenate your request timestamp with the request parameters to form a string. This results in 'HmacSHA256 content;

String hmacContent = param + String.valueOf(timestamp) ;

c. Utilize your API Secret Key as the key for the HmacSHA256 encryption of 'hmacContent.' Convert the result to hexadecimal format (hexDigest);

String hmacResult = HmacUtils.sha256(hmacContent,secretKey);

String signature = HexUtils.parse(hmacResult);

d. Place the obtained signature, along with the APP Key and timestamp, accurately within the Request Header. Proceed to initiate your request;

This process outlines the steps to create and utilize a secure signature for API calls in the context of cryptocurrency trading platforms.

# 3.2.2 Time Synchronization Security

The STAREX-TIMESTAMP in the request header is the UNIX timestamp when the request is initiated；

Upon receiving a request, the server evaluates the timestamp within the request. If it's older than 3000 milliseconds, the request is deemed invalid.

The permissible offset for this time can be defined by sending the optional parameter STAREX-TIMEOFFSET；

Due to network fluctuations or other uncontrollable factors, there might be significant time consumption at the network level before a request reaches the server；

In certain interfaces or specific scenarios, you may have stringent requirements for the timeliness of your calls；

For instance, you might want your order placement request to reach the server within one second; otherwise, you'd discard the request;

In such a scenario, you can meet your requirement by flexibly setting STAREX-TIMEOFFSET in the request header to 1000；

# 3.3 Restrictions

# 3.3.1 Access Restrictions

​ Each Api Key possesses distinct access permissions, encompassing various module/behavior/resource privileges. For specifics, please refer to the document under the section [Introduction → Application Permissions]

# 3.3.2 IP Restriction

​ In the scenario where an authorized application is bound to specific IP addresses, only those designated IPs are allowed to access the API successfully;

# 3.3.3 Rate Limiting (callLimits)

· Each interface requires proper access to the API through consuming callLimits. The consumption of callLimits varies based on the complexity of the API or the load on the system; please refer to each individual interface for specifics；

· The callLimits consumed by all interfaces are shared. This implies that they will mutually be affected by rate limiting；

· Each Api Key replenishes 24000 callLimits per minute;

· Upon exceeding the call frequency, the server will respond with an httpStatus:418 code, indicating an excessive call warning. This warning will persist for a certain period. It is both necessary and your obligation for your application to reduce its call frequency after receiving such a warning；

· After multiple instances of exceeding the call frequency with the same Api Key, the server will respond with an httpStatus:429 code, indicating temporary frequency blocking. This block is temporary and can last from a minimum of 1 hour to a maximum of 7 days. You need to address your calls or modify your program before being unblocked, and then proceed with correct initiation of calls；

# 3.4 Example of API Invocation

In the following examples, let's assume your Api Key is "abcd" and your Api Secret Key is "test". Your request timestamp is "1234567890";

# Example 1: Query Transfer Records

GET https://api.starex/v1/account/transfer/page?coin=USDT&from=EXCHANGE

Here, the request parameters are： "coin=USDT&from=EXCHANGE" (a string, no need for URL encoding)

  1. Concatenate it with your request timestamp to get the HmacSHA256 content: "coin=USDT&from=EXCHANGE1234567890" ;
  2. Use your Api Secret Key "test" as the HmacSHA256 Secret Key and calculate the Hmac Result;
  3. Convert the Hmac Result to Hexadecimal to obtain the signature;
String content = "coin=USDT&from=EXCHANGE1234567890";
String apiSecretKey = "test";
String hamc256Result = HmacUtils.sha256(content,secretKey);
String signature = HexUtils.parse(hexContent);

​ The resulting signature is "58c47be0d1119874dbeabe7af16a0c0fb6901d700bc7d10adcc85ff95f9d452f" , which should be placed in the STAREX-SIGNATURE request header；

The final request is：

curl -X GET 
-H  "STAERX_APP_KEY_V1:abcd" 
-H  "STAREX-TIMESTAMP:1234567890" 
-H  "STAREX-SIGNATURE:58c47be0d1119874dbeabe7af16a0c0fb6901d700bc7d10adcc85ff95f9d452f"
"http://api.starex/v1/account/transfer/page?coin=USDT&from=EXCHANGE"

# Example 2: Submit Transfer Request

   POST https://api.starex/v1/account/transfer/submit

   {	
		"amount":"1",
		"coin":"USDT",
		"from":"EXCHANGE",
		"to":"OTC"
  }

Here, the request parameter is： {"amount":"1","coin":"USDT","from":"EXCHANGE","to":"OTC"} (compressed JSON string)

Concatenate it with your request timestamp to get the HmacSHA256 content: {"amount":"1","coin":"USDT","from":"EXCHANGE","to":"OTC"}1234567890

Use your Api Secret Key "test" as the HmacSHA256 Secret Key and calculate the Hmac Result：

Convert the Hmac Result to Hexadecimal to obtain the signature.

String content = "{\"amount\":\"1\",\"coin\":\"USDT\",\"from\":\"EXCHANGE\",\"to\":\"OTC\"}1234567890";
String secretKey = "test";
String hamc256Result = HmacUtils.sha256(content,secretKey);
String signature = HexUtils.encode(hexContent);

The resulting signature is "3c908c790a0dcc1a308b66afc542472845f178c4e7303daa68301dcd4cf5eac9" , which should be placed in the STAREX-SIGNATURE request header；

The final request is：

curl -X POST 
-H  "STAREX-APP-KEY-V1:abcd" 
-H  "STAREX-TIMESTAMP:1234567890" 
-H  "STAREX-SIGNATURE:3c908c790a0dcc1a308b66afc542472845f178c4e7303daa68301dcd4cf5eac9"
-d  "{\"amount\":\"1\",\"coin\":\"USDT\",\"from\":\"EXCHANGE\",\"to\":\"OTC\"}"
"https://api.starex/v1/account/transfer/submit"

Changelog →