# 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": ""
    }
Last Updated: 10/28/2022, 6:41:54 PM