HotsCoin OpenAPI 文档

API 介绍

接入准备

交易对

交易对由基础币种和报价币种组成。以交易对 BTC/USDT 为例，BTC 为商品币种，USDT 为计价币种。

申请API Key

创建成功后请务必记住以下信息：

• Access Key API 访问密钥

• Secret Key 签名认证加密所使用的密钥（仅申请时可见）

接口鉴权

公共接口可用于获取基础信息和行情数据。公共接口无需认证即可调用。

私有接口可用于交易管理和账户管理。每个私有请求必须使用您的API Key进行签名验证。

接入URLs

REST API

https://api.hotscoin0.co/open-api

签名认证

API 请求在通过 internet 传输的过程中极有可能被篡改，为了确保请求未被更改，除公共接口（基础信息，行情数据）外的私有接口均必须使用您的 API Key 做加密处理，以校验参数或参数值在传输途中是否发生了更改。 每一个API Key需要有适当的权限才能访问相应的接口，每个新创建的API Key都需要分配权限。在使用接口前，请查看每个接口的权限类型，并确认你的API Key有相应的权限。

一个合法的请求所需要的内容：

• 方法请求地址：即访问服务器地址 https://api.hotscoin0.co/open-api。

• API 访问密钥（X_ACCESS_KEY）：您申请的 API Key 中的 Access Key。

• 必选和可选参数：每个方法都有一组用于定义 API 调用的必需参数和可选参数。可以在每个方法的说明中查看这些参数及其含义。

• 签名：加密计算得出的值，用于确保签名有效和未被篡改，为了您 API Key 的安全，一次参数签名 5 分钟后会过期。

• 签名必要参数**：需要签名认证的接口，必须添加 reqTime 参数（传值为服务器最新时间，可通过/v1/common/systemTime 接口获取）。

加密方式

规范要计算签名的请求 因为使用 HMAC 进行签名计算时，使用不同内容计算得到的结果会完全不同。所以在进行签名计算前，请先对请求进行规范化处理。下面以查询某订单详情请求为例进行说明：

下单请求URL

https://api.hotscoin0.co/open-api/v1/trade/order?amount=0.12&direction=ASK&price=7126.4285&symbol=BTC_USDT&reqTime=1672502400000

对参数按照ASCII码顺序进行排序

amount=0.12&direction=ASK&price=7126.4285&reqTime=1672502400000&symbol=BTC_USDT

将排完序的请求参数使用secretKey 进行HMAC SHA256进行加密，得到的结果

550ac73ace8c34372e0e1dd6631e890c7bd16697af8bb4e2908e966b50aba4e0

构建 http 请求使用

1. 使用 X_ACCESS_KEY 存储access key信息，并在 header 中进行参数传递

2. 使用 X_SIGNATURE 存储生成的签名信息，并在 header 中进行参数传递

请求方式

目前只有两种方法：GET和POST

• GET请求：所有的参数都在路径参数里

• POST请求，所有参数以form-data格式发送在请求主体（body）里

返回格式

所有的接口都是JSON格式。在JSON最上层有三个字段：message, code 和 data。前两个字段表示请求状态和信息，实际的业务数据在data字段里。

{
  "message": "success",
  "code": "0",
  "data": ""
}

常见错误码

1xxx（访问失败类）

2xxx（业务失败类）

错误码	描述
0	成功
1001	接口请求限流
1101	API Key鉴权失败
1102	密钥解密失败
1103	访问 IP 不在白名单内
2001	参数为空
2002	时间范围错误
2003	请求时间参数为空
2004	请求时间已过期
2101	账户不存在
2102	API Key不存在
2103	交易对不存在
2201	用户 API Key 被禁用
2202	IP 被禁用
9999	其他异常，具体参照 message 内容

现货接口

基础信息接口

服务器时间

HTTP 请求

• GET /v1/common/systemTime

鉴权：否

限流：100次/1秒

请求参数

此接口不接受任何参数。

返回字段

字段名称	数据类型	描述
data	long	服务器时间戳

{
  "message": "success",
  "code": "0",
  "data": 1672502400000
}

所有交易对信息

HTTP 请求

• GET /v1/common/symbols

鉴权：否

限流：5次/1秒

请求参数

此接口不接受任何参数。

返回字段

