# 现货交易(做市商)

## API 介绍 <a href="#api-jie-shao" id="api-jie-shao"></a>

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

#### **交易对**

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

#### **申请API Key**

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

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

#### **接口鉴权**

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

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

#### **接入URL**

**REST API**

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

### **常见错误码** <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 被禁用               |
| 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`

**鉴权：否**

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

**请求参数**

此接口不接受任何参数。

**返回字段**

```json
{
  "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-是） |

```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="#hang-qing-jie-kou" id="hang-qing-jie-kou"></a>

#### **最新成交价**

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

**HTTP 请求**

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

**鉴权：否**

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

**请求参数**

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

**返回字段**

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

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

#### **深度数据**

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

**HTTP 请求**

**GET** `/v1/market/depth`

**鉴权：否**

**限流：2次/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" : "2023-11-22 10:00:00",
      "bids" : [ [ "36074.99", "0.27225537" ], [ "36074.81", "0.00967628" ] ],
      "asks" : [ [ "36075.06", "0.55858424" ], [ "36075.24", "0.22475193" ] ]
  }
}
```

#### **K线数据**

此接口返回指定交易对的历史K线数据。

**HTTP 请求**

**GET** `/v1/market/kline`

**鉴权：否**

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

**请求参数**

<table><thead><tr><th>参数</th><th>数据类型</th><th>是否必须</th><th width="135.05615234375">描述</th><th width="247.8958740234375">取值范围</th></tr></thead><tbody><tr><td>symbol</td><td>string</td><td>true</td><td>交易对</td><td></td></tr><tr><td>period</td><td>string</td><td>true</td><td>k线周期</td><td>分钟:1min;5min;15min;30minx小时:1hour;4hour 天:1day 周:1week 月:1month</td></tr><tr><td>from</td><td>long</td><td>true</td><td>开始时间</td><td>毫秒</td></tr><tr><td>to</td><td>long </td><td>false</td><td>结束时间</td><td>毫秒，不填表示为当前时间</td></tr><tr><td>limit</td><td>integer</td><td>false</td><td>返回条数</td><td>不填默认500，最大1000</td></tr></tbody></table>

**返回字段**

```json
{
  "data": [
    [
      "1765555200000", // 开盘时间
      "89926.2", // 开盘价
      "90050.0", // 最高价
      "89785.5", // 最低价
      "89959.9", // 收盘价
      "30.8345", // 成交量
      "2773034.7896", // 计价货币成交额
      "2209" //成交笔数
    ],
    [
      "1765555260000",
      "89960",
      "90031.5",
      "89863.9",
      "89911.9",
      "19.8816",
      "1788283.7845",
      "1808"
    ]
  ],
  "code": 0,
  "message": "SUCCESS",
  "success": true
}
```

#### 历史成交记录

此接口返回指定交易对的成交记录(倒序查询）

**HTTP 请求**

**GET** `/v1/market/historicalTrades`

**鉴权：否**

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

**请求参数**

<table><thead><tr><th>参数</th><th>数据类型</th><th>是否必须</th><th width="135.05615234375">描述</th><th width="247.8958740234375">说明</th></tr></thead><tbody><tr><td>symbol</td><td>string</td><td>true</td><td>交易对</td><td></td></tr><tr><td>beforeId</td><td>string</td><td>false</td><td>查询开始id</td><td>查询该id之前的交易记录，不传按最新成交id向前查询</td></tr><tr><td>limit</td><td>integer</td><td>false</td><td>返回条数</td><td>不填默认100，最大100</td></tr></tbody></table>

**返回字段**

```json
{
  "data" : [ {
    "id" : "693d3d73453ac877d3233e55", // 成交id
    "price" : "90487.8", // 成交价
    "qty" : "0.0024", // 成交量
    "quoteQty" : "217.170912", // 计价货币成交额
    "time" : 1765621107203, // 成交时间
    "side" : "SELL" // 成交方向,买(BUY),卖(SELL)
  }, {
    "id" : "693d3d72453ac877d3233e14",
    "price" : "90487.8",
    "qty" : "0.0026976",
    "quoteQty" : "244.10013216",
    "time" : 1765621106245,
    "side" : "BUY"
  } ],
  "code" : 0,
  "message" : "SUCCESS",
  "success" : true
}
```

### **账户接口** <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="#jiao-yi-jie-kou" id="jiao-yi-jie-kou"></a>

#### **未完成挂单**

**HTTP 请求**

**POST** `/v1/trade/openOrder`

**鉴权：是**

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

**请求参数**

<table><thead><tr><th width="152">参数</th><th>数据类型</th><th width="153">是否必须</th><th>描述</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>

**返回字段**

<table><thead><tr><th width="207.1788330078125">字段名称</th><th width="148.6419677734375">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>orderId</td><td>string</td><td>挂单 ID</td></tr><tr><td>price</td><td>decimal</td><td>订单价格</td></tr><tr><td>avgPrice</td><td>decimal</td><td>成交均价</td></tr><tr><td>amount</td><td>decimal</td><td>买盘深度列表</td></tr><tr><td>tradedAmount</td><td>decimal</td><td>已成交数量</td></tr><tr><td>turnover</td><td>decimal</td><td>交易额（已成交数量*成交价格）</td></tr><tr><td>symbol</td><td>string</td><td>交易对</td></tr><tr><td>baseSymbol</td><td>string</td><td>计价币种</td></tr><tr><td>coinSymbol</td><td>string</td><td>商品币种</td></tr><tr><td>direction</td><td>enum</td><td>方向（BUY-买；SELL-卖）</td></tr><tr><td>status</td><td>enum</td><td>状态（TRADING-交易中；COMPLETED-完成；CANCELED-取消；OVERTIMED-超时；PARTLY-部分成交；）</td></tr><tr><td>type</td><td>enum</td><td>类型（MARKET_PRICE-市价；LIMIT_PRICE-限价；）</td></tr><tr><td>completedTime</td><td>long</td><td>订单完成时间(委托中订单为null)</td></tr><tr><td>canceledTime</td><td>long</td><td>订单取消时间(委托中订单为null)</td></tr><tr><td>time</td><td>long</td><td>订单创建时间</td></tr></tbody></table>

```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": "BUY",
      "status": "TRADING",
      "type": "LIMIT_PRICE",
      "completedTime": null,
      "canceledTime": null,
      "time": 1672502400000
    },{
      "orderId": "E1677269378757951488",
      "price": 2000,
      "avgPrice": 0,
      "amount": 1,
      "tradedAmount": 0,
      "turnover": 0,
      "symbol": "ETH/USDT",
      "baseSymbol": "USDT",
      "coinSymbol": "ETH",
      "direction": "BUY",
      "status": "TRADING",
      "type": "LIMIT_PRICE",
      "completedTime": null,
      "canceledTime": null,
      "time": 1672502400000
    }
  ]
}
```

#### **历史挂单（最大返回1000条）**

**HTTP 请求**

**POST** `/v1/trade/history`

**鉴权：是**

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

**请求参数**

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

**返回字段**

<table><thead><tr><th width="207.1788330078125">字段名称</th><th width="148.6419677734375">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>orderId</td><td>string</td><td>挂单 ID</td></tr><tr><td>price</td><td>decimal</td><td>订单价格</td></tr><tr><td>avgPrice</td><td>decimal</td><td>成交均价</td></tr><tr><td>amount</td><td>decimal</td><td>买盘深度列表</td></tr><tr><td>tradedAmount</td><td>decimal</td><td>已成交数量</td></tr><tr><td>turnover</td><td>decimal</td><td>交易额（已成交数量*成交价格）</td></tr><tr><td>symbol</td><td>string</td><td>交易对</td></tr><tr><td>baseSymbol</td><td>string</td><td>计价币种</td></tr><tr><td>coinSymbol</td><td>string</td><td>商品币种</td></tr><tr><td>direction</td><td>enum</td><td>方向（BUY-买；SELL-卖）</td></tr><tr><td>status</td><td>enum</td><td>状态（TRADING-交易中；COMPLETED-完成；CANCELED-取消；OVERTIMED-超时；PARTLY-部分成交；）</td></tr><tr><td>type</td><td>enum</td><td>类型（MARKET_PRICE-市价；LIMIT_PRICE-限价；）</td></tr><tr><td>completedTime</td><td>long</td><td>订单完成时间</td></tr><tr><td>canceledTime</td><td>long</td><td>订单取消时间</td></tr><tr><td>time</td><td>long</td><td>订单创建时间</td></tr></tbody></table>

```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": "BUY",
      "status": "TRADING",
      "type": "LIMIT_PRICE",
      "completedTime": null,
      "canceledTime": null,
      "time": 1672502400000
    },{
      "orderId": "E1677269378757951488",
      "price": 2000,
      "avgPrice": 0,
      "amount": 1,
      "tradedAmount": 0,
      "turnover": 0,
      "symbol": "ETH/USDT",
      "baseSymbol": "USDT",
      "coinSymbol": "ETH",
      "direction": "BUY",
      "status": "TRADING",
      "type": "LIMIT_PRICE",
      "completedTime": null,
      "canceledTime": null,
      "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 |

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

#### **撤销**

**HTTP 请求**

**POST** `/v1/trade/cancel`

**鉴权：是**

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

**请求参数**

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

**返回字段**

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