XT DOC logo

简体中文
english
Spot Futures
现货 合约

REST API Edit

production environment: https://sapi.xt.com

Basic information of the interface Edit

Due to reasons such as high latency and poor stability, it is not recommended to access the API through a proxy.

GET request parameters are placed in query Params, POST request parameters are placed in request body

Please set the request header information to:Content-Type=application/json

For requests that start other than /public, the request message needs to be signed

Frequency Limiting Rules Edit

Some interfaces will have limited flow control (the corresponding interface will have a limited flow description). The flow limit is mainly divided into gateway flow limit and WAF flow limit.

If the interface request triggers the gateway flow limit, 429 will be returned, indicating that the access frequency exceeds the limit, and the IP or apiKey will be blocked.

Gateway flow limiting is divided into IP and apiKey flow limiting.

Example description of IP flow limit: 100/s/ip, indicating the limit of the number of requests per second for this interface per IP.

apiKey current limit example description: 50/s/apiKey, indicating the limit of the number of requests per second for the interface per apiKey.

Signature Instructions Edit

Since XT needs to provide some open interfaces for third-party platforms, it requires data security issues of the interface, such as whether the data has been tampered with, whether the data is outdated, whether the data can be submitted repeatedly, and the frequency of access to the interface within a certain period of time. Among them, whether the data has been tampered with is the most important.

  1. First apply for appkey and secretkey through the user center, and provide different appkey and secretkey for different calls

  2. Add timestamp (timestamp), its value should be the unix timestamp (milliseconds) of the time when the request is sent, and the suburban time of the data is calculated according to this value.

  3. Add signature (data signature), the signature information of all data.

  4. Add recvwindow (custom request valid time), the valid time is relatively simple and fixed to a certain value.

When the server receives the request, it will judge the timestamp in the request. The longest is 60 seconds and the minimum is 2 seconds. If it was sent 5000 milliseconds ago, the request will be considered invalid. This time window value can be set by sending the optional parameter recvWindow. In addition, the server will also reject the request if it calculates that the client timestamp is more than one second ‘in the future’ of server time. Regarding the transaction timeliness, the Internet is not 100% reliable and cannot be completely relied upon. Therefore, the delay from your program to the XT server will be jittery. This is the purpose of setting recvwindow. If you are engaged in high-frequency trading, the transaction timeliness There are high requirements for sex, and you can flexibly set recvwindow to meet your requirements.

Recvwindow longer than 5 seconds is not recommended

5、Added algorithm (signature method/algorithm), the user’s signature is a hash-based protocol, and HmacSHA256 is recommended. For those protocols that are supported, see the table below.

HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256(recommended)、HmacSHA384、HmacSHA512

Signature generation Edit

Take https://sapi.xt-uat.com/v4/order as an example.

The following is an example appkey and secret for placing an order using a call interface implemented by echo openssl and curl tools in the linux bash environment for demonstration purposes only:

appKey: 3976eb88-76d0-4f6e-a6b2-a57980770085

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Header part data:

xt-validate-algorithms: HmacSHA256

xt-validate-appkey: 3976eb88-76d0-4f6e-a6b2-a57980770085

xt-validate-recvwindow: 5000

xt-validate-timestamp: 1641446237201

xt-validate-signature: 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9

request data:

{
  type: 'LIMIT',
  timeInForce: 'GTC',
  side: 'BUY',
  symbol: 'btc_usdt',
  price: '39000',
  quantity: '2'
}

1.data part

method: UpperCase method. eg: GET, POST, DELETE, PUT

path: Concatenate all values in the order in path. The restful path in the form of /test/{var1}/{var2}/ will be spliced according to the actual parameters filled in, for example: /sign/test/bb/aa

query: Sort all key=value according to the lexicographical order of the key. Example: userName=dfdfdf&password=ggg

body:   
    Json: Directly by JSON string without conversion or sorting.

    x-www-form-urlencoded: Sort all key=values according to the lexicographical order of keys, for example: userName=dfdfdf&password=ggg

    form-data:This format is not currently supported.

If there are multiple data forms, re-splicing is performed in the order of path, query, and body to obtain the splicing value of all data.

Method example:

POST

Path example:

/v4/order

The above concatenated value is recorded as path

Parameters passed query example:

symbol=btc_usdt

The above concatenated value is recorded as query

Parameters via body example

x-www-form-urlencoded:
  
    symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

    The above concatenated value is recorded as body

json:

    {"symbol":"btc_usdt","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":2,"price":39000}

    The above concatenated value is recorded as body

Mixed use of query and body (divided into form and json format)

query: 
    symbol=btc_usdt&side=BUY&type=LIMIT
    The above concatenated value is recorded as query

body: 
    {"symbol":"btc_usdt","side":BUY,"type":"LIMIT"}
    The above concatenated value is recorded as body

The most concatenated value of the entire data is spliced with method, path, query, and body by the # symbol to form #method, #path, #query, and #body, and the final spliced value is recorded as Y=#method#path#query#body. Notice:

The query has data, but the body has no data: Y=#method#path#query

query has no data, body has data: Y=#method#path#body

query has data, body has data: Y=#method#path#query#body

2.request header part After the keys are in natural ascending alphabetical order, use & to join them together as X. like:

    xt-validate-algorithms=HmacSHA256&xt-validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&xt-validate-recvwindow=5000&xt-validate-timestamp=1641446237201

3.generate signature

Finally, the string that needs to be encrypted is recorded as original=XY

Finally, encrypt the final concatenated value according to the following method to obtain a signature.

signature=org.apache.commons.codec.digest.HmacUtils.hmacSha256Hex(secretkey, original);

Put the generated signature singature in the request header, with xt-validate-signature as the key and singature as the value.

4.example

sample of original signature message:
  
    xt-validate-algorithms=HmacSHA256&xt-validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&xt-validate-recvwindow=60000&xt-validate-timestamp=1666026215729#POST#/v4/order#{"symbol":"XT_USDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":3,"quantity":2}

sample request message:

    curl --location --request POST 'https://sapi.xt.com/v4/order' 
    --header 'accept: */*' 
    --header 'Content-Type: application/json' 
    --header 'xt-validate-algorithms: HmacSHA256' 
    --header 'xt-validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' 
    --header 'xt-validate-recvwindow: 60000' 
    --header 'xt-validate-timestamp: 1666026215729' 
    --header 'xt-validate-signature: 4cb36e820f50d2e353e5e0a182dc4a955b1c26efcb4b513d81eec31dd36072ba' 
    --data-raw '{"symbol":"XT_USDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":3,"quantity":2}'    

matters needing attention:

    Pay attention to checking the parameter format of Content Type, signature original message and request message

API Key application steps Edit

The interface may require the user’s API Key,How to create API-KEY please refer to here

API code library Edit

Java connector

A lightweight Java codebase that provides methods that allow users to directly call the API。

Sdks for each language:

  java : https://github.com/xt-com/xt4-java-demo
  python : https://github.com/xt-com/xt4-python-demo
  golang : https://github.com/xt-com/xt4-go-demo
  c# : https://github.com/xt-com/xt4-c--demo
  nodejs: https://github.com/xt-com/xt4-nodejs-demo

Sample request information for each interface:

  https://github.com/xt-com/xt4-request-demo/blob/master/request-xt.txt

response format Edit

All interface returns are in JSON format.

{
    "rc": 0,
    "result": {
      },
    "mc": "SUCCESS"
    "ma": []
}

response code Edit

httpStatus description
200 The request is successful, please check the rc and mc sections further
404 interface does not exist
429 The request is too frequent, please control the request rate according to the speed limit requirement
500 Service exception
502 Gateway exception
503 Service unavailable, please try again later
rc return Code
0 business success
1 business failure
mc message code
SUCCESS success
FAILURE fail
AUTH_001 missing request header xt-validate-appkey
AUTH_002 missing request header xt-validate-timestamp
AUTH_003 missing request header xt-validate-recvwindow
AUTH_004 bad request header xt-validate-recvwindow
AUTH_005 missing request header xt-validate-algorithms
AUTH_006 bad request header xt-validate-algorithms
AUTH_007 missing request header xt-validate-signature
AUTH_101 ApiKey does not exist
AUTH_102 ApiKey is not activated
AUTH_103 Signature error
AUTH_104 Unbound IP request
AUTH_105 outdated message
AUTH_106 Exceeded apikey permission
SYMBOL_001 Symbol not exist
SYMBOL_002 Symbol offline
SYMBOL_003 Symbol suspend trading
SYMBOL_004 Symbol country disallow trading
ORDER_001 Platform rejection
ORDER_002 insufficient funds
ORDER_003 Trading Pair Suspended
ORDER_004 no transaction
ORDER_005 Order not exist
ORDER_006 Too many open orders
ORDER_F0101 Trigger Price Filter - Min
ORDER_F0102 Trigger Price Filter - Max
ORDER_F0103 Trigger Price Filter - Step Value
ORDER_F0201 Trigger Quantity Filter - Min
ORDER_F0202 Trigger Quantity Filter - Max
ORDER_F0203 Trigger Quantity Filter - Step Value
ORDER_F0301 Trigger QUOTE_QTY Filter - Min Value
ORDER_F0401 Trigger PROTECTION_ONLINE Filter
ORDER_F0501 Trigger PROTECTION_LIMIT Filter
ORDER_F0601 Trigger PROTECTION_MARKET Filter

Get server time Edit

/v4/public/time

public String getServerInfo(){


}

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": {
    "serverTime": 1662435658062  
  }
}

Get symbol information Edit

/v4/public/symbol

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false trading pair eg:btc_usdt
symbols array false Collection of trading pairs. Priority is higher than symbol. eg: btc_usdt,eth_usdt
version string false Version number, when the request version number is consistent with the response content version, the list will not be returned, reducing IO eg: 2e14d2cd5czcb2c2af2c1db65078d075

Limit Flow Rules

1.single symbol:100/s/ip

2.multiple symbols:10/s/ip


FILTER

Filter, defines a series of trading rules. There are different filters for different fields or entities. Here we mainly introduce the filter for the entity symbol. For symbols, there are two kinds of filters, one is a global filter, and the other is a filter customized for a certain trading pair.


PRICE FILTER

The price filter is used to check the validity of the price parameter in the order. Contains the following three parts:

