> For the complete documentation index, see [llms.txt](https://zhonghuahan.gitbook.io/v/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zhonghuahan.gitbook.io/v/english/bi-bi-jiao-yi.md).

# Spot

## Public

### Security: [None](/v/english/ji-ben-xin-xi.md#jie-kou-jian-quan-lei-xing)

Endpoints under **Public** section can be accessed freely without requiring any API-key or signatures.

##  Test Connectivity

<mark style="color:blue;">`GET`</mark> `https://openapi.xxx.com/sapi/v1/ping`

&#x20;This endpoint checks connectivity to the host

{% tabs %}
{% tab title="200  Connection normal" %}

```
{}
```

{% endtab %}
{% endtabs %}

## &#x20;Check Server Time

<mark style="color:blue;">`GET`</mark> `https://openapi.xxx.com/sapi/v1/time`

&#x20;This endpoint checks connectivity to the server and retrieves server timestamp

{% tabs %}
{% tab title="200  Successfully retrieved server time" %}

```java
{
    "timezone": "GMT+08:00",
    "serverTime": 1595563624731
}
```

{% endtab %}
{% endtabs %}

## Pairs List&#x20;

<mark style="color:blue;">`GET`</mark> `https://openapi.xxx.com/sapi/v1/symbols`

{% tabs %}
{% tab title="200 Successfully retrieved pairs list" %}

```java
{
    "symbols": [
        {
            "quantityPrecision": 3,
            "symbol": "sccadai",
            "pricePrecision": 6,
            "baseAsset": "SCCA",
            "quoteAsset": "DAI"
        },
        {
            "quantityPrecision": 8,
            "symbol": "btcusdt",
            "pricePrecision": 2,
            "baseAsset": "BTC",
            "quoteAsset": "USDT"
        },
        {
            "quantityPrecision": 3,
            "symbol": "bchusdt",
            "pricePrecision": 2,
            "baseAsset": "BCH",
            "quoteAsset": "USDT"
        },
        {
            "quantityPrecision": 2,
            "symbol": "etcusdt",
            "pricePrecision": 2,
            "baseAsset": "ETC",
            "quoteAsset": "USDT"
        },
        {
            "quantityPrecision": 2,
            "symbol": "ltcbtc",
            "pricePrecision": 6,
            "baseAsset": "LTC",
            "quoteAsset": "BTC"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Response:

| name              | type    | example   | description                     |
| ----------------- | ------- | --------- | ------------------------------- |
| symbol            | string  | `BTCUSDT` | Name of the symbol              |
| baseAsset         | string  | `BTC`     | Underlying asset for the symbol |
| quoteAsset        | string  | `USDT`    | Quote asset for the symbol      |
| pricePrecision    | integer | `2`       | Precision of the price          |
| quantityPrecision | integer | `6`       | Precision of the quantity       |

## Market

### Security Type: [None](/v/english/ji-ben-xin-xi.md#jie-kou-jian-quan-lei-xing)

**Market** section can be accessed freely without requiring any API-key or signatures.

## &#x20;Depth

<mark style="color:blue;">`GET`</mark> `https://openapi.xxx.com/sapi/v1/depth`

&#x20;market detpth data

#### Query Parameters

| Name   | Type    | Description              |
| ------ | ------- | ------------------------ |
| limit  | integer | Default 100; Max 100     |
| symbol | string  | Symbol Name E.g. BTCUSDT |

{% tabs %}
{% tab title="200  Successfully retrieved market depth data" %}

```java
{
  "bids": [
    [
      "3.90000000",   // price
      "431.00000000"  // vol
    ],
    [
      "4.00000000",
      "431.00000000"
    ]
  ],
  "asks": [
    [
      "4.00000200",  // price
      "12.00000000"  // vol
    ],
    [
      "5.10000000",
      "28.00000000"
    ]
  ]
}
```

{% endtab %}
{% endtabs %}

#### Response:

| name | type | example         | description                                                     |
| ---- | ---- | --------------- | --------------------------------------------------------------- |
| time | long | `1595563624731` | Current timestamp (ms)                                          |
| bids | list | ;               | List of all bids, best bids first. See below for entry details. |
| asks | list | ;               | List of all asks, best asks first. See below for entry details. |

The fields bids and asks are lists of order book price level entries, sorted from best to worst.

| name | type  | example | description                                       |
| ---- | ----- | ------- | ------------------------------------------------- |
| ' '  | float | `131.1` | price level                                       |
| ' '  | float | `2.3`   | The total quantity of orders for this price level |

## &#x20;24hrs ticker

<mark style="color:blue;">`GET`</mark> `https://openapi.xxx.com/sapi/v1/ticker`

&#x20;24 hour price change statistics.

#### Query Parameters

| Name   | Type   | Description                 |
| ------ | ------ | --------------------------- |
| symbol | string | Symbol Name. E.g. `BTCUSDT` |

{% tabs %}
{% tab title="200  Successfully retrieved ticker data" %}

```java
{
    "high": "9279.0301",
    "vol": "1302",
    "last": "9200",
    "low": "9279.0301",
    "rose": "0",
    "time": 1595563624731
}
```

{% endtab %}
{% endtabs %}

#### Response:

| name | type  | example         | description  |
| ---- | ----- | --------------- | ------------ |
| time | long  | `1595563624731` | Open Time    |
| high | float | `9900`          | High Price   |
| low  | float | `8800.34`       | Low Price    |
| open | float | `8700`          | Open Price   |
| last | float | `8900`          | Last Price   |
| vol  | float | `4999`          | Trade Volume |

## Trade

### Security Type: [TRADE](/v/english/ji-ben-xin-xi.md#jie-kou-jian-quan-lei-xing)

Endpoints under **Trade** require an [API-key and a signature.](/v/english/ji-ben-xin-xi.md#xu-yao-qian-ming-de-jie-kou-trade-yu-userdata)

## &#x20;New Order

<mark style="color:green;">`POST`</mark> `https://openapi.xxx.com/sapi/v1/order`

&#x20;**Rate Limit: 100times/2s**

#### Headers

| Name        | Type    | Description  |
| ----------- | ------- | ------------ |
| X-CH-SIGN   | string  | Sign         |
| X-CH-APIKEY | string  | Your API-key |
| X-CH-TS     | integer | timestamp    |

#### Request Body

| Name             | Type    | Description                                             |
| ---------------- | ------- | ------------------------------------------------------- |
| symbol           | string  | Symbol Name. E.g. `BTCUSDT`                             |
| volume           | number  | Order vol. For MARKET BUY orders,  vol=amount.          |
| side             | string  | Side of the order,`BUY/SELL`                            |
| type             | string  | Type of the order, `LIMIT/MARKET`                       |
| price            | number  | Order price, REQUIRED for LIMIT orders                  |
| newClientOrderId | string  | Unique order ID generated by users to mark their orders |
| recvWindow       | integer | Time window                                             |

{% tabs %}
{% tab title="200  Successfully post new order" %}

```java
{
    'symbol': 'LXTUSDT', 
    'orderId': '150695552109032492', 
    'clientOrderId': '157371322565051',
    'transactTime': '1573713225668', 
    'price': '0.005452', 
    'origQty': '110', 
    'executedQty': '0', 
    'status': 'NEW',
    'type': 'LIMIT', 
    'side': 'SELL'
}
```

{% endtab %}
{% endtabs %}

#### **Response:**

| name            | type    | example              | description                                                                                                     |
| --------------- | ------- | -------------------- | --------------------------------------------------------------------------------------------------------------- |
| `orderId`       | long    | `150695552109032492` | ID of the order                                                                                                 |
| `clientOrderId` | string  | `213443`             | A unique ID of the order.                                                                                       |
| `symbol`        | string  | `BTCUSDT`            | Symbol Name                                                                                                     |
| `transactTime`  | integer | `1273774892913`      | Time the order is placed                                                                                        |
| `price`         | float   | `4765.29`            | Price of the order                                                                                              |
| `origQty`       | float   | `1.01`               | Quantity ordered                                                                                                |
| `executedQty`   | float   | `1.01`               | Quantity of orders that has been executed                                                                       |
| `type`          | string  | `LIMIT`              | Order type `LIMIT,MARKET`                                                                                       |
| `side`          | string  | `BUY`                | Order side：`BUY, SELL`                                                                                          |
| `status`        | string  | `NEW`                | The state of the order.Possible values include `NEW`, `PARTIALLY_FILLED`, `FILLED`, `CANCELED`, and `REJECTED`. |

## &#x20;Test New Order

<mark style="color:green;">`POST`</mark> `https://openapi.xxx.com/sapi/v1/order/test`

&#x20;Test new order creation and signature/recvWindow length. Creates and validates a new order but does not send the order into the matching engine.

#### Headers

| Name        | Type    | Description  |
| ----------- | ------- | ------------ |
| X-CH-SIGN   | string  | Sign         |
| X-CH-APIKEY | string  | Your API-key |
| X-CH-TS     | integer | timestamp    |

#### Request Body

| Name             | Type    | Description                                             |
| ---------------- | ------- | ------------------------------------------------------- |
| recvWindow       | integer | Time window                                             |
| symbol           | string  | Symbol Name. E.g. `BTCUSDT`                             |
| volume           | number  | Order vol. For MARKET BUY orders, vol=amount.           |
| side             | string  | Side of the order, `BUY/SELL`                           |
| type             | string  | Type of the order, `LIMIT/MARKET`                       |
| price            | number  | Order price, REQUIRED for `LIMIT` orders                |
| newClientOrderId | string  | Unique order ID generated by users to mark their orders |

{% tabs %}
{% tab title="200  Successfully test new order" %}

```
{}
```

{% endtab %}
{% endtabs %}

## &#x20;Batch Orders

<mark style="color:green;">`POST`</mark> `https://openapi.xxx.com/sapi/v1/batchOrders`

&#x20;**Rate Limit: 50times/2s A batch contains at most 10 orders**

#### Headers

| Name        | Type    | Description  |
| ----------- | ------- | ------------ |
| X-CH-SIGN   | string  | Sign         |
| X-CH-APIKEY | string  | Your API-key |
| X-CH-TS     | integer | timestamp    |

#### Request Body

| Name   | Type   | Description                 |
| ------ | ------ | --------------------------- |
| orders | array  | Batch order param           |
| symbol | string | Symbol Name. E.g. `BTCUSDT` |

{% tabs %}
{% tab title="200 " %}

```java
{
    "mass_place": [
        {
            "msg": "Success",
            "order_id": [
                150951796778795013,
                150951796778795014
            ],
            "code": "0"
        }
    ],
    "mass_cancel": []
}
```

{% endtab %}
{% endtabs %}

#### Resquest `orders` field:

| name        | type   | example        | description             |
| ----------- | ------ | -------------- | ----------------------- |
| `price`     | folat  | 1000           | Price of the order      |
| `volume`    | folat  | 20.1           | Vol of the order        |
| `side`      | string | `BUY/SELL`     | Side of the order       |
| `batchType` | string | `LIMIT/MARKET` | Batch type of the order |

## &#x20;Query Order

<mark style="color:blue;">`GET`</mark> `https://openapi.xxx.com/sapi/v1/order`

&#x20;**Rate Limit: 20times/2s**

#### Query Parameters

| Name             | Type   | Description                                                                                      |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------ |
| orderId          | string | Order ID                                                                                         |
| newClientOrderId | string | Client Order Id, Unique order ID generated by users to mark their orders. E.g. 354444heihieddada |
| symbol           | string | Symbol Name. E.g. `BTCUSDT`                                                                      |

#### Headers

| Name        | Type    | Description  |
| ----------- | ------- | ------------ |
| X-CH-SIGN   | string  | Sign         |
| X-CH-APIKEY | string  | Your API-key |
| X-CH-TS     | integer | timestamp    |

{% tabs %}
{% tab title="200 " %}

```java
{
    'orderId': '499890200602846976', 
    'clientOrderId': '157432755564968', 
    'symbol': 'BHTUSDT', 
    'price': '0.01', 
    'origQty': '50', 
    'executedQty': '0', 
    'avgPrice': '0', 
    'status': 'NEW', 
    'type': 'LIMIT', 
    'side': 'BUY', 
    'transactTime': '1574327555669'
}
```

{% endtab %}
{% endtabs %}

#### **Response:**

| name            | type   | example              | description                                                                                                     |
| --------------- | ------ | -------------------- | --------------------------------------------------------------------------------------------------------------- |
| `orderId`       | long   | `150695552109032492` | ID of the order                                                                                                 |
| `clientOrderId` | string | `213443`             | Unique ID of the order.                                                                                         |
| `symbol`        | string | `BTCUSDT`            | Name of the symbol                                                                                              |
| `price`         | float  | `4765.29`            | Price of the order                                                                                              |
| `origQty`       | float  | `1.01`               | Quantity ordered                                                                                                |
| `executedQty`   | float  | `1.01`               | Quantity of orders that has been executed                                                                       |
| `avgPrice`      | float  | `4754.24`            | Average price of filled orders.                                                                                 |
| `type`          | string | `LIMIT`              | The order type`LIMIT,MARKET`                                                                                    |
| `side`          | string | `BUY`                | The order side`BUY,SELL`                                                                                        |
| `status`        | string | `NEW`                | The state of the order.Possible values include `NEW`, `PARTIALLY_FILLED`, `FILLED`, `CANCELED`, and `REJECTED`. |

## &#x20;Cancel Order

<mark style="color:green;">`POST`</mark> `https://openapi.xxx.com/sapi/v1/cancel`

&#x20;**Rate Limit: 100time/2s**

#### Headers

| Name        | Type    | Description  |
| ----------- | ------- | ------------ |
| X-CH-SIGN   | string  | Sign         |
| X-CH-APIKEY | string  | Your API-key |
| X-CH-TS     | integer | timestamp    |

#### Request Body

| Name             | Type   | Description                                                                                      |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------ |
| orderId          | string | Order ID                                                                                         |
| newClientOrderId | string | Client Order Id, Unique order ID generated by users to mark their orders. E.g. 354444heihieddada |
| symbol           | string | Symbol Name. E.g. `BTCUSDT`                                                                      |

{% tabs %}
{% tab title="200  撤销订单成功" %}

```java
{
    'symbol': 'BHTUSDT', 
    'clientOrderId': '0', 
    'orderId': '499890200602846976', 
    'status': 'CANCELED'
}

```

{% endtab %}
{% endtabs %}

#### Response:

| name            | type   | example              | description                                                                                                     |
| --------------- | ------ | -------------------- | --------------------------------------------------------------------------------------------------------------- |
| `orderId`       | long   | `150695552109032492` | ID of the order                                                                                                 |
| `clientOrderId` | string | `213443`             | Unique ID of the order.                                                                                         |
| `symbol`        | string | `BHTUSDT`            | Name of the symbol                                                                                              |
| `status`        | string | `NEW`                | The state of the order.Possible values include `NEW`, `PARTIALLY_FILLED`, `FILLED`, `CANCELED`, and `REJECTED`. |

## &#x20;Batch cancel orders

<mark style="color:green;">`POST`</mark> `https://openapi.xxx.com/sapi/v1/batchCancel`

&#x20;**Rate Limit: 50times/2s A batch contains at most 10 orders**

#### Headers

| Name        | Type    | Description  |
| ----------- | ------- | ------------ |
| X-CH-SIGN   | string  | Sign         |
| X-CH-APIKEY | string  | Your API-key |
| X-CH-TS     | integer | timestamp    |

#### Request Body

| Name     | Type   | Description                     |
| -------- | ------ | ------------------------------- |
| symbol   | string | Symbol Name. E.g. `BTCUSDT`     |
| orderIds | array  | Order ID collection `[123,456]` |

{% tabs %}
{% tab title="200 " %}

```java
{
    "mass_place": [],
    "mass_cancel": [
        {
            "msg": "Success",
            "order_id": [
                150695662109032492
            ],
            "code": "0"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## &#x20;Current Open Orders

<mark style="color:blue;">`GET`</mark> `https://openapi.xxx.com/sapi/v1/openOrders`

**Rate Limit: 20times/2s**

#### Query Parameters

| Name   | Type    | Description                 |
| ------ | ------- | --------------------------- |
| symbol | string  | Symbol Name. E.g. `BTCUSDT` |
| limit  | integer | Default 100; Max 1000       |

#### Headers

| Name        | Type    | Description  |
| ----------- | ------- | ------------ |
| X-CH-SIGN   | string  | Sign         |
| X-CH-APIKEY | string  | Your API-key |
| X-CH-TS     | integer | timestamp    |

{% tabs %}
{% tab title="200 " %}

```java
[
    {
        'orderId': '499902955766523648', 
        'symbol': 'BHTUSDT', 
        'price': '0.01', 
        'origQty': '50', 
        'executedQty': '0', 
        'avgPrice': '0', 
        'status': 'NEW', 
        'type': 'LIMIT', 
        'side': 'BUY', 
        'time': '1574329076202'
        },...
]
```

{% endtab %}
{% endtabs %}

#### **Response:**

| name            | type   | example              | description                                                                                                     |
| --------------- | ------ | -------------------- | --------------------------------------------------------------------------------------------------------------- |
| `orderId`       | long   | `150695552109032492` | ID of the order                                                                                                 |
| `clientOrderId` | string | `213443`             | Unique ID of the order.                                                                                         |
| `symbol`        | string | `BTCUSDT`            | Name of the symbol                                                                                              |
| `price`         | float  | `4765.29`            | Price of the order                                                                                              |
| `origQty`       | float  | `1.01`               | Quantity ordered                                                                                                |
| `executedQty`   | float  | `1.01`               | Quantity of orders that has been executed                                                                       |
| `avgPrice`      | float  | `4754.24`            | Average price of filled orders.                                                                                 |
| `type`          | string | `LIMIT`              | The order type`LIMIT,MARKET`                                                                                    |
| `side`          | string | `BUY`                | The order side `BUY,SELL`                                                                                       |
| `status`        | string | `NEW`                | The state of the order.Possible values include `NEW`, `PARTIALLY_FILLED`, `FILLED`, `CANCELED`, and `REJECTED`. |

## &#x20;Trades

<mark style="color:blue;">`GET`</mark> `https://openapi.xxx.com/sapi/v1/myTrades`

&#x20;**Rate Limt: 20times/2s**

#### Query Parameters

| Name   | Type    | Description                 |
| ------ | ------- | --------------------------- |
| symbol | string  | Symbol Name. E.g. `BTCUSDT` |
| limit  | string  | Default 100; Max1000        |
| fromId | integer | Trade Id to fetch from      |

#### Headers

| Name        | Type    | Description  |
| ----------- | ------- | ------------ |
| X-CH-SIGN   | string  | Sign         |
| X-CH-APIKEY | string  | Your API-key |
| X-CH-TS     | integer | timestamp    |

{% tabs %}
{% tab title="200 " %}

```java
[
  {
    "symbol": "ETHBTC",
    "id": 100211,
    "bidId": 150695552109032492,
    "askId": 150695552109032493,
    "price": "4.00000100",
    "qty": "12.00000000",
    "time": 1499865549590,
    "isBuyer": true,
    "isMaker": false,
    "feeCoin": "ETH",
    "fee":"0.001"
  },...
]
```

{% endtab %}
{% endtabs %}

#### **Response:**

| name      | type    | example              | description                   |
| --------- | ------- | -------------------- | ----------------------------- |
| `symbol`  | string  | `ETHBTC`             | Symbol Name                   |
| `id`      | integer | `28457`              | Trade ID                      |
| `bidId`   | long    | `150695552109032492` | Bid Order ID                  |
| `askId`   | long    | `150695552109032493` | Ask Order ID                  |
| `price`   | integer | `4.01`               | Price of the trade            |
| `qty`     | float   | `12`                 | Quantiry of the trade         |
| `time`    | number  | `1499865549590`      | timestamp of the trade        |
| `isBuyer` | bool    | `true`               | `true`= Buyer `false`= Seller |
| `isMaker` | bool    | `false`              | `true`=Maker `false`=Taker    |
| `feeCoin` | string  | `ETH`                | Trading fee coin              |
| `fee`     | number  | `0.001`              | Trading fee                   |

## Account

### Security Type: [USER\_DATA](/v/english/ji-ben-xin-xi.md#jie-kou-jian-quan-lei-xing)

Endpoints under Account require an [API-key and a signature.](/v/english/ji-ben-xin-xi.md#xu-yao-qian-ming-de-jie-kou-trade-yu-userdata)

## &#x20;Account Information

<mark style="color:blue;">`GET`</mark> `https://openapi.xxx.com/sapi/v1/account`

&#x20;**Rate Limit: 20times/2s**

#### Headers

| Name        | Type    | Description  |
| ----------- | ------- | ------------ |
| X-CH-SIGN   | string  | Sign         |
| X-CH-APIKEY | string  | Your API-key |
| X-CH-TS     | integer | timestamp    |

{% tabs %}
{% tab title="200  Successfully retrieved account information." %}

```java
{
    'balances': 
        [
            {
                'asset': 'BTC', 
                'free': '0', 
                'locked': '0'
                }, 
            {
                'asset': 'ETH', 
                'free': '0', 
                'locked': '0'
                },...
        ]
}
```

{% endtab %}
{% endtabs %}

#### Response:

| 名称         | 类型   | 描述                   |
| ---------- | ---- | -------------------- |
| `balances` | `[]` | Show balance details |

`balances` field:

| name     | type   | example | description                     |
| -------- | ------ | ------- | ------------------------------- |
| `asset`  | string | `USDT`  | Name of the asset               |
| `free`   | float  | 1000.30 | Amount available for use        |
| `locked` | float  | 400     | Amount locked (for open orders) |