Trade Interface

1. Place a New Order

HTTP Requests

    # Request
    POST api/v1/user/trade

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
symbol	String	YES	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
apiKey	String	YES	Interface Key
timestamp	String	YES	Timestamp of initiating the request, unit: ms
side	String	YES	(Bid/Ask)
entrustPrice	float64	YES	Price
entrustVolume	float64	YES	Volume
tradeType	String	YES	Market/Limit
action	String	YES	Open/Close
takerProfitPrice	float64	No	Take Profit Price
stopLossPrice	float64	No	Stop Loss Price

Return Parameters

Parameters	Type	Field Description
orderId	String	Order ID

# Response
    {
        "code": 0,
        "msg": "",
        "data": {
            "orderId": "11141",
        }
    }

2. One-Click Close Position

After querying the position information, you can close the position by one-click based on the position ID. Please note that the one-click closed position is traded at market price.

HTTP Requests

    # Request
    POST api/v1/user/oneClickClosePosition

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
symbol	String	YES	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
positionId	Int64	YES	ID of the position needs to be closed with one click
apiKey	String	YES	Interface Key
timestamp	String	YES	Timestamp of initiating the request, unit: ms

Return Parameters

Parameters	Type	Description
code	Int64	error code, 0 means successfully response, others means response failure
msg	String	Error Details Description
orderId	String	Order ID generated by one-click close

# Response
    {
        "code": 0,
        "msg": "",
        "data": {
        }
    }

3. One-Click Close All Positions

Close all positions within the current account by one click. Please note that the one-click closed positions are traded at market price.

HTTP Requests

    # Request
    POST api/v1/user/oneClickCloseAllPositions

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
apiKey	String	YES	Interface Key
timestamp	String	YES	Timestamp of initiating the request, unit: ms

Return Parameters

Parameters	Type	Description
code	Int64	error code, 0 means successfully response, others means response failure
msg	String	Error Details Description
orders	String array	Multiple Order IDs generated by one-click close all

# Response
    {
        "code": 0,
        "msg": "",
        "data": {
          "orders": ["123", "456", "789"]
        }
    }

4. Cancel an Order

   Cancel an order that is currently in a unfilled state

HTTP Requests

    # Request
    POST api/v1/user/cancelOrder

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
orderId	String	YES	Order ID
symbol	String	YES	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
apiKey	String	YES	Interface Key
timestamp	String	YES	Timestamp of initiating the request, unit: ms

Return Parameters

Parameters	Type	Field Description
orderId	String	Order ID

# Response
    {
        "code": 0,
        "msg": "",
        "data": {
            "orderId": "11141",
        }
    }

5. Cancel a Batch of Orders

Cancel a batch of orders that are currently in a unfilled state

HTTP Requests

    # Request
    POST api/v1/user/batchCancelOrders

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
symbol	String	YES	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
apiKey	String	YES	Interface Key
timestamp	String	YES	Timestamp of initiating the request, unit: ms
oids	String	YES	List of order IDs, multiple order IDs are separated by commas

Return Parameters

Parameters	Type	Description
code	Int64	error code, 0 means successfully response, others means response failure
msg	String	Error Details Description

# Response
    {
        "code": 0,
        "msg": "",
        "data": {
        }
    }

6. Cancel All Orders

Cancel all orders that are currently in a unfilled state

HTTP Requests

    # Request
    POST api/v1/user/cancelAll

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
apiKey	String	YES	Interface Key
timestamp	String	YES	Timestamp of initiating the request, unit: ms

Return Parameters

Parameters	Type	Description
code	Int64	error code, 0 means successfully response, others means response failure
msg	String	Error Details Description

# Response
    {
        "code": 0,
        "msg": "",
        "data": {
        }
    }

7. Unfilled Order Acquisition

Query the details of unfilled orders within the current account over a certain period of time

HTTP Requests

    # Request
    POST api/v1/user/pendingOrders

Request Method

POST

Request Parameters

Name	Type	Required	Field Description
symbol	String	YES	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT; Return all if the field is null.
apiKey	String	YES
timestamp	String	YES	Timestamp of initiating the request, unit: ms

Return Parameters