1.min Defines the minimum allowable price in the order

2.max Defines the maximum price allowed in the order

3.tickSize Defines the step interval of price in the order, that is, price must be equal to minPrice+(integer multiple of tickSize)

Each of the above items can be null, when it is null, it means that this item is no longer restricted

The logical pseudocode is as follows:

  • price >= min
  • price <= max
  • (price-minPrice) % tickSize == 0

QUANTITY FILTER

The logic is similar to PRICE FILTER ,but for the order quantity.

It contains three parts:

1.min minimum allowed

2.max maximum allowed

3.tickSize  Step interval, that is, quantity must be equal to minQuantity+(integer multiple of tickSize)

Each of the above items can be null, when it is null, it means that this item is no longer restricted

The logical pseudocode is as follows:

  • quantity>= min
  • quantity<= max
  • (quantity-minQuantity)% tickSize == 0

QUOTE_QTY FILTER

Limit the amount of the order

It internally defines the minimum allowable value-min

When min is null, the order is not limited

Otherwise the restriction rules are as follows:

1.For orders of the LIMIT type,must meet the following conditions: price*quantity>=min

2.For orders of the MARKET type and BUY type,must meet the following conditions: quoteQty>=min,(quoteQty,The required amount when placing an order of MARKET type by amount)


PROTECTION_LIMIT FILTER

There are price protection restrictions for orders whose order type (orderType) is LIMIT, including the following two parts:

1.buyMaxDeviation The maximum deviation of the buy order, which limits the difference between the buy order price and the latest transaction price

2.sellMaxDeviation The maximum deviation of the sell order, which limits the difference between the sell order price and the latest transaction price

If there is no latest transaction price, there will be no restrictions, or if the above parameters are null, the corresponding direction type orders will not be restricted.

In order to pass the limit price protection, the order price must meet the following conditions (latestPrice is the latest transaction price)

buy order: price >= latestPrice-latestPrice*buyMaxDeviation 

sell order: price <= latestPrice+latestPrice*sellMaxDeviation


PROTECTION_MARKET FILTER

There is a price limit protection mechanism for orders of the order type MARKET, which internally specifies the maximum deviation rate(maxDeviation).

For market type orders, the market price must meet the following conditions for the order to pass(sellBestPrice  sell one price,buyBestPrice buy one price,latestPrice The latest transaction price, these data are obtained through historical transaction data)

buy order: latestPrice + latestPrice* maxDeviation >= sellBestPrice 

sell order: latestPrice - latestPrice* maxDeviation <= buyBestPrice

For the above situation maxDeviation,latestPrice,sellBestPrice,buyBestPrice

All may be empty or there is no latest transaction price, buy one price, sell one price, there is no limit


PROTECTION_ONLINE FILTER

Limit the price of orders of the MARKET type within the specified time range after the opening

The maximum price multiple is defined inside this filter(maxPriceMultiple),duration(durationSeconds)。

Limitation logic: when it is within the durationSeconds time range after the opening of the symbol, Orders with an order type of LIMIT must meet the following conditions to pass

price<=openPrice*maxPriceMultiple,(openPrice is the opening price).

There are no restrictions on other types of orders or orders outside the opening time frame.

For maxPriceMultiple, durationSeconds can be null, when they are null, no opening protection limit is applied.

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": {
    "time": 1662444177871,  
    "version": "7cd2cfab0dc979339f1de904bd90c9cb",  
    "symbols": [                   
      {
        "id": 614,                              //ID
        "symbol": "btc_usdt",         
        "state": "ONLINE",                      //symbol state[ONLINE;OFFLINE,DELISTED]
        "tradingEnabled": true,           
        "nextStateTime": null,              
        "nextState": null,                 
        "depthMergePrecision": 5,               //Depth Merge Accuracy
        "baseCurrency": "btc",                  
        "baseCurrencyPrecision": 5,              
        "baseCurrencyId": 2,                 
        "quoteCurrency": "usdt",             
        "quoteCurrencyPrecision": 6,        
        "quoteCurrencyId": 11,             
        "pricePrecision": 4,                    //Transaction price accuracy
        "quantityPrecision": 6,           
        "orderTypes": [                         //Order Type[LIMIT;MARKET]
          "LIMIT",
          "MARKET"
        ],
        "timeInForces": [                       //Effective ways[GTC=It remains valid until the transaction is concluded; IOC=Cancel the part that cannot be transacted immediately (taking orders); FOK=Cancellation if all transactions cannot be completed immediately; GTX=Revoke if unable to become a pending party]
          "GTC",
          "FOK",
          "IOC",
          "GTX"
        ],
        "displayWeight": 1,                     //Show the weight, the greater the weight, the more forward
        "displayLevel": "FULL",                 //Presentation level,[FULL=Full display,SEARCH=Search display,DIRECT=Direct display,NONE=Don't show]
        "plates": [],                           //  eg:22,23,24
        "filters": [                       
          {
            "filter": "PROTECTION_LIMIT",
            "buyMaxDeviation": "0.8"
            "sellMaxDeviation": "0.8"
          },
          {
            "filter": "PROTECTION_MARKET",
            "maxDeviation": "0.1"
          },
          {
            "filter": "PROTECTION_ONLINE",
            "durationSeconds": "300",
            "maxPriceMultiple": "5"
          },
          {
            "filter": "PRICE",
            "min": null,
            "max": null,
            "tickSize": null
          },
          {
            "filter": "QUANTITY",
            "min": null,
            "max": null,
            "tickSize": null
          },
          {
            "filter": "QUOTE_QTY",
            "min": null
          },
       ]
      }
    ]
  }
}

Get depth data Edit

/v4/public/depth

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true trading pair eg:btc_usdt
limit number false 50 1~500

Limit Flow Rules

200/s/ip

public String depth(){


}

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": {
    "timestamp": 1662445330524,  
    "lastUpdateId": 137333589606963580,     //Last updated record
    "bids": [                               //buy order([?][0]=price;[?][1]=pending order volume)
      [
        "200.0000",                         //price
        "0.996000"                          //pending order volume
      ],
      [
        "100.0000",
        "0.001000"
      ],
      [
        "20.0000",
        "10.000000"
      ]
    ],
    "asks": []                              //sell order([?][0]=price;[?][1]=pending order volume)
  }
}

Get K-line data Edit

/v4/public/kline

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true trading pair eg:btc_usdt
interval string true K line type ,1m;3m;5m;15m;30m;1h;2h;4h;6h;8h;12h;1d;3d;1w;1M eg:1m [1m;3m;5m;15m;30m;1h;2h;4h;6h;8h;12h;1d;3d;1w;1M]
startTime number false start timestamp
endTime number false end timestamp
limit number false 100 1~1000

Limit Flow Rules

100/s/ip

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "t": 1662601014832,   //open time
      "o": "30000",         //open price
      "c": "32000",         //close price
      "h": "35000",         //highest price
      "l": "25000",         //lowest price
      "q": "512",           //transaction quantity
      "v": "15360000"       //transaction volume
    }
  ]
}

Query the list of recent transactions Edit

/v4/public/trade/recent

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true trading pair
limit number false 200 1,1000

Limit Flow Rules

100/s/ip

public String tradeRecent(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "i": 0,           //ID
      "t": 0,           //transaction time
      "p": "string",    //transaction price
      "q": "string",    //transaction quantity
      "v": "string",    //transaction volume
      "b": true         //buyerMaker
    }
  ]
}

Query historical transaction list Edit

/v4/public/trade/history

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true trading pair
limit number false 200 1,1000
fromId number false Start ID,eg: 6216559590087220004

Limit Flow Rules

100/s/ip

public String tradeHistory(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "i": 0,           //ID
      "t": 0,           //transaction time
      "p": "string",    //transaction price
      "q": "string",    //transaction quantity
      "v": "string",    //transaction volume
      "b": true         //buyerMaker
    }
  ]
}

Full ticker Edit

/v4/public/ticker

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false trading pair eg:btc_usdt
symbols array false Collection of trading pairs. Priority is higher than symbol. eg: btc_usdt,eth_usdt
tags string false Set of tags, separated by commas, currently only supports spot

Limit Flow Rules

1.single symbol:100/s/ip

2.multiple symbols:10/s/ip

public String price(){


}

{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": [
          {
            "s": "btc_usdt",        //symbol
            "t": 1662444879425,     //update time
            "cv": "0.00",           //change value
            "cr": "0.0000",         //change rate
            "o": "200.00",          //open
            "l": "200.00",          //low
            "h": "200.00",          //high
            "c": "200.00",          //close
            "q": "0.002",           //quantity
            "v": "0.40",            //volume
            "ap": null,             //asks price(sell one price)
            "aq": null,             //asks qty(sell one quantity)
            "bp": null,             //bids price(buy one price)
            "bq": null              //bids qty(buy one quantity)
            }
        ]
}

Get latest prices ticker Edit

/v4/public/ticker/price

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false trading pair eg:btc_usdt
symbols array false Collection of trading pairs. Priority is higher than symbol. eg: btc_usdt,eth_usdt
tags string false Set of tags, separated by commas, currently only supports spot

Limit Flow Rules

1.single symbol:100/s/ip

2.multiple symbols:10/s/ip

public String price(){


}

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": [
    {
      "s": "btc_usdt",      //symbol
      "t": 1661856036925    //time
      "p": "9000.0000",     //price
      }
  ]
}

Get the best pending order ticker Edit

/v4/public/ticker/book

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false trading pair eg:btc_usdt
symbols array false Collection of trading pairs. Priority is higher than symbol. eg: btc_usdt,eth_usdt
tags string false Set of tags, separated by commas, currently only supports spot

Limit Flow Rules

1.single symbol:100/s/ip

2.multiple symbols:10/s/ip

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": [
    {
      "s": "btc_usdt",      //symbol
      "t": 1661856036925,   //time 
      "ap": null,           //asks price(sell one price)
      "aq": null,           //asks qty(sell one quantity)
      "bp": null,           //bids price(buy one price)
      "bq": null            //bids qty(buy one quantity)
    }
  ]
}

Get 24h statistics ticker Edit

/v4/public/ticker/24h

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false trading pair eg:btc_usdt
symbols array false Collection of trading pairs. Priority is higher than symbol. eg: btc_usdt,eth_usdt
tags string false Set of tags, separated by commas, currently only supports spot

