> For the complete documentation index, see [llms.txt](https://docs.kryptox.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kryptox.finance/api/trading-endpoints.md).

# Trading Endpoints

### Place Order

**`POST`** `/api/v1/order` · Auth `USER_DATA` · Weight `2`

#### Request Parameters

| Name          | Type    | Required | Description                                                                                                                                          |
| ------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| clientOid     | STRING  | YES      | Client-assigned unique order ID, up to 40 characters. Allowed characters: digits, letters, underscore (`_`), and hyphen (`-`). A UUID is acceptable. |
| side          | ENUM    | YES      | Order side: `buy`, `sell`                                                                                                                            |
| symbol        | STRING  | YES      | Contract symbol                                                                                                                                      |
| type          | ENUM    | YES      | Order type: `limit`, `market`. Default is `limit`.                                                                                                   |
| stop          | ENUM    | NO       | Stop direction: `down` (triggered when price <= `stopPrice`), `up` (triggered when price >= `stopPrice`)                                             |
| stopPriceType | ENUM    | NO       | Stop trigger price type: `TP` (trade price), `MP` (mark price), `IP` (index price). Required when using a stop.                                      |
| stopPrice     | STRING  | NO       | Stop trigger price. Required when using a stop.                                                                                                      |
| reduceOnly    | BOOLEAN | NO       | Order can only reduce, never increase, the current position. Default `false`.                                                                        |
| closeOrder    | BOOLEAN | NO       | Close the current position to zero. Default `false`.                                                                                                 |
| forceHold     | BOOLEAN | NO       | Force-freeze margin for the order (intended for API users). Default `false`.                                                                         |
| stp           | ENUM    | NO       | Self-trade prevention: `CN` (cancel new), `CO` (cancel old), `CB` (cancel both)                                                                      |
| price         | STRING  | NO       | Order price; required for limit orders.                                                                                                              |
| size          | STRING  | NO       | Order size (in base contract units). Provide one of `size` or `valueQty`.                                                                            |
| valueQty      | STRING  | NO       | Order size as quote-currency notional (USDC). Provide one of `size` or `valueQty`.                                                                   |
| timeInForce   | ENUM    | NO       | Time in force: `GTC` (good-till-cancel), `IOC` (immediate-or-cancel), `POST_ONLY` (maker only). Default `GTC`.                                       |

#### Response Example

```json
{
  "code": "0",
  "data": {
    "orderId": "234125150956625920",
    "clientOid": "5c52e11203aa677f33e493fb"
  }
}
```

#### Response Fields

| Name      | Type   | Description          |
| --------- | ------ | -------------------- |
| orderId   | STRING | Server-side order ID |
| clientOid | STRING | Client order ID      |

### Place Batch Orders

**`POST`** `/api/v1/batch-orders` · Auth `USER_DATA` · Weight `20`

#### Request Body

The request body is an array of order parameters; each element has the same shape as the body of Place Order. Up to 10 orders per request.

#### Response Example

```json
{
  "code": "0",
  "data": [
    {
      "orderId": "234125150956625920",
      "clientOid": "5c52e11203aa677f33e493fb",
      "symbol": "BTCUSDC",
      "code": "0",
      "msg": "success"
    },
    {
      "orderId": "234125150956625921",
      "clientOid": "6d63f22314bb788g44f504gc",
      "symbol": "BTCUSDC",
      "code": "0",
      "msg": "success"
    }
  ]
}
```

#### Response Fields

| Name      | Type   | Description                                      |
| --------- | ------ | ------------------------------------------------ |
| orderId   | STRING | Server-side order ID (`null` if creation failed) |
| clientOid | STRING | Client order ID                                  |
| symbol    | STRING | Contract symbol                                  |
| code      | STRING | Per-order result code; `0` indicates success     |
| msg       | STRING | Per-order result message                         |

### Cancel Order

Cancel a single order by `orderId` or `clientOid`. Exactly one of the two ID parameters must be provided. If both are given, `orderId` takes precedence.**`DELETE`** `/api/v1/order` · Auth `USER_DATA` · Weight `1`

#### Request Parameters

| Name      | Type   | Required    | Description                                                                                     |
| --------- | ------ | ----------- | ----------------------------------------------------------------------------------------------- |
| orderId   | STRING | Conditional | Order ID. Required if `clientOid` is not provided.                                              |
| clientOid | STRING | Conditional | Client order ID. Required if `orderId` is not provided.                                         |
| symbol    | STRING | Conditional | Contract symbol. Required when cancelling by `clientOid`; ignored when cancelling by `orderId`. |

#### Response Example

```json
{
  "code": "0",
  "data": {
    "cancelledOrderIds": [
      "235303670076489728"
    ],
    "clientOid": null
  }
}
```

#### Response Fields

| Name              | Type           | Description                                                                           |
| ----------------- | -------------- | ------------------------------------------------------------------------------------- |
| cancelledOrderIds | `LIST<STRING>` | Cancelled order IDs. Populated when cancelled by `orderId`.                           |
| clientOid         | STRING         | Client order ID echo. Populated only when cancelled by `clientOid`; `null` otherwise. |

### Cancel All Orders by Symbol

Cancels every active order on the specified contract.**`DELETE`** `/api/v1/open-orders` · Auth `USER_DATA` · Weight `20`

#### Request Parameters

| Name   | Type   | Required | Description     |
| ------ | ------ | -------- | --------------- |
| symbol | STRING | YES      | Contract symbol |

#### Response Example

```json
{
  "code": "0",
  "data": {
    "cancelledOrderIds": [
      "235303670076489728",
      "235303670076489729"
    ]
  }
}
```

#### Response Fields

| Name              | Type           | Description          |
| ----------------- | -------------- | -------------------- |
| cancelledOrderIds | `LIST<STRING>` | Cancelled order IDs. |

### Batch Cancel Orders

**`DELETE`** `/api/v1/batch-orders` · Auth `USER_DATA` · Weight `20`

#### Request Parameters

| Name           | Type           | Required | Description                                                                           |
| -------------- | -------------- | -------- | ------------------------------------------------------------------------------------- |
| orderIdsList   | `LIST<STRING>` | NO       | List of order IDs; up to 10 entries                                                   |
| clientOidsList | `LIST<OBJECT>` | NO       | List of clientOids; up to 10 entries; each item must include `symbol` and `clientOid` |

Exactly one of `orderIdsList` and `clientOidsList` must be provided.

#### Response Example

```json
{
  "code": "0",
  "data": [
    {
      "orderId": "235303670076489728",
      "clientOid": null,
      "code": "0",
      "msg": "success"
    },
    {
      "orderId": null,
      "clientOid": "017485b0-2957-4681-8a14-5d46b35aee0d",
      "code": "0",
      "msg": "success"
    }
  ]
}
```

#### Response Fields

| Name      | Type   | Description                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------- |
| orderId   | STRING | Order ID (populated when cancelling by `orderId`, otherwise `null`)          |
| clientOid | STRING | Client order ID (populated when cancelling by `clientOid`, otherwise `null`) |
| code      | STRING | Per-order cancellation result code                                           |
| msg       | STRING | Per-order cancellation result message                                        |

### Cancel All Stop Orders

Cancels every active stop order on the specified contract.**`DELETE`** `/api/v1/batch-stop-orders` · Auth `USER_DATA` · Weight `15`

#### Request Parameters

| Name   | Type   | Required | Description     |
| ------ | ------ | -------- | --------------- |
| symbol | STRING | YES      | Contract symbol |

#### Response Example

```json
{
  "code": "0",
  "data": {
    "cancelledOrderIds": [
      "235303670076489730"
    ]
  }
}
```

#### Response Fields

Same as Cancel All Orders.

### Get Order Detail

**`GET`** `/api/v1/order/detail` · Auth `USER_DATA` · Weight `5`

#### Request Parameters

| Name      | Type   | Required | Description                                               |
| --------- | ------ | -------- | --------------------------------------------------------- |
| orderId   | STRING | NO       | Order ID. Provide one of `orderId` or `clientOid`.        |
| clientOid | STRING | NO       | Client order ID. Provide one of `orderId` or `clientOid`. |

#### Response Example

```json
{
  "code": "0",
  "data": {
    "id": "236655147005071361",
    "symbol": "BTCUSDC",
    "type": "limit",
    "side": "buy",
    "price": "60000",
    "size": "0.001",
    "value": "60",
    "filledValue": "0",
    "filledSize": "0",
    "stp": "",
    "stop": "",
    "stopPriceType": "",
    "stopTriggered": false,
    "stopPrice": null,
    "timeInForce": "GTC",
    "postOnly": false,
    "leverage": "3",
    "forceHold": false,
    "closeOrder": false,
    "clientOid": "5c52e11203aa677f33e493fb",
    "remark": null,
    "tags": "",
    "isActive": true,
    "cancelExist": false,
    "createdAt": 1729236185949,
    "updatedAt": 1729236185949,
    "endAt": null,
    "orderTime": 1729236185885648000,
    "settleCurrency": "USDC",
    "avgFillPrice": "0",
    "status": "open",
    "reduceOnly": false
  }
}
```

#### Response Fields

| Name           | Type    | Description                                           |
| -------------- | ------- | ----------------------------------------------------- |
| id             | STRING  | Order ID                                              |
| symbol         | STRING  | Contract symbol                                       |
| type           | STRING  | Order type: `limit` / `market`                        |
| side           | STRING  | Order side: `buy` / `sell`                            |
| price          | STRING  | Order price                                           |
| size           | STRING  | Order size (base units)                               |
| value          | STRING  | Order notional value                                  |
| filledValue    | STRING  | Filled notional value                                 |
| filledSize     | STRING  | Filled size (base units)                              |
| stp            | STRING  | Self-trade prevention: `CN` / `CO` / `CB`             |
| stop           | STRING  | Stop direction: `up` / `down`                         |
| stopPriceType  | STRING  | Stop price type: `TP` / `MP` / `IP`                   |
| stopTriggered  | BOOLEAN | Whether the stop has been triggered                   |
| stopPrice      | STRING  | Stop trigger price                                    |
| timeInForce    | STRING  | Time-in-force value                                   |
| postOnly       | BOOLEAN | Whether this is a post-only order                     |
| leverage       | STRING  | Leverage                                              |
| forceHold      | BOOLEAN | Whether margin is force-frozen                        |
| closeOrder     | BOOLEAN | Whether this is a close-position order                |
| clientOid      | STRING  | Client order ID                                       |
| remark         | STRING  | Order remark                                          |
| tags           | STRING  | Order tags                                            |
| isActive       | BOOLEAN | Whether the order is still active                     |
| cancelExist    | BOOLEAN | Whether a cancellation exists for this order          |
| createdAt      | LONG    | Creation time (ms)                                    |
| updatedAt      | LONG    | Last update time (ms)                                 |
| endAt          | LONG    | End time (ms); `null` while the order is still active |
| orderTime      | LONG    | Order placement time (nanoseconds)                    |
| settleCurrency | STRING  | Settlement currency                                   |
| avgFillPrice   | STRING  | Average fill price                                    |
| status         | STRING  | Order status: `open` / `done`                         |
| reduceOnly     | BOOLEAN | Whether this is a reduce-only order                   |

### Get Order List

**`GET`** `/api/v1/orders` · Auth `USER_DATA` · Weight `2`

#### Request Parameters

| Name        | Type    | Required | Description                                                          |
| ----------- | ------- | -------- | -------------------------------------------------------------------- |
| status      | ENUM    | NO       | Order status; default `done`. `active` (open) or `done` (completed). |
| symbol      | STRING  | NO       | Contract symbol                                                      |
| side        | ENUM    | NO       | Order side: `buy`, `sell`                                            |
| type        | ENUM    | NO       | Order type: `limit`, `market`                                        |
| tags        | STRING  | NO       | Order tag, up to 20 characters                                       |
| startAt     | LONG    | NO       | Start time (ms)                                                      |
| endAt       | LONG    | NO       | End time (ms)                                                        |
| currentPage | INTEGER | NO       | Current page; default 1                                              |
| pageSize    | INTEGER | NO       | Page size; default 50, max 1000                                      |

#### Response Example

```json
{
  "code": "0",
  "data": {
    "currentPage": 1,
    "pageSize": 50,
    "totalNum": 1,
    "totalPage": 1,
    "items": [
      {
        "id": "230181737576050688",
        "symbol": "BTCUSDC",
        "type": "limit",
        "side": "buy",
        "price": "60000",
        "size": "0.01",
        "value": "600",
        "filledValue": "0",
        "filledSize": "0",
        "stp": "",
        "stop": "",
        "stopPriceType": "",
        "stopTriggered": false,
        "stopPrice": null,
        "timeInForce": "GTC",
        "postOnly": false,
        "leverage": "1",
        "forceHold": false,
        "closeOrder": false,
        "clientOid": "5a80bd847f1811ef8a7faa665a37b3d7",
        "remark": null,
        "tags": "",
        "isActive": true,
        "cancelExist": false,
        "createdAt": 1727692804813,
        "updatedAt": 1727692804813,
        "endAt": null,
        "orderTime": 1727692804808418000,
        "settleCurrency": "USDC",
        "avgFillPrice": "0",
        "status": "open",
        "reduceOnly": false
      }
    ]
  }
}
```

#### Response Fields

Paginated response with `currentPage` / `pageSize` / `totalNum` / `totalPage` / `items[]`. Each entry in `items[]` uses the same fields as Get Order Detail.

### Get Stop Order List

**`GET`** `/api/v1/stop-orders` · Auth `USER_DATA` · Weight `6`

#### Request Parameters

| Name        | Type    | Required | Description                     |
| ----------- | ------- | -------- | ------------------------------- |
| symbol      | STRING  | NO       | Contract symbol                 |
| side        | ENUM    | NO       | Order side: `buy`, `sell`       |
| type        | ENUM    | NO       | Order type: `limit`, `market`   |
| start       | LONG    | NO       | Start time (ms)                 |
| end         | LONG    | NO       | End time (ms)                   |
| currentPage | INTEGER | NO       | Current page; default 1         |
| pageSize    | INTEGER | NO       | Page size; default 50, max 1000 |

#### Response Example

```json
{
  "code": "0",
  "data": {
    "currentPage": 1,
    "pageSize": 50,
    "totalNum": 1,
    "totalPage": 1,
    "items": [
      {
        "id": "230181737576050690",
        "symbol": "BTCUSDC",
        "type": "limit",
        "side": "buy",
        "price": "60000",
        "size": "0.001",
        "stop": "down",
        "stopPriceType": "MP",
        "stopPrice": "62000",
        "stopTriggered": false,
        "timeInForce": "GTC",
        "leverage": "3",
        "clientOid": "abc123",
        "isActive": true,
        "createdAt": 1727692804813,
        "settleCurrency": "USDC",
        "status": "open"
      }
    ]
  }
}
```

#### Response Fields

Paginated response with `currentPage` / `pageSize` / `totalNum` / `totalPage` / `items[]`. Each entry in `items[]` uses the same fields as Get Order Detail. Stop orders typically also include the stop-specific fields: `stop` / `stopPriceType` / `stopPrice` / `stopTriggered`.

### Get Trading Fee Rate

**`GET`** `/api/v1/trade/trade-fee` · Auth `USER_DATA` · Weight `3`

#### Request Parameters

| Name   | Type   | Required | Description     |
| ------ | ------ | -------- | --------------- |
| symbol | STRING | YES      | Contract symbol |

#### Response Example

```json
{
  "code": "0",
  "data": {
    "symbol": "BTCUSDC",
    "takerFeeRate": "0.0006",
    "makerFeeRate": "0.00025"
  }
}
```

#### Response Fields

| Name         | Type   | Description     |
| ------------ | ------ | --------------- |
| symbol       | STRING | Contract symbol |
| takerFeeRate | STRING | Taker fee rate  |
| makerFeeRate | STRING | Maker fee rate  |

### Get Max Open Size

**`GET`** `/api/v1/trade/max-open-size` · Auth `USER_DATA` · Weight `2`

#### Request Parameters

| Name   | Type    | Required | Description     |
| ------ | ------- | -------- | --------------- |
| symbol | STRING  | YES      | Contract symbol |
| price  | DECIMAL | YES      | Order price     |

#### Response Example

```json
{
  "code": "0",
  "data": {
    "symbol": "BTCUSDC",
    "maxBuyOpenSize": "1.23",
    "maxSellOpenSize": "1.22"
  }
}
```

#### Response Fields

| Name            | Type   | Description                         |
| --------------- | ------ | ----------------------------------- |
| symbol          | STRING | Contract symbol                     |
| maxBuyOpenSize  | STRING | Maximum open-buy size (base units)  |
| maxSellOpenSize | STRING | Maximum open-sell size (base units) |

### Get Order Limits

Returns the maximum leverage and margin ratios available under cross-margin mode for the specified contract.**`GET`** `/api/v1/trade/risklimit` · Auth `USER_DATA` · Weight `2`

#### Request Parameters

| Name   | Type   | Required | Description     |
| ------ | ------ | -------- | --------------- |
| symbol | STRING | YES      | Contract symbol |

#### Response Example

```json
{
  "code": "0",
  "data": {
    "symbol": "BTCUSDC",
    "leverage": "100",
    "imr": "0.1",
    "mmr": "0.005"
  }
}
```

#### Response Fields

| Name     | Type    | Description              |
| -------- | ------- | ------------------------ |
| symbol   | STRING  | Contract symbol          |
| leverage | STRING  | Max leverage             |
| imr      | DECIMAL | Initial margin ratio     |
| mmr      | DECIMAL | Maintenance margin ratio |

### Get Trade History (Fills)

**`GET`** `/api/v1/trade/fills` · Auth `USER_DATA` · Weight `5`

#### Request Parameters

| Name        | Type    | Required | Description                                                                                                                |
| ----------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| orderId     | STRING  | NO       | Order ID; when specified, other filters may be omitted                                                                     |
| symbol      | STRING  | NO       | Contract symbol                                                                                                            |
| side        | ENUM    | NO       | Order side: `buy`, `sell`                                                                                                  |
| type        | ENUM    | NO       | Order type: `limit`, `market`, `limit_stop`, `market_stop`                                                                 |
| tags        | STRING  | NO       | Order tag                                                                                                                  |
| tradeTypes  | STRING  | NO       | Trade type filter; comma-separated. If empty, returns all types. Allowed: `trade`, `adl`, `liquid`, `settlement`, `cancel` |
| startAt     | LONG    | NO       | Start time (ms)                                                                                                            |
| endAt       | LONG    | NO       | End time (ms)                                                                                                              |
| currentPage | INTEGER | NO       | Current page; default 1                                                                                                    |
| pageSize    | INTEGER | NO       | Page size; default 50, max 1000                                                                                            |

#### Response Example

```json
{
  "code": "0",
  "data": {
    "currentPage": 1,
    "pageSize": 50,
    "totalNum": 1,
    "totalPage": 1,
    "items": [
      {
        "symbol": "BTCUSDC",
        "tradeId": "1828954878212",
        "orderId": "284486580251463680",
        "side": "buy",
        "liquidity": "taker",
        "forceTaker": false,
        "price": "86275.1",
        "size": "0.001",
        "value": "86.2751",
        "openFeePay": "0.05176506",
        "closeFeePay": "0",
        "stop": "",
        "feeRate": "0.00060",
        "feeCurrency": "USDC",
        "displayType": "market",
        "fee": "0.05176506",
        "settleCurrency": "USDC",
        "orderType": "market",
        "tradeType": "trade",
        "tradeTime": 1740640088244000000,
        "createdAt": 1740640088427
      }
    ]
  }
}
```

#### Response Fields

Paginated response with `currentPage` / `pageSize` / `totalNum` / `totalPage` / `items[]`. Each entry in `items[]`:

| Name           | Type    | Description                                                      |
| -------------- | ------- | ---------------------------------------------------------------- |
| symbol         | STRING  | Contract symbol                                                  |
| tradeId        | STRING  | Trade ID                                                         |
| orderId        | STRING  | Associated order ID (`null` for non-`trade` records)             |
| side           | STRING  | Trade side: `buy` / `sell`                                       |
| liquidity      | STRING  | Liquidity role: `maker` / `taker`                                |
| forceTaker     | BOOLEAN | Whether this was a forced taker                                  |
| price          | STRING  | Fill price                                                       |
| size           | STRING  | Fill size (base units)                                           |
| value          | STRING  | Fill notional value                                              |
| openFeePay     | STRING  | Open-side fee paid                                               |
| closeFeePay    | STRING  | Close-side fee paid                                              |
| stop           | STRING  | Stop direction                                                   |
| feeRate        | STRING  | Fee rate applied                                                 |
| feeCurrency    | STRING  | Fee currency                                                     |
| displayType    | STRING  | Display type (includes stops: `limit_stop` / `market_stop`)      |
| fee            | STRING  | Total fee (= `openFeePay` + `closeFeePay`)                       |
| settleCurrency | STRING  | Settlement currency (same as `feeCurrency`)                      |
| orderType      | STRING  | Order type: `limit` / `market`                                   |
| tradeType      | STRING  | Trade type: `trade` / `adl` / `liquid` / `settlement` / `cancel` |
| tradeTime      | LONG    | Trade time (nanoseconds)                                         |
| createdAt      | LONG    | Record creation time (ms)                                        |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kryptox.finance/api/trading-endpoints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.