Skip to contents

Add Stop Order (Implementation)

Source: R/impl_spottrading_orders_stop.R
add_stop_order_impl.Rd

Places a stop order (limit or market) on the KuCoin Spot trading system asynchronously. This function constructs a JSON request body, sends it to the KuCoin API, and returns a data.table containing the resulting order ID and client order ID.

Usage

add_stop_order_impl(
  keys = get_api_keys(),
  base_url = get_base_url(),
  type,
  symbol,
  side,
  stopPrice,
  clientOid = NULL,
  price = NULL,
  size = NULL,
  funds = NULL,
  stp = NULL,
  remark = NULL,
  timeInForce = NULL,
  cancelAfter = NULL,
  postOnly = NULL,
  hidden = NULL,
  iceberg = NULL,
  visibleSize = NULL,
  tradeType = "TRADE",
  .__coro_env_parent__ = <environment>
)

Arguments

keys

List; API configuration parameters from get_api_keys(). Defaults to get_api_keys().

base_url

Character string; base URL for the KuCoin API. Defaults to get_base_url().

type

Character string; order type: "limit" or "market". Required.

symbol

Character string; trading pair symbol (e.g., "BTC-USDT"). Required.

side

Character string; order side: "buy" or "sell". Required.

stopPrice

Character string; trigger price for the stop order. Required.

clientOid

Character string; unique client order ID (max 40 characters). Optional.

price

Character string; price for limit orders. Required for limit orders.

size

Character string; quantity for the order. Required for limit orders, optional for market orders.

funds

Character string; funds for market orders. Optional for market orders.

stp

Character string; self-trade prevention: "DC", "CO", "CN", "CB". Optional.

remark

Character string; order remarks (max 20 characters). Optional.

timeInForce

Character string; time in force: "GTC", "GTT", "IOC", "FOK". Optional, defaults to "GTC".

cancelAfter

Integer; cancel after n seconds for GTT. Optional.

postOnly

Logical; post-only flag. Optional, defaults to FALSE.

hidden

Logical; hidden order flag. Optional, defaults to FALSE.

iceberg

Logical; iceberg order flag. Optional, defaults to FALSE.

visibleSize

Character string; visible size for iceberg orders. Optional.

tradeType

Character string; trade type (e.g., "TRADE"). Optional, defaults to "TRADE".

Value

Promise resolving to a data.table with:

  • orderId (character): Unique order ID generated by the system.

  • clientOid (character): Client-assigned order ID.

Details

Description

This endpoint allows users to place a stop order on the KuCoin Spot trading system, which triggers when the market price reaches the specified stopPrice. Two types of stop orders are supported:

  • Limit Stop Order: Executes at a specified price once triggered, requiring both price and size.

  • Market Stop Order: Executes as a market order once triggered, requiring either size or funds.

The maximum number of untriggered stop orders per trading pair in one account is 20. The function validates parameters based on the order type and ensures compliance with KuCoin API constraints.

Workflow

  1. Parameter Validation: Ensures required fields (type, symbol, side, stopPrice) are valid, and type-specific fields (price, size, funds) meet requirements.

  2. Request Construction: Builds a JSON body with required and optional parameters.

  3. Authentication: Generates private API headers using build_headers() with the POST method, endpoint, and request body.

  4. API Request: Sends a POST request to the KuCoin API with a 3-second timeout.

  5. Response Processing: Parses the response, validates success, and returns a data.table with orderId and clientOid.

API Details

  • Endpoint: POST https://api.kucoin.com/api/v1/stop-order

  • Domain: Spot

  • API Channel: Private

  • API Permission: Spot

  • Rate Limit Pool: Spot

  • Rate Limit Weight: 1

  • SDK Service: Spot

  • SDK Sub-Service: Order

  • SDK Method Name: addStopOrder

  • Official Documentation: KuCoin Add Stop Order

Request

Body Parameters (application/json)

  • type: Enum (required) - Order type: "limit" or "market".

  • symbol: String (required) - Trading pair symbol (e.g., "BTC-USDT").

  • side: Enum (required) - Order side: "buy" or "sell".

  • clientOid: String (optional) - Unique client order ID (max 40 characters, alphanumeric, underscores, or hyphens).

  • price: String (optional) - Order price (required for limit orders).

  • size: String (optional) - Order quantity (required for limit orders, optional for market orders if funds not provided).

  • funds: String (optional) - Funds for market orders (optional if size provided).

  • stp: Enum (optional) - Self Trade Prevention: "DC", "CO", "CN", "CB".

  • stopPrice: String (required) - Trigger price for the stop order.

  • remark: String (optional) - Order remarks (max 20 characters).

  • timeInForce: Enum (optional) - Time in force: "GTC", "GTT", "IOC", "FOK" (required for limit orders).

  • cancelAfter: Integer (optional) - Cancel after n seconds (for GTT).

  • postOnly: Boolean (optional) - Post-only flag.

  • hidden: Boolean (optional) - Hidden order flag.

  • iceberg: Boolean (optional) - Iceberg order flag.

  • visibleSize: String (optional) - Visible size for iceberg orders.

  • tradeType: String (optional) - Trade type (default "TRADE").

Example Request

curl --location --request POST 'https://api.kucoin.com/api/v1/stop-order' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "limit",
    "symbol": "BTC-USDT",
    "side": "buy",
    "price": "50000",
    "size": "0.00001",
    "stopPrice": "49000",
    "clientOid": "5c52e11203aa677f33e493fb",
    "remark": "order remarks"
}'

Response

HTTP Code: 200

  • Content Type: application/json

Data Schema

  • code: String (required) - Response code ("200000" indicates success).

  • data: Object (required) - Contains:

    • orderId: String (required) - Unique order ID generated by the system.

    • clientOid: String (required) - Client-assigned order ID from the request.

JSON Response Example

{
  "code": "200000",
  "data": {
    "orderId": "670fd33bf9406e0007ab3945",
    "clientOid": "5c52e11203aa677f33e493fb"
  }
}

Examples

if (FALSE) { # \dontrun{
library(coro)
library(data.table)

main_async <- coro::async(function() {
  # Place a limit stop order
  result <- await(add_stop_order_impl(
    type = "limit",
    symbol = "BTC-USDT",
    side = "buy",
    stopPrice = "49000",
    price = "50000",
    size = "0.00001",
    clientOid = "5c52e11203aa677f33e493fb",
    remark = "order remarks"
  ))
  print(result)

  # Place a market stop order with size
  result <- await(add_stop_order_impl(
    type = "market",
    symbol = "BTC-USDT",
    side = "buy",
    stopPrice = "49000",
    size = "0.00001",
    clientOid = "5c52e11203aa677f33e493fc"
  ))
  print(result)

  # Place a market stop order with funds
  result <- await(add_stop_order_impl(
    type = "market",
    symbol = "BTC-USDT",
    side = "buy",
    stopPrice = "49000",
    funds = "1",
    clientOid = "5c52e11203aa677f33e493fd"
  ))
  print(result)
})

# Run the async function
main_async()
while (!later::loop_empty()) later::run_now()
} # }