Skip to contents

Get Closed Orders (Implementation)

Source: R/impl_spottrading_orders_get_x.R
get_closed_orders_impl.Rd

Retrieves all closed spot orders for a specified symbol from the KuCoin Spot trading system asynchronously. This function supports pagination and returns a data.table with detailed information about each closed order, sorted by the latest update time in descending order.

Usage

get_closed_orders_impl(
  keys = get_api_keys(),
  base_url = get_base_url(),
  symbol,
  side = NULL,
  type = NULL,
  startAt = NULL,
  endAt = NULL,
  limit = 20,
  max_pages = Inf,
  .__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; the trading pair symbol (e.g., "BTC-USDT"). Required.

side

Character string; optional filter for order side: "buy" or "sell".

type

Character string; optional filter for order type: "limit" or "market".

startAt

Numeric; optional start time in milliseconds.

endAt

Numeric; optional end time in milliseconds.

limit

Integer; number of orders per page (1 to 100, default 20).

max_pages

Numeric; maximum number of pages to fetch (default Inf).

Value

Promise resolving to a data.table with columns:

  • 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.

  • remainSize (character): Remaining quantity.

  • remainFunds (character): Remaining funds.

  • cancelledSize (character): Canceled quantity.

  • cancelledFunds (character): Canceled 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.

  • tax (character): Tax information.

  • active (logical): Order status (false for closed orders).

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

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

  • createdAtDatetime (POSIXct): Creation time in UTC.

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

Details

Description

This endpoint fetches all closed orders (canceled or fully filled) for a given trading pair (e.g., "BTC-USDT"). The orders are returned in descending order based on their last update time. The function handles pagination using the lastId parameter to fetch multiple pages of results, with data availability limited to the last 72 hours by default if no time range is specified beyond that period.

Workflow

  1. Parameter Validation: Ensures symbol is a valid trading pair and limit is an integer between 1 and 100.

  2. Request Construction: Builds the API endpoint with query parameters including symbol, side, type, startAt, endAt, and limit.

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

  4. API Request: Sends asynchronous GET requests to fetch pages of closed orders until no more orders are returned or max_pages is reached.

  5. Response Processing: Combines the fetched orders into a single data.table and adds createdAtDatetime and lastUpdatedAtDatetime columns using time_convert_from_kucoin().

API Details

  • Endpoint: GET https://api.kucoin.com/api/v1/hf/orders/done

  • 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: getClosedOrders

  • Official Documentation: KuCoin Get Closed Orders

Request

Query Parameters

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

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

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

  • lastId: Integer (optional) - The ID of the last order from the previous batch for pagination.

  • limit: Integer (optional) - Number of orders per page (default 20, max 100).

  • startAt: Integer (optional) - Start time in milliseconds.

  • endAt: Integer (optional) - End time in milliseconds.

Example Request

curl --location --request GET 'https://api.kucoin.com/api/v1/hf/orders/done?symbol=BTC-USDT&side=buy&type=limit&lastId=254062248624417&limit=20&startAt=1728663338000&endAt=1728692138000'

Response

HTTP Code: 200

  • Content Type: application/json

Data Schema

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

  • data: Object (required) - Contains:

    • lastId: Integer (required) - The ID for the next page of data.

    • items: Array of objects (required) - List of closed orders, each with fields:

      • id: String - Unique order ID.

      • clientOid: String - Client-assigned order ID.

      • symbol: String - Trading pair.

      • opType: String - Operation type.

      • type: Enum - Order type: "limit" or "market".

      • side: Enum - Order side: "buy" or "sell".

      • price: String - Order price.

      • size: String - Order size.

      • funds: String - Order funds.

      • dealSize: String - Filled quantity.

      • dealFunds: String - Filled funds.

      • remainSize: String - Remaining quantity.

      • remainFunds: String - Remaining funds.

      • cancelledSize: String - Canceled quantity.

      • cancelledFunds: String - Canceled funds.

      • fee: String - Handling fees.

      • feeCurrency: String - Fee currency.

      • stp: Enum - Self Trade Prevention: "DC", "CO", "CN", "CB" or NA.

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

      • postOnly: Boolean - Post-only flag.

      • hidden: Boolean - Hidden order flag.

      • iceberg: Boolean - Iceberg order flag.

      • visibleSize: String - Visible size for iceberg orders.

      • cancelAfter: Integer - Seconds until cancellation for GTT.

      • channel: String - Order channel.

      • remark: String or NA - Order remarks.

      • tags: String or NA - Order tags.

      • cancelExist: Boolean - Indicates a cancellation record.

      • tradeType: String - Trade type.

      • inOrderBook: Boolean - Whether in the order book.

      • tax: String - Tax information.

      • active: Boolean - Order status (false for closed orders).

      • createdAt: Integer - Creation timestamp in milliseconds.

      • lastUpdatedAt: Integer - Last update timestamp in milliseconds.

JSON Response Example

{
  "code": "200000",
  "data": {
    "lastId": 19814995255305,
    "items": [
      {
        "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 closed orders for BTC-USDT
  closed_orders <- await(get_closed_orders_impl(
    symbol = "BTC-USDT",
    side = "buy",
    type = "limit",
    startAt = 1728663338000,
    endAt = 1728692138000,
    limit = 50,
    max_pages = 2
  ))
  print(closed_orders)
})

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