# Add Order Test ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /api/v1/hf/orders/test: post: summary: Add Order Test deprecated: false description: > :::info[Description] Order test endpoint, the request parameters and return parameters of this endpoint are exactly the same as the order endpoint, and can be used to verify whether the signature is correct and other operations. After placing an order, the order will not enter the matching system, and the order cannot be queried. ::: :::tip[Tips] Please note that once your order enters the order book, the system will freeze the handling fees for the order ahead of time. Before placing orders, please be sure to fully understand the meaning of the parameters for each trading pair. ::: :::tip[Tips] The maximum number of active orders per account is 2000, with a maximum of 200 active orders per trading pair. ::: **Public order placement request parameters** | Param | Type | Mandatory | Description | | --------- | ------ | --------- | ----------- | | clientOid | String | No | Client Order Id，unique identifier created by the user, the use of UUID is recommended | | symbol | String | Yes | symbol | | type | String | Yes | Order type `limit` and `market` | | side | String | Yes | `buy` or `sell` | | stp | String | No | self trade prevention is divided into four strategies: `CN`, `CO`, `CB` , and `DC` | | tags | String | No | Order tag, length cannot exceed `20` characters (ASCII) | | remark | String | No | Order placement remarks, length cannot exceed `20` characters (ASCII) | **Additional Request Parameters Required by `limit` Orders** | Param | Type | Mandatory | Description | | ----------- | ------- | --------- | ----------- | | price | String | Yes | Specify price for currency | | size | String | Yes | Specify quantity for currency | | timeInForce | String | No | Order timing strategy `GTC`, `GTT`, `IOC`, `FOK` (The default is `GTC`) | | cancelAfter | long | No | Cancel after `n` seconds，the order timing strategy is `GTT` | | postOnly | boolean | No | passive order labels, this is disabled when the order timing strategy is `IOC` or `FOK` | | hidden | boolean | No | Hidden or not (not shown in order book) | | iceberg | boolean | No | Whether or not only visible portions of orders are shown in iceberg orders | | visibleSize | String | No | Maximum visible quantity in iceberg orders | **Additional request parameters required by `market` orders** | Param | Type | Mandatory | Description | | ----- | ------ | --------- | ------------------------------------------ | | size | String | No | (Select one out of two: `size` or `funds`) | | funds | String | No | (Select one out of two: `size` or `funds`) | **Hold** For limit price purchase orders, we will hold the amount of funds (price * size) required for your purchase order. Similarly, for limit price sell orders, we will also hold you sell order assets. When the transaction is executed, the service fees will be calculated. If you cancel a portion of a filled or unfilled order, then the remaining funds or amounts will be released and returned to your account. For market price buy/sell orders that require specific funds, we will hold the required funds in from your account. If only the size is specified, we may freeze (usually for a very short amount of time) all of the funds in your account prior to the order being filled or cancelled. **Order Lifecycle** When an order placement request is successful (the matching engine receives the order) or denied (due to there being insufficient funds or illegal parameter values, etc.), the system will respond to the HTTP request. When an order is successfully placed, the order ID is returned. The order will be matched, which could result in it being fully or partially filled. When an order is fully or partially filled, the remaining portions of the order will be in an active state awaiting to be matched (this does not include IOC orders). Orders that are fully or partially filled(already cancelled) will be put into the “done” state. Users that have subscribed to the Market Data Channel can use the order ID （orderId） and client ID （clientOid） to identify messages. **Price Protection Mechanisms** Price protection mechanisms ae enabled for order placements. Rules are detailed below: - If the spot trading market order/limit order placed by the user can be directly matched with an order in the current order book, the system will judge whether deviation between the price corresponding to the transaction depth and the spread exceeds the threshold value （the threshold value can be obtained using the symbol API endpoint）； - If it is exceeded, for limit orders, the order will be directly cancelled; - If it is a market order, then the system will partially execute the order. The execution limit will be the order size within the price range corresponding to the threshold value. The remaining orders will not be filled. For example: if the threshold value is 10%, when a user places a market price purchase order in the KCS/USDT trading market for 10,000 USDT (the selling price is currently 1.20000), the system will determine that after the order is completely filled, the final price will be 1.40000. (1.40000-1.20000)/1.20000=16.7%>10%. The threshold value is 1.32000. The user’s market price purchase order will be filled only to a maximum of 1.32000. The remaining order portions will not be matched with orders in the order book. Note: this feature may not be able to determine depth with complete accuracy. If your order is not completely filled, it may be because the portion exceeding the threshold value was not filled. tags: - Classic REST/Spot Trading/Orders - MAIN - TH - TR - AU - ALL parameters: [] requestBody: content: application/json: schema: type: object properties: clientOid: type: string description: >- Client Order Id，The ClientOid field is a unique ID created by the user（we recommend using a UUID）, and can only contain numbers, letters, underscores （_）, and hyphens （-）. This field is returned when order information is obtained. You can use clientOid to tag your orders. ClientOid is different from the order ID created by the service provider. Please do not initiate requests using the same clientOid. The maximum length for the ClientOid is 40 characters. Please remember the orderId created by the service provider, it used to check for updates in order status. examples: - 5c52e11203aa677f33e493fb side: type: string description: specify if the order is to 'buy' or 'sell' enum: - buy - sell x-apidog-enum: - value: buy name: buy description: buy - value: sell name: sell description: sell examples: - buy symbol: type: string description: symbol examples: - BTC-USDT - ETH-USDT - KCS-USDT type: type: string description: >- specify if the order is an 'limit' order or 'market' order. The type of order you specify when you place your order determines whether or not you need to request other parameters and also affects the execution of the matching engine. When placing a limit order, you must specify a price and size. The system will try to match the order according to market price or a price better than market price. If the order cannot be immediately matched, it will stay in the order book until it is matched or the user cancels. Unlike limit orders, the price for market orders fluctuates with market prices. When placing a market order, you do not need to specify a price, you only need to specify a quantity. Market orders are filled immediately and will not enter the order book. All market orders are takers and a taker fee will be charged. enum: - limit - market x-apidog-enum: - value: limit name: limit description: limit order - value: market name: market description: market order examples: - limit remark: type: string description: >- Order placement remarks, length cannot exceed 20 characters (ASCII) stp: type: string description: >- [Self Trade Prevention](https://www.kucoin.com/docs-new/enums-definitions.md) is divided into four strategies: CN, CO, CB, and DC. enum: - DC - CO - CN - CB x-apidog-enum: - value: DC name: Decrease and Cancel description: >- Cancel the order with the smaller size and reduce the order with the larger size by the matched quantity (i.e., adjust it to the remaining difference). - value: CO name: Cancel Old description: >- Cancel the existing (older) resting order when a new incoming order from the same user would match it. - value: CN name: Cancel New description: >- Cancel the new incoming order if it would match against an existing (older) order from the same user. - value: CB name: Cancel Both description: >- Cancel both the existing (older) order and the new incoming order upon potential self-match. price: type: string description: >- Specify price for order When placing a limit order, the price must be based on priceIncrement for the trading pair. The price increment (priceIncrement) is the price precision for the trading pair. For example, for the BTC-USDT trading pair, the priceIncrement is 0.00001000. So the price for your orders cannot be less than 0.00001000 and must be a multiple of priceIncrement. Otherwise, the order will return an invalid priceIncrement error. size: type: string description: >- Specify quantity for order When **type** is limit, size refers to the amount of trading targets (the asset name written in front) for the trading pair. Teh Size must be based on the baseIncrement of the trading pair. The baseIncrement represents the precision for the trading pair. The size of an order must be a positive-integer multiple of baseIncrement and must be between baseMinSize and baseMaxSize. When **type** is market, select one out of two: size or funds timeInForce: type: string description: >- [Time in Force](https://www.kucoin.com/docs-new/enums-definitions.md) is a special strategy used during trading to specify how long an order remains active before execution or expiration. **Market orders are not supported**. Order fills include self-fills. Default is `GTC`. enum: - GTC - GTT - IOC - FOK x-apidog-enum: - value: GTC name: Good Till Canceled description: >- The order remains active on the order book until it is fully filled or manually canceled by the user. - value: GTT name: Good Till Time description: >- The order remains active until a specified expiration time (provided via `expire` parameter in milliseconds). If not filled by then, it is automatically canceled. - value: IOC name: Immediate Or Cancel description: >- Execute as much of the order as possible immediately at the current market price. Any unfilled portion is canceled immediately. The order does **not** enter the order book. - value: FOK name: Fill Or Kill description: >- The entire order must be filled immediately and completely at the limit price or better. If full execution is not possible right away, the entire order is canceled. default: GTC postOnly: type: boolean default: false description: >- passive order labels, this is disabled when the order timing strategy is IOC or FOK hidden: type: boolean description: >- [Hidden order](https://www.kucoin.com/docs-new/enums-definitions.md) or not (not shown in order book) default: false iceberg: type: boolean description: >- Whether or not only visible portions of orders are shown in [Iceberg orders](https://www.kucoin.com/docs-new/enums-definitions.md) default: false visibleSize: type: string description: Maximum visible quantity in iceberg orders tags: type: string description: Order tag, length cannot exceed 20 characters (ASCII) cancelAfter: type: integer description: > Cancel after n seconds, the order timing strategy is GTT, -1 means it will not be cancelled automatically, the default value is -1 format: int64 default: -1 minimum: 0 exclusiveMinimum: true maximum: 2592000 exclusiveMaximum: true funds: type: string description: >- When **type** is market, select one out of two: size or funds allowMaxTimeWindow: type: integer description: >- Order failed after timeout of specified milliseconds, If clientTimestamp + allowMaxTimeWindow < Gateway received the message time, this order will fail. format: int64 examples: - 10 - 20 - 30 clientTimestamp: type: integer description: >- Equal to KC-API-TIMESTAMP, Need to be defined if allowMaxTimeWindow is specified. format: int64 examples: - 1740711735178 x-apidog-orders: - type - symbol - side - clientOid - price - stp - tags - remark - timeInForce - cancelAfter - postOnly - hidden - iceberg - visibleSize - size - funds - allowMaxTimeWindow - clientTimestamp required: - symbol - type - side example: | //limit order { "type": "limit", "symbol": "BTC-USDT", "side": "buy", "price": "50000", "size": "0.00001", "clientOid": "5c52e11203aa677f33e493f", "remark": "order remarks" } //market order 1 // { // "type": "market", // "symbol": "BTC-USDT", // "side": "buy", // "size": "0.00001", // "clientOid": "5c52e11203aa677f33e493fc", // "remark": "order remarks", // } //market order 2 // { // "type": "market", // "symbol": "BTC-USDT", // "side": "buy", // "funds": "1", // "clientOid": "5c52e11203aa677f33e493fc", // "remark": "order remarks", // } responses: '200': description: '' content: application/json: schema: type: object properties: code: type: string data: type: object properties: orderId: type: string description: >- The unique order id generated by the trading system,which can be used later for further actions such as canceling the order. clientOid: type: string description: The user self-defined order id. required: - orderId - clientOid x-apidog-orders: - orderId - clientOid required: - code - data x-apidog-orders: - code - data example: code: '200000' data: orderId: 670fd33bf9406e0007ab3945 clientOid: 5c52e11203aa677f33e493fb headers: {} x-apidog-name: OK security: [] x-abandon: normal x-domain: Spot x-api-channel: Private x-api-permission: Spot x-api-rate-limit-pool: Spot x-sdk-service: Spot x-sdk-sub-service: Order x-sdk-method-name: addOrderTest x-sdk-method-description: >- Order test endpoint, the request parameters and return parameters of this endpoint are exactly the same as the order endpoint, and can be used to verify whether the signature is correct and other operations. After placing an order, the order will not enter the matching system, and the order cannot be queried. x-api-rate-limit-weight: 1 x-apidog-folder: Classic REST/Spot Trading/Orders x-apidog-status: released x-run-in-apidog: https://www.kucoin.com/docs-new/web/project/345089/apis/api-3470187-run components: schemas: {} securitySchemes: {} servers: - url: https://api.kucoin.com description: OPEN security: [] ```