Skip to contents

Add OCO Order (Implementation)

Source: R/impl_spottrading_orders_oco.R
add_oco_order_impl.Rd

Places an OCO (One-Cancels-the-Other) order on the KuCoin Spot trading system asynchronously by sending a POST request to the /api/v3/oco/order endpoint. An OCO order combines a limit order and a stop-limit order, where executing one cancels the other, returning a data.table with the order ID.

Usage

add_oco_order_impl(
  keys = get_api_keys(),
  base_url = get_base_url(),
  symbol,
  side,
  price,
  size,
  clientOid,
  stopPrice,
  limitPrice,
  remark = 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().

symbol

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

side

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

price

Character string; limit order price (e.g., "94000"). Required.

size

Character string; order quantity (e.g., "0.1"). Required.

clientOid

Character string; unique client order ID (max 40 characters, e.g., "5c52e11203aa67f1e493fb"). Required.

stopPrice

Character string; stop-limit trigger price (e.g., "98000"). Required.

limitPrice

Character string; stop-limit order price (e.g., "96000"). Required.

remark

Character string; optional remarks (max 20 characters, e.g., "this is remark").

tradeType

Character string; transaction type: "TRADE" (default).

Value

Promise resolving to a data.table with one row containing:

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

Details

What is an OCO Order?

An OCO (One-Cancels-the-Other) order is a sophisticated trading tool that pairs a limit order (to secure profits) with a stop-limit order (to cap losses). When one order executes—either hitting a profit target or a stop-loss threshold—the other is automatically canceled. This is particularly useful for:

  • Risk Management: Set a stop-loss to limit potential losses if the market moves against your position, e.g., buying BTC at $50,000 with a stop at $48,000.

  • Profit Taking: Lock in gains at a target price without constant monitoring, e.g., selling at $55,000 after buying at $50,000.

  • Volatile Markets: Automate trading decisions in fast-moving conditions, reducing emotional bias and ensuring discipline. For example, a trader might place an OCO order to buy BTC at $50,000, setting a limit sell at $55,000 (profit) and a stop-limit sell at $48,000 (loss protection). If BTC reaches $55,000, the profit is secured, and the stop cancels; if it drops to $48,000, losses are limited, and the limit cancels.

Description

This function constructs a JSON request body with required parameters (symbol, side, price, size, clientOid, stopPrice, limitPrice) and optional fields (remark, tradeType), authenticates the request, and processes the response into a data.table.

Workflow

  1. Parameter Validation: Ensures required fields are non-empty strings and validates side and tradeType enums.

  2. Request Construction: Builds a named list of parameters, excluding NULL values, and converts it to JSON using toJSON.

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

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

  5. Response Processing: Parses the response with process_kucoin_response, checks for success ("200000"), and converts the data field to a data.table.

API Details

  • Endpoint: POST https://api.kucoin.com/api/v3/oco/order

  • Domain: Spot

  • API Channel: Private

  • API Permission: Spot

  • Rate Limit Pool: Spot

  • Rate Limit Weight: 2

  • SDK Service: Spot

  • SDK Sub-Service: Order

  • SDK Method Name: addOcoOrder

  • Official Documentation: KuCoin Add OCO Order

Request

Body Parameters (application/json)

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

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

  • price: String (required) - Limit order price.

  • size: String (required) - Order quantity.

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

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

  • limitPrice: String (required) - Limit order price after triggering take-profit or stop-loss.

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

  • tradeType: Enum (optional) - Transaction type: "TRADE" (default).

Example Request

curl --location --request POST 'https://api.kucoin.com/api/v3/oco/order' \
--header 'Content-Type: application/json' \
--data-raw '{
    "symbol": "BTC-USDT",
    "side": "buy",
    "price": "94000",
    "size": "0.1",
    "clientOid": "5c52e11203aa67f1e493fb",
    "stopPrice": "98000",
    "limitPrice": "96000",
    "remark": "this is remark",
    "tradeType": "TRADE"
}'

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.

JSON Response Example

{
  "code": "200000",
  "data": {
    "orderId": "674c316e688dea0007c7b986"
  }
}

Examples

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

main_async <- coro::async(function() {
  # Place an OCO order for BTC-USDT
  oco_order <- await(add_oco_order_impl(
    symbol = "BTC-USDT",
    side = "buy",
    price = "94000",
    size = "0.1",
    clientOid = "5c52e11203aa67f1e493fb",
    stopPrice = "98000",
    limitPrice = "96000",
    remark = "Profit and Stop"
  ))
  print(oco_order)
})

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