API文档-StarEx

# 基本信息

# 1. 介绍

· 根据API的分类，大多数接口需要Api Key才可以访问 ，请前往用户中心->API管理 创建你的授权应用APP 来获取Api Key与Api Secret Key 。

· 请妥善保管好Api Key与Api Secret Key , 如果不小心泄露了，请立即删除对应的授权应用APP；

# 2. 应用权限

· 权限有三个维度：模块、行为、资源 ，请妥善配置好你的权限增加安全性并以便管理 ；

# 2.1 模块:

​ 基础模块；账户模块；现货模块；现货行情模块；

​ 其他模块也会在未来版本逐次提供；

# 2.2行为:

​ 查询 可以对模块查询对应的数据；

​ 例如：查询现货模块的成交历史、查询账户模块的划转记录；

​ 提交 可以对模块提交相应的业务请求；

​ 例如： 现货模块的下币币委托订单、账户模块的提交划转申请；

请注意：在API Key与Api Secret Key 泄露的情况下，如果该授权应用配置了[查询]权限，则有泄露该模块数据的风险；

​ 如果授权了[提交]权限，则有该模块的资金安全风险，所以需要谨慎配置！

# 2.3资源权限

针对于每个模块的业务不同，支持对应的资源权限隔离；

模块名称 资源权限类型
账户模块 币种 例如：USDT、BTC、ETH 等
现货模块 交易对 例如 BTC/USDT 、ETH/USDT 等
... ... 具体请参考每个接口中的[资源隔离类型]

例如：现货模块配置【BTC/USDT】资源权限后，该应用的Api Key 在现货模块只有该交易对的【查询或提交】权限；无法操作查询其他交易对；

# 3. 接入指南

# 3.1 Api基本信息

​ 1. 接口base URL

  • https://api.starex.com

​ 2. 所有的接口响应都是JSON格式

​ 3. 无论是请求\响应 ，所有的时间、时间戳均为UNIX时间戳，单位为毫秒；

​ 4. GET请求中，所有的参数都通过request params 传递 ;

​ POST请求中，所有的参数都通过request body 传递 ;

# 3.2 鉴权

服务器通过自定义请求头来鉴定接收到的请求是否有效并有权限；

请在每个需要鉴权的请求头中，按照鉴权约定填充它们；

键(key) 值(value) 备注
STAREX-APP-KEY-V1 你授权应用的Api Key 服务器用于识别你的授权应用
STAREX-SIGNATURE 按照约定的算法计算输出的签名 服务器用于校验你的请求是否健康完整
STAREX-TIMESTAMP 你的请求的时间戳 服务器用于校验你的请求是否有网络波动延迟
STAREX-TIMEOFFSET 你所能接受的网络波动延迟（毫秒） 选填，默认为3000毫秒

# 3.2.1 签名

调用绝大多数接口时，都需要进行签名，以便服务器校验接受到的请求没有被抓包篡改；

StarEX Open API签名采用 HmacSHA256算法进行签名;

a. 获取你的接口请求参数; 得到String param;

GET请求为你的request prams , POST请求为request body;

如果没有请求参数,则param为空字符串"";

b. 使用请求参数以拼接字符串的形式拼接你的请求时间戳 ; 得到HmacSHA256 content;

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

c. 使用你的Api Secret Key作为作为HmacSHA256的密钥，对HmacContent进行加密, 并将得到的结果进行hexDesign(输出为十六进制);

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

String signature = HexUtils.parse(hmacResult);

d. 将得到的签名,与APP Key、时间戳正确地放入请求头(Request Header)中,再发起你的请求;

# 3.2.2 时间同步安全

请求头中的STAREX-TIMESTAMP为请求发起时的UNIX时间戳；

服务器收到请求时会判断请求中的时间戳，如果是3000毫秒之前发出的，则请求会被认为无效。

这个时间的允许偏移值可以通过发送可选参数 STAREX-TIMEOFFSET 来定义；

由于网络波动或是其他不可控原因，请求到达服务器前可能会在网络层面就消耗许多时间 ；

在某些接口或特定场景下，你可能会对调用发起的时效要求比较高；

例如场景： 我希望我的下单请求在一秒钟内到达服务器，否则则丢弃请求；

在此场景下，你可以通过灵活设置请求头中的 STAREX-TIMEOFFSET=1000 来达到你的要求；

# 3.3 限制

# 3.3.1 访问限制

​ 每个Api Key都有不同的访问权限，其中包括不同的模块/行为/资源权限，具体请查阅本文档中【介绍 --> 应用权限】

# 3.3.2 IP限制

​ 在授权应用绑定了IP的场景下，有且仅有这些IP能够成功访问API ;

# 3.3.3 速率限制 (callLimits)

· 每个接口都需要通过消耗callLimits来正确的访问API ；根据API的业务复杂度或者是对系统的压力，消耗的callLimits也不同，具体参考每个接口；

· 所有接口消耗的callLimits是共公的；也就是说它们会互相受到速率限制的影响；

· 每个Api Key 每分钟恢复 24000 callLimits ;

· 在超频调用后，服务器会以httpStatus:418 返回超频调用警告，并且在一段时间内持续警告；您的应用在收到超频调用警告后，有必要也有义务对自己的调用频率进行降频；

· 同一Api Key进行多次超频警告后，服务器会转为httpStatus: 429 超频封禁。封禁是临时的，从最短1小时到最长7天不等，您需要在解封前处理您的调用或整改您的程序，然后再正确的发起调用；

# 3.4 调用示例

以下示例中， 假定你的Api Key为 "abcd" ， Api Secret Key 为 "test" , 你的请求时间戳为 "1234567890" ;

# 示例1:查询划转记录

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

其中请求参数为： "coin=USDT&from=EXCHANGE" (字符串，不需要URLEncode)

  1. 将它拼接你的请求时间戳, 得到HmacSHA256 Content : "coin=USDT&from=EXCHANGE1234567890" ;
  2. 再用你的Api Secret Key "test" 作为HmacSHA256 Secret Key 进行运算得到HmacResult ;
  3. 将HmacResult转Hex(十六进制) 得到签名;
String content = "coin=USDT&from=EXCHANGE1234567890";
String apiSecretKey = "test";
String hamc256Result = HmacUtils.sha256(content,secretKey);
String signature = HexUtils.parse(hexContent);

​ 得到签名结果 "58c47be0d1119874dbeabe7af16a0c0fb6901d700bc7d10adcc85ff95f9d452f" , 并放入请求头STAREX-SIGNATURE中；

最后的请求为：

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"

# 示例2:提交划转申请

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

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

其中请求参数为： {"amount":"1","coin":"USDT","from":"EXCHANGE","to":"OTC"} （压缩过后的JSON字符串)

将它拼接你的请求时间戳，得到HmacSHA256 Content : {"amount":"1","coin":"USDT","from":"EXCHANGE","to":"OTC"}1234567890

再用你的Api Secret Key "test" 作为HmacSHA256 Secret Key 进行运算并进行Hex 得到签名：

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);

得到签名结果 "3c908c790a0dcc1a308b66afc542472845f178c4e7303daa68301dcd4cf5eac9" , 并放入请求头STAREX-SIGNATURE中；

最后的请求为：

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"

更新日志 →