Trade

This document covers all trade execution endpoints that require API Key authentication, such as placing, canceling, and querying orders.

1. Get Order Details

GET /api/v1/trade/order

Retrieve detailed information for a single order by its system-generated Order ID (ordId) or the client-supplied Order ID (clOrdId).

Permission: read

Query Parameters:

Name	Type	Required	Description
ordId	String	No	The system-generated order ID. Either ordId or clOrdId must be provided.
clOrdId	String	No	The client-supplied order ID. ordId is prioritized if both are sent.
instId	String	No	Instrument ID. Providing this can help locate the order faster.

Success Response (200 OK):

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instId": "BTC-USDT-SWAP",
      "ordId": "1234567890123456",
      "clOrdId": "123456789012345",
      "px": "29400.0",
      "sz": "100",
      "ordType": "limit",
      "side": "buy",
      "state": "filled",
      "avgPx": "29398.5",
      "accFillSz": "100",
      "fee": "-0.05",
      "createdAt": "1678889400123",
      "updatedAt": "1678889500345"
    }
  ]
}

---

2. Get Pending Orders

GET /api/v1/trade/orders/pending

Retrieve a list of all your active orders (in live or partially_filled state).

Permission: read

Query Parameters:

Name	Type	Required	Description
instType	String	No	Instrument type, e.g., SPOT, SWAP.
instId	String	No	Instrument ID.
limit	String	No	Number of results. Max 100, default 20.
after	String	No	Request orders older than this ordId.
before	String	No	Request orders newer than this ordId.

Success Response (200 OK):

{
  "code": "0",
  "msg": "",
  "data": [
    { "ordId": "123...", "state": "live", "...": "..." },
    { "ordId": "456...", "state": "partially_filled", "...": "..." }
  ]
}

---

3. Get Order History

GET /api/v1/trade/orders/history

Retrieve a list of your recently completed orders (filled or canceled).

Permission: read

Query Parameters:

Name	Type	Required	Description
instType	String	No	Instrument type, e.g., SPOT, SWAP.
state	String	No	Order state, filled or canceled.
limit	String	No	Number of results. Max 100, default 20.
after	String	No	Request orders older than this ordId.
before	String	No	Request orders newer than this ordId.

Success Response (200 OK):

{
  "code": "0",
  "msg": "",
  "data": [
    { "ordId": "789...", "state": "filled", "...": "..." },
    { "ordId": "012...", "state": "canceled", "...": "..." }
  ]
}

---

4. Cancel Batch Orders

POST /api/v1/trade/cancel-batch-orders

Cancel one or more open contract orders in a batch.

Permission: trade_futures

Request Body:

A JSON array containing information about the orders to be canceled.

[
  {
    "instId": "BTC-USDT-SWAP",
    "ordId": "1234567890123458"
  },
  {
    "instId": "ETH-USDT-SWAP",
    "clOrdId": "123456789012345"
  }
]

Success Response (200 OK):

The data array in the response corresponds to the request array, indicating the result of each cancellation attempt.

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "ordId": "1234567890123458",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "123456789012345",
      "sCode": "51005",
      "sMsg": "Order has already been filled."
    }
  ]
}