Get Order By OrderId (Implementation) — get_order_by_order_id

Retrieves detailed information for a single spot order using its order ID 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_order_id_impl(
  keys = get_api_keys(),
  base_url = get_base_url(),
  orderId,
  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().
orderId: Character string; the unique order ID to retrieve (e.g., "6717422bd51c29000775ea03"). 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 orderId. 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.

Workflow

Parameter Validation: Ensures orderId and symbol are non-empty strings, with symbol validated as a trading pair.
Request Construction: Builds the endpoint URL with orderId in the path and symbol as a query parameter.
Authentication: Generates private API headers using build_headers() with the GET method and endpoint.
API Request: Sends a GET request to the KuCoin API with a 3-second timeout.
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/{orderId}?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: getOrderByOrderId
Official Documentation: KuCoin Get Order By OrderId

Request

Path Parameters

orderId: String (required) - The unique order ID generated by the trading system (e.g., "6717422bd51c29000775ea03").

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/6717422bd51c29000775ea03?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.
- 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
  order_details <- await(get_order_by_order_id_impl(
    orderId = "6717422bd51c29000775ea03",
    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