XT DOC logo

简体中文
english
Index Spot Futures Margin Spot Copy Trading Futures Copy Trading Third Party User Center
首页 现货 合约 杠杆 现货跟单 合约跟单 第三方平台 用户中心

Overview Edit

Welcome to XT API documentation. XT provides REST and Websocket APIs to suit your trading needs.

API Resources and Support Edit

Tutorials

Learn python spot trading step by step: Python Spot Trading Tutorial
Learn python derivatives trading step by step: Python Derivatives Trading Tutorial

Python libraries

Use Python SDK for easier integration: Python SDK

Java libraries

A lightweight Java code library: Java SDK

JavaScript SDK

This JavaScript SDK provides access to various endpoints for interacting with the XT platform: JavaScript SDK

Customer service

Get support in our telegram group: XT API Support Group
If you have any questions, please consult online customer service

概述 Edit

欢迎使用 XT API 文档。 XT 提供 REST 和 Websocket API 来满足您的交易需求。

API 资源和支持 Edit

教程

一步步学习Python现货交易: Python现货交易教程
一步步学习Python衍生品交易: Python衍生品交易教程

Python 库

使用Python SDK更容易集成: Python SDK

Java 库

一个轻量级的Java代码库: Java SDK

JavaScript 库

此 JavaScript SDK 提供对各种端点的访问,以便与 XT 平台进行交互: JavaScript SDK

客户服务

在我们的电报组中获取支持: XT API Support Group
如有疑问请咨询在线客服

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,therefore, the issue of data security needs to be considered. Such as whether the data has been tampered with, whether the data is outdated, whether the data can be submitted repeatedly, and the access frequency of the interface, and whether data has been tampered with is the most important issue.

  1. Please apply for appkey and secretkey in the user center first, each user’s appkey and secretkey are different.

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

  3. Add signature, its value is obtained by a certain rule of signature algorithm.

  4. Add recvwindow (defining the valid time of the request), the valid time is currently relatively simple and uniformly fixed at a certain value.

When a request is received by the server, the timestamp in the request is checked to ensure it falls between 2 to 60 seconds. Any request with a timestamp older than 5,000 milliseconds is considered invalid. The time window value can be set using the optional parameter: “recvWindow”. Additionally, if the server determines that the client’s timestamp is more than one second ahead of the server, the request will also be invalid. Online conditions are not always 100% reliable in terms of the timeliness of trades, resulting in varying levels of latency between your local program and the XT server. This is why we provide the “recvWindow” parameter - if you engage in high-frequency trading and require stricter transaction timeliness, you can adjust the “recvWindow” parameter to better meet your needs.

Recvwindow longer than 5 seconds is not recommended.

5、Added algorithm (signature method/algorithm), the user calculates the signature according to the protocol of the hash, 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:

validate-algorithms: HmacSHA256

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

validate-recvwindow: 5000

validate-timestamp: 1641446237201

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:

    validate-algorithms=HmacSHA256&validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-recvwindow=5000&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 validate-signature as the key and singature as the value.

4.example

sample of original signature message:
  
    validate-algorithms=HmacSHA256&validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&validate-recvwindow=60000&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 'validate-algorithms: HmacSHA256' 
    --header 'validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' 
    --header 'validate-recvwindow: 60000' 
    --header 'validate-timestamp: 1666026215729' 
    --header '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
  golang : https://github.com/xt-com/xt4-go-demo
  c# : https://github.com/xt-com/xt4-c--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 validate-appkey
AUTH_002 missing request header validate-timestamp
AUTH_003 missing request header validate-recvwindow
AUTH_004 bad request header validate-recvwindow
AUTH_005 missing request header validate-algorithms
AUTH_006 bad request header validate-algorithms
AUTH_007 missing request header 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
SYMBOL_005 The symbol does not support trading via API
SYMBOL_007 The trading pair does not support order modification
SYMBOL_010 This market does not support your 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_007 The sub-account has no transaction authority
ORDER_008 The order price or quantity precision is abnormal
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 or PROTECTION_LIMIT Filter
ORDER_F0501 Trigger PROTECTION_LIMIT Filter - Buy Max Deviation
ORDER_F0502 Trigger PROTECTION_LIMIT Filter - Sell Max Deviation
ORDER_F0503 Trigger PROTECTION_LIMIT Filter - Buy Limit Coefficient
ORDER_F0504 Trigger PROTECTION_LIMIT Filter - Sell Limit Coefficient
ORDER_F0601 Trigger PROTECTION_MARKET Filter
ORDER_F0704 Liquidation price limit for leveraged limit orders
COMMON_001 The user does not exist
COMMON_002 System busy, please try it later
COMMON_003 Operation failed, please try it later
CURRENCY_001 Information of currency is abnormal
DEPOSIT_001 Deposit is not open
DEPOSIT_002 The current account security level is low, please bind any two security verifications in mobile phone/email/Google Authenticator before deposit
DEPOSIT_003 The format of address is incorrect, please enter again
DEPOSIT_004 The address is already exists, please enter again
DEPOSIT_005 Can not find the address of offline wallet
DEPOSIT_006 No deposit address, please try it later
DEPOSIT_007 Address is being generated, please try it later
DEPOSIT_008 Deposit is not available
WITHDRAW_001 Withdraw is not open
WITHDRAW_002 The withdrawal address is invalid
WITHDRAW_003 The current account security level is low, please bind any two security verifications in mobile phone/email/Google Authenticator before withdraw
WITHDRAW_004 The withdrawal address is not added
WITHDRAW_005 The withdrawal address cannot be empty
WITHDRAW_006 Memo cannot be empty
WITHDRAW_008 Risk control is triggered, withdraw of this currency is not currently supported
WITHDRAW_009 Withdraw failed, some assets in this withdraw are restricted by T+1 withdraw
WITHDRAW_010 The precision of withdrawal is invalid
WITHDRAW_011 free balance is not enough
WITHDRAW_012 Withdraw failed, your remaining withdrawal limit today is not enough
WITHDRAW_013 Withdraw failed, your remaining withdrawal limit today is not enough, the withdrawal amount can be increased by completing a higher level of real-name authentication
WITHDRAW_014 This withdrawal address cannot be used in the internal transfer function, please cancel the internal transfer function before submitting
WITHDRAW_015 The withdrawal amount is not enough to deduct the handling fee
WITHDRAW_016 This withdrawal address is already exists
WITHDRAW_017 This withdrawal has been processed and cannot be canceled
WITHDRAW_018 Memo must be a number
WITHDRAW_019 Memo is incorrect, please enter again
WITHDRAW_020 Your withdrawal amount has reached the upper limit for today, please try it tomorrow
WITHDRAW_021 Your withdrawal amount has reached the upper limit for today, you can only withdraw up to {0} this time
WITHDRAW_022 Withdrawal amount must be greater than {0}
WITHDRAW_023 Withdrawal amount must be less than {0}
WITHDRAW_024 Withdraw is not supported
WITHDRAW_025 Please create a FIO address in the deposit page
FUND_001 Duplicate request (a bizId can only be requested once)
FUND_002 Insufficient account balance
FUND_003 Transfer operations are not supported (for example, sub-accounts do not support financial transfers)
FUND_004 Unfreeze failed
FUND_005 Transfer prohibited
FUND_014 The transfer-in account id and transfer-out account ID cannot be the same
FUND_015 From and to business types cannot be the same
FUND_016 Leverage transfer, symbol cannot be empty
FUND_017 Parameter error
FUND_018 Invalid freeze record
FUND_019 Freeze users not equal
FUND_020 Freeze currency are not equal
FUND_021 Operation not supported
FUND_022 Freeze record does not exist
FUND_044 The maximum length of the amount is 113 and cannot exceed the limit
SYMBOL_001 Symbol does not exist
TRANSFER_001 Duplicate request (a bizId can only be requested once)
TRANSFER_002 Insufficient account balance
TRANSFER_003 User not registered
TRANSFER_004 The currency is not allowed to be transferred
TRANSFER_005 The user’s currency is not allowed to be transferred
TRANSFER_006 Transfer prohibited
TRANSFER_007 Request timed out
TRANSFER_008 Transferring to a leveraged account is abnormal
TRANSFER_009 Departing from a leveraged account is abnormal
TRANSFER_010 Leverage cleared, transfer prohibited
TRANSFER_011 Leverage with borrowing, transfer prohibited
TRANSFER_012 Currency transfer prohibited
GATEWAY_0001 Trigger risk control
GATEWAY_0002 Trigger risk control
GATEWAY_0003 Trigger risk control
GATEWAY_0004 Trigger risk control

Public module Edit

Order state

State Description
NEW The order has been accepted by the engine.
PARTIALLY_FILLED A part of the order has been filled.
FILLED The order has been completed.
CANCELED The order has been canceled by the user.
REJECTED The order was not accepted by the engine and not processed.
EXPIRED The order has expired (e.g. Order canceled due to timeout or canceled due to premium)

Order type

Type Description
LIMIT Limit price order
MARKET Market price order

Symbol state

State Description
ONLINE The symbol is online
OFFLINE The symbol is offline
DELISTED The symbol has been delisted

Time in force

This sets how long an order will be active before expiration.

TimeInForces Description
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 Only pending orders, the triggering of transaction conditions will be cancelled immediately

Deposit/Withdraw status

Status Description
SUBMIT The withdrawal amount is not frozen.
REVIEW The withdrawal amount has been frozen and is pending review.
AUDITED The withdraw has been reviewed and is ready to on-chaining.
AUDITED_AGAIN Reexamine
PENDING The deposit or withdraw is already on-chaining.
SUCCESS The deposit or withdraw is success.
FAIL The deposit or withdraw failed.
CANCEL The deposit or withdraw has been canceled by the user.

BizType

Status Description
SPOT spot account
LEVER Leverage account
FINANCE Financial account
FUTURES_U USDT-M futures account
FUTURES_C COIN-M futures account

FAQ Edit

1.AUTH_ 105: The server verifies the request header parameters validate-timestamp (validTimeStamp) and validate-recvwindow (recvwindow) The following rules must be followed: dealTimeStamp (server time when the request is processed, in milliseconds) - validTimeStamp < recvwindow, otherwise AUTH_105 will be returned. To avoid this error, validate-timestamp recommends using the time when the request was sent, and it is measured in milliseconds. The validate-recvwindow is set a little larger

Contact us Edit

XT API Telegram Group: XT API Support Group
XT API Ticket: Create API Ticket

  • For any general questions about the API not covered in the documentation.
  • For any MM questions

XT Customer Support: Website and App online customer service

  • For cases such as missing funds, help with 2FA, etc.

Get server time Edit

/v4/public/time

public String getServerInfo(){


}

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

Get client ip Edit

/v4/public/client

public String getClient(){


}

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

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: 2e14d2cd5czcb2c2af2c1db6

Limit Flow Rules

1.single symbol:10/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 four parts:

1.buyMaxDeviation: The maximum deviation of the buy order, determine the minimum buy order price based on this value and the latest transaction price

2.buyPriceLimitCoefficient: The buy limit coefficient, determine the maximum buy order price based on this value and the latest transaction price

3.sellMaxDeviation: The maximum deviation of the sell order, determine the maximum sell order price based on this value and the latest transaction price

4.sellPriceLimitCoefficient: The sell limit coefficient, determine the minimum sell order price based on this value 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  && price <= latestPrice+latestPrice*buyPriceLimitCoefficient

sell order: price <= latestPrice+latestPrice*sellMaxDeviation  && price >= latestPrice-latestPrice*sellPriceLimitCoefficient


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,
        "openapiEnabled": true,      //Openapi transaction is available or not
        "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,
        "takerFeeRate": 0.001,       //Taker fee rate
        "makerFeeRate": 0.002,       //Maker fee rate
        "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 100 minimum number of queries is 100 1~500

Limit Flow Rules

1/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, 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

10/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

10/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         //whether is buyerMaker or not
    }
  ]
}

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
direction string true query direction PREV-previous page,NEXT-next page
fromId number false Start ID,eg: 6216559590087220004

Limit Flow Rules

10/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         //whether is buyerMaker or not
    }
  ]
}

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:10/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:10/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:10/s/ip

2.multiple symbols:10/s/ip

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": [
    {
      "s": "btc_usdt",      //symbol
      "t": 1661856036925,   //last updated 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:10/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
    "deductServices":[{                     //Fee deduction list (if set XT deduction fee and the deduction occurs, use this field to represent the trade fee. Otherwise, use the original fee and feeCurrency fields to represent the trade fee). 
                          "fee":"0.1",     
                          "feeCurrency":"xt"
                      },
                      {   
                          "fee":"0.001",
                          "feeCurrency":"btc"
                      }],
    "time": 1655958915583,                  //order time
    "ip": "127.0.0.1",                      //ip address
    "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
    "deductServices":[{                 //Fee deduction list (if set XT deduction fee and the deduction occurs, use this field to represent the trade fee. Otherwise, use the original fee and feeCurrency fields to represent the trade fee).  
                          "fee":"0.1",     
                          "feeCurrency":"xt"
                      },
                      {   
                          "fee":"0.001",
                          "feeCurrency":"btc"
                      }],
    "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

Remark

Create a BUY order based on market price, quantity must be null, quoteQty required; Create a SELL order based on market price, quoteQty must be null, quantity required.

Limit Flow Rules

50/s/apikey

public String orderPost(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "orderId": "6216559590087220004",
    "ip": "127.0.0.1",                  // ip address
  }
}

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",
      "deductServices":[{   //Fee deduction list (if set XT deduction fee and the deduction occurs, use this field to represent the trade fee. Otherwise, use the original fee and feeCurrency fields to represent the trade fee). 
                            "fee":"0.1",     
                            "feeCurrency":"xt"
                        },
                        {   
                            "fee":"0.001",
                            "feeCurrency":"btc"
                        }],
      "time": 1655958915583,
      "ip": "127.0.0.1",
      "updatedTime": 1655958915583
    }
  ]
}

Update Order(Limit) Edit

/v4/order/{orderId}

Parameters
Parameter Type mandatory Default Description Ranges
orderId number true order ID
price number true Price
quantity number true Quantity

Limit Flow Rules

50/s/apikey

public String orderPost(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "orderId": "6216559590087220004",   //order id
    "modifyId": "407329711723834560"    //modify id
  }
}

Cancell batch order Edit

/v4/batch-order

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

Note: The parameters should be placed in the request 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

Limit Flow Rules

10/s/apikey

{
  "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",
      "deductServices":[{   //Fee deduction list (if set XT deduction fee and the deduction occurs, use this field to represent the trade fee. Otherwise, use the original fee and feeCurrency fields to represent the trade fee). 
                            "fee":"0.1",     
                            "feeCurrency":"xt"
                        },
                        {   
                            "fee":"0.001",
                            "feeCurrency":"btc"
                        }],
      "time": 1655958915583,
      "ip": "127.0.0.1",
      "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 true SPOT, LEVER
side string false BUY,SELL

Limit Flow Rules

10/s/apikey
Note: The parameters should be placed in the request 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 order state,
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

Limit Flow Rules

10/s/apikey

{
  "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",
        "deductServices":[{   //Fee deduction list (if set XT deduction fee and the deduction occurs, use this field to represent the trade fee. Otherwise, use the original fee and feeCurrency fields to represent the trade fee). 
                              "fee":"0.1",     
                              "feeCurrency":"xt"
                          },
                          {   
                              "fee":"0.001",
                              "feeCurrency":"btc"
                          }],
        "time": 1655958915583,
        "ip": "127.0.0.1",
        "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

Limit Flow Rules

10/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "totalBtcAmount": 0,
    "assets": [    
      {        
        "currency": "string",
        "currencyId": 0,
        "frozenAmount": 0,
        "availableAmount": 0,
        "totalAmount": 0,
        "convertBtcAmount": 0
      }
    ]
  }
}

Get information of currencies (available for deposit and withdraw) Edit

/v4/public/wallet/support/currency

Remark

The currency and chain in the response need to be used in other deposit/withdrawal API

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
        "currency": "BTC",                  //currency name
        "supportChains": [
            {
                "chain": "Bitcon",          //supported transfer network
                "depositEnabled": true,     //deposit is supported or not
                "withdrawEnabled": true     //withdraw is supported or not
                "withdrawFeeAmount": 0.2,   //withdraw fee
                "withdrawMinAmount": 10,    //minimum withdrawal amount
                "depositFeeRate": 0.2,      //deposit fee rate
                "contract": "contractaddress" //contract address
            }
        ]           
    },
    {
        "currency": "ETH",                  //currency name
        "supportChains": [
            {
                "chain": "Ethereum",        //supported transfer network
                "depositEnabled": true,     //deposit is supported or not
                "withdrawEnabled": true     //withdraw is supported or not
                "withdrawFeeAmount": 0.2,   //withdraw fee
                "withdrawMinAmount": 10,    //minimum withdrawal amount
                "depositFeeRate": 0.2,       //deposit fee rate
                "contract": "contractaddress" //contract address
            }
        ]
    }
  ]
}

Get the deposit address Edit

/v4/deposit/address

Parameters
Parameter Type mandatory Default Description Ranges
chain string true network for deposit
currency string true currency name
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "address": "0xfa3abfa50eb2006f5be7831658b17aca240d8526",     //wallet address
    "memo": ""
  }
}

Get history records of deposit Edit

/v4/deposit/history

Parameters
Parameter Type mandatory Default Description Ranges
currency string true Currency name, can be obtained from the response of "Get the supported currencies for deposit or withdrawal" API
chain string true Transfer networks, can be obtained from the response of "Get the supported currencies for deposit or withdrawal" API
status string false The status of deposit SUBMIT、REVIEW、AUDITED、PENDING、SUCCESS、FAIL、CANCEL
fromId long false Start ID, e.g. 6216559590087220004
direction string false NEXT query direction query direction:PREV, NEXT
limit int false 10 Limit number, max 200 1<=limit<=200
startTime long false Start time used for filtering deposit list, timestamp in milliseconds
endTime long false End time used for filtering deposit list, timestamp in milliseconds
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "hasPrev": true,            //Is there a previous page
    "hasNext": true,            //Is there a next page
    "items": [
      {
         "id": 169669597,       //Unique ID of the deposit record
         "currency": "xlm2",    //Currency name
         "chain": "XLM",        //Transfer Network
         "memo": "441824256",   //memo
         "status": "SUCCESS",   //The status of deposit
         "amount": "0.1",       //Deposit amount
         "confirmations": 12,   //Number of block confirmations
         "transactionId": "28dd15b5c119e00886517f129e5e1f8283f0286b277bcd3cd1f95f7fd4a1f7fc",   //Unique ID of transaction
         "address": "GBY6UIYEYLAAXRQXVO7X5I4BSSCS54EAHTUILXWMW6ONPM3PNEA3LWEC",     //Target address of deposit
         "fromAddr": "GBTISB3JK65DG6LEEYYFW33RMMDHBQ65AEUPE5VDBTCLYYFS533FTG6Q",    //From address of deposit
         "createdTime": 1667260957000   //Time of deposit record in millisecondstime
      }
    ]
  }
}

Withdraw Edit

/v4/withdraw

Parameters
Parameter Type mandatory Default Description Ranges
currency string true Currency name, which can be obtained from the 'Get the supported currencies for deposit or withdrawal' interface
chain string true The name of the transfer network, which can be obtained from the interface of 'Get the supported currencies for deposit or withdrawal' interface
amount number true Withdrawal amount, including handling fee
address string true Withdrawal address
memo String false memo,For EOS similar chains that require memo must be transferred

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

Limit Flow Rules

1/s/apikey

{
    "currency":"zb",
    "chain":"Ethereum",
    "amount":1000,
    "address":"0xfa3abfa50eb2006f5be7831658b17aca240d8526",
    "memo":""
}
{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": {      
        "id": 100    //Long  Withdrawal record id, used for querying withdrawal history later
    }
}

Withdrawal history Edit

/v4/withdraw/history

Parameters
Parameter Type mandatory Default Description Ranges
currency string true Currency name, which can be obtained from the 'Get the supported currencies for deposit or withdrawal' interface
chain string true The name of the transfer network, which can be obtained from the interface of 'Get the supported currencies for deposit or withdrawal' interface
status string false The status of the withdrawal record, string type,Refer to public module-Deposit/withdrawal status SUBMIT、REVIEW、AUDITED、AUDITED_AGAIN、PENDING、SUCCESS、FAIL、CANCEL
fromId Long false The Id of the last pagination, that is, the primary key id of the record
direction String false NEXT Page direction NEXT:next page,PREV:previous page
limit int false 10 Number of records per page, maximum 200 1<=limit<=200
startTime Long false Query range start boundary, timestamp in milliseconds
endTime Long false Query range end boundary, timestamp in milliseconds
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
        "hasPrev": true,                      //Is there a previous page                              
        "hasNext": true,                      //Is there a next page                              
        "items": [
            {
                "id": 763111,                 //Withdrawal record id 
                "currency": "usdt",           //currency name 
                "chain": "Ethereum",          //Withdraw network 
                "address": "0xfa3abf",        //Withdrawal target address 
                "memo": "",
                "status": "REVIEW",           //Refer to public module-Deposit/withdrawal record status
                "amount": "30",               //Withdrawal Amount
                "fee": "0",                   //Withdrawal fee
                "confirmations": 0,           //number of block confirmations
                "transactionId": "",          //transaction hash
                "createdTime": 1667763470000  //Withdrawal application time, timestamp in milliseconds
            },
            {
                "id": 763107,
                "currency": "usdt",
                "chain": "Tron",
                "address": "TYnJJw",
                "memo": "",
                "status": "REVIEW",
                "amount": "50",
                "fee": "1",
                "confirmations": 0,
                "transactionId": "",
                "createdTime": 1667428286000
            }
        ]
  }
}

Transfer between user business systems Edit

/v4/balance/transfer

Parameters
Parameter Type mandatory Default Description Ranges
bizId string true Unique id for idempotent processing Maximum length is 128
from enum true Fund transfer out account bizType enmu
to enum true Fund transfer in account bizType enum
currency string true Currency name must be all lowercase (usdt,btc)
symbol string false The transfer symbol must be all lowercase (this field must be passed if one of the transfer-in and transfer-out parties is leverage)
amount bigDecimal true Transfer amount
public String transferPost(){


}

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": 123456 //The returned unique id of the transfer, it is recommended to store it for reconciliation
}

Transfer between sub-account business systems Edit

/v4/balance/account/transfer

Parameters
Parameter Type mandatory Default Description Ranges
bizId string true Unique id for idempotent processing Maximum length is 128
from enum true Fund transfer out account bizType enmu
to enum true Fund transfer in account bizType enum
currency string true Currency name must be all lowercase (usdt,btc)
symbol string false The transfer symbol must be all lowercase (this field must be passed if one of the transfer-in and transfer-out parties is leverage)
amount bigDecimal true Transfer amount
toAccountId long true Transfer-in account id (must belong to the same user as the transfer-out account ID)
fromAccountId long false Transfer-out account id
public String accountTransferPost(){


}

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": 123456 //The returned unique id of the transfer, it is recommended to store it for reconciliation
}

General WSS information Edit

Base Address

wss://stream.xt.com/public

Request Headers

The request header of the compression extension protocol must be added.

Sec-Websocket-Extensions:permessage-deflate

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",           //symbol
        "i": 6316559590087222000,  //tradeId
        "t": 1655992403617,        //time
        "oi": 6616559590087222666, //orderId
        "p": "43000",              //price
        "q": "0.21",               //quantity
        "v": "9030"                //quoteQty
        "b": true                  //whether is buyerMaker or not
    }
}

Heartbeat Edit

Each link of the client needs to send a text “ping” periodically, and the server will reply to the text “pong”. 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},…

Orderbook manage Edit

How to manage a local order book correctly

1.Open a stream to wss://stream.xt.com/public , depth_update@btc_usdt

2.Buffer the events you receive from the stream.

3.Get a depth snapshot from https://sapi.xt.com/v4/public/depth?symbol=btc_usdt&limit=500

4.Drop any event where i is <= lastUpdateId in the snapshot.

5.The first processed event should have fi <= lastUpdateId+1 AND i >= lastUpdateId+1.

6.While listening to the stream, each new event’s fi should be equal to the previous event’s i+1.

7.The data in each event is the absolute quantity for a price level.

8.If the quantity is 0, remove the price level.

9.Receiving an event that removes a price level that is not in your local order book can happen and is normal.

Note: Due to depth snapshots having a limit on the number of price levels, a price level outside of the initial snapshot that doesn’t have a quantity change won’t have an update in the Diff. Depth Stream. Consequently, those price levels will not be visible in the local order book even when applying all updates from the Diff. Depth Stream correctly and cause the local order book to have some slight differences with the real order book. However, for most use cases the depth limit of 500 is enough to understand the market and trade effectively.

Trade record Edit

request

format: trade@{symbol}

eg: trade@btc_usdt

rate: real

{
    "topic": "trade", 
    "event": "trade@btc_usdt", 
    "data": {
        "s": "btc_usdt",           //symbol
        "i": 6316559590087222000,  //tradeId
        "t": 1655992403617,        //time
        "oi": 6616559590087222666, //orderId
        "p": "43000",              //price
        "q": "0.21",               //quantity
        "v": "9030"                //quoteQty
        "b": true                  //whether is buyerMaker or not
    }
}

K-line 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

rate: 1000ms

 

{
    "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 Edit

request

 

format: depth@{symbol},{levels}

levels: 5, 10, 20, 50

eg: depth@btc_usdt,20

rate: 1000ms

{
    "topic": "depth", 
    "event": "depth@btc_usdt,20", 
    "data": {
        "s": "btc_usdt",        // symbol
        "i": 12345678,          // updateId
        "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 Edit

request

format: depth_update@{symbol}

eg: depth_update@btc_usdt

rate: 100ms

{
    "topic": "depth_update", 
    "event": "depth_update@btc_usdt", 
    "data": {
        "s": "btc_usdt",        // symbol
        "fi": 121,              // firstUpdateId = previous lastUpdateId + 1
        "i": 123,               // lastUpdateId
        "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 Edit

request

format: ticker@{symbol}

eg: ticker@btc_usdt

rate: 1000ms

{
    "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
   }
}

General WSS information Edit

Base Address

wss://stream.xt.com/private

Request Headers

The request header of the compression extension protocol must be added.

Sec-Websocket-Extensions:permessage-deflate

Request message format Edit

param format

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

{
    "method": "subscribe", 
    "params": [
        "{topic}@{arg},{arg}",    //event
        "{topic}@{arg}"
    ], 
    "listenKey": "512312356123123123",   //the listener Key, Apply accessToken through /v4/ws-token interface
    "id": "{id}"
}
{
    "method": "unsubscribe", 
    "params": [
        "{topic}@{arg},{arg}",    //event
        "{topic}@{arg}"
    ], 
    "listenKey": "512312356123123123",   //the listener Key, Apply accessToken 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

Note:

The accessToken is valid for 2 days. Calling the endpoint again will reset the validity period.

accessToken = listenKey

{
    "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": {
        "a": "123",           // accountId                     
        "t": 1656043204763,   // time happened time
        "c": "btc",           // currency
        "b": "123",           // all spot balance
        "f": "11",            // frozen
        "z": "SPOT",           // bizType [SPOT,LEVER]
        "s": "btc_usdt"       // symbol
    }
}

Change of order Edit

param

format: order

eg: order

{
    "topic": "order", 
    "event": "order", 
    "data": {
        "s": "btc_usdt",                // symbol
        "bc": "btc",                    // base currency 
        "qc": "usdt",                   // quotation currency 
        "t": 1656043204763,             // happened time
        "ct": 1656043204663,            // create time
        "i": "6216559590087220004",     // order id,
        "ci": "test123",                // client order id
        "st": "PARTIALLY_FILLED",       // state NEW/PARTIALLY_FILLED/FILLED/CANCELED/REJECTED/EXPIRED
        "sd": "BUY",                    // side BUY/SELL
        "tp": "LIMIT",                  // type LIMIT/MARKET
        "oq":  "4"                      // original quantity
        "oqq":  48000,                  // original quotation quantity 
        "eq": "2",                      // executed quantity
        "lq": "2",                      // remaining quantity
        "p": "4000",                    // price 
        "ap": "30000",                  // avg price
        "f":"0.002"                     // fee 
    }
}

Order filled Edit

param

format: trade

eg: trade

{
    "topic": "trade", 
    "event": "trade", 
    "data": {
        "s": "btc_usdt",           //symbol
        "i": 6316559590087222000,  //tradeId
        "t": 1655992403617,        //time
        "oi": 6616559590087222666, //orderId
        "p": "43000",              //price
        "q": "0.21",               //quantity
        "v": "9030"                //quoteQty
        "b": true                  //whether is buyerMaker or not
    }
}

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部分数据:

validate-algorithms: HmacSHA256

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

validate-recvwindow: 5000

validate-timestamp: 1641446237201

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。如:

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

3、生成签名

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

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

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

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

4、样例

签名原始报文样例:

    validate-algorithms=HmacSHA256&validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&validate-recvwindow=60000&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 'validate-algorithms: HmacSHA256' 
    --header 'validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' 
    --header 'validate-recvwindow: 60000' 
    --header 'validate-timestamp: 1666026215729' 
    --header '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
  golang : https://github.com/xt-com/xt4-go-demo
  c# : https://github.com/xt-com/xt4-c--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 缺少请求头 validate-appkey
AUTH_002 缺少请求头 validate-timestamp
AUTH_003 缺少请求头 validate-recvwindow
AUTH_004 错误的请求头 validate-recvwindow
AUTH_005 缺少请求头 validate-algorithms
AUTH_006 错误的请求头 validate-algorithms
AUTH_007 缺少请求头 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 此交易对不支持您所在的国家
SYMBOL_005 该市场不支持通过API进行交易
SYMBOL_007 该交易对暂不支持改单
SYMBOL_010 该市场不支持您进行交易
ORDER_001 平台拒单
ORDER_002 资金不足
ORDER_003 交易对暂停交易
ORDER_004 禁止交易
ORDER_005 订单不存在
ORDER_006 过多的未完成订单
ORDER_007 子账户暂无交易权限
ORDER_008 当前下单价格或数量精度异常
ORDER_F0101 触发价格过滤器-最小值
ORDER_F0102 触发价格过滤器-最大值
ORDER_F0103 触发价格过滤器-步进值
ORDER_F0201 触发数量过滤器-最小值
ORDER_F0202 触发数量过滤器-最大值
ORDER_F0203 触发数量过滤器-步进值
ORDER_F0301 触发金额过滤器-最小值
ORDER_F0401 触发开盘保护滤器或限价保护过滤器
ORDER_F0501 触发限价保护滤器-买单最大偏离度
ORDER_F0502 触发限价保护滤器-卖单最大偏离度
ORDER_F0503 触发限价保护滤器-买单限制系数
ORDER_F0504 触发限价保护滤器-卖单限制系数
ORDER_F0601 触发市价保护滤器
ORDER_F0704 杠杠限价订单爆仓价格限制
COMMON_001 用户不存在
COMMON_002 系统繁忙,请稍后再试
COMMON_003 操作失败,请稍后再试
CURRENCY_001 币种信息异常
DEPOSIT_001 充值暂未开放
DEPOSIT_002 当前账号安全等级较低,请绑定手机/邮箱/谷歌身份验证器中的任意两种安全验证后再进行充值
DEPOSIT_003 地址格式不正确,请重新输入
DEPOSIT_004 地址已存在,请重新输入
DEPOSIT_005 冷钱包地址未找到
DEPOSIT_006 暂无充值地址,请稍后再试
DEPOSIT_007 地址生成中,请稍后再试
DEPOSIT_008 不支持充值
WITHDRAW_001 提现暂未开放
WITHDRAW_002 提币地址不合法
WITHDRAW_003 当前账号安全等级较低,请绑定手机/邮箱/谷歌身份验证器中的任意两种安全验证后再进行提现
WITHDRAW_004 未添加提币地址
WITHDRAW_005 提币地址不能为空
WITHDRAW_006 Memo不能为空
WITHDRAW_008 触发风控,暂不支持该币提现
WITHDRAW_009 提现失败,本次提现中部分资产受T+1提币限制
WITHDRAW_010 提币精度不合法
WITHDRAW_011 可用余额不足
WITHDRAW_012 提现失败,您今日剩余提现额度不足
WITHDRAW_013 提现失败,您今日剩余提现额度不足,可通过完成更高等级的实名认证提高额度
WITHDRAW_014 该笔提现地址不能使用内部转账功能,请取消内部转账功能后再提交
WITHDRAW_015 提现金额不足以抵扣手续费
WITHDRAW_016 提币地址已经存在
WITHDRAW_017 本次提币已处理,无法取消
WITHDRAW_018 Memo必须为数字
WITHDRAW_019 Memo不正确,请重新输入
WITHDRAW_020 您今日提现额度已达上限,请明天再试
WITHDRAW_021 您今日提现额度已达上限,本次最多只能提现{0}
WITHDRAW_022 提现金额必须大于{0}
WITHDRAW_023 提现金额必须小于{0}
WITHDRAW_024 不支持提现
WITHDRAW_025 请前往充值页面创建FIO地址
FUND_001 请求重复(一个bizId请求多次接口)
FUND_002 余额不足
FUND_003 划转操作不支持 (比如子账户不支持理财划入划出)
FUND_004 解冻失败
FUND_005 划转禁止
FUND_014 划入账户id和划出账户id不可以一样
FUND_015 from和to 业务类型不可相同(用户不可以操作自己现货划转到现货)
FUND_016 杠杆交易对不可为空
FUND_017 参数错误
FUND_018 冻结记录无效
FUND_019 解冻用户不相等
FUND_020 解冻币种不相等
FUND_021 操作不支持
FUND_022 冻结记录不存在
FUND_044 金额最大长度为113 不可超过限制
SYMBOL_001 交易对不存在
TRANSFER_001 请求重复(一个bizId请求多次接口)
TRANSFER_002 余额不足
TRANSFER_003 用户未注册
TRANSFER_004 币种不允许划转
TRANSFER_005 用户币种不允许划转
TRANSFER_006 划转禁止
TRANSFER_007 请求超时
TRANSFER_008 杠杆划入异常
TRANSFER_009 杠杆划出异常
TRANSFER_010 杠杆清零 划出禁止
TRANSFER_011 杠杆有借贷 划出禁止
TRANSFER_012 币种划转禁止
GATEWAY_0001 触发风控
GATEWAY_0002 触发风控
GATEWAY_0003 触发风控
GATEWAY_0004 触发风控

公共模块 Edit

订单状态码及含义

State 说明
NEW 新建
PARTIALLY_FILLED 部分成交
FILLED 全部成交
CANCELED 用户撤单
REJECTED 下单失败
EXPIRED 过期(time_in_force撤单或溢价撤单)

订单类型及含义

Type 说明
LIMIT 限价单
MARKET 市价单

交易对状态及含义

State 说明
ONLINE 上线的
OFFLINE 下线的
DELISTED 退市的

有效方式及含义

这里定义了订单多久能够失效

TimeInForces 说明
GTC 成交为止,一直有效
IOC 无法立即成交(吃单)的部分就撤销
FOK 无法全部立即成交就撤销
GTX 只挂单,触发成交条件会被立即撤销

充值/提现记录状态码及含义

Status 说明
SUBMIT 提现: 未冻结
REVIEW 提现: 已冻结,待审核
AUDITED 提现: 已审核,发送钱包,待上链
AUDITED_AGAIN 复审中
PENDING 充值/提现: 已上链
SUCCESS 完成
FAIL 失败
CANCEL 已取消

BizType

Status Description
SPOT 现货
LEVER 杠杠
FINANCE 理财
FUTURES_U 合约u本位
FUTURES_C 合约币本位

FAQ Edit

1.AUTH_105:服务器在校验请求头参数validate-timestamp(validTimeStamp)、validate-recvwindow(recvwindow)时, 需要符合以下规则:dealTimeStamp(请求被处理时服务器时间,单位毫秒)- validTimeStamp < recvwindow ,否则就会返回AUTH_105,为了避免此错误,建议validate-timestamp 设置为请求发出的时间,以毫秒为单位,validate-recvwindow设置的大一点

联系我们 Edit

XT API电报群: XT API Support Group
XT API工单: Create API Ticket

  • 咨询文档中没有提及的API问题
  • 咨询API或者Websocket性能方面的问题
  • 咨询做市相关的问题

XT 客服:官网、App中在线客服

  • 咨询关于钱包、短信、2FA等问题

获取服务器时间 Edit

/v4/public/time

public String getServerInfo(){


}

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

获取客户端IP Edit

/v4/public/client

public String getClient(){


}

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

获取交易对信息 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.获取单个交易对:10/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.buyPriceLimitCoefficient: 买单限制系数,根据该值和最新成交价确定买单价格最大值

3.sellMaxDeviation: 卖单最大偏离度,根据该值和最新成交价确定卖单价格最大值

4.sellPriceLimitCoefficient: 卖单限制系数,根据该值和最新成交价确定卖单价格最小值

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

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

买单: price >= latestPrice-latestPrice*buyMaxDeviation  && price <= latestPrice+latestPrice*buyPriceLimitCoefficient

卖单: price <= latestPrice+latestPrice*sellMaxDeviation  && price >= latestPrice-latestPrice*sellPriceLimitCoefficient


市价保护过滤器 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,                     //启用交易
        "openapiEnabled": true,                     //启用OPENAPI
        "nextStateTime": null,                      //下一个状态时间
        "nextState": null,                          //下一个状态
        "depthMergePrecision": 5,                   //深度合并精度
        "baseCurrency": "btc",                      //标的资产
        "baseCurrencyPrecision": 5,                 //标的资产精度
        "baseCurrencyId": 2,                        //标的资产ID
        "quoteCurrency": "usdt",                    //报价资产
        "quoteCurrencyPrecision": 6,                //报价资产精度
        "quoteCurrencyId": 11,                      //报价资产ID
        "pricePrecision": 4,                        //交易价格精度
        "quantityPrecision": 6,                     //交易数量精度
        "takerFeeRate": 0.001,                      //吃单手续费率
        "makerFeeRate": 0.002,                      //挂单手续费率
        "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 100 数量,最小查询100条 1~500

限流规则

1/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

限流规则

10/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

限流规则

10/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
direction string true 查询方向 PREV-上一页,NEXT-下一页
fromId number false 起始ID,eg: 6216559590087220004

限流规则

10/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.单个交易对:10/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.单个交易对:10/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.单个交易对:10/s/ip

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

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": [
    {
      "s": "btc_usdt",      //交易对(symbol)
      "t": 1661856036925,   //最后更新时间(last updated 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.单个交易对:10/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撤单或溢价撤单)
    "deductServices":[{                     //手续费抵扣列表(如果设置手续费抵扣并产生抵扣,使用该字段代表手续费,没有抵扣使用原有fee、feeCurrency字段代表手续费)                         
                          "fee":"0.1",     
                          "feeCurrency":"xt"
                      },
                      {   
                          "fee":"0.001",
                          "feeCurrency":"btc"
                      }],
    "time": 1655958915583,                  //订单时间
    "ip": "127.0.0.1",                      //ip地址
    "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撤单或溢价撤单)
    "deductServices":[{                     //手续费抵扣列表(如果设置手续费抵扣并产生抵扣,使用该字段代表手续费,没有抵扣使用原有fee、feeCurrency字段代表手续费)
                          "fee":"0.1",     
                          "feeCurrency":"xt"
                      },
                      {   
                          "fee":"0.001",
                          "feeCurrency":"btc"
                      }],
    "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 金额。限价不填;市价按金额下单时必填

备注

按照市价创建BUY订单时,quantity为空,quoteQty必填;按照市价创建SELL订单时,quoteQty为空,quantity必填。

限流规则

50/s/apikey

public String orderPost(){


}

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

单笔撤单 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",
      "deductServices":[{   //手续费抵扣列表(如果设置手续费抵扣并产生抵扣,使用该字段代表手续费,没有抵扣使用原有fee、feeCurrency字段代表手续费)
                            "fee":"0.1",     
                            "feeCurrency":"xt"
                        },
                        {   
                            "fee":"0.001",
                            "feeCurrency":"btc"
                        }],
      "time": 1655958915583,
      "ip": "127.0.0.1",
      "updatedTime": 1655958915583
    }
  ]
}

单笔改单(限价) Edit

/v4/order/{orderId}

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderId number true 订单号
price number true 价格
quantity number true 数量

限流规则

50/s/apikey

public String orderPost(){


}

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

批量撤单 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-卖

限流规则

10/s/apikey

{
  "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",
      "deductServices":[{   //手续费抵扣列表(如果设置手续费抵扣并产生抵扣,使用该字段代表手续费,没有抵扣使用原有fee、feeCurrency字段代表手续费)
                            "fee":"0.1",     
                            "feeCurrency":"xt"
                        },
                        {   
                            "fee":"0.001",
                            "feeCurrency":"btc"
                        }],
      "time": 1655958915583,
      "ip": "127.0.0.1",
      "updatedTime": 1655958915583
    }
  ]
}

撤销当前挂单 Edit

/v4/open-order

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

限流规则

10/s/apikey
注意:参数以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 隐藏已取消

限流规则

10/s/apikey

{
  "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",
        "deductServices":[{   //手续费抵扣列表(如果设置手续费抵扣并产生抵扣,使用该字段代表手续费,没有抵扣使用原有fee、feeCurrency字段代表手续费)
                              "fee":"0.1",     
                              "feeCurrency":"xt"
                          },
                          {   
                              "fee":"0.001",
                              "feeCurrency":"btc"
                          }],
        "time": 1655958915583,
        "ip": "127.0.0.1",
        "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

限流规则

10/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "totalBtcAmount": 0,
    "assets": [    //参数内容参考获取单个币种资产接口
      {        
        "currency": "string",
        "currencyId": 0,
        "frozenAmount": 0,
        "availableAmount": 0,
        "totalAmount": 0,
        "convertBtcAmount": 0
      }
    ]
  }
}

获取XT可充提的币种 Edit

/v4/public/wallet/support/currency

备注

currency 、chain 字段需要在后续充值/提现接口中使用

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
        "currency": "BTC",                  //币种
        "supportChains": [
            {
                "chain": "Bitcon",          //支持的转账网络
                "depositEnabled": true,     //是否支持充值,true:支持,false:不支持
                "withdrawEnabled": true,    //是否支持提现,true:支持,false:不支持
                "withdrawFeeAmount": 0.2,   //提现手续费
                "withdrawMinAmount": 10,    //最小提现数量
                "depositFeeRate": 0.2,      //充值费率,百分比
                "contract": "contractaddress" //合约地址
            }
        ]           
    },
    {
        "currency": "ETF",                  //币种
        "supportChains": [
            {
                "chain": "Ethereum",        //支持的转账网络
                "depositEnabled": true,     //是否支持充值,true:支持,false:不支持
                "withdrawEnabled": true,    //是否支持提现,true:支持,false:不支持
                "withdrawFeeAmount": 0.2,   //提现手续费
                "withdrawMinAmount": 10,    //最小提现数量
                "depositFeeRate": 0.2,      //充值费率,百分比
                "contract": "contractaddress" //合约地址
            }
        ]
    }
  ]
}

获取充值地址 Edit

/v4/deposit/address

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
chain string true 转账网络名称
currency string true 币种名称
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "address": "0xfa3abfa50eb2006f5be7831658b17aca240d8526",     //钱包地址
    "memo": ""
  }
}

充值历史 Edit

/v4/deposit/history

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
currency string true 币种名称,可从“获取XT可充提的币种”接口中获取
chain string true 转账网络名称,可从“获取XT可充提的币种”接口中获取
status string false 充值记录的状态 SUBMIT、REVIEW、AUDITED、PENDING、SUCCESS、FAIL、CANCEL
fromId long false 上次开始分页的Id,即记录的主键id
direction string false NEXT 分页方向 NEXT:下一页,PREV:上一页
limit int false 10 每页记录数,最大不超过200 1<=limit<=200
startTime long false 查询范围开始边界,毫秒级时间戳
endTime long false 查询范围结束边界,毫秒级时间戳
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "hasPrev": true,            //是否有上一页
    "hasNext": true,            //是否有下一页
    "items": [
      {
         "id": 169669597,       //提现记录id
         "currency": "xlm2",    //币种名称
         "chain": "XLM",        //转账网络名称
         "memo": "441824256",   //memo
         "status": "SUCCESS",   //充值状态
         "amount": "0.1",       //充值金额
         "confirmations": 12,   //区块确认数
         "transactionId": "28dd15b5c119e00886517f129e5e1f8283f0286b277bcd3cd1f95f7fd4a1f7fc",   //交易哈希
         "address": "GBY6UIYEYLAAXRQXVO7X5I4BSSCS54EAHTUILXWMW6ONPM3PNEA3LWEC",     //充值目标地址
         "fromAddr": "GBTISB3JK65DG6LEEYYFW33RMMDHBQ65AEUPE5VDBTCLYYFS533FTG6Q",    //来源地址
         "createdTime": 1667260957000   //充值时间,毫秒级时间戳
      }
    ]
  }
}

提现 Edit

/v4/withdraw

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
currency string true 币种名称,可从'获取XT可充提的币种'接口中获取
chain string true 转账网络名称,可从'获取XT可充提的币种'接口中获取
amount number true 提现金额,包含手续费部分
address string true 提现地址
memo String false memo,对于EOS类似的需要memo的链必传

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

限流规则

1/s/apikey

{
    "currency":"zb",
    "chain":"Ethereum",
    "amount":1000,
    "address":"0xfa3abfa50eb2006f5be7831658b17aca240d8526",
    "memo":""
}
{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": {      
        "id": 100    //Long  提现记录id,用于后期查询提现历史记录
    }
}

提现历史 Edit

/v4/withdraw/history

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
currency string true 币种名称,可从'获取XT可充提的币种'接口中获取
chain string true 转账网络名称,可从'获取XT可充提的币种'接口中获取
status string false 提现记录的状态,字符串类型(含义见公共模块-充值/提现记录状态码及含义) SUBMIT、REVIEW、AUDITED、AUDITED_AGAIN、PENDING、SUCCESS、FAIL、CANCEL
fromId Long false 上次开始分页的Id,即记录的主键id
direction String false NEXT 分页方向 NEXT:下一页,PREV:上一页
limit int false 10 每页记录数,最大不超过200 1<=limit<=200
startTime Long false 查询范围开始边界,毫秒级时间戳
endTime Long false 查询范围结束边界,毫秒级时间戳
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
        "hasPrev": true,                       //是否有上一页
        "hasNext": true,                       //是否有下一页
        "items": [
            {
                "id": 763111,                  //提现记录id
                "currency": "usdt",            //币种名称
                "chain": "Ethereum",           //提现网络
                "address": "0xfa3abfa50eb2",   //提现目标地址
                "memo": "",
                "status": "REVIEW",            //状态,含义见公共模块-充值/提现记录状态码及含义
                "amount": "30",                //提现金额
                "fee": "0",                    //提现手续费
                "confirmations": 0,            //区块确认数
                "transactionId": "",           //交易哈希
                "createdTime": 1667763470000                                
            },
            {
                "id": 763107,
                "currency": "usdt",
                "chain": "Tron",
                "address": "TYnJJwaJKkqVvE2zEfUvFbHgKxVBY5zGq9",
                "memo": "",
                "status": "REVIEW",
                "amount": "50",
                "fee": "1",
                "confirmations": 0,
                "transactionId": "",
                "createdTime": 1667428286000
            }
        ]
  }
}

用户业务系统间划转 Edit

/v4/balance/transfer

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
bizId string true 唯一id 用作重复请求幂等 最大长度为128
from enum true 划出业务账户 bizType 枚举
to enum true 划入业务账户 bizType 枚举
currency string true 币种名称必须全部小写(usdt,btc)
symbol string false 划转交易对必须全部小写(划入划出有一方是杠杆此字段必传)
amount bigDecimal true 划转的数量
public String transferPost(){


}

{
  "rc": 0,
  "mc": "string",
  "ma": [],
  "result": 123456  //返回的划转唯一id 建议存储用来对账
}

子账户业务系统间划转 Edit

/v4/balance/account/transfer

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
bizId string true 唯一id 用作重复请求幂等 最大长度为128
from enum true 划出业务账户 bizType 枚举
to enum true 划入业务账户 bizType 枚举
currency string true 币种名称必须全部小写(usdt,btc)
symbol string false 划转交易对必须全部小写(划入划出有一方是杠杆此字段必传)
amount bigDecimal true 划转的数量
toAccountId long true 划入账户id(必须和划出账户id属于同一个用户否则不支持)
fromAccountId long false 划出账户id
public String accountTransferPost(){


}

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": 123456 //返回的划转唯一id 建议存储用来对账
}

基本信息 Edit

基地址

wss://stream.xt.com/public

Request Headers

请求头必须添加压缩扩展协议。

Sec-Websocket-Extensions:permessage-deflate

请求报文格式 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",           //symbol
        "i": 6316559590087222000,  //成交id
        "t": 1655992403617,        //时间
        "oi": 6616559590087222666, //订单id
        "p": "43000",              //价格
        "q": "0.21",               //数量
        "v": "9030"                //金额
        "b": true                  //是否是buyerMaker
    }
}

心跳 Edit

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

订阅参数 Edit

结构

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

Orderbook 维护 Edit

如何正确在本地维护一个orderbook副本

1.订阅 wss://stream.xt.com/public,depth_update@btc_usdt

2.开始缓存收到的更新。同一个价位,后收到的更新覆盖前面的。

3.访问Rest接口 https://sapi.xt.com/v4/public/depth?symbol=btc_usdt&limit=500 获得一个500档的深度快照

4.将目前缓存到的信息中i <= 步骤3中获取到的快照中的lastUpdateId的部分丢弃(丢弃更早的信息,已经过期)。

5.将深度快照中的内容更新到本地orderbook副本中,并从websocket接收到的第一个fi <= lastUpdateId+1 且 i >= lastUpdateId+1 的event开始继续更新本地副本。

6.每一个新event的fi应该恰好等于上一个event的i+1,否则可能出现了丢包,请从step3重新进行初始化。

7.每一个event中的挂单量代表这个价格目前的挂单量绝对值,而不是相对变化。

8.如果某个价格对应的挂单量为0,表示该价位的挂单已经撤单或者被吃,应该移除这个价位。

注意: 因为深度快照对价格档位数量有限制,初始快照之外的价格档位并且没有数量变化的价格档位不会出现在增量深度的更新信息内。因此,即使应用来自增量深度的所有更新,这些价格档位也不会在本地 order book 中可见, 所以本地的 order book 与真实的 order book 可能会有一些差异。 不过对于大多数用例,500 的深度限制足以有效地了解市场和交易。

成交记录 Edit

请求

语法: trade@{symbol}

示例: trade@btc_usdt

速率: 实时

{
    "topic": "trade", 
    "event": "trade@btc_usdt", 
    "data": {
        "s": "btc_usdt",           //symbol
        "i": 6316559590087222000,  //成交id
        "t": 1655992403617,        //时间
        "oi": 6616559590087222666, //订单id
        "p": "43000",              //价格
        "q": "0.21",               //数量
        "v": "9030"                //金额
        "b": true                  //是否是buyerMaker
    }
}

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

速率: 1000ms

 

{
        "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

速率: 1000ms

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

增量深度 Edit

请求

语法: depth_update@{symbol}

示例: depth_update@btc_usdt

速率:100ms

{
    "topic": "depth_update", 
    "event": "depth_update@btc_usdt", 
    "data": {
        "s": "btc_usdt",        // symbol 交易对
        "fi": 121,              // firstUpdateId 等于上一次推送的lastUpdateId + 1
        "i": 123,               // lastUpdateId
        "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

速率: 1000ms

{
    "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 成交额
    }
}

基本信息 Edit

基地址

wss://stream.xt.com/private

Request Headers

请求头必须添加压缩扩展协议。

Sec-Websocket-Extensions:permessage-deflate

请求报文格式 Edit

param结构

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

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

响应报⽂格式 Edit

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

获取token接口 Edit

/v4/ws-token

备注:

accessToken有效期是2天,重新调用接口获取token会重置有效期。

accessToken = listenKey

{
    "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": {
        "a": "123",           // accountId 账号 
        "t": 1656043204763,   // time 发⽣时间
        "c": "btc",           // currency 币种
        "b": "123",           // balance 全部现货资产
        "f": "11",            // frozen 冻结资产
        "z": "SPOT",          // bizType 业务类型[SPOT,LEVER]
        "s": "btc_usdt"       // symbol 交易市场  
    }
}

订单变动 Edit

param

语法: order

示例: order

{
    "topic": "order", 
    "event": "order", 
    "data": {
        "s": "btc_usdt",                // symbol 交易对
        "bc": "btc",                    // baseCurrency 标的币种
        "qc": "usdt",                   // quoteCurrency 报价币种
        "t": 1656043204763,             // time 发⽣时间
        "ct": 1656043204663,            // createTime 下单时间
        "i": "6216559590087220004",     // orderId 订单号
        "ci": "test123",                // clientOrderId 客户端订单号
        "st": "PARTIALLY_FILLED",       // state 状态 NEW/PARTIALLY_FILLED/FILLED/CANCELED/REJECTED/EXPIRED
        "sd": "BUY",                    // side 方向 BUY/SELL
        "tp": "LIMIT",                  // type 类型 LIMIT/MARKET
        "oq":  "4"                      // origQty 原始数量
        "oqq":  48000,                  // origQuoteQty 原始金额
        "eq": "2",                      // executedQty 已执⾏数量
        "lq": "2",                      // leavingQty 待执行数量
        "p": "4000",                    // price 价格
        "ap": "30000",                  // avg price 均价
        "f": "0.001"                    // fee 手续费
    }
}

订单成交 Edit

param

语法: trade

示例: trade

{
    "topic": "trade", 
    "event": "trade", 
    "data": {
        "s": "btc_usdt",           //symbol
        "i": 6316559590087222000,  //成交id
        "t": 1655992403617,        //时间
        "oi": 6616559590087222666, //订单id
        "p": "43000",              //价格
        "q": "0.21",               //数量
        "v": "9030"                //金额
        "b": true                  //是否是buyerMaker
    }
}

REST API Edit

Official:

USDT-M:https://fapi.xt.com

Coin-M:https://dapi.xt.com

Basic Information of the Interface Edit

Due to the reasons of high latency and poor stability, it is not recommend to access the XT API through a proxy.

GET request parameters are put in query Params, POST request parameters are put in request body.

The request header information is set to: Content-Type=application/x-www-form-urlencoded

In addition to the parameters required by the interface itself, signature, which is the signature parameter, needs to be passed in the query Params or request body. The interface that does not need to pass the signature parameter will be additionally explained.

Frequency Limiting Rules Edit

Get assets 3 times per second, other methods 10 times per second for each single user, 1000 times per minute for each single IP, exceeding the requested times, account will be locked for 10 minutes.

Signature Statement 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 most important.

  1. Offline distribution of appkey and secretkey, for different calls, provide different appkey and secretkey.

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

  3. Add signature information for all data.

  4. Add recvwindow, the valid time is relatively simple and fixed to a certain value. For example, the data is valid within 10 minutes under the same api and appid. Here, it can be further optimized to the valid time of a single api is different.

The server determines the timestamp when it receives a request. Up to 60 seconds, and the default is 5 seconds. If it was sent 5000 milliseconds ago, the request will be considered invalid. This time window value can be customized 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, so your application’s local time delay to the XT server may be jitter.This is the purpose of setting recvWindow. If you are engaged in high-frequency trading and have high requirements for trading timeliness, you can flexibly set recvWindow to meet your requirements.

RecvWindow for more than 5 seconds is not recommended.

5、5. Add algorithms (signature method/algorithm). User’s signature calculation is a HSC-based protocol, where HmacSHA256 is used by default. See the specific supported protocols listed in the table below.

Name Mandatory Example Description
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow false 5000(millisecond)
validate-algorithms false HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,默认为:HmacSHA256
api-version false 1.0 Reserved, API version number
validate-signversion false 1.0 Reserved, signature version number

Obtain Signature Edit

Example for http://fapi.xt.com/api/v1/public/symbol/detail?symbol=btc_usdt

The following is an example of an order placed in a call interface using echo openssl and curl tools in a Linux bash environment. Appkey, secret for demonstration purposes only:

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Partial data of Header:

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

validate-timestamp: 1641446237201

validate-algorithms: HmacSHA256

Request data:

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

1、Data

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: Sorted by lexicographic order of key, concatenate all key=value. Example: userName=dfdfdf&password=ggg

body: Json: Operate as JSON string is not converted or sorted.

      x-www-form-urlencoded: Sorted by lexicographic order of key, concatenate all key=value. Example: userName=dfdfdf&password=ggg 

      form-data:Not supported.

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

Example of Path:

      /future/api/v1/public/symbol/detail

      The above concatenated value is recorded as path

Example 1: All parameters sent via query string

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        The above concatenate value is recorded as query

Example 2: All parameters send X-www-form-urlencoded request body string via the request body

Request body string of json

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        The above concatenate value is recorded as body

Request body string of www-form-urlencoded

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

        The above concatenate value is recorded as body

Example 3: Mix to use query string and request body (form and json format)

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

requestBody: {“quantity”:2,”price”:39000} The above concatenate value is recorded as query

    The final concatenate value of the entire data is # concatenated with path, query, and body and form #path, #query, and #body. The finalconcatenate value is recorded asY=#path#query#body。

    Note:

        query without data, body with data:Y=#path#body

        query with data, body without data:Y=#path#query

        query with data, body with data:Y=#path#query#body

2:Request header X=”validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-timestamp=1641446237201”

3:Obtain Signature

Finally, record the string that needs to be encrypted as sign=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, sign);

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

How to Apply for API Key Edit

The interface may require the user’s API Key, please refer to how to create an API-KEY this page(https://xtsupport.zendesk.com/hc/zh-cn/articles/900006868163-%E5%A6%82%E4%BD%95%E7%94%B3%E8%AF%B7API%E4%BA%A4%E6%98%93-%E5%A6%82%E4%BD%95%E5%88%9B%E5%BB%BAAPI%E5%AF%86%E9%92%A5-)

API Library Edit

Java connector

A lightweight Java code library that provides a method for users to directly call the API

Sdks for each language:

  java: https://github.com/xt-com/xt4-java-demo

Return Format Edit

All interfaces’ returns are in JSON format.

{
    "returnCode": 200,
    "result": {
        "serverTime": 1636612706739
    },
    "msgInfo": "Success."
    "error": null,
}

Error Code Edit

Status code Error information
200 Success
401 Login required
403 Login expired

Python Package Edit

Official Python3 API connector for XT.COM’s HTTP APIs :

https://pypi.org/project/pyxt/

Get client ip Edit

/future/public/client

Note:This method does not require a signature.

{
  "returnCode": 0,
  "msgInfo": "success",
  "error": null
  "result": {
    "ip": 192.168.1.1  
  }
}

Get Trading Pair Currency Edit

/future/market/v1/public/symbol/coins

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [],
  "returnCode": 0
}

Get Configuration Information for Single Trading Pair Edit

/future/market/v1/public/symbol/detail

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
         "baseCoin": "",      //Target Assets
         "baseCoinDisplayPrecision": 0,  //Displayed target currency precision
         "baseCoinPrecision": 0,  //Target currency precision
         "cnDesc": "",  //Chinese description of the contract
         "cnName": "",  //Contract Chinese name
         "cnRemark": "",  //Contract Remarks (Chinese)
         "contractSize": 0,  //Contract multiplier(face value)
         "contractType": "",  //Contract type, perpetual, delivery
         "deliveryCompletion": false, //Whether the delivery is completed
         "deliveryDate": 0,  //delivery time
         "deliveryPrice": 0,  //delivery price
         "depthPrecisionMerge": 0,  //Handicap Precision Consolidation
         "enDesc": "",      //English description of the contract
         "enName": "",      //Contract English name
         "enRemark": "",    //Contract Remarks (English)
         "initLeverage": 0,  //Initial leverage
         "initPositionType": "",  //Initial position type
         "isDisplay": false,      //whether to display
         "isOpenApi": false,      //Whether to support OpenApi
         "labels": [],            //Label
         "liquidationFee": 0,     //Forced liquidation fee
         "makerFee": 0,           //Maker fee
         "marketTakeBound": 0,    //Market order maximum price deviation
         "maxEntrusts": 0,        //Maximum active orders
         "maxNotional": 0,        //Maximum Notional Value
         "maxOpenOrders": 0,      //Maximum open orders
         "maxPrice": 0,           //Maximum price
         "minNotional": 0,        //Minimum notional value
         "minPrice": 0,           //Minimum price
         "minQty": 0,             //Minimum quantity
         "minStepPrice": 0,       //Smallest tick
         "multiplierDown": 0,     //Floor percentage of sell limit order
         "multiplierUp": 0,       //Cap percentage of buy limit order
         "onboardDate": 0,        //List time
         "pair": "",              //Target trading pair
         "plates": [],
         "predictEventParam": "",   //Event Correlation Parameters
         "predictEventSort": "",    //Event Correlation Sorting: WIN wins, FLAT draws, NEGATIVE loses
         "predictEventType": "",    //Forecast event type: PERPETUAL perpetual event, ONCE single event
         "pricePrecision": 0,       //Price precision
         "productType": "",         //Contract type, perpetual, futures, regardless of delivery interval
         "quantityPrecision": 0,     //Quantity precision
         "quoteCoin": "",            //Quote currency
         "quoteCoinDisplayPrecision": 0,  //Displayed quote currency precision
         "quoteCoinPrecision": 0,         //Quote currency precision
         "state": 0,                    //Status
         "supportEntrustType": "",      //Trigger order type supported
         "supportOrderType": "",        //Order type supported
         "supportPositionType": "",     //Support position type
         "supportTimeInForce": "",      //Valid ways supported
         "symbol": "",                  //Trading pair
         "symbolGroupId": 0,
         "takerFee": 0,                  //Taker fee
         "tradeSwitch": false,           //Trading pair switch
         "underlyingType": ""            //Target type, Coin-M,USDT-M
      },
  "returnCode": 0
}

Get Configuration Information for Listed And Tradeable Symbols Edit

/future/market/v3/public/symbol/list

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
      {
         "baseCoin": "",      //Target Assets
         "baseCoinDisplayPrecision": 0,  //Displayed target currency precision
         "baseCoinPrecision": 0,  //Target currency precision
         "cnDesc": "",  //Chinese description of the contract
         "cnName": "",  //Contract Chinese name
         "cnRemark": "",  //Contract Remarks (Chinese)
         "contractSize": 0,  //Contract multiplier(face value)
         "contractType": "",  //Contract type, perpetual, delivery
         "deliveryCompletion": false, //Whether the delivery is completed
         "deliveryDate": 0,  //delivery time
         "deliveryPrice": 0,  //delivery price
         "depthPrecisionMerge": 0,  //Handicap Precision Consolidation
         "enDesc": "",      //English description of the contract
         "enName": "",      //Contract English name
         "enRemark": "",    //Contract Remarks (English)
         "initLeverage": 0,  //Initial leverage
         "initPositionType": "",  //Initial position type
         "isDisplay": false,      //whether to display
         "isOpenApi": false,      //Whether to support OpenApi
         "labels": [],            //Label
         "liquidationFee": 0,     //Forced liquidation fee
         "makerFee": 0,           //Maker fee
         "marketTakeBound": 0,    //Market order maximum price deviation
         "maxEntrusts": 0,        //Maximum active orders
         "maxNotional": 0,        //Maximum Notional Value
         "maxOpenOrders": 0,      //Maximum open orders
         "maxPrice": 0,           //Maximum price
         "minNotional": 0,        //Minimum notional value
         "minPrice": 0,           //Minimum price
         "minQty": 0,             //Minimum quantity
         "minStepPrice": 0,       //Smallest tick
         "multiplierDown": 0,     //Floor percentage of sell limit order
         "multiplierUp": 0,       //Cap percentage of buy limit order
         "onboardDate": 0,        //List time
         "pair": "",              //Target trading pair
         "plates": [],
         "predictEventParam": "",   //Event Correlation Parameters
         "predictEventSort": "",    //Event Correlation Sorting: WIN wins, FLAT draws, NEGATIVE loses
         "predictEventType": "",    //Forecast event type: PERPETUAL perpetual event, ONCE single event
         "pricePrecision": 0,       //Price precision
         "productType": "",         //Contract type, perpetual, futures, regardless of delivery interval
         "quantityPrecision": 0,     //Quantity precision
         "quoteCoin": "",            //Quote currency
         "quoteCoinDisplayPrecision": 0,  //Displayed quote currency precision
         "quoteCoinPrecision": 0,         //Quote currency precision
         "state": 0,                    //Status
         "supportEntrustType": "",      //Trigger order type supported
         "supportOrderType": "",        //Order type supported
         "supportPositionType": "",     //Support position type
         "supportTimeInForce": "",      //Valid ways supported
         "symbol": "",                  //Trading pair
         "symbolGroupId": 0,
         "takerFee": 0,                  //Taker fee
         "tradeSwitch": false,           //Trading pair switch
         "underlyingType": ""            //Target type, Coin-M,USDT-M
   }
  ],
  "returnCode": 0
}

See Leverage Stratification of Single Trading Pair Edit

/future/market/v1/public/leverage/bracket/detail

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "leverageBrackets": [
      {
        "bracket": 0, //Level
        "maintMarginRate": 0, //Maintain margin rate
        "maxLeverage": 0, //Maximum leverage
        "maxNominalValue": 0, //Maximum notional value
        "maxStartMarginRate": 0, //Maximum initial margin rate
        "minLeverage": 0, //Minimum leverage
        "startMarginRate": 0, //Initial margin rate
        "symbol": "" //Trading pair
      }
    ],
    "symbol": ""
  },
  "returnCode": 0
}

See Leverage Stratification of All Trading Pairs Edit

/future/market/v1/public/leverage/bracket/list

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "leverageBrackets": [
        {
          "bracket": 0, //Level
          "maintMarginRate": 0, //Maintain margin rate
          "maxLeverage": 0, //Maximum leverage
          "maxNominalValue": 0, //Maximum notional value
          "maxStartMarginRate": 0, //Maximum initial margin rate
          "minLeverage": 0, //Minimum leverage
          "startMarginRate": 0, //Initial margin rate
          "symbol": "" //Trading pair
        }
      ],
      "symbol": ""
    }
  ],
  "returnCode": 0
}

Get Market Information for Specific Trading Pair Edit

/future/market/v1/public/q/ticker

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "a": "", //24h volume
    "c": "", //Latest price
    "h": "", //Highest price in 24 hours
    "l": "", //Lowest price in 24 hours
    "o": "", //The first transaction price 24 hours ago
    "r": "", //24h Price Fluctuation Limit
    "s": "", //Trading pair
    "t": 0, //Time
    "v": "" //24h turnover
  },
  "returnCode": 0
}

Get Market Information for All Trading Pairs Edit

/future/market/v1/public/q/tickers

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "a": "", //24h volume
      "c": "", //Latest price
      "h": "", //Highest price in 24 hours
      "l": "", //Lowest price in 24 hours
      "o": "", //The first transaction price 24 hours ago
      "r": "", //24h Price Fluctuation Limit
      "s": "", //Trading pair
      "t": 0, //Time
      "v": "" //24h turnover
    }
  ],
  "returnCode": 0
}

Get Latest Transaction Information of Trading Pairs Edit

/future/market/v1/public/q/deal

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair
num integer true N/A Quantity

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "a": 0, //Volume
      "m": "", //Order side
      "p": 0, //Price
      "s": "", //Trading pair
      "t": 0 //Time
    }
  ],
  "returnCode": 0
}

Get Depth Data of Trading Pairs Edit

/future/market/v1/public/q/depth

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair
level integer true N/A Level(min:1,max:50)

Limit Flow Rules

1/s/ip
Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "a": [], //Buy
    "b": [], //Sell
    "s": "", //Trading pair
    "t": 0, //Time
    "u": 0 //updateId
  },
  "returnCode": 0
}

Get Index Price for Single Trading Pair Edit

/future/market/v1/public/q/symbol-index-price

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "p": 0, //Price
    "s": "", //Trading pair
    "t": 0 //Time
  },
  "returnCode": 0
}

Get Index Price for All Trading Pairs Edit

/future/market/v1/public/q/index-price

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "p": 0, //Price
      "s": "", //Trading pair
      "t": 0 //Time
    }
  ],
  "returnCode": 0
}

Get Mark Price for Single Trading Pair Edit

/future/market/v1/public/q/symbol-mark-price

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "p": 0, //Price
    "s": "", //Trading pair
    "t": 0 //Time
  },
  "returnCode": 0
}

Get Mark Price for All Trading Pairs Edit

/future/market/v1/public/q/mark-price

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false N/A Trading pair

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "p": 0, //Price
      "s": "", //Trading pair
      "t": 0 //Time
    }
  ],
  "returnCode": 0
}

Get Trading Pair Information of Kline Edit

/future/market/v1/public/q/kline

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair
interval string true N/A Time-interval 1m;5m;15m;30m;1h;4h;1d;1w
startTime integer false N/A Start time
endTime integer false N/A End time
limit integer false N/A Limit

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "a": 0, //Volume
      "c": 0, //Close price
      "h": 0, //Highest price
      "l": 0, //Lowest price
      "o": 0, //Open price
      "s": "", //Trading pair
      "t": 0, //Time
      "v": 0 //Turnover
    }
  ],
  "returnCode": 0
}

Get Aggregated Market Information for Specific Trading Pair Edit

/future/market/v1/public/q/agg-ticker

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "a": "", //24h volume
    "ap": "", //ask price
    "bp": "", //bid price
    "c": "", //Latest price
    "h": "", //Highest price in 24 hours
    "i": "", //index price
    "l": "", //Lowest price in 24 hours
    "m": "", //mark price
    "o": "", //The first transaction price 24 hours ago
    "r": "", //24h price fluctuation limit
    "s": "", //Trading pair
    "t": 0, //Time
    "v": "" //24h Turnover
  },
  "returnCode": 0
}

Get Aggregated Market Information for All Trading Pairs Edit

/future/market/v1/public/q/agg-tickers

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "a": "", //24h volume
      "ap": "", //ask price
      "bp": "", //bid price
      "c": "", //Latest price
      "h": "", //Highest price in 24 hours
      "i": "", //index price
      "l": "", //Lowest price in 24 hours
      "m": "", //mark price
      "o": "", //The first transaction price 24 hours ago
      "r": "", //24h price fluctuation limit
      "s": "", //Trading pair
      "t": 0, //Time
      "v": "" //24h Turnover
    }
  ],
  "returnCode": 0
}

Get Funding Rate Information Edit

/future/market/v1/public/q/funding-rate

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair

Limit Flow Rules

1/s/ip
Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //Is there a next page
    "hasPrev": false, //Is there a previous page
    "items": [ //Datasheets
      {
        "collectionInternal": 0, //Billing Cycle (hour)
        "createdTime": 0, //Time
        "fundingRate": 0, //Latest funding rate
        "id": 0, //id
        "symbol": "" //Trading pair
      }
    ]
  },
  "returnCode": 0
}

Get Ask Bid Market Information for Specific Trading Pair Edit

/future/market/v1/public/q/ticker/book

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "ap": "", //ask price
    "aq": "", //ask amount
    "bp": "", //bid price
    "bq": "", //bid amount
    "s": "", //Trading pair
    "t": 0 //Time
  },
  "returnCode": 0
}

Get Funding Rate Records Edit

/future/market/v1/public/q/funding-rate-record

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair
direction string false NEXT Direction(PREV:Previous page;NEXT:Next page) PREV;NEXT
id integer false N/A id
limit integer false 10 Limit

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //Is there a next page
    "hasPrev": false, //Is there a previous page
    "items": [ //Datasheets
      {
        "collectionInternal": 0, //Billing Cycle (second)
        "createdTime": 0, //Time
        "fundingRate": 0, //Latest funding rate
        "id": 0, //id
        "symbol": "" //Trading pair
      }
    ]
  },
  "returnCode": 0
}

Get Ask Bid Market Information for All Trading Pairs Edit

/future/market/v1/public/q/ticker/books

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "ap": "", //ask price
      "aq": "", //ask amount
      "bp": "", //bid price
      "bq": "", //bid amount
      "s": "", //Trading pair
      "t": 0 //Time
    }
  ],
  "returnCode": 0
}

Get Trading Pair Risk Fund Balance Edit

/future/market/v1/public/contract/risk-balance

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true Trading pair
direction string false NEXT Direction(PREV:Previous page;NEXT:Next page) PREV;NEXT
id integer false N/A id
limit integer false 10 Limit

Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //Is there a next page
    "hasPrev": false, //Is there a previous page
    "items": [ //Datasheets
      {
        "amount": 0, //Balance
        "coin": "", //Currency
        "createdTime": 0, //Time
        "id": 0 //id
      }
    ]
  },
  "returnCode": 0
}

Get the open position of a trading pair Edit

/future/market/v1/public/contract/open-interest

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair

Limit Flow Rules

1/s/ip
Note:This method does not require a signature.

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "symbol": "", //Trading pair
    "openInterest": "", //open position
    "openInterestUsd": 0, //open value
    "time": "", //time
  },
  "returnCode": 0
}

Get Futures Info Edit

/future/market/v1/public/cg/contracts

Content-Type = application/x-www-form-urlencoded

Note:This method does not require a signature.

[{
    "id": 123, 
    "ask": "1817.32",                 //Current lowest ask price
    "base_currency": "ETH",           //Symbol/currency code of base pair, eg. BTC
    "base_volume": "13267684284",     //24 hour trading volume
    "bid": "1817.31",                 //Current highest bid price
    "contractSize": 10,               //Futures par value
    "end_timestamp": 253402099200000, //Ending of this derivative product
    "funding_rate": "-0.03",          //Fund rate
    "high": "1828.89",                //24-hour highest trading price
    "index_currency": "USD",          //Underlying currency for index
    "index_name": "ETH-USD",          //Name of the underlying index if any
    "index_price": "1816.61",         //Underlying index price
    "last_price": "1817.31",          //Latest price
    "low": "1778.65",                 //24-hour lowest trading price
    "next_funding_rate": "-0.03",     //Upcoming predicted funding rate
    "next_funding_rate_timestamp":1698681600000,  //Next funding rate time
    "open_interest": "2419347630",    //The open interest in the last 24 hours in contracts
    "product_type": "PERPETUAL",      //Product type
    "start_timestamp": 1651328033000, //Starting of this derivative product (relevant for expirable futures or options)
    "symbol": "eth_usd",
    "target_currency": "USD",         //Symbol/currency code of target pair, eg. ETH
    "target_volume": "73698647.51054371",  //24 hours trading volume
    "ticker_id": "ETH-USD",           //Identifier of a ticker with delimiter to separate base/target, eg. BTC-PERP
    "underlyingType": 1               //Target type, Coin-M,USDT-M
  }]

Get Depth Info Edit

/future/market/v1/public/cg/orderbook

Content-Type = application/x-www-form-urlencoded

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair, eg.BTC-USDT
level int false 50 1-200

Note:This method does not require a signature.

{
          "ticker_id": "BTC-USDT", 
          "timestamp": 1698668957638,
          "bids": [[
               "34794.6",
               "97164"
              ],[
               "34794.5",
               "9897"
              ],...], 
          "asks": [[
               "34794.7",
               "168479"
              ],[
               "34794.8",
               "4009"
              ],...]
}

Create Orders Edit

/future/trade/v1/order/create

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
clientOrderId string false N/A Client order ID
symbol string true Trading pair
orderSide string true N/A Order side:BUY;SELL BUY;SELL
orderType string true N/A Order type:LIMIT;MARKET LIMIT;MARKET
origQty number true N/A Quantity (Cont)
price number false N/A Price
timeInForce string false GTC Valid way:GTC;IOC;FOK;GTX GTC;IOC;FOK;GTX
triggerProfitPrice number false N/A Stop profit price
triggerStopPrice number false N/A Stop loss price
positionSide string true N/A Position side:LONG;SHORT LONG;SHORT

OrigQty Calculation Formula

Formula

origQty = Truncate ((Balance * Percent * Leverage ) / (Mark_price * Contract_size))

Explain
Truncate : take the integer part 

Balance : (walletBalance - openOrderMarginFrozen) , api: /future/user/v1/compat/balance/list  

Percent : user input , exp: 0.2 

Leverage : leverage your want , exp: 20 

Mark_price : current symobl mark price , exp: 88888 (btc_usdt) 

Contract_size : contractSize , api: /future/market/v1/public/symbol/detail , Contract multiplier(face value)  
Example

truncate(10000 * 0.2 * 20 / 88888 / 0.0001) = 4500

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

See Order History Edit

/future/trade/v1/order/list-history

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pairs (queries all trading pairs if not passed)
direction string false NEXT Direction(PREV:Previous page;NEXT:Next page) PREV;NEXT
id integer false N/A id
limit integer false 10 Limit
startTime integer false N/A Start time
endTime integer false N/A End time

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //Is there a next page
    "hasPrev": false, //Is there a previous page
    "items": [ //Datasheets
      {
        "clientOrderId": "", //Client order ID
        "avgPrice": 0, //Average price
        "closePosition": false, //Whether to close all when order condition is triggered
        "closeProfit": 0, //Offset profit and loss
        "createdTime": 0, //Creat time
        "executedQty": 0, //Volume (Cont)
        "forceClose": false, //Is it a liquidation order
        "marginFrozen": 0, //Occupied margin
        "orderId": 0, //Order ID
        "orderSide": "", //Order side
        "orderType": "", //Order type
        "origQty": 0, //Quantity (Cont)
        "positionSide": "", //Position side
        "price": 0, //Order price
        "sourceId": 0, //Triggering conditions ID
        "state": "", //Order state:NEW:New order (unfilled);PARTIALLY_FILLED:Partial deal;PARTIALLY_CANCELED:Partial revocation;FILLED:Filled;CANCELED:Cancled;REJECTED:Order failed;EXPIRED:Expired
        "symbol": "", //Trading pair
        "timeInForce": "", //Valid type
        "triggerProfitPrice": 0, //TP trigger price
        "triggerStopPrice": 0 //SL trigger price
      }
    ]
  },
  "returnCode": 0
}

See Transaction Details Edit

/future/trade/v1/order/trade-list

Parameters
Parameter Type mandatory Default Description Ranges
orderId integer false N/A Order ID
symbol string false N/A Trading pair
page integer false 1 Page
size integer false 10 Quantity of a single page
startTime integer false N/A start time
endTime integer false N/A end time

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "items": [
      {
        "fee": 0,                //Fee
        "feeCoin": "",           //Currency of fee
        "orderId": 0,            //Order ID
        "execId": 0,             //Trade ID
        "price": 0,              //Price
        "quantity": 0,           //Volume
        "symbol": "",            //Trading pair
        "timestamp": 0,          //Time
        "takerMaker": "TAKER"    //taker or maker
      }
    ],
    "page": 0,
    "ps": 0,
    "total": 0
  },
  "returnCode": 0
}

Update Orders Edit

/future/trade/v1/order/update

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
orderId number true Order ID
price number true Target price
origQty number true Target quantity (cont)
triggerProfitPrice number false N/A Profit target price
triggerStopPrice number false N/A Stop-Loss price
triggerPriceType string false LATEST_PRICE Trigger price type INDEX_PRICE(Index price);MARK_PRICE(Mark price);LATEST_PRICE(latest price)
profitDelegateOrderType string false N/A Take-Profit order type LIMIT;MARKET
profitDelegateTimeInForce string false N/A Take-Profit order validity method GTC;IOC;FOK;GTX
profitDelegatePrice number false N/A Take-Profit order price
stopDelegateOrderType string false N/A Stop-Loss order type LIMIT;MARKET
stopDelegateTimeInForce string false N/A Stop-Loss order validity method GTC;IOC;FOK;GTX
stopDelegatePrice number false N/A Stop-Loss order price
followUpOrder boolean false N/A If true, it indicates chase order

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

Bulk Orders Edit

/future/trade/v1/order/create-batch

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
list string true N/A List collection of order data

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

See Orders by ID Edit

/future/trade/v1/order/detail

Parameters
Parameter Type mandatory Default Description Ranges
orderId integer true N/A Order ID

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "avgPrice": 0, //Average price
    "closePosition": false, //Whether to close all when order condition is triggered
    "closeProfit": 0, //Offset profit and loss
    "createdTime": 0, //Create time
    "executedQty": 0, //Volume (Cont)
    "forceClose": false, //Is it a liquidation order
    "marginFrozen": 0, //Occupied margin
    "orderId": 0, //Order ID
    "orderSide": "", //Order side
    "orderType": "", //Order type
    "origQty": 0, //Quantity (Cont)
    "positionSide": "", //Position side
    "price": 0, //Order price
    "sourceId": 0, //Triggering conditions ID
    "state": "", //Order state:NEW:New order (unfilled);PARTIALLY_FILLED:Partial deal;PARTIALLY_CANCELED:Partial revocation;FILLED:Filled;CANCELED:Cancled;REJECTED:Order failed;EXPIRED:Expired
    "symbol": "", //Trading pair
    "timeInForce": "", //Valid type
    "triggerProfitPrice": 0, //TP trigger price
    "triggerStopPrice": 0 //SL trigger price
  },
  "returnCode": 0
}

See Orders Edit

/future/trade/v1/order/list

Parameters
Parameter Type mandatory Default Description Ranges
clientOrderId String false N/A Client order ID
page integer false 1 Page
size integer false 10 Quantity of a single page
startTime integer false N/A Start time
endTime integer false N/A End time
state string false NEW Order state: NEW:New order (unfilled);PARTIALLY_FILLED:Partial deal;PARTIALLY_CANCELED:Partial revocation;FILLED:Filled;CANCELED:Cancled;REJECTED:Order failed;EXPIRED:Expired;UNFINISHED:Unfinished;HISTORY:(History)
symbol string false N/A Trading pair

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "items": [
      {
        "clientOrderId": "", //Client order ID
        "avgPrice": 0, //Average price
        "closePosition": false, //Whether to close all when order condition is triggered
        "closeProfit": 0, //Offset profit and loss
        "createdTime": 0, //Creat time
        "executedQty": 0, //Volume (Cont)
        "forceClose": false, //Is it a liquidation order
        "marginFrozen": 0, //Occupied margin
        "orderId": 0, //Order id
        "orderSide": "", //Order side
        "orderType": "", //Order type
        "origQty": 0, //Quantity (Cont)
        "positionSide": "", //Position side
        "price": 0, //Order price
        "sourceId": 0, //Triggering conditions ID
        "state": "", //Order state:NEW:New order (unfilled);PARTIALLY_FILLED:Partial deal;PARTIALLY_CANCELED:Partial revocation;FILLED:Filled;CANCELED:Cancled;REJECTED:Order failed;EXPIRED:Expired
        "symbol": "", //Trading pair
        "timeInForce": "", //Valid type
        "triggerProfitPrice": 0, //TP trigger price
        "triggerStopPrice": 0 //SL trigger price
      }
    ],
    "page": 0,
    "ps": 0,
    "total": 0
  },
  "returnCode": 0
}

Cancel Orders Edit

/future/trade/v1/order/cancel

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
orderId Integer true N/A Order ID

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": "", //Order ID
  "returnCode": 0
}

Cancel All Orders Edit

/future/trade/v1/order/cancel-all

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
symbol String true N/A Trading pair (cancel all trading pair orders if pass "")

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

Create Trigger Orders Edit

/future/trade/v1/entrust/create-plan

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
clientOrderId string false N/A Client order ID
symbol string true Trading pair
orderSide string true N/A Order side:BUY;SELL BUY;SELL
entrustType string true N/A Order type:TAKE_PROFIT(Take Profit Limit Order);STOP(Stop Limit Order);TAKE_PROFIT_MARKET(Take Profit Market Order);STOP_MARKET(Stop Loss Market Order) TAKE_PROFIT;STOP;TAKE_PROFIT_MARKET;STOP_MARKET
origQty number true N/A Quantity (Cont)
price number false N/A Price
stopPrice number true N/A Trigger price
timeInForce string true N/A Valid way:GTC;IOC;FOK;GTX, Market orders only support IOC GTC;IOC;FOK;GTX
triggerPriceType string true N/A Trigger price type:INDEX_PRICE(Index price);MARK_PRICE(Mark price);LATEST_PRICE(latest price) INDEX_PRICE;MARK_PRICE;LATEST_PRICE
positionSide string true N/A Position side:LONG;SHORT LONG;SHORT

Limit Flow Rules

200/s/apikey

{
    "error": {
    "code": "",
    "msg": ""
    },
    "msgInfo": "",
    "result": {},
    "returnCode": 0
}
title: Response
language: json

Cancel Trigger Orders Edit

/future/trade/v1/entrust/cancel-plan

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
entrustId integer true N/A Trigger order ID

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

Cancel All Trigger Orders Edit

/future/trade/v1/entrust/cancel-all-plan

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true Trading pair. e.g. btc_usdt

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

See Trigger Orders Edit

/future/trade/v1/entrust/plan-list

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pairs (queries all trading pairs if not passed)
page integer false 1 Page
size integer false 10 Quantity of a single page
startTime integer false N/A Start time
endTime integer false N/A End time
state string true N/A Order status NOT_TRIGGERED:New order (not triggered);TRIGGERING:Triggering;TRIGGERED:Triggered;USER_REVOCATION:User revocation;PLATFORM_REVOCATION:Platform revocation (rejection);EXPIRED:expired;UNFINISHED:Unfinished;HISTORY:(History) NOT_TRIGGERED;TRIGGERING;TRIGGERED;USER_REVOCATION;PLATFORM_REVOCATION;EXPIRED;UNFINISHED;HISTORY

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "items": [
      {
        "clientOrderId": "", //Client order ID
        "closePosition": false, //Whether triggered to close all
        "createdTime": 0, //Create time
        "entrustId": 0, //Order ID
        "entrustType": "", //Order type
        "marketOrderLevel": 0, //Best market price
        "orderSide": "", //Order side
        "ordinary": true,
        "origQty": 0, //Quantity (Cont)
        "positionSide": "", //osition side
        "price": 0, //Order price
        "state": "", //Order state:NOT_TRIGGERED:New order (not triggered);TRIGGERING:Triggering;TRIGGERED:Triggered;USER_REVOCATION:User revocation;PLATFORM_REVOCATION:Platform revocation (rejection);EXPIRED:expired;UNFINISHED:Unfinished;HISTORY:(History)
        "stopPrice": 0, //Trigger price
        "symbol": "", //Trading pair
        "timeInForce": "", //Valid way
        "triggerPriceType": "" //Trigger price type
      }
    ],
    "page": 0,
    "ps": 0,
    "total": 0
  },
  "returnCode": 0
}

See Trigger Orders base on EntrustId Edit

/future/trade/v1/entrust/plan-detail

Parameters
Parameter Type mandatory Default Description Ranges
entrustId integer true N/A Order ID

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "closePosition": false, //Whether triggered to close all
    "createdTime": 0, //Create time
    "entrustId": 0, //Order ID
    "entrustType": "", //Order type
    "marketOrderLevel": 0, //Best market price
    "orderSide": "", //Order side
    "ordinary": true,
    "origQty": 0, //Quantity (Cont)
    "positionSide": "", //Position side
    "price": 0, //Order price
    "state": "", //Order state:NOT_TRIGGERED:New order (not triggered);TRIGGERING:Triggering;TRIGGERED:Triggered;USER_REVOCATION:User revocation;PLATFORM_REVOCATION:Platform revocation (rejection);EXPIRED:expired;UNFINISHED:Unfinished;HISTORY:(History)
    "stopPrice": 0, //Trigger price
    "symbol": "", //Trading pair
    "timeInForce": "", //有效方式
    "triggerPriceType": "" //触发价格类型
  },
  "returnCode": 0
}

See Trigger Orders History Edit

/future/trade/v1/entrust/plan-list-history

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pairs (queries all trading pairs if not passed)
direction string false NEXT Direction(PREV:Previous page;NEXT:Next page) PREV;NEXT
id integer false N/A id
limit integer false 10 Limit
startTime integer false N/A Start time
endTime integer false N/A End time

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //Is there a next page
    "hasPrev": false, //Is there a previous page
    "items": [ //Datasheets
      {
        "clientOrderId": "", //Client order ID
        "closePosition": false, //Whether triggered to close all
        "createdTime": 0, //Create time
        "entrustId": 0, //Order ID
        "entrustType": "", //Order type
        "marketOrderLevel": 0, //Best market price
        "orderSide": "", //Order side
        "ordinary": true,
        "origQty": 0, //Quantity (Cont)
        "positionSide": "", //Position side
        "price": 0, //Order price
        "state": "", //Order state:NOT_TRIGGERED:New order (not triggered);TRIGGERING:Triggering;TRIGGERED:Triggered;USER_REVOCATION:User revocation;PLATFORM_REVOCATION:Platform revocation (rejection);EXPIRED:expired
        "stopPrice": 0, //Trigger price
        "symbol": "", //Trading pair
        "timeInForce": "", //Valid way
        "triggerPriceType": "" //Trigger price type
      }
    ]
  },
  "returnCode": 0
}

Create Stop Limit Edit

/future/trade/v1/entrust/create-profit

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false N/A Trading pair
origQty integer true Quantity (Cont)
triggerProfitPrice integer true TP trigger price
triggerStopPrice integer true SL trigger price
expireTime integer true Expiration time
positionSide string true Position side:LONG;SHORT LONG;SHORT

Limit Flow Rules

200/s/apikey

{
    "error": {
    "code": "",
    "msg": ""
    },
    "msgInfo": "",
    "result": {},
    "returnCode": 0
}
title: Response
language: json

Cancel Stop Limit Edit

/future/trade/v1/entrust/cancel-profit-stop

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
profitId integer true N/A Stop limit ID

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

Cancel All Stop Limit Edit

/future/trade/v1/entrust/cancel-all-profit-stop

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair, e.g. btc_usdt

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

See Stop Limit Edit

/future/trade/v1/entrust/profit-list

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pairs (queries all trading pairs if not passed)
page integer false 1 Page
size integer false 10 Quantity of a single page
startTime integer false N/A Start time
endTime integer false N/A End time
state string true N/A Order state:NOT_TRIGGERED:New order (not triggered);TRIGGERING:Triggering;TRIGGERED:Triggered;USER_REVOCATION:User revocation;PLATFORM_REVOCATION:Platform revocation (rejection);EXPIRED:expired;UNFINISHED:Unfinished;HISTORY:(History) NOT_TRIGGERED;TRIGGERING;TRIGGERED;USER_REVOCATION;PLATFORM_REVOCATION;EXPIRED;UNFINISHED;HISTORY

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "items": [
      {
        "createdTime": 0, //Time
        "entryPrice": 0, //Open position average price
        "executedQty": 0, //Actual transaction
        "isolatedMargin": 0, //Isolated Margin
        "origQty": 0, //Quantity (Cont)
        "positionSide": "", //Position side
        "positionSize": 0, //Position quantity (Cont)
        "profitId": 0, //Order ID
        "state": "", //Order state:NOT_TRIGGERED:New order (not triggered);TRIGGERING:Triggering;TRIGGERED:Triggered;USER_REVOCATION:User revocation;PLATFORM_REVOCATION:Platform revocation (rejection);EXPIRED:expired;
        "symbol": "", //Trading pair
        "triggerProfitPrice": 0, //Stop profit price
        "triggerStopPrice": 0 //Stop loss price
      }
    ],
    "page": 0,
    "ps": 0,
    "total": 0
  },
  "returnCode": 0
}

See Stop Limit base on Profitld Edit

/future/trade/v1/entrust/profit-detail

Parameters
Parameter Type mandatory Default Description Ranges
profitId integer true N/A Stop limit ID

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "createdTime": 0, //Time
    "entryPrice": 0, //Open position average price
    "executedQty": 0, //Actual transaction
    "isolatedMargin": 0, //Isolated Margin
    "origQty": 0, //Quantity (Cont)
    "positionSide": "", //Position side
    "positionSize": 0, //Position quantity (Cont)
    "profitId": 0, //Order ID
    "state": "", //Order state:NOT_TRIGGERED:New order (not triggered);TRIGGERING:Triggering;TRIGGERED:Triggered;USER_REVOCATION:User revocation;PLATFORM_REVOCATION:Platform revocation (rejection);EXPIRED:expired;
    "symbol": "", //Trading pair
    "triggerProfitPrice": 0, //Stop profit price
    "triggerStopPrice": 0 //Stop loss price
  },
  "returnCode": 0
}

Alter Stop Limit Edit

/future/trade/v1/entrust/update-profit-stop

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
profitId integer true N/A Stop limit ID
triggerProfitPrice number false N/A TP trigger price
triggerStopPrice number false N/A SL trigger price

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

Create track Edit

/future/trade/v1/entrust/create-track

Content-Type = application/x-www-form-urlencoded

Parameters
Parameter Type mandatory Default Description Ranges
callback string true N/A Callback range configuration FIXED;PROPORTION
callbackVal number true N/A Callback value Greater than 0
orderSide string true N/A Order side BUY;SELL
origQty number true N/A Original quantity(count)
positionSide string true N/A Position side:LONG;SHORT BOTH;LONG;SHORT
positionType string true N/A Position type CROSSED;ISOLATED
symbol string true N/A Trading pair
triggerPriceType string true N/A Trigger price type:INDEX_PRICE(Index price);MARK_PRICE(Mark price);LATEST_PRICE(latest price) INDEX_PRICE;MARK_PRICE;LATEST_PRICE
activationPrice number false N/A Activation price
clientMedia string false N/A Client media
clientMediaChannel string false N/A Client media channel
clientOrderId string false N/A client order id
expireTime integer false N/A expire time

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

Cancel single track Edit

/future/trade/v1/entrust/cancel-track

Content-Type = application/x-www-form-urlencoded

Parameters
Parameter Type mandatory Default Description Ranges
trackId integer true N/A track id

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

Get single track detail Edit

/future/trade/v1/entrust/track-detail

Parameters
Parameter Type mandatory Default Description Ranges
trackId integer true N/A track id

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "activationPrice": 0,      //Activation price
    "avgPrice": 0,             //Average price
    "callback": "",            //Callback range configuration 1:PROPORTION 2:FIXED
    "callbackVal": 0,          //Callback value
    "configActivation": false, //Whether to configure activation price
    "createdTime": 0,          //Creat time
    "currentPrice": 0,         //Real-time price, compared with the activation price and order price, to determine the direction of the activation price
    "desc": "",                //Describe
    "executedQty": 0,          //Actual transaction quantity
    "orderSide": "",           //Order side
    "ordinary": true,          //
    "origQty": 0,              //Quantity (Cont)
    "positionSide": "",        //Position side
    "price": 0,                //Order price
    "state": "",               //Order state: NOT_ACTIVATION:inactivated;NOT_TRIGGERED:not triggered;TRIGGERING:triggering;TRIGGERED:triggered;USER_REVOCATION:user revocation;PLATFORM_REVOCATION:platform rejects;EXPIRED:expired;DELEGATION_FAILED:delegation failed
    "stopPrice": 0,            //Trigger price
    "symbol": "",              //Symbol
    "trackId": 0,              //Track id
    "triggerPriceType": "",    //Trigger price type
    "updatedTime": 0           //Update time
  },
  "returnCode": 0
}

Get track list(all active) Edit

/future/trade/v1/entrust/track-list

Parameters
Parameter Type mandatory Default Description Ranges
page integer false 1 page
size integer false 10 Quantity of a single page
endTime integer false N/A
startTime integer false N/A start time
symbol string false N/A symbol

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    items:[
      "activationPrice": 0,      //Activation price
      "avgPrice": 0,             //Average price
      "callback": "",            //Callback range configuration 1:PROPORTION 2:FIXED
      "callbackVal": 0,          //Callback value
      "configActivation": false, //Whether to configure activation price
      "createdTime": 0,          //Creat time
      "currentPrice": 0,         //Real-time price, compared with the activation price and order price, to determine the direction of the activation price
      "desc": "",                //Describe
      "executedQty": 0,          //Actual transaction quantity
      "orderSide": "",           //Order side
      "ordinary": true,          //
      "origQty": 0,              //Quantity (Cont)
      "positionSide": "",        //Position side
      "price": 0,                //Order price
      "state": "",               //Order state: NOT_ACTIVATION:inactivated;NOT_TRIGGERED:not triggered;TRIGGERING:triggering;TRIGGERED:triggered;USER_REVOCATION:user revocation;PLATFORM_REVOCATION:platform rejects;EXPIRED:expired;DELEGATION_FAILED:delegation failed
      "stopPrice": 0,            //Trigger price
      "symbol": "",              //Symbol
      "trackId": 0,              //Track id
      "triggerPriceType": "",    //Trigger price type
      "updatedTime": 0           //Update time
    ],
    page: 1,                     //Page
    ps: 10,                      //Page size
    total: 20                    //Total
  },
  "returnCode": 0
}

Cancel all track Edit

/future/trade/v1/entrust/cancel-all-track

Content-Type = application/x-www-form-urlencoded

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

Get history track list(inactive) Edit

/future/trade/v1/entrust/track-list-history

Parameters
Parameter Type mandatory Default Description Ranges
direction string false NEXT Direction(PREV:Previous page;NEXT:Next page) PREV;NEXT
limit integer false 10 Limit
id integer false N/A
endTime integer false N/A End time
startTime integer false N/A start time
state string false N/A track state NOT_ACTIVATION;NOT_TRIGGERED;TRIGGERING;TRIGGERED;USER_REVOCATION;PLATFORM_REVOCATION;EXPIRED;DELEGATION_FAILED
symbol string false N/A symbol

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    hasNext: true,               //Is there a next page
    hasPre: true,                //Is there a previous page
    items:[
      "activationPrice": 0,      //Activation price
      "avgPrice": 0,             //Average price
      "callback": "",            //Callback range configuration 1:PROPORTION 2:FIXED
      "callbackVal": 0,          //Callback value
      "configActivation": false, //Whether to configure activation price
      "createdTime": 0,          //Creat time
      "currentPrice": 0,         //Real-time price, compared with the activation price and order price, to determine the direction of the activation price
      "desc": "",                //Describe
      "executedQty": 0,          //Actual transaction quantity
      "orderSide": "",           //Order side
      "ordinary": true,          //
      "origQty": 0,              //Quantity (Cont)
      "positionSide": "",        //Position side
      "price": 0,                //Order price
      "state": "",               //Order state: NOT_ACTIVATION:inactivated;NOT_TRIGGERED:not triggered;TRIGGERING:triggering;TRIGGERED:triggered;USER_REVOCATION:user revocation;PLATFORM_REVOCATION:platform rejects;EXPIRED:expired;DELEGATION_FAILED:delegation failed
      "stopPrice": 0,            //Trigger price
      "symbol": "",              //Symbol
      "trackId": 0,              //Track id
      "triggerPriceType": "",    //Trigger price type
      "updatedTime": 0           //Update time
    ]
  },
  "returnCode": 0
}

Get contract account assets Edit

/future/user/v1/compat/balance/list

Parameters
Parameter Type mandatory Default Description Ranges
queryAccountId string false N/A account id

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
        "accountId": 500000000000, // account id
        "userId": 500000000000, // user id
        "coin": "usdt", // Currency
        "underlyingType": 2, // Coin standard, u standard
        "walletBalance": "2078.57264793", // Currency balance
        "openOrderMarginFrozen": "0", // Order frozen
        "isolatedMargin": "0", // Margin freeze
        "crossedMargin": "0", // Full margin freeze
        "amount": "2078.57264793", // Net asset balance
        "totalAmount": "2078.57264793", // Margin balance
        "convertBtcAmount": "0.03638940", // walletBalance wallet asset conversion BTC
        "convertUsdtAmount": "2078.5726", // walletBalance wallet asset conversion to USDT
        "profit": "0", // Profit and loss
        "notProfit": "0", // unrealized profit or loss
        "bonus": "0", // Trial fee
        "coupon": "0" // Deduction
    }
 ],
  "returnCode": 0
}

Get Account Related Information Edit

/future/user/v1/account/info

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "accountId": 0, //Account ID
    "allowOpenPosition": false, //Is it possible to open position
    "allowTrade": false, //Is it possible to trade
    "allowTransfer": false, //Is it possible to transfer
    "openTime": "", //Opening time
    "state": 0, //User status
    "userId": 0 //User ID
  },
  "returnCode": 0
}

Get ListenKey Edit

/future/user/v1/user/listen-key

Note:Valid time is 8 hours

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

Open Contract Edit

/future/user/v1/account/open

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

Get User's Single Currency Fund Information Edit

/future/user/v1/balance/detail

Parameters
Parameter Type mandatory Default Description Ranges
coin string true N/A Currency

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "availableBalance": 0,      //Available balance
    "coin": "",                 //Currency
    "isolatedMargin": 0,        //Frozen isolated margin
    "openOrderMarginFrozen": 0, //Frozen order
    "crossedMargin": 0,         //Crossed Margin
    "bonus": 0,                 //Bouns
    "coupon": 0,                //Coupon
    "walletBalance": 0          //Balance
  },
  "returnCode": 0
}

Get User's Funds Information Edit

/future/user/v1/balance/list

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "availableBalance": 0,      //Available balance
      "coin": "",                 //Currency
      "isolatedMargin": 0,        //Frozen isolated margin
      "openOrderMarginFrozen": 0, //Frozen order
      "crossedMargin": 0,         //Crossed Margin
      "bonus": 0,                 //Bouns
      "coupon": 0,                //Coupon
      "walletBalance": 0          //Balance
    }
  ],
  "returnCode": 0
}

Get User's Account Flow Information Edit

/future/user/v1/balance/bills

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pairs (queries all trading pairs if not passed)
direction string false NEXT Direction(PREV:Previous page;NEXT:Next page) PREV;NEXT
id integer false N/A id
limit integer false 10 Limit
startTime integer false N/A Start time
endTime integer false N/A End time

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //Is there a next page
    "hasPrev": false, //Is there a previous page
    "items": [ //Datasheets
      {
        "afterAmount": 0, //Balance after change
        "amount": 0, //Quantity
        "coin": "", //Currency
        "createdTime": 0, //Time
        "id": 0, //id
        "side": "", //ADD:transfer in;SUB:transfer out
        "symbol": "", //Trading pair
        "type": "" //EXCHANGE:transfer;CLOSE_POSITION:Offset profit and loss;TAKE_OVER:position takeover;QIANG_PING_MANAGER:Liquidation management fee (fee);FUND:Fund Fee;FEE:Fee(Open position, liquidation, Forced liquidation);ADL:Adl;TAKE_OVER:position takeover;MERGE:Position Merge
      }
    ]
  },
  "returnCode": 0
}

Get Fund Fee Information Edit

/future/user/v1/balance/funding-rate-list

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pairs (queries all trading pairs if not passed)
direction string false NEXT Direction(PREV:Previous page;NEXT:Next page) PREV;NEXT
id integer false N/A id
limit integer false 10 Limit
startTime integer false N/A Start time
endTime integer false N/A End time

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //Is there a next page
    "hasPrev": false, //Is there a previous page
    "items": [ //Datasheets
      {
        "cast": 0, //Fund fee
        "coin": "", //Currency
        "createdTime": 0, //Time
        "id": 0, //id
        "positionSide": "", //Direction
        "symbol": "" //Trading pair
      }
    ]
  },
  "returnCode": 0
}

Get active position information Edit

/future/user/v1/position

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false N/A Trading pairs (query the position information of all trading pairs when not uploaded)

Limit Flow Rules

200/s/apikey

{
  "error": {
    "args": [],
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "autoMargin": false, // Whether to automatically call margin
      "availableCloseSize": 0, // Available quantity (Cont)
      "breakPrice": 0, // Blowout price
      "calMarkPrice": 0, // Calculated mark price
      "closeOrderSize": 0, // Quantity of open order (Cont)
      "contractType": "", // Contract Types: PERPETUAL (Perpetual Contract), PREDICT (Predict Contract)
      "entryPrice": 0, // Average opening price
      "floatingPL": 0, // Unrealized profit or loss
      "isolatedMargin": 0, // Warehouse-by-warehouse margin
      "leverage": 0, // Leverage ratio
      "openOrderMarginFrozen": 0, // Occupation of deposit for opening order
      "openOrderSize": 0, // Opening warehouse orders occupied
      "positionSide": "", // Position direction
      "positionSize": 0, // Position quantity (Cont)
      "positionType": "", // Position type: CROSSED (full position); ISOLATED (warehouse by warehouse)
      "profitId": 0, // Take profit and stop loss id
      "realizedProfit": 0, // Realized profit and loss
      "symbol": "", // trading pair
      "triggerPriceType": "", // Trigger price type 1. Index price 2: Mark price (reasonable price); 3: Latest price
      "triggerProfitPrice": 0, // Take profit trigger price
      "triggerStopPrice": 0, // Stop loss trigger price
      "welfareAccount": true
    }
  ],
  "returnCode": 0
}

Get Position Information Edit

/future/user/v1/position/list

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false N/A Trading pair (see the position information of all trading pairs if don't pass parameters)

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "autoMargin": false, //Whether to automatically call margin
      "availableCloseSize": 0, //Available quantity (Cont)
      "closeOrderSize": 0, //Pending order quantity (Cont)
      "entryPrice": 0, //Open position average price
      "isolatedMargin": 0, //Isolated Margin
      "leverage": 0, //Leverage
      "openOrderMarginFrozen": 0, //Occupied open position margin
      "positionSide": "", //Position side
      "positionSize": 0, //Position quantity (Cont)
      "positionType": "", //Position type
      "realizedProfit": 0, //Realized profit and loss
      "symbol": "" //Trading pair
    }
  ],
  "returnCode": 0
}

Get User's Step Rate Edit

/future/user/v1/user/step-rate

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "success",
  "result": {
    "makerFee":"0.00004",
    "takerFee": "0.00001"
  },
  "returnCode": 0
}

Adjust Leverage Edit

/future/user/v1/position/adjust-leverage

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair
positionSide string true N/A Position side LONG;SHORT
leverage integer true N/A Leverage

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

Alter Margin Edit

/future/user/v1/position/margin

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair
margin number false N/A Quantity
positionSide string false N/A Position side:LONG;SHORT
type string false N/A Adjust direction (add isolated margin, reduce isolated margin) ADD;SUB

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

Close All Edit

/future/user/v1/position/close-all

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

Get ADL Information Edit

/future/user/v1/position/adl

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "longQuantile": 0, //long position adl
      "shortQuantile": 0, //Short position adl
      "symbol": "" //Trading pair
    }
  ],
  "returnCode": 0
}

Collect Trading Pair Edit

/future/user/v1/user/collection/add

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

Cancel Trading Pair Collection Edit

/future/user/v1/user/collection/cancel

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

List of Collected Trading Pairs Edit

/future/user/v1/user/collection/list

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [],
  "returnCode": 0
}

Change Position Type Edit

/future/user/v1/position/change-type

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true N/A Trading pair
positionSide string true N/A Position side LONG;SHORT
positionType string true N/A Position type CROSSED;ISOLATED

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

Get Margin Call Information Edit

/future/user/v1/position/break-list

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false N/A Trading pair (see the margin call of all trading pairs if don't pass parameters)

Limit Flow Rules

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "breakPrice": 0,    //Margin call price. 0 means no margin call
      "calMarkPrice": 0,  //Mark price
      "contractType": "", //Futures type: PERPETUAL;PREDICT
      "entryPrice": 0,    //Open position average price
      "isolatedMargin": 0,//Isolated Margin
      "leverage": 0,      //Leverage
      "positionSide": "", //Position side:LONG;SHORT
      "positionSize": 0,  //Position quantity (Cont)
      "positionType": "", //Position type:CROSSED;ISOLATED
      "symbol": ""        //Symbol
    }
  ],
  "returnCode": 0
}

General WSS information Edit

Base Address

wss://fstream.xt.com/ws/market

Request Headers

The request header of the compression extension protocol must be added.

Sec-Websocket-Extensions:permessage-deflate

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 text “ping” periodically, and the server will reply to the text “pong”. If the server does not receive a ping message from the client within 30 seconds, it will actively disconnect the link.

Subscription parameters Edit

format

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

Orderbook manage Edit

How to manage a local order book correctly

1.Open a stream to wss://fstream.xt.com/ws/market , depth_update@btc_usdt

2.Buffer the events you receive from the stream.

3.Get a depth snapshot from https://fapi.xt.com/future/market/v1/public/depth?symbol=btc_usdt&level=500

4.Drop any event where u is <= lastUpdateId in the snapshot.

5.The first processed event should have fu <= lastUpdateId+1 AND u >= lastUpdateId+1.

6.While listening to the stream, each new event’s fu should be equal to the previous event’s u+1.

7.The data in each event is the absolute quantity for a price level.

8.If the quantity is 0, remove the price level.

9.Receiving an event that removes a price level that is not in your local order book can happen and is normal.

Note: Due to depth snapshots having a limit on the number of price levels, a price level outside of the initial snapshot that doesn’t have a quantity change won’t have an update in the Diff. Depth Stream. Consequently, those price levels will not be visible in the local order book even when applying all updates from the Diff. Depth Stream correctly and cause the local order book to have some slight differences with the real order book. However, for most use cases the depth limit of 500 is enough to understand the market and trade effectively.

Trade record Edit

request

format: trade@{symbol}

eg: trade@btc_usdt

rate: real

{
    "topic": "trade", 
    "event": "trade@btc_usdt", 
    "data": {
        "s":"btc_index", //trading pair
        "p":"50000",    //price
        "a":"0.1"   //Quantity
        "m": "BID"   //Deal side  BID:Buy ASK:Sell
        "t":123124124   //timestamp
    }
}

K-line 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

rate: 1000ms

 

{
    "topic": "kline", 
    "event": "kline@btc_usdt,5m", 
    "data": {
        "s":"btc_index", //trading pair
        "o":"49000",     // opening price
        "c":"50000",    //Closing price
        "h":"0.1",      //highest price
        "l":"0.1",       //lowest price
        "a":"0.1",      //volume
        "v":"0.1",       //Turnover
        "ch":"0.21",   //Quote change
        "t":123124124   //timestamp
    }
}

Ticker Edit

request

format: ticker@{symbol}

eg: ticker@btc_usdt

rate: 1000ms

{
    "topic": "ticker", 
    "event": "ticker@btc_usdt", 
    "data": {
        "s":"btc_index", //trading pair
        "o":"49000",     // opening price
        "c":"50000",    //Closing price
        "h":"0.1",      //highest price
        "l":"0.1",       //lowest price
        "a":"0.1",      //volume
        "v":"0.1",       //Turnover
        "ch":"0.21",   //Quote change
        "t":123124124   //timestamp
   }
}

Agg ticker Edit

request

format: agg_ticker@{symbol}

eg: agg_ticker@btc_usdt

rate: 1000ms

{
    "topic": "agg_ticker", 
    "event": "agg_ticker@btc_usdt", 
    "data": {
        "s":"btc_index", //trading pair
        "o":"49000",     // opening price
        "c":"50000",    //Closing price
        "h":"0.1",      //highest price
        "l":"0.1",       //lowest price
        "a":"0.1",      //volume
        "v":"0.1",       //Turnover
        "ch":"0.21",   //Quote change

        "i":"0.21" ,   //index price

        "m":"0.21",   //mark price

        "bp":"0.21",   //bid price

        "ap":"0.21" ,  //ask price
        "t":123124124   //timestamp
   }
}

Index price Edit

request

format: index_price@{symbol}

eg: index_price@btc_usdt

rate: 1000ms

{
    "topic": "index_price", 
    "event": "index_price@btc_usdt", 
    "data": {
        "s":"btc_usdt", //trading pair
        "p":"50000",    //price
        "t":123124124   //timestamp
   }
}

Mark price Edit

request

format: mark_price@{symbol}

eg: mark_price@btc_usdt

rate: 1000ms

{
    "topic": "mark_price", 
    "event": "mark_price@btc_usdt", 
    "data": {
        "s":"btc_usdt", //trading pair
        "p":"50000",    //price
        "t":123124124   //timestamp
   }
}

Incremental depth Edit

request

format: depth_update@{symbol},{interval}

interval: 100/250/500/1000   default rate 100ms

eg: depth_update@btc_usdt,100ms

{
    "topic": "depth_update", 
    "event": "depth_update@btc_usdt", 
    "data": {
        "s": "btc_usdt",        // symbol
        "pu": 120,              // previousUpdateId = previous lastUpdateId
        "fu": 121,              // firstUpdateId = previous lastUpdateId + 1
        "u": 123,               // lastUpdateId
        "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"
            ]
        ],
        "t": 123456789 // time stamp
    }
}

Limited depth Edit

request

 

format: depth@{symbol},{levels},{interval}

levels: 5/10/20/50

interval: 100/250/500/1000   default rate 1000ms

eg: depth@btc_usdt,50,1000ms

{
    "topic": "depth", 
    "event": "depth@btc_usdt,20", 
    "data": {
        "id": "1234", //lastUpdateId
        "s":"btc_index", //trading pair
        "a":[["50000","0.1"],["50001","0.2"]],    //ask sell order queue,[price, quantity]
        "b":[["49999","0.1"],["48888","0.2"]],   //bid buy queue
        "t": 123456789 // time stamp
    }
}

Fund rate Edit

request

format: fund_rate@{symbol}

eg: fund_rate@btc_usdt

rate: 60s

{
    "topic": "fund_rate", 
    "event": "fund_rate@btc_usdt", 
    "data": {
        "s":"btc_usdt", //Trading pair
        "r":"0.01",    // Fund fee
        "t":123124124   //timestamp
   }
}

General WSS information Edit

Base Address

wss://fstream.xt.com/ws/user

Request Headers

The request header of the compression extension protocol must be added.

Sec-Websocket-Extensions:permessage-deflate

Subscription Steps

Step 1: The user need to call the interface: /v1/user/listen-key to get the listenKey.
Step 2: When subscribing to user-related websocket events, users need to send: {“method”:”SUBSCRIBE”,”params”:[“order@{listenKey obtained in the previous step}”],”id”:”test1”}
If you receive “invalid_listen_key”, it means that the listenKey is expired or invalid, and you need to re-request to obtain the listenKey.
ps: listenKey is obtained through the interface.
User-related data will be pushed after subscription.

Request message format Edit

subscribe:

  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{order}@{listenKey}",
         "{trade}@{listenKey}",
         "{balance}@{listenKey}",
         "{position}@{listenKey}",
         "{notify}@{listenKey}"
      ],
     "id": "{id}"    //user defined
  }
{"method":"SUBSCRIBE",
 "params":["order@A246C3DF8EE532DC75007BC5D86698541678596355681"],
 "id":"test1"
 }

Response message format Edit

{"id":"123", "code": 0, "msg": "success"}   
{"id":"123", "code": 401, "msg": "token expire"}

Subscription parameters Edit

format

{topic}@{listenKey},…

Balance change Edit

subscribe:

  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{balance}@{listenKey}",
      ],
     "id": "{id}"
  }
{
    "topic": "balance", 
    "event": "balance@123456", 
    "data": {
         "coin":"usdt",
         "underlyingType":1, //  1:Coin-M,2:USDT-M
         "walletBalance":"123", // Balance
         "openOrderMarginFrozen":"123", // Frozen order
         "isolatedMargin":"213",  // Isolated Margin
         "crossedMargin":"0" //Crossed Margin
       }  
}

Change position Edit

subscribe:

  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{position}@{listenKey}",
      ],
     "id": "{id}"
  }
{
    "topic": "position", 
    "event": "position@123456", 
    "data": {
           "symbol":"btc_usdt",
           "contractType": "PERPUTUAL", //PERPUTUAL,DELIVERY
           "positionType": "ISOLATED",  // "ISOLATED", "CROSSED"
           "positionSide": "LONG",
           "positionSize":"123",  // Position quantity
           "closeOrderSize": "100",  //  Pending order quantity (Cont)
           "availableCloseSize": "23",  //  Available quantity (Cont)
           "realizedProfit": "123"   //  Realized profit and loss
           "entryPrice":"213",   //  Open position average price
           "isolatedMargin":"213",  //  Isolated Margin
           "openOrderMarginFrozen": "123", //  Occupied open position margin
           "underlyingType": ""// COIN_BASED, U_BASED
           "leverage":20  // Leverage
       }
}

Transactions Edit

subscribe:

  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{trade}@{listenKey}",
      ],
     "id": "{id}"
  }
{
    "topic": "trade", 
    "event": "trade@123456", 
    "data": {
            "orderId":"12312312",       // Order ID
            "clientOrderId":"123456",   // Client order ID
            "price":"34244",            // Price
            "quantity":"123",           // Quantity
            "marginUnfrozen":"123",     // Quantity of unfrozen margin
            "timestamp":1731231231,     // Timestamp
            "symbol": "btc_usdt",       //Symbol
            "orderSide": "BUY",         //Order side
            "positionSide": "LONG",     //Position side
            "isMaker": true,            //Is maker or not, true:maker;false:taker
            "fee": 0.0002               //fee
       }
}

user Order Edit

subscribe:

  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{order}@{listenKey}",
      ],
     "id": "{id}"
  }
{
    "topic": "order", 
    "event": "order@123456", 
    "data": {
         "symbol":"btc_usdt",        // Trading pair
         "orderId": "1234",          // Order Id
         "origQty": "34244",         // Original Quantity
         "avgPrice": "123",          // Quantity
         "price": "1111",            // Average price
         "executedQty":"34244",      // Volume (Cont)
         "orderSide": "BUY",         // BUY, SELL
         "timeInForce": "IOC",       // Valid way
         "positionSide": "LONG",     // LONG, SHORT
         "marginFrozen":"123",       // Occupied margin
         "sourceType":"default",     //  DEFAULT:normal order,ENTRUST:plan commission,PROFIR:Take Profit and Stop Loss
         "type" : "ORDER",           // 
         "state": "FILLED",          // state:NEW:New order (unfilled);PARTIALLY_FILLED:Partial deal;PARTIALLY_CANCELED:Partial revocation;FILLED:Filled;CANCELED:Cancled;REJECTED:Order failed;EXPIRED:Expired
         "createdTime": 1731231231,  // CreateTime
         "leverage":20,              //leverage
         "positionType": "ISOLATED", //position type:CROSSED;ISOLATED
         "orderType:": "MARKET"      //Order Type [LIMIT;MARKET]
       }
}

Message Edit

subscribe:

  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{notify}@{listenKey}",
      ],
     "id": "{id}"
  }
{
    "topic": "notify", 
    "event": "notify", 
    "data": {
           "symbol":"btc_usdt",
           "positionType": "ISOLATED",  
           "positionSide": "LONG",
           "positionSize":"123",  // Position quantity
           "notifyType": "WARN",  // Notification Type:WARN:Warning, about to be levelled,PARTIAL:Partially Liquidation,LIQUIDATION:Liquidation,ADL:ADL
    }
}

REST API Edit

正式:

U本位合约:https://fapi.xt.com

币本位合约:https://dapi.xt.com

接口的基本信息 Edit

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

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

请求头信息请设置为:Content-Type=application/x-www-form-urlencoded

除了接口本身所需的参数外,还需要在query Params 或 request body中传递 signature, 即签名参数,不需要传递签名参数的接口会额外说明。

限频规则 Edit

获取资产每秒3次,其他方法单个用户每秒10次,单个IP每分钟1000次,超出锁定账户10分钟。

签名说明 Edit

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

1、线下分配appkey和secretkey,针对不同的调用,提供不同的appkey和secretkey

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

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

4、加入recvwindow(自定义请求有效时间),有效时间目前相对简单统一固定为某个值,比如:同api同appid下10分钟内数据都有郊,此处可以再进步优化到具体单个api有效时间都不相同。

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

不推荐使用5秒以上的recvWindow

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

字段名 是否必须 示例 说明
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow false 5000(毫秒)
validate-algorithms false HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,默认为:HmacSHA256
api-version false 1.0 保留,API版本号
validate-signversion false 1.0 保留,签名版本号

签名生成 Edit

http://fapi.xt.com/future/api/v1/public/symbol/detail?symbol=btc_usdt的示例

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

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Header部分数据:

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

validate-timestamp: 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9

validate-algorithms: HmacSHA256

请求数据:

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

1、数据部分

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的顺序进行再拼接,得到所有数据的拼接值。

路径Path示例:

      /future/api/v1/public/symbol/detail

      上述拼接值记作为path

示例 1: 所有参数通过 query string 发送

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        上述值拼接记作query

示例 2: 所有参数通过 request body 发送

x-www-form-urlencoded的request body string :

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        上述值拼接记作body

json的request body string :

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

        上述值拼接记作body

示例 3: 混合使用 query string 与 request body(分为表单与json两种格式)

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

requestBody: {“quantity”:2,”price”:39000} 上述拼接值记作body

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

    注意:

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

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

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

2、请求头部分 X=”validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-timestamp=1641446237201”

3、生成签名

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

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

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

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

API Key申请步骤 Edit

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

API 代码库 Edit

Java connector

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

各个语言的sdk:

  java: https://github.com/xt-com/xt4-java-demo

返回格式 Edit

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

{
    "returnCode": 200,
    "result": {
        "serverTime": 1636612706739
    },
    "msgInfo": "Success."
    "error": null,
}

错误代码 Edit

状态码 错误信息
200 成功
401 需要登录
403 登录过期

Python Package Edit

用于 XT.COM 的 HTTP API 的官方 Python3 Package :

https://pypi.org/project/pyxt/

获取客户端IP Edit

/future/public/client

注:此方法不需要签名

{
  "returnCode": 0,
  "msgInfo": "success",
  "error": null
  "result": {
    "ip": 192.168.1.1  
  }
}

获取交易对币种 Edit

/future/market/v1/public/symbol/coins

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [],
  "returnCode": 0
}

获取单个交易对的配置信息 Edit

/future/market/v1/public/symbol/detail

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
       "baseCoin": "",      //标的资产
       "baseCoinDisplayPrecision": 0,  //标的币种显示精度
       "baseCoinPrecision": 0,  //标的币种精度
       "cnDesc": "",  //合约中文描述
       "cnName": "",  //合约中文名称
       "cnRemark": "",  //合约备注(中文)
       "contractSize": 0,  //合约乘数(面值)
       "contractType": "",  //合约类型,永续,交割
       "deliveryCompletion": false, //交割是否完成
       "deliveryDate": 0,  //交割时间
       "deliveryPrice": 0,  //交割价格
       "depthPrecisionMerge": 0,  //盘口精度合并
       "enDesc": "",      //合约英文描述
       "enName": "",      //合约英文名称
       "enRemark": "",    //合约备注(英文)
       "initLeverage": 0,  //初始杠杆倍数
       "initPositionType": "",  //初始仓位类型
       "isDisplay": false,      //是否展示
       "isOpenApi": false,      //是否支持OpenApi|
       "labels": [],            //标签
       "liquidationFee": 0,     //强平手续费
       "makerFee": 0,           //maker手续费
       "marketTakeBound": 0,    //市价单最多价格偏离
       "maxEntrusts": 0,        //最多open条件单
       "maxNotional": 0,        //最大名义价值
       "maxOpenOrders": 0,      //最多open订单
       "maxPrice": 0,           //预测合约价格上限(原型指数价格上限)
       "minNotional": 0,        //最小名义价值
       "minPrice": 0,           //预测合约价格下限(原型指数价格下限)
       "minQty": 0,             //最小数量
       "minStepPrice": 0,       //最小价格变动单位
       "multiplierDown": 0,     //限价卖单下限百分比
       "multiplierUp": 0,       //限价买单价格上限百分比
       "onboardDate": 0,        //上线时间
       "pair": "",              //标的交易对
       "plates": [],
       "predictEventParam": "",   //事件关联参数
       "predictEventSort": "",    //事件关联排序:WIN , FLAT , NEGATIVE 
       "predictEventType": "",    //预测事件类型:PERPETUAL 永续事件,ONCE 单事件
       "pricePrecision": 0,       //价格精度
       "productType": "",         //合约类型,perpetual, futures,不区分交割间隔
       "quantityPrecision": 0,     //数量精度
       "quoteCoin": "",            //报价资产
       "quoteCoinDisplayPrecision": 0,  //报价币种显示精度
       "quoteCoinPrecision": 0,         //报价币种精度
       "state": 0,                    //状态
       "supportEntrustType": "",      //支持计划委托类型
       "supportOrderType": "",        //支持订单类型
       "supportPositionType": "",     //支持仓位类型
       "supportTimeInForce": "",      //支持有效方式
       "symbol": "",                  //交易对
       "symbolGroupId": 0,
       "takerFee": 0,                  //手续费
       "tradeSwitch": false,           //交易对开关
       "underlyingType": ""            //标的类型,币本位,u本位
     },
  "returnCode": 0
}

获取上架和可交易的交易对配置信息 Edit

/future/market/v3/public/symbol/list

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
      {
       "baseCoin": "",      //标的资产
       "baseCoinDisplayPrecision": 0,  //标的币种显示精度
       "baseCoinPrecision": 0,  //标的币种精度
       "cnDesc": "",  //合约中文描述
       "cnName": "",  //合约中文名称
       "cnRemark": "",  //合约备注(中文)
       "contractSize": 0,  //合约乘数(面值)
       "contractType": "",  //合约类型,永续,交割
       "deliveryCompletion": false, //交割是否完成
       "deliveryDate": 0,  //交割时间
       "deliveryPrice": 0,  //交割价格
       "depthPrecisionMerge": 0,  //盘口精度合并
       "enDesc": "",      //合约英文描述
       "enName": "",      //合约英文名称
       "enRemark": "",    //合约备注(英文)
       "initLeverage": 0,  //初始杠杆倍数
       "initPositionType": "",  //初始仓位类型
       "isDisplay": false,      //是否展示
       "isOpenApi": false,      //是否支持OpenApi|
       "labels": [],            //标签
       "liquidationFee": 0,     //强平手续费
       "makerFee": 0,           //maker手续费
       "marketTakeBound": 0,    //市价单最多价格偏离
       "maxEntrusts": 0,        //最多open条件单
       "maxNotional": 0,        //最大名义价值
       "maxOpenOrders": 0,      //最多open订单
       "maxPrice": 0,           //预测合约价格上限(原型指数价格上限)
       "minNotional": 0,        //最小名义价值
       "minPrice": 0,           //预测合约价格下限(原型指数价格下限)
       "minQty": 0,             //最小数量
       "minStepPrice": 0,       //最小价格变动单位
       "multiplierDown": 0,     //限价卖单下限百分比
       "multiplierUp": 0,       //限价买单价格上限百分比
       "onboardDate": 0,        //上线时间
       "pair": "",              //标的交易对
       "plates": [],
       "predictEventParam": "",   //事件关联参数
       "predictEventSort": "",    //事件关联排序:WIN , FLAT , NEGATIVE 
       "predictEventType": "",    //预测事件类型:PERPETUAL 永续事件,ONCE 单事件
       "pricePrecision": 0,       //价格精度
       "productType": "",         //合约类型,perpetual, futures,不区分交割间隔
       "quantityPrecision": 0,     //数量精度
       "quoteCoin": "",            //报价资产
       "quoteCoinDisplayPrecision": 0,  //报价币种显示精度
       "quoteCoinPrecision": 0,         //报价币种精度
       "state": 0,                    //状态
       "supportEntrustType": "",      //支持计划委托类型
       "supportOrderType": "",        //支持订单类型
       "supportPositionType": "",     //支持仓位类型
       "supportTimeInForce": "",      //支持有效方式
       "symbol": "",                  //交易对
       "symbolGroupId": 0,
       "takerFee": 0,                  //手续费
       "tradeSwitch": false,           //交易对开关
       "underlyingType": ""            //标的类型,币本位,u本位
     } 

  ],
  "returnCode": 0
}

查询单个交易对杠杆分层 Edit

/future/market/v1/public/leverage/bracket/detail

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "leverageBrackets": [
      {
        "bracket": 0, //档位
        "maintMarginRate": 0, //维持保证金率
        "maxLeverage": 0, //最大杠杆倍数
        "maxNominalValue": 0, //该层最大名义价值
        "maxStartMarginRate": 0, //最大起始保证金率
        "minLeverage": 0, //最小杠杆倍数
        "startMarginRate": 0, //起始保证金率
        "symbol": "" //交易对
      }
    ],
    "symbol": ""
  },
  "returnCode": 0
}

查询所有交易对杠杆分层 Edit

/future/market/v1/public/leverage/bracket/list

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "leverageBrackets": [
        {
          "bracket": 0, //档位
          "maintMarginRate": 0, //维持保证金率
          "maxLeverage": 0, //最大杠杆倍数
          "maxNominalValue": 0, //该层最大名义价值
          "maxStartMarginRate": 0, //最大起始保证金率
          "minLeverage": 0, //最小杠杆倍数
          "startMarginRate": 0, //起始保证金率
          "symbol": "" //交易对
        }
      ],
      "symbol": ""
    }
  ],
  "returnCode": 0
}

获取指定交易对的行情信息 Edit

/future/market/v1/public/q/ticker

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "a": "", //24小时成交量
    "c": "", //最新价
    "h": "", //24小时最高价
    "l": "", //24小时最低价
    "o": "", //24小时前第一笔成交价
    "r": "", //24小时涨跌幅
    "s": "", //交易对
    "t": 0, //时间
    "v": "" //24小时成交额
  },
  "returnCode": 0
}

获取全交易对的行情信息 Edit

/future/market/v1/public/q/tickers

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "a": "", //24小时成交量
      "c": "", //最新价
      "h": "", //24小时最高价
      "l": "", //24小时最低价
      "o": "", //24小时前第一笔成交价
      "r": "", //24小时涨跌幅
      "s": "", //交易对
      "t": 0, //时间
      "v": "" //24小时成交额
    }
  ],
  "returnCode": 0
}

获取交易对的最新成交信息 Edit

/future/market/v1/public/q/deal

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对
num integer true N/A 数量

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "a": 0, //成交量
      "m": "", //买卖方向
      "p": 0, //成交价
      "s": "", //交易对
      "t": 0 //成交时间
    }
  ],
  "returnCode": 0
}

获取交易对的深度信息 Edit

/future/market/v1/public/q/depth

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对
level integer true N/A 档位(min:1,max:50)

限流规则

1/s/ip
注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "a": [], //卖单
    "b": [], //买单
    "s": "", //交易对
    "t": 0, //时间
    "u": 0 //updateId
  },
  "returnCode": 0
}

获取单个交易对的指数价格 Edit

/future/market/v1/public/q/symbol-index-price

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "p": 0, //价格
    "s": "", //交易对
    "t": 0 //时间
  },
  "returnCode": 0
}

获取所有交易对的指数价格 Edit

/future/market/v1/public/q/index-price

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "p": 0, //价格
      "s": "", //交易对
      "t": 0 //时间
    }
  ],
  "returnCode": 0
}

获取单个交易对的标记价格 Edit

/future/market/v1/public/q/symbol-mark-price

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "p": 0, //价格
    "s": "", //交易对
    "t": 0 //时间
  },
  "returnCode": 0
}

获取所有交易对的标记价格 Edit

/future/market/v1/public/q/mark-price

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false N/A 交易对

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "p": 0, //价格
      "s": "", //交易对
      "t": 0 //时间
    }
  ],
  "returnCode": 0
}

获取交易对的k线信息 Edit

/future/market/v1/public/q/kline

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对
interval string true N/A 时间间隔 1m;5m;15m;30m;1h;4h;1d;1w
startTime integer false N/A 起始时间
endTime integer false N/A 结束时间
limit integer false N/A 限制条数

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "a": 0, //成交量
      "c": 0, //结束价
      "h": 0, //最高价
      "l": 0, //最低价
      "o": 0, //开始价
      "s": "", //交易对
      "t": 0, //时间
      "v": 0 //成交额
    }
  ],
  "returnCode": 0
}

获取指定交易对的聚合行情信息 Edit

/future/market/v1/public/q/agg-ticker

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "a": "", //24小时成交量
    "ap": "", //卖一价格
    "bp": "", //买一价格
    "c": "", //最新价
    "h": "", //24小时最高价
    "i": "", //指数价格
    "l": "", //24小时最低价
    "m": "", //标记价格
    "o": "", //24小时前第一笔成交价
    "r": "", //24小时涨跌幅
    "s": "", //交易对
    "t": 0, //时间
    "v": "" //24小时成交额
  },
  "returnCode": 0
}

获取全交易对的聚合行情信息 Edit

/future/market/v1/public/q/agg-tickers

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "a": "", //24小时成交量
      "ap": "", //卖一价格
      "bp": "", //买一价格
      "c": "", //最新价
      "h": "", //24小时最高价
      "i": "", //指数价格
      "l": "", //24小时最低价
      "m": "", //标记价格
      "o": "", //24小时前第一笔成交价
      "r": "", //24小时涨跌幅
      "s": "", //交易对
      "t": 0, //时间
      "v": "" //24小时成交额
    }
  ],
  "returnCode": 0
}

获取资金费率 Edit

/future/market/v1/public/q/funding-rate

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对

限流规则

1/s/ip
注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //是否有下一页
    "hasPrev": false, //是否有上一页
    "items": [ //数据列表
      {
        "collectionInternal": 0, //收取时间间隔(时)
        "createdTime": 0, //时间
        "fundingRate": 0, //最新资金费率
        "id": 0, //id
        "symbol": "" //交易对
      }
    ]
  },
  "returnCode": 0
}

获取指定交易对的买一卖一行情信息 Edit

/future/market/v1/public/q/ticker/book

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "ap": "", //卖一价格
    "aq": "", //卖一数量
    "bp": "", //买一价格
    "bq": "", //买一数量
    "s": "", //交易对
    "t": 0 //时间
  },
  "returnCode": 0
}

获取资金费率记录 Edit

/future/market/v1/public/q/funding-rate-record

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对
direction string false NEXT 方向(PREV:上一页;NEXT:下一页) PREV;NEXT
id integer false N/A id
limit integer false 10 条数

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //是否有下一页
    "hasPrev": false, //是否有上一页
    "items": [ //数据列表
      {
        "collectionInternal": 0, //收取时间间隔(秒)
        "createdTime": 0, //时间
        "fundingRate": 0, //最新资金费率
        "id": 0, //id
        "symbol": "" //交易对
      }
    ]
  },
  "returnCode": 0
}

获取全交易对的买一卖一行情信息 Edit

/future/market/v1/public/q/ticker/books

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "ap": "", //卖一价格
      "aq": "", //卖一数量
      "bp": "", //买一价格
      "bq": "", //买一数量
      "s": "", //交易对
      "t": 0 //时间
    }
  ],
  "returnCode": 0
}

获取交易对风险基金余额 Edit

/future/market/v1/public/contract/risk-balance

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 交易对
direction string false NEXT 方向(PREV:上一页;NEXT:下一页) PREV;NEXT
id integer false N/A id
limit integer false 10 条数

注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //是否有下一页
    "hasPrev": false, //是否有上一页
    "items": [ //数据列表
      {
        "amount": 0, //余额
        "coin": "", //币种
        "createdTime": 0, //时间
        "id": 0 //id
      }
    ]
  },
  "returnCode": 0
}

获取交易对开仓量 Edit

/future/market/v1/public/contract/open-interest

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对

限流规则

1/s/ip
注:此方法不需要签名

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "symbol": "", //交易对
    "openInterest": "", //开仓量
    "openInterestUsd": 0, //开仓价值
    "time": "", //时间
  },
  "returnCode": 0
}

获取合约信息 Edit

/future/market/v1/public/cg/contracts

Content-Type = application/x-www-form-urlencoded

Note:这个方法不需要签名.

[{
    "id": 123, 
    "ask": "1817.32",                 //当前最低价
    "base_currency": "ETH",           //标的币种,比如 BTC
    "base_volume": "13267684284",     //24小时交易量
    "bid": "1817.31",                 //当前最高价
    "contractSize": 10,               //合约面值
    "end_timestamp": 253402099200000, //该衍生品的终结时间
    "funding_rate": "-0.03",          //资金费率
    "high": "1828.89",                //24小时最高成交价
    "index_currency": "USD",          //指数的基础币种
    "index_name": "ETH-USD",          //基础指数的名称
    "index_price": "1816.61",         //基础指数价格
    "last_price": "1817.31",          //最新价格
    "low": "1778.65",                 //24小时最低成交价
    "next_funding_rate": "-0.03",     //预计下一个资金费率
    "next_funding_rate_timestamp":1698681600000,  //下一个资金费率时间
    "open_interest": "2419347630",    //24小时合约持仓量
    "product_type": "PERPETUAL",      //产品类型
    "start_timestamp": 1651328033000, //该衍生品的开始时间
    "symbol": "eth_usd",
    "target_currency": "USD",         //报价币种
    "target_volume": "73698647.51054371",  //24小时交易量
    "ticker_id": "ETH-USD",           //代码标识符
    "underlyingType": 1               //标的类型,币本位,u本位
  }]

获取交易对深度信息 Edit

/future/market/v1/public/cg/orderbook

Content-Type = application/x-www-form-urlencoded

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对,例如BTC-USDT
level int false 50 1-200

Note:这个方法不需要签名

{
          "ticker_id": "BTC-USDT", 
          "timestamp": 1698668957638,
          "bids": [[
               "34794.6",
               "97164"
              ],[
               "34794.5",
               "9897"
              ],...], 
          "asks": [[
               "34794.7",
               "168479"
              ],[
               "34794.8",
               "4009"
              ],...]
}

下单 Edit

/future/trade/v1/order/create

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
clientOrderId string false N/A 自定义订单id
symbol string true 交易对
orderSide string true N/A 买卖方向:BUY;SELL BUY;SELL
orderType string true N/A 订单类型:LIMIT;MARKET LIMIT;MARKET
origQty number true N/A 数量(张)
price number false N/A 价格
timeInForce string false GTC 有效方式:GTC;IOC;FOK;GTX GTC;IOC;FOK;GTX
triggerProfitPrice number false N/A 止盈价
triggerStopPrice number false N/A 止损价
positionSide string true N/A 仓位方向:LONG;SHORT LONG;SHORT

OrigQty 计算公式

公式

origQty = Truncate ((Balance * Percent * Leverage ) / (Mark_price * Contract_size))

解释
Truncate : 取整数部分 

Balance : (walletBalance - openOrderMarginFrozen) , api: /future/user/v1/compat/balance/list  

Percent : 用户输入 , 例如: 0.2 

Leverage : 杠杆倍数 , 例如: 20 

Mark_price : 市场标记价格 , 例如: 88888 (btc_usdt) 

Contract_size : 合约面值 , api: /future/market/v1/public/symbol/detail , Contract multiplier(face value)  
举例

truncate(10000 * 0.2 * 20 / 88888 / 0.0001) = 4500

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

查询历史订单 Edit

/future/trade/v1/order/list-history

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false N/A 交易对
direction string false NEXT 方向(PREV:上一页;NEXT:下一页) PREV;NEXT
id integer false N/A id
limit integer false 10 条数
startTime integer false N/A 起始时间
endTime integer false N/A 结束时间

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //是否有下一页
    "hasPrev": false, //是否有上一页
    "items": [ //数据列表
      {
        "clientOrderId": "", //自定义订单id
        "avgPrice": 0, //成交均价
        "closePosition": false, //是否条件全平仓
        "closeProfit": 0, //平仓盈亏
        "createdTime": 0, //创建时间
        "executedQty": 0, //已成交数量(张)
        "forceClose": false, //是否是强平订单
        "marginFrozen": 0, //占用保证金
        "orderId": 0, //订单id
        "orderSide": "", //买卖方向
        "orderType": "", //订单类型
        "origQty": 0, //数量(张)
        "positionSide": "", //持仓方向
        "price": 0, //委托价格
        "sourceId": 0, //条件触发id
        "state": "", //订单状态 NEW:新建订单(未成交);PARTIALLY_FILLED:部分成交;PARTIALLY_CANCELED:部分撤销;FILLED:全部成交;CANCELED:已撤销;REJECTED:下单失败;EXPIRED:已过期
        "symbol": "", //交易对
        "timeInForce": "", //有效类型
        "triggerProfitPrice": 0, //止盈触发价
        "triggerStopPrice": 0 //止损触发价
      }
    ]
  },
  "returnCode": 0
}

查询成交明细 Edit

/future/trade/v1/order/trade-list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderId integer false N/A 订单id
symbol string false N/A 交易对
page integer false 1 页码
size integer false 10 单页数
startTime integer false N/A 起始时间
endTime integer false N/A 结束时间

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "items": [
      {
        "fee": 0,               //手续费
        "feeCoin": "",          //手续费币种
        "orderId": 0,           //订单id
        "execId": 0,            //成交id
        "price": 0,             //成交价格
        "quantity": 0,          //成交数量
        "symbol": "",           //交易对
        "timestamp": 0,         //时间
        "takerMaker": "TAKER"   
      }
    ],
    "page": 0,
    "ps": 0,
    "total": 0
  },
  "returnCode": 0
}

改单 Edit

/future/trade/v1/order/update

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderId number true 订单id
price number true 目标价格
origQty number true 目标数量(张)
triggerProfitPrice number false N/A 止盈价格
triggerStopPrice number false N/A 止损价格
triggerPriceType string false LATEST_PRICE 触发价格类型 INDEX_PRICE(指数价格);MARK_PRICE(标记价格);LATEST_PRICE(最新价)
profitDelegateOrderType string false N/A 止盈委托订单类型 LIMIT(限价);MARKET(市价)
profitDelegateTimeInForce string false N/A 止盈委托有效方式 GTC;IOC;FOK;GTX
profitDelegatePrice number false N/A 止盈委托委托价格
stopDelegateOrderType string false N/A 止损委托订单类型 LIMIT(限价);MARKET(市价)
stopDelegateTimeInForce string false N/A 止损委托有效方式 GTC;IOC;FOK;GTX
stopDelegatePrice number false N/A 止损委托价格
followUpOrder boolean false N/A 如果为 true,则表示为追单订单

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

批量下单 Edit

/future/trade/v1/order/create-batch

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
list string true N/A 下单数据的list集合

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

根据id查询订单 Edit

/future/trade/v1/order/detail

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderId integer true N/A 订单id

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "avgPrice": 0, //成交均价
    "closePosition": false, //是否条件全平仓
    "closeProfit": 0, //平仓盈亏
    "createdTime": 0, //创建时间
    "executedQty": 0, //已成交数量(张)
    "forceClose": false, //是否是强平订单
    "marginFrozen": 0, //占用保证金
    "orderId": 0, //订单id
    "orderSide": "", //买卖方向
    "orderType": "", //订单类型
    "origQty": 0, //数量(张)
    "positionSide": "", //持仓方向
    "price": 0, //委托价格
    "sourceId": 0, //条件触发id
    "state": "", //订单状态 NEW:新建订单(未成交);PARTIALLY_FILLED:部分成交;PARTIALLY_CANCELED:部分撤销;FILLED:全部成交;CANCELED:已撤销;REJECTED:下单失败;EXPIRED:已过期
    "symbol": "", //交易对
    "timeInForce": "", //有效类型
    "triggerProfitPrice": 0, //止盈触发价
    "triggerStopPrice": 0 //止损触发价
  },
  "returnCode": 0
}

查询订单 Edit

/future/trade/v1/order/list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
clientOrderId String false N/A 自定义订单id
page integer false 1 页码
size integer false 10 单页数
startTime integer false N/A 开始时间
endTime integer false N/A 结束时间
state string false NEW 订单状态 NEW:新建订单(未成交);PARTIALLY_FILLED:部分成交;FILLED:全部成交;CANCELED:用户撤销;REJECTED:下单失败;EXPIRED:已过期;UNFINISHED:未完成;HISTORY:(历史)
symbol string false N/A 交易对

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "items": [
      {
        "clientOrderId": "", //自定义订单id
        "avgPrice": 0, //成交均价
        "closePosition": false, //是否条件全平仓
        "closeProfit": 0, //平仓盈亏
        "createdTime": 0, //创建时间
        "executedQty": 0, //已成交数量(张)
        "forceClose": false, //是否是全平订单
        "marginFrozen": 0, //占用保证金
        "orderId": 0, //订单id
        "orderSide": "", //买卖方向
        "orderType": "", //订单类型
        "origQty": 0, //数量(张)
        "positionSide": "", //持仓方向
        "price": 0, //委托价格
        "sourceId": 0, //条件触发id
        "state": "", //订单状态 NEW:新建订单(未成交);PARTIALLY_FILLED:部分成交;PARTIALLY_CANCELED:部分撤销;FILLED:全部成交;CANCELED:已撤销;REJECTED:下单失败;EXPIRED:已过期
        "symbol": "", //交易对
        "timeInForce": "", //有效类型
        "triggerProfitPrice": 0, //止盈触发价
        "triggerStopPrice": 0 //止损触发价
      }
    ],
    "page": 0,
    "ps": 0,
    "total": 0
  },
  "returnCode": 0
}

撤销订单 Edit

/future/trade/v1/order/cancel

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderId Integer true N/A 订单id

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": "", //订单id
  "returnCode": 0
}

撤销所有订单 Edit

/future/trade/v1/order/cancel-all

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol String true N/A 交易对(传空字符串撤销所有交易对订单)

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

创建计划委托 Edit

/future/trade/v1/entrust/create-plan

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
clientOrderId string false N/A 自定义订单id
symbol string true 交易对
orderSide string true N/A 买卖方向:BUY;SELL BUY;SELL
entrustType string true N/A 委托类型:TAKE_PROFIT(止盈限价单);STOP(止损限价单);TAKE_PROFIT_MARKET(止盈市价单);STOP_MARKET(止损市价单) TAKE_PROFIT;STOP;TAKE_PROFIT_MARKET;STOP_MARKET
origQty number true N/A 数量(张)
price number false N/A 价格
stopPrice number true N/A 触发价
timeInForce string true N/A 有效方式:GTC;IOC;FOK;GTX, 市价委托只支持IOC GTC;IOC;FOK;GTX
triggerPriceType string true N/A 触发价格类型:INDEX_PRICE(指数价格);MARK_PRICE(标记价格);LATEST_PRICE(最新价格) INDEX_PRICE;MARK_PRICE;LATEST_PRICE
positionSide string true N/A 仓位方向:LONG;SHORT LONG;SHORT

限流规则

200/s/apikey

{
    "error": {
    "code": "",
    "msg": ""
    },
    "msgInfo": "",
    "result": {},
    "returnCode": 0
}
title: Response
language: json

撤销计划委托 Edit

/future/trade/v1/entrust/cancel-plan

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
entrustId integer true N/A 计划委托id

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

撤销所有计划委托 Edit

/future/trade/v1/entrust/cancel-all-plan

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 交易对,例如btc_usdt

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

查询计划委托 Edit

/future/trade/v1/entrust/plan-list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对(不传时撤销所有交易对)
page integer false 1 页码
size integer false 10 单页数
startTime integer false N/A 开始时间
endTime integer false N/A 结束时间
state string true N/A 委托状态 NOT_TRIGGERED:新建委托(未触发);TRIGGERING:触发中;TRIGGERED:已触发;USER_REVOCATION:用户撤销;PLATFORM_REVOCATION:平台撤销(拒绝);EXPIRED:已过期;UNFINISHED:未完成;HISTORY:(历史) NOT_TRIGGERED;TRIGGERING;TRIGGERED;USER_REVOCATION;PLATFORM_REVOCATION;EXPIRED;UNFINISHED;HISTORY

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "items": [
      {
        "clientOrderId": "", //自定义订单id
        "closePosition": false, //是否触发全平
        "createdTime": 0, //创建时间
        "entrustId": 0, //委托id
        "entrustType": "", //委托类型
        "marketOrderLevel": 0, //市价最优档
        "orderSide": "", //买卖方向
        "ordinary": true,
        "origQty": 0, //数量(张)
        "positionSide": "", //持仓方向
        "price": 0, //订单价格
        "state": "", //订单状态 NOT_TRIGGERED:新建委托(未触发);TRIGGERING:触发中;TRIGGERED:已触发;USER_REVOCATION:用户撤销;PLATFORM_REVOCATION:平台撤销(拒绝);EXPIRED:已过期
        "stopPrice": 0, //触发价格
        "symbol": "", //交易对
        "timeInForce": "", //有效方式
        "triggerPriceType": "" //触发价格类型
      }
    ],
    "page": 0,
    "ps": 0,
    "total": 0
  },
  "returnCode": 0
}

根据entrustId查询计划委托 Edit

/future/trade/v1/entrust/plan-detail

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
entrustId integer true N/A 委托id

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "closePosition": false, //是否触发全平
    "createdTime": 0, //创建时间
    "entrustId": 0, //委托id
    "entrustType": "", //委托类型
    "marketOrderLevel": 0, //市价最优档
    "orderSide": "", //买卖方向
    "ordinary": true,
    "origQty": 0, //数量(张)
    "positionSide": "", //持仓方向
    "price": 0, //订单价格
    "state": "", //订单状态 NOT_TRIGGERED:新建委托(未触发);TRIGGERING:触发中;TRIGGERED:已触发;USER_REVOCATION:用户撤销;PLATFORM_REVOCATION:平台撤销(拒绝);EXPIRED:已过期
    "stopPrice": 0, //触发价格
    "symbol": "", //交易对
    "timeInForce": "", //有效方式
    "triggerPriceType": "" //触发价格类型
  },
  "returnCode": 0
}

查询历史计划委托 Edit

/future/trade/v1/entrust/plan-list-history

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对(不传时撤销所有交易对)
direction string false NEXT 方向(PREV:上一页;NEXT:下一页) PREV;NEXT
id integer false N/A id
limit integer false 10 条数
startTime integer false N/A 起始时间
endTime integer false N/A 结束时间

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //是否有下一页
    "hasPrev": false, //是否有上一页
    "items": [ //数据列表
      {
        "clientOrderId": "", //自定义订单id
        "closePosition": false, //是否触发全平
        "createdTime": 0, //创建时间
        "entrustId": 0, //委托id
        "entrustType": "", //委托类型
        "marketOrderLevel": 0, //市价最优档
        "orderSide": "", //买卖方向
        "ordinary": true,
        "origQty": 0, //数量(张)
        "positionSide": "", //持仓方向
        "price": 0, //订单价格
        "state": "", //订单状态 NOT_TRIGGERED:新建委托(未触发);TRIGGERING:触发中;TRIGGERED:已触发;USER_REVOCATION:用户撤销;PLATFORM_REVOCATION:平台撤销(拒绝);EXPIRED:已过期
        "stopPrice": 0, //触发价格
        "symbol": "", //交易对
        "timeInForce": "", //有效方式
        "triggerPriceType": "" //触发价格类型
      }
    ]
  },
  "returnCode": 0
}

创建止盈止损 Edit

/future/trade/v1/entrust/create-profit

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对
origQty integer true 数量(张)
triggerProfitPrice integer true 止盈触发价
triggerStopPrice integer true 止损触发价
expireTime integer true 过期时间
positionSide string true 仓位方向:LONG;SHORT LONG;SHORT

限流规则

200/s/apikey

{
    "error": {
    "code": "",
    "msg": ""
    },
    "msgInfo": "",
    "result": {},
    "returnCode": 0
}
title: Response
language: json

撤销止盈止损 Edit

/future/trade/v1/entrust/cancel-profit-stop

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
profitId integer true N/A 止盈止损id

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

撤销所有止盈止损 Edit

/future/trade/v1/entrust/cancel-all-profit-stop

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 交易对,例如btc_usdt

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

查询止盈止损 Edit

/future/trade/v1/entrust/profit-list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对(不传时撤销所有交易对)
page integer false 1 页码
size integer false 10 单页数
startTime integer false N/A 开始时间
endTime integer false N/A 结束时间
state string true N/A 委托状态 NOT_TRIGGERED:新建委托(未触发);TRIGGERING:触发中;TRIGGERED:已触发;USER_REVOCATION:用户撤销;PLATFORM_REVOCATION:平台撤销(拒绝);EXPIRED:已过期;UNFINISHED:未完成;HISTORY:(历史) NOT_TRIGGERED;TRIGGERING;TRIGGERED;USER_REVOCATION;PLATFORM_REVOCATION;EXPIRED;UNFINISHED;HISTORY

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "items": [
      {
        "createdTime": 0, //时间
        "entryPrice": 0, //开仓均价
        "executedQty": 0, //实际成交
        "isolatedMargin": 0, //逐仓保证金
        "origQty": 0, //数量(张)
        "positionSide": "", //仓位方向
        "positionSize": 0, //持仓数量(张)
        "profitId": 0, //委托id
        "state": "", //订单状态 NOT_TRIGGERED:新建委托(未触发);TRIGGERING:触发中;TRIGGERED:已触发;USER_REVOCATION:用户撤销;PLATFORM_REVOCATION:平台撤销(拒绝);EXPIRED:已过期
        "symbol": "", //交易对
        "triggerProfitPrice": 0, //止盈价格
        "triggerStopPrice": 0 //止损价格
      }
    ],
    "page": 0,
    "ps": 0,
    "total": 0
  },
  "returnCode": 0
}

根据profitId查询止盈止损 Edit

/future/trade/v1/entrust/profit-detail

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
profitId integer true N/A 止盈止损id

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "createdTime": 0, //时间
    "entryPrice": 0, //开仓均价
    "executedQty": 0, //实际成交
    "isolatedMargin": 0, //逐仓保证金
    "origQty": 0, //数量(张)
    "positionSide": "", //仓位方向
    "positionSize": 0, //持仓数量(张)
    "profitId": 0, //委托id
    "state": "", //订单状态 NOT_TRIGGERED:新建委托(未触发);TRIGGERING:触发中;TRIGGERED:已触发;USER_REVOCATION:用户撤销;PLATFORM_REVOCATION:平台撤销(拒绝);EXPIRED:已过期
    "symbol": "", //交易对
    "triggerProfitPrice": 0, //止盈价格
    "triggerStopPrice": 0 //止损价格
  },
  "returnCode": 0
}

修改止盈止损 Edit

/future/trade/v1/entrust/update-profit-stop

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
profitId integer true N/A 止盈止损id
triggerProfitPrice number false N/A 止盈触发价s
triggerStopPrice number false N/A 止损触发价

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

创建跟踪委托 Edit

/future/trade/v1/entrust/create-track

Content-Type = application/x-www-form-urlencoded

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
callback string true N/A 回调幅度配置:FIXED(固定);PROPORTION(比例) FIXED;PROPORTION
callbackVal number true N/A 回调幅度配置值 大于0
orderSide string true N/A 订单方向 BUY;SELL
origQty number true N/A 数量(张)
positionSide string true N/A 持仓方向 BOTH;LONG;SHORT
positionType string true N/A 仓位模式:CROSSED(全仓),ISOLATED(逐仓) CROSSED;ISOLATED
symbol string true N/A 交易对
triggerPriceType string true N/A 触发价格类型:INDEX_PRICE(指数价格);MARK_PRICE(标记价格);LATEST_PRICE(最新价格) INDEX_PRICE;MARK_PRICE;LATEST_PRICE
activationPrice number false N/A 激活价格
clientMedia string false N/A 客户端媒体
clientMediaChannel string false N/A 客户端媒体渠道
clientOrderId string false N/A 客户端ID
expireTime integer false N/A 过期时间

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

撤销跟踪委托(单个) Edit

/future/trade/v1/entrust/cancel-track

Content-Type = application/x-www-form-urlencoded

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
trackId integer true N/A 跟踪委托id

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

查询单个跟踪委托 Edit

/future/trade/v1/entrust/track-detail

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
trackId integer true N/A 跟踪委托id

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "activationPrice": 0,      //激活价格,如果没有配置,则用当前价格为激活价格
    "avgPrice": 0,             //实际成交均价
    "callback": "",            //回调幅度配置 1比例 2固定
    "callbackVal": 0,          //回调幅度配置值,大于0
    "configActivation": false, //是否配置激活价格
    "createdTime": 0,          //创建时间
    "currentPrice": 0,         //下单时对应类型的实时价格,激活价格和下单行情价格比较,判断激活价格的方向
    "desc": "",                //描述,撤销、委托失败等描述
    "executedQty": 0,          //实际成交数量
    "orderSide": "",           //买卖方向
    "ordinary": true,          //
    "origQty": 0,              //数量(张)
    "positionSide": "",        //持仓方向
    "price": 0,                //订单价格
    "state": "",               //订单状态 NOT_ACTIVATION: 未激活;NOT_TRIGGERED:新建委托(未触发);TRIGGERING:触发中;TRIGGERED:已触发;USER_REVOCATION:用户撤销;PLATFORM_REVOCATION:平台撤销(拒绝);EXPIRED:已过期;DELEGATION_FAILED: 委托失败
    "stopPrice": 0,            //触发价格
    "symbol": "",              //交易对
    "trackId": 0,              //跟踪委托id
    "triggerPriceType": "",    //触发价格类型
    "updatedTime": 0           //更新时间
  },
  "returnCode": 0
}

查询跟踪委托(所有活跃) Edit

/future/trade/v1/entrust/track-list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
page integer false 1 页码
size integer false 10 单页数
endTime integer false N/A
startTime integer false N/A 起始时间
symbol string false N/A 交易对

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    items:[
      "activationPrice": 0,      //激活价格,如果没有配置,则用当前价格为激活价格
      "avgPrice": 0,             //实际成交均价
      "callback": "",            //回调幅度配置 1比例 2固定
      "callbackVal": 0,          //回调幅度配置值,大于0
      "configActivation": false, //是否配置激活价格
      "createdTime": 0,          //创建时间
      "currentPrice": 0,         //下单时对应类型的实时价格,激活价格和下单行情价格比较,判断激活价格的方向
      "desc": "",                //描述,撤销、委托失败等描述
      "executedQty": 0,          //实际成交数量
      "orderSide": "",           //买卖方向
      "ordinary": true,          //
      "origQty": 0,              //数量(张)
      "positionSide": "",        //持仓方向
      "price": 0,                //订单价格
      "state": "",               //订单状态 NOT_ACTIVATION: 未激活;NOT_TRIGGERED:新建委托(未触发);TRIGGERING:触发中;TRIGGERED:已触发;USER_REVOCATION:用户撤销;PLATFORM_REVOCATION:平台撤销(拒绝);EXPIRED:已过期;DELEGATION_FAILED: 委托失败
      "stopPrice": 0,            //触发价格
      "symbol": "",              //交易对
      "trackId": 0,              //跟踪委托id
      "triggerPriceType": "",    //触发价格类型
      "updatedTime": 0           //更新时间
    ],
    page: 1,                     //页码
    ps: 10,                      //一页数量
    total: 20                    //总量
  },
  "returnCode": 0
}

撤销所有跟踪委托 Edit

/future/trade/v1/entrust/cancel-all-track

Content-Type = application/x-www-form-urlencoded

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

查询历史跟踪委托(非活跃) Edit

/future/trade/v1/entrust/track-list-history

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
direction string false NEXT 方向(PREV:上一页;NEXT:下一页) PREV;NEXT
limit integer false 10 条数
id integer false N/A
endTime integer false N/A 结束时间
startTime integer false N/A 起始时间
state string false N/A 订单状态 NOT_ACTIVATION;NOT_TRIGGERED;TRIGGERING;TRIGGERED;USER_REVOCATION;PLATFORM_REVOCATION;EXPIRED;DELEGATION_FAILED
symbol string false N/A 交易对

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    hasNext: true,               //是否有下一页
    hasPre: true,                //是否有上一页
    items:[
      "activationPrice": 0,      //激活价格,如果没有配置,则用当前价格为激活价格
      "avgPrice": 0,             //实际成交均价
      "callback": "",            //回调幅度配置 1比例 2固定
      "callbackVal": 0,          //回调幅度配置值,大于0
      "configActivation": false, //是否配置激活价格
      "createdTime": 0,          //创建时间
      "currentPrice": 0,         //下单时对应类型的实时价格,激活价格和下单行情价格比较,判断激活价格的方向
      "desc": "",                //描述,撤销、委托失败等描述
      "executedQty": 0,          //实际成交数量
      "orderSide": "",           //买卖方向
      "ordinary": true,          //
      "origQty": 0,              //数量(张)
      "positionSide": "",        //持仓方向
      "price": 0,                //订单价格
      "state": "",               //订单状态 NOT_ACTIVATION: 未激活;NOT_TRIGGERED:新建委托(未触发);TRIGGERING:触发中;TRIGGERED:已触发;USER_REVOCATION:用户撤销;PLATFORM_REVOCATION:平台撤销(拒绝);EXPIRED:已过期;DELEGATION_FAILED: 委托失败
      "stopPrice": 0,            //触发价格
      "symbol": "",              //交易对
      "trackId": 0,              //跟踪委托id
      "triggerPriceType": "",    //触发价格类型
      "updatedTime": 0           //更新时间
    ]
  },
  "returnCode": 0
}

获取合约账户资产 Edit

/future/user/v1/compat/balance/list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
queryAccountId string false N/A 账户id

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
        "accountId": 500000000000, // 账户id
        "userId": 500000000000, // 用户id
        "coin": "usdt", // 币种
        "underlyingType": 2, // 币本位,u本位
        "walletBalance": "2078.57264793", // 币种余额
        "openOrderMarginFrozen": "0", // 订单冻结
        "isolatedMargin": "0", // 保证金冻结
        "crossedMargin": "0", // 全仓保证金冻结
        "amount": "2078.57264793", // 净资产余额
        "totalAmount": "2078.57264793", // 保证金余额
        "convertBtcAmount": "0.03638940", // walletBalance钱包资产折算 BTC
        "convertUsdtAmount": "2078.5726", // walletBalance钱包资产折算 USDT
        "profit": "0", // 已盈亏
        "notProfit": "0", // 未实现盈亏
        "bonus": "0", // 体验金
        "coupon": "0" // 抵扣金
    }
 ],
  "returnCode": 0

获取账户相关信息 Edit

/future/user/v1/account/info

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "accountId": 0, //帐户id
    "allowOpenPosition": false, //是否可开仓
    "allowTrade": false, //是否可以交易
    "allowTransfer": false, //是否可以划转
    "openTime": "", //开通时间
    "state": 0, //用户状态
    "userId": 0 //用户id
  },
  "returnCode": 0
}

获取listenKey Edit

/future/user/v1/user/listen-key

注:有效时间为8小时

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

开通合约 Edit

/future/user/v1/account/open

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

获取用户单币种资金 Edit

/future/user/v1/balance/detail

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
coin string true N/A 币种

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "availableBalance": 0,      //可用余额
    "coin": "",                 //币种
    "isolatedMargin": 0,        //逐仓保证金冻结
    "openOrderMarginFrozen": 0, //订单冻结
    "crossedMargin": 0,         //全仓起始保证金
    "bonus": 0,                 //体验金余额
    "coupon": 0,                //抵扣金余额
    "walletBalance": 0          //钱包余额
  },
  "returnCode": 0
}

获取用户资金 Edit

/future/user/v1/balance/list

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "availableBalance": 0,      //可用余额
      "coin": "",                 //币种
      "isolatedMargin": 0,        //逐仓保证金冻结
      "openOrderMarginFrozen": 0, //订单冻结
      "crossedMargin": 0,         //全仓起始保证金
      "bonus": 0,                 //体验金余额
      "coupon": 0,                //抵扣金余额
      "walletBalance": 0          //钱包余额
    }
  ],
  "returnCode": 0
}

获取用户账务流水 Edit

/future/user/v1/balance/bills

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对
direction string false NEXT 方向(PREV:上一页;NEXT:下一页) PREV;NEXT
id integer false N/A id
limit integer false 10 条数
startTime integer false N/A 起始时间
endTime integer false N/A 结束时间

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //是否有下一页
    "hasPrev": false, //是否有上一页
    "items": [ //数据列表
      {
        "afterAmount": 0, //变动后余额
        "amount": 0, //数量
        "coin": "", //币种
        "createdTime": 0, //时间
        "id": 0, //id
        "side": "", //ADD:划入;SUB:转出
        "symbol": "", //交易对
        "type": "" //EXCHANGE:划转;CLOSE_POSITION:平仓盈亏;TAKE_OVER:仓位接管;QIANG_PING_MANAGER:强平管理费(手续费);FUND:资金费用;FEE:手续费 (开仓、平仓、强平);ADL:自动减仓;TAKE_OVER:仓位接管MERGE:仓位合并
      }
    ]
  },
  "returnCode": 0
}

获取资金费用 Edit

/future/user/v1/balance/funding-rate-list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false N/A 交易对
direction string false NEXT 方向(PREV:上一页;NEXT:下一页) PREV;NEXT
id integer false N/A id
limit integer false 10 条数
startTime integer false N/A 起始时间
endTime integer false N/A 结束时间

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {
    "hasNext": false, //是否有下一页
    "hasPrev": false, //是否有上一页
    "items": [ //数据列表
      {
        "cast": 0, //资金费用
        "coin": "", //币种
        "createdTime": 0, //时间
        "id": 0, //id
        "positionSide": "", //方向
        "symbol": "" //交易对
      }
    ]
  },
  "returnCode": 0
}

获取活跃持仓信息 Edit

/future/user/v1/position

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false N/A 交易对(不传时查询所有交易对的持仓信息)

限流规则

200/s/apikey

{
  "error": {
    "args": [],
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "autoMargin": false, // 是否自动追加保证金
      "availableCloseSize": 0, // 可平仓数量(张)
      "breakPrice": 0, // 爆仓价格
      "calMarkPrice": 0, // 计算标记价格
      "closeOrderSize": 0, // 平仓挂单数量(张)
      "contractType": "", // 合约类型:PERPETUAL(永续合约)、PREDICT(预测合约)
      "entryPrice": 0, // 开仓均价
      "floatingPL": 0, // 未实现盈亏
      "isolatedMargin": 0, // 逐仓保证金
      "leverage": 0, // 杠杆倍数
      "openOrderMarginFrozen": 0, // 开仓订单保证金占用
      "openOrderSize": 0, // 开仓订单占用
      "positionSide": "", // 持仓方向
      "positionSize": 0, // 持仓数量(张)
      "positionType": "", // 仓位类型:CROSSED(全仓);ISOLATED(逐仓)
      "profitId": 0, // 止盈止损id
      "realizedProfit": 0, // 已实现盈亏
      "symbol": "", // 交易对
      "triggerPriceType": "", // 触发价格类型 1、指数价格2:标记价格(合理价格);3:最新价
      "triggerProfitPrice": 0, // 止盈触发价
      "triggerStopPrice": 0, // 止损触发价
      "welfareAccount": true
    }
  ],
  "returnCode": 0
}

获取持仓信息 Edit

/future/user/v1/position/list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false N/A 交易对(不传时查询所有交易对的持仓信息)

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "autoMargin": false, //是否自动追加保证金
      "availableCloseSize": 0, //可平仓数量(张)
      "closeOrderSize": 0, //平仓挂单数量(张)
      "entryPrice": 0, //开仓均价
      "isolatedMargin": 0, //逐仓保证金
      "leverage": 0, //杠杆倍数
      "openOrderMarginFrozen": 0, //开仓订单保证金占用
      "positionSide": "", //持仓方向
      "positionSize": 0, //持仓数量(张)
      "positionType": "", //仓位类型
      "realizedProfit": 0, //已实现盈亏
      "symbol": "" //交易对
    }
  ],
  "returnCode": 0
}

获取用户阶梯费率 Edit

/future/user/v1/user/step-rate

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "success",
  "result": {
    "makerFee":"0.00004",
    "takerFee": "0.00001"
  },
  "returnCode": 0
}

调整杠杆倍数 Edit

/future/user/v1/position/adjust-leverage

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对
positionSide string true N/A 仓位方向 LONG;SHORT
leverage integer true N/A 杠杆倍数

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

修改保证金 Edit

/future/user/v1/position/margin

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对
margin number false N/A 数量
positionSide string false N/A 持仓方向:LONG;SHORT
type string false N/A 调整方向(ADD:增加逐仓保证金;SUB:减少逐仓保证金) ADD;SUB

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

一键平仓 Edit

/future/user/v1/position/close-all

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

获取ADL信息 Edit

/future/user/v1/position/adl

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "longQuantile": 0, //多头adl
      "shortQuantile": 0, //空头adl
      "symbol": "" //交易对
    }
  ],
  "returnCode": 0
}

收藏交易对 Edit

/future/user/v1/user/collection/add

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

取消收藏交易对 Edit

/future/user/v1/user/collection/cancel

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": true,
  "returnCode": 0
}

收藏交易对列表 Edit

/future/user/v1/user/collection/list

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [],
  "returnCode": 0
}

修改持仓模式 Edit

/future/user/v1/position/change-type

Content-Type = application/x-www-form-urlencoded && application/json

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true N/A 交易对
positionSide string true N/A 仓位方向 LONG;SHORT
positionType string true N/A 仓位类型 CROSSED;ISOLATED

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": {},
  "returnCode": 0
}

获取持仓爆仓信息 Edit

/future/user/v1/position/break-list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false N/A 交易对(不传时查询所有交易对的持仓爆仓信息)

限流规则

200/s/apikey

{
  "error": {
    "code": "",
    "msg": ""
  },
  "msgInfo": "",
  "result": [
    {
      "breakPrice": 0,    //爆仓价格,0代表不爆仓
      "calMarkPrice": 0,  //计算标记价格
      "contractType": "", //合约类型:PERPETUAL(永续合约)、PREDICT(预测合约)
      "entryPrice": 0,    //开仓均价
      "isolatedMargin": 0,//逐仓保证金
      "leverage": 0,      //杠杆倍数
      "positionSide": "", //持仓方向
      "positionSize": 0,  //持仓数量(张)
      "positionType": "", //仓位类型:CROSSED(全仓);ISOLATED(逐仓)
      "symbol": ""        //交易对
    }
  ],
  "returnCode": 0
}

基本信息 Edit

基地址

wss://fstream.xt.com/ws/market

Request Headers

请求头必须添加压缩扩展协议。

Sec-Websocket-Extensions:permessage-deflate

请求报文格式 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”,服务端在30秒内没有收到客户端的ping消息,会主动断开链接

订阅参数 Edit

结构

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

Orderbook 维护 Edit

如何正确在本地维护一个orderbook副本

1.订阅 wss://fstream.xt.com/ws/market,depth_update@btc_usdt

2.开始缓存收到的更新。同一个价位,后收到的更新覆盖前面的。

3.访问Rest接口 https://fapi(或dapi).xt.com/future/market/v1/public/q/depth?symbol=btc_usdt&level=500 获得一个500档的深度快照

4.将目前缓存到的信息中u <= 步骤3中获取到的快照中的lastUpdateId的部分丢弃(丢弃更早的信息,已经过期)。

5.将深度快照中的内容更新到本地orderbook副本中,并从websocket接收到的第一个fu <= lastUpdateId+1 且 u >= lastUpdateId+1 的event开始继续更新本地副本。

6.每一个新event的fu应该恰好等于上一个event的u+1,否则可能出现了丢包,请从step3重新进行初始化。

7.每一个event中的挂单量代表这个价格目前的挂单量绝对值,而不是相对变化。

8.如果某个价格对应的挂单量为0,表示该价位的挂单已经撤单或者被吃,应该移除这个价位。

注意: 因为深度快照对价格档位数量有限制,初始快照之外的价格档位并且没有数量变化的价格档位不会出现在增量深度的更新信息内。因此,即使应用来自增量深度的所有更新,这些价格档位也不会在本地 order book 中可见, 所以本地的 order book 与真实的 order book 可能会有一些差异。 不过对于大多数用例,500 的深度限制足以有效地了解市场和交易。

成交记录 Edit

请求

语法: trade@{symbol}

示例: trade@btc_usdt

速率: 实时

{
    "topic": "trade", 
    "event": "trade@btc_usdt", 
    "data": {
        "s":"btc_index", //交易对
        "p":"50000",    //价格
        "a":"0.1"   //数量
        "m": "BID"   //成交方向  BID  ASK卖
        "t":123124124   //时间戳
    }
}

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

速率: 1000ms

 

{
        "topic": "kline",
        "event": "kline@btc_usdt,5m",
            "data": {
                "s":"btc_index", //交易对
                "o":"49000", // open 开盘价
                "c":"50000",    //cloes 收盘价
                "h":"0.1", //high 最高价
                "l":"0.1", //low 最低价
                "a":"0.1", //amount 成交量
                "v":"0.1", //volume 成交额
                "ch":"0.21",   //change 涨跌幅
                "t":123124124   //时间戳
            }
}

ticker Edit

请求

语法: ticker@{symbol}

示例: ticker@btc_usdt

速率: 1000ms

{
    "topic": "ticker", 
    "event": "ticker@btc_usdt", 
    "data": {
        "s":"btc_index", //交易对
        "o":"49000", // open 开盘价
        "c":"50000",    //cloes 收盘价
        "h":"0.1", //high 最高价
        "l":"0.1", //low 最低价
        "a":"0.1", //amount 成交量
        "v":"0.1", //volume 成交额
        "ch":"0.21"   //change 涨跌幅
        "t":123124124   //时间戳
    }
}

agg ticker Edit

请求

语法: agg_ticker@{symbol}

示例: agg_ticker@btc_usdt

速率: 1000ms

{
    "topic": "agg_ticker", 
    "event": "agg_ticker@btc_usdt", 
    "data": {
        "s":"btc_index", //交易对
        "o":"49000",     // open 开盘价
        "c":"50000",    //cloes 收盘价
        "h":"0.1",      //high 最高价
        "l":"0.1",       //low 最低价
        "a":"0.1",      //amount 成交量
        "v":"0.1",       //volume 成交额
        "ch":"0.21",   //change 涨跌幅

        "i":"0.21" ,   //index 指数价格

        "m":"0.21",   //mark 标记价格

        "bp":"0.21",   //bid price 买一价格

        "ap":"0.21" ,  //ask price 卖一价格

        "t":123124124   //时间戳
    }
}

指数价格 Edit

请求

语法: index_price@{symbol}

示例: index_price@btc_usdt

速率: 1000ms

{
    "topic": "index_price", 
    "event": "index_price@btc_usdt", 
    "data": {
        "s":"btc_usdt", //交易对
        "p":"50000",    //价格
        "t":123124124   //时间戳
    }
}

标记价格 Edit

请求

语法: mark_price@{symbol}

示例: mark_price@btc_usdt

速率: 1000ms

{
    "topic": "mark_price", 
    "event": "mark_price@btc_usdt", 
    "data": {
        "s":"btc_usdt", //交易对
        "p":"50000",    //价格
        "t":123124124   //时间戳
    }
}

增量深度 Edit

请求

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

interval: 100/250/500/1000 默认速率100ms

示例: depth_update@btc_usdt,100ms

{
    "topic": "depth_update", 
    "event": "depth_update@btc_usdt", 
    "data": {
        "s": "btc_usdt",        // symbol 交易对
        "pu": 120,              // previousUpdateId 等于上一次推送的lastUpdateId
        "fu": 121,              // firstUpdateId 等于上一次推送的lastUpdateId + 1
        "u": 123,               // lastUpdateId
        "a": [                  // asks 卖盘
            [                   // [0]价格, [1]数量
                "34000",        //价格
                "1.2"           //数量
            ], 
            [
                "34001", 
                "2.3"
            ]
        ], 
        "b": [                  // bids 买盘
            [
                "32000", 
                "0.2"
            ], 
            [
                "31000", 
                "0.5"
            ]
        ],
        "t": 123456789 // 时间戳
    }
}

有限深度 Edit

请求

 

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

levels: 5/10/20/50

interval: 100/250/500/1000 默认速率1000ms

示例: depth@btc_usdt,50,1000ms

{
    "topic": "depth", 
    "event": "depth@btc_usdt,50", 
    "data": {
        "id": "1234", //lastUpdateId
        "s":"btc_index", //交易对
        "a":[["50000","0.1"],["50001","0.2"]],    //ask 卖单队列, [价格,数量]
        "b":[["49999","0.1"],["48888","0.2"]],   //bid 买单队列
        "t": 123456789 // 时间戳
    }
}

资金费率 Edit

请求

语法: fund_rate@{symbol}

示例: fund_rate@btc_usdt

速率: 60s

{
    "topic": "fund_rate", 
    "event": "fund_rate@btc_usdt", 
    "data": {
        "s":"btc_usdt", //交易对
        "r":"0.01",    // 资金费率
        "t":123124124   //时间戳
    }
}

基本信息 Edit

基地址

wss://fstream.xt.com/ws/user

Request Headers

请求头必须添加压缩扩展协议。

Sec-Websocket-Extensions:permessage-deflate

订阅步骤

第一步:用户要先调用接口:/v1/user/listen-key 获取listenKey
第二步:订阅用户相关的websocket事件时需要发送:{“method”:”SUBSCRIBE”,”params”:[“order@{上一步获取的listenKey}”],”id”:”test1”}
如果收到”invalid_listen_key”表示listenKey过期或者无效,需要重新请求获取listenKey
ps:listenKey通过接口获取
订阅之后会推送用户相关数据

请求报文格式 Edit

subscribe:

  {
   "method": "SUBSCRIBE/UNSUBSCRIBE",
   "params": [
          "{order}@{listenKey}",
          "{trade}@{listenKey}",
          "{balance}@{listenKey}",
          "{position}@{listenKey}",
          "{notify}@{listenKey}"
        ],
   "id": "{id}"    //用户自己定义
   }
{"method":"SUBSCRIBE",
 "params":["order@A246C3DF8EE532DC75007BC5D86698541678596355681"],
 "id":"test1"
}

响应报文格式 Edit

{"id":"123", "code": 0, "msg": "success"}   
{"id":"123", "code": 401, "msg": "token expire"}

订阅参数 Edit

结构

{topic}@{listenKey},…

余额变更 Edit

subscribe:

  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{balance}@{listenKey}",
      ],
     "id": "{id}"
  }
{
    "topic": "balance", 
    "event": "balance@123456", 
    "data": {
         "coin":"usdt",
         "underlyingType":1, //  1:币本位,2:U本位
         "walletBalance":"123", // 钱包余额
         "openOrderMarginFrozen":"123", // 订单冻结
         "isolatedMargin":"213",  // 逐仓保证金
         "crossedMargin":"0" //全仓保证金
       }  
}

仓位变更 Edit

subscribe:

  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{position}@{listenKey}",
      ],
     "id": "{id}"
  }
{
    "topic": "position", 
    "event": "position@123456", 
    "data": {
           "symbol":"btc_usdt",
           "contractType": "PERPUTUAL", //合约类型,PERPUTUAL,DELIVERY
           "positionType": "ISOLATED",  // "ISOLATED", "CROSSED"
           "positionSide": "LONG",
           "positionSize":"123",  // 持仓数量
           "closeOrderSize": "100",  //  平仓挂单数量
           "availableCloseSize": "23",  //  可平仓张数
           "realizedProfit": "123"   //  已实现盈亏
           "entryPrice":"213",   //  开仓均价
           "isolatedMargin":"213",  //  逐仓保证金
           "openOrderMarginFrozen": "123", //  开仓订单占用保证金
           "underlyingType": ""// COIN_BASED, U_BASED
           "leverage":20  // 杠杆倍数
       }
}

用户成交 Edit

subscribe:

  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{trade}@{listenKey}",
      ],
     "id": "{id}"
  }
{
    "topic": "trade", 
    "event": "trade@123456", 
    "data": {
            "orderId":"12312312",     // 订单id
            "clientOrderId":"123456", // 自定义订单id
            "price":"34244",          // 价格
            "quantity":"123",         // 数量
            "marginUnfrozen":"123",   // 保证金解冻数量
            "timestamp":1731231231,   // 时间戳
            "symbol": "btc_usdt",     //交易对
            "orderSide": "BUY",       //订单方向
            "positionSide": "LONG",   //持仓方向
            "isMaker": true,          //是否是maker,true:maker;false:taker
            "fee": 0.0002             //手续费
       }
}

用户订单 Edit

subscribe:

  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{order}@{listenKey}",
      ],
     "id": "{id}"
  }
{
    "topic": "order", 
    "event": "order@123456", 
    "data": {
         "symbol":"btc_usdt",        // 交易对
         "orderId": "1234",          // 订单id
         "origQty": "34244",         // 下单数量
         "avgPrice": "123",          // 成交均价
         "price": "1111",            // 下单价格
         "executedQty":"34244",      // 已成交数量
         "orderSide": "BUY",         // 买卖方向
         "positionSide": "LONG",     // LONG, SHORT
         "marginFrozen":"123",       // 占用保证金
         "sourceType":"default",     // DEFAULT:普通订单, ENTRUST:计划委托,PROFIR:止盈止损
         "type" : "ORDER",           // 
         "state": "",                // 订单状态 NEW:新建订单;未成交; PARTIALLY_FILLED:部分成交;PARTIALLY_CANCELED:部分撤销;FILLED:全部成交;CANCELED:已撤销;REJECTED:下单失败;EXPIRED:已过期
         "createdTime": 1731231231,   // 下单时间
         "leverage":20,              // 杠杆倍数
         "positionType": "ISOLATED", // 仓位类型:CROSSED(全仓);ISOLATED(逐仓)
         "orderType:": "MARKET"      // 订单类型 LIMIT:限价, MARKET:市价
       }
}

用户消息 Edit

subscribe:

  {
     "method": "SUBSCRIBE/UNSUBSCRIBE",
     "params": [
         "{notify}@{listenKey}",
      ],
     "id": "{id}"
  }
{
    "topic": "notify", 
    "event": "notify", 
    "data": {
           "symbol":"btc_usdt",
           "positionType": "ISOLATED",  
           "positionSide": "LONG",
           "positionSize":"123",  // 持仓数量
           "notifyType": "WARN",  // 通知类型:  WARN:告警,即将被强平,PARTIAL:部分强平,LIQUIDATION:全部强平,ADL:自动减仓
    }
}

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,therefore, the issue of data security needs to be considered. Such as whether the data has been tampered with, whether the data is outdated, whether the data can be submitted repeatedly, and the access frequency of the interface, and whether data has been tampered with is the most important issue.

  1. Please apply for appkey and secretkey in the user center first, each user’s appkey and secretkey are different.

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

  3. Add signature, its value is obtained by a certain rule of signature algorithm.

  4. Add recvwindow (defining the valid time of the request), the valid time is currently relatively simple and uniformly fixed at a certain value.

When a request is received by the server, the timestamp in the request is checked to ensure it falls between 2 to 60 seconds. Any request with a timestamp older than 5,000 milliseconds is considered invalid. The time window value can be set using the optional parameter: “recvWindow”. Additionally, if the server determines that the client’s timestamp is more than one second ahead of the server, the request will also be invalid. Online conditions are not always 100% reliable in terms of the timeliness of trades, resulting in varying levels of latency between your local program and the XT server. This is why we provide the “recvWindow” parameter - if you engage in high-frequency trading and require stricter transaction timeliness, you can adjust the “recvWindow” parameter to better meet your needs.

Recvwindow longer than 5 seconds is not recommended.

5、Added algorithm (signature method/algorithm), the user calculates the signature according to the protocol of the hash, and HmacSHA256 is recommended. For those protocols that are supported, see the table below.

HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256(recommended)、HmacSHA384、HmacSHA512
Name Mandatory Example Description
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow true 5000(millisecond)
validate-algorithms true HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,The default is:HmacSHA256
validate-signversion false 1.0 reserved, signed version number

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:

validate-algorithms: HmacSHA256

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

validate-recvwindow: 5000

validate-timestamp: 1641446237201

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:

    validate-algorithms=HmacSHA256&validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-recvwindow=5000&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 validate-signature as the key and singature as the value.

4.example

sample of original signature message:
  
    validate-algorithms=HmacSHA256&validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&validate-recvwindow=60000&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 'validate-algorithms: HmacSHA256' 
    --header 'validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' 
    --header 'validate-recvwindow: 60000' 
    --header 'validate-timestamp: 1666026215729' 
    --header '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
  golang : https://github.com/xt-com/xt4-go-demo
  c# : https://github.com/xt-com/xt4-c--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 validate-appkey
AUTH_002 missing request header validate-timestamp
AUTH_003 missing request header validate-recvwindow
AUTH_004 bad request header validate-recvwindow
AUTH_005 missing request header validate-algorithms
AUTH_006 bad request header validate-algorithms
AUTH_007 missing request header 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
LEVER_ORDER_099 Already order is being processed
LEVER_ORDER_082 The position is currently closed and the operation is not supported for the time being.
LEVER_ORDER_081 Currently, manual processing is not supported.
LEVER_ORDER_080 The liquidation is currently in progress and the operation is not supported for the time being.
LEVER_ORDER_032 There is currently no loan or manual repayments can’t be made. Please try again.
LEVER_ORDER_031 Wrong repayment amount.
LEVER_ORDER_006 Insufficient leverage capital.
LEVER_ORDER_005 The current maximum loanable amount in the market is insufficient.
LEVER_ORDER_004 Insufficient loan amount.
LEVER_ORDER_003 Wrong loan amount.
LEVER_ORDER_001 Repeat request.
LEVER_1004 The current sub-account does not have this transaction permission.
GATEWAY_0001 Trigger risk control
GATEWAY_0002 Trigger risk control
GATEWAY_0003 Trigger risk control
GATEWAY_0004 Trigger risk control

Public module Edit

Interest source

Interest source Description
FIX_JOB Daily scheduled tasks.
USER User loan.

Repay type

Repay type Description
MANUAL Manual loan repayment.
SYSTEM System Liquidation.

Order type

Order type Description
LOAN Loan.
REPAY Repayment

FAQ Edit

1.AUTH_ 105: The server verifies the request header parameters validate-timestamp (validTimeStamp) and validate-recvwindow (recvwindow) The following rules must be followed: dealTimeStamp (server time when the request is processed, in milliseconds) - validTimeStamp < recvwindow, otherwise AUTH_105 will be returned. To avoid this error, validate-timestamp recommends using the time when the request was sent, and it is measured in milliseconds. The validate-recvwindow is set a little larger

Contact us Edit

XT API Telegram Group: XT API Support Group
XT API Ticket: Create API Ticket

  • For any general questions about the API not covered in the documentation.
  • For any MM questions

XT Customer Support: Website and App online customer service

  • For cases such as missing funds, help with 2FA, etc.

Get symbol list Edit

/v4/public/lever/symbol

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": [{
       "symbolId": 123,          //Spot symbol id
       "symbol": "btc_usdt",     //Spot symbol
       "buyCurrencyId": 123,     //Buy currency id
       "buyCurrency": "btc",     //Buy currency
       "sellCurrencyId": 234,    //Sell currency id
       "sellCurrency": "usdt",   //Sell currency
       "maxLoanAmountBuy": "",   //The maximum amount of buy currency that can be borrowed
       "maxLoanAmountSell": "",  //The maximum amount of sell currency that can be borrowed
       "maxLeverage": "",        //Maximum loan multiple
       "dailyInterestRate": "",  //Daily interest rate
       "liquidationRate": "",    //Liquidation risk rate
       "tipsRate": ""            //Reminder coefficient
  }]
}

Create order Edit

/v4/lever/order

Parameters
Parameter Type mandatory Default Description Ranges
marketName string true trading pair eg:BTC_USDT
coinName string true coin name,lower case. e.g. btc
amount number true eg: 8000
type string true type, LOAN/REPAY
media string false media eg:btok
mediaChannel string false media channel

Limit Flow Rules

30/s/apikey

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

Get balance by symbol Edit

/v4/lever/balance

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true symbol eg:BTC_USDT
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [{}],
  "result": {
      "btcLoanAmount": 0,               //convert BTC loan assets
      "btcNetAmount": 0,                //Convert BTC net assets
      "symbol": "string",               //symbol
      "symbolId": 0,                    //symbol id
      "usdtLoanAmount": 0,              //convert USDT loan assets
      "usdtNetAmount": 0                //convert USDT net assets
      "base":{
         "availableAmount": "string",   //available amount
         "capitalAmount": "string",     //capital amount
         "currency": "string",          //currency
         "currencyId": 0,               //currency id
         "frozenAmount": "string",      //frozen amount
         "interestAmount": "string",    //interest amount outstanding
         "loanAmount": "string",        //loan amount
         "totalAmount": "string",       //total amount
         "updatedTime": 0               //update time
      },
      "quote":{
          "availableAmount": "string",  //available amount
          "capitalAmount": "string",    //capital amount
          "currency": "string",         //currency
          "currencyId": 0,              //currency id
          "frozenAmount": "string",     //frozen amount
          "interestAmount": "string",   //interest amount outstanding
          "loanAmount": "string",       //loan amount
          "totalAmount": "string",      //total amount
          "updatedTime": 0              //update time
      }
  }
}

Get loan list Edit

/v4/lever/loan

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true
startTime long true start time
endTime long true end time
fromId long false page from id
direction string true page direction NEXT/PREV
limit int false 20 page limit
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [{}],
  "result": {
      "hasNext": true,               //whether has next page
      "hasPrev": true,               //whether has previous page
      "items":[{
           "id": "string",           //id
           "amount": 0,              //amount
           "currency": "string",     //currency
           "currencyId": 0,          //currency id
           "symbol": "string",       //symbol
           "symbolId": 0,            //symbol id
           "createTime": 0           //create time
      }]
  }
}

Get repay list Edit

/v4/lever/repay

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false
startTime long true start time
endTime long false end time
fromId long false page from id
direction string true page direction NEXT/PREV
limit int false 20 page limit
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [{}],
  "result": {
      "hasNext": true,               //whether has next page
      "hasPrev": true,               //whether has previous page
      "items":[{
           "id": "string",           //id
           "amount": 0,              //amount
           "currency": "string",     //currency
           "currencyId": 0,          //currency id
           "symbol": "string",       //symbol
           "symbolId": 0,            //symbol id
           "interestAmount": 0,      //interest amount
           "type": "MANUAL",         //type, MANUAL/SYSTEM
           "createTime": 0           //create time
      }]
  }
}

Get interest list Edit

/v4/lever/interest

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false
startTime long true start time
endTime long true end time
fromId long false page from id
direction string true page direction NEXT/PREV
limit int false 20 page limit
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [{}],
  "result": {
      "hasNext": true,               //whether has next page
      "hasPrev": true,               //whether has previous page
      "items":[{
           "id": "string",           //id
           "amount": 0,              //amount
           "currency": "string",     //currency
           "currencyId": 0,          //currency id
           "symbol": "string",       //symbol
           "symbolId": 0,            //symbol id
           "dailyInterestRate": 0,   //daily interest rate
           "source": "FIX_JOB",      //source, FIX_JOB/USER
           "createTime": 0           //create time
      }]
  }
}

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
字段名 是否必须 示例 说明
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow true 5000(毫秒)
validate-algorithms true HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,默认为:HmacSHA256
validate-signversion false 1.0 保留,签名版本号

签名生成 Edit

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

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

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Header部分数据:

validate-algorithms: HmacSHA256

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

validate-recvwindow: 5000

validate-timestamp: 1641446237201

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。如:

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

3、生成签名

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

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

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

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

4、样例

签名原始报文样例:

    validate-algorithms=HmacSHA256&validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&validate-recvwindow=60000&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 'validate-algorithms: HmacSHA256' 
    --header 'validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' 
    --header 'validate-recvwindow: 60000' 
    --header 'validate-timestamp: 1666026215729' 
    --header '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
  golang : https://github.com/xt-com/xt4-go-demo
  c# : https://github.com/xt-com/xt4-c--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 缺少请求头 validate-appkey
AUTH_002 缺少请求头 validate-timestamp
AUTH_003 缺少请求头 validate-recvwindow
AUTH_004 错误的请求头 validate-recvwindow
AUTH_005 缺少请求头 validate-algorithms
AUTH_006 错误的请求头 validate-algorithms
AUTH_007 缺少请求头 validate-signature
AUTH_101 ApiKey不存在
AUTH_102 ApiKey未激活
AUTH_103 签名错误
AUTH_104 非绑定IP请求
AUTH_105 报文过时
AUTH_106 超出apikey权限
LEVER_ORDER_099 已有订单处理中
LEVER_ORDER_082 当前穿仓,暂不支持操作
LEVER_ORDER_081 当前人工处理,暂不支持操作
LEVER_ORDER_080 当前爆仓中,暂不支持操作
LEVER_ORDER_032 当前无借款或不能手动还款,请重试
LEVER_ORDER_031 还款数量错误
LEVER_ORDER_006 杠杠本金不足
LEVER_ORDER_005 当前市场最大可借数量不足
LEVER_ORDER_004 可借贷数量不足
LEVER_ORDER_003 借贷数量错误
LEVER_ORDER_001 重复请求
LEVER_1004 当前子账户暂无该交易权限
GATEWAY_0001 触发风控
GATEWAY_0002 触发风控
GATEWAY_0003 触发风控
GATEWAY_0004 触发风控

公共模块 Edit

利息来源

Interest source 说明
FIX_JOB 每日定时任务
USER 用户借贷

还款类型

Repay type 说明
MANUAL 手动还款
SYSTEM 爆仓

订单类型

Order type 说明
LOAN 借贷
REPAY 还款

FAQ Edit

1.AUTH_105:服务器在校验请求头参数validate-timestamp(validTimeStamp)、validate-recvwindow(recvwindow)时, 需要符合以下规则:dealTimeStamp(请求被处理时服务器时间,单位毫秒)- validTimeStamp < recvwindow ,否则就会返回AUTH_105,为了避免此错误,建议validate-timestamp 设置为请求发出的时间,以毫秒为单位,validate-recvwindow设置的大一点

联系我们 Edit

XT API电报群: XT API Support Group
XT API工单: Create API Ticket

  • 咨询文档中没有提及的API问题
  • 咨询API或者Websocket性能方面的问题
  • 咨询做市相关的问题

XT 客服:官网、App中在线客服

  • 咨询关于钱包、短信、2FA等问题

获取交易对列表 Edit

/v4/public/lever/symbol

{
   "rc": 0,
   "mc": "SUCCESS",
   "ma": [],
   "result": [{
        "symbolId": 123,          //现货市场ID
        "symbol": "btc_usdt",     //现货市场名称
        "buyCurrencyId": 123,     //买方币种ID
        "buyCurrency": "btc",     //买方币种名称
        "sellCurrencyId": 234,    //卖方币种ID
        "sellCurrency": "usdt",   //卖房币种名称
        "maxLoanAmountBuy": "",   //买方币种最大可借数量
        "maxLoanAmountSell": "",  //卖方币种最大可借数量
        "maxLeverage": "",        //最大借贷倍数
        "dailyInterestRate": "",  //日利率
        "liquidationRate": "",    //爆仓风险率
        "tipsRate": ""            //提醒系数
   }]
}           

下单 Edit

/v4/lever/order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
marketName string true 交易对 例如:BTC_USDT
coinName string true 币种,小写。 例如:btc
amount number true 数量
type string true 类型, LOAN/REPAY
media string false 媒体 例如:btok
mediaChannel string false 媒体渠道

限流规则

30/s/apikey

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

获取杠杆单个资产 Edit

/v4/lever/balance

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 市场 例如:BTC_USDT
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [{}],
  "result": {
      "btcLoanAmount": 0,               //折算BTC借贷资产
      "btcNetAmount": 0,                //折算BTD总资产
      "symbol": "string",               //市场
      "symbolId": 0,                    //市场 id
      "usdtLoanAmount": 0,              //折算USDT借贷资产
      "usdtNetAmount": 0                //折算USDT总资产
      "base":{
         "availableAmount": "string",   //可用数量
         "capitalAmount": "string",     //本金数量
         "currency": "string",          //币种
         "currencyId": 0,               //币种 id
         "frozenAmount": "string",      //冻结数量
         "interestAmount": "string",    //未还利息数量
         "loanAmount": "string",        //借款数量
         "totalAmount": "string",       //总数量
         "updatedTime": 0               //更新时间
      },
      "quote":{
          "availableAmount": "string",  //可用数量
          "capitalAmount": "string",    //本金数量
          "currency": "string",         //币种
          "currencyId": 0,              //币种 id
          "frozenAmount": "string",     //冻结数量
          "interestAmount": "string",   //未还利息数量
          "loanAmount": "string",       //借款数量
          "totalAmount": "string",      //总数量
          "updatedTime": 0              //更新时间
      }
  }
}

获取杠杆借贷列表 Edit

/v4/lever/loan

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 市场
startTime long true 开始时间
endTime long true 结束时间
fromId long false 分页开始id
direction string true 分页方向 NEXT/PREV
limit int false 20 页数
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [{}],
  "result": {
      "hasNext": true,               //是否有下一页
      "hasPrev": true,               //是否有上一页
      "items":[{
           "id": "string",           //id
           "amount": 0,              //数量
           "currency": "string",     //币种
           "currencyId": 0,          //币种 id
           "symbol": "string",       //市场
           "symbolId": 0,            //市场 id
           "createTime": 0           //创建时间
      }]
  }
}

获取杠杆还款列表 Edit

/v4/lever/repay

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 市场 例如:btc_usdt
startTime long true 开始时间
endTime long true 结束时间
fromId long false 分页开始id
direction string true 分页方向 NEXT/PREV
limit int false 20 页数
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [{}],
  "result": {
      "hasNext": true,               //是否有下一页
      "hasPrev": true,               //是否有上一页
      "items":[{
           "id": "string",           //id
           "amount": 0,              //数量
           "currency": "string",     //币种
           "currencyId": 0,          //币种 id
           "symbol": "string",       //市场
           "symbolId": 0,            //市场 id
           "interestAmount": 0,      //利息数量
           "type": "MANUAL",         //类型, MANUAL/SYSTEM
           "createTime": 0           //创建时间
      }]
  }
}

获取杠杆利息列表 Edit

/v4/lever/interest

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 市场
startTime long true 开始时间
endTime long true 结束时间
fromId long false 分页开始id
direction string true 分页方向 NEXT/PREV
limit int false 20 页数
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [{}],
  "result": {
      "hasNext": true,               //是否有下一页
      "hasPrev": true,               //是否有上一页
      "items":[{
           "id": "string",           //id
           "amount": 0,              //数量
           "currency": "string",     //币种
           "currencyId": 0,          //币种 id
           "symbol": "string",       //市场
           "symbolId": 0,            //市场 id
           "dailyInterestRate": 0,   //日利率
           "source": "FIX_JOB",      //来源, FIX_JOB(定时任务)/USER(用户借贷)
           "createTime": 0           //创建时间
      }]
  }
}

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,therefore, the issue of data security needs to be considered. Such as whether the data has been tampered with, whether the data is outdated, whether the data can be submitted repeatedly, and the access frequency of the interface, and whether data has been tampered with is the most important issue.

  1. Please apply for appkey and secretkey in the user center first, each user’s appkey and secretkey are different.

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

  3. Add signature, its value is obtained by a certain rule of signature algorithm.

  4. Add recvwindow (defining the valid time of the request), the valid time is currently relatively simple and uniformly fixed at a certain value.

When a request is received by the server, the timestamp in the request is checked to ensure it falls between 2 to 60 seconds. Any request with a timestamp older than 5,000 milliseconds is considered invalid. The time window value can be set using the optional parameter: “recvWindow”. Additionally, if the server determines that the client’s timestamp is more than one second ahead of the server, the request will also be invalid. Online conditions are not always 100% reliable in terms of the timeliness of trades, resulting in varying levels of latency between your local program and the XT server. This is why we provide the “recvWindow” parameter - if you engage in high-frequency trading and require stricter transaction timeliness, you can adjust the “recvWindow” parameter to better meet your needs.

Recvwindow longer than 5 seconds is not recommended.

5、Added algorithm (signature method/algorithm), the user calculates the signature according to the protocol of the hash, and HmacSHA256 is recommended. For those protocols that are supported, see the table below.

HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256(recommended)、HmacSHA384、HmacSHA512
Name Mandatory Example Description
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow true 5000(millisecond)
validate-algorithms true HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,The default is:HmacSHA256
validate-signversion false 1.0 reserved, signed version number

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:

validate-algorithms: HmacSHA256

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

validate-recvwindow: 5000

validate-timestamp: 1641446237201

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:

    validate-algorithms=HmacSHA256&validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-recvwindow=5000&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 validate-signature as the key and singature as the value.

4.example

sample of original signature message:
  
    validate-algorithms=HmacSHA256&validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&validate-recvwindow=60000&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 'validate-algorithms: HmacSHA256' 
    --header 'validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' 
    --header 'validate-recvwindow: 60000' 
    --header 'validate-timestamp: 1666026215729' 
    --header '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
  golang : https://github.com/xt-com/xt4-go-demo
  c# : https://github.com/xt-com/xt4-c--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 validate-appkey
AUTH_002 missing request header validate-timestamp
AUTH_003 missing request header validate-recvwindow
AUTH_004 bad request header validate-recvwindow
AUTH_005 missing request header validate-algorithms
AUTH_006 bad request header validate-algorithms
AUTH_007 missing request header 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
SYMBOL_005 The symbol does not support trading via API
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_007 The sub-account has no transaction authority
ORDER_008 The order price or quantity precision is abnormal
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 or PROTECTION_LIMIT Filter
ORDER_F0501 Trigger PROTECTION_LIMIT Filter - Buy Max Deviation
ORDER_F0502 Trigger PROTECTION_LIMIT Filter - Sell Max Deviation
ORDER_F0503 Trigger PROTECTION_LIMIT Filter - Buy Limit Coefficient
ORDER_F0504 Trigger PROTECTION_LIMIT Filter - Sell Limit Coefficient
ORDER_F0601 Trigger PROTECTION_MARKET Filter
COMMON_001 The user does not exist
COMMON_002 System busy, please try it later
COMMON_003 Operation failed, please try it later
CURRENCY_001 Information of currency is abnormal
SYMBOL_001 Symbol does not exist
GATEWAY_0001 Trigger risk control
GATEWAY_0002 Trigger risk control
GATEWAY_0003 Trigger risk control
GATEWAY_0004 Trigger risk control
COPY_TRADE_SPOT_000 The system is busy, please try again later
COPY_TRADE_SPOT_001 You are already a leader
COPY_TRADE_SPOT_002 You already have a leader
COPY_TRADE_SPOT_003 You have already submitted your leader application
COPY_TRADE_SPOT_004 You have not completed real-name authentication or your real-name authentication level does not meet the application requirements
COPY_TRADE_SPOT_005 Your account total assets do not meet the application requirements
COPY_TRADE_SPOT_006 The leader does not exist
COPY_TRADE_SPOT_007 You have already submitted your leader application, follow order is not supported
COPY_TRADE_SPOT_008 The copy margin exceeds the limit
COPY_TRADE_SPOT_009 The copy order ratio exceeds the limit
COPY_TRADE_SPOT_010 The number of followers is full
COPY_TRADE_SPOT_011 Exceeded the maximum number of followers
COPY_TRADE_SPOT_012 The precision of the take-profit price is abnormal
COPY_TRADE_SPOT_013 The precision of the stop-loss price is abnormal
COPY_TRADE_SPOT_014 The take-profit trigger price must be greater than the latest transaction price
COPY_TRADE_SPOT_015 The stop-loss trigger price must be less than the latest transaction price
COPY_TRADE_SPOT_016 The leader has spot orders and is not allowed to cancel the termination

Public module Edit

Leader order request type

Type Description
1 Query order details.
2 Query order summary information.

Copy trade user status

User status Description
LEADER Copy trade leader
FOLLOWER Copy trade follower
NONE None

Leader type

Type Description
1 Current follow
2 History follow

Copy trade follow type

Follow type Description
FUND Copy trading according to fixed amount.
RATE Copy trading according to fund ratio.

Copy stop loss position processing

FollowLossOperate Description
MARKET_SELL Immediately settle at market price
LEADER_CLOSE Follow the lead to close the position
MANUAL_PROCESS Manual Processing

FAQ Edit

1.AUTH_ 105: The server verifies the request header parameters validate-timestamp (validTimeStamp) and validate-recvwindow (recvwindow) The following rules must be followed: dealTimeStamp (server time when the request is processed, in milliseconds) - validTimeStamp < recvwindow, otherwise AUTH_105 will be returned. To avoid this error, validate-timestamp recommends using the time when the request was sent, and it is measured in milliseconds. The validate-recvwindow is set a little larger

Contact us Edit

XT API Telegram Group: XT API Support Group
XT API Ticket: Create API Ticket

  • For any general questions about the API not covered in the documentation.
  • For any MM questions

XT Customer Support: Website and App online customer service

  • For cases such as missing funds, help with 2FA, etc.

Get current lead order Edit

/v1/copy-trade-order/copy-trade/order/cur-leader-order

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false Trading pair, if not filled in, represents all
type number false 2 Leader order request type, 1,detail; 2,summarize

Limit Flow Rules

2/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",
      "orderId": "string",        //order id
      "symbol": "string",         //symbol
      "buySize": 0,               //buy quantity
      "buyTime": 0,               //buy time
      "buyPrice": 0,              //buy price
      "sellSize": 0,              //sell quantity
      "sellTime": 0,              //sell time
      "sellPrice": 0,             //sell price
      "profit": 0,                //profit
      "profitRate": 0,            //profit rate
      "triggerProfitPrice": 0,    //trigger profit price
      "triggerStopPrice": 0,      //trigger stop price
      "followCount": 0            //number of followers
    }
  ]
}

Get current copy order Edit

/v1/copy-trade-order/copy-trade/order/cur-follower-order

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false Trading pair, if not filled in, represents all
type number false 2 Leader order request type, 1,detail; 2,summarize

Limit Flow Rules

2/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",        
      "orderId": "string",        //order id
      "symbol": "string",         //symbol
      "buySize": 0,               //buy quantity
      "buyTime": 0,               //buy time
      "buyPrice": 0,              //buy price
      "sellSize": 0,              //sell quantity
      "sellTime": 0,              //sell time
      "sellPrice": 0,             //sell price
      "profit": 0,                //profit
      "profitRate": 0,            //profit rate
      "triggerProfitPrice": 0,    //trigger profit price
      "triggerStopPrice": 0,      //trigger stop price
      "leaderOrderId": "string",  //leader order id
      "leaderNickname": "string", //leader nick name
      "leaderAvatar": "string"    //leader avatar
    }
  ]
}

Get historical copy order Edit

/v1/copy-trade-order/copy-trade/order/his-follower-order

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false Trading pair, if not filled in, represents all
direction string false NEXT query direction PREV-previous page,NEXT-next page
limit number false 10 number of pages 1-100
id object false start ID,e.g. 6216559590087220004

Limit Flow Rules

2/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",        
      "orderId": "string",           //order id
      "symbol": "string",            //symbol
      "buySize": 0,                  //buy quantity
      "buyTime": 0,                  //buy time
      "buyPrice": 0,                 //buy price
      "sellSize": 0,                 //sell quantity
      "sellTime": 0,                 //sell time
      "sellPrice": 0,                //sell price
      "profit": 0,                   //profit
      "profitRate": 0,               //profit rate
      "triggerProfitPrice": 0,       //trigger profit price
      "triggerStopPrice": 0,         //trigger stop price
      "leaderOrderId": "string",     //leader order id
      "leaderNickname": "string",    //leader nickname
      "leaderAvatar": "string"       //leader avatar
    }
  ]
}

Get historical lead order Edit

/v1/copy-trade-order/copy-trade/order/his-leader-order

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false Trading pair, if not filled in, represents all
direction string false NEXT query direction PREV-previous page,NEXT-next page
limit number false 10 number of pages 1-100
id object false start ID,e.g. 6216559590087220004

Limit Flow Rules

2/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",
      "orderId": "string",        //order id
      "symbol": "string",         //symbol
      "buySize": 0,               //buy quantity
      "buyTime": 0,               //buy time
      "buyPrice": 0,              //buy price
      "sellSize": 0,              //sell quantity
      "sellTime": 0,              //sell time
      "sellPrice": 0,             //sell price
      "profit": 0,                //profit
      "profitRate": 0,            //profit rate
      "triggerProfitPrice": 0,    //trigger profit price
      "triggerStopPrice": 0,      //trigger stop price
      "followCount": 0            //number of followers
    }
  ]
}

Set stop-loss or stop-profit for lead or copy order Edit

/v1/copy-trade-order/copy-trade/order/stop-profit-loss

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true symbol
leaderOrderId number true For copy order, need leaderOrderId; for lead order, need orderId
triggerProfitPrice number false trigger profit price
triggerStopPrice number false trigger stop price

Limit Flow Rules

2/s/apikey

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

Sell lead order Edit

/v1/copy-trade-order/copy-trade/order/sell

Parameters
Parameter Type mandatory Default Description Ranges
leaderOrderId number true leader order id
symbol string true symbol

Limit Flow Rules

50/s/apikey

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

Sell all lead order Edit

/v1/copy-trade-order/copy-trade/order/sell-all

Parameters
Parameter Type mandatory Default Description Ranges
leaderOrder bool true true:sell all lead order; false:sell all copy order
symbol string false symbol

Limit Flow Rules

50/s/apikey

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

Close copy order Edit

/v1/copy-trade-order/copy-trade/order/close

Parameters
Parameter Type mandatory Default Description Ranges
leaderOrderId number true leader order id
symbol string true symbol

Limit Flow Rules

50/s/apikey

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

Close all copy order Edit

/v1/copy-trade-order/copy-trade/order/close-all

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true symbol

Limit Flow Rules

50/s/apikey

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

Get copy trade symbols Edit

/v1/copy-trade-market/public/copy-trade/symbol

Limit Flow Rules

2/s/apikey

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": [{
     symbolId: 1,        //symbol id
     symbol: "btc_usdt"  //symbol
   }]
}

Get user role Edit

/v1/copy-trade-account/copy-trade/user-status

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": "string"        //LEADER、FOLLOWER、NONE
}

Get leader setting Edit

/v1/copy-trade-account/copy-trade/leader-settings

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "displayEquity": true,      //Display total assets or not
    "displayQuantity": true,    //Display buy quantity or not
    "labelIds": "string",       //Label ids, separated by commas
    "leaderIntro": "string",    //Leader introduction
    "leaderSymbol": [           //Selected copy trade symbols
         "btc_usdt"
    ],
    "openLeader": true,        //Open leader or not
    "symbolConfig": [          //All copy trade symbols
         "btc_usdt"
    ],
    "tagsConfig": [            //tag config, label list
      {
        "id": 0,
        "label": "string"
      }
    ]
  }
}

Modify leader setting Edit

/v1/copy-trade-account/copy-trade/leader-settings

Parameters
Parameter Type mandatory Default Description Ranges
leaderIntro string false Leader introduction
labelIds string false Label ids, separated by commas, e.g. 1,2,3,4
displayEquity bool false Display total assets or not
displayQuantity bool false Display buy quantity or not
symbols string true Selected copy trade symbols, e.g. btc_usdt,eth_usdt
openLeader bool false Open leader or not

Limit Flow Rules

2/s/ip

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

Get historical total profit sharing Edit

/v1/copy-trade-balance/copy-trade/share-profit/his

Parameters
Parameter Type mandatory Default Description Ranges
direction string false NEXT query direction PREV-previous page,NEXT-next page
limit number false 10 number of pages 1-100
id object false start ID,e.g. 6216559590087220004

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
      {
        "amount": 0,    //profit sharing amount
        "id": "string", //the id used for pagination query
        "time": 0       //profit sharing time
      }
    ]
  }
}

Get historical profit sharing detail Edit

/v1/copy-trade-balance/copy-trade/share-profit/his-detail

Parameters
Parameter Type mandatory Default Description Ranges
time number true profit sharing time. e.g. 1717545600000
direction string false NEXT query direction PREV-previous page,NEXT-next page
limit number false 10 number of pages 1-100
id object false start ID,e.g. 6216559590087220004

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
      {
        "amount": 0,            //profit sharing amount.
        "avatar": "string",     //avatar of copy trader.
        "id": 0,                //the id used for pagination query.
        "name": "string"        //nickname of copy trader.
      }
    ]
  }
}

Get unrealized total profit sharing Edit

/v1/copy-trade-balance/copy-trade/share-profit/expected

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": 0    //unrealized profit sharing amount
}

Get unrealized profit sharing detail Edit

/v1/copy-trade-balance/copy-trade/share-profit/expected-detail

Parameters
Parameter Type mandatory Default Description Ranges
direction string false NEXT query direction PREV-previous page,NEXT-next page
limit number false 10 number of pages 1-100
id object false start ID,e.g. 6216559590087220004

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
      {
        "amount": 0,        //profit sharing amount.
        "avatar": "string", //avatar of copy trader.
        "id": 0,            //the id used for pagination query.
        "name": "string"    //nickname of copy trader.
      }
    ]
  }
}

Apply for lead trading Edit

/v1/copy-trade-account/copy-trade/apply

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": true    //true or false
}

Stop lead trading Edit

/v1/copy-trade-account/copy-trade/cancel-leader

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": true    //true or false
}

Get leader account configuration Edit

/v1/copy-trade-account/public/copy-trade/leader-detail

Parameters
Parameter Type mandatory Default Description Ranges
accountId number true leader account id

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "avatar": "string",        //avatar
    "currentFollowNumber": 0,  //current number of copy traders
    "displayEquity": true,     //display total assets or not
    "displayQuantity": true,   //display the purchase quantity or not
    "fansNum": 0,             //fans number
    "followNumber": 0,        //follow number
    "label": [                //label
      "string"
    ],
    "leadDays": 0,            //time to become a lead
    "leaderIntro": "string",  //leader introduction
    "level": 0,               //current level
    "levelId": 0,             //current level id
    "levelName": "string",    //current level name
    "maxFollowerSize": 0,     //maximum number of copy traders
    "nickName": "string",     //nickname
    "profitRate": 0,          //profit sharing ratio.
    "totalRights": 0          //total assets
  }
}

Get my lead trades Edit

/v1/copy-trade-account/copy-trade/my-leaders

Parameters
Parameter Type mandatory Default Description Ranges
type number true the type of lead trade leader type, 1:current lead trades; 2:historical lead trades
direction string false NEXT query direction PREV-previous page,NEXT-next page
limit number false 10 number of pages 1-100
id object false start ID,e.g. 6216559590087220004

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
      {
        "accountId": 0,        //account id
        "avatar": "string",    //avatar
        "followMargin": 0,     //follow amount
        "followProfit": 0,     //follow profit
        "id": 0,               //the id used for pagination query
        "leaderName": "string" //nickname of lead trader
      }
    ]
  }
}

Get my copy setting Edit

/v1/copy-trade-account/copy-trade/follow-leader-config

Parameters
Parameter Type mandatory Default Description Ranges
leaderAccountId number true leader account id

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "autoFollowSymbol": true,                //auto follow new symbol or not
    "followLoss": 0,                         //follow loss
    "followLossOperate": "LEADER_CLOSE",     //follow loss operate.MARKET_SELL;LEADER_CLOSE;MANUAL_PROCESS
    "followSymbols": [                       //follow symbols, comma separated (the symbols has been selected)
         "string"
    ],
    "followType": "FUND",                    //follow type,FUND;RATE
    "followVal": 0,                          //follow value, fund or rate value
    "leaderSymbols": [                       //leader symbols, all copy trading symbols
         "string"
    ],
    "profitRate": 0,                         //profit rate
    "triggerProfitRate": 0,                  //trigger profit rate
    "triggerStopRate": 0                     //trigger stop rate
  }
}

Follow copy trading Edit

/v1/copy-trade-account/copy-trade/follow

Parameters
Parameter Type mandatory Default Description Ranges
leaderAccountId number true leader account id
followType string true follow type follow type, FUND;RATE
followVal number true follow fund value or rate value
followLoss number false follow loss
followLossOperate string true follow loss operate follow loss operate, MARKET_SELL;LEADER_CLOSE;MANUAL_PROCESS
triggerStopRate number false single stop loss rate
triggerProfitRate number false single take profit rate
autoFollowSymbol bool true auto follow symbol or not
symbols string true copy trade symbols. e.g. xt_usdt,btc_usdt

Limit Flow Rules

2/s/ip

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

Stop copy trading Edit

/v1/copy-trade-account/copy-trade/cancel-follow

Parameters
Parameter Type mandatory Default Description Ranges
leaderAccountId number true leader account id

Limit Flow Rules

2/s/ip

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

Get lead trader stats Edit

/v1/copy-trade-balance/public/copy-trade/leader-stats

Parameters
Parameter Type mandatory Default Description Ranges
accountId number true leader account id
days string false 7 query days 7,30,90,180,all

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "avgHoldTime": 0,           //average holding time (seconds)
    "avgLossAmount": 0,         //average loss amount
    "avgProfitAmount": 0,       //average profit amount
    "followerMargin": 0,        //follower margin
    "followersEarnings": 0,     //follower profit
    "lastTradeTime": 0,         //latest trading time
    "lossCount": 0,             //loss count
    "maxRetraction": 0,         //max retraction
    "pnlRate": "string",        //Profit and loss ratio
    "profitCount": 0,           //profit count
    "recentRate": 0,            //yield rate 
    "totalEarnings": 0,         //total revenue
    "totalTransactions": 0,     //total transactions
    "tradeDays": 0,             //trade days
    "weeklyTradeFrequency": 0,  //trading frequency (weekly)
    "winRate": 0                //win rate
  }
}

Get leader daily income chart Edit

/v1/copy-trade-balance/public/copy-trade/leader-income-chart

Parameters
Parameter Type mandatory Default Description Ranges
accountId number true leader account id
days number false 7 query days 7,30,90,180

Limit Flow Rules

2/s/ip

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

Get leader daily cumulative income chart Edit

/v1/copy-trade-balance/public/copy-trade/leader-income-rate

Parameters
Parameter Type mandatory Default Description Ranges
accountId number true leader account id
days number false 7 query days 7,30,90,180

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "incomeRate": [        //income rate
      {
        "amount": 0,
        "id": "string",
        "time": 0
      }
    ],
    "totalIncome": [        //total income
      {
        "amount": 0,
        "id": "string",
        "time": 0
      }
    ],
    "totalIncomeRate": [    //total income rate
      {
        "amount": 0,
        "id": "string",
        "time": 0
      }
    ]
  }
}

Get lead trader currency preferences Edit

/v1/copy-trade-balance/public/copy-trade/leader-trading-prefer

Parameters
Parameter Type mandatory Default Description Ranges
accountId number true leader account id
days number false 7 query days 7,30,90,180

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": [
    {
      "count": 0,           //trade count
      "index": 0,
      "percentage": 0,      //percentage
      "pnl": 0,             //trading Profit and Loss
      "symbol": "string"    //symbol, others return others
    }
  ]
}

Get lead trader current lead order Edit

/v1/copy-trade-order/public/copy-trade/order/leader-order-page

Parameters
Parameter Type mandatory Default Description Ranges
leaderAccountId number true leader account id
symbol string false trading pair eg:btc_usdt. if null, defaults to all
type number true type search type, 1:detail;2:total

Limit Flow Rules

2/s/ip

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",           //id
      "orderId": "string",      //order id
      "symbol": "string",       //symbol
      "buySize": 0,             //buy size
      "buyTime": 0,             //buy time
      "buyPrice": 0,            //buy price
      "sellSize": 0,            //sell size
      "sellTime": 0,            //sell time
      "sellPrice": 0,           //sell price
      "profit": 0,              //profit
      "profitRate": 0,          //profit rate
      "triggerProfitPrice": 0,  //take profit price
      "triggerStopPrice": 0,    //stop Loss Price
      "followCount": 0          //follow count
    }
  ]
}

Get lead trader historical lead order Edit

/v1/copy-trade-order/public/copy-trade/order/leader-order-history

Parameters
Parameter Type mandatory Default Description Ranges
leaderAccountId number true leader account id
symbol string false trading pair eg:btc_usdt. if null, defaults to all
direction string false NEXT query direction PREV-previous page,NEXT-next page
limit number false 10 number of pages 1-100
id object false start ID,e.g. 6216559590087220004

Limit Flow Rules

2/s/ip

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",           //id
      "orderId": "string",      //order id
      "symbol": "string",       //symbol
      "buySize": 0,             //buy size
      "buyTime": 0,             //buy time
      "buyPrice": 0,            //buy price
      "sellSize": 0,            //sell size
      "sellTime": 0,            //sell time
      "sellPrice": 0,           //sell price
      "profit": 0,              //profit
      "profitRate": 0,          //profit rate
      "triggerProfitPrice": 0,  //take profit price
      "triggerStopPrice": 0,    //stop Loss Price
      "followCount": 0          //follow count
    }
  ]
}

Get my copy trader list Edit

/v1/copy-trade-account/copy-trade/leader-followers

Parameters
Parameter Type mandatory Default Description Ranges
direction string false NEXT query direction PREV-previous page,NEXT-next page
limit number false 10 number of pages 1-100
id object false start ID,e.g. 6216559590087220004

Limit Flow Rules

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
      {
        "accountId": 0,            //copy trader account id
        "avatar": "string",        //avatar of copy trader
        "days": 0,                 //follow days
        "followMargin": 0,         //follow margin
        "followProfit": 0,         //follow profit
        "followProfitRate": 0,     //follow profit rate
        "followerName": "string",  //name of copy trader
        "id": 0,                   //id
        "pageId": 0                //the id used for pagination query
      }
    ]
  }
}

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
字段名 是否必须 示例 说明
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow true 5000(毫秒)
validate-algorithms true HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,默认为:HmacSHA256
validate-signversion false 1.0 保留,签名版本号

签名生成 Edit

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

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

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Header部分数据:

validate-algorithms: HmacSHA256

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

validate-recvwindow: 5000

validate-timestamp: 1641446237201

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。如:

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

3、生成签名

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

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

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

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

4、样例

签名原始报文样例:

    validate-algorithms=HmacSHA256&validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&validate-recvwindow=60000&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 'validate-algorithms: HmacSHA256' 
    --header 'validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' 
    --header 'validate-recvwindow: 60000' 
    --header 'validate-timestamp: 1666026215729' 
    --header '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
  golang : https://github.com/xt-com/xt4-go-demo
  c# : https://github.com/xt-com/xt4-c--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 缺少请求头 validate-appkey
AUTH_002 缺少请求头 validate-timestamp
AUTH_003 缺少请求头 validate-recvwindow
AUTH_004 错误的请求头 validate-recvwindow
AUTH_005 缺少请求头 validate-algorithms
AUTH_006 错误的请求头 validate-algorithms
AUTH_007 缺少请求头 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 此交易对不支持您所在的国家
SYMBOL_005 该市场不支持通过API进行交易
ORDER_001 平台拒单
ORDER_002 资金不足
ORDER_003 交易对暂停交易
ORDER_004 禁止交易
ORDER_005 订单不存在
ORDER_006 过多的未完成订单
ORDER_007 子账户暂无交易权限
ORDER_008 当前下单价格或数量精度异常
ORDER_F0101 触发价格过滤器-最小值
ORDER_F0102 触发价格过滤器-最大值
ORDER_F0103 触发价格过滤器-步进值
ORDER_F0201 触发数量过滤器-最小值
ORDER_F0202 触发数量过滤器-最大值
ORDER_F0203 触发数量过滤器-步进值
ORDER_F0301 触发金额过滤器-最小值
ORDER_F0401 触发开盘保护滤器或限价保护过滤器
ORDER_F0501 触发限价保护滤器-买单最大偏离度
ORDER_F0502 触发限价保护滤器-卖单最大偏离度
ORDER_F0503 触发限价保护滤器-买单限制系数
ORDER_F0504 触发限价保护滤器-卖单限制系数
ORDER_F0601 触发市价保护滤器
COMMON_001 用户不存在
COMMON_002 系统繁忙,请稍后再试
COMMON_003 操作失败,请稍后再试
CURRENCY_001 币种信息异常
SYMBOL_001 交易对不存在
GATEWAY_0001 触发风控
GATEWAY_0002 触发风控
GATEWAY_0003 触发风控
GATEWAY_0004 触发风控
COPY_TRADE_SPOT_000 系统繁忙,请稍后再试
COPY_TRADE_SPOT_001 您已经是交易员
COPY_TRADE_SPOT_002 您有跟随的交易员
COPY_TRADE_SPOT_003 您已提交交易员申请,无须重复申请
COPY_TRADE_SPOT_004 您未实名认证或实名认证等级不满足申请规则
COPY_TRADE_SPOT_005 您的账户总资产不满足申请规则
COPY_TRADE_SPOT_006 带单员不存在
COPY_TRADE_SPOT_007 您已提交带单员申请,不支持跟单
COPY_TRADE_SPOT_008 跟单保证金超出限制范围
COPY_TRADE_SPOT_009 跟单比例超出限制范围
COPY_TRADE_SPOT_010 带单员跟随者已满员
COPY_TRADE_SPOT_011 超过最大可跟随人数
COPY_TRADE_SPOT_012 止盈价格精度异常
COPY_TRADE_SPOT_013 止损价格精度异常
COPY_TRADE_SPOT_014 止盈触发价需大于最新成交价
COPY_TRADE_SPOT_015 止损触发价需小于最新成交价
COPY_TRADE_SPOT_016 当前带单员存在现货带单订单,不允许解约

公共模块 Edit

查询类型

Type 说明
1 请求订单明细信息
2 请求订单汇总信息

跟单用户类型

User status 说明
LEADER 带单员
FOLLOWER 跟单员
NONE 其他

跟单员类型

Type Description
1 当前跟随
2 历史跟随

跟随类型

Follow type Description
FUND 按照固定金额跟单.
RATE 按照资金比例跟单.

跟单止损仓位处理

FollowLossOperate 说明
MARKET_SELL 立即市价全平
LEADER_CLOSE 跟随带单员平仓
MANUAL_PROCESS 手动处理

FAQ Edit

1.AUTH_105:服务器在校验请求头参数validate-timestamp(validTimeStamp)、validate-recvwindow(recvwindow)时, 需要符合以下规则:dealTimeStamp(请求被处理时服务器时间,单位毫秒)- validTimeStamp < recvwindow ,否则就会返回AUTH_105,为了避免此错误,建议validate-timestamp 设置为请求发出的时间,以毫秒为单位,validate-recvwindow设置的大一点

联系我们 Edit

XT API电报群: XT API Support Group
XT API工单: Create API Ticket

  • 咨询文档中没有提及的API问题
  • 咨询API或者Websocket性能方面的问题
  • 咨询做市相关的问题

XT 客服:官网、App中在线客服

  • 咨询关于钱包、短信、2FA等问题

获取当前带单 Edit

/v1/copy-trade-order/copy-trade/order/cur-leader-order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对,不传表示查询所有的交易对
type number false 2 订单请求类型, 1:明细;2:汇总

限流规则

2/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",
      "orderId": "string",        //订单id
      "symbol": "string",         //市场
      "buySize": 0,               //买入数量
      "buyTime": 0,               //买入时间
      "buyPrice": 0,              //买入价格
      "sellSize": 0,              //卖出数量
      "sellTime": 0,              //卖出时间
      "sellPrice": 0,             //卖出价格
      "profit": 0,                //收益
      "profitRate": 0,            //收益率
      "triggerProfitPrice": 0,    //止盈
      "triggerStopPrice": 0,      //止损
      "followCount": 0            //跟单人数
    }
  ]
}

获取当前跟单 Edit

/v1/copy-trade-order/copy-trade/order/cur-follower-order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对,不传表示查询所有的交易对
type number false 2 订单请求类型, 1:明细;2:汇总

限流规则

2/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",        
      "orderId": "string",        //订单id
      "symbol": "string",         //市场
      "buySize": 0,               //买入数量
      "buyTime": 0,               //买入时间
      "buyPrice": 0,              //买入价格
      "sellSize": 0,              //卖出数量
      "sellTime": 0,              //卖出时间
      "sellPrice": 0,             //卖出价格
      "profit": 0,                //收益
      "profitRate": 0,            //收益率
      "triggerProfitPrice": 0,    //止盈
      "triggerStopPrice": 0,      //止损
      "leaderOrderId": "string",  //带单员订单id
      "leaderNickname": "string", //带单员昵称
      "leaderAvatar": "string"    //带单员头像
    }
  ]
}

获取历史跟单 Edit

/v1/copy-trade-order/copy-trade/order/his-follower-order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对,不传表示查询所有的交易对
direction string false NEXT 分页查询方向 PREV-上一页,NEXT-下一页
limit number false 10 每页的数量 1-100
id object false 起始ID,例如 6216559590087220004

限流规则

2/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",        
      "orderId": "string",           //订单id
      "symbol": "string",            //市场
      "buySize": 0,                  //买入数量
      "buyTime": 0,                  //买入时间
      "buyPrice": 0,                 //买入价格
      "sellSize": 0,                 //卖出数量
      "sellTime": 0,                 //卖出时间
      "sellPrice": 0,                //卖出价格
      "profit": 0,                   //收益
      "profitRate": 0,               //收益率
      "triggerProfitPrice": 0,       //止盈
      "triggerStopPrice": 0,         //止损
      "leaderOrderId": "string",     //带单员订单id
      "leaderNickname": "string",    //带单员昵称
      "leaderAvatar": "string"       //带单员头像
    }
  ]
}

获取历史带单 Edit

/v1/copy-trade-order/copy-trade/order/his-leader-order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 交易对,不传表示查询所有的交易对
direction string false NEXT 分页查询方向 PREV-上一页,NEXT-下一页
limit number false 10 每页的数量 1-100
id object false 起始ID,例如 6216559590087220004

限流规则

2/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",
      "orderId": "string",        //订单id
      "symbol": "string",         //市场
      "buySize": 0,               //买入数量
      "buyTime": 0,               //买入时间
      "buyPrice": 0,              //买入价格
      "sellSize": 0,              //卖出数量
      "sellTime": 0,              //卖出时间
      "sellPrice": 0,             //卖出价格
      "profit": 0,                //收益
      "profitRate": 0,            //收益率
      "triggerProfitPrice": 0,    //止盈
      "triggerStopPrice": 0,      //止损
      "followCount": 0            //跟单人数
    }
  ]
}

设置带单或跟单止盈止损 Edit

/v1/copy-trade-order/copy-trade/order/stop-profit-loss

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 交易对
leaderOrderId number true 跟单止盈止损传leaderOrderId,带单止盈止损传orderId
triggerProfitPrice number false 止盈价格
triggerStopPrice number false 止损价格

限流规则

50/s/apikey

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

卖出带单 Edit

/v1/copy-trade-order/copy-trade/order/sell

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderOrderId number true 带单订单id
symbol string true 交易对

限流规则

50/s/apikey

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

卖出全部带单 Edit

/v1/copy-trade-order/copy-trade/order/sell-all

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderOrder bool true true:卖出全部带单;false:卖出全部跟单
symbol string false 交易对

限流规则

50/s/apikey

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

结束跟单 Edit

/v1/copy-trade-order/copy-trade/order/close

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderOrderId number true 带单订单id
symbol string true 交易对

限流规则

50/s/apikey

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

结束全部跟单 Edit

/v1/copy-trade-order/copy-trade/order/close-all

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 交易对

限流规则

50/s/apikey

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

获取跟单交易对信息 Edit

/v1/copy-trade-market/public/copy-trade/symbol

限流规则

2/s/apikey

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": [{
      symbolId: 1,       //市场id
      symbol: "btc_usdt" //市场
  }]
}            

获取用户角色 Edit

/v1/copy-trade-account/copy-trade/user-status

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": "string"        //LEADER:带单员、FOLLOWER:跟单员、NONE:无身份
}

获取带单设置 Edit

/v1/copy-trade-account/copy-trade/leader-settings

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "displayEquity": true,      //是否展示总资产
    "displayQuantity": true,    //是否展示买入数量
    "labelIds": "string",       //带单员已选标签id,逗号分割;例:1,2,3,4
    "leaderIntro": "string",    //带单简介
    "leaderSymbol": [           //带单员已选市场
         "btc_usdt"
    ],
    "openLeader": true,        //现货带单
    "symbolConfig": [          //全部带单市场
         "btc_usdt"
    ],
    "tagsConfig": [            //全部标签配置
      {
        "id": 0,
        "label": "string"
      }
    ]
  }
}

修改带单设置 Edit

/v1/copy-trade-account/copy-trade/leader-settings

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderIntro string false 带单简介
labelIds string false 标签id,逗号分割;例:1,2,3,4
displayEquity bool false 是否展示总资产
displayQuantity bool false 是否展示买入数量
symbols string true 带单市场,逗号分割;例:btc_usdt,eth_usdt
openLeader bool false 是否开启现货带单

Limit Flow Rules

2/s/ip

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

查询带单员历史分润汇总 Edit

/v1/copy-trade-balance/copy-trade/share-profit/his

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
direction string false NEXT 分页查询方向 PREV-上一页,NEXT-下一页
limit number false 10 每页的数量 1-100
id object false 起始ID,例如 6216559590087220004

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
      {
        "amount": 0,    //分润金额
        "id": "string", //用于分页查询的id
        "time": 0       //分润时间
      }
    ]
  }
}

获取历史分润明细 Edit

/v1/copy-trade-balance/copy-trade/share-profit/his-detail

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
time number true 分润时间,例如 1717545600000
direction string false NEXT 分页查询方向 PREV-上一页,NEXT-下一页
limit number false 10 每页的数量 1-100
id object false 起始ID,例如 6216559590087220004

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
      {
        "amount": 0,            //分润金额
        "avatar": "string",     //跟单员头像
        "id": 0,                //用于分页查询的id
        "name": "string"        //跟单员昵称
      }
    ]
  }
}

获取预计待分润总额 Edit

/v1/copy-trade-balance/copy-trade/share-profit/expected

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": 0    //预计待分润总额
}

获取预计待分润明细 Edit

/v1/copy-trade-balance/copy-trade/share-profit/expected-detail

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
direction string false NEXT 分页查询方向 PREV-上一页,NEXT-下一页
limit number false 10 每页的数量 1-100
id object false 起始ID,例如 6216559590087220004

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
      {
        "amount": 0,        //分润金额
        "avatar": "string", //跟单员头像
        "id": 0,            //用于分页查询的id
        "name": "string"    //跟单员昵称
      }
    ]
  }
}

申请成为带单员 Edit

/v1/copy-trade-account/copy-trade/apply

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": true    //成功或失败
}

停止带单 Edit

/v1/copy-trade-account/copy-trade/cancel-leader

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": true    //true or false
}

获取带单员详情 Edit

/v1/copy-trade-account/public/copy-trade/leader-detail

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountId number true 带单员账号id

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "avatar": "string",        //头像
    "currentFollowNumber": 0,  //当前跟随人数
    "displayEquity": true,     //是否展示总资产
    "displayQuantity": true,   //是否展示买入数量
    "fansNum": 0,              //粉丝数
    "followNumber": 0,         //累计跟随人数
    "label": [                 //标签
      "string"
    ],
    "leadDays": 0,             //入驻时间
    "leaderIntro": "string",   //带单简介
    "level": 0,                //当前等级
    "levelId": 0,              //等级id
    "levelName": "string",     //当前等级名称
    "maxFollowerSize": 0,      //最多跟随人数
    "nickName": "string",      //昵称
    "profitRate": 0,           //分润比例
    "totalRights": 0           //总资产
  }
}

获取我的带单员 Edit

/v1/copy-trade-account/copy-trade/my-leaders

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
type number true 带单员类型 带单员类型,1:当前带单员; 2:历史带单员
direction string false NEXT 分页查询方向 PREV-上一页,NEXT-下一页
limit number false 10 每页的数量 1-100
id object false 起始ID,例如 6216559590087220004

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
      {
        "accountId": 0,        //带单员账号
        "avatar": "string",    //头像
        "followMargin": 0,     //跟随本金
        "followProfit": 0,     //跟随收益
        "id": 0,               //用于分页查询的id
        "leaderName": "string" //带单员昵称
      }
    ]
  }
}

查询我的跟单配置 Edit

/v1/copy-trade-account/copy-trade/follow-leader-config

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderAccountId number true 带单员id

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "autoFollowSymbol": true,                //是否自动跟单新增币对
    "followLoss": 0,                         //跟单止损
    "followLossOperate": "LEADER_CLOSE",     //跟单止损仓位处理。MARKET_SELL;LEADER_CLOSE;MANUAL_PROCESS
    "followSymbols": [                       //跟单市场,逗号分隔(跟单员已选交易对)
         "string"
    ],
    "followType": "FUND",                    //跟单方式:FUND(固定保证金);RATE(按倍率跟单)
    "followVal": 0,                          //保证金/倍率
    "leaderSymbols": [                       //交易员带单交易对(可选交易对)
         "string"
    ],
    "profitRate": 0,                         //交易员分润比例
    "triggerProfitRate": 0,                  //单笔止盈
    "triggerStopRate": 0                     //单笔止损
  }
}

立即跟单/跟单设置 Edit

/v1/copy-trade-account/copy-trade/follow

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderAccountId number true 带单员accountId
followType string true 跟单方式 跟单类型, FUND(固定保证金);RATE(按倍率跟单)
followVal number true 保证金/倍率
followLoss number false 跟单止损
followLossOperate string true 跟单止损仓位处理 跟单止损仓位处理类型, MARKET_SELL;LEADER_CLOSE;MANUAL_PROCESS
triggerStopRate number false 单笔止损
triggerProfitRate number false 单笔止盈
autoFollowSymbol bool true 自动跟单新增币对
symbols string true 跟单市场,逗号分隔,例如 xt_usdt,btc_usdt

限流规则

2/s/ip

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

停止跟单 Edit

/v1/copy-trade-account/copy-trade/cancel-follow

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderAccountId number true 带单员账号id

限流规则

2/s/ip

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

获取带单员带单统计 Edit

/v1/copy-trade-balance/public/copy-trade/leader-stats

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountId number true 带单员账号id
days string false 7 查询天数 7,30,90,180,all

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "avgHoldTime": 0,           //平均持仓时间(秒)
    "avgLossAmount": 0,         //平均亏损
    "avgProfitAmount": 0,       //平均盈利
    "followerMargin": 0,        //带单规模
    "followersEarnings": 0,     //跟单者收益
    "lastTradeTime": 0,         //最近交易时间
    "lossCount": 0,             //亏损次数
    "maxRetraction": 0,         //最大回撤
    "pnlRate": "string",        //盈亏比
    "profitCount": 0,           //盈利次数
    "recentRate": 0,            //收益率
    "totalEarnings": 0,         //总收益
    "totalTransactions": 0,     //交易次数
    "tradeDays": 0,             //交易天数
    "weeklyTradeFrequency": 0,  //交易频次(每周)
    "winRate": 0                //胜率
  }
}

查询带单员每日收益图图表 Edit

/v1/copy-trade-balance/public/copy-trade/leader-income-chart

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountId number true 带单员账号id
days string false 7 查询天数 7,30,90,180

限流规则

2/s/ip

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

查询带单员每日累计收益图图表 Edit

/v1/copy-trade-balance/public/copy-trade/leader-income-rate

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountId number true 带单员账号id
days string false 7 查询天数 7,30,90,180

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "incomeRate": [        //当日收益率
      {
        "amount": 0,
        "id": "string",
        "time": 0
      }
    ],
    "totalIncome": [        //累计收益
      {
        "amount": 0,
        "id": "string",
        "time": 0
      }
    ],
    "totalIncomeRate": [    //累计收益率
      {
        "amount": 0,
        "id": "string",
        "time": 0
      }
    ]
  }
}

查询带单员币种偏好 Edit

/v1/copy-trade-balance/public/copy-trade/leader-trading-prefer

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountId number true 带单员账号id
days number false 7 查询天数 7,30,90,180

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": [
    {
      "count": 0,           //交易次数
      "index": 0,
      "percentage": 0,      //占比
      "pnl": 0,             //交易盈亏
      "symbol": "string"    //交易对,其他返回others
    }
  ]
}

查询带单员当前带单 Edit

/v1/copy-trade-order/public/copy-trade/order/leader-order-page

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderAccountId number true 带单员账号id
symbol string false 交易对,不传表示查询所有的交易对
type number true 查询类型 查询类型,1:明细,2:汇总

限流规则

2/s/ip

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",           //id
      "orderId": "string",      //订单id
      "symbol": "string",       //市场
      "buySize": 0,             //买入数量
      "buyTime": 0,             //买入时间
      "buyPrice": 0,            //买入价格
      "sellSize": 0,            //卖出数量
      "sellTime": 0,            //卖出时间
      "sellPrice": 0,           //卖出价格
      "profit": 0,              //收益
      "profitRate": 0,          //收益率
      "triggerProfitPrice": 0,  //止盈
      "triggerStopPrice": 0,    //止损
      "followCount": 0          //跟单人数
    }
  ]
}

查询带单员历史带单 Edit

/v1/copy-trade-order/public/copy-trade/order/leader-order-history

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderAccountId number true 带单员账号id
symbol string false 交易对,不传表示查询所有的交易对
direction string false NEXT 分页查询方向 PREV-上一页,NEXT-下一页
limit number false 10 每页的数量 1-100
id object false 起始ID,例如 6216559590087220004

限流规则

2/s/ip

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "id": "string",           //id
      "orderId": "string",      //订单id
      "symbol": "string",       //市场
      "buySize": 0,             //买入数量
      "buyTime": 0,             //买入时间
      "buyPrice": 0,            //买入价格
      "sellSize": 0,            //卖出数量
      "sellTime": 0,            //卖出时间
      "sellPrice": 0,           //卖出价格
      "profit": 0,              //收益
      "profitRate": 0,          //收益率
      "triggerProfitPrice": 0,  //止盈
      "triggerStopPrice": 0,    //止损
      "followCount": 0          //跟单人数
    }
  ]
}

获取我的跟单员列表 Edit

/v1/copy-trade-account/copy-trade/leader-followers

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
direction string false NEXT 分页查询方向 PREV-上一页,NEXT-下一页
limit number false 10 每页数量 1-100
id object false 起始ID,例如 6216559590087220004

限流规则

2/s/ip

{
  "ma": [
    {}
  ],
  "mc": "string",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
      {
        "accountId": 0,            //跟单员帐号id
        "avatar": "string",        //头像
        "days": 0,                 //跟单天数
        "followMargin": 0,         //累计跟随本金
        "followProfit": 0,         //累计跟随收益
        "followProfitRate": 0,     //跟单收益率
        "followerName": "string",  //跟随用户昵称
        "id": 0,
        "pageId": 0
      }
    ]
  }
}

REST API Edit

Official:

USDT-M:https://fapi.xt.com

Coin-M:https://dapi.xt.com

Basic Information of the Interface Edit

Due to the reasons of high latency and poor stability, it is not recommend to access the XT API through a proxy.

GET request parameters are put in query Params, POST request parameters are put in request body.

The request header information is set to: Content-Type=application/x-www-form-urlencoded

In addition to the parameters required by the interface itself, signature, which is the signature parameter, needs to be passed in the query Params or request body. The interface that does not need to pass the signature parameter will be additionally explained.

Frequency Limiting Rules Edit

Get assets 3 times per second, other methods 10 times per second for each single user, 1000 times per minute for each single IP, exceeding the requested times, account will be locked for 10 minutes.

Signature Statement 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 most important.

  1. Offline distribution of appkey and secretkey, for different calls, provide different appkey and secretkey.

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

  3. Add signature information for all data.

  4. Add recvwindow, the valid time is relatively simple and fixed to a certain value. For example, the data is valid within 10 minutes under the same api and appid. Here, it can be further optimized to the valid time of a single api is different.

The server determines the timestamp when it receives a request. Up to 60 seconds, and the default is 5 seconds. If it was sent 5000 milliseconds ago, the request will be considered invalid. This time window value can be customized 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, so your application’s local time delay to the XT server may be jitter.This is the purpose of setting recvWindow. If you are engaged in high-frequency trading and have high requirements for trading timeliness, you can flexibly set recvWindow to meet your requirements.

RecvWindow for more than 5 seconds is not recommended.

5、5. Add algorithms (signature method/algorithm). User’s signature calculation is a HSC-based protocol, where HmacSHA256 is used by default. See the specific supported protocols listed in the table below.

Name Mandatory Example Description
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow false 5000(millisecond)
validate-algorithms false HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,默认为:HmacSHA256
api-version false 1.0 Reserved, API version number
validate-signversion false 1.0 Reserved, signature version number

Obtain Signature Edit

Example for http://fapi.xt.com/api/v1/public/symbol/detail?symbol=btc_usdt

The following is an example of an order placed in a call interface using echo openssl and curl tools in a Linux bash environment. Appkey, secret for demonstration purposes only:

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Partial data of Header:

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

validate-timestamp: 1641446237201

validate-algorithms: HmacSHA256

Request data:

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

1、Data

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: Sorted by lexicographic order of key, concatenate all key=value. Example: userName=dfdfdf&password=ggg

body: Json: Operate as JSON string is not converted or sorted.

      x-www-form-urlencoded: Sorted by lexicographic order of key, concatenate all key=value. Example: userName=dfdfdf&password=ggg 

      form-data:Not supported.

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

Example of Path:

      /future/api/v1/public/symbol/detail

      The above concatenated value is recorded as path

Example 1: All parameters sent via query string

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        The above concatenate value is recorded as query

Example 2: All parameters send X-www-form-urlencoded request body string via the request body

Request body string of json

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        The above concatenate value is recorded as body

Request body string of www-form-urlencoded

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

        The above concatenate value is recorded as body

Example 3: Mix to use query string and request body (form and json format)

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

requestBody: {“quantity”:2,”price”:39000} The above concatenate value is recorded as query

    The final concatenate value of the entire data is # concatenated with path, query, and body and form #path, #query, and #body. The finalconcatenate value is recorded asY=#path#query#body。

    Note:

        query without data, body with data:Y=#path#body

        query with data, body without data:Y=#path#query

        query with data, body with data:Y=#path#query#body

2:Request header X=”validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-timestamp=1641446237201”

3:Obtain Signature

Finally, record the string that needs to be encrypted as sign=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, sign);

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

How to Apply for API Key Edit

The interface may require the user’s API Key, please refer to how to create an API-KEY this page(https://xtsupport.zendesk.com/hc/zh-cn/articles/900006868163-%E5%A6%82%E4%BD%95%E7%94%B3%E8%AF%B7API%E4%BA%A4%E6%98%93-%E5%A6%82%E4%BD%95%E5%88%9B%E5%BB%BAAPI%E5%AF%86%E9%92%A5-)

API Library Edit

Java connector

A lightweight Java code library that provides a method for users to directly call the API

Sdks for each language:

  java: https://github.com/xt-com/xt4-java-demo

Return Format Edit

All interfaces’ returns are in JSON format.

{
    "returnCode": 200,
    "result": {
        "serverTime": 1636612706739
    },
    "msgInfo": "Success."
    "error": null,
}

Error Code Edit

Status code Error information
200 Success
401 Login required
403 Login expired
invalid_params Params error
invalid_order Order illegal
invalid_symbol Symbol illegal
invalid_price Price illegal
invalid_order_type Order type required
invalid_order_side Order side expired
invalid_triggerProfitPrice Trigger profit price illegal
invalid_triggerStopPrice Trigger stop price illegal
invalid_leader Leader not exist
invalid_accountId Account id not exist
invalid_leverage Leverage illegal

Get leader current order Edit

/future/copytrade/order/v1/copy-trade/leader-order-list

Parameters
Parameter Type mandatory Default Description Ranges
type number true type,1(detail),2(total) 12
symbol string false symbol
direction string false direction NEXT,PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // symbol
        "positionType": "string", // position type:CROSSED;ISOLATED
        "positionSide": "string", // direction:LONG;SHORT
        "openLeverage": 5, // leverage
        "id": 0, // id
        "orderId": 0, // order id
        "trackNo": 0, // trackNo
        "openTime": 0, // open time
        "closeTime": 0, // close time
        "entryPrice": 0, // position price
        "openPrice": 0, // open price
        "closePrice": 0, // close price
        "profitRate": 0, // profit rate
        "openMargin": 0, // open margin
        "realizedPnl": 0, // realized pnl
        "fee": 0, // fee
        "openSize": 0, // open quantity
        "closeSize": 0, // close quantity
        "positionSize": 0, // position quantity
        "closeOrderSize": 0, // close order quantity
        "availableCloseSize": 0, // available close quantity
        "triggerProfitPrice": 0, // trigger profit price
        "triggerStopPrice": 0, // trigger stop price
        "triggerPriceType": "string", // trigger price type:LATEST_PRICE,MARK_PRICE
        "followOrderCount": 0 // follow order count
        }
]
}

Get leader current order page Edit

/future/copytrade/order/v1/copy-trade/leader-order-page

Parameters
Parameter Type mandatory Default Description Ranges
type number true type,1(detail),2(total) 12
symbol string false symbol
direction string false direction NEXT,PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // symbol
        "positionType": "string", // position type:CROSSED;ISOLATED
        "positionSide": "string", // direction:LONG;SHORT
        "openLeverage": 5, // leverage
        "id": 0, // id
        "orderId": 0, // order id
        "trackNo": 0, // trackNo
        "openTime": 0, // open time
        "closeTime": 0, // close time
        "entryPrice": 0, // position price
        "openPrice": 0, // open price
        "closePrice": 0, // close price
        "profitRate": 0, // profit rate
        "openMargin": 0, // open margin
        "realizedPnl": 0, // realized pnl
        "fee": 0, // fee
        "openSize": 0, // open quantity
        "closeSize": 0, // close quantity
        "positionSize": 0, // position quantity
        "closeOrderSize": 0, // close order quantity
        "availableCloseSize": 0, // available close quantity
        "triggerProfitPrice": 0, // trigger profit price
        "triggerStopPrice": 0, // trigger stop price
        "triggerPriceType": "string", // trigger price type:LATEST_PRICE,MARK_PRICE
        "followOrderCount": 0 // follow order count
        }
]
}

Get leader history order page Edit

/future/copytrade/order/v1/copy-trade/leader-order-history

Parameters
Parameter Type mandatory Default Description Ranges
type number true type,1(detail),2(total) 12
symbol string false symbol
direction string false direction NEXT,PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
    "hasPrev": false,
    "hasNext": false,
    "items": [
            {
            "symbolName": "string", // symbol
            "positionType": "string", // position type:CROSSED;ISOLATED
            "positionSide": "string", // direction:LONG;SHORT
            "openLeverage": 5, // leverage
            "id": 0, // id
            "orderId": 0, // order id
            "trackNo": 0, // trackNo
            "openTime": 0, // open time
            "closeTime": 0, // close time
            "entryPrice": 0, // position price
            "openPrice": 0, // open price
            "closePrice": 0, // close price
            "profitRate": 0, // profit rate
            "openMargin": 0, // open margin
            "realizedPnl": 0, // realized pnl
            "fee": 0, // fee
            "openSize": 0, // open quantity
            "closeSize": 0, // close quantity
            "positionSize": 0, // position quantity
            "closeOrderSize": 0, // close order quantity
            "availableCloseSize": 0, // available close quantity
            "triggerProfitPrice": 0, // trigger profit price
            "triggerStopPrice": 0, // trigger stop price
            "triggerPriceType": "string", // trigger price type:LATEST_PRICE,MARK_PRICE
            "followOrderCount": 0 // follow order count
            }
        ]
}
}

Get leader history profit detail Edit

/future/copytrade/user/v1/copy-trade/my-profit-history-detail

Parameters
Parameter Type mandatory Default Description Ranges
divideTime number true time
direction string false direction NEXT,PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
        "hasPrev": false,
        "hasNext": false,
        "items": [
                {
                "avatar": "string", // avatar
                "name": "string", // leader name
                "profit": 5, // amount
                "profitTime": "time", // time
                "coin": 0, // currency
                "id":  // id
                }
        ]
}
}

Get leader future profit total Edit

/future/copytrade/user/v1/copy-trade/my-profit-history

Parameters
Parameter Type mandatory Default Description Ranges
direction string false direction NEXT,PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
    "hasPrev": false,
    "hasNext": false,
     "items": [
               {
                "avatar": "string", // avatar
                "name": "string", // leader name
                "profit": 5, // amount
                "profitTime": "time", // time
                "coin": 0, // currency
                "id":  // id
                }
       ]
}
}

Get leader future profit detail Edit

/future/copytrade/user/v1/copy-trade/my-profit-future

Parameters
Parameter Type mandatory Default Description Ranges
direction string false direction NEXT,PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
    "hasPrev": false,
    "hasNext": false,
    "items": [
            {
            "avatar": "string", // avatar
            "name": "string", // leader name
            "profit": 5, // amount
            "profitTime": "time", // time
            "coin": 0, // currency
            "id":  // id
            }
    ]
}
}

Get leader future profit total Edit

/future/copytrade/user/v1/copy-trade/my-profit-future-total

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": 0 // amount
}

Get leader info Edit

/future/copytrade/user/v1/copy-trade/leader-detail

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
        "nickName": "string", // nickName
        "avatar": "string", // avatar
        "intro": "string", // intro
        "leadDays": 0, // begin time
        "levelId": 0, // leader level id
        "level": 0, // leader level
        "levelName": "string", // leader level name
        "label": ["string"], // labels
        "followNumber": 0, // leader's follower count
        "currentFollowNumber": 0, // leader's current follower count
        "maxFollowerSize": 0, // leader's max follower count
        "profitRate": 0, // leader profit rate
        "platformProfitRate": 0, // platform profit rate
        "totalRights": 0, // total amount
        "displayEquity": Boolean, // is display amount
        "displayPosition": Boolean // is display position
 }
}

Cancel leader Edit

/future/copytrade/user/v1/copy-trade/cancel-leader

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true=success false=fail
}

Get user setting Edit

/future/copytrade/user/v1/copy-trade/user-settings

Limit Flow Rules

10/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
        "id": 0, // id
        "intro": "string", // intro
        "followCapitalMin": 0, // margin
        "labelIds": 0, // label id
        "label": [ // labels
         {
            "id": 0, // id
            "label": "string", // remark
          }
        ], 
        "autoUnfollow": Boolean, // is auto cancel follow
        "displayEquity": Boolean, // is display total amount
        "displayPosition": Boolean, // is display position
        "openLeader": Boolean // is open lead trading
 }
}

Add/update/cancel profit-stop order Edit

/future/copytrade/order/v1/copy-trade/update-profit-stop

Parameters
Parameter Type mandatory Default Description Ranges
trackNo number true trackNo
triggerPriceType string true trigger Price Type LATEST_PRICE,MARK_PRICE
leaderOrder boolean true is leader order true,false
triggerProfitPrice number false trigger profit price
triggerStopPrice number false trigger stop price

Limit Flow Rules

10/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean // true=success false=fail
}

Close all orders Edit

/future/copytrade/order/v1/copy-trade/close-all

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false symbol
closeLongShortType string false direction LONG,SHORT,BOTH

Limit Flow Rules

5/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true=success false=fail
}

Close order Edit

/future/copytrade/order/v1/copy-trade/close

Parameters
Parameter Type mandatory Default Description Ranges
trackNo number true track no
leaderOrder boolean false is leader's order true,false

Limit Flow Rules

5/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true=success false=fail
}

Get follower current order Edit

/future/copytrade/order/v1/copy-trade/follower-order-list

Parameters
Parameter Type mandatory Default Description Ranges
type number false type,1(detail),2(total) 12
symbol string false symbol
direction string false direction NEXT,PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
            {
            "symbolName": "string", // symbol
            "positionType": "string", // position type:CROSSED;ISOLATED
            "positionSide": "string", // direction:LONG;SHORT
            "openLeverage": 5, // leverage
            "id": 0, // id
            "orderId": 0, // order id
            "trackNo": 0, // trackNo
            "openTime": 0, // open time
            "closeTime": 0, // close time
            "openPrice": 0, // open price
            "closePrice": 0, // close price
            "profitRate": 0, // profit rate
            "openMargin": 0, // open margin
            "realizedPnl": 0, // realized pnl
            "leaderNickname": "string", // leader name
            "openSize": 0, // open quantity
            "closeSize": 0, // close quantity
            "positionSize": 0, // position quantity
            "closeOrderSize": 0, // close order quantity
            "availableCloseSize": 0, // available close quantity
            "triggerProfitPrice": 0, // trigger profit price
            "triggerStopPrice": 0, // trigger stop price
            "triggerPriceType": "string", // trigger price type:LATEST_PRICE,MARK_PRICE
            "avatar": "string" // avatar
            }
]
}

Get follower current order page Edit

/future/copytrade/order/v1/copy-trade/follower-order-page

Parameters
Parameter Type mandatory Default Description Ranges
type number false type,1(detail),2(total) 12
symbol string false symbol
direction string false direction NEXT,PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
            {
            "symbolName": "string", // symbol
            "positionType": "string", // position type:CROSSED;ISOLATED
            "positionSide": "string", // direction:LONG;SHORT
            "openLeverage": 5, // leverage
            "id": 0, // id
            "orderId": 0, // order id
            "trackNo": 0, // trackNo
            "openTime": 0, // open time
            "closeTime": 0, // close time
            "openPrice": 0, // open price
            "closePrice": 0, // close price
            "profitRate": 0, // profit rate
            "openMargin": 0, // open margin
            "realizedPnl": 0, // realized pnl
            "leaderNickname": "string", // leader name
            "openSize": 0, // open quantity
            "closeSize": 0, // close quantity
            "positionSize": 0, // position quantity
            "closeOrderSize": 0, // close order quantity
            "availableCloseSize": 0, // available close quantity
            "triggerProfitPrice": 0, // trigger profit price
            "triggerStopPrice": 0, // trigger stop price
            "triggerPriceType": "string", // trigger price type:LATEST_PRICE,MARK_PRICE
            "avatar": "string" // avatar
            }
]
}

Get follower history order page Edit

/future/copytrade/order/v1/copy-trade/follower-order-history

Parameters
Parameter Type mandatory Default Description Ranges
type number false type,1(detail),2(total) 12
symbol string false symbol
direction string false direction NEXT,PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // symbol
        "positionType": "string", // position type:CROSSED;ISOLATED
        "positionSide": "string", // direction:LONG;SHORT
        "openLeverage": 5, // leverage
        "id": 0, // id
        "orderId": 0, // order id
        "trackNo": 0, // trackNo
        "openTime": 0, // open time
        "closeTime": 0, // close time
        "openPrice": 0, // open price
        "closePrice": 0, // close price
        "profitRate": 0, // profit rate
        "openMargin": 0, // open margin
        "realizedPnl": 0, // realized pnl
        "leaderNickname": "string", // leader name
        "openSize": 0, // open quantity
        "closeSize": 0, // close quantity
        "positionSize": 0, // position quantity
        "closeOrderSize": 0, // close order quantity
        "availableCloseSize": 0, // available close quantity
        "triggerProfitPrice": 0, // trigger profit price
        "triggerStopPrice": 0, // trigger stop price
        "triggerPriceType": "string", // trigger price type:LATEST_PRICE,MARK_PRICE
        "avatar": "string" // avatar
        }
]
}

Choose leader Edit

/future/copytrade/user/v1/copy-trade/choose-leader

Parameters
Parameter Type mandatory Default Description Ranges
leaderAccountId number true leader accountId
symbols string true symbol
followType string true follow type FUND,RATE,MARGIN_RATE
followVal number false
triggerProfitRate number false profit rate
triggerStopRate number false stop rate
followDirection string false direction FORWARD,REVERSE
followLoss number false follow loss
autoFollowSymbol boolean false is auto follow symbol true,false
followLossOperate enum false follow loss operation MARKET_SELL,LEADER_CLOSE,MANUAL_PROCESS

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true=success false=fail
}

Cancel follow leader Edit

/future/copytrade/user/v1/copy-trade/cancel-choose-leader

Parameters
Parameter Type mandatory Default Description Ranges
leaderAccountId number true leader accountId

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true=success false=fail
}

Get my current leaders Edit

/future/copytrade/user/v1/copy-trade/my-follow-list

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [number,number] // leader accountId
}

Get my history leaders Edit

/future/copytrade/user/v1/copy-trade/follower-leaders-page

Parameters
Parameter Type mandatory Default Description Ranges
type number false type(1:current follow,2:history follow) 12
direction string false direction NEXT, PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
       "hasPrev": false,
       "hasNext": false,
        "items": [
{
        "leaderName": "string", // leader nickname
        "avatar": "string", // avatar
        "accountId": 0, // leader accountId
        "id": 0, // id
        "level": 0, // level
        "levelName": "string", // level name
        "followMarginU": 0, // total follow margin
        "followProfitU": 0, // total follow profit
        "cancel": Boolean // status:0 following,1canceled
}
]
}

Get available symbol list Edit

/future/copytrade/public/user/v1/public/copy-trade/symbol-list

Limit Flow Rules

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [string,string] // symbols
}

Public get leader current orders Edit

/future/copytrade/public/order/v1/public/copy-trade/leader-order-page

Parameters
Parameter Type mandatory Default Description Ranges
type number false type(1:detail, 2:total) 12
symbol string false symbol
leaderAccountId number true leader accountId
direction string false direction NEXT, PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // symbol
        "positionType": "string", // position type:CROSSED;ISOLATED
        "positionSide": "string", // direction:LONG;SHORT
        "openLeverage": 5, // leverage
        "id": 0, // id
        "orderId": 0, // order id
        "trackNo": 0, // trackNo
        "openTime": 0, // open time
        "closeTime": 0, // close time
        "entryPrice": 0, // position price
        "openPrice": 0, // open price
        "closePrice": 0, // close price
        "profitRate": 0, // profit rate
        "openMargin": 0, // open margin
        "realizedPnl": 0, // realized pnl
        "fee": 0, // fee
        "openSize": 0, // open quantity
        "closeSize": 0, // close quantity
        "positionSize": 0, // position quantity
        "closeOrderSize": 0, // close order quantity
        "availableCloseSize": 0, // available close quantity
        "triggerProfitPrice": 0, // trigger profit price
        "triggerStopPrice": 0, // trigger stop price
        "triggerPriceType": "string", // trigger price type:LATEST_PRICE,MARK_PRICE
        "followOrderCount": 0 // follow order count
        }
]
}

Public get leader history orders Edit

/future/copytrade/public/order/v1/public/copy-trade/leader-order-history

Parameters
Parameter Type mandatory Default Description Ranges
type number false type(1:detail, 2:total) 12
symbol string false symbol
leaderAccountId number true leader accountId
direction string false direction NEXT, PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // symbol
        "positionType": "string", // position type:CROSSED;ISOLATED
        "positionSide": "string", // direction:LONG;SHORT
        "openLeverage": 5, // leverage
        "id": 0, // id
        "orderId": 0, // order id
        "trackNo": 0, // trackNo
        "openTime": 0, // open time
        "closeTime": 0, // close time
        "entryPrice": 0, // position price
        "openPrice": 0, // open price
        "closePrice": 0, // close price
        "profitRate": 0, // profit rate
        "openMargin": 0, // open margin
        "realizedPnl": 0, // realized pnl
        "fee": 0, // fee
        "openSize": 0, // open quantity
        "closeSize": 0, // close quantity
        "positionSize": 0, // position quantity
        "closeOrderSize": 0, // close order quantity
        "availableCloseSize": 0, // available close quantity
        "triggerProfitPrice": 0, // trigger profit price
        "triggerStopPrice": 0, // trigger stop price
        "triggerPriceType": "string", // trigger price type:LATEST_PRICE,MARK_PRICE
        "followOrderCount": 0 // follow order count
        }
]
}

Public get leader day income Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-day-income

Parameters
Parameter Type mandatory Default Description Ranges
accountId number true leader accountId
days number false days

Limit Flow Rules

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "amount": 0, // amount
        "time": 0 // time
        }
]
}

Public get leader day income rate Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-day-income-rate

Parameters
Parameter Type mandatory Default Description Ranges
accountId number true leader accountId
days number false days

Limit Flow Rules

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
       "totalIncome":[{
        "amount": 0, // amount
         "time": 0 // time
        }],
       "totalIncomeRate":[{
        "amount": 0, // amount
        "time": 0 // time
        }],
        "incomeRate":[
         {"amount": 0, // amount
         "time": 0 // time
         }]
}
}

Public get leader statistics Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-stats

Parameters
Parameter Type mandatory Default Description Ranges
accountId number true leader accountId
days number false days

Limit Flow Rules

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result":{
"recentRate": 0, // current rate
"totalEarnings": 0, // total current
"maxRetraction": 0, // max retraction
"followersEarnings": 0, // follower's earning
"winRate": 0, // win rate
"totalTransactions": 0, // total transactions
"profitCount": 0, // profit count
"lossCount": 0, // loss count
"avgProfitAmount": 0, // avg profit amount
"avgLossAmount": 0, // avg loss amount
"pnlRate": 0, // profit loss rate
"avgHoldTime": 0, // avg hold time
"weeklyTradeFrequency": 0, // trade frequency
"followerMargin": 0, // follower total margin
"tradeDays": 0, // total trade days
"lastTradeTime": 0, // last tradetime
}
}

Public get leader's prefer Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-symbol-prefer

Parameters
Parameter Type mandatory Default Description Ranges
accountId number true leader accountId
recentDays number false days

Limit Flow Rules

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result":{
        "index": 0, // 
        "symbol": "string", // symbol
        "count": 0, // count
        "percentage": 0, // percent
        "pnl": 0 // pnl
 }
}

Public get leader info Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-detail-v2

Parameters
Parameter Type mandatory Default Description Ranges
accountId number true leader accountId

Limit Flow Rules

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
        "nickName": "string", // nickName
        "avatar": "string", // avatar
        "intro": "string", // intro
        "leadDays": 0, // begin time
        "levelId": 0, // leader level id
        "level": 0, // leader level
        "levelName": "string", // leader level name
        "label": ["string"], // labels
        "followNumber": 0, // leader's follower count
        "currentFollowNumber": 0, // leader's current follower count
        "maxFollowerSize": 0, // leader's max follower count
        "profitRate": 0, // leader profit rate
        "platformProfitRate": 0, // platform profit rate
        "totalRights": 0, // total amount
        "displayEquity": Boolean, // is display amount
        "displayPosition": Boolean // is display position
 }
}

Get follower info Edit

/future/copytrade/user/v1/copy-trade/leader-relation

Parameters
Parameter Type mandatory Default Description Ranges
leaderAccountId number true leader account

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
        "leaderAccountId": 0, // leader accountId
        "symbols": "string", // symbol
        "followLoss": 0, // follow loss
        "followLossOperate": enum, // operatio(MARKET_SELL,LEADER_CLOSE,MANUAL_PROCESS)
        "triggerProfitRate": 0, // trigger profit rate
        "triggerStopRate": 0, // trigger stop rate
        "cancel": Boolean, // is cancel (true=canceled, false=uncanceled)
        "followDirection": 0, // direction:FORWARDREVERSE
        "followType": 0, // flow type:FUND;RATE;MARGIN_RATE
        "followVal": 0, // follow val
        "autoFollowSymbol": Boolean // is auto follow new add symbol
}
}

Public get leader's followers Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-follower-page

Parameters
Parameter Type mandatory Default Description Ranges
type number false type(1:detail,2:total) 12
symbol string false symbol
leaderAccountId number true leader accountId
direction string false direction NEXT, PREV
limit number false page size 10
id number false id

Limit Flow Rules

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "accountId": 0, // leader accountId
        "followerName": "string", // follower nickname
        "avatar": "string", // avatar
        "id": 0, // id
        "pageId": 0, // pageId
        "followMarginU": 0, // follower total margin
        "followProfitU": 0, // follower total profit
        "followProfitRate": 0, // follower profit rate
        "days": 0 // days
        }
]
}

Get leverage list Edit

/future/copytrade/order/v1/position/list

Parameters
Parameter Type mandatory Default Description Ranges
symbol string false symbol
welfareAccountVersion string false version

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
          {
            "symbol": "string", //symbol
            "positionType": "string",//position type:CROSSED;ISOLATED
            "positionSide": "string",//direction
            "contractType": "string",//contract type:PERPETUAL、PREDICT
            "positionSize": 0,// position size
            "closeOrderSize": 0,//close order size
            "availableCloseSize": 0,//available close size
            "entryPrice": 0,//open price
            "openOrderSize": 0,//open order size
            "isolatedMargin": 0,// isolated margin
            "openOrderMarginFrozen": 0,//open order margin frozen
            "realizedProfit": 0,//realized pnl
            "autoMargin": false,//is auto add margin
            "leverage": 0, // leverage
            "profitId": 0,//profit order id
            "triggerPriceType": 0,//trigger price type 1index price 2mark price 3deal price
            "triggerProfitPrice": 0,//trigger profit price
            "triggerStopPrice": 0,//trigger stop price
            "welfareAccount": boolean //is welfare account
           }
  ]
}

adjust leverage Edit

/future/copytrade/order/v1/position/adjust-leverage

Parameters
Parameter Type mandatory Default Description Ranges
symbol string true symbol
leverage number true leverage
positionSide enum false direction LONG,SHORT,BOTH

Limit Flow Rules

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true=success false=fail
}

REST API Edit

正式:

U本位合约:https://fapi.xt.com

币本位合约:https://dapi.xt.com

接口的基本信息 Edit

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

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

请求头信息请设置为:Content-Type=application/x-www-form-urlencoded

除了接口本身所需的参数外,还需要在query Params 或 request body中传递 signature, 即签名参数,不需要传递签名参数的接口会额外说明。

限频规则 Edit

获取资产每秒3次,其他方法单个用户每秒10次,单个IP每分钟1000次,超出锁定账户10分钟。

签名说明 Edit

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

1、线下分配appkey和secretkey,针对不同的调用,提供不同的appkey和secretkey

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

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

4、加入recvwindow(自定义请求有效时间),有效时间目前相对简单统一固定为某个值,比如:同api同appid下10分钟内数据都有郊,此处可以再进步优化到具体单个api有效时间都不相同。

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

不推荐使用5秒以上的recvWindow

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

字段名 是否必须 示例 说明
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow false 5000(毫秒)
validate-algorithms false HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,默认为:HmacSHA256
api-version false 1.0 保留,API版本号
validate-signversion false 1.0 保留,签名版本号

签名生成 Edit

http://fapi.xt.com/future/api/v1/public/symbol/detail?symbol=btc_usdt的示例

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

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Header部分数据:

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

validate-timestamp: 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9

validate-algorithms: HmacSHA256

请求数据:

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

1、数据部分

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的顺序进行再拼接,得到所有数据的拼接值。

路径Path示例:

      /future/api/v1/public/symbol/detail

      上述拼接值记作为path

示例 1: 所有参数通过 query string 发送

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        上述值拼接记作query

示例 2: 所有参数通过 request body 发送

x-www-form-urlencoded的request body string :

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        上述值拼接记作body

json的request body string :

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

        上述值拼接记作body

示例 3: 混合使用 query string 与 request body(分为表单与json两种格式)

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

requestBody: {“quantity”:2,”price”:39000} 上述拼接值记作body

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

    注意:

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

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

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

2、请求头部分 X=”validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-timestamp=1641446237201”

3、生成签名

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

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

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

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

API Key申请步骤 Edit

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

API 代码库 Edit

Java connector

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

各个语言的sdk:

  java: https://github.com/xt-com/xt4-java-demo

返回格式 Edit

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

{
    "returnCode": 200,
    "result": {
        "serverTime": 1636612706739
    },
    "msgInfo": "Success."
    "error": null,
}

错误代码 Edit

状态码 错误信息
200 成功
401 需要登录
403 登录过期
invalid_params 参数异常
invalid_order 订单异常
invalid_symbol 错误的市场
invalid_price 错误的价格
invalid_order_type orderType 必传
invalid_order_side orderSide 必传
invalid_triggerProfitPrice 止盈价格错误
invalid_triggerStopPrice 止损价格错误
invalid_leader 交易员不存在
invalid_accountId accountId错误
invalid_leverage 杠杆倍数错误

获取当前带单 Edit

/future/copytrade/order/v1/copy-trade/leader-order-list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
type number true 查询类型,1:明细,2:汇总
symbol string false 交易对
direction string false 方向(NEXT, PREV)
limit number false 翻页大小 10
id number false id

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // 市场名称
        "positionType": "string", // 仓位类型:CROSSED(全仓);ISOLATED(逐仓)
        "positionSide": "string", // 持仓方向:LONG;SHORT
        "openLeverage": 5, // 杠杆
        "id": 0, // id
        "orderId": 0, // 订单id
        "trackNo": 0, // 跟单trackNo
        "openTime": 0, // 开仓时间
        "closeTime": 0, // 平仓时间
        "entryPrice": 0, // 持仓均价
        "openPrice": 0, // 开仓均价
        "closePrice": 0, // 平仓均价
        "profitRate": 0, // 收益率
        "openMargin": 0, // 开仓初始保证金
        "realizedPnl": 0, // 已实现盈亏
        "fee": 0, // 手续费
        "openSize": 0, // 开仓仓位数量
        "closeSize": 0, // 平仓仓位数量
        "positionSize": 0, // 持仓数量
        "closeOrderSize": 0, // 平仓订单占用
        "availableCloseSize": 0, // 可平数量
        "triggerProfitPrice": 0, // 止盈价
        "triggerStopPrice": 0, // 止损价
        "triggerPriceType": "string", // 触发价格类型:LATEST_PRICE,MARK_PRICE
        "followOrderCount": 0 // 跟随订单数
        }
]
}

获取带单员当前带单 Edit

/future/copytrade/order/v1/copy-trade/leader-order-page

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
type number true 查询类型,1:明细,2:汇总
symbol string false 交易对
direction string false 方向(NEXT, PREV)
limit number false 翻页大小 10
id number false id

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // 市场名称
        "positionType": "string", // 仓位类型:CROSSED(全仓);ISOLATED(逐仓)
        "positionSide": "string", // 持仓方向:LONG;SHORT
        "openLeverage": 5, // 杠杆
        "id": 0, // id
        "orderId": 0, // 订单id
        "trackNo": 0, // 跟单trackNo
        "openTime": 0, // 开仓时间
        "closeTime": 0, // 平仓时间
        "entryPrice": 0, // 持仓均价
        "openPrice": 0, // 开仓均价
        "closePrice": 0, // 平仓均价
        "profitRate": 0, // 收益率
        "openMargin": 0, // 开仓初始保证金
        "realizedPnl": 0, // 已实现盈亏
        "fee": 0, // 手续费
        "openSize": 0, // 开仓仓位数量
        "closeSize": 0, // 平仓仓位数量
        "positionSize": 0, // 持仓数量
        "closeOrderSize": 0, // 平仓订单占用
        "availableCloseSize": 0, // 可平数量
        "triggerProfitPrice": 0, // 止盈价
        "triggerStopPrice": 0, // 止损价
        "triggerPriceType": "string", // 触发价格类型:LATEST_PRICE,MARK_PRICE
        "followOrderCount": 0 // 跟随订单数
        }
]
}

获取带单员历史带单 Edit

/future/copytrade/order/v1/copy-trade/leader-order-history

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
type number true 查询类型,1:明细,2:汇总
symbol string false 交易对
direction string false 方向(NEXT, PREV)
limit number false 翻页大小 10
id number false id

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
    "hasPrev": false,
    "hasNext": false,
    "items": [
            {
            "symbolName": "string", // 市场名称
            "positionType": "string", // 仓位类型:CROSSED(全仓);ISOLATED(逐仓)
            "positionSide": "string", // 持仓方向:LONG;SHORT
            "openLeverage": 5, // 杠杆
            "id": 0, // id
            "orderId": 0, // 订单id
            "trackNo": 0, // 跟单trackNo
            "openTime": 0, // 开仓时间
            "closeTime": 0, // 平仓时间
            "entryPrice": 0, // 持仓均价
            "openPrice": 0, // 开仓均价
            "closePrice": 0, // 平仓均价
            "profitRate": 0, // 收益率
            "openMargin": 0, // 开仓初始保证金
            "realizedPnl": 0, // 已实现盈亏
            "fee": 0, // 手续费
            "openSize": 0, // 开仓仓位数量
            "closeSize": 0, // 平仓仓位数量
            "positionSize": 0, // 持仓数量
            "closeOrderSize": 0, // 平仓订单占用
            "availableCloseSize": 0, // 可平数量
            "triggerProfitPrice": 0, // 止盈价
            "triggerStopPrice": 0, // 止损价
            "triggerPriceType": "string", // 触发价格类型:LATEST_PRICE,MARK_PRICE
            "followOrderCount": 0 // 跟随订单数
            }
    ]
}
}

获取带单员历史分润明细 Edit

/future/copytrade/user/v1/copy-trade/my-profit-history-detail

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
divideTime number true 分润日期(时间戳)
direction string false 方向(NEXT, PREV)
limit number false 翻页大小 10
id number false id

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
    "hasPrev": false,
    "hasNext": false,
    "items": [{
            "avatar": "string", // 头像
            "name": "string", // 用户名称
            "profit": 5, // 分润数量
            "profitTime": "time", // 日期
            "coin": 0, // 币种
            "id":  // id
            }]
    }
}

获取带单员历史分润汇总 Edit

/future/copytrade/user/v1/copy-trade/my-profit-history

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
direction string false 方向(NEXT, PREV)
limit number false 翻页大小 10
id number false id

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
    "hasPrev": false,
    "hasNext": false,
     "items": [{
                "avatar": "string", // 头像
                "name": "string", // 用户名称
                "profit": 5, // 分润数量
                "profitTime": "time", // 日期
                "coin": 0, // 币种
                "id":  // id
     }]
}
}

获取带单员预计待分润明细 Edit

/future/copytrade/user/v1/copy-trade/my-profit-future

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
direction string false 方向(NEXT, PREV) NEXT,PREV
limit number false 翻页大小 10
id number false id

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
    "hasPrev": false,
    "hasNext": false,
    "items": [{
            "avatar": "string", // 头像
            "name": "string", // 用户名称
            "profit": 5, // 分润数量
            "profitTime": "time", // 日期
            "coin": 0, // 币种
            "id":  // id
    }]
}
}

获取带单员预计待分润汇总 Edit

/future/copytrade/user/v1/copy-trade/my-profit-future-total

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": 0 // 待分润总量
}

带单员信息 Edit

/future/copytrade/user/v1/copy-trade/leader-detail

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
        "nickName": "string", // 名称
        "avatar": "string", // 头像
        "intro": "string", // 简介
        "leadDays": 0, // 入驻时间
        "levelId": 0, // 当前等级id
        "level": 0, // 当前等级
        "levelName": "string", // 当前等级名称
        "label": ["string"], // 标签
        "followNumber": 0, // 累计跟随人数
        "currentFollowNumber": 0, // 当前跟随人数
        "maxFollowerSize": 0, // 最多跟随人数
        "profitRate": 0, // 交易员分润比例
        "platformProfitRate": 0, // 平台分润比例
        "totalRights": 0, // 总权益
        "displayEquity": Boolean, // 是否展示权益
        "displayPosition": Boolean // 是否展示持仓量
  }
}

取消带单员身份 Edit

/future/copytrade/user/v1/copy-trade/cancel-leader

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true成功 false失败
}

获取交易员/跟单员设置信息 Edit

/future/copytrade/user/v1/copy-trade/user-settings

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
        "id": 0, // id
        "intro": "string", // 简介
        "followCapitalMin": 0, // 最小跟单本金
        "labelIds": 0, // 标签id,逗号分割;例:1,2,3,4
        "label": [ // 标签
         {
            "id": 0, // 标签id
            "label": "string", // 标签说明
          }
        ], 
        "autoUnfollow": Boolean, // 是否自动取消跟随
        "displayEquity": Boolean, // 显示总权益:true:展示,false:不展示
        "displayPosition": Boolean, // 显示持仓量:true:展示,false:不展示
        "openLeader": Boolean // 开启带单
  }
}

新增/修改/撤销带单或跟单止盈止损 Edit

/future/copytrade/order/v1/copy-trade/update-profit-stop

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
trackNo number true 交易员带单特有单号
triggerPriceType string true 触发价格类型:LATEST_PRICE,MARK_PRICE
leaderOrder boolean true 是否带单:true 带单,false 跟单
triggerProfitPrice number false 止盈价
triggerStopPrice number false 止损价

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true成功 false失败
}

带单/跟单一键平仓 Edit

/future/copytrade/order/v1/copy-trade/close-all

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 市场名称
closeLongShortType string false 平仓方向:LONG;SHORT;BOTH LONG,SHORT,BOTH

限流规则

5/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true成功 false失败
}

带单/跟单平仓 Edit

/future/copytrade/order/v1/copy-trade/close

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
trackNo number true 交易员带单特有单号
leaderOrder boolean false 是否带单:true 带单,false 跟单 true,false

限流规则

5/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": boolean //true成功 false失败
}

获取当前跟单 Edit

/future/copytrade/order/v1/copy-trade/follower-order-list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
type number false 查询类型,1:明细,2:汇总 12
symbol string false 交易对
direction string false 方向(NEXT, PREV) NEXT,PREV
limit number false 翻页大小 10
id number false id

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // 市场名称
        "positionType": "string", // 仓位类型:CROSSED(全仓);ISOLATED(逐仓)
        "positionSide": "string", // 持仓方向:LONG;SHORT
        "openLeverage": 5, // 杠杆
        "id": 0, // id
        "orderId": 0, // 订单id
        "trackNo": 0, // 跟单trackNo
        "openTime": 0, // 开仓时间
        "closeTime": 0, // 平仓时间
        "openPrice": 0, // 开仓均价
        "closePrice": 0, // 平仓均价
        "profitRate": 0, // 收益率
        "openMargin": 0, // 开仓初始保证金
        "realizedPnl": 0, // 已实现盈亏
        "leaderNickname": "string", // 交易员
        "openSize": 0, // 开仓仓位数量
        "closeSize": 0, // 平仓仓位数量
        "positionSize": 0, // 持仓数量
        "closeOrderSize": 0, // 平仓订单占用
        "availableCloseSize": 0, // 可平数量
        "triggerProfitPrice": 0, // 止盈价
        "triggerStopPrice": 0, // 止损价
        "triggerPriceType": "string", // 触发价格类型:LATEST_PRICE,MARK_PRICE
        "avatar": "string" // 头像
        }
]
}

获取跟单员当前跟单 Edit

/future/copytrade/order/v1/copy-trade/follower-order-page

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
type number false 查询类型,1:明细,2:汇总 12
symbol string false 交易对
direction string false 方向(NEXT, PREV) NEXT,PREV
limit number false 翻页大小 10
id number false id

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // 市场名称
        "positionType": "string", // 仓位类型:CROSSED(全仓);ISOLATED(逐仓)
        "positionSide": "string", // 持仓方向:LONG;SHORT
        "openLeverage": 5, // 杠杆
        "id": 0, // id
        "orderId": 0, // 订单id
        "trackNo": 0, // 跟单trackNo
        "openTime": 0, // 开仓时间
        "closeTime": 0, // 平仓时间
        "openPrice": 0, // 开仓均价
        "closePrice": 0, // 平仓均价
        "profitRate": 0, // 收益率
        "openMargin": 0, // 开仓初始保证金
        "realizedPnl": 0, // 已实现盈亏
        "leaderNickname": "string", // 交易员
        "openSize": 0, // 开仓仓位数量
        "closeSize": 0, // 平仓仓位数量
        "positionSize": 0, // 持仓数量
        "closeOrderSize": 0, // 平仓订单占用
        "availableCloseSize": 0, // 可平数量
        "triggerProfitPrice": 0, // 止盈价
        "triggerStopPrice": 0, // 止损价
        "triggerPriceType": "string", // 触发价格类型:LATEST_PRICE,MARK_PRICE
        "avatar": "string" // 头像
        }
]
}

获取跟单员历史跟单 Edit

/future/copytrade/order/v1/copy-trade/follower-order-history

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
type number false 查询类型,1:明细,2:汇总 12
symbol string false 交易对
direction string false 方向(NEXT, PREV) NEXT,PREV
limit number false 翻页大小 10
id number false id

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // 市场名称
        "positionType": "string", // 仓位类型:CROSSED(全仓);ISOLATED(逐仓)
        "positionSide": "string", // 持仓方向:LONG;SHORT
        "openLeverage": 5, // 杠杆
        "id": 0, // id
        "orderId": 0, // 订单id
        "trackNo": 0, // 跟单trackNo
        "openTime": 0, // 开仓时间
        "closeTime": 0, // 平仓时间
        "openPrice": 0, // 开仓均价
        "closePrice": 0, // 平仓均价
        "profitRate": 0, // 收益率
        "openMargin": 0, // 开仓初始保证金
        "realizedPnl": 0, // 已实现盈亏
        "leaderNickname": "string", // 交易员
        "openSize": 0, // 开仓仓位数量
        "closeSize": 0, // 平仓仓位数量
        "positionSize": 0, // 持仓数量
        "closeOrderSize": 0, // 平仓订单占用
        "availableCloseSize": 0, // 可平数量
        "triggerProfitPrice": 0, // 止盈价
        "triggerStopPrice": 0, // 止损价
        "triggerPriceType": "string", // 触发价格类型:LATEST_PRICE,MARK_PRICE
        "avatar": "string" // 头像
        }
]
}

立即跟单 Edit

/future/copytrade/user/v1/copy-trade/choose-leader

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderAccountId number true 交易员accountId
symbols string true 跟单合约交易对,逗号分隔
followType string true 跟单类型:FUND(固定保证金);RATE(按倍率跟单);MARGIN_RATE(同比例跟单) FUND,RATE,MARGIN_RATE
followVal number false 跟单本金/跟单比例
triggerProfitRate number false 止盈比率
triggerStopRate number false 止损比率
followDirection string false 跟单方向:正向:FORWARD;反向:REVERSE FORWARD,REVERSE
followLoss number false 跟单止损
autoFollowSymbol boolean false 自动跟单新增合约市场 true是 false否 true,false
followLossOperate enum false 跟单止损仓位处理 MARKET_SELL,LEADER_CLOSE,MANUAL_PROCESS

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true成功  false失败
}

取消跟随 Edit

/future/copytrade/user/v1/copy-trade/cancel-choose-leader

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderAccountId number true 交易员accountId

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true成功 false失败
}

我跟随的交易员列表(当前跟随) Edit

/future/copytrade/user/v1/copy-trade/my-follow-list

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [number,number] //交易员accountId
}

我的带单员(历史跟随) Edit

/future/copytrade/user/v1/copy-trade/follower-leaders-page

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
type number false 查询类型,1:当前跟随,2:历史跟随 12
direction string false 方向(NEXT, PREV) NEXT,PREV
limit number false 翻页大小 10
id number false id

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
       "hasPrev": false,
       "hasNext": false,
        "items": [
                {
                "leaderName": "string", // 交易员名称
                "avatar": "string", // 头像
                "accountId": 0, // 交易员id
                "id": 0, // id
                "level": 0, // 当前等级
                "levelName": "string", // 当前等级名称
                "followMarginU": 0, // 累计跟随本金,USDT
                "followProfitU": 0, // 累计跟随收益,USDT
                "cancel": Boolean // 状态:0跟随中,1已取消
                 }
          ]
}

获取跟单合约所有交易对列表 Edit

/future/copytrade/public/user/v1/public/copy-trade/symbol-list

限流规则

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [string,string] // 交易对名称
}

获取交易员当前带单 Edit

/future/copytrade/public/order/v1/public/copy-trade/leader-order-page

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
type number false 查询类型,1:明细,2:汇总
symbol string false 交易对
leaderAccountId number true 交易员帐号
direction string false 方向(NEXT, PREV)
limit number false 翻页大小 10
id number false id

限流规则

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // 市场名称
        "positionType": "string", // 仓位类型:CROSSED(全仓);ISOLATED(逐仓)
        "positionSide": "string", // 持仓方向:LONG;SHORT
        "openLeverage": 5, // 杠杆
        "id": 0, // id
        "orderId": 0, // 订单id
        "trackNo": 0, // 跟单trackNo
        "openTime": 0, // 开仓时间
        "closeTime": 0, // 平仓时间
        "entryPrice": 0, // 持仓均价
        "openPrice": 0, // 开仓均价
        "closePrice": 0, // 平仓均价
        "profitRate": 0, // 收益率
        "openMargin": 0, // 开仓初始保证金
        "realizedPnl": 0, // 已实现盈亏
        "fee": 0, // 手续费
        "openSize": 0, // 开仓仓位数量
        "closeSize": 0, // 平仓仓位数量
        "positionSize": 0, // 持仓数量
        "closeOrderSize": 0, // 平仓订单占用
        "availableCloseSize": 0, // 可平数量
        "triggerProfitPrice": 0, // 止盈价
        "triggerStopPrice": 0, // 止损价
        "triggerPriceType": "string", // 触发价格类型:LATEST_PRICE,MARK_PRICE
        "followOrderCount": 0 // 跟随订单数
        }
]
}

获取交易员历史带单 Edit

/future/copytrade/public/order/v1/public/copy-trade/leader-order-history

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
type number false 查询类型,1:明细,2:汇总 12
symbol string false 交易对
leaderAccountId number true 交易员帐号
direction string false 方向(NEXT, PREV) NEXT, PREV
limit number false 翻页大小 10
id number false id

限流规则

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "symbolName": "string", // 市场名称
        "positionType": "string", // 仓位类型:CROSSED(全仓);ISOLATED(逐仓)
        "positionSide": "string", // 持仓方向:LONG;SHORT
        "openLeverage": 5, // 杠杆
        "id": 0, // id
        "orderId": 0, // 订单id
        "trackNo": 0, // 跟单trackNo
        "openTime": 0, // 开仓时间
        "closeTime": 0, // 平仓时间
        "entryPrice": 0, // 持仓均价
        "openPrice": 0, // 开仓均价
        "closePrice": 0, // 平仓均价
        "profitRate": 0, // 收益率
        "openMargin": 0, // 开仓初始保证金
        "realizedPnl": 0, // 已实现盈亏
        "fee": 0, // 手续费
        "openSize": 0, // 开仓仓位数量
        "closeSize": 0, // 平仓仓位数量
        "positionSize": 0, // 持仓数量
        "closeOrderSize": 0, // 平仓订单占用
        "availableCloseSize": 0, // 可平数量
        "triggerProfitPrice": 0, // 止盈价
        "triggerStopPrice": 0, // 止损价
        "triggerPriceType": "string", // 触发价格类型:LATEST_PRICE,MARK_PRICE
        "followOrderCount": 0 // 跟随订单数
        }
]
}

获取交易员收益额图表 Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-day-income

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountId number true 交易员帐号
days number false 天数

限流规则

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "amount": 0, // 收益额
        "time": 0 // 时间
        }
]
}

获取交易员收益率图表 Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-day-income-rate

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountId number true 交易员帐号
days number false 天数

限流规则

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
       "totalIncome":[{
        "amount": 0, // 额度
         "time": 0 // 时间
        }],
       "totalIncomeRate":[{
        "amount": 0, // 额度
        "time": 0 // 时间
        }],
        "incomeRate":[
         {"amount": 0, // 额度
         "time": 0 // 时间
         }]
}
}

获取交易员带单情况 Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-stats

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountId number true 交易员帐号
days number false 天数

限流规则

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result":{
        "recentRate": 0, // 收益率
        "totalEarnings": 0, // 总收益
        "maxRetraction": 0, // 最大回撤
        "followersEarnings": 0, // 跟单者收益
        "winRate": 0, // 胜率
        "totalTransactions": 0, // 交易次数
        "profitCount": 0, // 盈利次数
        "lossCount": 0, // 亏损次数
        "avgProfitAmount": 0, // 平均盈利
        "avgLossAmount": 0, // 平均亏损
        "pnlRate": 0, // 盈亏比
        "avgHoldTime": 0, // 平均持仓时间(秒)
        "weeklyTradeFrequency": 0, // 交易频次(每周)
        "followerTradeAmount": 0, // 带单规模(废弃)
        "followerMargin": 0, // 带单规模
        "tradeDays": 0, // 交易天数
        "lastTradeTime": 0, // 最近交易时间
}
}

获取交易员交易偏好 Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-symbol-prefer

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountId number true 交易员帐号
recentDays number false 天数

限流规则

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result":{
        "index": 0, // 
        "symbol": "string", // 交易对
        "count": 0, // 最大回撤
        "percentage": 0, // 占比
        "pnl": 0 // 交易盈亏
}
}

获取交易员详情 Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-detail-v2

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountId number true 交易员帐号

限流规则

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
        "nickName": "string", // 名称
        "avatar": "string", // 头像
        "intro": "string", // 简介
        "leadDays": 0, // 入驻时间
        "levelId": 0, // 当前等级id
        "level": 0, // 当前等级
        "levelName": "string", // 当前等级名称
        "label": ["string"], // 标签
        "followNumber": 0, // 累计跟随人数
        "currentFollowNumber": 0, // 当前跟随人数
        "maxFollowerSize": 0, // 最多跟随人数
        "profitRate": 0, // 交易员分润比例
        "platformProfitRate": 0, // 平台分润比例
        "totalRights": 0, // 总权益
        "displayEquity": Boolean, // 是否展示权益
        "displayPosition": Boolean // 是否展示持仓量
 }
}

获取跟单员信息 Edit

/future/copytrade/user/v1/copy-trade/leader-relation

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
leaderAccountId number true 交易员账号

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": {
        "leaderAccountId": 0, // 交易员accountId
        "symbols": "string", // 市场
        "followLoss": 0, // 跟单止损
        "followLossOperate": enum, // 跟单止损仓位处理 MARKET_SELL,LEADER_CLOSE,MANUAL_PROCESS
        "triggerProfitRate": 0, // 止盈比率
        "triggerStopRate": 0, // 止损比率
        "cancel": Boolean, // 是否已取消跟随
        "followDirection": 0, // 跟单方向:正向:FORWARD;反向:REVERSE
        "followType": 0, // 跟单类型:FUND(固定保证金);RATE(按倍率跟单);MARGIN_RATE(同比例跟单)
        "followVal": 0, // 跟单本金/跟单比例
        "autoFollowSymbol": Boolean // 自动跟单新增合约市场 true false
}
}

获取交易员的跟单人信息 Edit

/future/copytrade/public/user/v1/public/copy-trade/leader-follower-page

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
type number false 查询类型,1:明细,2:汇总
symbol string false 交易对
leaderAccountId number true 交易员帐号
direction string false 方向(NEXT, PREV) NEXT,PREV
limit number false 翻页大小 10
id number false id

限流规则

2/s/ip

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
        {
        "accountId": 0, // 跟单员帐号id
        "followerName": "string", // 跟随用户昵称
        "avatar": "string", // 头像
        "id": 0, // id
        "pageId": 0, // pageId
        "followMarginU": 0, // 累计跟随本金USDT
        "followProfitU": 0, // 累计跟随收益USDT
        "followProfitRate": 0, // 跟单收益率
        "days": 0 // 跟单天数
        }
]
}

查看杠杆倍数 Edit

/future/copytrade/order/v1/position/list

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string false 市场
welfareAccountVersion string false 版本号

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": [
          {
            "symbol": "string", //市场
            "positionType": "string",//仓位类型:CROSSED(全仓);ISOLATED(逐仓)
            "positionSide": "string",//持仓方向
            "contractType": "string",//合约类型:PERPETUAL(永续合约)、PREDICT(预测合约)
            "positionSize": 0,// 持仓数量
            "closeOrderSize": 0,//平仓挂单数量
            "availableCloseSize": 0,//可平仓数量
            "entryPrice": 0,//开仓均价
            "openOrderSize": 0,//开仓订单占用
            "isolatedMargin": 0,// 逐仓保证金
            "openOrderMarginFrozen": 0,//开仓订单保证金占用
            "realizedProfit": 0,//已实现盈亏
            "autoMargin": false,//是否自动追加保证金
            "leverage": 0, // 杠杆倍数
            "profitId": 0,//止盈止损id
            "triggerPriceType": 0,//触发价格类型 1、指数价格 2:标记价格(合理价格);3:最新价
            "triggerProfitPrice": 0,//止盈触发价
            "triggerStopPrice": 0,//止损触发价
            "welfareAccount": boolean //是否是体验金账户
           }
  ]
}

调整杠杆倍数 Edit

/future/copytrade/order/v1/position/adjust-leverage

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
symbol string true 市场
leverage number true 杠杆倍数
positionSide PositionSide false 仓位方向 LONG,SHORT,BOTH

限流规则

2/s/apikey

{
"returnCode": 0,
"msgInfo": "success",
"error": null,
"result": Boolean //true成功 false失败
}

REST API Edit

Official:

https://oapi.xt.com

Basic Information of the Interface Edit

Due to the reasons of high latency and poor stability, it is not recommend to access the XT API through a proxy.

GET request parameters are put in query Params, POST request parameters are put in request body.

The request header information is set to: Content-Type=application/x-www-form-urlencoded

In addition to the parameters required by the interface itself, signature, which is the signature parameter, needs to be passed in the query Params or request body. The interface that does not need to pass the signature parameter will be additionally explained.

Frequency Limiting Rules Edit

Get assets 3 times per second, other methods 10 times per second for each single user, 1000 times per minute for each single IP, exceeding the requested times, account will be locked for 10 minutes.

Token Instructions Edit

If the third-party platform is accessible to the user-authorized interface, you need to add an additional access-token field to the interface Header, how to get access-token please refer to here

Signature Statement 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 most important.

  1. Offline distribution of appkey and secretkey, for different calls, provide different appkey and secretkey.

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

  3. Add signature information for all data.

  4. Add recvwindow, the valid time is relatively simple and fixed to a certain value. For example, the data is valid within 10 minutes under the same api and appid. Here, it can be further optimized to the valid time of a single api is different.

The server determines the timestamp when it receives a request. Up to 60 seconds, and the default is 5 seconds. If it was sent 5000 milliseconds ago, the request will be considered invalid. This time window value can be customized 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, so your application’s local time delay to the XT server may be jitter.This is the purpose of setting recvWindow. If you are engaged in high-frequency trading and have high requirements for trading timeliness, you can flexibly set recvWindow to meet your requirements.

RecvWindow for more than 5 seconds is not recommended.

5、5. Add algorithms (signature method/algorithm). User’s signature calculation is a HSC-based protocol, where HmacSHA256 is used by default. See the specific supported protocols listed in the table below.

Name Mandatory Example Description
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow false 5000(millisecond)
validate-algorithms false HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,默认为:HmacSHA256
api-version false 1.0 Reserved, API version number
validate-signversion false 1.0 Reserved, signature version number

Obtain Signature Edit

Example for http://oapi.xt.com/api/v1/public/symbol/detail?symbol=btc_usdt

The following is an example of an order placed in a call interface using echo openssl and curl tools in a Linux bash environment. Appkey, secret for demonstration purposes only:

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Partial data of Header:

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

validate-timestamp: 1641446237201

validate-algorithms: HmacSHA256

Request data:

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

1、Data

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: Sorted by lexicographic order of key, concatenate all key=value. Example: userName=dfdfdf&password=ggg

body: Json: Operate as JSON string is not converted or sorted.

      x-www-form-urlencoded: Sorted by lexicographic order of key, concatenate all key=value. Example: userName=dfdfdf&password=ggg 

      form-data:Not supported.

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

Example of Path:

      /future/api/v1/public/symbol/detail

      The above concatenated value is recorded as path

Example 1: All parameters sent via query string

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        The above concatenate value is recorded as query

Example 2: All parameters send X-www-form-urlencoded request body string via the request body

Request body string of json

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        The above concatenate value is recorded as body

Request body string of www-form-urlencoded

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

        The above concatenate value is recorded as body

Example 3: Mix to use query string and request body (form and json format)

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

requestBody: {“quantity”:2,”price”:39000} The above concatenate value is recorded as query

    The final concatenate value of the entire data is # concatenated with path, query, and body and form #path, #query, and #body. The finalconcatenate value is recorded asY=#path#query#body。

    Note:

        query without data, body with data:Y=#path#body

        query with data, body without data:Y=#path#query

        query with data, body with data:Y=#path#query#body

2:Request header X=”validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-timestamp=1641446237201”

3:Obtain Signature

Finally, record the string that needs to be encrypted as sign=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, sign);

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

How to Apply for API Key Edit

The interface may require the user’s API Key,How to create API-KEY please contact the operator.

API 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
golang : https://github.com/xt-com/xt4-go-demo
c# : https://github.com/xt-com/xt4-c--demo

Return Format Edit

All interfaces’ returns are in JSON format.

{
    "returnCode": 200,
    "result": {
        "serverTime": 1636612706739
    },
    "msgInfo": "Success."
    "error": null,
}

Error 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 validate-appkey
AUTH_002 missing request header validate-timestamp
AUTH_003 missing request header validate-recvwindow
AUTH_004 bad request header validate-recvwindow
AUTH_005 missing request header validate-algorithms
AUTH_006 bad request header validate-algorithms
AUTH_007 missing request header 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

User Registration Edit

If you do not have an XT account, please register in advance, register address:http(s)://{URL}/{language}/accounts/register?client_id={clientId}
Parameter
1. URL
The domain name of the xt authorization page, the official environment is: www.xt.com
2. language
Authorization page language, the currently supported content is as follows:
en:English
ja:Japanese
hi:Hindi
id:Indonesian
ru:Russian
es:spanish
tr:turkish
zh-HK:traditional Chinese
zh-CN:Simplified Chinese
vi:vietnamese
th:Thai
3. clientId
The unique identification of the organization, please apply to XT.COM in advance
For Example:
http://www.xt.com/en/accounts/register?client_id=DDJ7BLK49YUCL97S
Users registered through this url will belong to the institution:DDJ7BLK49YUCL97S

Authorization Link Edit

When the third-party platform requires XT.COM users to authorize certain operations, please jump from the third-party platform page to http(s)://{URL}/{language}/accounts/oauth2?response_type=code&client_id={clientId}&redirect_uri={redirectUri}&scope={scope}
Parameter
1. URL
The domain name of the xt authorization page, the official environment is: www.xt.com
2. language
Authorization page language, the currently supported content is as follows:
en:English
ja:Japanese
hi:Hindi
id:Indonesian
ru:Russian
es:spanish
tr:turkish
zh-HK:traditional Chinese
zh-CN:Simplified Chinese
vi:vietnamese
th:Thai
3. clientId
The unique identification of the organization, please apply to XT.COM in advance
4. redirectUri
The redirected address after successful authorization
5. scope
Authorization scope, obtained from XT.COM together with clientId
For example:
http://www.xt.com/zh-CN/accounts/oauth2?response_type=code&client_id=DDJ7BLK49YUCL97S&redirect_uri=https%3A%2F%2Fwww.baidu.com&scope=userinfo

Apply Token Edit

/public/uaa/oauth2/token?client_id={client_id}&client_secret=${client_secret}&grant_type={grant_type}&code={code}

Parameters
Parameter Type mandatory Default Description Ranges
client_id string true Institutional identity Please apply to XT.COM
client_secret string true Institutional Secret Key Please apply to XT.COM
grant_type string true authorization type, fixed value authorization_code
code string true The user is redirected to the institution page after authorization, and the code field will be carried in the url
{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": {
        "user_id":"12345678",
        "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5MTU2MTA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.vkSTiFLcQuO0qJqdm21MfmoLKb38wwhsKPCJI3x1xmOxYouH5GtmcYglk0XRxPeOMVZ-6E6tM3HGn1yMQdqTgHOVeAbtLSBBIqyUh6y-8j_MF8GyBwcEaRK2hfWBNOHw06B-0jLO_mKEduUWZXYHjNiAN2jenbj7Ba6MX7rcENk",//Token used to access the authorization interface.The default validity period is one day
        "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5NDE1MzA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.UIeGGDiiybfEUEPFAteN3TtCxz5PyZxGDIULaNJjO3mCck7s28nRpXWSxONMGYMXG03XxJVUJs5WfdpNEmKUmmoQQuy-UOCuvV7zLdFmwUHd5e5tDMA7mgTCxbCeyxYE4L8Vr8StEEhxwWbDFxG_-2wdNEgEIvlgg9bI87Qcy9s",//The token used to refresh the access token.The default validity period is 180 days
        "expires_in": 15551999,//The number of milliseconds before the access_token expires
        "refresh_expires_in": 18143999,//The number of milliseconds before refresh_token expires
        "client_id": "35LF2FSLHX5IRQA4",//Institutional identity
        "scope": "userinfo"//authorized scope
    }
}

Refresh Token Edit

/public/uaa/oauth2/token?client_id={client_id}&client_secret=${client_secret}&grant_type={grant_type}&refresh_token={refresh_token}

Parameters
Parameter Type mandatory Default Description Ranges
client_id string true Institutional identity Please apply to XT.COM
client_secret string true Institutional Secret Key Please apply to XT.COM
grant_type string true authorization type, fixed value refresh_token
refresh_token string true The refresh_token field returned when applying for token
{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": {
        "user_id":"12345678",
        "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5MTU2MTA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.vkSTiFLcQuO0qJqdm21MfmoLKb38wwhsKPCJI3x1xmOxYouH5GtmcYglk0XRxPeOMVZ-6E6tM3HGn1yMQdqTgHOVeAbtLSBBIqyUh6y-8j_MF8GyBwcEaRK2hfWBNOHw06B-0jLO_mKEduUWZXYHjNiAN2jenbj7Ba6MX7rcENk",//token used to access the authorization interface
        "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5NDE1MzA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.UIeGGDiiybfEUEPFAteN3TtCxz5PyZxGDIULaNJjO3mCck7s28nRpXWSxONMGYMXG03XxJVUJs5WfdpNEmKUmmoQQuy-UOCuvV7zLdFmwUHd5e5tDMA7mgTCxbCeyxYE4L8Vr8StEEhxwWbDFxG_-2wdNEgEIvlgg9bI87Qcy9s",//The token used to refresh the access token
        "expires_in": 15551999,//The number of milliseconds before the access_token expires
        "refresh_expires_in": 18143999,//The number of milliseconds before refresh_token expires
        "client_id": "35LF2FSLHX5IRQA4",//Institutional identity
        "scope": "userinfo"//authorized scope
    }
}

Create apiKey Edit

/user/account/api-key

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": {
     "userId": 12345678,                                        //user id
     "accessKey": "99258227-f053-46a2-9b10-66c155eb705c",       //encryption key
     "secretKey": "4b1839e11bf7a1c6de5f078bd9f4b6e0850da3cf"    //encryption string
  }
}

Get single Edit

/spot/v4/order/{orderId}

Parameters
Parameter Type mandatory Default Description Ranges
orderId number true
{
  "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

/spot/v4/order

Parameters
Parameter Type mandatory Default Description Ranges
orderId number false
clientOrderId string false
{
  "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

/spot/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

Remark

Create a BUY order based on market price, quantity must be null, quoteQty required; Create a SELL order based on market price, quoteQty must be null, quantity required.

Limit Flow Rules

50/s/apikey

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

Cancell order Edit

/spot/v4/order/{orderId}

Parameters
Parameter Type mandatory Default Description Ranges
orderId number true
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "cancelId": "6216559590087220004"
  }
}

Get batch Edit

/spot/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

{
  "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

/spot/v4/batch-order

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

Note: The parameters should be placed in the request body in the form of json

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

Query the current pending order Edit

/spot/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

Limit Flow Rules

10/s/apikey

{
  "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

/spot/v4/open-order

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

Limit Flow Rules

10/s/apikey
Note: The parameters should be placed in the request body in the form of json

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

Query historical orders Edit

/spot/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 order state,
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

Limit Flow Rules

10/s/apikey

{
  "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

/spot/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 a single currency asset Edit

/spot/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

/spot/v4/balances

Parameters
Parameter Type mandatory Default Description Ranges
currencies string false List of currencies, comma separated,eg: usdt,btc

Limit Flow Rules

10/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "totalBtcAmount": 0,
    "assets": [    
      {        
        "currency": "string",
        "currencyId": 0,
        "frozenAmount": 0,
        "availableAmount": 0,
        "totalAmount": 0,
        "convertBtcAmount": 0
      }
    ]
  }
}

REST API Edit

正式:

https://oapi.xt.com

接口的基本信息 Edit

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

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

请求头信息请设置为:Content-Type=application/x-www-form-urlencoded

除了接口本身所需的参数外,还需要在query Params 或 request body中传递 signature, 即签名参数,不需要传递签名参数的接口会额外说明。

限频规则 Edit

获取资产每秒3次,其他方法单个用户每秒10次,单个IP每分钟1000次,超出锁定账户10分钟。

Token说明 Edit

第三方平台如果访问得到用户授权的接口,需要在接口header中额外添加access-token字段,字段value的获取参考这里

签名说明 Edit

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

1、线下分配appkey和secretkey,针对不同的调用,提供不同的appkey和secretkey

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

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

4、加入recvwindow(自定义请求有效时间),有效时间目前相对简单统一固定为某个值,比如:同api同appid下10分钟内数据都有郊,此处可以再进步优化到具体单个api有效时间都不相同。

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

不推荐使用5秒以上的recvWindow

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

字段名 是否必须 示例 说明
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow false 5000(毫秒)
validate-algorithms false HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,默认为:HmacSHA256
api-version false 1.0 保留,API版本号
validate-signversion false 1.0 保留,签名版本号

签名生成 Edit

http://oapi.xt.com/future/api/v1/public/symbol/detail?symbol=btc_usdt的示例

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

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Header部分数据:

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

validate-timestamp: 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9

validate-algorithms: HmacSHA256

请求数据:

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

1、数据部分

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的顺序进行再拼接,得到所有数据的拼接值。

路径Path示例:

      /future/api/v1/public/symbol/detail

      上述拼接值记作为path

示例 1: 所有参数通过 query string 发送

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        上述值拼接记作query

示例 2: 所有参数通过 request body 发送

x-www-form-urlencoded的request body string :

        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        上述值拼接记作body

json的request body string :

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

        上述值拼接记作body

示例 3: 混合使用 query string 与 request body(分为表单与json两种格式)

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

requestBody: {“quantity”:2,”price”:39000} 上述拼接值记作body

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

    注意:

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

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

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

2、请求头部分 X=”validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-timestamp=1641446237201”

3、生成签名

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

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

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

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

API Key申请步骤 Edit

接口需要用户的 API Key,如何创建API-KEY请联系运营人员。

API 代码库 Edit

Java connector

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

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

返回格式 Edit

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

{
    "returnCode": 200,
    "result": {
        "serverTime": 1636612706739
    },
    "msgInfo": "Success."
    "error": null,
}

错误代码 Edit

httpStatus 描述
200 请求成功,请进一步查看rc、mc部分
404 接口不存在
429 请求过于频繁,请按照限速要求,控制请求速率
500 服务异常
502 网关异常
503 服务不可用,请稍后重试
rc return Code
0 业务成功
1 业务失败
mc message code
SUCCESS 成功
FAILURE 失败
AUTH_001 缺少请求头 validate-appkey
AUTH_002 缺少请求头 validate-timestamp
AUTH_003 缺少请求头 validate-recvwindow
AUTH_004 错误的请求头 validate-recvwindow
AUTH_005 缺少请求头 validate-algorithms
AUTH_006 错误的请求头 validate-algorithms
AUTH_007 缺少请求头 validate-signature
AUTH_101 ApiKey不存在
AUTH_102 ApiKey未激活
AUTH_103 签名错误
AUTH_104 非绑定IP请求
AUTH_105 报文过时
AUTH_106 超出apikey权限

用户注册 Edit

如果您没有XT账号,请提前注册,注册地址:http(s)://{URL}/{language}/accounts/register?client_id={clientId}
参数说明
1. URL
xt授权页面域名,正式环境为: www.xt.com
2. language
授权页面语言,当前支持的内容如下:
en:英语
ja:日本语
hi:印地语
id:印尼语
ru:俄语
es:西班牙语
tr:土耳其语
zh-HK:繁体中文
zh-CN:简体中文
vi:越南语
th:泰语
3. clientId
机构唯一标识,请提前向XT.COM申请
例如:
http://www.xt.com/en/accounts/register?client_id=DDJ7BLK49YUCL97S
通过该url注册的用户将属于机构:DDJ7BLK49YUCL97S

跳转说明 Edit

当第三方平台需要XT.COM用户授权某些操作时,请从第三方平台页面跳转到http(s)://{URL}/{language}/accounts/oauth2?response_type=code&client_id={clientId}&redirect_uri={redirectUri}&scope={scope}
参数说明
1. URL
xt授权页面域名,正式环境为: www.xt.com
2. language
授权页面语言,当前支持的内容如下:
en:英语
ja:日本语
hi:印地语
id:印尼语
ru:俄语
es:西班牙语
tr:土耳其语
zh-HK:繁体中文
zh-CN:简体中文
vi:越南语
th:泰语
3. clientId
机构唯一标识,请提前向XT.COM申请
4. redirectUri
授权成功后的跳转到的地址
5. scope
授权作用域,和clientId一同向XT.COM获取
例如:
http://www.xt.com/zh-CN/accounts/oauth2?response_type=code&client_id=DDJ7BLK49YUCL97S&redirect_uri=https%3A%2F%2Fwww.baidu.com&scope=userinfo

申请Token Edit

/public/uaa/oauth2/token?client_id={client_id}&client_secret=${client_secret}&grant_type={grant_type}&code={code}

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
client_id string true 机构标识 请向XT.COM申请
client_secret string true 机构Secret Key 请向XT.COM申请
grant_type string true 授权类型,固定值 authorization_code
code string true 用户授权后重定向到机构页面,会在url中携带code字段
{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": {
        "user_id":"12345678",
        "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5MTU2MTA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.vkSTiFLcQuO0qJqdm21MfmoLKb38wwhsKPCJI3x1xmOxYouH5GtmcYglk0XRxPeOMVZ-6E6tM3HGn1yMQdqTgHOVeAbtLSBBIqyUh6y-8j_MF8GyBwcEaRK2hfWBNOHw06B-0jLO_mKEduUWZXYHjNiAN2jenbj7Ba6MX7rcENk",//用于访问授权接口的token,默认有效期1
        "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5NDE1MzA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.UIeGGDiiybfEUEPFAteN3TtCxz5PyZxGDIULaNJjO3mCck7s28nRpXWSxONMGYMXG03XxJVUJs5WfdpNEmKUmmoQQuy-UOCuvV7zLdFmwUHd5e5tDMA7mgTCxbCeyxYE4L8Vr8StEEhxwWbDFxG_-2wdNEgEIvlgg9bI87Qcy9s",//用于刷新access token的token,默认有效期180
        "expires_in": 15551999,//access_token距离过期的毫秒数
        "refresh_expires_in": 18143999,//refresh_token距离过期的毫秒数
        "client_id": "35LF2FSLHX5IRQA4",//机构标识
        "scope": "userinfo"//授权的scope
    }
}

刷新Token Edit

/public/uaa/oauth2/token?client_id={client_id}&client_secret=${client_secret}&grant_type={grant_type}&refresh_token={refresh_token}

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
client_id string true 机构标识
client_secret string true 机构Secret Key
grant_type string true 授权类型,固定值 refresh_token
refresh_token string true 申请token时返回的refresh_token字段
{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": {
        "user_id":"12345678",
        "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5MTU2MTA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.vkSTiFLcQuO0qJqdm21MfmoLKb38wwhsKPCJI3x1xmOxYouH5GtmcYglk0XRxPeOMVZ-6E6tM3HGn1yMQdqTgHOVeAbtLSBBIqyUh6y-8j_MF8GyBwcEaRK2hfWBNOHw06B-0jLO_mKEduUWZXYHjNiAN2jenbj7Ba6MX7rcENk",//用于访问授权接口的token
        "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5NDE1MzA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.UIeGGDiiybfEUEPFAteN3TtCxz5PyZxGDIULaNJjO3mCck7s28nRpXWSxONMGYMXG03XxJVUJs5WfdpNEmKUmmoQQuy-UOCuvV7zLdFmwUHd5e5tDMA7mgTCxbCeyxYE4L8Vr8StEEhxwWbDFxG_-2wdNEgEIvlgg9bI87Qcy9s",//用于刷新access token的token
        "expires_in": 15551999,//access_token距离过期的毫秒数
        "refresh_expires_in": 18143999,//refresh_token距离过期的毫秒数
        "client_id": "35LF2FSLHX5IRQA4",//机构标识
        "scope": "userinfo"//授权的scope
    }
}

创建apiKey Edit

/user/account/api-key

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": {
     "userId": 12345678,                                       //user id
     "accessKey": "99258227-f053-46a2-9b10-66c155eb705c",      //加密key
     "secretKey": "4b1839e11bf7a1c6de5f078bd9f4b6e0850da3cf"   //加密串
  }
}

单笔获取 Edit

/spot/v4/order/{orderId}

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderId number true 订单ID
{
  "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

/spot/v4/order

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderId number false 订单ID
clientOrderId string false 客户端订单号
{
  "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

/spot/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 金额。限价不填;市价按金额下单时必填

备注

按照市价创建BUY订单时,quantity为空,quoteQty必填;按照市价创建SELL订单时,quoteQty为空,quantity必填。

限流规则

50/s/apikey

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

单笔撤单 Edit

/spot/v4/order/{orderId}

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
orderId number true 订单ID
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "cancelId": "6216559590087220004"
  }
}

批量获取 Edit

/spot/v4/batch-order

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

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

{
  "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

/spot/v4/batch-order

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

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

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

查询当前挂单 Edit

/spot/v4/open-order

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

限流规则

10/s/apikey

{
  "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

/spot/v4/open-order

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

限流规则

10/s/apikey
注意:参数以json形式放在body中

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

历史订单查询 Edit

/spot/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 隐藏已取消

限流规则

10/s/apikey

{
  "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

/spot/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

/spot/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

/spot/v4/balances

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
currencies string false 币种列表,逗号分隔,eg: usdt,btc

限流规则

10/s/apikey

{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "totalBtcAmount": 0,
    "assets": [    //参数内容参考获取单个币种资产接口
      {        
        "currency": "string",
        "currencyId": 0,
        "frozenAmount": 0,
        "availableAmount": 0,
        "totalAmount": 0,
        "convertBtcAmount": 0
      }
    ]
  }
}

REST API Edit

production environment: https://api.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,therefore, the issue of data security needs to be considered. Such as whether the data has been tampered with, whether the data is outdated, whether the data can be submitted repeatedly, and the access frequency of the interface, and whether data has been tampered with is the most important issue.

  1. Please apply for appkey and secretkey in the user center first, each user’s appkey and secretkey are different.

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

  3. Add signature, its value is obtained by a certain rule of signature algorithm.

  4. Add recvwindow (defining the valid time of the request), the valid time is currently relatively simple and uniformly fixed at a certain value.

When a request is received by the server, the timestamp in the request is checked to ensure it falls between 2 to 60 seconds. Any request with a timestamp older than 5,000 milliseconds is considered invalid. The time window value can be set using the optional parameter: “recvWindow”. Additionally, if the server determines that the client’s timestamp is more than one second ahead of the server, the request will also be invalid. Online conditions are not always 100% reliable in terms of the timeliness of trades, resulting in varying levels of latency between your local program and the XT server. This is why we provide the “recvWindow” parameter - if you engage in high-frequency trading and require stricter transaction timeliness, you can adjust the “recvWindow” parameter to better meet your needs.

Recvwindow longer than 5 seconds is not recommended.

5、Added algorithm (signature method/algorithm), the user calculates the signature according to the protocol of the hash, and HmacSHA256 is recommended. For those protocols that are supported, see the table below.

HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256(recommended)、HmacSHA384、HmacSHA512
Name Mandatory Example Description
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow true 5000(millisecond)
validate-algorithms true HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,The default is:HmacSHA256
validate-signversion false 1.0 reserved, signed version number

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:

validate-algorithms: HmacSHA256

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

validate-recvwindow: 5000

validate-timestamp: 1641446237201

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:

    validate-algorithms=HmacSHA256&validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-recvwindow=5000&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 validate-signature as the key and singature as the value.

4.example

sample of original signature message:
  
    validate-algorithms=HmacSHA256&validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&validate-recvwindow=60000&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 'validate-algorithms: HmacSHA256' 
    --header 'validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' 
    --header 'validate-recvwindow: 60000' 
    --header 'validate-timestamp: 1666026215729' 
    --header '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

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
NO_OPERATION_PERMISSION current account does not have permission to operate
PERMISSION_LIMIT it’s not allowed to operate other user resources, such as: delete other user apiKey or sub-account
ACCOUNT_HAVE_API account has an apikey that cannot be deleted
ACCOUNT_NAME_EXIST account name already exists
SUB_ACCOUNT_LIMIT the number of sub-accounts exceeds the limit
MASTER_ACCOUNT_REMOVE_LIMIT deletion of master account is not allowed

Query account list(applicable to master and sub account) Edit

/v4/user/account

Parameters
Parameter Type mandatory Default Description Ranges
accountId string false account id
accountName string false account name
level integer false account level 1:master account; 2:sub account
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": [
    {
        "id": "1352123154436",                     //account id
        "accountName": "master1",                  //account name
        "userId": 1352123154435,                   //user id
        "level": 1,                                //account level: 1-master account; 2-sub account
        "createTime": "2022-04-19 02:02:42",       //account creation time
        "updateTime": "2022-04-19 02:02:42"        //account update time
    }, 
    {
        "id": "1626456841938669570",               //account id
        "accountName": "first1",                   //account name
        "userId": 1352123154436,                   //user id
        "level": 2,                                //account level: 1-master account; 2-sub account
        "createTime": "2023-02-17 05:41:43",       //account creation time
        "updateTime": "2023-02-17 05:41:43"        //account update time
    }
  ]
}

create a sub-account Edit

/v4/user/account

Parameters
Parameter Type mandatory Default Description Ranges
accountName string true sub-account name
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": true  //true: success; false/null: unsuccess
}

Query user's apiKey (applicable to master and sub account) Edit

/v4/user/account/api-key

Parameters
Parameter Type mandatory Default Description Ranges
userAccountId string false account id
keyName string false apiKey name
isLock integer false apiKey is locked or not 0:apiKey is not locked;1:apiKey is locked
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": [
    {
        "id": 1,                     
        "userAccountId": "1352123154435",                         //account id
        "userAccountLevel": 1,                                    //account level: 1-master account; 2-sub account
        "userId": 1352123154435,                                  //user id
        "keyName": "abc",                                         //apiKey name
        "bindIps": "",                                            //bind ip list
        "accessKey": "b5e58714-2382-4e2f-8762-81b5ec9d363a",      //encryption key
        "secretKey": "17aef63c0cba308089fae03e2b13a4794bd2d411",  //encryption string
        "isLock": 0,                                              //isLock: 0-apiKey is not locked;1-apiKey is locked
        "roleScopes": "QUERY_TRADE",                              //permissions code: QUERY_TRADE: trade is enabled; QUERY_NO_TRADE: trade is not enabled
        "tags": null,                                             //tags
        "createTime": "2023-02-17 05:41:43",                      //apiKey create time
        "updateTime": "2023-02-17 05:41:43"                       //apiKey update time
    }, 
    {
        "id": 2,                     
        "userAccountId": "13523123154435",                        //account id
        "userAccountLevel": 1,                                    //account level: 1-master account; 2-sub account
        "userId": 1352123154435,                                  //user id
        "keyName": "bcd",                                         //apiKey name
        "bindIps": "",                                            //bind ip list
        "accessKey": "b5e58714-2382-4e2f-8762-81b5ec9d363a",      //encryption key
        "secretKey": "17aef63c0cba308089fae03e2b13a4794bd2d411",  //encryption string
        "isLock": 0,                                              //isLock: 0-apiKey is not locked;1-apiKey is locked
        "roleScopes": "QUERY_TRADE",                              //permissions code: QUERY_TRADE: trade is enabled; QUERY_NO_TRADE: trade is not enabled
        "tags": null,                                             //tags
        "createTime": "2023-02-17 05:41:43",                      //apiKey create time
        "updateTime": "2023-02-17 05:41:43"                       //apiKey update time
    }
  ]
}

Create user account apiKey Edit

/v4/user/account/api-key

Parameters
Parameter Type mandatory Default Description Ranges
userAccountId string true account id
keyName string true apiKey name
bindIps string false bind ip list, multiple can be separated by commas
roleScopes string true permissions code QUERY:query is enabled; TRADE:spot and margin trade is enabled; WITHDRAW:withdraw is enabled; LEVER_LOAN:margin pledged is enabled; FUTURE:future trade is enabled; TRANSFER:transfer is enabled
tags string false tags
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": {
     "id": 4564,                                             //apiKey id
     "userAccountId": "1626456841938669570",                 //account id
     "userAccountLevel": 2,                                  //account level: 1-master account; 2-sub account
     "userId": 1352123154435,                                //user id
     "keyName": "123aaa",                                    //apiKey name
     "bindIps": null,                                        //bind ip list
     "accessKey": "99258227-f053-46a2-9b10-66c155eb705c",    //encryption key
     "secretKey": "4b1839e11bf7a1c6de5f078bd9f4b6e0850da3cf",//encryption string
     "isLock": 0,                                            //isLock: 0-apiKey is not locked;1-apiKey is locked
     "roleScopes": "QUERY_TRADE",                            //permissions code: QUERY_TRADE: trade is enabled; QUERY_NO_TRADE: trade is not enabled
     "tags": null,                                           //tags
     "createTime": "2023-02-20 07:39:56.768",                //apiKey create time
     "updateTime": "2023-02-20 07:39:56.768"                 //apiKey update time
  }
}

Modify user account apiKey Edit

/v4/user/account/api-key

Parameters
Parameter Type mandatory Default Description Ranges
id string true apiKey id
accessKey string true access key
keyName string false apiKey name
bindIps string false bind ip list, multiple can be separated by commas
roleScopes string true permissions code QUERY:query is enabled; TRADE:spot and margin trade is enabled; WITHDRAW:withdraw is enabled; LEVER_LOAN:margin pledged is enabled; FUTURE:future trade is enabled; TRANSFER:transfer is enabled
tags string false tags
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": {
     "id": 4564,                                             //apiKey id
     "userAccountId": "1626456841938669570",                 //account id
     "userAccountLevel": 2,                                  //account level: 1-master account; 2-sub account
     "userId": 1352123154435,                                //user id
     "keyName": "123aaa",                                    //apiKey name
     "bindIps": null,                                        //bind ip list
     "accessKey": "99258227-f053-46a2-9b10-66c155eb705c",    //encryption key
     "secretKey": "4b1839e11bf7a1c6de5f078bd9f4b6e0850da3cf",//encryption string
     "isLock": 0,                                            //isLock: 0-apiKey is not locked;1-apiKey is locked
     "roleScopes": "QUERY_TRADE",                            //permissions code: QUERY_TRADE: trade is enabled; QUERY_NO_TRADE: trade is not enabled
     "tags": null,                                           //tags
     "createTime": "2023-02-20 07:39:56.768",                //apiKey create time
     "updateTime": "2023-02-20 07:39:56.768"                 //apiKey update time
  }
}

Delete user account apiKey Edit

/v4/user/account/api-key/{apikeyId}

Parameters
Parameter Type mandatory Default Description Ranges
apikeyId string true apiKey id
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": true    //true: success; false/null: unsuccess
}

Get All Users of Affiliate Edit

/v4/referal/invite/users

Parameters
Parameter Type mandatory Default Description Ranges
startTime number false start time
endTime number false end time
fromId number false Starting ID
direction string false NEXT query direction PREV, NEXT
limit int false 10 Limit number, max 100 1<=limit<=100
{
  "ma": [],
  "mc": "SUCCESS",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
        {
        "id": 123,
        "regTime": 1721962593000, //Registration time
        "role": "PARTNER",        //User roles: CHANNEL/PARTNER/DIRECTOR
        "userId": 123456789       //User ID
        }
    ]
  }
}

Get Deposit & Trading Data of Users Edit

/v4/referal/invite/user/data

Parameters
Parameter Type mandatory Default Description Ranges
startTime number false start time
endTime number false end time
uid number true Queried user ID
{
  "ma": [],
  "mc": "SUCCESS",
  "rc": 0,
  "result": {
    "userId": 123456789,                //User ID
    "role": "PARTNER",                  //User role
    "deposit": true,                    //Deposit status
    "depositDetails": [
        {
            "amount": 100,              //Deposit amount
            "amountU": 100,             //Deposit amount (converted to USDT)
            "currency": "USDT",         //Deposit currency
            "timestamp": 1721962593000  //Deposit time
        }
    ],
    "trade": true,                      //Trade status
    "tradeAmount": 1000.1234            //Trading volume (converted to USDT)
  }
}

REST API Edit

生产环境: https://api.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
字段名 是否必须 示例 说明
validate-appkey true dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
validate-timestamp true 1641446237201
validate-signature true 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d
validate-recvwindow true 5000(毫秒)
validate-algorithms true HmacSHA256 HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512,默认为:HmacSHA256
validate-signversion false 1.0 保留,签名版本号

签名生成 Edit

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

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

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Header部分数据:

validate-algorithms: HmacSHA256

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

validate-recvwindow: 5000

validate-timestamp: 1641446237201

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。如:

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

3、生成签名

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

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

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

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

4、样例

签名原始报文样例:

    validate-algorithms=HmacSHA256&validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&validate-recvwindow=60000&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 'validate-algorithms: HmacSHA256' 
    --header 'validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' 
    --header 'validate-recvwindow: 60000' 
    --header 'validate-timestamp: 1666026215729' 
    --header 'validate-signature: 4cb36e820f50d2e353e5e0a182dc4a955b1c26efcb4b513d81eec31dd36072ba' 
    --data-raw '{"symbol":"XT_USDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":3,"quantity":2}'

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

响应代码 Edit

httpStatus 描述
200 请求成功,请进一步查看rc、mc部分
404 接口不存在
429 请求过于频繁,请按照限速要求,控制请求速率
500 服务异常
502 网关异常
503 服务不可用,请稍后重试
rc return Code
0 业务成功
1 业务失败
mc message code
SUCCESS 成功
FAILURE 失败
NO_OPERATION_PERMISSION 当前账户无操作权限
PERMISSION_LIMIT 不允许操作不属于自己的资源 如:删除别的用户apiKey 或者子账户
ACCOUNT_HAVE_API 该账户存在apikey无法删除
ACCOUNT_NAME_EXIST 账户名已存在
SUB_ACCOUNT_LIMIT 子账户创建超过限制
MASTER_ACCOUNT_REMOVE_LIMIT 不允许删除主账户

查询账户列表(适用于主账户和子账户) Edit

/v4/user/account

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountId string false 账户id
accountName string false 账户名
level integer false 账户等级 1:主账户;2:子账户
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": [
    {
        "id": "1352123154436",                     //账户id
        "accountName": "master1",                  //账户名
        "userId": 1352123154435,                   //用户id
        "level": 1,                                //账户等级:1-主账户;2-子账户
        "createTime": "2022-04-19 02:02:42",       //账户创建时间
        "updateTime": "2022-04-19 02:02:42"        //账户更新时间
    }, 
    {
        "id": "1626456841938669570",               //账户id
        "accountName": "first1",                   //账户名
        "userId": 1352123154436,                   //用户id
        "level": 2,                                //账户等级:1-主账户;2-子账户
        "createTime": "2023-02-17 05:41:43",       //账户创建时间
        "updateTime": "2023-02-17 05:41:43"        //账户更新时间
    }
  ]
}

创建子账户 Edit

/v4/user/account

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
accountName string true 子账户名
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": true   //true 成功;falsenull未成功
}

查询用户apiKey(适用于主账户和子账户) Edit

/v4/user/account/api-key

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
userAccountId string false 账户id
keyName string false apiKey名称
isLock integer false 是否锁定 0:否;1:是
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": [
    {
        "id": 1,                     
        "userAccountId": "1352123154435",                         //账户id
        "userAccountLevel": 1,                                    //账户等级:1-主账户;2-子账户
        "userId": 1352123154435,                                  //用户id
        "keyName": "abc",                                         //apiKey名称
        "bindIps": "",                                            //绑定ip列表
        "accessKey": "b5e58714-2382-4e2f-8762-81b5ec9d363a",      //加密key
        "secretKey": "17aef63c0cba308089fae03e2b13a4794bd2d411",  //加密串
        "isLock": 0,                                              //是否锁定:0-否;1:是
        "roleScopes": "QUERY_TRADE",                              //权限code: QUERY_TRADE: 开启交易权限; QUERY_NO_TRADE: 不开启交易权限
        "tags": null,                                             //标签
        "createTime": "2023-02-17 05:41:43",                      //apiKey创建时间
        "updateTime": "2023-02-17 05:41:43"                       //apiKey更新时间
    }, 
    {
        "id": 2,                     
        "userAccountId": "13523123154435",                        //账户id
        "userAccountLevel": 1,                                    //账户等级:1-主账户;2-子账户
        "userId": 1352123154435,                                  //用户id
        "keyName": "bcd",                                         //apiKey名称
        "bindIps": "",                                            //绑定ip列表
        "accessKey": "b5e58714-2382-4e2f-8762-81b5ec9d363a",      //加密key
        "secretKey": "17aef63c0cba308089fae03e2b13a4794bd2d411",  //加密串
        "isLock": 0,                                              //是否锁定:0-否;1:是
        "roleScopes": "QUERY_TRADE",                              //权限code: QUERY_TRADE: 开启交易权限; QUERY_NO_TRADE: 不开启交易权限
        "tags": null,                                             //标签
        "createTime": "2023-02-17 05:41:43",                      //apiKey创建时间
        "updateTime": "2023-02-17 05:41:43"                       //apiKey更新时间
    }
  ]
}

创建用户账户apiKey Edit

/v4/user/account/api-key

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
userAccountId string true 账户id
keyName string true apiKey名称
bindIps string false 绑定ip,多个用逗号分隔
roleScopes string true 权限code QUERY 查询权限开启,TRADE 现货及杠杆交易开启, WITHDRAW 提币权限开启, LEVER_LOAN 杠杆质押借币权限开启, FUTURE 合约交易开启, TRANSFER 划转权限开启
tags string false 标签
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": {
     "id": 4564,                                             //apiKey id
     "userAccountId": "1626456841938669570",                 //账户id
     "userAccountLevel": 2,                                  //账户等级:1-主账户;2-子账户
     "userId": 1352123154435,                                //用户id
     "keyName": "123aaa",                                    //apiKey名称
     "bindIps": null,                                        //绑定ip列表
     "accessKey": "99258227-f053-46a2-9b10-66c155eb705c",    //加密key
     "secretKey": "4b1839e11bf7a1c6de5f078bd9f4b6e0850da3cf",//加密串
     "isLock": 0,                                            //是否锁定:0-否;1:是
     "roleScopes": "QUERY_TRADE",                            //权限code: QUERY_TRADE: 开启交易权限; QUERY_NO_TRADE: 不开启交易权限
     "tags": null,                                           //标签
     "createTime": "2023-02-20 07:39:56.768",                //apiKey创建时间
     "updateTime": "2023-02-20 07:39:56.768"                 //apiKey更新时间
  }
}

修改用户账户apiKey Edit

/v4/user/account/api-key

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
id string true apiKey id
accessKey string true access key
keyName string false apiKey名称
bindIps string false 绑定ip 多个ip英文逗号分割
roleScopes string true 权限code QUERY 查询权限开启,TRADE 现货及杠杆交易开启, WITHDRAW 提币权限开启, LEVER_LOAN 杠杆质押借币权限开启, FUTURE 合约交易开启, TRANSFER 划转权限开启
tags string false 标签
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": {
     "id": 4564,                                             //apiKey id
     "userAccountId": "1626456841938669570",                 //账户id
     "userAccountLevel": 2,                                  //账户等级:1-主账户;2-子账户
     "userId": 1352123154435,                                //用户id
     "keyName": "123aaa",                                    //apiKey名称
     "bindIps": null,                                        //绑定ip列表
     "accessKey": "99258227-f053-46a2-9b10-66c155eb705c",    //加密key
     "secretKey": "4b1839e11bf7a1c6de5f078bd9f4b6e0850da3cf",//加密串
     "isLock": 0,                                            //是否锁定:0-否;1:是
     "roleScopes": "QUERY_TRADE",                            //权限code: QUERY_TRADE: 开启交易权限; QUERY_NO_TRADE: 不开启交易权限
     "tags": null,                                           //标签
     "createTime": "2023-02-20 07:39:56.768",                //apiKey创建时间
     "updateTime": "2023-02-20 07:39:56.768"                 //apiKey更新时间
  }
}

删除用户账户apiKey Edit

/v4/user/account/api-key/{apikeyId}

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
apikeyId string true apiKey id
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": true    //true 成功;falsenull未成功
}

查询所有下级代理及子代理(含直客) Edit

/v4/referal/invite/users

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
startTime number false 开始时间
endTime number false 结束时间
fromId number false 分页查询开始id
direction string false NEXT 上一页/下一页 PREV, NEXT
limit int false 10 每页数量,最大100 1<=limit<=100
{
  "ma": [],
  "mc": "SUCCESS",
  "rc": 0,
  "result": {
    "hasNext": true,
    "hasPrev": true,
    "items": [
        {
        "id": 123,
        "regTime": 1721962593000, //注册时间
        "role": "PARTNER",        //用户角色: CHANNEL/PARTNER/DIRECTOR
        "userId": 123456789       //用户id
        }
    ]
  }
}

查询该用户充值及交易数据 Edit

/v4/referal/invite/user/data

Parameters
参数 数据类型 是否必须 默认值 描述 取值范围
startTime number false 开始时间
endTime number false 结束时间
uid number true 查询的用户id
{
  "ma": [],
  "mc": "SUCCESS",
  "rc": 0,
  "result": {
    "userId": 123456789,                //用户id
    "role": "PARTNER",                  //用户角色
    "deposit": true,                    //是否充值
    "depositDetails": [
        {
            "amount": 100,              //充值数量
            "amountU": 100,             //充值兑U数量
            "currency": "USDT",         //充值币种
            "timestamp": 1721962593000  //充值时间
        }
    ],
    "trade": true,                      //是否交易
    "tradeAmount": 1000.1234            //交易兑U数量
  }
}