字段名称	数据类型	描述
symbol	string	交易对
baseCoinScale	integer	计价币数量精度
coinScale	integer	商品币数量精度
priceScale	integer	价格精度
baseSymbol	string	基础币
coinSymbol	string	计价币
minTurnover	decimal	最小挂单成交额
minVolume	decimal	最小下单量
maxVolume	decimal	最大下单量
enable	integer	是否支持交易（0-否；1-是）

{
  "message": "success",
  "code": "0",
  "data": [
    {
      "symbol": "BTC/USDT", // 交易对
      "baseCoinScale": 4, // 计价币数量精度
      "coinScale": 4, // 商品币数量精度
      "priceScale": 2, // 价格精度
      "baseSymbol": "USDT", // 计价币种
      "coinSymbol":"BTC", // 商品币种
      "minTurnover": 10, // 最小挂单成交额
      "minVolume": 0.001, // 最小下单量
      "maxVolume": 50, // 最大下单量
      "enable":  1 // 是否启用
    },
    {
      "symbol": "ETH/USDT",
      "baseCoinScale": 4,
      "coinScale": 4,
      "baseSymbol": "USDT",
      "coinSymbol":"ETH",
      "minTurnover": 10,
      "minVolume": 0.01,
      "maxVolume": 500,
      "enable": 1
    }
  ]
}

行情接口

最新成交价

此接口提供交易对当前最新成交价

HTTP 请求

• GET /v1/market/ticker/price

鉴权：否

限流：10次/1秒

请求参数

参数	数据类型	是否必须	描述
symbol	string	true	交易对

返回字段

字段名称	数据类型	描述
tickerPrice	decimal	最新成交价

{
  "message": "success",
  "code": "0",
  "data": {
      "tickerPrice": 40000
    }
}

深度数据

此接口返回指定交易对的当前深度数据。

HTTP 请求

• GET /v1/market/depth

鉴权：否

限流：10次/1秒

请求参数

参数	数据类型	是否必须	描述	取值范围
symbol	string	true	交易对
depth	integer	true	返回深度的数量	最大 50 档

返回字段

字段名称	数据类型	描述
symbol	string	交易对
bids	array	买盘深度列表
asks	array	买盘深度列表
timestamp	datetime	时间

{
  "message": "success",
  "code": "0",
  "data": {
      "symbol" : "BTC/USDT",
      "timestamp" : "2023-11-22 10:00:00",
      "bids" : [ [ "36074.99", "0.27225537" ], [ "36074.81", "0.00967628" ] ],
      "asks" : [ [ "36075.06", "0.55858424" ], [ "36075.24", "0.22475193" ] ]
  }
}

账户接口

账户余额

此接口返回指定交易对的当前深度数据。

HTTP 请求

• POST /v1/account/balance

鉴权：是

限流：5次/1秒

请求参数

参数	数据类型	是否必须	描述
coin	string	false	币种

返回字段

字段名称	数据类型	描述
coin	string	币种
balance	decimal	余额
frozenBalance	decimal	冻结余额
isLock	string	是否锁定

{
  "message": "success",
  "code": "0",
  "data": [
    {
      "coin": "USDT",
      "balance": 1000,
      "frozenBalance": 1000,
      "isLock": "IS_FALSE"
    },{
      "coin": BTC,
      "balance": 1,
      "frozenBalance": 0.01,
      "isLock": "IS_TRUE"
    }
  ]
}

交易接口

未完成挂单

HTTP 请求

• POST /v1/trade/openOrder

鉴权：是

限流：10次/1秒

请求参数

参数	数据类型	是否必须	描述
symbol	string	true	交易对
direction	integer	true	订单方向（0-买；1-卖）

返回字段

字段名称		数据类型	描述
orderId		string	挂单 ID
clOrdId		string	客户自定义订单ID
price		decimal	订单价格
avgPrice		decimal	成交均价
amount		decimal	买盘深度列表
tradedAmount		decimal	已成交数量
turnover		decimal	交易额（已成交数量*成交价格）
symbol		string	交易对
baseSymbol		string	计价币种
coinSymbol		string	商品币种
direction		integer	方向（0-买；1-卖）
status		integer	状态（0-交易中；1-完成；2-取消；3-超时；4-部分成交；）
type		integer	类型（0-市价；1-限价；）
completedTime		long	订单完成时间
canceledTime		long	订单取消时间
time		long	订单创建时间