Parameters	Type	Description
entrustTm	String	Trigger time of order
side	String	Direction (Bid/Ask)
tradeType	String	Order Type(Market/Limit)
action	String	Open/Close
entrustPrice	Float64	Order Price
entrustVolume	Float64	Order Amount
avgFilledPrice	Float64	Ave. Price
filledVolume	Float64	Filled Amount
orderId	String	Order ID
profit	Float64	Profit
commission	Float64	Commission
updateTm	String	Update time of order

# Response
   {
      "code": 0,
      "msg": "",
      "data": {
           "orders": [
               {
                   "entrustTm": "2018-04-25T15:00:51.000Z",
                   "side": "Bid",
                   "tradeType": "Limit",
                   "action": "Open",
                   "entrustPrice": 6.021954,
                   "entrustVolume": 18.098,
                   "filledVolume": 0,
                   "avgFilledPrice": 0,
                   "orderId": "6030",
                   "symbol": "BTC-USDT",
                   "profit": 0,
                   "commission": 0,
                   "updateTm": "2018-04-25T15:00:52.000Z"
               }
           ]
       }
   }

8. Query Order Details

HTTP Requests

 # Request
 POST api/v1/user/queryOrderStatus

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
apiKey	String	YES	Interface Key
timestamp	String	YES	Timestamp of initiating the request, unit: ms
symbol	String	YES	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
orderId	String	YES	Order ID

Return Parameters

Parameters	Type	Description
entrustTm	String	Order Time
side	String	Direction (Bid/Ask)
tradeType	String	Order type (Market/Limit)
action	String	Open/Close
entrustPrice	Float64	Order Price
entrustVolume	Float64	Order Amount
avgFilledPrice	Float64	Ave. Price
filledVolume	Float64	Filled Amount
orderId	String	Order No.
status	String	The status of Order (Filled or PartiallyFilled, Pending, Cancelled, Failed)
profit	Float64	Profit
commission	Float64	Commission
updateTm	String	Update time of order

Remarks

Status	Field Description
Pending	Order that has not been closed
PartiallyFilled	Order that has been Partially filled
Cancelled	Cancelled
Filled	Filled
Failed	Failed

# Response
{
    "code": 0,
    "msg": "",
    "data": {
        "entrustTm": "2018-04-25T15:00:51.000Z",
        "side": "Ask",
        "tradeType": "Limit",
        "action": "Close",
        "entrustPrice": 6.021954,
        "entrustVolume": 18.098,
        "filledVolume": 0,
        "avgFilledPrice": 0,
        "orderId": "6030",
        "status": "Filled",
        "profit": 0,
        "commission": 0,
        "updateTm": "2018-04-25T15:00:52.000Z"
     }
 }

9. Query Margin Mode

HTTP Requests

    # Request
    Post api/v1/user/getMarginMode

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
symbol	String	Yes	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
apiKey	String	Yes	Interface Key
timestamp	String	Yes	Timestamp of initiating the request, unit: ms

Return Parameters

Parameters	Type	Description
marginMode	String	Margin Mode

Remark

MarginMode	Field Description
Isolated	isolated
Cross	cross

    {
        "data": {
            "marginMode":"Isolated"
        },
        "code": 0,
        "message": ""
    }

10. Switch Margin Mode

Switch the margin mode of the Perpetual Swap Account, Cross Margin mode or Isolated Margin mode.

HTTP Requests

    # Request
    POST api/v1/user/setMarginMode

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
symbol	String	YES	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
marginMode	String	YES	Isolated or Cross
apiKey	String	YES	Interface key
timestamp	String	YES	Timestamp of initiating the request, unit: ms

Return Parameters

Parameters	Type	Description
code	Int64	error code, 0 means successfully response, others means response failure
msg	String	Error Details Description

# Response
    {
        "code": 0,
        "msg": "",
        "data": {
        }
    }

11. Query Leverage

HTTP Requests

    # Request
    Post api/v1/user/getLeverage

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
symbol	String	Yes	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
apiKey	String	Yes	Interface key
timestamp	String	Yes	Timestamp of initiating the request, unit: ms

Return Parameters

Parameters	Type	Description
longLeverage	Int64	Leverage of long position
shortLeverage	Int64	Leverage of short position

# Response
    {
        "data": {
            "longLeverage": 5,
            "shortLeverage": 5
        },
        "code": 0,
        "message": ""
    }