Limit Flow Rules

1.single symbol:100/s/ip

2.multiple symbols:10/s/ip

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": [
    {
      "s": "btc_usdt",      //symbol
      "t": 1661856036925,   //time 
      "cv": "0.0000",       //price change value
      "cr": "0.00",         //price change rate
      "o": "9000.0000",     //open price
      "l": "9000.0000",     //lowest price
      "h": "9000.0000",     //highest price
      "c": "9000.0000",     //close price
      "q": "0.0136",        //transaction quantity
      "v": "122.9940"       //transaction volume
    }
  ]
}

Get single Edit

/v4/order/{orderId}

Parameters
Parameter Type mandatory Default Description Ranges
orderId number true
public String orderGet(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "symbol": "BTC_USDT",   
    "orderId": "6216559590087220004",  
    "clientOrderId": "16559590087220001",  
    "baseCurrency": "string",   
    "quoteCurrency": "string",   
    "side": "BUY",                          //order side:BUY,SELL
    "type": "LIMIT",                        //order type  LIMIT,MARKET 
    "timeInForce": "GTC",                   //effective way:GTC,IOC,FOK,GTX
    "price": "40000",   
    "origQty": "2",                         //original quantity
    "origQuoteQty": "48000",                //original amount
    "executedQty": "1.2",                   //executed quantity
    "leavingQty": "string",                 //The quantity to be executed (if the order is cancelled or the order is rejected, the value is 0)
    "tradeBase": "2",                       //transaction quantity
    "tradeQuote": "48000",                  //transaction amount
    "avgPrice": "42350",                    //average transaction price
    "fee": "string",                        //handling fee
    "feeCurrency": "string",   
    "state": "NEW",                         //order stat NEW,PARTIALLY_FILLED,FILLED,CANCELED,REJECTED,EXPIRED
    "time": 1655958915583,                  //order time
    "updatedTime": 1655958915583  
  }
}

Query single Edit

/v4/order

Parameters
Parameter Type mandatory Default Description Ranges
orderId number false
clientOrderId string false
public String orderGet(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "symbol": "BTC_USDT",   
    "orderId": "6216559590087220004",  
    "clientOrderId": "16559590087220001",  
    "baseCurrency": "string",   
    "quoteCurrency": "string",   
    "side": "BUY",                      //order side:BUY,SELL
    "type": "LIMIT",                    //order type  LIMIT,MARKET 
    "timeInForce": "GTC",               //effective way:GTC,IOC,FOK,GTX
    "price": "40000",   
    "origQty": "2",                     //original quantity
    "origQuoteQty": "48000",            //original amount
    "executedQty": "1.2",               //executed quantity
    "leavingQty": "string",             //The quantity to be executed (if the order is cancelled or the order is rejected, the value is 0)
    "tradeBase": "2",                   //transaction quantity
    "tradeQuote": "48000",              //transaction amount
    "avgPrice": "42350",                //average transaction price
    "fee": "string",                    //handling fee
    "feeCurrency": "string",   
    "state": "NEW",                     //order stat NEW,PARTIALLY_FILLED,FILLED,CANCELED,REJECTED,EXPIRED
    "time": 1655958915583,              //order time
    "updatedTime": 1655958915583  
  }
}

Submit order Edit

/v4/order

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true
clientOrderId string false Pattern: ^[a-zA-Z0-9_]{4,32}$
side string true BUY,SELL
type string true order type:LIMIT,MARKET
timeInForce string true effective way:GTC, FOK, IOC, GTX
bizType string true SPOT, LEVER
price number false price. Required if it is the LIMIT price; blank if it is the MARKET price
quantity number false quantity. Required if it is the LIMIT price or the order is placed at the market price by quantity
quoteQty number false amount. Required if it is the LIMIT price or the order is the market price when placing an order by amount

Limit Flow Rules

50/s/apikey

public String orderPost(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "orderId": "6216559590087220004"  
  }
}

Cancell order Edit

/v4/order/{orderId}

Parameters
Parameter Type mandatory Default Description Ranges
orderId number true
public String orderDel(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "cancelId": "6216559590087220004"
  }
}

Get batch Edit

/v4/batch-order

Parameters
Parameter Type mandatory Default Description Ranges
orderIds string true order Ids eg: 6216559590087220004,6216559590087220004

reponse field information, refer to the Get single interface

public String batchOrderGet(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "symbol": "BTC_USDT",
      "orderId": "6216559590087220004",
      "clientOrderId": "16559590087220001",
      "baseCurrency": "string",
      "quoteCurrency": "string",
      "side": "BUY",
      "type": "LIMIT",
      "timeInForce": "GTC",
      "price": "40000",
      "origQty": "2",
      "origQuoteQty": "48000",
      "executedQty": "1.2",
      "leavingQty": "string",
      "tradeBase": "2",
      "tradeQuote": "48000",
      "avgPrice": "42350",
      "fee": "string",
      "feeCurrency": "string",
      "state": "NEW",
      "time": 1655958915583,
      "updatedTime": 1655958915583
    }
  ]
}

Cancell batch order Edit

/v4/batch-order

Parameters
Parameter Type mandatory Default Description Ranges
clientBatchId string false client batch id
orderIds array true 62165595900872200046216559590087220005

The parameters are placed in the body in the form of json

public String batchOrderDel(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {}
}

Query the current pending order Edit

/v4/open-order

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false Trading pair, if not filled in, represents all
bizType string false SPOT, LEVER
side string false BUY,SELL
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [      //For field information, refer to the Get single interface
    {
      "symbol": "BTC_USDT",
      "orderId": "6216559590087220004",
      "clientOrderId": "16559590087220001",
      "baseCurrency": "string",
      "quoteCurrency": "string",
      "side": "BUY",
      "type": "LIMIT",
      "timeInForce": "GTC",
      "price": "40000",
      "origQty": "2",
      "origQuoteQty": "48000",
      "executedQty": "1.2",
      "leavingQty": "string",
      "tradeBase": "2",
      "tradeQuote": "48000",
      "avgPrice": "42350",
      "fee": "string",
      "feeCurrency": "string",
      "state": "NEW",
      "time": 1655958915583,
      "updatedTime": 1655958915583
    }
  ]
}

Cancel the current pending order Edit

/v4/open-order

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false Trading pair, if not filled in, represents all
bizType string false SPOT, LEVER
side string false BUY,SELL

The parameters are placed in the body in the form of json

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {}
}

Query historical orders Edit

/v4/history-order

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false Trading pair, if not filled in, represents all
bizType string false SPOT, LEVER
side string false BUY,SELL
type string false LIMIT, MARKET
state string false PARTIALLY_FILLED,FILLED,CANCELED,REJECTED,EXPIRED
fromId number false start id
direction string false query direction:PREV, NEXT
limit number false 20 Limit number, max 100
startTime number false eg:1657682804112
endTime number false
hiddenCanceled bool false
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "hasPrev": true,
    "hasNext": true,
    "items": [   //For field information, refer to the Get single interface
      {
        "symbol": "BTC_USDT",
        "orderId": "6216559590087220004",
        "clientOrderId": "16559590087220001",
        "baseCurrency": "string",
        "quoteCurrency": "string",
        "side": "BUY",
        "type": "LIMIT",
        "timeInForce": "GTC",
        "price": "40000",
        "origQty": "2",
        "origQuoteQty": "48000",
        "executedQty": "1.2",
        "leavingQty": "string",
        "tradeBase": "2",
        "tradeQuote": "48000",
        "avgPrice": "42350",
        "fee": "string",
        "feeCurrency": "string",
        "state": "NEW",
        "time": 1655958915583,
        "updatedTime": 1655958915583
      }
    ]
  }
}

Query trade Edit

/v4/trade

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false Trading pair, if not filled in, represents all
bizType string false SPOT, LEVER
orderSide string false BUY,SELL
orderType string false LIMIT, MARKET
orderId number false
fromId number false start id
direction string false query direction:PREV, NEXT
limit number false 20 Limit number, max 100
startTime number false start time eg:1657682804112
endTime number false
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "hasPrev": true,
    "hasNext": true,
    "items": [
      {
        "symbol": "BTC_USDT",  
        "tradeId": "6316559590087222001",  
        "orderId": "6216559590087220004",  
        "orderSide": "BUY",    
        "orderType": "LIMIT",  
        "bizType": "SPOT",    
        "time": 1655958915583,  
        "price": "40000",     
        "quantity": "1.2",    
        "quoteQty": "48000",   //amount
        "baseCurrency": "BTC",  
        "quoteCurrency": "USDT",  
        "fee": "0.5",   
        "feeCurrency": "USDT", 
        "takerMaker": "taker"  //takerMaker
      }
    ]
  }
}

Get currency information Edit

/v4/public/currencies

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
       "id": 11,                //currency id
      "currency": "usdt",       //currency name
      "fullName": "usdt",       //currency full name
      "logo": null,             //currency logo
      "cmcLink": null,          //cmc link
      "weight": 100,    
      "maxPrecision": 6,  
      "depositStatus": 1,       //Recharge status(0 close 1 open)
      "withdrawStatus": 1,      //Withdrawal status(0 close 1 open)
      "convertEnabled": 1,      //Small asset exchange switch[0=close;1=open]
      "transferEnabled": 1      //swipe switch[0=close;1=open]
    }
  ]
}

Get a single currency asset Edit

/v4/balance

Parameters
Parameter Type mandatory Default Description Ranges
currency string true eg:usdt
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "currency": "usdt",  
    "currencyId": 0,   
    "frozenAmount": 0,  
    "availableAmount": 0,  
    "totalAmount": 0,    
    "convertBtcAmount": 0  //Converted BTC amount
  }
}

Get a list of currency assets Edit

/v4/balances

Parameters
Parameter Type mandatory Default Description Ranges
currencies string false List of currencies, comma separated,eg: usdt,btc
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "totalBtcAmount": 0,
    "assets": [    
      {        
        "currency": "string",
        "currencyId": 0,
        "frozenAmount": 0,
        "availableAmount": 0,
        "totalAmount": 0,
        "convertBtcAmount": 0
      }
    ]
  }
}

Base address Edit

wss://stream.xt.com/public

Request message format Edit

