# Hibt OpenAPI 文档

## API 介绍

### 接入准备

**交易对**

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

#### 申请API Key

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

* `Access Key` API 访问密钥
* `Secret Key` 签名认证加密所使用的密钥（仅申请时可见）

**接口鉴权**

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

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

#### 接入URLs

**REST API**

<https://api.hibt0.co/open-api>

#### 签名认证

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

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

* 方法请求地址：即访问服务器地址 <https://api.hibt0.com/open-api。>
* API 访问密钥（X-ACCESS-KEY）：您申请的 API Key 中的 Access Key。
* 必选和可选参数：每个方法都有一组用于定义 API 调用的必需参数和可选参数。可以在每个方法的说明中查看这些参数及其含义。
* 签名：加密计算得出的值，用于确保签名有效和未被篡改，**为了您 API Key 的安全，一次参数签名 5 分钟后会过期**。
* **签名必要参数\*\*：需要签名认证的接口，必须添加 reqTime 参数（传值为服务器最新时间，可通过`/v1/common/systemTime` 接口获取）。**

**加密方式**

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

下单请求URL

```
https://api.hibt0.com/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
    }
  ]
}
```

### 行情接口

**最新成交价**

&#x20;   此接口提供交易对当前最新成交价

**HTTP 请求**

* GET `/v1/market/ticker/price`

**鉴权：否**

**限流：10次/1秒**

**请求参数**

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

**返回字段**

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

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

**深度数据**

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

**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" ] ]
  }
}
```

### 账户接口

**账户余额**

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

**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秒**

**请求参数**

| 参数      | 数据类型   | 是否必须 | 描述    |
| ------- | ------ | ---- | ----- |
| symbol  | string | true | 交易对   |
| orderId | string | true | 订单 ID |

**返回字段**

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