> For the complete documentation index, see [llms.txt](https://apidoc.hibt.co/hibt-openapi-cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidoc.hibt.co/hibt-openapi-cn/xian-huo-jiao-yi.md).

# 现货交易

## **接入准备** <a href="#jie-ru-zhun-bei" id="jie-ru-zhun-bei"></a>

### **交易对** <a href="#jie-ru-zhun-bei-1" id="jie-ru-zhun-bei-1"></a>

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

### **申请API Key**

手机访问HibtApp，进入个人设置页找到API管理，申请API Key，创建成功后请务必记住以下信息：

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

### **接口鉴权**

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

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

### **REST API**

`https://api.hibt0.com/user-open-api`

### **签名认证**

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

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

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

### **加密方式**

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

**下单请求URL**

```
https://api.hibt0.com/user-open-api/v1/trade/order?amount=0.12&direction=ASK&price=7126.4285&symbol=BTC/USDT&reqTime=1672502400000
```

对参数按照ASCII码顺序进行排序，并且带上请求时间戳**timestamp**

```
amount=0.12&direction=ASK&price=7126.4285&reqTime=1672502400000&symbol=BTC/USDT&timestamp=1672502400000
```

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

```
550ac73ace8c34372e0e1dd6631e890c7bd16697af8bb4e2908e966b50aba4e0
```

#### **构建 http 请求使用**

1. `使用`**`X-ACCESS-KEY`**`存储access key信息，并在 header 中进行参数传递`
2. `使用`**`X-SIGNATURE`**`存储生成的签名信息，并在 header 中进行参数传递`
3. `使用`**`X-TIMESTAMP`**`存储请求时间戳，并在 header 中进行参数传递`

#### **请求方式**

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

* GET请求：所有的参数都在路径参数里
* POST请求，所有参数以form-data格式发送在请求主体（body）里

#### **返回格式**

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

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

### **常见错误码** <a href="#chang-jian-cuo-wu-ma" id="chang-jian-cuo-wu-ma"></a>

#### **1xxx（访问失败类）**

#### **2xxx（业务失败类）**

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

## **现货接口** <a href="#xian-huo-jie-kou" id="xian-huo-jie-kou"></a>

### **基础信息接口** <a href="#ji-chu-xin-xi-jie-kou" id="ji-chu-xin-xi-jie-kou"></a>

#### **服务器时间**

#### **HTTP 请求**

* GET `/v1/common/systemTime`

#### **鉴权：否**

#### **限流：100次/1秒**

#### **请求参数**

此接口不接受任何参数。

#### **返回字段**

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

### **所有交易对信息** <a href="#suo-you-jiao-yi-dui-xin-xi" id="suo-you-jiao-yi-dui-xin-xi"></a>

#### **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-是） |

**返回示例**

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

### **最新成交价** <a href="#zui-xin-cheng-jiao-jia" id="zui-xin-cheng-jiao-jia"></a>

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

#### **HTTP 请求**

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

#### **鉴权：否**

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

#### **请求参数**

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

#### **返回字段**

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

#### **返回示例**

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

### **深度数据** <a href="#shen-du-shu-ju" id="shen-du-shu-ju"></a>

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

#### **HTTP 请求**

* GET `/v1/market/depth`

#### **鉴权：否**

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

#### **请求参数**

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

#### **返回字段**

| 字段名称      | 数据类型     | 描述                |
| --------- | -------- | ----------------- |
| symbol    | string   | 交易对               |
| bids      | array    | 买盘深度列表\[\[价格,数量]] |
| asks      | array    | 买盘深度列表\[\[价格,数量]] |
| timestamp | datetime | 时间                |

#### **返回示例**

```json
{
  "message": "success",
  "code": "0",
  "data": {
      "symbol" : "BTC/USDT",
      "timestamp" : "1723199363658",
      "bids" : [ [ "36074.99", "0.27225537" ], [ "36074.81", "0.00967628" ] ],
      "asks" : [ [ "36075.06", "0.55858424" ], [ "36075.24", "0.22475193" ] ]
  }
}
```

### **账户余额** <a href="#zhang-hu-jie-kou" id="zhang-hu-jie-kou"></a>

此接口返回指定币种的余额信息

#### **HTTP 请求**

* POST `/v1/account/balance`

#### **鉴权：是**

#### **限流：5次/1秒**

#### **请求参数**

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

#### **返回字段**

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

#### **返回示例**

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

### **账单列表** <a href="#zhang-hu-jie-kou-1" id="zhang-hu-jie-kou-1"></a>

此接口返回指定币种的账单列表数据。

#### **HTTP 请求**

* POST `/v1/account/bill`

#### **鉴权：是**

#### **限流：5次/1秒**

#### **请求参数**

| 参数        | 数据类型   | 是否必须 | 描述       |
| --------- | ------ | ---- | -------- |
| coin      | string | true | 币种       |
| startTime | long   | true | 开始时间（ms） |
| endTime   | long   | true | 结束时间（ms） |

#### **返回字段**

| 字段名称                | 数据类型    | 描述                       |
| ------------------- | ------- | ------------------------ |
| uid                 | long    | 用户uid                    |
| firstLevelBillType  | string  | 一级账单类型，2交易               |
| secondLevelBillType | string  | 二级账单类型名称，1充币;4现货买入;5现货卖出 |
| tradeType           | int     | 交易类型；1：现货                |
| amount              | decimal | 数量                       |
| coinUnit            | string  | 币种                       |
| createTime          | long    | 创建时间(ms)                 |

#### **返回示例**

```json
{
  "message": "success",
  "code": "0",
  "data": [
    {
      "uid": "123456",
      "firstLevelBillType": 2,
      "secondLevelBillType: 4,
      "tradeType: 1,
      "amount: 15.00,
      "coinUnit": "USDT",
      "createTime": 1672502400000
    }
  ]
}
```

### **当前委托** <a href="#jiao-yi-jie-kou" id="jiao-yi-jie-kou"></a>

#### **HTTP 请求**

* POST `/v1/trade/openOrder`

#### **鉴权：是**

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

#### **请求参数**

<table><thead><tr><th>参数</th><th>数据类型</th><th>是否必须</th><th width="213">描述</th></tr></thead><tbody><tr><td>symbol</td><td>string</td><td>true</td><td>交易对</td></tr><tr><td>direction</td><td>integer</td><td>true</td><td>订单方向（0-买；1-卖）</td></tr></tbody></table>

#### **返回字段**

| 字段名称          | 数据类型    | 描述                               |
| ------------- | ------- | -------------------------------- |
| orderId       | 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    | 订单创建时间                           |

#### **返回示例**

```json
{
  "message": "success",
  "code": "0",
  "data": [
    {
      "orderId": "E1677194831589408768",
      "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",
      "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 个月）** <a href="#li-shi-gua-dan-fan-wei-3-ge-yue" id="li-shi-gua-dan-fan-wei-3-ge-yue"></a>

#### **HTTP 请求**

* POST `/v1/trade/history`

#### **鉴权：是**

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

#### **请求参数**

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

#### **返回字段**

| 字段名称          | 数据类型    | 描述                               |
| ------------- | ------- | -------------------------------- |
| orderId       | 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    | 订单创建时间                           |

#### **返回示例**

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

### **现货下单** <a href="#xian-huo-xia-dan" id="xian-huo-xia-dan"></a>

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

#### **返回示例**

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

### **撤销委托** <a href="#che-xiao-wei-tuo" id="che-xiao-wei-tuo"></a>

#### **HTTP 请求**

* POST `/v1/trade/cancel`

#### **鉴权：是**

#### **限流：20次/1秒**

#### **请求参数**

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

#### **返回示例**

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

### 返佣列表 <a href="#fan-yong-lie-biao" id="fan-yong-lie-biao"></a>

#### **HTTP 请求**

* POST `/v1/account/rebateInfo`

#### **鉴权：是**

#### **限流：5次/1秒**

#### **请求参数**

#### **返回字段**

<table><thead><tr><th width="194">字段名称</th><th>数据类型</th><th>描述</th></tr></thead><tbody><tr><td>invitedUID</td><td>long</td><td>被邀请人UID</td></tr><tr><td>parentUID</td><td>long</td><td>邀请人(上级)UID</td></tr><tr><td>createTime</td><td>long</td><td>创建时间（ms）</td></tr><tr><td>coin</td><td>string</td><td>返佣币种</td></tr><tr><td>rebateAmount</td><td>decimal</td><td>返佣数量</td></tr><tr><td>rebateUsdtAmount</td><td>decimal</td><td>返佣代币折合usdt数量</td></tr></tbody></table>

#### **返回示例**

```json
{
  "message": "success",
  "code": "0",
  "data": [
    {
      "invitedUID": "123456",
      "parentUID": "45678",
      "coin": "BTC",
      "rebateAmount": 0.1,
      "rebateUsdtAmount": 0.1,
      "createTime": 1672502400000
    }
  ]
}
```

### K线列表 <a href="#k-xian-lie-biao" id="k-xian-lie-biao"></a>

#### **HTTP 请求**

* POST `/v1/market/kline`

#### **鉴权：是**

#### **限流：5次/1秒**

#### **请求参数**

<table><thead><tr><th>参数</th><th>数据类型</th><th width="158">是否必须</th><th>描述</th></tr></thead><tbody><tr><td>symbol</td><td>string</td><td>true</td><td>交易对</td></tr><tr><td>period</td><td>string</td><td>true</td><td>"1min", "5min", "15min", "30min", "60min", "4hour", "1day", "1week", "1mon", "1year"</td></tr><tr><td>size</td><td>int</td><td>false</td><td>获取数量，默认为100，最大500</td></tr><tr><td>from</td><td>long</td><td>true</td><td>开始时间（ms）</td></tr><tr><td>to</td><td>long</td><td>true</td><td>结束时间（ms）</td></tr></tbody></table>

#### **返回字段**

| 字段名称         | 数据类型    | 描述       |
| ------------ | ------- | -------- |
| openPrice    | decimal | 开盘       |
| highestPrice | decimal | 最高价      |
| lowestPrice  | decimal | 最低价      |
| closePrice   | decimal | 收盘价      |
| time         | long    | k线时间（ms） |
| volume       | decimal | 成交数量     |
| turnover     | decimal | 成交额      |

#### **返回示例**

```json
{
  "message": "success",
  "code": "0",
  "data": [
    {
      "openPrice": 0.5,
      "highestPrice": 1.5,
      "lowestPrice": 0.5,
      "closePrice": 0.1,
      "volume": 0.1,
      "time": 1672502400000,
      "turnover": 1.2
    }
  ]
}
```

### **用户信息** <a href="#yong-hu-xin-xi" id="yong-hu-xin-xi"></a>

#### **HTTP 请求**

* POST `/v1/account/uInfo`

#### **鉴权：是**

#### **限流：5次/1秒**

#### **请求参数**

#### **返回字段**

| 字段名称      |   | 数据类型   | 描述     |
| --------- | - | ------ | ------ |
| uid       |   | long   | 用户uid  |
| email     |   | string | 邮箱     |
| mobile    |   | string | 手机号    |
| parentUid |   | long   | 邀请人uid |

#### **返回示例**

```json
{
  "message": "success",
  "code": "0",
  "data": 
    {
      "uid": "123456",
      "email": "45678@qq.com",
      "mobile": 13800138000,
      "parentUid": 45678
    }
}
```