{
    "method": "subscribe", 
    "params": [
        "{topic}@{arg},{arg}", 
        "{topic}@{arg}"
    ], 
    "id": "{id}"    //call back ID
}
{
    "method": "unsubscribe", 
    "params": [
        "{topic}@{arg},{arg}"
    ], 
    "id": "{id}"   //call back ID
}

Response message format Edit

{
    "id": "{id}",   //call back ID
    "code": 1,      //result 0=success;1=fail;2=listenKey invalid
    "msg": ""
}
{"id":"123", "code": 0, "msg": "success"}   
{"id":"123", "code": 401, "msg": "token expire"}

Push message format Edit

{
    "topic": "trade",             
    "event": "trade@btc_usdt",    //title
    "data": { }                   
}
{
    "topic": "trade", 
    "event": "trade@btc_usdt", 
    "data": {
        "s": "btc_usdt", 
        "i": 6316559590087222000, 
        "t": 1655992403617, 
        "p": "43000", 
        "q": "0.21", 
        "b": true
    }
}

Heartbeat Edit

Each link of the client needs to send a ping message periodically, and the server will reply to the pong message. If the server does not receive a ping message from the client within 1 minute, it will actively disconnect the link.

Subscription parameters Edit

format

{topic}@{arg},{arg},…

Transaction record (real-time push) Edit

request

format: trade@{symbol}

eg: trade@btc_usdt

{
    "topic": "trade", 
    "event": "trade@btc_usdt", 
    "data": {
        "s": "btc_usdt",          // symbol
        "i": 6316559590087222000, // trade id
        "t": 1655992403617,       // trade time
        "p": "43000",             // trade price
        "q": "0.21",              // qty,trade quantity
        "b": true                 // buyer
    }
}

K-line according to symbol(real-time push) Edit

request

 

format: kline@{symbol},{interval}

interval: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M

eg: kline@btc_usdt,5m

 

{
    "topic": "kline", 
    "event": "kline@btc_usdt,5m", 
    "data": {
        "s": "btc_usdt",        // symbol
        "t": 1656043200000,     // time
        "i": "5m",              // interval
        "o": "44000",           // open price
        "c": "50000",           // close price
        "h": "52000",           // highest price
        "l": "36000",           // lowest price
        "q": "34.2",            // qty(quantity)
        "v": "230000"           // volume
    }
}

Limited depth (cycle push) Edit

request

 

format: depth@{symbol},{levels}

levels: 5, 10, 20, 50

eg: depth@btc_usdt,20

{
    "topic": "depth", 
    "event": "depth@btc_usdt,20", 
    "data": {
        "s": "btc_usdt",        // symbol
        "t": 1657699200000,     // time
        "a": [                  // asks(sell order)
            [                   //[0]price, [1]quantity
                "34000",        //price
                "1.2"           //quantity 
            ], 
            [
                "34001", 
                "2.3"
            ]
        ], 
        "b": [                   // bids(buy order)
            [
                "32000", 
                "0.2"
            ], 
            [
                "31000", 
                "0.5"
            ]
        ]
    }
}

Incremental depth (push every second) Edit

request

format: depth_update@{symbol}

eg: depth_update@btc_usdt

{
    "topic": "depth_update", 
    "event": "depth_update@btc_usdt", 
    "data": {
        "s": "btc_usdt",        // symbol
        "i": 123,               // updateId
        "a": [                  // asks  sell order
            [                   // [0]price, [1]quantity
                "34000",        //price
                "1.2"           //quantity
            ], 
            [
                "34001", 
                "2.3"
            ]
        ], 
        "b": [                  // bids buy order
            [
                "32000", 
                "0.2"
            ], 
            [
                "31000", 
                "0.5"
            ]
        ]
    }
}

ticker(real-time push) Edit

request

format: ticker@{symbol}

eg: ticker@btc_usdt

{
    "topic": "ticker", 
    "event": "ticker@btc_usdt", 
    "data": {
        "s": "btc_usdt",      // symbol
        "t": 1657586700119,   // time(Last transaction time)
        "cv": "-200",         // priceChangeValue(24 hour price change)
        "cr": "-0.02",        // priceChangeRate 24-hour price change (percentage)
        "o": "30000",         // open price
        "c": "39000",         // close price
        "h": "38000",         // highest price
        "l": "40000",         // lowest price
        "q": "4",             // quantity
        "v": "150000",        // volume
   }
}

All ticker(Push for changes) Edit

request

format: tickers

{
    "topic": "tickers", 
    "event": "tickers", 
    "data": [ ]  // refer to ticker(real-time push)
}

Base address Edit

wss://stream.xt.com/private

Request message format Edit

param format

{topic}@{arg},{arg},…

{
    "method": "subscribe", 
    "params": [
        "{topic}@{arg},{arg}",    //event
        "{topic}@{arg}"
    ], 
    "listenKey": "512312356123123123",   //the listener Key, Apply through  /v4/ws-token interface
    "id": "{id}"
}
{
    "method": "unsubscribe", 
    "params": [
        "{topic}@{arg},{arg}",    //event
        "{topic}@{arg}"
    ], 
    "listenKey": "512312356123123123",   //the listener Key, Apply through /v4/ws-token interface
    "id": "{id}"
}

Response message format Edit

{
    "id": "{id}", //call back ID
    "code": 1,     //result 0=success;1=fail;2=listenKey invalid
    "msg": ""
}

Get token Edit

/v4/ws-token

{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": {
        "accessToken": "eyJhbqGciOiJSUzI1NiJ9.eyJhY2NvdW50SWQiOiIyMTQ2Mjg1MzIyNTU5Iiwic3ViIjoibGh4dDRfMDAwMUBzbmFwbWFpbC5jYyIsInNjb3BlIjoiYXV0aCIsImlzcyI6Inh0LmNvbSIsImxhc3RBdXRoVGltZSI6MTY2MzgxMzY5MDk1NSwic2lnblR5cGUiOiJBSyIsInVzZXJOYW1lIjoibGh4dDRfMDAwMUBzbmFwbWFpbC5jYyIsImV4cCI6MTY2NjQwNTY5MCwiZGV2aWNlIjoidW5rbm93biIsInVzZXJJZCI6MjE0NjI4NTMyMjU1OX0.h3zJlJBQrK2x1HvUxsKivnn6PlSrSDXXXJ7WqHAYSrN2CG5XPTKc4zKnTVoYFbg6fTS0u1fT8wH7wXqcLWXX71vm0YuP8PCvdPAkUIq4-HyzltbPr5uDYd0UByx0FPQtq1exvsQGe7evXQuDXx3SEJXxEqUbq_DNlXPTq_JyScI",
        "refreshToken": "eyJhbGciOiqJSUzI1NiJ9.eyJhY2NvdW50SWQiOiIyMTQ2Mjg1MzIyNTU5Iiwic3ViIjoibGh4dDRfMDAwMUBzbmFwbWFpbC5jYyIsInNjb3BlIjoicmVmcmVzaCIsImlzcyI6Inh0LmNvbSIsImxhc3RBdXRoVGltZSI6MTY2MzgxMzY5MDk1NSwic2lnblR5cGUiOiJBSyIsInVzZXJOYW1lIjoibGh4dDRfMDAwMUBzbmFwbWFpbC5jYyIsImV4cCI6MTY2NjQwNTY5MCwiZGV2aWNlIjoidW5rbm93biIsInVzZXJJZCI6MjE0NjI4NTMyMjU1OX0.Fs3YVm5YrEOzzYOSQYETSmt9iwxUHBovh2u73liv1hLUec683WGfktA_s28gMk4NCpZKFeQWFii623FvdfNoteXR0v1yZ2519uNvNndtuZICDdv3BQ4wzW1wIHZa1skxFfqvsDnGdXpjqu9UFSbtHwxprxeYfnxChNk4ssei430"
    }
}

Push message format Edit

{
    "topic": "trade",          
    "event": "trade@btc_usdt", 
    "data": { }                
}

Change of balance Edit

param

format: balance

eg: balance

{
    "topic": "balance", 
    "event": "balance", 
    "data": {
        "t": 1656043204763,   // time happened time
        "c": "btc",           // currency
        "b": "123",           // balance available balance
        "z": "SPOT"           // bizType [SPOT,LEVER]
    }
}

Change of entrust Edit

param

format: trigger

eg: trigger

{
    "topic": "trigger", 
    "event": "trigger", 
    "data": {
        "s": "btc_usdt",                // symbol
        "t": 1656043204763,             // time happened time
        "i": "6216559590087220004",     // triggerId
        "st": "NEW"                     // state
    }
}

Change of order Edit

param

format: order

eg: order

{
    "topic": "order", 
    "event": "order", 
    "data": {
        "s": "btc_usdt",                // symbol
        "t": 1656043204763,             // time happened time
        "i": "6216559590087220004",     // orderId
        "st": "PARTIALLY_FILLED",       // state
        "eq": "2",                      // executedQty executed quantity
        "ap": "30000"                   // avg price
    }
}

Order filled Edit

param

format: trade

eg: trade

{
    "topic": "trade", 
    "event": "trade", 
    "data": {
        "s": "btc_usdt",                // symbol
        "t": 1656043204763,             //time 
        "i": "6316559590087251233",     // tradeId
        "oi": "6216559590087220004",    // orderId
        "p": "30000",                   // trade price
        "q": "3",                       // qty quantity
        "v": "90000"                    //volumn trade amount
    }
}

REST API Edit

生产环境: https://sapi.xt.com

接口的基本信息 Edit

鉴于延迟高和稳定性差等原因,不建议通过代理的方式访问API。

GET请求参数放入query Params中,POST请求参数放入request body中

请求头信息请设置为:Content-Type=application/json

对于/public以外开头的请求,需要对请求报文进行签名

限频规则 Edit

部分接口会有限流控制(对应接口下会有限流说明),限流主要分为网关限流和WAF限流。

若接口请求触发了网关限流则会返回429,表示警告访问频次超限,即将被封IP或者apiKey。

网关限流分为针对IP和apiKey限流。

IP限流示例说明:100/s/ip,表示每个IP每秒该接口请求次数限制。

apiKey限流示例说明:50/s/apiKey,表示每个apiKey每秒该接口请求次数限制。

签名说明 Edit

由于XT需要为第三方平台提供一些开放性的接口,所以需要接口的数据安全问题,比如数据是否被篡改,数据是否已过时,数据是否可以重复提交,接口在某个时间内访问频率等问题。其中数据是否被篡改是最重要的。

