Get Order By ClientOid (Implementation)

Retrieves detailed information for a single spot order using its client order ID (clientOid) from the KuCoin Spot trading system asynchronously. This function returns a data.table with comprehensive order details, including additional UTC datetime columns derived from timestamps.

Usage

get_order_by_client_oid_impl(
  keys = get_api_keys(),
  base_url = get_base_url(),
  clientOid,
  symbol,
  .__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().

clientOid

Character string; the unique client order ID to retrieve (e.g., "5c52e11203aa677f33e493fb"). Required.

symbol

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

Value

Promise resolving to a data.table with one row containing order details, including:

• id (character): Unique order ID.

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

• symbol (character): Trading pair.

• opType (character): Operation type.

• type (character): Order type ("limit" or "market").

• side (character): Order side ("buy" or "sell").

• price (character): Order price.

• size (character): Order size.

• funds (character): Order funds.

• dealSize (character): Filled quantity.

• dealFunds (character): Filled funds.

• cancelledSize (character): Canceled quantity.

• cancelledFunds (character): Canceled funds.

• remainSize (character): Remaining quantity.

• remainFunds (character): Remaining funds.

• fee (character): Handling fees.

• feeCurrency (character): Fee currency.

• stp (character or NA): Self Trade Prevention strategy.

• timeInForce (character): Time in force.

• postOnly (logical): Post-only flag.

• hidden (logical): Hidden order flag.

• iceberg (logical): Iceberg order flag.

• visibleSize (character): Visible size for iceberg orders.

• cancelAfter (integer): Seconds until cancellation for GTT.

• channel (character): Order channel.

• remark (character or NA): Order remarks.

• tags (character or NA): Order tags.

• cancelExist (logical): Indicates a cancellation record.

• tradeType (character): Trade type.

• inOrderBook (logical): Whether in the order book.

• active (logical): Order status (true = active, false = done).

• tax (character): Tax information.

• createdAt (integer): Creation timestamp (milliseconds).

• lastUpdatedAt (integer): Last update timestamp (milliseconds).

• createdAtDatetime (POSIXct): Creation time in UTC.

• lastUpdatedAtDatetime (POSIXct): Last update time in UTC.

Details

Description

This endpoint fetches data for a specific spot order identified by its clientOid, a unique identifier assigned by the user when placing the order. The order can be in an active or done state:

• Active Orders: Orders currently in the order book (check inOrderBook to confirm).

• Done Orders: Orders that are canceled or fully filled (data available only within 3 * 24 hours from the current time).

If the order is not active and exceeds the 3 * 24-hour window, the API defaults to querying within that timeframe, potentially returning no data if outside the range.

Differences from Get Order By OrderId

• Get Order By OrderId: Uses the KuCoin-generated orderId to retrieve order details, suitable when tracking orders via system-assigned IDs.

• Get Order By ClientOid: Uses the user-assigned clientOid, ideal when managing orders with custom identifiers without needing to map to KuCoin’s IDs.

Choose this method if you track orders using your own identifiers.

Workflow

1. Parameter Validation: Ensures clientOid and symbol are non-empty strings, with symbol validated as a trading pair.

2. Request Construction: Builds the endpoint URL with clientOid in the path and symbol as a query parameter.

3. Authentication: Generates private API headers using build_headers() with the GET method and endpoint.

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

5. Response Processing: Parses the response, converts the data object to a data.table, and adds createdAtDatetime and lastUpdatedAtDatetime columns.

API Details

• Endpoint: GET https://api.kucoin.com/api/v1/hf/orders/client-order/{clientOid}?symbol={symbol}

• Domain: Spot

• API Channel: Private

• API Permission: General

• Rate Limit Pool: Spot

• Rate Limit Weight: 2

• SDK Service: Spot

• SDK Sub-Service: Order

• SDK Method Name: getOrderByClientOid

• Official Documentation: KuCoin Get Order By ClientOid

Request

Path Parameters

• clientOid: String (required) - The unique client order ID created by the user (e.g., "5c52e11203aa677f33e493fb").

Query Parameters

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

Example Request

curl --location --request GET 'https://api.kucoin.com/api/v1/hf/orders/client-order/5c52e11203aa677f33e493fb?symbol=BTC-USDT'

Response

HTTP Code: 200

• Content Type: application/json

Data Schema

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

• data: Object (required) - Order details with the following fields:

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

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

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

  • opType: String (required) - Operation type.

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

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

  • price: String (required) - Order price.

  • size: String (required) - Order size.

  • funds: String (required) - Order funds.

  • dealSize: String (required) - Filled quantity.

  • dealFunds: String (required) - Filled funds.

  • cancelledSize: String (required) - Canceled quantity.

  • cancelledFunds: String (required) - Canceled funds.

  • remainSize: String (required) - Remaining quantity.

  • remainFunds: String (required) - Remaining funds.

  • fee: String (required) - Handling fees.

  • feeCurrency: String (required) - Fee currency.

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

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

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

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

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

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

  • cancelAfter: Integer (required) - Seconds until cancellation for GTT.

  • channel: String (required) - Order channel.

  • remark: String (optional) - Order remarks.

  • tags: String (optional) - Order tags.

  • cancelExist: Boolean (required) - Indicates a cancellation record.

  • tradeType: String (required) - Trade type (redundant parameter).

  • inOrderBook: Boolean (required) - Whether the order is in the order book.

  • active: Boolean (required) - Order status (true = active, false = done).

  • tax: String (required) - Tax information (for certain regions).

  • createdAt: Integer (required) - Creation timestamp in milliseconds.

  • lastUpdatedAt: Integer (required) - Last update timestamp in milliseconds.

JSON Response Example

{
  "code": "200000",
  "data": {
    "id": "6717422bd51c29000775ea03",
    "clientOid": "5c52e11203aa677f33e493fb",
    "symbol": "BTC-USDT",
    "opType": "DEAL",
    "type": "limit",
    "side": "buy",
    "price": "70000",
    "size": "0.00001",
    "funds": "0.7",
    "dealSize": "0.00001",
    "dealFunds": "0.677176",
    "remainSize": "0",
    "remainFunds": "0.022824",
    "cancelledSize": "0",
    "cancelledFunds": "0",
    "fee": "0.000677176",
    "feeCurrency": "USDT",
    "stp": null,
    "timeInForce": "GTC",
    "postOnly": false,
    "hidden": false,
    "iceberg": false,
    "visibleSize": "0",
    "cancelAfter": 0,
    "channel": "API",
    "remark": "order remarks",
    "tags": null,
    "cancelExist": false,
    "tradeType": "TRADE",
    "inOrderBook": false,
    "active": false,
    "tax": "0",
    "createdAt": 1729577515444,
    "lastUpdatedAt": 1729577515481
  }
}

Examples

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

main_async <- coro::async(function() {
  # Retrieve order details by clientOid
  order_details <- await(get_order_by_client_oid_impl(
    clientOid = "5c52e11203aa677f33e493fb",
    symbol = "BTC-USDT"
  ))
  print(order_details)
})

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

# Expected Output (simplified):
#    id                    clientOid symbol opType type  side price size  ... createdAtDatetime   lastUpdatedAtDatetime
# 1: 6717422bd51c29000775ea03 5c52e11203aa677f33e493fb BTC-USDT DEAL limit buy  70000 0.00001 ... 2023-10-22 03:31:55 2023-10-22 03:31:55