{
  "message": "success",
  "code": "0",
  "data": [
    {
      "orderId": "E1677194831589408768",
      "clOrdId": "1677AAA",
      "price": 35000,
      "avgPrice": 0,
      "amount": 0.1,
      "tradedAmount": 0,
      "turnover": 0,
      "symbol": "BTC/USDT",
      "baseSymbol": "USDT",
      "coinSymbol": "BTC",
      "direction": 0,
      "status": 0,
      "type": 1,
      "completedTime": 1672502400000,
      "canceledTime": 1672502400000,
      "time": 1672502400000
    },{
      "orderId": "E1677269378757951488",
      "clOrdId": "1677AAA",
      "price": 2000,
      "avgPrice": 0,
      "amount": 1,
      "tradedAmount": 0,
      "turnover": 0,
      "symbol": "ETH/USDT",
      "baseSymbol": "USDT",
      "coinSymbol": "ETH",
      "direction": 1,
      "status": 0,
      "type": 1,
      "completedTime": 1672502400000,
      "canceledTime": 1672502400000,
      "time": 1672502400000
    }
  ]
}

历史挂单（范围 3 个月）

HTTP 请求

• POST /v1/trade/history

鉴权：是

限流：10次/1秒

请求参数

参数	数据类型	是否必须	描述
symbol	string	true	交易对
startTime	long	true	开始时间（ms）
endTime	long	true	结束时间（ms）

返回字段

字段名称		数据类型	描述
orderId		string	挂单 ID
clOrdId		string	客户自定义订单ID
price		decimal	订单价格
avgPrice		decimal	成交均价
amount		decimal	买盘深度列表
tradedAmount		decimal	已成交数量
turnover		decimal	交易额（已成交数量*成交价格）
symbol		string	交易对
baseSymbol		string	计价币种
coinSymbol		string	商品币种
direction		integer	方向（0-买；1-卖）
status		integer	状态（0-交易中；1-完成；2-取消；3-超时；4-部分成交；）
type		integer	类型（0-市价；1-限价；）
completedTime		long	订单完成时间
canceledTime		long	订单取消时间
time		long	订单创建时间

{
  "message": "success",
  "code": "0",
  "data": [
    {
      "orderId": "E1677226372826791936",
      "clOrdId": "1677AAA",
      "price": 35000,
      "avgPrice": 35000,
      "amount": 0.1,
      "tradedAmount": 0.1,
      "turnover": 3500,
      "symbol": "BTC/USDT",
      "baseSymbol": "USDT",
      "coinSymbol": "BTC",
      "direction": 0,
      "status": 1,
      "type": 1,
      "completedTime": 1672502400000,
      "canceledTime": 1672502400000,
      "time": 1672502400000
    },{
      "orderId": "E1677261905426776064",
      "clOrdId": "1677AAA",
      "price": 2000,
      "avgPrice": 2000,
      "amount": 1,
      "tradedAmount": 1,
      "turnover": 2000,
      "symbol": "ETH/USDT",
      "baseSymbol": "USDT",
      "coinSymbol": "ETH",
      "direction": 1,
      "status": 1,
      "type": 1,
      "completedTime": 1672502400000,
      "canceledTime": 1672502400000,
      "time": 1672502400000
    }
  ]
}

下单

HTTP 请求

• POST /v1/trade/order

鉴权：是

限流：20次/1秒

请求参数

参数	数据类型	是否必须	描述
symbol	string	true	交易对
price	decimal	true	价格（市价单传 0 即可）
amount	decimal	true	数量（市价买单：表示 需要买入的交易额，以USDT 为单位；市价卖单：表示需要卖出的商品币数量；）
direction	integer	true	方向（0-买；1-卖）
type	integer	true	类型（0-市价；1-限价）

返回字段

字段名称		数据类型	描述
data		string	挂单 ID

{
  "message": "success",
  "code": "0",
  "data": "E1677226372826791936"
}

撤销

HTTP 请求

• POST /v1/trade/cancel

鉴权：是

限流：20次/1秒

请求参数

参数	数据类型	是否必须	描述
orderId	string	true	订单 ID

返回字段

{
  "message": "success",
  "code": "0",
  "data": ""
}