1、先通过用户中心申请appkey和secretkey,针对不同的调用,提供不同的appkey和secretkey

2、加入timestamp(时间戳),其值应当是请求发送时刻的unix时间戳(毫秒),数据的有郊时间根据此值来计算。

3、加入signature(数据签名),所有数据的签名信息。

4、加入recvwindow(自定义请求有效时间),有效时间目前相对简单统一固定为某个值。

服务器收到请求时会判断请求中的时间戳,最长60秒,最小为2秒,如果是5000毫秒之前发出的,则请求会被认为无效。这个时间窗口值可以通过发送可选参数recvWindow来设置。 另外,如果服务器计算得出客户端时间戳在服务器时间的‘未来’一秒以上,也会拒绝请求。 关于交易时效性 互联网状况并不100%可靠,不可完全依赖,因此你的程序本地到XT服务器的时延会有抖动. 这是我们设置recvwindow的目的所在,如果你从事高频交易,对交易时效性有较高的要求,可以灵活设置recvwindow以达到你的要求。

不推荐使用5秒以上的recvwindow

5、加入algorithms (签名方法/算法),用户计算签名是基于哈希的协议,推荐使用HmacSHA256。具体支持那些协议,请参见下面表格中所列出。

HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256(推荐)、HmacSHA384、HmacSHA512

签名生成 Edit

以https://sapi.xt-uat.com/v4/order为例。

以下是在linux bash环境下使用 echo openssl 和curl工具实现的一个调用接口下单的示例 appkey、secret仅供示范:

appKey: 3976eb88-76d0-4f6e-a6b2-a57980770085

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Header部分数据:

xt-validate-algorithms: HmacSHA256

xt-validate-appkey: 3976eb88-76d0-4f6e-a6b2-a57980770085

xt-validate-recvwindow: 5000

xt-validate-timestamp: 1641446237201

xt-validate-signature: 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9

请求数据:

{
  type: 'LIMIT',
  timeInForce: 'GTC',
  side: 'BUY',
  symbol: 'btc_usdt',
  price: '39000',
  quantity: '2'
}

1、数据部分

method: 大写的请求方法,例如:GET、POST、DELETE、PUT

path: 按照path中顺序将所有value进行拼接。形如/test/{var1}/{var2}/的restful路径将按填入的实际参数后路径拼接,示例:/sign/test/bb/aa

query: 按照key的字典序排序,将所有key=value进行拼接。示例:userName=dfdfdf&password=ggg

body:   
    Json: 直接按JSON字符串不做转换或排序操作。

    x-www-form-urlencoded: 按照key的字典序排序,将所有key=value进行拼接,示例:userName=dfdfdf&password=ggg 

    form-data:此格式暂不支持。

如果存在多种数据形式,则按照path、query、body的顺序进行再拼接,得到所有数据的拼接值。

方法method示例:

POST

路径path示例:

/v4/order

上述拼接值记作为path

参数通过query示例:

symbol=btc_usdt

上述值拼接记作query

参数通过body示例

x-www-form-urlencoded:
  
    symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

    上述值拼接记作body

json:

    {"symbol":"btc_usdt","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":2,"price":39000}

    上述值拼接记作body

混合使用query与body(分为表单与json两种格式)

query: 
    symbol=btc_usdt&side=BUY&type=LIMIT
    上述拼接值记作query

body: 
    {"symbol":"btc_usdt","side":BUY,"type":"LIMIT"}
    上述拼接值记作body

整个数据最且拼接值由#符号分别与method、path、query、body进行拼接成#method、#path、#query、#body,最终拼接值记作为Y=#method#path#query#body。 注意:

query有数据,body无数据:Y=#method#path#query

query无数据,body有数据:Y=#method#path#body

query有数据,body有数据:Y=#method#path#query#body

2、请求头部分 将key按照字母自然升序后,使用&方式拼接在一起,作为X。如:

    xt-validate-algorithms=HmacSHA256&xt-validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&xt-validate-recvwindow=5000&xt-validate-timestamp=1641446237201

3、生成签名

最终把需要进行加密的字符串,记作为original=XY

最后将最终拼接值按照如下方法进行加密得到签名。

signature=org.apache.commons.codec.digest.HmacUtils.hmacSha256Hex(secretkey, original);

将生成的签名singature放到请求头中,以xt-validate-signature为Key,以singature为值。

4、样例

签名原始报文样例:

    xt-validate-algorithms=HmacSHA256&xt-validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&xt-validate-recvwindow=60000&xt-validate-timestamp=1666026215729#POST#/v4/order#{"symbol":"XT_USDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":3,"quantity":2}

请求报文样例:
  
    curl --location --request POST 'https://sapi.xt.com/v4/order' 
    --header 'accept: */*' 
    --header 'Content-Type: application/json' 
    --header 'xt-validate-algorithms: HmacSHA256' 
    --header 'xt-validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' 
    --header 'xt-validate-recvwindow: 60000' 
    --header 'xt-validate-timestamp: 1666026215729' 
    --header 'xt-validate-signature: 4cb36e820f50d2e353e5e0a182dc4a955b1c26efcb4b513d81eec31dd36072ba' 
    --data-raw '{"symbol":"XT_USDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":3,"quantity":2}'

注意事项:
    注意检查 Content-Type、签名原始报文中的参数格式、请求报文中的参数格式

API Key申请步骤 Edit

接口可能需要用户的 API Key,如何创建API-KEY请参考这里

API 代码库 Edit

Java connector

一个轻量级的Java代码库,提供让用户直接调用API的方法。

各个语言的sdk:

  java : https://github.com/xt-com/xt4-java-demo
  python : https://github.com/xt-com/xt4-python-demo
  golang : https://github.com/xt-com/xt4-go-demo
  c# : https://github.com/xt-com/xt4-c--demo
  nodejs: https://github.com/xt-com/xt4-nodejs-demo

各个接口的请求信息样例

  https://github.com/xt-com/xt4-request-demo/blob/master/request-xt.txt

响应格式 Edit

所有的接口返回都是JSON格式。

{
    "rc": 0,
    "result": {
      },
    "mc": "SUCCESS"
    "ma": []
}

响应代码 Edit

httpStatus 描述
200 请求成功,请进一步查看rc、mc部分
404 接口不存在
429 请求过于频繁,请按照限速要求,控制请求速率
500 服务异常
502 网关异常
503 服务不可用,请稍后重试
rc return Code
0 业务成功
1 业务失败
mc message code
SUCCESS 成功
FAILURE 失败
AUTH_001 缺少请求头 xt-validate-appkey
AUTH_002 缺少请求头 xt-validate-timestamp
AUTH_003 缺少请求头 xt-validate-recvwindow
AUTH_004 错误的请求头 xt-validate-recvwindow
AUTH_005 缺少请求头 xt-validate-algorithms
AUTH_006 错误的请求头 xt-validate-algorithms
AUTH_007 缺少请求头 xt-validate-signature
AUTH_101 ApiKey不存在
AUTH_102 ApiKey未激活
AUTH_103 签名错误
AUTH_104 非绑定IP请求
AUTH_105 报文过时
AUTH_106 超出apikey权限
SYMBOL_001 交易对不存在
SYMBOL_002 交易对未开盘
SYMBOL_003 交易对暂停交易
SYMBOL_004 此交易对不支持您所在的国家
ORDER_001 平台拒单
ORDER_002 资金不足
ORDER_003 交易对暂停交易
ORDER_004 禁止交易
ORDER_005 订单不存在
ORDER_006 过多的未完成订单
ORDER_F0101 触发价格过滤器-最小值
ORDER_F0102 触发价格过滤器-最大值
ORDER_F0103 触发价格过滤器-步进值
ORDER_F0201 触发数量过滤器-最小值
ORDER_F0202 触发数量过滤器-最大值
ORDER_F0203 触发数量过滤器-步进值
ORDER_F0301 触发金额过滤器-最小值
ORDER_F0401 触发开盘保护滤器
ORDER_F0501 触发限价保护滤器
ORDER_F0601 触发市价保护滤器

获取服务器时间 Edit

/v4/public/time

public String getServerInfo(){


}

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": {
    "serverTime": 1662435658062  //服务器时间
  }
}

获取交易对信息 Edit

/v4/public/symbol

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对 eg:btc_usdt
symbols string false 交易对集合,优先级高于symbol。 eg: btc_usdt,eth_usdt
version string false 版本号,当请求版本号与响应内容版本一致时,不返回清单,减少IO eg: 2e14d2cd5czcb2c2af2c1db65078d075

限流规则

1.获取单个交易对:100/s/ip

2.获取多个交易对:10/s/ip


过滤器

过滤器,即Filter,定义了一系列交易规则。针对不同的领域或者实体有不同的过滤器,这里主要介绍针对symbol这个实体的过滤器。 对于symbol来说,有两种过滤器,一种是全局过滤器,一种是针对某个交易对定制的过滤器。


价格过滤器 PRICE FILTER

价格过滤器 用于检测订单中 price 参数的合法性。包含以下三个部分:

1.min 定义了订单中price允许的最小值

2.max 定义了订单中price允许的最大值

3.tickSize 定义了订单中price的步进间隔,即price必须等于minPrice+(tickSize的整数倍)

以上每一项均可为null,为null时代表这一项不再做限制

逻辑伪代码如下:

  • price >= min
  • price <= max
  • (price-minPrice) % tickSize == 0

数量过滤器  QUANTITY FILTER

其逻辑和PRICE FILTER 类似,不过针对的是订单数量。

其内部包含三个部分

1.min 允许的最小值

2.max 允许的最大值

3.tickSize  步进间隔,即quantity必须等于minQuantity+(tickSize的整数倍)

以上每一项均可为null,为null时代表这一项不再做限制

逻辑伪代码如下:

  • quantity>= min
  • quantity<= max
  • (quantity-minQuantity)% tickSize == 0

金额过滤器 QUOTE_QTY FILTER

对于订单的金额做限制

其内部定义了min允许的最小值

当min为null时,订单不做限制

否则限制规则如下:

1.对于现价LIMIT类型的订单,需满足 price*quantity>=min

2.对于市价MARKET类型并且是购买类型(orderSide=BUY)订单,需满足quoteQty>=min,(quoteQty,市价按金额下单时必填的金额)