12. Switch Leverage

Switch the leverage size of a certain trading pair for long or short positions

HTTP Requests

    # Request
      POST api/v1/user/setLeverage

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
symbol	String	YES	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
side	String	YES	Leverage of Long or Short positions
leverage	String	YES	Leverage Size
apiKey	String	YES	Interface key
timestamp	String	YES	Timestamp of initiating the request, unit: ms

```javascript
    # Response
        {
            "code": 0,
            "msg": "",
            "data": {
                "userId": "123",
                "currency": "USDT",
                "balance": 123.33,
                "equity": 128.99,
                "unrealisedPNL": 1.22,
                "realisedPNL": 8.1,
                "availableMargin": 123.33,
                "usedMargin": 2.2,
                "freezedMargin": 3.3,
                "longLeverage": 10,
                "shortLeverage": 10,
            }
        }
```

Return Parameters

Parameters	Type	Description
code	Int64	error code, 0 means successfully response, others means response failure
msg	String	Error Details Description

# Response
    {
        "code": 0,
        "msg": "",
        "data": {
        }
    }

13. User's Force Orders

HTTP Requests

    # Request
    POST api/v1/user/forceOrders

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
symbol	String	YES	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
autoCloseType	String	YES	"LIQUIDATION" for liquidation orders, "ADL" for ADL orders.
lastOrderId	int64	YES	Used for paging, fill in 0 for the first time; for subsequent requests, fill in the last order id from the previous return results.
length	int64	YES	Length per request, max 100

Return Parameters

Parameters	Type	Description
symbol	String	Trading pair symbol
tradeType	String	Order type, Limit or Market
action	String	"LIQUIDATION" for liquidation orders, "ADL" for ADL orders.
avgFilledPrice	Float64	Average filled price
entrustTm	String	Entrust time
filledVolume	Float64	Filled volume
orderId	String	Order No.
side	String	Direction (Bid/Ask)
profit	Float64	P&L
commission	Float64	Fees

# Response
    {
        "code": 0,
        "msg": "",
        "data": {
            "symbol": "BTC-USDT",
            "tradeType": "Limit",
            "action": "Liquidation",
            "avgFilledPrice": 5938.23,
            "entrustTm": "2018-04-25T15:00:51.000Z",
            "filledVolume": 1.2123,
            "orderId": 123456789,
            "side": "Bid",
            "profit": -11.34,
            "commission": 0.4231
        }
    }

14. User's History Orders

HTTP Requests

    # Request
    POST api/v1/user/historyOrders

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
symbol	String	NO	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
lastOrderId	int64	Yes	Used for paging, fill in 0 for the first time; for subsequent requests, fill in the last order id from the previous return results.
length	int64	Yes	Length per request, max 100
apiKey	String	Yes	Interface key
timestamp	String	Yes	Timestamp of initiating the request, unit: ms

Return Parameters

Parameters	Type	Description
symbol	String	Symbol
orderId	String	Order ID
side	String	Direction (Bid/Ask)
action	String	Open/Close/ADL/Liquidation
tradeType	String	Order Type(Market/Limit)
entrustVolume	Float64	Order Amount
entrustPrice	Float64	Order Price
filledVolume	Float64	Filled Amount
avgFilledPrice	Float64	Ave. Price
profit	Float64	Profit
commission	Float64	Commission
orderStatus	String	Order Status(Filled or PartiallyFilled, Pending, Cancelled, Failed)
entrustTm	String	Entrust time of order
updateTm	String	Update time of order

Remarks

OrderStatus	Field Description
Pending	Order that has not been closed
PartiallyFilled	Order that has been Partially filled
Cancelled	Cancelled
Filled	Filled
Failed	Failed

# Response
    {
        "code": 0,
        "data": {
            "orders": [
                {
                    "action": "Open",
                    "avgFilledPrice": 31333.37,
                    "commission": -0.0009,
                    "entrustPrice": 31331.25,
                    "entrustTm": "2021-01-05T09:15:02Z",
                    "entrustVolume": 0.0001,
                    "filledVolume": 0.0001,
                    "orderId": "996273190",
                    "orderStatus": "Filled",
                    "profit": 0,
                    "side": "Bid",
                    "symbol": "BTC-USDT",
                    "tradeType": "Market",
                    "updateTm": "2021-01-05T09:15:15Z"
                }
            ]
        },
        "message": ""
    }

