基本信息

REST 基本信息

  • 本篇列出REST接口的baseurl：https://api-ct.hotcoin.fit
  • 所有接口的响应都是JSON格式
  • 所有时间、时间戳均为UNIX时间，单位为毫秒

接入准备

如需使用API ，请先登录网页端，完成API key的申请和权限配置，再据此文档详情进行开发和交易。

权限说明如下：

  • 读取权限：读取权限用于对数据的查询接口，例如：订单查询、成交查询等。
  • 交易权限：交易权限用于下单、撤单、划转类接口。
  • 提币权限：提币权限用于创建提币订单、取消提币订单操作。

接口的基本信息

  • GET 方法的接口，参数必须在 query string 中发送
  • POST、PUT 和 DELETE 方法的接口，参数可以在 query string 中发送，也可以在 request body 中发送（Content-Type: application/x-www-form-urlencoded）。允许混合两种方式发送参数，但如果同一个参数名在两处均有，则以 query string 中的值为准
  • 对参数的顺序不做要求

HTTP 返回代码

  • HTTP 4XX 错误码用于指示错误的请求内容、行为或格式
  • HTTP 429 错误码表示警告访问频次超限，即将被封IP
  • HTTP 5XX 错误码用于指示服务侧的问题

接口错误代码

每个接口都有可能抛出异常，异常响应格式如下：

{
  "code": 500,
  "msg": "Invalid symbol."
}

SDK 和代码示例

Java

可以通过以下方式获取 Java SDK：

访问限制

  • 如屡次违反速率限制，将导致 IP 被封禁
  • 强烈建议尽可能多地使用 WebSocket 订阅实时数据，既可保障消息的及时性，也可减少 REST 请求带来的访问限制压力

IP 访问限制

  • 每个 IP 的访问频率有上限，超限后将收到 HTTP 429 警告
  • 持续违反限制将导致 IP 被封禁

接口鉴权类型

  • 每个接口都有自己的鉴权类型，鉴权类型决定了访问时应当进行何种鉴权
  • AccessKey 与 SecretKey 是大小写敏感的
  • 可在网页用户中心申请 API Key 并配置相应权限
鉴权类型 描述
公开接口 不需要鉴权，如行情数据接口
私有接口 需要有效的 AccessKey 和签名，如资产、订单、仓位接口

权限说明：

  • 读取权限：用于查询数据，例如：订单查询、成交查询等
  • 交易权限：用于下单、撤单等操作
  • 提币权限：用于创建、取消提币订单

需要签名的接口

调用私有接口时，除接口本身所需的参数外，还需传递以下签名相关参数：

参数 说明
AccessKeyId 您申请的 API Key 中的 AccessKey
SignatureMethod 签名所用的哈希算法，固定为 HmacSHA256
SignatureVersion 签名协议版本，固定为 2
Timestamp 请求发出时刻的 UTC 时间，如 2017-05-11T16:22:06.123Z
Signature 经签名运算得出的值
  • 签名大小写不敏感
  • 请确保 Signature 参数位于请求的最后

签名运算

API 请求在通过 Internet 发送的过程中极有可能被篡改。为了确保请求未被更改，所有私有接口都必须携带签名。

示例信息：

Key Value
AccessKey AccessKeyHotcoin123456789
SecretKey SecretKeyHotcoin123456789
参数 取值
AccessKeyId AccessKeyHotcoin123456789
SignatureMethod HmacSHA256
SignatureVersion 2
Timestamp 2017-05-11T16:22:06.123Z

第1步：构造待签名字符串

将以下内容依次用换行符 \n 连接：

  1. 请求方法（大写），如 GET
  2. 主机名（小写），如 api-ct.hotcoin.fit
  3. 请求路径，如 /api/v1/perpetual/account/assets/btcusdt
  4. 按 ASCII 码升序排列并 URL 编码后的请求参数（十六进制字母大写，如 : 编码为 %3A，空格编码为 %20）

示例请求：

https://api-ct.hotcoin.fit/api/v1/perpetual/account/assets/btcusdt?
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123Z

第2步：对参数按 ASCII 排序并 URL 编码

AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z

第3步：组成最终签名字符串

GET\n
api-ct.hotcoin.fit\n
/api/v1/perpetual/account/assets/btcusdt\n
AccessKeyId=AccessKeyHotcoin123456789&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T16%3A22%3A06.123Z

第4步：计算 HmacSHA256 签名并 Base64 编码

以 SecretKey 为密钥，对第3步中的字符串进行 HmacSHA256 计算，再进行 Base64 编码：

SecretKey: SecretKeyHotcoin123456789
签名结果：ND/9e/TW6pqNSeDKkBYnXHaKye7Wfivu2Vk3EYRl2W8=

第5步：将签名附加到请求

将签名进行 URI 编码后，以 Signature 参数附加到请求末尾：

https://api-ct.hotcoin.fit/api/v1/perpetual/account/assets/btcusdt
?AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z
&Signature=ND/9e/TW6pqNSeDKkBYnXHaKye7Wfivu2Vk3EYRl2W8=

时间同步安全

  • 签名接口均需要传递 Timestamp 参数，其值应为请求发送时刻的 UTC 时间，格式如 2017-05-11T16:22:06.123Z
  • 若请求时间戳与服务器时间差距过大，请求将被拒绝
  • 建议定期同步本地时间以确保请求时效性

可通过以下接口获取服务器当前时间：

GET /api/v1/perpetual/public/time