baseurl https://openapi.xxx.xx
All endpoints return either a JSON object or array.
Data is returned in Reverse order. newest first, oldest last.
All time and timestamp related fields are in milliseconds.
HTTP 4XX return codes are used for malformed requests; the issue is on the sender's side.
HTTP 410 return code is used when breaking a request rate limit.
HTTP 418 means that if you continue to access after receiving 429, you will be blocked from IP, and the blocking time will be gradually extended from a minimum of 2 minutes to a maximum of 3 days for frequent violations of the restrictions.
HTTP 5XX return codes are used for internal errors
HTTP 504 return code is used when the API successfully sent the message but not get a response within the timeout period. It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success.
All endpoints can possibly return an ERROR, the error payload is as follows:
{ "code": -1121, "msg": "Invalid symbol."}All requests are based on the Https protocol, and the Content-Type in the request header information needs to be uniformly set to:'application/json'
For the interface of the GET method, the parameters must be sent in the query string
The interface of the POST method, the parameters must be sent in the request body
Parameters may be sent in any order.
Access restrictions are based on IP or UID, not API Key.
The statistics by IP and by UID (account) are independent of each other.
The total weight of single interface weight according to IP statistics is 12,000 per minute
The total amount of interface weights by UID is 60,000 per minute
Each interface will indicate whether the statistics are by IP or by UID, and the weight value of the corresponding request once
There will be a limited frequency description below each interface.
A 429 will be returned when either rate limit is violated.
A 429 will be returned when either rate limit is violated.
Each endpoint has a security type that determines the how you will interact with it.
API-keys are passed into the Rest API via the X-CH-APIKEY header.
API-keys and secret-keys are case sensitive.
| Security Type | Description |
|---|---|
| NONE | Endpoint can be accessed freely. |
| TRADE | Endpoint requires sending a valid API-Key and signature. |
| USER_DATA | Endpoint requires sending a valid API-Key and signature. |
| USER_STREAM | Endpoint requires sending a valid API-Key. |
| MARKET_DATA | Endpoint requires sending a valid API-Key. |
When calling the TRADE or USER_DATA interface, the signature parameter should be passed in the X-CH-SIGN field in the HTTP header.
The signature uses the HMAC SHA256 algorithm. The API-Secretcorresponding to the API-KEY is used as the HMAC SHA256key.
The request header of X-CH-SIGN is based on timestamp + method + requestPath + body string (+ means string connection) as the operation object
The value of timestamp is the same as the X-CH-TS request header, method is the request method, and the letters are all uppercase: GET/POST
requestPath is the request interface path For example: /sapi/v1/order
body is the string of the request body (post only)
The signature is not case sensitive.
The signature interface needs to pass the timestamp in the X-CH-TS field in the HTTP header, and its value should be the unix timestamp of the request sending time e.g. 1528394129373
An additional parameter, recvWindow, may be sent to specify the number of milliseconds after timestamp the request is valid for. If recvWindow is not sent, it defaults to 5000.
In addition, if the server calculates that the client's timestamp is more than one second ‘in the future’ of the server’s time, it will also reject the request.
The logic is as follows:
xxxxxxxxxxif (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) { // process request} else { // reject request}Serious trading is about timing. Networks can be unstable and unreliable, which can lead to requests taking varying amounts of time to reach the servers. With recvWindow, you can specify that the request must be processed within a certain number of milliseconds or be rejected by the server.
It recommended to use a small recvWindow of 5000 or less!
Here is a step-by-step example of how to send a vaild signed payload from the Linux command line using echo, openssl, and curl.
| Key | Value |
|---|---|
| apiKey | vmPUZE6mv9SD5V5e14y7Ju91duEh8A |
| secretKey | 902ae3cb34ecee2779aa4d3e1d226686 |
| Parameter | value |
|---|---|
| symbol | BTCUSDT |
| side | BUY |
| type | LIMIT |
| volume | 1 |
| price | 9300 |
body:
xxxxxxxxxx{"symbol":"BTCUSDT","price":"9300","volume":"1","side":"BUY","type":"LIMIT"}HMAC SHA256 Signature:
xxxxxxxxxx[linux]$ echo -n "1588591856950POST/sapi/v1/order/test{\"symbol\":\"BTCUSDT\",\"price\":\"9300\",\"volume\":\"1\",\"side\":\"BUY\",\"type\":\"LIMIT\"}" | openssl dgst -sha256 -hmac "902ae3cb34ecee2779aa4d3e1d226686"(stdin)= c50d0a74bb9427a9a03933d0eded03af9bf50115dc5b706882a4fcf07a26b761Curl command :
xxxxxxxxxx (HMAC SHA256) [linux]$ curl -H "X-CH-APIKEY: c3b165fd5218cdd2c2874c65da468b1e" -H "X-CH-SIGN: c50d0a74
base asset refers to the asset that is the quantity of a symbol.
quote asset refers to the asset that is the price of a symbol.
NEW
PARTIALLY_FILLED
FILLED
CANCELED
PENDING_CANCEL
REJECTED
LIMIT
MARKET
BUY
SELL
min -> minutes; h -> hours; day -> days; week -> weeks; month -> months
1min
5min
15min
30min
60min
1h
4h
1day
1week
1month
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/pingThis endpoint checks connectivity to the host
200: OK Connection normal
xxxxxxxxxx}xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/timeThis endpoint checks connectivity to the server and retrieves server timestamp
200: OK Successfully retrieved server time
xxxxxxxxxx{ "timezone": "GMT+08:00", "serverTime": 1595563624731}xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/symbols200: OK
xxxxxxxxxx{ "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" } ]}weight(IP/UID): 1
| symbol | string | BTCUSDT | Name of the symbol | Currency to name | |
|---|---|---|---|---|---|
| baseAsset | string | BTC | Underlying asset for the symbol | base currency | |
| quoteAsset | string | USDT | Quote asset for the symbol | The base currency | |
| pricePrecision | integer | 2 | Precision of the price | Price Accuracy | |
| quantityPrecision | integer | 6 | Precision of the quantity | Quantity accuracy |
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/depthmarket detpth data
| Name | Type | Description |
|---|---|---|
| limit | integer | Default 100; Max 100 |
| symbol* | String | Symbol Name E.g. BTCUSDT |
200: OK Successfully retrieved market depth data
xxxxxxxxxx{ "bids": [ [ "3.90000000", // price "431.00000000" // vol ], [ "4.00000000", "431.00000000" ] ], "asks": [ [ "4.00000200", // price "12.00000000" // vol ], [ "5.10000000", "28.00000000" ] ]}weight(IP/UID): 5
| 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.
| ' ' | float | 131.1 | price level |
|---|---|---|---|
| ' ' | float | 2.3 | The total quantity of orders for this price level |
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/ticker24 hour price change statistics.
| Name | Type | Description |
|---|---|---|
| symbol* | String | Symbol Name. E.g. BTCUSDT |
200: OK Successfully retrieved ticker data
xxxxxxxxxx{ "high": "9279.0301", "vol": "1302", "last": "9200", "low": "9279.0301", "rose": "0", "time": 1595563624731}weight(IP/UID): 5
| 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 | |
| rose | float | 0 | Price increase or Price rise |
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/trades| Name | Type | Description |
|---|---|---|
| symbol* | String | Symbol Name. E.g. BTCUSDT |
| limit | String | Default 100; Max 1000Responses200 |
200: OK
xxxxxxxxxx{ "list":[ { "price":"3.00000100", "qty":"11.00000000", "time":1499865549590, "side":"BUY" } ]}weight(IP/UID): 5
| price | float | 0.055 | The price of the trade | |
|---|---|---|---|---|
| time | long | 1537797044116 | Current timestamp (ms) | |
| qty | float | 5 | The quantity traded | |
| side | string | BUY/SELL | Taker side |
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/klines| Name | Type | Description |
|---|---|---|
| symbol* | Symbol Name. E.g. BTCUSDT | |
| interval* | String | Interval of the Kline. Possible values include: 1min,5min,15min,30min,60min,1day,1week,1month |
| Default 100; Max 300 | String | Default 100; Max 300Responses200 |
| startTime | long | startTime example:1538728740000 |
| endTime | long | endTime example:1538728740000 |
200: OK
xxxxxxxxxx[ { "high": "6228.77", "vol": "111", "low": "6228.77", "idx": 1594640340, "close": "6228.77", "open": "6228.77" }, { "high": "6228.77", "vol": "222", "low": "6228.77", "idx": 1587632160, "close": "6228.77", "open": "6228.77" }, { "high": "6228.77", "vol": "333", "low": "6228.77", "idx": 1587632100, "close": "6228.77", "open": "6228.77" }]weight(IP/UID): 1
idx | long | 1538728740000 | Open time | |
|---|---|---|---|---|
| open | float | 36.00000 | open price | |
| close | float | 33.00000 | close price | |
| high | float | 36.00000 | high price | |
| low | float | 30.00000 | low price | |
| vol | float | 2456.111 | volume |
Endpoints under Trade require an API Key and a signature
xxxxxxxxxxPOST https://openapi.xxx.xx/sapi/v1/orderRate Limit: 100times/2s
| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | string | Sign |
| X-CH-APIKEY | string | Your API-key |
| X-CH-TS | integer | timestamp |
| 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 |
200: OK Successfully post new order
xxxxxxxxxx{ 'symbol': 'LXTUSDT', 'orderId': 150695552109032492, 'orderIdString': '150695552109032492',//Character String Type Order ID (Recommended) 'clientOrderId': '157371322565051', 'transactTime': '1573713225668', 'price': '0.005452', 'origQty': '110', 'executedQty': '0', 'status': 'NEW', 'type': 'LIMIT', 'side': 'SELL'}weight(IP/UID): 5
| 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 | Time the order is placed | |
| origQty | float | 1.01 | Quantity ordered | |
| executedQty | float | 1.01 | Quantity of orders that has been executed | |
| type | string | LIMIT | Order typeLIMIT,MARKET | |
| side | string | BUY | Order side：BUY, SELL | |
| status | string | 0 | 0 = new order |
xxxxxxxxxxPOST https://openapi.xxx.xx/sapi/v1/order/testTest new order creation and signature/recvWindow length. Creates and validates a new order but does not send the order into the matching engine.
| Name | Type | Description |
|---|---|---|
| X-CH-APIKEY | String | Your API-key |
| X-CH-TS | String | timestamp |
| X-CH-SIGN | String | Sign |
| Name | Type | Description |
|---|---|---|
| type* | String | Type of the order, LIMIT/MARKET |
| price* | number | Order price, REQUIRED for LIMIT orders |
| volume* | number | Order vol. For MARKET BUY orders, vol=amount. |
| side* | String | Side of the order, BUY/SELL |
| symbol* | String | Symbol Name. E.g. BTCUSDT |
| recvwindow | integer | Time window |
| newClientorderId | String | Unique order ID generated by users to mark their orders |
200: OK Successfully test new order
xxxxxxxxxx{ // Response}weight(IP/UID): 1
xxxxxxxxxxPOST https://openapi.xxx.xx/sapi/v1/batchOrdersbatch contains at most 10 orders
| Name | Type | Description |
|---|---|---|
| X-CH-APIKEY | String | Your API-key |
| X-CH-TS | String | timestamp |
| X-CH-SIGN | String | Sign |
| Name | Type | Description |
|---|---|---|
| orders | number | The batch order information can contain a maximum of 10 records. |
| symbol* | String | Symbol Name. E.g. BTCUSDT |
200: OK
xxxxxxxxxx{ "idsString": [ //Character String Type Order ID (Recommended) "165964665990709251", "165964665990709252", "165964665990709253" ], "ids": [ 165964665990709251, 165964665990709252, 165964665990709253 ]}weight(IP/UID): 10
orders field:| name | type | Example | Description |
|---|---|---|---|
| price | folat | 1000 | Price |
| volume | folat | 20.1 | Quantity |
| side | String | BUY/SELL | Direction |
| batchType | String | LIMIT/MARKET | Type |
| idsString | String | “3213213” | A collection of order numbers of type String. |
|---|---|---|---|
| ids | integer | 2100 | Collection of order numbers. |
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/order| 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. BTCUSDl |
| Name | Type | Description |
|---|---|---|
| X-CH-APIKEY | String | Your API-key |
| X-CH-TS | String | timestampResponses200 |
| X-CH-SIGN | String | Sign |
200: OK
xxxxxxxxxx{ 'orderId': '499890200602846976', 'clientOrderId': '157432755564968', 'symbol': 'BHTUSDT', 'price': '0.01', 'origQty': '50', 'executedQty': '0', 'avgPrice': '0', 'status': 'NEW', 'type': 'LIMIT', 'side': 'BUY', 'transactTime': '1574327555669'}weight(IP/UID): 1
| orderId | long | 150695552109032492 | Order ID (system generated) | |
|---|---|---|---|---|
| clientorderId | string | 213443 | Order ID (sent by yourself) | |
| symbol | string | BTCUSDT | Currency Pair Name | |
| price | float | 4765.29 | Order Price | |
| origQty | float | 1.01 | Number of orders | |
| executedQty | float | 1.01 | Number of orders already filled | |
| avgPrice | float | 4754.24 | Average price of orders already filled | |
| type | string | limit | The order typeLIMIT,MARKET | |
| side | string | BUY | Order direction. Possible values can only be: BUY (buy long) and SELL (sell short) | |
| status | string | NEW | Order status. Possible values are NEW (new order, no transaction), PARTIALLY_FILLED (partially filled), FILLED (fully filled), CANCELED (cancelled) and REJECTED (order rejected).POST | |
| transactTime | string | 1574327555669 | Order Creation Time |
xxxxxxxxxxPOST https://openapi.xxx.xx/sapi/v1/cancel| Name | Type | Description |
|---|---|---|
| X-CH-APIKEY | String | Your API-key |
| X-CH-TS | String | timestamp |
| X-CH-SIGN | String | Sign |
| Name | Type | Description |
|---|---|---|
| newClientOrderId | String | Client Order Id, Unique order ID generated by users to mark their orders. E.g. 354444heihieddada |
| orderId* | String | Order ID |
| symbol* | String | Symbol Name. E.g. BTCUSDT |
200: OK
xxxxxxxxxx{ 'symbol': 'BHTUSDT', 'clientOrderId': '0', 'orderId': '499890200602846976', 'status': 'CANCELED'}weight(IP/UID): 5
| orderId | long | 150695552109032492 | ID of the order | |
|---|---|---|---|---|
| clientorderId | string | 213443 | Unique ID of the order. | |
| symbol | string | BTCUSDT | Name of the symbol | |
| status | string | NEW | The state of the order.Possible values include NEW, PARTIALLY_FILLED, FILLED, CANCELED, and REJECTED.POST |
xxxxxxxxxxPOST https://openapi.xxx.xx/sapi/v1/batchCancelbatch contains at most 10 orders
| Name | Type | Description |
|---|---|---|
| X-CH-APIKEY | String | Your API-key |
| X-CH-TS | String | timestamp |
| X-CH-SIGN | String | Sign |
| Name | Type | Description |
|---|---|---|
| orderIds | String | Order ID collection[123,456]Responses200GET |
| symbol* | String | Symbol Name. E.g. BTCUSDT |
200: OK
xxxxxxxxxx{"success": [165964665990709251,165964665990709252,165964665990709253],"failed": [ //cancel fails because the order does not exist or the order state has expired165964665990709250]}
weight(IP/UID): 10
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/openOrders| Name | Type | Description |
|---|---|---|
| symbol* | String | Symbol Name. E.g. BTCUSDT |
| limit | String | Default 100; Max 1000 |
| Name | Type | Description |
|---|---|---|
| X-CH-APIKEY | String | Your API-key |
| X-CH-TS | String | timestamp |
| X-CH-SIGN | String | Sign |
200: OK
xxxxxxxxxx[ { 'orderId': 499902955766523648, 'orderIdString': '499902955766523648', //Character String Type Order ID (Recommended) 'symbol': 'BHTUSDT', 'price': '0.01', 'origQty': '50', 'executedQty': '0', 'avgPrice': '0', 'status': 'NEW', 'type': 'LIMIT', 'side': 'BUY', 'time': '1574329076202' },...]weight(IP/UID): 1
| orderId | long | 150695552109032492 | ID of the order | |
|---|---|---|---|---|
| orderIdString | string | "150695552109032492" | Character String Type Order ID (Recommended) | |
| 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 typeLIMIT,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.GET | |
| time | string | 1574327555669 | Creation Time |
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/myTrades| Name | Type | Description |
|---|---|---|
| symbol* | String | Symbol Name. E.g. BTCUSDT |
| limit | String | Default 100; Max1000 |
| fromId | String | Trade Id to fetch from |
| Name | Type | Description |
|---|---|---|
| X-CH-APIKEY | String | Your API-key |
| X-CH-TS | String | timestamp |
| X-CH-SIGN | String | Sign |
200: OK
xxxxxxxxxx[ { "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", "bidUserId":23334, "askUserId":44112 },...]weight(IP/UID): 1
| symbol | string | BTCUSDT | Name of the symbol |
|---|---|---|---|
| id | integer | 28457 | Trade ID |
| bidId | long | 150695552109032492 | Bid Order ID |
| askId | long | 150695552109032492 | 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 |
| bidUserId | long | 23334 | Buyer UID |
| askUserId | long | 44112 | Seller UID |
| isSelf | bool | true | whether is self dealt |
Endpoints under Account require an API-key and a signature.
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/account| Name | Type | Description |
|---|---|---|
| X-CH-APIKEY | String | Your API-key |
| X-CH-TS | String | timestamp |
| X-CH-SIGN | String | Sign |
200: OK Successfully retrieved account information.
xxxxxxxxxx{ 'balances': [ { 'asset': 'BTC', 'free': '0', 'locked': '0' }, { 'asset': 'ETH', 'free': '0', 'locked': '0' },... ]}weight(IP/UID): 1
| name | type | description |
|---|---|---|
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) |
Endpoints under Trade require an API-key and a signature.
xxxxxxxxxxPOST https://openapi.xxx.xx/sapi/v1/margin/orderRate Limit：100times/2s
| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | String | Sign |
| X-CH-TS | String | timestamp |
| X-CH-APIKEY | String | Your API-key |
| Name | Type | Description |
|---|---|---|
| type | String | Type of the order, LIMIT/MARKET |
| recwwindow | String | Time window |
| price | number | Order price, REQUIRED for LIMIT orders |
| newClientOrderId | String | Unique order ID generated by users to mark their orders, Cannot exceed 32 characters |
| side | String | Side of the order, BUY/SELL |
| volume | number | Order vol. For MARKET BUY orders, vol=amount. |
| symbol | String | Symbol Name. E.g. BTCUSDT |
200: OK
xxxxxxxxxx{ 'symbol': 'LXTUSDT', 'orderId': '494736827050147840', 'clientOrderId': '157371322565051', 'transactTime': '1573713225668', 'price': '0.005452', 'origQty': '110', 'executedQty': '0', 'status': 'NEW', 'type': 'LIMIT', 'side': 'SELL'}weight(IP/UID): 5
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/margin/orderRate Limit: 20times/2s
| 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. BTCUSDTHeader |
| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | String | Sign |
| X-CH-TS | String | timestamp |
| X-CH-APIKEY | String | Your API-key |
200: OK
xxxxxxxxxx{ 'orderId': '499890200602846976', 'clientOrderId': '157432755564968', 'symbol': 'BHTUSDT', 'price': '0.01', 'origQty': '50', 'executedQty': '0', 'avgPrice': '0', 'status': 'NEW', 'type': 'LIMIT', 'side': 'BUY', 'transactTime': '1574327555669'}weight(IP/UID): 5
xxxxxxxxxxPOST https://openapi.xxx.xx/sapi/v1/margin/cancelRate Limit: 100times/2s
| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | String | Sign |
| X-CH-TS | String | timestamp |
| X-CH-APIKEY | String | Your API-key |
| Name | Type | Description |
|---|---|---|
| newClientOrderId | String | Symbol Name. E.g. BTCUSDTResponses200GET |
| symbol | String | Client Order Id, Unique order ID generated by users to mark their orders. E.g. 354444heihieddada |
| orderId | String | Order ID |
200: OK
xxxxxxxxxx{ 'symbol': 'BHTUSDT', 'clientOrderId': '0', 'orderId': '499890200602846976', 'status': 'CANCELED'}weight(IP/UID): 5
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/margin/openOrdersRate Limit: 20times/2s
| Name | Type | Description |
|---|---|---|
| symbol | String | Symbol Name. E.g. BTCUSDT |
| limit | String | Default 100; Max 1000 |
| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | String | Sign |
| X-CH-TS | String | timestamp |
| X-CH-APIKEY | String | Your API-key |
200: OK
xxxxxxxxxx[ { 'orderId': '499902955766523648', 'symbol': 'BHTUSDT', 'price': '0.01', 'origQty': '50', 'executedQty': '0', 'avgPrice': '0', 'status': 'NEW', 'type': 'LIMIT', 'side': 'BUY', 'time': '1574329076202' },...]weight(IP/UID): 1
xxxxxxxxxxGET https://openapi.xxx.xx/sapi/v1/margin/myTrades| Name | Type | Description |
|---|---|---|
| symbol | String | Symbol Name. E.g. BTCUSDT |
| limit | String | Default 100; Max 1000 |
| fromId | String | Trade Id to fetch from |
| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | String | Sign |
| X-CH-TS | String | timestamp |
| X-CH-APIKEY | String | Your API-key |
200: OK
xxxxxxxxxx[ { "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" },...]weight(IP/UID): 1
Endpoints under Public section can be accessed freely without requiring any API-key or signatures
xxxxxxxxxxGET https://futuresopenapi.xxx.xx/fapi/v1/pingThis endpoint checks connectivity to the host
200
xxxxxxxxxx{}
xxxxxxxxxxGET https://futuresopenapi.xxx.xx/fapi/v1/time200
xxxxxxxxxx{ "serverTime":1607702400000, "timezone":Chinese standard time}| name | type | example | description |
|---|---|---|---|
| serverTime | long | 1607702400000 | server timestamp |
| timezone | string | China standard time | server time zone |
xxxxxxxxxxGET https://futuresopenapi.xxx.xx/fapi/v1/contracts200
xxxxxxxxxx[ { "symbol": "H-HT-USDT", "pricePrecision": 8, "side": 1, "maxMarketVolume": 100000, "multiplier": 6, "minOrderVolume": 1, "maxMarketMoney": 10000000, "type": "H", "maxLimitVolume": 1000000, "maxValidOrder": 20, "multiplierCoin": "HT", "minOrderMoney": 0.001, "maxLimitMoney": 1000000, "status": 1 }]| name | type | example | description |
|---|---|---|---|
| symbol | string | E-BTC-USDT | Contract name |
| status | number | 1 | status（0：cannot trade，1：can trade |
| type | string | S | contract type, E: perpetual contract, S: test contract, others are mixed contract |
| side | number | 1 | Contract direction(backwards：0，1：forward) |
| multiplier | number | 0.5 | Contract face value |
| multiplierCoin | string | BTC | Contract face value unit |
| pricePrecision | number | 4 | Precision of the price |
| minOrderVolume | number | 10 | Minimum order volume |
| minOrderMoney | number | 10 | Minimum order value |
| maxMarketVolume | number | 100000 | Market price order maximum volume |
| maxMarketMoney | number | 100000 | Market price order maximum value |
| maxLimitVolume | number | 100000 | Limit price order maximum volume |
| maxValidOrder | number | 100000 | Maximum valid order quantity |
Market section can be accessed freely without requiring any API-key or signatures.
xxxxxxxxxxGET https://futuresopenapi.xxx.xx/fapi/v1/depthMarket depth data
| Name | Type | Description |
|---|---|---|
| limit | integer | Default 100, Max 100 |
| Contract name | string | Contract Name E.g. E-BTC-USDT |
200 Successfully retrieve market depth data
xxxxxxxxxx{ "bids": [ [ "3.90000000", // price "431.00000000" // quantity ], [ "4.00000000", "431.00000000" ] ], "asks": [ [ "4.00000200", // price "12.00000000" // quantity ], [ "5.10000000", "28.00000000" ] ]}
| name | type | example | description |
|---|---|---|---|
| time | long | 1595563624731 | Current Timestamp (ms) |
| bids | list | Look below | Order book purchase info |
| asks | list | Look below | Order book selling info |
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 | Total order quantity for this price level |
xxxxxxxxxxGET https://futuersopenapi.xxx.xx/fapi/v1/ticker24 hour price change statistics
| Name | Type | Description |
|---|---|---|
| Contract name | string | Contract name E.g. E-BTC-USDT |
200 Successfully obtain ticker info
xxxxxxxxxx{ "high": "9279.0301", "vol": "1302", "last": "9200", "low": "9279.0301", "rose": "0", "time": 1595563624731}| name | type | example | description |
|---|---|---|---|
| time | long | 1595563624731 | Open time |
| high | float | 9900 | Higher price |
| low | float | 8800.34 | Lower price |
| last | float | 8900 | Newest price |
| vol | float | 4999 | Trade volume |
| rose | string | +0.5 | Price variation |
xxxxxxxxxxGET https://futuersopenapi.xxx.xx/fapi/v1/index| Name | Type | Description |
|---|---|---|
| Contract name | string | Contract name E.g. E-BTC-USDT |
| limit | string | Default 100, Max 100 |
200
xxxxxxxxxx{ "markPrice": 581.5, "indexPrice": 646.3933333333333, "lastFundingRate": 0.001, "contractName": "E-ETH-USDT", "time": 1608273554063}| name | type | example | Description |
|---|---|---|---|
indexPrice | float | 0.055 | Index price |
markPrice | float | 0.0578 | Marked price |
contractName | string | E-BTC-USDT | Contract name |
lastFundingRate | float | 0.123 | Current fund rate |
xxxxxxxxxxGET https://futuresopenapi.xxx.xx/fapi/v1/klines| Name | Type | Description |
|---|---|---|
| ContractName | string | Contract name E.g. E-BTC-USDT |
| interval | string | K-line interval, identifies the sent value as: 1min,5min,15min,30min,1h,1day,1week,1month |
| limit | integer | Default 100, Max 300 |
200
xxxxxxxxxx[ { "high": "6228.77", "vol": "111", "low": "6228.77", "idx": 1594640340, "close": "6228.77", "open": "6228.77" }, { "high": "6228.77", "vol": "222", "low": "6228.77", "idx": 1587632160, "close": "6228.77", "open": "6228.77" }, { "high": "6228.77", "vol": "333", "low": "6228.77", "idx": 1587632100, "close": "6228.77", "open": "6228.77" }]| name | type | example | description |
|---|---|---|---|
idx | long | 1538728740000 | Start timestamp (ms） |
open | float | 36.00000 | Open price |
close | float | 33.00000 | Closing price |
high | float | 36.00000 | Max price |
low | float | 30.00000 | Min price |
vol | float | 2456.111 | Trade volume |
All interfaces under the transaction require signature and API-key verification
xxxxxxxxxxPOST` `https://futuresopenapi.xxx.xx/fapi/v1/order
Creation of single new orders
| Name | Type | Description |
|---|---|---|
| X-CH-TS | string | Time stamp |
| X-CH-APIKEY | string | Your API-key |
| X-CH-SIGN | string | Signature |
| Name | Type | Description |
|---|---|---|
| volume | number | Order quantity |
| price | number | Order price |
| contractName | string | Contract name E.g. E-BTC-USDT |
| type | string | Order type, LIMIT/MARKET |
| side | string | trade direction, BUY/SELL |
| open | string | Open balancing direction, OPEN/CLOSE |
| positionType | number | Hold-up position,1 full position, 2 restrictive position |
| clientOrderId | string | Client order identity, a string with length less than 32 bit |
| timeInForce | string | LIMIT/MARKET |
200
xxxxxxxxxx{"orderId": 256609229205684228}
| name | type | example | description |
|---|---|---|---|
| orderId | String | 256609229205684228 | Order ID |
xxxxxxxxxxPOST https://futuresopenapi.xxx.xx/fapi/v1/conditionOrder| Name | Type | Description |
|---|---|---|
| X-CH-TS | string | Time stamp |
| X-CH-APIKEY | string | Your API-key |
| X-CH-SIGN | string | Signature |
| Name | Type | Description |
|---|---|---|
| volume | number | Order quantity |
| triggerType | string | trigger type 3UP/4DOWN |
| triggerPrice | string | trigger price |
| positionType | number | Hold-up position,1 full position, 2 restrictive position |
| open | string | Open balancing direction, OPEN/CLOSE |
| side | string | trade direction, BUY/SELL |
| type | string | Order type, LIMIT/MARKET |
| contractName | string | Contract name E.g. E-BTC-USDT |
| price | number | Order price |
200: OK
xxxxxxxxxx{ "orderId": 256609229205684228}xxxxxxxxxxPOST https://futuresopenapi.xxx.xx/fapi/v1/cancelSpeed limit rules: 20 times/ 2 seconds
| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | string | Signature |
| X-CH-APIKEY | string | Your API-key |
| X-CH-TS | integer | Time stamp |
| Name | Type | Description |
|---|---|---|
| contractName | string | Contract name E.g.E-BTC-USDT |
| orderId | string | Order ID |
200
xxxxxxxxxx{ "orderId": 256609229205684228}xxxxxxxxxxGET https://futuresopenapi.xxx.xx/fapi/v1/order| Name | Type | Description |
|---|---|---|
| contractName | string |
200
xxxxxxxxxx[ { "side": "BUY", "executedQty": 0, "orderId": 259396989397942275, "price": 10000.0000000000000000, "origQty": 1.0000000000000000, "avgPrice": 0E-8, "transactTime": "1607702400000", "action": "OPEN", "contractName": "E-BTC-USDT", "type": "LIMIT", "status": "INIT" }]| name | type | example | description |
|---|---|---|---|
orderId | long | 150695552109032492 | Order ID（system generated |
contractName | string | E-BTC-USDT | Contract name |
price | float | 10.5 | Order price |
origQty | float | 10.5 | Order quantity |
executedQty | float | 20 | Order quantity |
avgPrice | float | 10.5 | Average transaction price |
symbol | string | BHTUSDT | Coin pair name |
status | string | NEW | Order status. Possible values are：NEW(new order，not filled)、PARTIALLY_FILLED（partially filled）、FILLED（fully filled）、CANCELLED（already cancelled）andREJECTED（order rejected） |
side | string | NEW | Order direction. Possible values can only be：BUY（buy long）and SELL（sell short） |
action | string | OPEN | OPEN/CLOSE |
transactTime | long | 1607702400000 | Order creation time |
xxxxxxxxxxGET https://futuresopenapi.xxx.xx/fapi/v1/openOrdersSpeed limit rules: Obtain open contract, the user's current order
| Name | Type | Description |
|---|---|---|
| contractName | string | Contract name E-BTC-USDT |
| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | string | signature |
| X-CH-APIKEY | string | Your API-key |
| X-CH-TS | integer | time stamp |
200
xxxxxxxxxx[ { "side": "BUY", "executedQty": 0, "orderId": 259396989397942275, "price": 10000.0000000000000000, "origQty": 1.0000000000000000, "avgPrice": 0E-8, "transactTime": "1607702400000", "action": "OPEN", "contractName": "E-BTC-USDT", "type": "LIMIT", "status": "INIT" }]| name | type | example | description |
|---|---|---|---|
orderId | long | 150695552109032492 | Order ID（system generated） |
contractName | string | E-BTC-USDT | Contract name |
price | float | 4765.29 | Order price |
origQty | float | 1.01 | Order quantity |
executedQty | float | 1.01 | Filled orders quantity |
avgPrice | float | 4754.24 | Filled orders average price |
type | string | LIMIT | Order type. Possible values can only be:LIMIT(limit price) andMARKET（market price） |
side | string | BUY | Order direction. Possible values can only be：BUY（buy long）and SELL（sell short） |
status | string | NEW | Order status. Possible values are：NEW(new order，not filled)、PARTIALLY_FILLED（partially filled）、FILLED（fully filled）、CANCELLED（already cancelled）andREJECTED（order rejected） |
action | string | OPEN | OPEN/CLOSE |
transactTime | long | 1607702400000 | Order creation time, |
xxxxxxxxxxPOST https://futuresopenapi.xxx.xx/fapi/v1/orderHistorical| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | string | signature |
| X-CH-APIKEY | string | Your API-key |
| X-CH-TS | string | time stamp |
| Name | Type | Description |
|---|---|---|
| contractName | string | Contract name E.g. E-BTC-USDT |
| limit | string | Lines per page, default 100, max 1000 |
| fromId | long | Start retrieving from this Id |
200: OK
xxxxxxxxxx[ { "side":"BUY", "clientId":"0", "ctimeMs":1632903411000, "positionType":2, "orderId":777293886968070157, "avgPrice":41000, "openOrClose":"OPEN", "leverageLevel":26, "type":4, "closeTakerFeeRate":0.00065, "volume":2, "openMakerFeeRate":0.00025, "dealVolume":1, "price":41000, "closeMakerFeeRate":0.00025, "contractId":1, "ctime":"2021-09-29T16:16:51", "contractName":"E-BTC-USDT", "openTakerFeeRate":0.00065, "dealMoney":4.1, "status":4 }]xxxxxxxxxxPOST https://futuresopenapi.xxx.xx/fapi/v1/profitHistorical| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | string | signature |
| X-CH-APIKEY | string | Your API-key |
| X-CH-TS | string | time stamp |
| Name | Type | Description |
|---|---|---|
| contractName | string | Contract name E.g. E-BTC-USDT |
| limit | string | Lines per page, default 100, max 1000 |
| fromId | long | Start retrieving from this Id |
200: OK
xxxxxxxxxx[ { "side":"SELL", "positionType":2, "tradeFee":-5.23575, "realizedAmount":0, "leverageLevel":26, "openPrice":44500, "settleProfit":0, "mtime":1632882739000, "shareAmount":0, "openEndPrice":44500, "closeProfit":-45, "volume":900, "contractId":1, "historyRealizedAmount":-50.23575, "ctime":1632882691000, "id":8764, "capitalFee":0 }]
xxxxxxxxxxGET https://futuresopenapi.xxx.xx/fapi/v1/myTrades| Name | Type | Description |
|---|---|---|
| contractName | string | Contract name E.g. E-BTC-USDT |
| limit | string | Lines per page, default 100, max 1000 |
| fromId | long | Start retrieving from this tradeId |
| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | string | signature |
| X-CH-APIKEY | string | Your API-key |
| X-CH-TS | string | time stamp |
200
xxxxxxxxxx[ { "symbol": "ETHBTC", "id": 100211, "bidId": 150695552109032492, "askId": 150695552109032493, "price": "4.00000100", "qty": "12.00000000", "time": 1499865549590, "isBuyer": true, "isMaker": false, "fee":"0.001" },...]
| name | type | example | description |
|---|---|---|---|
| symbol | string | ETHBTC | Coin name(trade pair) |
| tradeId | number | 28457 | Trade ID |
| bidId | long | 150695552109032492 | Buyer order ID |
| askId | long | 150695552109032493 | Seller order ID |
| bidUserId | integer | 10024 | Buyer user ID |
| askUserId | integer | 10025 | Seller user ID |
| price | float | 4.01 | Filled price |
| qty | float | 12 | Trade quantity |
| amount | float | 5.38 | Filled amount |
| time | number | 1499865549590 | Trade time stamp |
| fee | number | 0.001 | Trading fees |
| side | string | buy | Current order direction BUY purchase, SELL selling |
| contractName | string | E-BTC-USDT | Contract name |
| isMaker | boolean | true | is it maker? |
| isBuyer | boolean | true | is it buyer? |
All interfaces under the account require signature and API-key verificationwindow.location='https://exdocs.gitbook.io/v/v/english/general-info#signed-trade-yu-userdata-endpoint-security')
xxxxxxxxxxGET https://futuresopenapi.xxx.com /fapi/v1/account| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | string | Signature |
| X-CH-APIKEY | string | Your API-key |
| X-CH-TS | integer | time stamp |
200
xxxxxxxxxx{ "account": [ { "marginCoin": "USDT", "accountNormal": 999.5606, "accountLock": 23799.5017, "partPositionNormal": 9110.7294, "totalPositionNormal": 0, "achievedAmount": 4156.5072, "unrealizedAmount": 650.6385, "totalMarginRate": 0, "totalEquity": 99964804.560, "partEquity": 13917.8753, "totalCost": 0, "sumMarginRate": 873.4608, "positionVos": [ { "contractId": 1, "contractName": "E-BTC-USDT", "contractSymbol": "BTC-USDT", "positions": [ { "id": 13603, "uid": 10023, "contractId": 1, "positionType": 2, "side": "BUY", "volume": 69642.0, "openPrice": 11840.2394, "avgPrice": 11840.3095, "closePrice": 12155.3005, "leverageLevel": 24, "holdAmount": 7014.2111, "closeVolume": 40502.0, "pendingCloseVolume": 0, "realizedAmount": 8115.9125, "historyRealizedAmount": 1865.3985, "tradeFee": -432.0072, "capitalFee": 2891.2281, "closeProfit": 8117.6903, "shareAmount": 0.1112, "freezeLock": 0, "status": 1, "ctime": "2020-12-11T17:42:10", "mtime": "2020-12-18T20:35:43", "brokerId": 21, "marginRate": 0.2097, "reducePrice": 9740.8083, "returnRate": 0.3086, "unRealizedAmount": 2164.5289, "openRealizedAmount": 2165.0173, "positionBalance": 82458.2839, "settleProfit": 0.4883, "indexPrice": 12151.1175, "keepRate": 0.005, "maxFeeRate": 0.0025 } ] } ] } ]}
| name | type | description |
|---|---|---|
account | [] | Balance collection |
account field:
| name | type | example | description |
|---|---|---|---|
| marginCoin | string | USDT | Margin coin |
| accountNormal | float | 10.05 | Balance account |
| accountLock | float | 10.07 | Margin frozen account |
| partPositionNormal | float | 10.07 | Restricted position margin balance |
| totalPositionNormal | float | 10.07 | Full position initial margin |
| achievedAmount | float | 10.07 | Profit and losses occurred |
| unrealizedAmount | float | 10.05 | Unfilled profit and losses |
| totalMarginRate | float | 10.05 | Full position margin rate |
| totalEquity | float | 10.07 | Full position equity |
| partEquity | float | 10.07 | Restricted position equity |
| totalCost | float | 10.07 | Full position costs |
| sumMarginRate | float | 10.07 | All accounts margin rate |
| positionVos | [ ] | Position contract record |
positionVos field:
| name | type | example | description |
|---|---|---|---|
| contractId | integer | 2 | Contract id |
| contractName | string | E-BTC-USDT | Contract name |
| contractSymbol | string | BTC-USDT | Contract coin pair |
| positions | [ ] | Position details |
positions field:
| name | type | example | description |
|---|---|---|---|
| id | integer | 2 | Position id |
| uid | integer | 10023 | User ID |
| positionType | integer | 1 | Hold position type(1 full，2 restrictive) |
| side | string | SELL | Hold position direction BUY sell long, SELL buy short |
| volume | float | 1.05 | Hold quantity |
| openPrice | float | 1.05 | Open position price |
| avgPrice | float | 1.05 | Hold average price |
| closePrice | float | 1.05 | Balancing average price |
| leverageLevel | float | 1.05 | Leverage multiple |
| holdAmount | float | 1.05 | Hold position margin |
| closeVolume | float | 1.05 | Balanced quantity |
| pendingCloseVolume | float | 1.05 | The number of pending closing orders |
| realizedAmount | float | 1.05 | Profit and losses occurred |
| historyRealizedAmount | float | 1.05 | Historic accumulated profit and losses |
| tradeFee | float | 1.05 | Trading fees |
| capitalFee | float | 1.05 | Capital costs |
| closeProfit | float | 1.05 | Balancing profit and loss |
| shareAmount | float | 1.05 | Amount to share |
| freezeLock | integer | 0 | Position freeze status: 0 normal, 1 liquidation freeze, 2 delivery freeze |
| status | integer | 0 | Position effectiveness，0 ineffective 1 effective |
| ctime | time | Creation time | |
| mtime | time | Update time | |
| brokerId | integer | 1023 | Client id |
| lockTime | time | liquidation lock time | |
| marginRate | float | 1.05 | Margin rate |
| reducePrice | float | 1.05 | Price reduction |
| returnRate | float | 1.05 | Return rate (profit rate) |
| unRealizedAmount | float | 1.05 | Unfilled profit and losses |
| openRealizedAmount | float | 1.05 | Open position unfilled profit and losses |
| positionBalance | float | 1.05 | Position value |
| indexPrice | float | 1.05 | Newest marked price |
| keepRate | float | 1.05 | Scaled minimum kept margin rate |
| maxFeeRate | float | 1.05 | Balancing maximum fees rate |
xxxxxxxxxxPOST https://futuresopenapi.xxx.xx/fapi/v1/tpslOrderCreate a single new order
| Name | Type | Description |
|---|---|---|
| X-CH-TS | string | Timestamp |
| X-CH-APIKEY | string | API-KEY |
| X-CH-SIGN | string | Signature |
| Name | Type | Description |
|---|---|---|
| contractName | string | Contract name such as E-BTC-USDT |
| type | string | Order Type(1 limit， 2 market) |
| side | string | Buy and sell direction, BUY/SELL |
| open | string | Opening and closing direction, OPEN/CLOSE |
| positionType | number | Position type, 1 Full Position/2 Position by Position |
| leverageLevel | number | Leverage, 10 |
| orderListStr | string | Order list |
OrderListStr
| Name | Type | Description |
|---|---|---|
| triggerType | number | Stop-loss and take-profit order types (1 stop-loss, 2 take-profit) |
| volume | number | Order quantity |
| price | number | Order price |
| type | string | Order Type(1 limit， 2 market) |
| expiredTime | number | Valid time Unit: Days |
| triggerPrice | number | Trigger Price |
xxxxxxxxxx{ "orderId": 256609229205684228}| Name | Type | Example | Description |
|---|---|---|---|
| orderId | string | 256609229205684228 | Order ID |
xxxxxxxxxxPOST https://futuresopenapi.xxx.xx/fapi/v1/tpslOrderCancelCreate a single new order
| Name | Type | Description |
|---|---|---|
| X-CH-TS | string | Timestamp |
| X-CH-APIKEY | string | API-KEY |
| X-CH-SIGN | string | Signature |
| Name | Type | Description |
|---|---|---|
| contractName | string | Contract name such as E-BTC-USDT |
| orderIds | string | Order ID, used for multiple orders, separated |
xxxxxxxxxx{ "code": "0, "msg": "success"}| Name | Type | Example | Description |
|---|---|---|---|
| code | string | 0 | Status 0 Success |
xxxxxxxxxxPOST https://futuresopenapi.xxx.xx/fapi/v1/lightClose| Name | Type | Description |
|---|---|---|
| X-CH-SIGN | string | Signature |
| X-CH-APIKEY | string | API-key |
| X-CH-TS | integer | Timestamp |
| Name | Type | Description |
|---|---|---|
| contractName | string | Contract name such as E-BTC-USDT |
| side | string | Buy and sell direction, BUY/SELL |
| open | string | Opening and closing direction, OPEN/CLOSE |
| positionType | number | Position type, 1 Full Position/2 Position by Position |
xxxxxxxxxx{ "orderId": 256609229205684228}| Name | Type | Example | Description |
|---|---|---|---|
| orderId | string | 256609229205684228 | 订单ID |
xxxxxxxxxxPOST https://futuresopenapi.xxx.xx/fapi/v1/tpsl/order
Query the user's effective stop-profit and stop-loss orders
| Name | Type | Description |
|---|---|---|
| X-CH-TS | string | Timestamp |
| X-CH-APIKEY | string | API-KEY |
| X-CH-SIGN | string | Signature |
| Name | Type | Description |
|---|---|---|
| contractName | string | Contract Name : E-BTC-USDT |
xxxxxxxxxx{"takeProfitList": [{"id": "12345","contractName": "E-BTC-USDT","triggerPrice": 42000,"price": 41500,"pricePrecision": 2,"volume": 1.5,"base": "BTC","quote": "USDT"}],"stopLossList": [{"id": "12346","contractId": "E-BTC-USDT","triggerPrice": 38000,"price": 37500,"pricePrecision": 2,"volume": 1.5,"base": "BTC","quote": "USDT"}],"takeProfitCount": 1,"stopLossCount": 1,"count": 2}
| Name | Type | Description |
|---|---|---|
| takeProfitList | Array | Take Profit Order List |
| stopLossList | Array | Stop Loss Order List |
| takeProfitCount | Integer | Number of take profit orders |
| stopLossCount | Integer | Number of stop loss orders |
| count | Integer | Total Orders |
| Field Name | Type | Description |
|---|---|---|
| id | String | Order ID |
| contractName | String | Contract Name |
| triggerPrice | BigDecimal | Trigger Price |
| price | BigDecimal | Commission Price |
| pricePrecision | Integer | Price precision (decimal places) |
| volume | BigDecimal | Order quantity |
| base | String | Base currency (such as BTC) |
| quote | String | Denominated currency (such as USDT) |
xxxxxxxxxxPOST https://openapi.xxx.xx/sapi/v1/withdraw/apply| Name | Type | Description |
|---|---|---|
| X-CH-APIKEY* | String | Your API-key |
| X-CH-SIGN* | String | Sign |
| X-CH-TS* | Integer | timestamp |
| Name | Type | Description |
|---|---|---|
| withdrawOrderId* | String | Custom withdrawal id, guaranteed to be unique |
| amount* | String | quantity |
| address* | String | Withdrawal address |
| label | String | Some currencies such as XRP, XMR allow filling of secondary address labels |
| symbol | String | currency name，For coins that support multiple mainchains, the actual currency name needs to be transmitted, as shown in Appendix 1 |
200: OK
xxxxxxxxxx{ "code":"Ѳ",//Return code, 0 for success, other failures "msg":"sucess",//returned messages "data":{ "id":518353 //Platform withdrawal id }}weight(IP/UID): 100
xxxxxxxxxxPOST` `https://openapi.xxx.xx/sapi/v1/withdraw/query
| Name | Type | Description |
|---|---|---|
| X-CH-APIKEY* | String | Your API-key |
| X-CH-SIGN* | String | Sign |
| X-CH-TS* | String | timestamp |
| Name | Type | Description |
|---|---|---|
| symbol | String | Currency Name, For coins that support multiple mainchains, the actual currency name needs to be transmitted, as shown in Appendix 1 |
| withdrawId | String | Platform withdrawal id |
| withdrawOrderId | String | Custom withdrawal id |
| startTime | String | Start time, timestamp, default 90 days ago |
| endTime | String | end time, timestamp, default current time |
| page | String | Page number, starting at 1 |
200: OK
xxxxxxxxxx{ "code": "0", "msg": "成功", "data": { "withdrawList": [ { "symbol": "TUSDT", "amount": 19.99999, "address": "TFFrjNfBAagmFWypE3Hnv6zPKAFhd3VcDf", "withdrawOrderId": "abc123", "fee": 0.00001, "ctime": 1605585397000, "txId": "749864_20201117115930", "id": 749864, "applyTime": 1666754820000, "status": 5, "info": "" }, { "symbol": "TUSDT", "amount": 10.50999, "address": "TYsTiVVDU5VmnUPufzGD52CD1hSbPATT3Q", "withdrawOrderId": "abc456", "fee": 0.00001, "ctime": 1607089149000, "txId": "764294_20201204094130", "id": 764294, "applyTime": 1666754820000", "status": 5, "info": "" } ], "count": 2 }}weight(IP/UID): 100
| Parameter | Type | Example | Remark |
|---|---|---|---|
| symbol | String | USDT | Withdrawal currency |
| amount | Number | 9.99 | quantity |
| address | String | TFFrjNfBAagmFWypE3Hnv6zPKAFhd3VcDf | Withdrawal address |
| withdrawOrderId | String | abc123 | Custom withdrawal id |
| fee | Number | 0.01 | fee |
| ctime | Number | 1605585397000 | creation time |
| txId | String | 749864_20201117115930 | Withdrawal transaction id |
| id | Number | 749864 | Platform withdrawal id |
| applyTime | Number | 1605585397000 | On-chain time |
| status | Number | 2 | Withdrawal status, 0-unapproved, 1-approved, 2-approved rejected, 3-payment, 4-payment failed, 5-completed, 6-revoked |
| info | String | Withdrawal address error | Review rejection reasons |
Websocket is a new HTML5 Protocol. It achieves full-duplex data transmission between the client and the server, allowing data to be transferred effectively in both directions. With just only one handshake, the connection between the client and the server is established. The server will then be able to push data to the client according to preset rules. Its advantages include:
The WebSocket request header for data transmission between client and server is approximately 2 bytes only
Either the client or server can initiate a data transmission
As there is no need to create and delete TCP connection repeatedly, it saves resources for both bandwidth and server
We strongly recommend developers to use WebSocket API to retrieve market data and order book depth.
url: wss://ws.xxx.xx/kline-api/ws
The returned data will be binary compressed (users need to decompress it through the Gzip algorithm)
The server actively pushes ping messages every 10 seconds, and the client can decide whether to process it after receiving it (the server does not perform strict one-to-one verification and time verification on the client's Pong reply). To ensure the validity of the link, it is recommended that the client immediately reply in Pong format after receiving the ping message from the server. Format of ping message that is sent by Server is: {"ping": timestamp (seconds)} pong message format that is replied by client is : {"pong": timestamp (seconds)} Example: {"pong":1694416595}
| sub | market_$symbol_depth_step0 | Subscribe depth | 描述 | |
|---|---|---|---|---|
| unsub | market_$symbol_depth_step0 | Unsubscribe depth | 币对名称 | |
| sub | market_$symbol_trade_ticker | Subscribe to real-time trade | base货币 | |
| unsub | market_$symbol_trade_ticker | Unsubscribe real-time trade | 计价货币 | |
| sub | market_$symbol_ticker | Subscribe to 24h market data | 价格精度 | |
| unsub | market_$symbol_ticker | Unsubscribe 24h market data | 数量精度 | |
| sub | market_$symbol_kline_1min | Subscribe to 1min k-line information | ||
| reg | market_$symbol_kline_1month | Request 1 month historical bar record |
Every once in a while, the server will send a PING message. The client needs to reply to the PONG message, otherwise the server will close the connection.
ping
xxxxxxxxxx{ "ping": 1535975085052}pong
xxxxxxxxxx{ "pong": 1535975085052}Subscription message structure
xxxxxxxxxx{ "event":"sub", "params":{ "channel":"market_$symbol_depth_step0", // $symbol E.g. btcusdt "cb_id":"1" // Business ID is not required }}Payload
xxxxxxxxxx{ "channel":"market_btcusdt_depth_step0", "ts":1506584998239, "tick":{ //A maximum of 30 orders are returned "asks":[ //asks [10000.19,0.93], [10001.21,0.2], [10002.22,0.34] ], "buys":[ //buy [9999.53,0.93], [9998.2,0.2], [9997.19,0.21] ] }}Subscription message structure
xxxxxxxxxx{ "event":"sub", "params":{ "channel":"market_$symbol_trade_ticker", // $symbol E.g. btcusdt "cb_id":"1" // Business ID is not required }}Payload
xxxxxxxxxx{ "channel":"market_$symbol_trade_ticker", "ts":1506584998239,//request time "tick":{ "data":[ { "side":"buy",//buy,sell "price":32.233, "vol":232, "amount":323, "ds":'2017-09-10 23:12:21' } ] }}Subscription message structure
xxxxxxxxxx{ "event":"sub", "params":{ "channel":"market_$symbol_kline_[1min/5min/15min/30min/60min/1day/1week/1month]", // $symbol E.g. btcusdt "cb_id":"1" // Business ID is not required }}Payload
xxxxxxxxxx{ "channel":"market_$symbol_kline_1min", //1min is for 1 minute "ts":1506584998239,//request time "tick":{ "id":1506602880,//kline start time "vol":1212.12211, "open":2233.22,//open price "close":1221.11,//close price "high":22322.22,//high price "low":2321.22//low price }}Subscription message structure
xxxxxxxxxx{ "event":"sub", "params":{ "channel":"market_$symbol_ticker", // $symbol E.g. btcusdt "cb_id":"1" // Business ID is not required }}Payload
xxxxxxxxxx{ "channel":"market_$symbol_ticker", "ts":1506584998239,//request time "tick":{ "amount":123.1221, "vol":1212.12211, "open":2233.22,//open price "close":1221.11,//close price "high":22322.22,//high price "low":2321.22,//low price "rose":-0.2922,//increase }}Subscription message structure
xxxxxxxxxx{ "event":"req", "params":{ "channel":"market_$symbol_kline_[1min/5min/15min/30min/60min/1day/1week/1month]", "cb_id":"1", "endIdx":"1506602880", //Return pageSize data before endIdx Not required "pageSize":100 // Not required }}Payload
xxxxxxxxxx{ "event_rep":"rep","channel":"market_$symbol_kline_5min", "ts":1506584998239,//request time "data":[ //up to 300 { "id":1506602880,//kline start time "amount":123.1221, "vol":1212.12211, "open":2233.22,//open price "close":1221.11,//close price "high":22322.22,//high price "low":2321.22//low price }, { "id":1506602880,//kline start time "amount":123.1221, "vol":1212.12211, "open":2233.22,//open price "close":1221.11,//close price "high":22322.22,//high price "low":2321.22//low price } ]}Subscription message structure
xxxxxxxxxx{ "event":"req", "params":{ "channel":"market_$symbol_trade_ticker", // $symbol E.g. btcusdt "cb_id":"1" // Business ID is not required }}Payload
xxxxxxxxxx{ "event_rep":"rep","channel":"market_$symbol_trade_ticker", "ts":1506584998239,"status":"ok", "data":[ { "side":"buy",//buy,sell "price":32.233,//trade price "vol":232,//trade vol "amount":323//trade amount }, { "side":"buy",//buy,sell "price":32.233,//trade price "vol":232,//trade vol "amount":323//trade amount } ]}
Errors consist of two parts: an error code and a message. Codes are universal, but messages can vary. Here is the error JSON payload:
Copy
xxxxxxxxxx{ "code":-1121, "msg":"Invalid symbol."}
| code | 描述 |
|---|---|
| -1000 | An unknown error occured while processing the request. |
| -1001 | Internal error; unable to process your request. Please try again. |
| -1002 | You are not authorized to execute this request. Request need API Key included in . We suggest that API Key be included in any request. |
| -1003 | Requests exceed the limit too frequently. |
| -1004 | You are not authorized to execute this request. User not exit Company |
| -1006 | An unexpected response was received from the message bus. Execution status unknown. OPEN API server find some exception in execute request .Please report to Customer service. |
| -1007 | Timeout waiting for response from backend server. Send status unknown; execution status unknown. |
| -1014 | Unsupported order combination. |
| -1015 | Too many new orders. |
| -1016 | This service is no longer available. |
| -1017 | We recommend attaching Content-Type to all request headers and setting it to application/json |
| -1020 | This operation is not supported. |
| -1021 | Timestamp for this request is outside of the recvWindow.Timestamp for this request was 1000ms ahead of the server's time.Please check the difference between your local time and server time . |
| -1022 | Signature for this request is not valid. |
| -1023 | You are not authorized to execute this request, we recommend that you add X-CH-TS to all request headers |
| -1024 | You are not authorized to execute this request, we recommend that you add X-CH-SIGN to the request header |
| code | 描述 |
|---|---|
| -1100 | Illegal characters found in a parameter. |
| -1101 | Too many parameters sent for this endpoint |
| -1102 | A mandatory parameter was not sent, was empty/null, or malformed.Mandatory parameter '%s' was not sent, was empty/null, or malformed. Param '%s' or '%s' must be sent, but both were empty/null! |
| -1103 | An unknown parameter was sent.each request requires at least one parameter. {Timestamp}. |
| -1104 | Not all sent parameters were read.Not all sent parameters were read; read '%s' parameter(s) but was sent '%s'. |
| -1105 | A parameter was empty.Parameter '%s' was empty. |
| -1106 | A parameter was sent when not required.Parameter '%s' sent when not required. |
| -1111 | Precision is over the maximum defined for this asset. |
| -1112 | No orders on book for symbol. |
| -1116 | Invalid orderType.In the current version , ORDER_TYPE values is LIMIT or MARKET. |
| -1117 | Invalid side.ORDER_SIDE values is BUY or SELL |
| -1118 | New client order ID was empty. |
| -1121 | Invalid symbol. |
| -1136 | Order volume lower than the minimum. |
| -1138 | Order price exceeds permissible range. |
| -1139 | This trading pair does not support market trading |
| -1145 | This order type does not support cancellation |
| -2013 | Order does not exist. |
| -2015 | Invalid API-key, IP, or permissions for action. |
| -2016 | Transaction is frozen |
| -2017 | Insufficient balance |
https://github.com/exchange2021
x/** * generate sign **/private String toSign(String timestamp, String method, String requestPath, String queryString, String body, String secretKey) throws Exception { // sign String preHash = preHash(timestamp, method, requestPath, queryString, body); byte[] secretKeyBytes = secretKey.getBytes("UTF-8"); SecretKeySpec secretKeySpec = new SecretKeySpec(secretKeyBytes, "HmacSHA256"); Mac mac = (Mac) MAC.clone(); mac.init(secretKeySpec); return Hex.encodeHexString(mac.doFinal(preHash.getBytes("UTF-8")));}
/** * sign **/private String preHash(String timestamp, String method, String requestPath, String queryString, String body) { StringBuilder preHash = new StringBuilder(); preHash.append(timestamp); preHash.append(method.toUpperCase()); preHash.append(requestPath); if (org.apache.commons.lang3.StringUtils.isNotEmpty(queryString)) { preHash.append("?").append(queryString); } if (org.apache.commons.lang3.StringUtils.isNotEmpty(body)) { preHash.append(body); } return preHash.toString();}
/** * queryString **/private String queryString(ServerHttpRequest request) { String url = request.getURI().toString(); String queryString = ""; if (url.contains("?")) { queryString = url.substring(url.lastIndexOf("?") + 1); } return queryString;}Java
xxxxxxxxxxOkHttpClient client = new OkHttpClient().newBuilder() .build();MediaType mediaType = MediaType.parse("application/json");RequestBody body = RequestBody.create(mediaType, "{\"symbol\":\"BTCUSDT\",\"volume\":1,\"side\":\"BUY\",\"type\":\"LIMIT\",\"price\":10000,\"newClientOrderId\":\"\",\"recvWindow\":5000}");Request request = new Request.Builder() .url("https://openapi.xxx.com") .method("POST", body) .addHeader("X-CH-APIKEY", "Your API key") .addHeader("X-CH-TS", "1596543296058") .addHeader("Content-Type", "application/json") .addHeader("X-CH-SIGN", "encrypt sign") .build();Response response = client.newCall(request).execute();Go
xxxxxxxxxxpackage main
import ( "fmt" "strings" "net/http" "io/ioutil")
func main() {
url := "https://openapi.xxx.com" method := "POST"
payload := strings.NewReader("{\"symbol\":\"BTCUSDT\",\"volume\":1,\"side\":\"BUY\",\"type\":\"LIMIT\",\"price\":10000,\"newClientOrderId\":\"\",\"recvWindow\":5000}")
client := &http.Client { } req, err := http.NewRequest(method, url, payload)
if err != nil { fmt.Println(err) } req.Header.Add("X-CH-APIKEY", "Your API key") req.Header.Add("X-CH-TS", "1596543881257") req.Header.Add("Content-Type", "application/json") req.Header.Add("X-CH-SIGN", "encrypt sign")
res, err := client.Do(req) defer res.Body.Close() body, err := ioutil.ReadAll(res.Body)
fmt.Println(string(body))}Python
xxxxxxxxxximport requests
url = "https://openapi.xxx.com"
payload = "{\"symbol\":\"BTCUSDT\",\"volume\":1,\"side\":\"BUY\",\"type\":\"LIMIT\",\"price\":10000,\"newClientOrderId\":\"\",\"recvWindow\":5000}"headers = { 'X-CH-APIKEY': 'Your API key', 'X-CH-TS': '1596543881257', 'Content-Type': 'application/json', 'X-CH-SIGN': 'encrypt sign'}
response = requests.request("POST", url, headers=headers, data = payload)
print(response.text.encode('utf8'))Php
xxxxxxxxxx<?phprequire_once 'HTTP/Request2.php';$request = new HTTP_Request2();$request->setUrl('https://openapi.xxx.com');$request->setMethod(HTTP_Request2::METHOD_POST);$request->setConfig(array( 'follow_redirects' => TRUE));$request->setHeader(array( 'X-CH-APIKEY' => 'Your API key', 'X-CH-TS' => '1596543881257', 'Content-Type' => 'application/json', 'X-CH-SIGN' => 'encrypt sign'));$request->setBody('{"symbol":"BTCUSDT","volume":1,"side":"BUY","type":"LIMIT","price":10000,"newClientOrderId":"","recvWindow":5000}');try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); }}catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage();}NodeJs
xxxxxxxxxxvar request = require('request');var options = { 'method': 'POST', 'url': 'https://openapi.xxx.com', 'headers': { 'X-CH-APIKEY': 'Your API key', 'X-CH-TS': '1596543881257', 'Content-Type': 'application/json', 'X-CH-SIGN': 'encrypt sign' }, body: JSON.stringify({"symbol":"BTCUSDT","volume":1,"side":"BUY","type":"LIMIT","price":10000,"newClientOrderId":"","recvWindow":5000})
};request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body);});
When the server receives the request, it will judge the timestamp in the request. If it is sent before 5000 milliseconds, the request will be considered invalid. This time window value can be customized by sending the optional parameter recvWindow.
First, it is recommended that the user print out the X-CH-TS, and check whether the X-CH-TS is empty when there is an exception, and it is recommended that the user code is optimized, and judge whether the X-CH-TS is empty before each request.
You can print out the request header information and the string before signature, with the following points:：
Compare your request header with the following request header example one by one
xxxxxxxxxxExample request header:Content-Type: application/jsonX-CH-APIKEY: 44c541a1-****-****-****-10fe390df2X-CH-SIGN: ssseLeefrffraoEQ3yI9qEtI1CZ82ikZ4xSG5Kj8gnl3uw=X-CH-TS: 1574327555669Is the API-key configured correctly in the program
Whether the string before signing conforms to the standard format, the order of all elements must be consistent. You can copy the following example to compare with your string before signing:
xxxxxxxxxxGET Example： 1588591856950GET/sapi/v1/accountPOST Example：1588591856950POST/sapi/v1/order/test{"symbol":"BTCUSDT","price":"9300","volume":"1","side":"BUY","type":"LIMIT"}We recommend attaching Content-Type to all request headers and setting it to application/json
There are restrictions. For details, see the access frequency restrictions for each interface in the document.
Personal data is restricted according to API-key, and public data is restricted according to ip. It should be noted that if the user requests public data and passes in valid personal information, it is restricted according to API-key.
The request interface exceeds the access frequency limit. It is recommended to reduce the access frequency.
Normally not, just reduce the frequency of access.
Without adding a heartbeat, the WebSocket connection requires the client to return to pong to ensure the stability of the connection.
The pong message sent by the client is caused by network reasons, but the server does not receive it, or other network reasons may also cause automatic disconnection.
It is recommended that users have a good WebSocket disconnect and reconnect mechanism to ensure that the program can automatically reconnect when the heartbeat (ping/pong) connection is accidentally disconnected.
The network cannot connect to the server. It is recommended that you check whether the network is smooth.
Coin's /sapi/v1/symbols interface can be obtained
Yes, the batch interface will limit 10 orders
newClientOrderId is your customized order number, which can be used to identify your order. After the order is placed, you can make newClientOrderId call the "Order Information" interface to view the order status;
The user needs to ensure that this ID is not repeated, and we will not prompt for re-relocation. If there is a repetition, you can only cancel or query the latest piece of data when canceling and querying the order
You can get ticker information, last is the latest transaction price
Will do. Because the 24-hour trading volume is a 24-hour rolling data (the size of the translation window is 24 hours), it may happen that the accumulated trading volume and accumulated trading volume in the next window are smaller than the previous window.