# 现货交易

## **接入准备** <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
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidoc.hibt.co/hibt-openapi-cn/xian-huo-jiao-yi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.