开盘保护过滤器 PROTECTION_ONLINE FILTER

对处于开盘之后指定的时间范围内,对于现价类型的订单的价格进行限制

该过滤器内部定义了最大价格倍数(maxPriceMultiple),持续时间(durationSeconds)。

限制逻辑:当处于交易对开盘后durationSeconds时间范围内,订单类型为现价类(LIMIT)的订单

须满足订单价格price<=openPrice*maxPriceMultiple,才会通过(openPrice为开盘价)。

其他类型的订单或者不在开盘时间范围内的订单不做限制。

对于maxPriceMultiple,durationSeconds均可为null,为null时,不做开盘保护限制。


现价保护过滤器 PROTECTION_LIMIT FILTER

对于订单类型(orderType)为LIMIT(现价) 类型的订单具有价格保护限制,包含以下两个部分

1.buyMaxDeviation 买单最大偏离度,限制了买单价格与最新成交价之间的差值

2.sellMaxDeviation 卖单最大偏离度,限制了卖单价格与最新成交价之间的差值

若没有最新成交价则不做限制,或者以上参数为null,则对应方向类型订单不做限制

为了通过限价保护,订单price必须满足以下条件(latestPrice为最新成交价)

买单: price >= latestPrice-latestPrice*buyMaxDeviation 

卖单: price <= latestPrice+latestPrice*sellMaxDeviation


市价保护过滤器 PROTECTION_MARKET FILTER

对于订单类型为MARKET的订单具有价格限制保护机制,其内部规定了maxDeviation最大偏差率。

对于市价类型订单,市场价格须满足以下条件,订单才会通过(sellBestPrice  卖一价格,buyBestPrice 买一价格,latestPrice 最新成交价,这些数据均通过历史成交数据获得)

买单: latestPrice + latestPrice* maxDeviation >= sellBestPrice 

卖单: latestPrice - latestPrice* maxDeviation <= buyBestPrice

对于以上情况maxDeviation,latestPrice,sellBestPrice ,buyBestPrice

均有可能为空或者没有最新成交价,买一价格,卖一价格,则不做限制

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": {
    "time": 1662444177871,                          //时间
    "version": "7cd2cfab0dc979339f1de904bd90c9cb",  //内容版本
    "symbols": [                                    //交易对清单
      {
        "id": 614,                                  //ID
        "symbol": "btc_usdt",                       //交易对
        "state": "ONLINE",                          //交易对状态[ONLINE=上线的;OFFLINE=下线的,DELISTED=退市]
        "tradingEnabled": true,                     //启用交易
        "nextStateTime": null,                      //下一个状态时间
        "nextState": null,                          //下一个状态
        "depthMergePrecision": 5,                   //深度合并精度
        "baseCurrency": "btc",                      //标的资产
        "baseCurrencyPrecision": 5,                 //标的资产精度
        "baseCurrencyId": 2,                        //标的资产ID
        "quoteCurrency": "usdt",                    //报价资产
        "quoteCurrencyPrecision": 6,                //报价资产精度
        "quoteCurrencyId": 11,                      //报价资产ID
        "pricePrecision": 4,                        //交易价格精度
        "quantityPrecision": 6,                     //交易数量精度
        "orderTypes": [                             //订单类型[LIMIT=限价单;MARKET=市价单]
          "LIMIT",
          "MARKET"
        ],
        "timeInForces": [                           //有效方式[GTC=成交为止,一直有效; IOC=无法立即成交(吃单)的部分就撤销; FOK=无法全部立即成交就撤销; GTX=无法成为挂单方就撤销]
          "GTC",
          "FOK",
          "IOC",
          "GTX"
        ],
        "displayWeight": 1,                         //展示权重,越大越靠前
        "displayLevel": "FULL",                     //展示级别,[FULL=完全展示,SEARCH=搜索展示,DIRECT=直达展示,NONE=不展示]
        "plates": [],                               //所属板块  eg:22,23,24
        "filters": [                                //过滤器
          {
            "filter": "PROTECTION_LIMIT",
            "buyMaxDeviation": "0.8"
            "sellMaxDeviation": "0.8"
          },
          {
            "filter": "PROTECTION_MARKET",
            "maxDeviation": "0.1"
          },
          {
            "filter": "PROTECTION_ONLINE",
            "durationSeconds": "300",
            "maxPriceMultiple": "5"
          },
          {
            "filter": "PRICE",
            "min": null,
            "max": null,
            "tickSize": null
          },
          {
            "filter": "QUANTITY",
            "min": null,
            "max": null,
            "tickSize": null
          },
          {
            "filter": "QUOTE_QTY",
            "min": null
          },
       ]
      }
    ]
  }
}            

获取深度数据 Edit

/v4/public/depth

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 交易对 eg:btc_usdt
limit number false 50 数量 1~500

限流规则

200/s/ip

public String depth(){


}

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": {
    "timestamp": 1662445330524,          //时间戳
    "lastUpdateId": 137333589606963580,  //最后更新记录
    "bids": [                            //买盘([?][0]=价位;[?][1]=挂单量)
      [
        "200.0000",                      //价位
        "0.996000"                       //挂单量
      ],
      [
        "100.0000",
        "0.001000"
      ],
      [
        "20.0000",
        "10.000000"
      ]
    ],
    "asks": []                          //卖盘([?][0]=价位;[?][1]=挂单量)
  }
}

获取k线数据 Edit

/v4/public/kline

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 交易对 eg:btc_usdt
interval string true K线类型 ,1m;3m;5m;15m;30m;1h;2h;4h;6h;8h;12h;1d;3d;1w;1M eg:1m [1m;3m;5m;15m;30m;1h;2h;4h;6h;8h;12h;1d;3d;1w;1M]
startTime number false 起始时间戳
endTime number false 结束时间戳
limit number false 100 限制数量 1~1000

限流规则

100/s/ip

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "t": 1662601014832,   //开盘时间(time)
      "o": "30000",         //开盘价(open)
      "c": "32000",         //收盘价(close)
      "h": "35000",         //最高价(high)
      "l": "25000",         //最低价(low)
      "q": "512",           //成交量(quantity)
      "v": "15360000"       //成交额(volume)
    }
  ]
}

查询近期成交列表 Edit

/v4/public/trade/recent

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 交易对
limit number false 200 数量 1,1000

限流规则

100/s/ip

public String tradeRecent(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "i": 0,           //ID
      "t": 0,           //成交时间(time)
      "p": "string",    //成交价(price)
      "q": "string",    //成交量(quantity)
      "v": "string",    //成交额(volume)
      "b": true         //方向(buyerMaker)
    }
  ]
}

查询历史成交列表 Edit

/v4/public/trade/history

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 交易对
limit number false 200 数量 1,1000
fromId number false 起始ID,eg: 6216559590087220004

限流规则

100/s/ip

public String tradeHistory(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "i": 0,           //ID
      "t": 0,           //成交时间(time)
      "p": "string",    //成交价(price)
      "q": "string",    //成交量(quantity)
      "v": "string",    //成交额(volume)
      "b": true         //方向(buyerMaker)
    }
  ]
}

完整ticker Edit

/v4/public/ticker

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对 eg:btc_usdt
symbols array false 交易对集合,优先级高于symbol。 eg: btc_usdt,eth_usdt
tags string false 标签集合,逗号分割,当前仅支持 spot

限流规则

1.单个交易对:100/s/ip

2.多个交易对:10/s/ip

public String price(){


}

{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": [
          {
            "s": "btc_usdt",        //交易对(symbol)
            "t": 1662444879425,     //更新时间(time)
            "cv": "0.00",           //价格变动(change value)
            "cr": "0.0000",         //价格变动百分比(change rate)
            "o": "200.00",          //最早一笔(open)
            "l": "200.00",          //最低(low)
            "h": "200.00",          //最高(high)
            "c": "200.00",          //最后一笔(close)
            "q": "0.002",           //成交量(quantity)
            "v": "0.40",            //成交额(volume)
            "ap": null,             //asks price(卖一价)
            "aq": null,             //asks qty(卖一量)
            "bp": null,             //bids price(买一价)
            "bq": null              //bids qty(买一量)
            }
        ]
}

获取最新价格ticker Edit

/v4/public/ticker/price

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对 eg:btc_usdt
symbols array false 交易对集合,优先级高于symbol。 eg: btc_usdt,eth_usdt
tags string false 标签集合,逗号分割,当前仅支持 spot

限流规则

1.单个交易对:100/s/ip

2.多个交易对:10/s/ip

public String price(){


}

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": [
    {
      "s": "btc_usdt",     //交易对(symbol)
      "t": 1661856036925   //时间(time)
      "p": "9000.0000",    //价格(price)
      }
  ]
}

获取最优挂单ticker Edit

/v4/public/ticker/book

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对 eg:btc_usdt
symbols array false 交易对集合,优先级高于symbol。 eg: btc_usdt,eth_usdt
tags string false 标签集合,逗号分割,当前仅支持 spot

限流规则

1.单个交易对:100/s/ip

2.多个交易对:10/s/ip

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": [
    {
      "s": "btc_usdt",      //交易对(symbol)
      "t": 1661856036925,   //时间(time) 
      "ap": null,           //asks price(卖一价)
      "aq": null,           //asks qty(卖一量)
      "bp": null,           //bids price(买一价)
      "bq": null            //bids qty(买一量)
    }
  ]
}

获取24h统计ticker Edit

/v4/public/ticker/24h

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对 eg:btc_usdt
symbols array false 交易对集合,优先级高于symbol。 eg: btc_usdt,eth_usdt
tags string false 标签集合,逗号分割,当前仅支持 spot

限流规则

1.单个交易对:100/s/ip

2.多个交易对:10/s/ip

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": [
    {
      "s": "btc_usdt",     //交易对(symbol)
      "t": 1661856036925,  //时间(time) 
      "cv": "0.0000",      //价格变动(change value)
      "cr": "0.00",        //价格变动百分比(change rate)
      "o": "9000.0000",    //最早一笔(open)
      "l": "9000.0000",    //最低(low)
      "h": "9000.0000",    //最高(high)
      "c": "9000.0000",    //最后一笔(close)
      "q": "0.0136",       //成交量(quantity)
      "v": "122.9940"      //成交额(volume)
    }
  ]
}

