REST API Edit
production environment: https://sapi.cryptoland.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 CRYPTOLAND 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.
-
Please apply for appkey and secretkey in the user center first, each user’s appkey and secretkey are different.
-
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.
-
Add signature, its value is obtained by a certain rule of signature algorithm.
-
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 CRYPTOLAND 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.cryptoland.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":"ETH_USDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":3,"quantity":2}
sample request message:
curl --location --request POST 'https://sapi.cryptoland.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":"ETH_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, Apply for the uri of the api is 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/CryptoLandEX/java-demo
Sample request information for each interface：
https://github.com/CryptoLandEX/java-demo/blob/main/request.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_F0101 | Trigger Price Filter - Min |
| ORDER_F0102 | Trigger Price Filter - Max |
| ORDER_F0103 | Trigger Price Filter - Step Value |
| ORDER_F0201 | Trigger Quantity Filter - Min |
| ORDER_F0202 | Trigger Quantity Filter - Max |
| ORDER_F0203 | Trigger Quantity Filter - Step Value |
| ORDER_F0301 | Trigger QUOTE_QTY Filter - Min Value |
| ORDER_F0401 | Trigger PROTECTION_ONLINE Filter |
| ORDER_F0501 | Trigger PROTECTION_LIMIT Filter - Buy Max Deviation |
| ORDER_F0502 | Trigger PROTECTION_LIMIT Filter - Sell Max Deviation |
| 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 |
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 | ancel 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 |
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
Get server time Edit
/v4/public/time
public String getServerInfo(){
}
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": {
"serverTime": 1662435658062
}
}
Get symbol information Edit
/v4/public/symbol
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| symbol | string | false | trading pair eg:btc_usdt | ||
| symbols | array | false | Collection of trading pairs. Priority is higher than symbol. eg: btc_usdt,eth_usdt | ||
| version | string | false | Version number, when the request version number is consistent with the response content version, the list will not be returned, reducing IO eg: 2e14d2cd5czcb2c2af2c1db6 |
Limit Flow Rules
1.single symbol：100/s/ip
2.multiple symbols：10/s/ip
FILTER
Filter, defines a series of trading rules. There are different filters for different fields or entities. Here we mainly introduce the filter for the entity symbol. For symbols, there are two kinds of filters, one is a global filter, and the other is a filter customized for a certain trading pair.
PRICE FILTER
The price filter is used to check the validity of the price parameter in the order. Contains the following three parts:
1.min Defines the minimum allowable price in the order
2.max Defines the maximum price allowed in the order
3.tickSize Defines the step interval of price in the order, that is, price must be equal to minPrice+(integer multiple of tickSize)
Each of the above items can be null, when it is null, it means that this item is no longer restricted
The logical pseudocode is as follows:
- price >= min
- price <= max
- (price-minPrice) % tickSize == 0
QUANTITY FILTER
The logic is similar to PRICE FILTER ,but for the order quantity.
It contains three parts:
1.min minimum allowed
2.max maximum allowed
3.tickSize Step interval, that is, quantity must be equal to minQuantity+(integer multiple of tickSize)
Each of the above items can be null, when it is null, it means that this item is no longer restricted
The logical pseudocode is as follows:
- quantity>= min
- quantity<= max
- (quantity-minQuantity)% tickSize == 0
QUOTE_QTY FILTER
Limit the amount of the order
It internally defines the minimum allowable value-min
When min is null, the order is not limited
Otherwise the restriction rules are as follows:
1.For orders of the LIMIT type,must meet the following conditions: price*quantity>=min
2.For orders of the MARKET type and BUY type,must meet the following conditions: quoteQty>=min,(quoteQty,The required amount when placing an order of MARKET type by amount)
PROTECTION_LIMIT FILTER
There are price protection restrictions for orders whose order type (orderType) is LIMIT, including the following two parts：
1.buyMaxDeviation The maximum deviation of the buy order, which limits the difference between the buy order price and the latest transaction price
2.sellMaxDeviation The maximum deviation of the sell order, which limits the difference between the sell order price and the latest transaction price
If there is no latest transaction price, there will be no restrictions, or if the above parameters are null, the corresponding direction type orders will not be restricted.
In order to pass the limit price protection, the order price must meet the following conditions (latestPrice is the latest transaction price)
buy order: price >= latestPrice-latestPrice*buyMaxDeviation
sell order: price <= latestPrice+latestPrice*sellMaxDeviation
PROTECTION_MARKET FILTER
There is a price limit protection mechanism for orders of the order type MARKET, which internally specifies the maximum deviation rate(maxDeviation).
For market type orders, the market price must meet the following conditions for the order to pass(sellBestPrice sell one price，buyBestPrice buy one price，latestPrice The latest transaction price, these data are obtained through historical transaction data)
buy order: latestPrice + latestPrice* maxDeviation >= sellBestPrice
sell order: latestPrice - latestPrice* maxDeviation <= buyBestPrice
For the above situation maxDeviation,latestPrice,sellBestPrice,buyBestPrice
All may be empty or there is no latest transaction price, buy one price, sell one price, there is no limit
PROTECTION_ONLINE FILTER
Limit the price of orders of the MARKET type within the specified time range after the opening
The maximum price multiple is defined inside this filter(maxPriceMultiple)，duration(durationSeconds)。
Limitation logic: when it is within the durationSeconds time range after the opening of the symbol, Orders with an order type of LIMIT must meet the following conditions to pass
price<=openPrice*maxPriceMultiple,（openPrice is the opening price）.
There are no restrictions on other types of orders or orders outside the opening time frame.
For maxPriceMultiple, durationSeconds can be null, when they are null, no opening protection limit is applied.
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": {
"time": 1662444177871,
"version": "7cd2cfab0dc979339f1de904bd90c9cb",
"symbols": [
{
"id": 614, //ID
"symbol": "btc_usdt",
"state": "ONLINE", //symbol state [ONLINE;OFFLINE,DELISTED]
"tradingEnabled": true,
"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,
"orderTypes": [ //Order Type [LIMIT;MARKET]
"LIMIT",
"MARKET"
],
"timeInForces": [ //Effective ways [GTC=It remains valid until the transaction is concluded; IOC=Cancel the part that cannot be transacted immediately (taking orders); FOK=Cancellation if all transactions cannot be completed immediately; GTX=Revoke if unable to become a pending party]
"GTC",
"FOK",
"IOC",
"GTX"
],
"displayWeight": 1, //Show the weight, the greater the weight, the more forward
"displayLevel": "FULL", //Presentation level, [FULL=Full display,SEARCH=Search display,DIRECT=Direct display,NONE=Don't show]
"plates": [], // eg:22,23,24
"filters": [
{
"filter": "PROTECTION_LIMIT",
"buyMaxDeviation": "0.8"
"sellMaxDeviation": "0.8"
},
{
"filter": "PROTECTION_MARKET",
"maxDeviation": "0.1"
},
{
"filter": "PROTECTION_ONLINE",
"durationSeconds": "300",
"maxPriceMultiple": "5"
},
{
"filter": "PRICE",
"min": null,
"max": null,
"tickSize": null
},
{
"filter": "QUANTITY",
"min": null,
"max": null,
"tickSize": null
},
{
"filter": "QUOTE_QTY",
"min": null
},
]
}
]
}
}
Get depth data Edit
/v4/public/depth
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| symbol | string | true | trading pair eg:btc_usdt | ||
| limit | number | false | 50 | 1~500 |
Limit Flow Rules
200/s/ip
public String depth(){
}
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": {
"timestamp": 1662445330524,
"lastUpdateId": 137333589606963580, //Last updated record
"bids": [ //buy order([?][0]=price;[?][1]=pending order volume)
[
"200.0000", //price
"0.996000" //pending order volume
],
[
"100.0000",
"0.001000"
],
[
"20.0000",
"10.000000"
]
],
"asks": [] //sell order([?][0]=price;[?][1]=pending order volume)
}
}
Get K-line data Edit
/v4/public/kline
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| symbol | string | true | trading pair eg:btc_usdt | ||
| interval | string | true | K line type, eg:1m | [1m;3m;5m;15m;30m;1h;2h;4h;6h;8h;12h;1d;3d;1w;1M] | |
| startTime | number | false | start timestamp | ||
| endTime | number | false | end timestamp | ||
| limit | number | false | 100 | 1~1000 |
Limit Flow Rules
100/s/ip
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [
{
"t": 1662601014832, //open time
"o": "30000", //open price
"c": "32000", //close price
"h": "35000", //highest price
"l": "25000", //lowest price
"q": "512", //transaction quantity
"v": "15360000" //transaction volume
}
]
}
Query the list of recent transactions Edit
/v4/public/trade/recent
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| symbol | string | true | trading pair | ||
| limit | number | false | 200 | 1，1000 |
Limit Flow Rules
100/s/ip
public String tradeRecent(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [
{
"i": 0, //ID
"t": 0, //transaction time
"p": "string", //transaction price
"q": "string", //transaction quantity
"v": "string", //transaction volume
"b": true //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
100/s/ip
public String tradeHistory(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [
{
"i": 0, //ID
"t": 0, //transaction time
"p": "string", //transaction price
"q": "string", //transaction quantity
"v": "string", //transaction volume
"b": true //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：100/s/ip
2.multiple symbols：10/s/ip
public String price(){
}
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": [
{
"s": "btc_usdt", //symbol
"t": 1662444879425, //update time
"cv": "0.00", //change value
"cr": "0.0000", //change rate
"o": "200.00", //open
"l": "200.00", //low
"h": "200.00", //high
"c": "200.00", //close
"q": "0.002", //quantity
"v": "0.40", //volume
"ap": null, //asks price(sell one price)
"aq": null, //asks qty(sell one quantity)
"bp": null, //bids price(buy one price)
"bq": null //bids qty(buy one quantity)
}
]
}
Get latest prices ticker Edit
/v4/public/ticker/price
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| symbol | string | false | trading pair eg:btc_usdt | ||
| symbols | array | false | Collection of trading pairs. Priority is higher than symbol. eg: btc_usdt,eth_usdt | ||
| tags | string | false | Set of tags, separated by commas, currently only supports spot |
Limit Flow Rules
1.single symbol：100/s/ip
2.multiple symbols：10/s/ip
public String price(){
}
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": [
{
"s": "btc_usdt", //symbol
"t": 1661856036925 //time
"p": "9000.0000", //price
}
]
}
Get the best pending order ticker Edit
/v4/public/ticker/book
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| symbol | string | false | trading pair eg:btc_usdt | ||
| symbols | array | false | Collection of trading pairs. Priority is higher than symbol. eg: btc_usdt,eth_usdt | ||
| tags | string | false | Set of tags, separated by commas, currently only supports spot |
Limit Flow Rules
1.single symbol：100/s/ip
2.multiple symbols：10/s/ip
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": [
{
"s": "btc_usdt", //symbol
"t": 1661856036925, //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：100/s/ip
2.multiple symbols：10/s/ip
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": [
{
"s": "btc_usdt", //symbol
"t": 1661856036925, //time
"cv": "0.0000", //price change value
"cr": "0.00", //price change rate
"o": "9000.0000", //open price
"l": "9000.0000", //lowest price
"h": "9000.0000", //highest price
"c": "9000.0000", //close price
"q": "0.0136", //transaction quantity
"v": "122.9940" //transaction volume
}
]
}
Get single Edit
/v4/order/{orderId}
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| orderId | number | true |
public String orderGet(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"symbol": "BTC_USDT",
"orderId": "6216559590087220004",
"clientOrderId": "16559590087220001",
"baseCurrency": "string",
"quoteCurrency": "string",
"side": "BUY", //order side:BUY,SELL
"type": "LIMIT", //order type LIMIT,MARKET
"timeInForce": "GTC", //effective way:GTC,IOC,FOK,GTX
"price": "40000",
"origQty": "2", //original quantity
"origQuoteQty": "48000", //original amount
"executedQty": "1.2", //executed quantity
"leavingQty": "string", //The quantity to be executed (if the order is cancelled or the order is rejected, the value is 0)
"tradeBase": "2", //transaction quantity
"tradeQuote": "48000", //transaction amount
"avgPrice": "42350", //average transaction price
"fee": "string", //handling fee
"feeCurrency": "string",
"state": "NEW", //order stat NEW,PARTIALLY_FILLED,FILLED,CANCELED,REJECTED,EXPIRED
"time": 1655958915583, //order time
"updatedTime": 1655958915583
}
}
Query single Edit
/v4/order
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| orderId | number | false | |||
| clientOrderId | string | false |
public String orderGet(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"symbol": "BTC_USDT",
"orderId": "6216559590087220004",
"clientOrderId": "16559590087220001",
"baseCurrency": "string",
"quoteCurrency": "string",
"side": "BUY", //order side:BUY,SELL
"type": "LIMIT", //order type LIMIT,MARKET
"timeInForce": "GTC", //effective way:GTC,IOC,FOK,GTX
"price": "40000",
"origQty": "2", //original quantity
"origQuoteQty": "48000", //original amount
"executedQty": "1.2", //executed quantity
"leavingQty": "string", //The quantity to be executed (if the order is cancelled or the order is rejected, the value is 0)
"tradeBase": "2", //transaction quantity
"tradeQuote": "48000", //transaction amount
"avgPrice": "42350", //average transaction price
"fee": "string", //handling fee
"feeCurrency": "string",
"state": "NEW", //order stat NEW,PARTIALLY_FILLED,FILLED,CANCELED,REJECTED,EXPIRED
"time": 1655958915583, //order time
"updatedTime": 1655958915583
}
}
Submit order Edit
/v4/order
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| symbol | string | true | |||
| clientOrderId | string | false | Pattern: ^[a-zA-Z0-9_]{4,32}$ | ||
| side | string | true | BUY,SELL | ||
| type | string | true | order type:LIMIT,MARKET | ||
| timeInForce | string | true | effective way:GTC, FOK, IOC, GTX | ||
| bizType | string | true | SPOT, LEVER | ||
| price | number | false | price. Required if it is the LIMIT price; blank if it is the MARKET price | ||
| quantity | number | false | quantity. Required if it is the LIMIT price or the order is placed at the market price by quantity | ||
| quoteQty | number | false | amount. Required if it is the LIMIT price or the order is the market price when placing an order by amount |
Limit Flow Rules
50/s/apikey
public String orderPost(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"orderId": "6216559590087220004"
}
}
Cancell order Edit
/v4/order/{orderId}
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| orderId | number | true |
public String orderDel(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"cancelId": "6216559590087220004"
}
}
Get batch Edit
/v4/batch-order
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| orderIds | string | true | order Ids eg: 6216559590087220004, 6216559590087220004 |
reponse field information, refer to the Get single interface
public String batchOrderGet(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [
{
"symbol": "BTC_USDT",
"orderId": "6216559590087220004",
"clientOrderId": "16559590087220001",
"baseCurrency": "string",
"quoteCurrency": "string",
"side": "BUY",
"type": "LIMIT",
"timeInForce": "GTC",
"price": "40000",
"origQty": "2",
"origQuoteQty": "48000",
"executedQty": "1.2",
"leavingQty": "string",
"tradeBase": "2",
"tradeQuote": "48000",
"avgPrice": "42350",
"fee": "string",
"feeCurrency": "string",
"state": "NEW",
"time": 1655958915583,
"updatedTime": 1655958915583
}
]
}
Cancell batch order Edit
/v4/batch-order
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| clientBatchId | string | false | client batch id | ||
| orderIds | array | true | 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 |
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [ //For field information, refer to the Get single interface
{
"symbol": "BTC_USDT",
"orderId": "6216559590087220004",
"clientOrderId": "16559590087220001",
"baseCurrency": "string",
"quoteCurrency": "string",
"side": "BUY",
"type": "LIMIT",
"timeInForce": "GTC",
"price": "40000",
"origQty": "2",
"origQuoteQty": "48000",
"executedQty": "1.2",
"leavingQty": "string",
"tradeBase": "2",
"tradeQuote": "48000",
"avgPrice": "42350",
"fee": "string",
"feeCurrency": "string",
"state": "NEW",
"time": 1655958915583,
"updatedTime": 1655958915583
}
]
}
Cancel the current pending order Edit
/v4/open-order
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| symbol | string | false | Trading pair, if not filled in, represents all | ||
| bizType | string | false | SPOT, LEVER | ||
| side | string | false | BUY,SELL |
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 |
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"hasPrev": true,
"hasNext": true,
"items": [ //For field information, refer to the Get single interface
{
"symbol": "BTC_USDT",
"orderId": "6216559590087220004",
"clientOrderId": "16559590087220001",
"baseCurrency": "string",
"quoteCurrency": "string",
"side": "BUY",
"type": "LIMIT",
"timeInForce": "GTC",
"price": "40000",
"origQty": "2",
"origQuoteQty": "48000",
"executedQty": "1.2",
"leavingQty": "string",
"tradeBase": "2",
"tradeQuote": "48000",
"avgPrice": "42350",
"fee": "string",
"feeCurrency": "string",
"state": "NEW",
"time": 1655958915583,
"updatedTime": 1655958915583
}
]
}
}
Query trade Edit
/v4/trade
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| symbol | string | false | Trading pair, if not filled in, represents all | ||
| bizType | string | false | SPOT, LEVER | ||
| orderSide | string | false | BUY,SELL | ||
| orderType | string | false | LIMIT, MARKET | ||
| orderId | number | false | |||
| fromId | number | false | start id | ||
| direction | string | false | query direction:PREV, NEXT | ||
| limit | number | false | 20 | Limit number, max 100 | |
| startTime | number | false | start time eg:1657682804112 | ||
| endTime | number | false |
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"hasPrev": true,
"hasNext": true,
"items": [
{
"symbol": "BTC_USDT",
"tradeId": "6316559590087222001",
"orderId": "6216559590087220004",
"orderSide": "BUY",
"orderType": "LIMIT",
"bizType": "SPOT",
"time": 1655958915583,
"price": "40000",
"quantity": "1.2",
"quoteQty": "48000", //amount
"baseCurrency": "BTC",
"quoteCurrency": "USDT",
"fee": "0.5",
"feeCurrency": "USDT",
"takerMaker": "taker" //takerMaker
}
]
}
}
Get currency information Edit
/v4/public/currencies
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [
{
"id": 11, //currency id
"currency": "usdt", //currency name
"fullName": "usdt", //currency full name
"logo": null, //currency logo
"cmcLink": null, //cmc link
"weight": 100,
"maxPrecision": 6,
"depositStatus": 1, //Recharge status(0 close 1 open)
"withdrawStatus": 1, //Withdrawal status(0 close 1 open)
"convertEnabled": 1, //Small asset exchange switch[0=close;1=open]
"transferEnabled": 1 //swipe switch[0=close;1=open]
}
]
}
Get a single currency asset Edit
/v4/balance
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| currency | string | true | eg:usdt |
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"currency": "usdt",
"currencyId": 0,
"frozenAmount": 0,
"availableAmount": 0,
"totalAmount": 0,
"convertBtcAmount": 0 //Converted BTC amount
}
}
Get a list of currency assets Edit
/v4/balances
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| currencies | string | false | List of currencies, comma separated,eg: usdt,btc |
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"totalBtcAmount": 0,
"assets": [
{
"currency": "string",
"currencyId": 0,
"frozenAmount": 0,
"availableAmount": 0,
"totalAmount": 0,
"convertBtcAmount": 0
}
]
}
}
Base address Edit
wss://stream.cryptoland.com/public
Request message format Edit
{
"method": "subscribe",
"params": [
"{topic}@{arg},{arg}",
"{topic}@{arg}"
],
"id": "{id}" //call back ID
}
{
"method": "unsubscribe",
"params": [
"{topic}@{arg},{arg}"
],
"id": "{id}" //call back ID
}
Response message format Edit
{
"id": "{id}", //call back ID
"code": 1, //result 0=success;1=fail;2=listenKey invalid
"msg": ""
}
{"id":"123", "code": 0, "msg": "success"}
{"id":"123", "code": 401, "msg": "token expire"}
Push message format Edit
{
"topic": "trade",
"event": "trade@btc_usdt", //title
"data": { }
}
{
"topic": "trade",
"event": "trade@btc_usdt",
"data": {
"s": "btc_usdt",
"i": 6316559590087222000,
"t": 1655992403617,
"p": "43000",
"q": "0.21",
"b": true
}
}
Heartbeat Edit
Each link of the client needs to send a ping message periodically, and the server will reply to the pong message. If the server does not receive a ping message from the client within 1 minute, it will actively disconnect the link.
Subscription parameters Edit
format
{topic}@{arg},{arg},…
Orderbook manage Edit
How to manage a local order book correctly
1.Open a stream to wss://stream.cryptoland.com/public , depth_update@btc_usdt
2.Buffer the events you receive from the stream.
3.Get a depth snapshot from https://sapi.cryptoland.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, // trade id
"t": 1655992403617, // trade time
"p": "43000", // trade price
"q": "0.21", // qty，trade quantity
"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
}
}
All ticker Edit
request
format: tickers
rate: 1000ms, only when there are changes
{
"topic": "tickers",
"event": "tickers",
"data": [ ] // refer to ticker(real-time push)
}
Base address Edit
wss://stream.cryptoland.com/private
Request message format Edit
param format
{topic}@{arg},{arg},…
{
"method": "subscribe",
"params": [
"{topic}@{arg},{arg}", //event
"{topic}@{arg}"
],
"listenKey": "512312356123123123", //the listener Key, Apply 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
{
"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", // balance available 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
"t": 1656043204763, // time happened time
"i": "6216559590087220004", // orderId,
"ci": "test123", // clientOrderId
"st": "PARTIALLY_FILLED", // state
"sd": "BUY", // side BUY/SELL
"eq": "2", // executedQty executed quantity
"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
"t": 1656043204763, //time
"i": "6316559590087251233", // tradeId
"oi": "6216559590087220004", // orderId
"p": "30000", // trade price
"q": "3", // qty quantity
"v": "90000" //volumn trade amount
}
}
REST API Edit
生产环境: https://sapi.cryptoland.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
由于CRYPTOLAND需要为第三方平台提供一些开放性的接口，所以需要接口的数据安全问题，比如数据是否被篡改，数据是否已过时，数据是否可以重复提交，接口在某个时间内访问频率等问题。其中数据是否被篡改是最重要的。
1、先通过用户中心申请appkey和secretkey，针对不同的调用，提供不同的appkey和secretkey
2、加入timestamp(时间戳)，其值应当是请求发送时刻的unix时间戳(毫秒)，数据的有郊时间根据此值来计算。
3、加入signature(数据签名)，所有数据的签名信息。
4、加入recvwindow(自定义请求有效时间)，有效时间目前相对简单统一固定为某个值。
服务器收到请求时会判断请求中的时间戳，最长60秒，最小为2秒，如果是5000毫秒之前发出的，则请求会被认为无效。这个时间窗口值可以通过发送可选参数recvWindow来设置。 另外，如果服务器计算得出客户端时间戳在服务器时间的‘未来’一秒以上，也会拒绝请求。 关于交易时效性 互联网状况并不100%可靠，不可完全依赖,因此你的程序本地到CRYPTOLAND服务器的时延会有抖动. 这是我们设置recvwindow的目的所在，如果你从事高频交易，对交易时效性有较高的要求，可以灵活设置recvwindow以达到你的要求。
不推荐使用5秒以上的recvwindow
5、加入algorithms (签名方法/算法)，用户计算签名是基于哈希的协议，推荐使用HmacSHA256。具体支持那些协议，请参见下面表格中所列出。
HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256(推荐)、HmacSHA384、HmacSHA512
签名生成 Edit
以https://sapi.cryptoland.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":"ETH_USDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":3,"quantity":2}
请求报文样例：
curl --location --request POST 'https://sapi.cryptoland.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":"ETH_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/CryptoLandEX/java-demo
各个接口的请求信息样例
https://github.com/CryptoLandEX/java-demo/blob/main/request.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_F0101 | 触发价格过滤器-最小值 |
| ORDER_F0102 | 触发价格过滤器-最大值 |
| ORDER_F0103 | 触发价格过滤器-步进值 |
| ORDER_F0201 | 触发数量过滤器-最小值 |
| ORDER_F0202 | 触发数量过滤器-最大值 |
| ORDER_F0203 | 触发数量过滤器-步进值 |
| ORDER_F0301 | 触发金额过滤器-最小值 |
| ORDER_F0401 | 触发开盘保护滤器 |
| ORDER_F0501 | 触发限价保护滤器-买单最大偏离度 |
| ORDER_F0502 | 触发限价保护滤器-卖单最大偏离度 |
| ORDER_F0601 | 触发市价保护滤器 |
| COMMON_001 | 用户不存在 |
| COMMON_002 | 系统繁忙，请稍后再试 |
| COMMON_003 | 操作失败，请稍后再试 |
| CURRENCY_001 | 币种信息异常 |
公共模块 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
/v4/public/time
public String getServerInfo(){
}
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": {
"serverTime": 1662435658062 //服务器时间
}
}
获取交易对信息 Edit
/v4/public/symbol
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | false | 交易对 eg:btc_usdt | ||
| symbols | string | false | 交易对集合，优先级高于symbol。 eg: btc_usdt,eth_usdt | ||
| version | string | false | 版本号,当请求版本号与响应内容版本一致时，不返回清单，减少IO eg: 2e14d2cd5czcb2c2af2c1db65078d075 |
限流规则
1.获取单个交易对：100/s/ip
2.获取多个交易对：10/s/ip
过滤器
过滤器，即Filter，定义了一系列交易规则。针对不同的领域或者实体有不同的过滤器，这里主要介绍针对symbol这个实体的过滤器。 对于symbol来说，有两种过滤器，一种是全局过滤器，一种是针对某个交易对定制的过滤器。
价格过滤器 PRICE FILTER
价格过滤器 用于检测订单中 price 参数的合法性。包含以下三个部分:
1.min 定义了订单中price允许的最小值
2.max 定义了订单中price允许的最大值
3.tickSize 定义了订单中price的步进间隔，即price必须等于minPrice+(tickSize的整数倍)
以上每一项均可为null，为null时代表这一项不再做限制
逻辑伪代码如下:
- price >= min
- price <= max
- (price-minPrice) % tickSize == 0
数量过滤器 QUANTITY FILTER
其逻辑和PRICE FILTER 类似，不过针对的是订单数量。
其内部包含三个部分
1.min 允许的最小值
2.max 允许的最大值
3.tickSize 步进间隔，即quantity必须等于minQuantity+(tickSize的整数倍)
以上每一项均可为null，为null时代表这一项不再做限制
逻辑伪代码如下:
- quantity>= min
- quantity<= max
- (quantity-minQuantity)% tickSize == 0
金额过滤器 QUOTE_QTY FILTER
对于订单的金额做限制
其内部定义了min允许的最小值
当min为null时，订单不做限制
否则限制规则如下：
1.对于现价LIMIT类型的订单，需满足 price*quantity>=min
2.对于市价MARKET类型并且是购买类型(orderSide=BUY)订单，需满足quoteQty>=min,(quoteQty,市价按金额下单时必填的金额)
开盘保护过滤器 PROTECTION_ONLINE FILTER
对处于开盘之后指定的时间范围内，对于现价类型的订单的价格进行限制
该过滤器内部定义了最大价格倍数(maxPriceMultiple)，持续时间(durationSeconds)。
限制逻辑:当处于交易对开盘后durationSeconds时间范围内，订单类型为现价类（LIMIT）的订单
须满足订单价格price<=openPrice*maxPriceMultiple,才会通过（openPrice为开盘价）。
其他类型的订单或者不在开盘时间范围内的订单不做限制。
对于maxPriceMultiple,durationSeconds均可为null,为null时，不做开盘保护限制。
现价保护过滤器 PROTECTION_LIMIT FILTER
对于订单类型(orderType)为LIMIT(现价) 类型的订单具有价格保护限制，包含以下两个部分
1.buyMaxDeviation 买单最大偏离度，限制了买单价格与最新成交价之间的差值
2.sellMaxDeviation 卖单最大偏离度，限制了卖单价格与最新成交价之间的差值
若没有最新成交价则不做限制，或者以上参数为null,则对应方向类型订单不做限制
为了通过限价保护，订单price必须满足以下条件(latestPrice为最新成交价)
买单: price >= latestPrice-latestPrice*buyMaxDeviation
卖单: price <= latestPrice+latestPrice*sellMaxDeviation
市价保护过滤器 PROTECTION_MARKET FILTER
对于订单类型为MARKET的订单具有价格限制保护机制，其内部规定了maxDeviation最大偏差率。
对于市价类型订单，市场价格须满足以下条件，订单才会通过(sellBestPrice 卖一价格，buyBestPrice 买一价格，latestPrice 最新成交价,这些数据均通过历史成交数据获得)
买单: latestPrice + latestPrice* maxDeviation >= sellBestPrice
卖单: latestPrice - latestPrice* maxDeviation <= buyBestPrice
对于以上情况maxDeviation，latestPrice，sellBestPrice ，buyBestPrice
均有可能为空或者没有最新成交价，买一价格，卖一价格，则不做限制
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": {
"time": 1662444177871, //时间
"version": "7cd2cfab0dc979339f1de904bd90c9cb", //内容版本
"symbols": [ //交易对清单
{
"id": 614, //ID
"symbol": "btc_usdt", //交易对
"state": "ONLINE", //交易对状态[ONLINE=上线的;OFFLINE=下线的,DELISTED=退市]
"tradingEnabled": true, //启用交易
"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, //交易数量精度
"orderTypes": [ //订单类型[LIMIT=限价单;MARKET=市价单]
"LIMIT",
"MARKET"
],
"timeInForces": [ //有效方式[GTC=成交为止,一直有效; IOC=无法立即成交(吃单)的部分就撤销; FOK=无法全部立即成交就撤销; GTX=无法成为挂单方就撤销]
"GTC",
"FOK",
"IOC",
"GTX"
],
"displayWeight": 1, //展示权重，越大越靠前
"displayLevel": "FULL", //展示级别,[FULL=完全展示,SEARCH=搜索展示,DIRECT=直达展示,NONE=不展示]
"plates": [], //所属板块 eg:22,23,24
"filters": [ //过滤器
{
"filter": "PROTECTION_LIMIT",
"buyMaxDeviation": "0.8"
"sellMaxDeviation": "0.8"
},
{
"filter": "PROTECTION_MARKET",
"maxDeviation": "0.1"
},
{
"filter": "PROTECTION_ONLINE",
"durationSeconds": "300",
"maxPriceMultiple": "5"
},
{
"filter": "PRICE",
"min": null,
"max": null,
"tickSize": null
},
{
"filter": "QUANTITY",
"min": null,
"max": null,
"tickSize": null
},
{
"filter": "QUOTE_QTY",
"min": null
},
]
}
]
}
}
获取深度数据 Edit
/v4/public/depth
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | true | 交易对 eg:btc_usdt | ||
| limit | number | false | 50 | 数量 | 1~500 |
限流规则
200/s/ip
public String depth(){
}
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": {
"timestamp": 1662445330524, //时间戳
"lastUpdateId": 137333589606963580, //最后更新记录
"bids": [ //买盘([?][0]=价位;[?][1]=挂单量)
[
"200.0000", //价位
"0.996000" //挂单量
],
[
"100.0000",
"0.001000"
],
[
"20.0000",
"10.000000"
]
],
"asks": [] //卖盘([?][0]=价位;[?][1]=挂单量)
}
}
获取k线数据 Edit
/v4/public/kline
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | true | 交易对 eg:btc_usdt | ||
| interval | string | true | K线类型 ,1m;3m;5m;15m;30m;1h;2h;4h;6h;8h;12h;1d;3d;1w;1M eg:1m | [1m;3m;5m;15m;30m;1h;2h;4h;6h;8h;12h;1d;3d;1w;1M] | |
| startTime | number | false | 起始时间戳 | ||
| endTime | number | false | 结束时间戳 | ||
| limit | number | false | 100 | 限制数量 | 1~1000 |
限流规则
100/s/ip
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [
{
"t": 1662601014832, //开盘时间(time)
"o": "30000", //开盘价(open)
"c": "32000", //收盘价(close)
"h": "35000", //最高价(high)
"l": "25000", //最低价(low)
"q": "512", //成交量(quantity)
"v": "15360000" //成交额(volume)
}
]
}
查询近期成交列表 Edit
/v4/public/trade/recent
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | true | 交易对 | ||
| limit | number | false | 200 | 数量 | 1，1000 |
限流规则
100/s/ip
public String tradeRecent(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [
{
"i": 0, //ID
"t": 0, //成交时间(time)
"p": "string", //成交价(price)
"q": "string", //成交量(quantity)
"v": "string", //成交额(volume)
"b": true //方向(buyerMaker)
}
]
}
查询历史成交列表 Edit
/v4/public/trade/history
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | true | 交易对 | ||
| limit | number | false | 200 | 数量 | 1，1000 |
| direction | string | true | 查询方向 | PREV-上一页,NEXT-下一页 | |
| fromId | number | false | 起始ID，eg: 6216559590087220004 |
限流规则
100/s/ip
public String tradeHistory(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [
{
"i": 0, //ID
"t": 0, //成交时间(time)
"p": "string", //成交价(price)
"q": "string", //成交量(quantity)
"v": "string", //成交额(volume)
"b": true //方向(buyerMaker)
}
]
}
完整ticker Edit
/v4/public/ticker
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | false | 交易对 eg:btc_usdt | ||
| symbols | array | false | 交易对集合，优先级高于symbol。 eg: btc_usdt,eth_usdt | ||
| tags | string | false | 标签集合,逗号分割，当前仅支持 spot |
限流规则
1.单个交易对：100/s/ip
2.多个交易对：10/s/ip
public String price(){
}
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": [
{
"s": "btc_usdt", //交易对(symbol)
"t": 1662444879425, //更新时间(time)
"cv": "0.00", //价格变动(change value)
"cr": "0.0000", //价格变动百分比(change rate)
"o": "200.00", //最早一笔(open)
"l": "200.00", //最低(low)
"h": "200.00", //最高(high)
"c": "200.00", //最后一笔(close)
"q": "0.002", //成交量(quantity)
"v": "0.40", //成交额(volume)
"ap": null, //asks price(卖一价)
"aq": null, //asks qty(卖一量)
"bp": null, //bids price(买一价)
"bq": null //bids qty(买一量)
}
]
}
获取最新价格ticker Edit
/v4/public/ticker/price
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | false | 交易对 eg:btc_usdt | ||
| symbols | array | false | 交易对集合，优先级高于symbol。 eg: btc_usdt,eth_usdt | ||
| tags | string | false | 标签集合,逗号分割，当前仅支持 spot |
限流规则
1.单个交易对：100/s/ip
2.多个交易对：10/s/ip
public String price(){
}
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": [
{
"s": "btc_usdt", //交易对(symbol)
"t": 1661856036925 //时间(time)
"p": "9000.0000", //价格(price)
}
]
}
获取最优挂单ticker Edit
/v4/public/ticker/book
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | false | 交易对 eg:btc_usdt | ||
| symbols | array | false | 交易对集合，优先级高于symbol。 eg: btc_usdt,eth_usdt | ||
| tags | string | false | 标签集合,逗号分割，当前仅支持 spot |
限流规则
1.单个交易对：100/s/ip
2.多个交易对：10/s/ip
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": [
{
"s": "btc_usdt", //交易对(symbol)
"t": 1661856036925, //最后更新时间(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.单个交易对：100/s/ip
2.多个交易对：10/s/ip
{
"rc": 0,
"mc": "SUCCESS",
"ma": [],
"result": [
{
"s": "btc_usdt", //交易对(symbol)
"t": 1661856036925, //时间(time)
"cv": "0.0000", //价格变动(change value)
"cr": "0.00", //价格变动百分比(change rate)
"o": "9000.0000", //最早一笔(open)
"l": "9000.0000", //最低(low)
"h": "9000.0000", //最高(high)
"c": "9000.0000", //最后一笔(close)
"q": "0.0136", //成交量(quantity)
"v": "122.9940" //成交额(volume)
}
]
}
单笔获取 Edit
/v4/order/{orderId}
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| orderId | number | true | 订单ID |
public String orderGet(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"symbol": "BTC_USDT", //交易对
"orderId": "6216559590087220004", //订单号
"clientOrderId": "16559590087220001", //客户端订单号
"baseCurrency": "string", //标的币种
"quoteCurrency": "string", //报价币种
"side": "BUY", //订单方向 BUY-买,SELL-卖
"type": "LIMIT", //订单类型 LIMIT-现价,MARKET-市价
"timeInForce": "GTC", //有效方式 GTC,IOC,FOK,GTX
"price": "40000", //价格
"origQty": "2", //原始数量
"origQuoteQty": "48000", //原始金额
"executedQty": "1.2", //已执行数量
"leavingQty": "string", //待执行数量（若撤单或下单拒绝，该值为0）
"tradeBase": "2", //成交标的(成交数量)
"tradeQuote": "48000", //成交报价(成交金额)
"avgPrice": "42350", //成交均价
"fee": "string", //手续费
"feeCurrency": "string", //手续费币种
"state": "NEW", //订单状态 NEW-新建,PARTIALLY_FILLED-部分成交,FILLED-全部成交,CANCELED-用户撤单,REJECTED-下单失败,EXPIRED-过期(time_in_force撤单或溢价撤单)
"time": 1655958915583, //订单时间
"updatedTime": 1655958915583 //订单更新时间
}
}
单笔查询 Edit
/v4/order
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| orderId | number | false | 订单ID | ||
| clientOrderId | string | false | 客户端订单号 |
public String orderGet(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"symbol": "BTC_USDT", //交易对
"orderId": "6216559590087220004", //订单号
"clientOrderId": "16559590087220001", //客户端订单号
"baseCurrency": "string", //标的币种
"quoteCurrency": "string", //报价币种
"side": "BUY", //订单方向 BUY-买,SELL-卖
"type": "LIMIT", //订单类型 LIMIT-现价,MARKET-市价
"timeInForce": "GTC", //有效方式 GTC,IOC,FOK,GTX
"price": "40000", //价格
"origQty": "2", //原始数量
"origQuoteQty": "48000", //原始金额
"executedQty": "1.2", //已执行数量
"leavingQty": "string", //待执行数量（若撤单或下单拒绝，该值为0）
"tradeBase": "2", //成交标的(成交数量)
"tradeQuote": "48000", //成交报价(成交金额)
"avgPrice": "42350", //成交均价
"fee": "string", //手续费
"feeCurrency": "string", //手续费币种
"state": "NEW", //订单状态 NEW-新建,PARTIALLY_FILLED-部分成交,FILLED-全部成交,CANCELED-用户撤单,REJECTED-下单失败,EXPIRED-过期(time_in_force撤单或溢价撤单)
"time": 1655958915583, //订单时间
"updatedTime": 1655958915583 //订单更新时间
}
}
单笔下单 Edit
/v4/order
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | true | 交易对 | ||
| clientOrderId | string | false | 客户端ID正则：^[a-zA-Z0-9_]{4,32}$ | ||
| side | string | true | 买卖方向 BUY-买,SELL-卖 | ||
| type | string | true | 订单类型 LIMIT-现价,MARKET-市价 | ||
| timeInForce | string | true | 有效方式 GTC, FOK, IOC, GTX | ||
| bizType | string | true | 业务类型 SPOT-现货, LEVER-杠杆 | ||
| price | number | false | 价格。现价必填; 市价不填 | ||
| quantity | number | false | 数量。现价必填；市价按数量下单时必填 | ||
| quoteQty | number | false | 金额。现价不填；市价按金额下单时必填 |
限流规则
50/s/apikey
public String orderPost(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"orderId": "6216559590087220004" //订单ID
}
}
单笔撤单 Edit
/v4/order/{orderId}
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| orderId | number | true | 订单ID |
public String orderDel(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"cancelId": "6216559590087220004"
}
}
批量获取 Edit
/v4/batch-order
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| orderIds | string | true | 订单ID集合，逗号分割 eg: 6216559590087220004,6216559590087220004 |
reponse 字段信息参考单笔订单获取接口
public String batchOrderGet(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [
{
"symbol": "BTC_USDT",
"orderId": "6216559590087220004",
"clientOrderId": "16559590087220001",
"baseCurrency": "string",
"quoteCurrency": "string",
"side": "BUY",
"type": "LIMIT",
"timeInForce": "GTC",
"price": "40000",
"origQty": "2",
"origQuoteQty": "48000",
"executedQty": "1.2",
"leavingQty": "string",
"tradeBase": "2",
"tradeQuote": "48000",
"avgPrice": "42350",
"fee": "string",
"feeCurrency": "string",
"state": "NEW",
"time": 1655958915583,
"updatedTime": 1655958915583
}
]
}
批量撤单 Edit
/v4/batch-order
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| clientBatchId | string | false | 客户端批次号 | ||
| orderIds | array | true | 集合[6216559590087220004,6216559590087220005] |
注意：参数以json形式放在body中
public String batchOrderDel(){
}
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {}
}
查询当前挂单 Edit
/v4/open-order
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | false | 交易对，不传代表所有 | ||
| bizType | string | false | 业务类型 SPOT-现货, LEVER-杠杆 | ||
| side | string | false | BUY-买,SELL-卖 |
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [ //字段信息参考单笔订单获取接口
{
"symbol": "BTC_USDT",
"orderId": "6216559590087220004",
"clientOrderId": "16559590087220001",
"baseCurrency": "string",
"quoteCurrency": "string",
"side": "BUY",
"type": "LIMIT",
"timeInForce": "GTC",
"price": "40000",
"origQty": "2",
"origQuoteQty": "48000",
"executedQty": "1.2",
"leavingQty": "string",
"tradeBase": "2",
"tradeQuote": "48000",
"avgPrice": "42350",
"fee": "string",
"feeCurrency": "string",
"state": "NEW",
"time": 1655958915583,
"updatedTime": 1655958915583
}
]
}
撤销当前挂单 Edit
/v4/open-order
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | false | 交易对，不传代表所有 | ||
| bizType | string | false | 业务类型 SPOT-现货, LEVER-杠杆 | ||
| side | string | false | BUY-买,SELL-卖 |
注意：参数以json形式放在body中
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {}
}
历史订单查询 Edit
/v4/history-order
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | false | 交易对，不传代表所有 | ||
| bizType | string | false | 业务类型 SPOT-现货, LEVER-杠杆 | ||
| side | string | false | BUY-买,SELL-卖 | ||
| type | string | false | 订单类型 LIMIT-现价, MARKET-市价 | ||
| state | string | false | 订单状态 NEW-新建,PARTIALLY_FILLED-部分成交,FILLED-全部成交,CANCELED-用户撤单,REJECTED-下单失败,EXPIRED-过期(time_in_force撤单或溢价撤单) | ||
| fromId | number | false | 起始ID | ||
| direction | string | false | 查询方向:PREV, NEXT | ||
| limit | number | false | 20 | 限制数量,最大100 | |
| startTime | number | false | 开始时间 eg:1657682804112 | ||
| endTime | number | false | 结束时间 | ||
| hiddenCanceled | bool | false | 隐藏已取消 |
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"hasPrev": true,
"hasNext": true,
"items": [ //内容信息参考单笔获取订单接口
{
"symbol": "BTC_USDT",
"orderId": "6216559590087220004",
"clientOrderId": "16559590087220001",
"baseCurrency": "string",
"quoteCurrency": "string",
"side": "BUY",
"type": "LIMIT",
"timeInForce": "GTC",
"price": "40000",
"origQty": "2",
"origQuoteQty": "48000",
"executedQty": "1.2",
"leavingQty": "string",
"tradeBase": "2",
"tradeQuote": "48000",
"avgPrice": "42350",
"fee": "string",
"feeCurrency": "string",
"state": "NEW",
"time": 1655958915583,
"updatedTime": 1655958915583
}
]
}
}
成交查询 Edit
/v4/trade
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | false | 交易对，不传代表所有 | ||
| bizType | string | false | 业务类型 SPOT-现货, LEVER-杠杆 | ||
| orderSide | string | false | BUY-买,SELL-卖 | ||
| orderType | string | false | 订单类型 LIMIT-现价, MARKET-市价 | ||
| orderId | number | false | 订单号 | ||
| fromId | number | false | 分页起始ID | ||
| direction | string | false | 查询方向:PREV, NEXT | ||
| limit | number | false | 20 | 限制数量,最大100 | |
| startTime | number | false | 开始时间 eg:1657682804112 | ||
| endTime | number | false | 结束时间 |
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"hasPrev": true,
"hasNext": true,
"items": [
{
"symbol": "BTC_USDT", //交易对
"tradeId": "6316559590087222001", //成交单号
"orderId": "6216559590087220004", //订单号
"orderSide": "BUY", //订单方向
"orderType": "LIMIT", //订单类型
"bizType": "SPOT", //业务类型
"time": 1655958915583, //成交时间
"price": "40000", //成交价格
"quantity": "1.2", //成交数量
"quoteQty": "48000", //成交金额
"baseCurrency": "BTC", //标的币种类型
"quoteCurrency": "USDT", //报价币种类型
"fee": "0.5", //手续费资产金额
"feeCurrency": "USDT", //手续费资产类型
"takerMaker": "taker" //takerMaker
}
]
}
}
获取币种信息 Edit
/v4/public/currencies
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": [
{
"id": 11, //币种id
"currency": "usdt", //币种名称
"fullName": "usdt", //币种全称
"logo": null, //币种logo
"cmcLink": null, //cmc链接
"weight": 100, //权重
"maxPrecision": 6, //精度
"depositStatus": 1, //充值状态(0关闭 1开放)
"withdrawStatus": 1, //提现状态(0关闭 1开放)
"convertEnabled": 1, //小额资产兑换开关[0=关;1=开]
"transferEnabled": 1 //划转开关[0=关;1=开]
}
]
}
获取单个币种资产 Edit
/v4/balance
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| currency | string | true | eg:usdt |
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"currency": "usdt", //币种
"currencyId": 0, //币种ID
"frozenAmount": 0, //冻结数量
"availableAmount": 0, //可用数量
"totalAmount": 0, //总数量
"convertBtcAmount": 0 //折算BTC数量
}
}
获取币种资产列表 Edit
/v4/balances
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| currencies | string | false | 币种列表,逗号分隔，eg: usdt,btc |
{
"rc": 0,
"mc": "string",
"ma": [
{}
],
"result": {
"totalBtcAmount": 0,
"assets": [ //参数内容参考获取单个币种资产接口
{
"currency": "string",
"currencyId": 0,
"frozenAmount": 0,
"availableAmount": 0,
"totalAmount": 0,
"convertBtcAmount": 0
}
]
}
}
基地址 Edit
wss://stream.cryptoland.com/public
请求报文格式 Edit
{
"method": "subscribe",
"params": [
"{topic}@{arg},{arg}",
"{topic}@{arg}"
],
"id": "{id}" //回调ID
}
{
"method": "unsubscribe",
"params": [
"{topic}@{arg},{arg}"
],
"id": "{id}" //回调ID
}
响应报文格式 Edit
{
"id": "{id}", //请求回调ID
"code": 1, //结果0=成功;1=失败;2=listenKey⽆效
"msg": ""
}
{"id":"123", "code": 0, "msg": "success"}
{"id":"123", "code": 401, "msg": "token expire"}
推送报文格式 Edit
{
"topic": "trade", //事件
"event": "trade@btc_usdt", //主题
"data": { } //数据
}
{
"topic": "trade",
"event": "trade@btc_usdt",
"data": {
"s": "btc_usdt",
"i": 6316559590087222000,
"t": 1655992403617,
"p": "43000",
"q": "0.21",
"b": true
}
}
心跳 Edit
客户端每个链接需要定期发送ping消息，服务端会回复pong的消息，服务端在1分钟内没有收到客户端的ping消息，会主动断开链接
订阅参数 Edit
结构
{topic}@{arg},{arg},…
Orderbook 维护 Edit
如何正确在本地维护一个orderbook副本
1.订阅 wss://stream.cryptoland.com/public，depth_update@btc_usdt
2.开始缓存收到的更新。同一个价位，后收到的更新覆盖前面的。
3.访问Rest接口 https://sapi.cryptoland.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, // time，成交时间
"p": "43000", // price，成交价格
"q": "0.21", // qty，成交数量
"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 成交额
}
}
所有ticker Edit
请求
语法: tickers
速率: 1000ms，(只推送有变化部分)
{
"topic": "tickers",
"event": "tickers",
"data": [ ] // 同 ticker
}
基地址 Edit
wss://stream.cryptoland.com/private
请求报文格式 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
{
"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 交易对
"t": 1656043204763, // time 发⽣时间
"i": "6216559590087220004", // orderId 订单号
"ci": "test123", // clientOrderId 客户端订单号
"st": "PARTIALLY_FILLED", // state 状态
"sd": "BUY", // side 方向 BUY/SELL
"eq": "2", // executedQty 已执⾏数量
"ap": "30000", // avg price 均价
"f": "0.001" // fee 手续费
}
}
订单成交 Edit
param
语法: trade
示例: trade
{
"topic": "trade",
"event": "trade",
"data": {
"s": "btc_usdt", // symbol 交易对
"t": 1656043204763, // time 发⽣时间
"i": "6316559590087251233", // tradeId 订单号
"oi": "6216559590087220004", // orderId 订单号
"p": "30000", // price 成交价
"q": "3", // qty 成交量
"v": "90000" // quoteQty 成交量
}
}
REST API Edit
Official:
USDT-M:https://fapi.cryptoland.com
Coin-M:https://dapi.cryptoland.com
Basic Information of the Interface Edit
Due to the reasons of high latency and poor stability, it is not recommend to access the CRYPTOLAND 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 CRYPTOLAND 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.
-
Offline distribution of appkey and secretkey, for different calls, provide different appkey and secretkey.
-
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.
-
Add signature information for all data.
-
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 CRYPTOLAND 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.cryptoland.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, Apply for the uri of the api is Here .
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/CryptoLandEX/futures-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 |
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 All Trading Pairs Edit
/future/market/v1/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 |
注：此方法不需要签名
{
"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) |
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 |
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 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 Trading Pair Risk Fund Balance Edit
/future/market/v1/public/contract/risk-balance
Parameters
| Parameter | Type | mandatory | Default | Description | Ranges |
|---|---|---|---|---|---|
| symbol | string | false | 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
{
"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 |
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
}
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 | false | N/A | 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 | |
| reduceOnly | boolean | false | false | Reduce only | |
| 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 |
{
"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 |
{
"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 | 起始时间 | |
| endTime | integer | false | N/A | 结束时间 |
{
"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
}
],
"page": 0,
"ps": 0,
"total": 0
},
"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 |
{
"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 |
{
"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 | true | 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 |
{
"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 |
{
"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 don't pass parameters) |
{
"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 |
|---|---|---|---|---|---|
| symbol | string | true | N/A | 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);TRAILING_STOP_MARKET(trailing stop order) | TAKE_PROFIT;STOP;TAKE_PROFIT_MARKET;STOP_MARKET;TRAILING_STOP_MARKET |
| origQty | number | true | N/A | Quantity (Cont) | |
| price | number | false | N/A | Price | |
| stopPrice | number | false | N/A | Trigger price | |
| timeInForce | string | true | N/A | Valid way:GTC;IOC;FOK;GTX | 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 |
| expireTime | integer | false | N/A | Expiration time | |
| positionSide | string | true | N/A | Position side:LONG;SHORT | LONG;SHORT |
{
"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 |
{
"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 | false | N/A | Trading pair (cancel all trading pair orders if don't pass parameters) |
{
"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 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {
"items": [
{
"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 |
{
"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 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {
"hasNext": false, //Is there a next page
"hasPrev": false, //Is there a previous page
"items": [ //Datasheets
{
"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 |
{
"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 |
{
"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 | false | N/A | Trading pair (cancel all trading pair orders if don't pass parameters) |
{
"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 |
{
"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 |
{
"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 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {},
"returnCode": 0
}
Get Account Related Information Edit
/future/user/v1/account/info
{
"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
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {},
"returnCode": 0
}
Open Contract Edit
/future/user/v1/account/open
{
"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 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {
"availableBalance": 0, //Available balance
"coin": "", //Currency
"isolatedMargin": 0, //Frozen isolated margin
"openOrderMarginFrozen": 0, //Frozen order
"walletBalance": 0 //Balance
},
"returnCode": 0
}
Get User's Funds Information Edit
/future/user/v1/balance/list
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": [
{
"availableBalance": 0, //Available balance
"coin": "", //Currency
"isolatedMargin": 0, //Frozen isolated margin
"openOrderMarginFrozen": 0, //Frozen order
"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 |
{
"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 |
{
"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 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) |
{
"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
}
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 |
{
"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 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {},
"returnCode": 0
}
Alter the automatical margin call Edit
/future/user/v1/position/auto-margin
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 |
| autoMargin | boolean | true | N/A | Whether to automatically call margin | true;false |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {},
"returnCode": 0
}
Close All Edit
/future/user/v1/position/close-all
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": true,
"returnCode": 0
}
Get ADL Information Edit
/future/user/v1/position/adl
{
"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 |
{
"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 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": true,
"returnCode": 0
}
List of Collected Trading Pairs Edit
/future/user/v1/user/collection/list
{
"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 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {},
"returnCode": 0
}
Base address Edit
wss://fstream.cryptoland.com/ws/market
Request message format Edit
{
"method": "subscribe",
"params": [
"{topic}@{arg},{arg}",
"{topic}@{arg}"
],
"id": "{id}" //call back ID
}
{
"method": "unsubscribe",
"params": [
"{topic}@{arg},{arg}"
],
"id": "{id}" //call back ID
}
Response message format Edit
{
"id": "{id}", //call back ID
"code": 1, //result 0=success;1=fail;2=listenKey invalid
"msg": ""
}
{"id":"123", "code": 0, "msg": "success"}
{"id":"123", "code": 401, "msg": "token expire"}
Push message format Edit
{
"topic": "trade",
"event": "trade@btc_usdt", //title
"data": { }
}
{
"topic": "trade",
"event": "trade@btc_usdt",
"data": {
"s": "btc_usdt",
"i": 6316559590087222000,
"t": 1655992403617,
"p": "43000",
"q": "0.21",
"b": true
}
}
Heartbeat Edit
Each link of the client needs to send a ping message periodically, and the server will reply to the pong message. If the server does not receive a ping message from the client within 1 minute, it will actively disconnect the link.
Subscription parameters Edit
format
{topic}@{arg},{arg},…
Orderbook manage Edit
How to manage a local order book correctly
1.Open a stream to wss://fstream.cryptoland.com/ws/market , depth_update@btc_usdt
2.Buffer the events you receive from the stream.
3.Get a depth snapshot from https://fapi.cryptoland.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
}
}
All ticker Edit
request
format: tickers
rate: 1000ms, only when there are changes
{
"topic": "tickers",
"event": "tickers",
"data": [ ] // refer to ticker(real-time push)
}
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
}
}
All agg ticker Edit
request
format: agg_tickers
rate: 1000ms, only when there are changes
{
"topic": "agg_tickers",
"event": "agg_tickers",
"data": [ ] // refer to agg_ticker(real-time push)
}
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}
eg: depth_update@btc_usdt
rate: 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"
]
]
}
}
Limited depth Edit
request
format: depth@{symbol},{levels}
levels: 50
eg: depth@btc_usdt,50
rate: 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
}
}
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
}
}
Users subscription Edit
WS user subscription address:wss://fstream.cryptoland.com/ws/user
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
{
"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
{
"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
{
"topic": "trade",
"event": "trade@123456",
"data": {
"orderId":"12312312", // Order ID
"price":"34244", // Price
"quantity":"123", // Quantity
"marginUnfrozen":"123", // Quantity of unfrozen margin
"timestamp":1731231231 // Timestamp
}
}
user Order Edit
{
"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
"positionSide": "LONG", // LONG, SHORT
"marginFrozen":"123", // Occupied margin
"sourceType":"default", // DEFAULT:normal order,ENTRUST:plan commission,PROFIR:Take Profit and Stop Loss
"sourceId" : "1231231",// Triggering conditions ID
"state": "", // state:NEW：New order (unfilled);PARTIALLY_FILLED:Partial deal;PARTIALLY_CANCELED:Partial revocation;FILLED:Filled;CANCELED:Cancled;REJECTED:Order failed;EXPIRED：Expired
"createTime": 1731231231, // CreateTime
"clientOrderId":"204788317630342726"
}
}
Message Edit
{
"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.cryptoland.com
币本位合约:https://dapi.cryptoland.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
由于CRYPTOLAND需要为第三方平台提供一些开放性的接口，所以需要接口的数据安全问题，比如数据是否被篡改，数据是否已过时，数据是否可以重复提交，接口在某个时间内访问频率等问题。其中数据是否被篡改是最重要的。
1、线下分配appkey和secretkey，针对不同的调用，提供不同的appkey和secretkey
2、加入timestamp(时间戳)，其值应当是请求发送时刻的unix时间戳(毫秒)，数据的有郊时间根据此值来计算。
3、加入signature(数据签名)，所有数据的签名信息。
4、加入recvwindow(自定义请求有效时间)，有效时间目前相对简单统一固定为某个值，比如：同api同appid下10分钟内数据都有郊，此处可以再进步优化到具体单个api有效时间都不相同。
服务器收到请求时会判断请求中的时间戳，最长60秒，默认为5秒，如果是5000毫秒之前发出的，则请求会被认为无效。这个时间窗口值可以通过发送可选参数recvWindow来自定义。 另外，如果服务器计算得出客户端时间戳在服务器时间的‘未来’一秒以上，也会拒绝请求。 关于交易时效性 互联网状况并不100%可靠，不可完全依赖,因此你的程序本地到CRYPTOLAND服务器的时延会有抖动. 这是我们设置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.cryptoland.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/CryptoLandEX/futures-java-demo
返回格式 Edit
所有的接口返回都是JSON格式。
{
"returnCode": 200,
"result": {
"serverTime": 1636612706739
},
"msgInfo": "Success."
"error": null,
}
错误代码 Edit
| 状态码 | 错误信息 |
|---|---|
| 200 | 成功 |
| 401 | 需要登录 |
| 403 | 登录过期 |
获取交易对币种 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/v1/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） |
注：此方法不需要签名
{
"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 | 交易对 |
注：此方法不需要签名
{
"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/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/contract/risk-balance
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | false | 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": [ //数据列表
{
"amount": 0, //余额
"coin": "", //币种
"createdTime": 0, //时间
"id": 0 //id
}
]
},
"returnCode": 0
}
获取交易对开仓量 Edit
/future/market/v1/public/contract/open-interest
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | true | N/A | 交易对 |
注：此方法不需要签名
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {
"symbol": "", //交易对
"openInterest": "", //开仓量
"openInterestUsd": 0, //开仓价值
"time": "", //时间
},
"returnCode": 0
}
下单 Edit
/future/trade/v1/order/create
Content-Type = application/x-www-form-urlencoded && application/json
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| clientOrderId | string | false | N/A | 自定义订单id | |
| symbol | string | false | N/A | 交易对 | |
| 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 | 价格 | |
| reduceOnly | boolean | false | false | 只减仓 | |
| 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 |
{
"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 | 结束时间 |
{
"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 | 结束时间 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {
"items": [
{
"fee": 0, //手续费
"feeCoin": "", //手续费币种
"orderId": 0, //订单id
"execId": 0, //成交id
"price": 0, //成交价格
"quantity": 0, //成交数量
"symbol": "", //交易对
"timestamp": 0 //时间
}
],
"page": 0,
"ps": 0,
"total": 0
},
"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集合 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": true,
"returnCode": 0
}
根据id查询订单 Edit
/future/trade/v1/order/detail
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| orderId | integer | true | N/A | 订单id |
{
"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 | true | NEW | 订单状态 NEW：新建订单（未成交）；PARTIALLY_FILLED：部分成交；FILLED：全部成交；CANCELED：用户撤销；REJECTED：下单失败；EXPIRED：已过期；UNFINISHED：未完成；HISTORY：（历史） | |
| symbol | string | false | N/A | 交易对 |
{
"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 |
{
"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 | 交易对（不传时撤销所有交易对订单） |
{
"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
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | false | N/A | 交易对 | |
| orderSide | string | true | N/A | 买卖方向：BUY;SELL | BUY;SELL |
| entrustType | string | true | N/A | 委托类型：TAKE_PROFIT(止盈限价单)；STOP(止损限价单)；TAKE_PROFIT_MARKET（止盈市价单）；STOP_MARKET（止损市价单）；TRAILING_STOP_MARKET（跟踪止损单） | TAKE_PROFIT;STOP;TAKE_PROFIT_MARKET;STOP_MARKET;TRAILING_STOP_MARKET |
| origQty | number | true | N/A | 数量（张） | |
| price | number | false | N/A | 价格 | |
| stopPrice | number | false | N/A | 触发价 | |
| timeInForce | string | true | N/A | 有效方式：GTC;IOC;FOK;GTX | GTC;IOC;FOK;GTX |
| triggerPriceType | string | true | N/A | 触发价格类型：INDEX_PRICE(指数价格)；MARK_PRICE(标记价格)；LATEST_PRICE(最新价格) | INDEX_PRICE;MARK_PRICE;LATEST_PRICE |
| expireTime | integer | false | N/A | 过期时间 | |
| positionSide | string | true | N/A | 仓位方向：LONG;SHORT | LONG;SHORT |
{
"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 |
{
"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 | false | N/A | 交易对（不传时撤销所有交易对） |
{
"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 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {
"items": [
{
"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 |
{
"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 | 结束时间 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {
"hasNext": false, //是否有下一页
"hasPrev": false, //是否有上一页
"items": [ //数据列表
{
"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 |
{
"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 |
{
"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 | false | N/A | 交易对（不传时撤销所有交易对） |
{
"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 |
{
"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 |
{
"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 | 止损触发价 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {},
"returnCode": 0
}
获取账户相关信息 Edit
/future/user/v1/account/info
{
"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小时
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {},
"returnCode": 0
}
开通合约 Edit
/future/user/v1/account/open
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": true,
"returnCode": 0
}
获取用户单币种资金 Edit
/future/user/v1/balance/detail
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| coin | string | true | N/A | 币种 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {
"availableBalance": 0, //可用余额
"coin": "", //币种
"isolatedMargin": 0, //逐仓保证金冻结
"openOrderMarginFrozen": 0, //订单冻结
"walletBalance": 0 //钱包余额
},
"returnCode": 0
}
获取用户资金 Edit
/future/user/v1/balance/list
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": [
{
"availableBalance": 0, //可用余额
"coin": "", //币种
"isolatedMargin": 0, //逐仓保证金冻结
"openOrderMarginFrozen": 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 | 结束时间 |
{
"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 | 结束时间 |
{
"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/list
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | false | N/A | 交易对（不传时查询所有交易对的持仓信息） |
{
"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/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 | 杠杆倍数 |
{
"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 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {},
"returnCode": 0
}
修改自动追加保证金 Edit
/future/user/v1/position/auto-margin
Content-Type = application/x-www-form-urlencoded && application/json
Parameters
| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
|---|---|---|---|---|---|
| symbol | string | true | N/A | 交易对 | |
| positionSide | string | true | N/A | 仓位方向 | LONG;SHORT |
| autoMargin | boolean | true | N/A | 是否开启自动追加保证金 | true;false |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {},
"returnCode": 0
}
一键平仓 Edit
/future/user/v1/position/close-all
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": true,
"returnCode": 0
}
获取ADL信息 Edit
/future/user/v1/position/adl
{
"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 | 交易对 |
{
"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 | 交易对 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": true,
"returnCode": 0
}
收藏交易对列表 Edit
/future/user/v1/user/collection/list
{
"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 |
{
"error": {
"code": "",
"msg": ""
},
"msgInfo": "",
"result": {},
"returnCode": 0
}
基地址 Edit
wss://fstream.cryptoland.com/ws/market
请求报文格式 Edit
{
"method": "subscribe",
"params": [
"{topic}@{arg},{arg}",
"{topic}@{arg}"
],
"id": "{id}" //回调ID
}
{
"method": "unsubscribe",
"params": [
"{topic}@{arg},{arg}"
],
"id": "{id}" //回调ID
}
响应报文格式 Edit
{
"id": "{id}", //请求回调ID
"code": 1, //结果0=成功;1=失败;2=listenKey⽆效
"msg": ""
}
{"id":"123", "code": 0, "msg": "success"}
{"id":"123", "code": 401, "msg": "token expire"}
推送报文格式 Edit
{
"topic": "trade", //事件
"event": "trade@btc_usdt", //主题
"data": { } //数据
}
{
"topic": "trade",
"event": "trade@btc_usdt",
"data": {
"s": "btc_usdt",
"i": 6316559590087222000,
"t": 1655992403617,
"p": "43000",
"q": "0.21",
"b": true
}
}
心跳 Edit
客户端每个链接需要定期发送ping消息，服务端会回复pong的消息，服务端在1分钟内没有收到客户端的ping消息，会主动断开链接
订阅参数 Edit
结构
{topic}@{arg},{arg},…
Orderbook 维护 Edit
如何正确在本地维护一个orderbook副本
1.订阅 wss://fstream.cryptoland.com/ws/market，depth_update@btc_usdt
2.开始缓存收到的更新。同一个价位，后收到的更新覆盖前面的。
3.访问Rest接口 https://fapi(或dapi).cryptoland.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 //时间戳
}
}
所有ticker Edit
请求
语法: tickers
速率: 1000ms，(只推送有变化部分)
{
"topic": "tickers",
"event": "tickers",
"data": [ ] // 同 ticker
}
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 //时间戳
}
}
所有agg ticker Edit
请求
语法: agg_tickers
速率: 1000ms，(只推送有变化部分)
{
"topic": "agg_tickers",
"event": "agg_tickers",
"data": [ ] // 同 agg_ticker
}
指数价格 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}
示例: 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"
]
]
}
}
有限深度 Edit
请求
语法: depth@{symbol},{levels}
levels: 50
示例: 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 买单队列
}
}
资金费率 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
用户ws订阅地址: wss://fstream.cryptoland.com/ws/user
第一步：用户要先调用接口:/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
{
"topic": "balance",
"event": "balance@123456",
"data": {
"coin":"usdt",
"underlyingType":1, // 1:币本位，2:U本位
"walletBalance":"123", // 钱包余额
"openOrderMarginFrozen":"123", // 订单冻结
"isolatedMargin":"213", // 逐仓保证金
"crossedMargin":"0" //全仓保证金
}
}
仓位变更 Edit
{
"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
{
"topic": "trade",
"event": "trade@123456",
"data": {
"orderId":"12312312", // 订单id
"price":"34244", // 价格
"quantity":"123", // 数量
"marginUnfrozen":"123", // 保证金解冻数量
"timestamp":1731231231 // 时间戳
}
}
用户订单 Edit
{
"topic": "order",
"event": "order@123456",
"data": {
"symbol":"btc_usdt", // 交易对
"orderId": "1234", //订单id
"origQty": "34244", // 下单数量
"avgPrice": "123", // 成交均价
"price": "1111", //下单价格
"executedQty":"34244", // 已成交数量
"orderSide": "BUY", // BUY, SELL
"positionSide": "LONG", // LONG, SHORT
"marginFrozen":"123", // 占用保证金
"sourceType":"default", // DEFAULT:普通订单， ENTRUST:计划委托，PROFIR:止盈止损
"sourceId" : "1231231",// 条件订单出发ID
"state": "", // 订单状态 NEW：新建订单;未成交; PARTIALLY_FILLED：部分成交；PARTIALLY_CANCELED：部分撤销；FILLED：全部成交；CANCELED：已撤销；REJECTED：下单失败；EXPIRED：已过期
"createTime": 1731231231,// 时间戳
"clientOrderId":"204788317630342726"
}
}
用户消息 Edit
{
"topic": "notify",
"event": "notify",
"data": {
"symbol":"btc_usdt",
"positionType": "ISOLATED",
"positionSide": "LONG",
"positionSize":"123", // 持仓数量
"notifyType": "WARN", // 通知类型: WARN：告警，即将被强平，PARTIAL：部分强平，LIQUIDATION：全部强平，ADL：自动减仓
}
}