15. Place a Stop Order

HTTP Requests

    # Request
    POST api/v1/user/stopOrder

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
apiKey	String	Yes	Interface key
timestamp	String	Yes	Timestamp of initiating the request, unit: ms
positionId	String	Yes	Position ID
orderId	String	No	Stop Order ID
stopLossPrice	Float64	No	Stop Loss Price
takeProfitPrice	Float64	No	Taker Profit Price
entrustVolume	Float64	Yes	Order Amount

Return Parameters

Parameters	Type	Description
orderId	String	Stop Order ID

# Response
    {
        "code": 0,
        "data": {
            "orderId": "1414483504200159232"
        },
        "message": ""
    }

16. Cancel Stop Order

HTTP Requests

    # Request
    POST api/v1/user/cancelStopOrder

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
apiKey	String	Yes	Interface key
timestamp	String	Yes	Timestamp of initiating the request, unit: ms
orderId	String	Yes	Stop Order ID

Return Parameters

# Response
    {
        "code": 0,
        "message": ""
    }

17. Query Stop Orders

HTTP Requests

    # Request
    POST api/v1/user/pendingStopOrders

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
apiKey	String	Yes	Interface key
timestamp	String	Yes	Timestamp of initiating the request, unit: ms
symbol	String	Yes	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT

Return Parameters

Parameters	Type	Description
userId	String	User ID
orderId	String	Order ID
symbol	String	Symbol
positionId	String	Position ID
stopLossPrice	Float64	Stop Loss Price
takeProfitPrice	Float64	Taker Profit Price
entrustVolume	Float64	Order Amount
side	String	Direction (Bid/Ask)
entrustTm	String	Entrust time of order

# Response
    {
        "code": 0,
        "data": {
            "orders": [
                {
                    "entrustTm": "2021-07-12T07:15:21.891Z",
                    "entrustVolume": 0.001,
                    "orderId": "1414483504200159232",
                    "positionId": "1414483266773192704",
                    "side": "Ask",
                    "stopLossPrice": 10000,
                    "symbol": "BTC-USDT",
                    "takeProfitPrice": 0,
                    "userId": "809519987784454146"
                }
            ]
        },
        "message": ""
    }

18. Query History Stop Orders

HTTP Requests

    # Request
    POST api/v1/user/historyStopOrders

Request Method

POST

Request Parameters

Parameters	Type	Required	Description
apiKey	String	Yes	Interface key
timestamp	String	Yes	Timestamp of initiating the request, unit: ms
symbol	String	Yes	There must be a hyphen/ "-" in the trading pair symbol. eg: BTC-USDT
lastOrderId	int64	Yes	Used for paging, fill in 0 for the first time; for subsequent requests, fill in the last order id from the previous return results.
length	int64	Yes	Length per request, max 100

Return Parameters

Parameters	Type	Description
userId	String	User ID
orderId	String	Order ID
symbol	String	Symbol
positionId	String	Position ID
stopLossPrice	Float64	Stop Loss Price
takeProfitPrice	Float64	Taker Profit Price
entrustVolume	Float64	Order Amount
side	String	Direction (Bid/Ask)
orderStatus	String	Status of Order
entrustTm	String	Entrust Time of Order
triggerTm	String	Trigger Time of Order

Remark

OrderStatus	Description
TriggerStopLoss	Trigger by Stop Loss Price
TriggerTakeProfit	Trigger By Take Profit Price
Cancelled	Cancelled
Failed	Failed

# Response
    {
        "code": 0,
        "data": {
            "orders": [
                {
                    "entrustTm": "2021-05-17T10:13:46.000Z",
                    "entrustVolume": 0.001,
                    "orderId": "47513",
                    "orderStatus": "TriggerTakeProfit",
                    "positionId": "74578",
                    "side": "Ask",
                    "stopLossPrice": 0,
                    "symbol": "BTC-USDT",
                    "takeProfitPrice": 45400,
                    "triggerTm": "2021-05-17T11:34:06.000Z",
                    "userId": "809519987784454146"
                }
            ]
        },
        "message": ""
    }