单笔获取 Edit

/v4/order/{orderId}

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderId number true 订单ID
public String orderGet(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "symbol": "BTC_USDT",                   //交易对
    "orderId": "6216559590087220004",       //订单号
    "clientOrderId": "16559590087220001",   //客户端订单号
    "baseCurrency": "string",               //标的币种
    "quoteCurrency": "string",              //报价币种
    "side": "BUY",                          //订单方向 BUY-买,SELL-卖
    "type": "LIMIT",                        //订单类型  LIMIT-现价,MARKET-市价 
    "timeInForce": "GTC",                   //有效方式  GTC,IOC,FOK,GTX
    "price": "40000",                       //价格
    "origQty": "2",                         //原始数量
    "origQuoteQty": "48000",                //原始金额
    "executedQty": "1.2",                   //已执行数量
    "leavingQty": "string",                 //待执行数量(若撤单或下单拒绝,该值为0
    "tradeBase": "2",                       //成交标的(成交数量)
    "tradeQuote": "48000",                  //成交报价(成交金额)
    "avgPrice": "42350",                    //成交均价
    "fee": "string",                        //手续费
    "feeCurrency": "string",                //手续费币种
    "state": "NEW",                         //订单状态 NEW-新建,PARTIALLY_FILLED-部分成交,FILLED-全部成交,CANCELED-用户撤单,REJECTED-下单失败,EXPIRED-过期(time_in_force撤单或溢价撤单)
    "time": 1655958915583,                  //订单时间
    "updatedTime": 1655958915583            //订单更新时间
  }
}

单笔查询 Edit

/v4/order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderId number false 订单ID
clientOrderId string false 客户端订单号
public String orderGet(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "symbol": "BTC_USDT",                   //交易对
    "orderId": "6216559590087220004",       //订单号
    "clientOrderId": "16559590087220001",   //客户端订单号
    "baseCurrency": "string",               //标的币种
    "quoteCurrency": "string",              //报价币种
    "side": "BUY",                          //订单方向 BUY-买,SELL-卖
    "type": "LIMIT",                        //订单类型  LIMIT-现价,MARKET-市价 
    "timeInForce": "GTC",                   //有效方式  GTC,IOC,FOK,GTX
    "price": "40000",                       //价格
    "origQty": "2",                         //原始数量
    "origQuoteQty": "48000",                //原始金额
    "executedQty": "1.2",                   //已执行数量
    "leavingQty": "string",                 //待执行数量(若撤单或下单拒绝,该值为0
    "tradeBase": "2",                       //成交标的(成交数量)
    "tradeQuote": "48000",                  //成交报价(成交金额)
    "avgPrice": "42350",                    //成交均价
    "fee": "string",                        //手续费
    "feeCurrency": "string",                //手续费币种
    "state": "NEW",                         //订单状态 NEW-新建,PARTIALLY_FILLED-部分成交,FILLED-全部成交,CANCELED-用户撤单,REJECTED-下单失败,EXPIRED-过期(time_in_force撤单或溢价撤单)
    "time": 1655958915583,                  //订单时间
    "updatedTime": 1655958915583            //订单更新时间
  }
}

单笔下单 Edit

/v4/order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 交易对
clientOrderId string false 客户端ID正则:^[a-zA-Z0-9_]{4,32}$
side string true 买卖方向  BUY-买,SELL-卖
type string true 订单类型  LIMIT-现价,MARKET-市价 
timeInForce string true 有效方式 GTC, FOK, IOC, GTX
bizType string true 业务类型 SPOT-现货, LEVER-杠杆
price number false 价格。现价必填; 市价不填
quantity number false 数量。现价必填;市价按数量下单时必填
quoteQty number false 金额。现价不填;市价按金额下单时必填

限流规则

50/s/apikey

public String orderPost(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "orderId": "6216559590087220004"   //订单ID
  }
}

单笔撤单 Edit

/v4/order/{orderId}

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderId number true 订单ID
public String orderDel(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "cancelId": "6216559590087220004"
  }
}

批量获取 Edit

/v4/batch-order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderIds string true 订单ID集合,逗号分割 eg: 6216559590087220004,6216559590087220004

reponse 字段信息参考单笔订单获取接口

public String batchOrderGet(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "symbol": "BTC_USDT",
      "orderId": "6216559590087220004",
      "clientOrderId": "16559590087220001",
      "baseCurrency": "string",
      "quoteCurrency": "string",
      "side": "BUY",
      "type": "LIMIT",
      "timeInForce": "GTC",
      "price": "40000",
      "origQty": "2",
      "origQuoteQty": "48000",
      "executedQty": "1.2",
      "leavingQty": "string",
      "tradeBase": "2",
      "tradeQuote": "48000",
      "avgPrice": "42350",
      "fee": "string",
      "feeCurrency": "string",
      "state": "NEW",
      "time": 1655958915583,
      "updatedTime": 1655958915583
    }
  ]
}

批量撤单 Edit

/v4/batch-order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
clientBatchId string false 客户端批次号
orderIds array true 集合[6216559590087220004,6216559590087220005]

注意:参数以json形式放在body中

public String batchOrderDel(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {}
}

查询当前挂单 Edit

/v4/open-order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对,不传代表所有
bizType string false 业务类型 SPOT-现货, LEVER-杠杆
side string false BUY-买,SELL-卖
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [      //字段信息参考单笔订单获取接口
    {
      "symbol": "BTC_USDT",
      "orderId": "6216559590087220004",
      "clientOrderId": "16559590087220001",
      "baseCurrency": "string",
      "quoteCurrency": "string",
      "side": "BUY",
      "type": "LIMIT",
      "timeInForce": "GTC",
      "price": "40000",
      "origQty": "2",
      "origQuoteQty": "48000",
      "executedQty": "1.2",
      "leavingQty": "string",
      "tradeBase": "2",
      "tradeQuote": "48000",
      "avgPrice": "42350",
      "fee": "string",
      "feeCurrency": "string",
      "state": "NEW",
      "time": 1655958915583,
      "updatedTime": 1655958915583
    }
  ]
}

撤销当前挂单 Edit

/v4/open-order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对,不传代表所有
bizType string false 业务类型 SPOT-现货, LEVER-杠杆
side string false BUY-买,SELL-卖

注意:参数以json形式放在body中

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {}
}

历史订单查询 Edit

/v4/history-order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对,不传代表所有
bizType string false 业务类型 SPOT-现货, LEVER-杠杆
side string false BUY-买,SELL-卖
type string false 订单类型 LIMIT-现价, MARKET-市价
state string false 订单状态 NEW-新建,PARTIALLY_FILLED-部分成交,FILLED-全部成交,CANCELED-用户撤单,REJECTED-下单失败,EXPIRED-过期(time_in_force撤单或溢价撤单)
fromId number false 起始ID
direction string false 查询方向:PREV, NEXT
limit number false 20 限制数量,最大100
startTime number false 开始时间 eg:1657682804112
endTime number false 结束时间
hiddenCanceled bool false 隐藏已取消
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "hasPrev": true,
    "hasNext": true,
    "items": [   //内容信息参考单笔获取订单接口
      {
        "symbol": "BTC_USDT",
        "orderId": "6216559590087220004",
        "clientOrderId": "16559590087220001",
        "baseCurrency": "string",
        "quoteCurrency": "string",
        "side": "BUY",
        "type": "LIMIT",
        "timeInForce": "GTC",
        "price": "40000",
        "origQty": "2",
        "origQuoteQty": "48000",
        "executedQty": "1.2",
        "leavingQty": "string",
        "tradeBase": "2",
        "tradeQuote": "48000",
        "avgPrice": "42350",
        "fee": "string",
        "feeCurrency": "string",
        "state": "NEW",
        "time": 1655958915583,
        "updatedTime": 1655958915583
      }
    ]
  }
}

成交查询 Edit

/v4/trade

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对,不传代表所有
bizType string false 业务类型 SPOT-现货, LEVER-杠杆
orderSide string false BUY-买,SELL-卖
orderType string false 订单类型 LIMIT-现价, MARKET-市价
orderId number false 订单号
fromId number false 分页起始ID
direction string false 查询方向:PREV, NEXT
limit number false 20 限制数量,最大100
startTime number false 开始时间 eg:1657682804112
endTime number false 结束时间
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "hasPrev": true,
    "hasNext": true,
    "items": [
      {
        "symbol": "BTC_USDT",               //交易对
        "tradeId": "6316559590087222001",   //成交单号
        "orderId": "6216559590087220004",   //订单号
        "orderSide": "BUY",                 //订单方向
        "orderType": "LIMIT",               //订单类型
        "bizType": "SPOT",                  //业务类型
        "time": 1655958915583,              //成交时间
        "price": "40000",                   //成交价格
        "quantity": "1.2",                  //成交数量
        "quoteQty": "48000",                //成交金额
        "baseCurrency": "BTC",              //标的币种类型
        "quoteCurrency": "USDT",            //报价币种类型
        "fee": "0.5",                       //手续费资产金额
        "feeCurrency": "USDT",              //手续费资产类型
        "takerMaker": "taker"               //takerMaker
      }
    ]
  }
}

获取币种信息 Edit

/v4/public/currencies

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
       "id": 11,            //币种id
      "currency": "usdt",   //币种名称
      "fullName": "usdt",   //币种全称
      "logo": null,         //币种logo
      "cmcLink": null,      //cmc链接
      "weight": 100,        //权重
      "maxPrecision": 6,    //精度
      "depositStatus": 1,   //充值状态(0关闭 1开放)
      "withdrawStatus": 1,  //提现状态(0关闭 1开放)
      "convertEnabled": 1,  //小额资产兑换开关[0=关;1=开]
      "transferEnabled": 1  //划转开关[0=关;1=开]
    }
  ]
}

获取单个币种资产 Edit

/v4/balance

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
currency string true eg:usdt
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "currency": "usdt",     //币种
    "currencyId": 0,        //币种ID
    "frozenAmount": 0,      //冻结数量
    "availableAmount": 0,   //可用数量
    "totalAmount": 0,       //总数量
    "convertBtcAmount": 0   //折算BTC数量
  }
}

获取币种资产列表 Edit

/v4/balances

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
currencies string false 币种列表,逗号分隔,eg: usdt,btc
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "totalBtcAmount": 0,
    "assets": [    //参数内容参考获取单个币种资产接口
      {        
        "currency": "string",
        "currencyId": 0,
        "frozenAmount": 0,
        "availableAmount": 0,
        "totalAmount": 0,
        "convertBtcAmount": 0
      }
    ]
  }
}

基地址 Edit

wss://stream.xt.com/public

请求报文格式 Edit

{
    "method": "subscribe", 
    "params": [
        "{topic}@{arg},{arg}", 
        "{topic}@{arg}"
    ], 
    "id": "{id}"    //回调ID
}
{
    "method": "unsubscribe", 
    "params": [
        "{topic}@{arg},{arg}"
    ], 
    "id": "{id}"   //回调ID
}

响应报文格式 Edit

{
    "id": "{id}",   //请求回调ID
    "code": 1,      //结果0=成功;1=失败;2=listenKey⽆效
    "msg": ""
}
{"id":"123", "code": 0, "msg": "success"}   
{"id":"123", "code": 401, "msg": "token expire"}

推送报文格式 Edit

{
    "topic": "trade",             //事件
    "event": "trade@btc_usdt",    //主题
    "data": { }                   //数据
}
{
    "topic": "trade", 
    "event": "trade@btc_usdt", 
    "data": {
        "s": "btc_usdt", 
        "i": 6316559590087222000, 
        "t": 1655992403617, 
        "p": "43000", 
        "q": "0.21", 
        "b": true
    }
}

心跳 Edit

客户端每个链接需要定期发送ping消息,服务端会回复pong的消息,服务端在1分钟内没有收到客户端的ping消息,会主动断开链接

订阅参数 Edit

结构

{topic}@{arg},{arg},…

成交记录(实时推) Edit

请求

语法: trade@{symbol}

示例: trade@btc_usdt

{
    "topic": "trade", 
    "event": "trade@btc_usdt", 
    "data": {
        "s": "btc_usdt",          // symbol,交易对
        "i": 6316559590087222000, // 成交ID
        "t": 1655992403617,       // time,成交时间
        "p": "43000",             // price,成交价格
        "q": "0.21",              // qty,成交数量
        "b": true                 // buyer
    }
}

按symbol的K线(实时推) Edit

请求

 

语法: kline@{symbol},{interval}

interval: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M

示例: kline@btc_usdt,5m

 

{
        "topic": "kline",
        "event": "kline@btc_usdt,5m",
            "data": {
            "s": "btc_usdt",       // symbol 交易对
            "t": 1656043200000,    // time 时间
            "i": "5m",             // interval 间隔
            "o": "44000",          // open 开盘价
            "c": "50000",          // close 收盘价
            "h": "52000",          // high 最⾼价
            "l": "36000",          // low 最低价
            "q": "34.2",           // qty 成交量
            "v": "230000"          // volume 成交额
            }
}

有限深度(周期推) Edit

请求

 

语法: depth@{symbol},{levels}

levels: 5, 10, 20, 50

示例: depth@btc_usdt,20

{
    "topic": "depth", 
    "event": "depth@btc_usdt,20", 
    "data": {
        "s": "btc_usdt",        // symbol 交易对
        "t": 1657699200000,     // time 时间戳
        "a": [                  // asks 卖盘
            [                   //[0]价格, [1]数量
                "34000",        //价格
                "1.2"           //数量 
            ], 
            [
                "34001", 
                "2.3"
            ]
        ], 
        "b": [                   // bids 买盘
            [
                "32000", 
                "0.2"
            ], 
            [
                "31000", 
                "0.5"
            ]
        ]
    }
}

增量深度(1秒推一次) Edit

请求

语法: depth_update@{symbol}

示例: depth_update@btc_usdt

{
    "topic": "depth_update", 
    "event": "depth_update@btc_usdt", 
    "data": {
        "s": "btc_usdt",        // symbol 交易对
        "i": 123,               // updateId
        "a": [                  // asks 卖盘
            [                   // [0]价格, [1]数量
                "34000",        //价格
                "1.2"           //数量
            ], 
            [
                "34001", 
                "2.3"
            ]
        ], 
        "b": [                  // bids 买盘
            [
                "32000", 
                "0.2"
            ], 
            [
                "31000", 
                "0.5"
            ]
        ]
    }
}

ticker(实时推) Edit

请求

语法: ticker@{symbol}

示例: ticker@btc_usdt

{
    "topic": "ticker", 
    "event": "ticker@btc_usdt", 
    "data": {
        "s": "btc_usdt",      // symbol 交易对
        "t": 1657586700119,   // time 最后成交时间
        "cv": "-200",         // priceChangeValue 24⼩时价格变化
        "cr": "-0.02",        // priceChangeRate 24⼩时价格变化(百分⽐)
        "o": "30000",         // open 第⼀笔
        "c": "39000",         // close 最后⼀笔
        "h": "38000",         // high 最⾼价
        "l": "40000",         // low 最低价
        "q": "4",             // quantity 成交量
        "v": "150000",        // volume 成交额
    }
}

所有ticker(有变化才推) Edit

请求

语法: tickers

{
    "topic": "tickers", 
    "event": "tickers", 
    "data": [ ]  //  ticker
}

基地址 Edit

wss://stream.xt.com/private

请求报文格式 Edit

param结构

{topic}@{arg},{arg},…

{
    "method": "subscribe", 
    "params": [
        "{topic}@{arg},{arg}",    //event
        "{topic}@{arg}"
    ], 
    "listenKey": "512312356123123123",   //监听Key,先通过/v4/ws-token接⼝申请
    "id": "{id}"
}
{
    "method": "unsubscribe", 
    "params": [
        "{topic}@{arg},{arg}",    //event
        "{topic}@{arg}"
    ], 
    "listenKey": "512312356123123123",   //监听Key,先通过/v4/ws-token接⼝申请
    "id": "{id}"
}

响应报⽂格式 Edit

{
    "id": "{id}",   //请求回调ID
    "code": 1,      //结果1=成功;0=失败;2=listenKey⽆效
    "msg": ""
}

获取token接口 Edit

/v4/ws-token

{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": {
        "accessToken": "eyJhbqGciOiJSUzI1NiJ9.eyJhY2NvdW50SWQiOiIyMTQ2Mjg1MzIyNTU5Iiwic3ViIjoibGh4dDRfMDAwMUBzbmFwbWFpbC5jYyIsInNjb3BlIjoiYXV0aCIsImlzcyI6Inh0LmNvbSIsImxhc3RBdXRoVGltZSI6MTY2MzgxMzY5MDk1NSwic2lnblR5cGUiOiJBSyIsInVzZXJOYW1lIjoibGh4dDRfMDAwMUBzbmFwbWFpbC5jYyIsImV4cCI6MTY2NjQwNTY5MCwiZGV2aWNlIjoidW5rbm93biIsInVzZXJJZCI6MjE0NjI4NTMyMjU1OX0.h3zJlJBQrK2x1HvUxsKivnn6PlSrSDXXXJ7WqHAYSrN2CG5XPTKc4zKnTVoYFbg6fTS0u1fT8wH7wXqcLWXX71vm0YuP8PCvdPAkUIq4-HyzltbPr5uDYd0UByx0FPQtq1exvsQGe7evXQuDXx3SEJXxEqUbq_DNlXPTq_JyScI",
        "refreshToken": "eyJhbGciOiqJSUzI1NiJ9.eyJhY2NvdW50SWQiOiIyMTQ2Mjg1MzIyNTU5Iiwic3ViIjoibGh4dDRfMDAwMUBzbmFwbWFpbC5jYyIsInNjb3BlIjoicmVmcmVzaCIsImlzcyI6Inh0LmNvbSIsImxhc3RBdXRoVGltZSI6MTY2MzgxMzY5MDk1NSwic2lnblR5cGUiOiJBSyIsInVzZXJOYW1lIjoibGh4dDRfMDAwMUBzbmFwbWFpbC5jYyIsImV4cCI6MTY2NjQwNTY5MCwiZGV2aWNlIjoidW5rbm93biIsInVzZXJJZCI6MjE0NjI4NTMyMjU1OX0.Fs3YVm5YrEOzzYOSQYETSmt9iwxUHBovh2u73liv1hLUec683WGfktA_s28gMk4NCpZKFeQWFii623FvdfNoteXR0v1yZ2519uNvNndtuZICDdv3BQ4wzW1wIHZa1skxFfqvsDnGdXpjqu9UFSbtHwxprxeYfnxChNk4ssei430"
    }
}

推送报⽂格式 Edit

{
    "topic": "trade",          //主题
    "event": "trade@btc_usdt", //事件
    "data": { }                //数据
}

余额变动 Edit

param

语法: balance

示例: balance

{
    "topic": "balance", 
    "event": "balance", 
    "data": {
        "t": 1656043204763,   // time 发⽣时间
        "c": "btc",           // currency 币种
        "b": "123",           // balance 可⽤资产
        "z": "SPOT"           // bizType 业务类型[SPOT,LEVER]
    }
}

委托变动 Edit

param

语法: trigger

示例: trigger

{
    "topic": "trigger", 
    "event": "trigger", 
    "data": {
        "s": "btc_usdt",                // symbol 交易对
        "t": 1656043204763,             // time 发⽣时间
        "i": "6216559590087220004",     // triggerId 订单号
        "st": "NEW"                     // state 状态
    }
}

订单变动 Edit

param

语法: order

示例: order

{
    "topic": "order", 
    "event": "order", 
    "data": {
        "s": "btc_usdt",                // symbol 交易对
        "t": 1656043204763,             // time 发⽣时间
        "i": "6216559590087220004",     // orderId 订单号
        "st": "PARTIALLY_FILLED",       // state 状态
        "eq": "2",                      // executedQty 已执⾏数量
        "ap": "30000"                   // avg price 均价
    }
}

订单成交 Edit

param

语法: trade

示例: trade

{
    "topic": "trade", 
    "event": "trade", 
    "data": {
        "s": "btc_usdt",                // symbol 交易对
        "t": 1656043204763,             // time 发⽣时间
        "i": "6316559590087251233",     // tradeId 订单号
        "oi": "6216559590087220004",    // orderId 订单号
        "p": "30000",                   // price 成交价
        "q": "3",                       // qty 成交量
        "v": "90000"                    // quoteQty 成交量
    }
}