Skip to contents

Getting Started with kucoin

Dereck Mezquita

Source: vignettes/getting-started.Rmd
getting-started.Rmd

This vignette demonstrates how to use kucoin in synchronous mode.

Setup 

box::use(
  kucoin[
    KucoinMarketData, KucoinTrading, KucoinAccount,
    KucoinStopOrders, KucoinOcoOrders, KucoinDeposit,
    KucoinSubAccount, get_api_keys
  ],
  lubridate[ymd_hms]
)

keys <- get_api_keys(
  api_key = "your-api-key",
  api_secret = "your-api-secret",
  api_passphrase = "your-api-passphrase"
)

Market Data

The KucoinMarketData class covers all public (no auth) market endpoints.

market <- KucoinMarketData$new()

Ticker 

ticker <- market$get_ticker("BTC-USDT")
ticker

24hr Statistics 

stats <- market$get_24hr_stats("BTC-USDT")
stats

All Tickers 

tickers <- market$get_all_tickers()
tickers

Trade History 

trades <- market$get_trade_history("BTC-USDT")
trades

Partial Orderbook 

book <- market$get_part_orderbook("BTC-USDT", size = 20)
book

Klines (Candlestick Data) 

klines <- market$get_klines("BTC-USDT", "15min",
  from = ymd_hms("2024-10-16 20:00:00"),
  to = ymd_hms("2024-10-16 21:00:00")
)
klines
#>               datetime     open     high      low    close   volume turnover
#>                 <POSc>    <num>    <num>    <num>    <num>    <num>    <num>
#> 1: 2025-07-26 12:00:00 117775.9 118221.2 117766.4 118128.9 264.6461 31241540
#> 2: 2025-07-26 16:00:00 118129.0 118291.8 117940.3 118227.4 197.8112 23355797
#> 3: 2025-07-26 20:00:00 118227.3 118299.3 117880.4 117915.0 252.9352 29854685

Currency Info 

btc <- market$get_currency("BTC")
btc
#>    currency   name full_name precision confirms contract_address
#>      <char> <char>    <char>     <int>   <lgcl>           <lgcl>
#> 1:      BTC    BTC   Bitcoin         8       NA               NA
#> 2:      BTC    BTC   Bitcoin         8       NA               NA
#>    is_margin_enabled is_debit_enabled chain_name withdrawal_min_size
#>               <lgcl>           <lgcl>     <char>              <char>
#> 1:              TRUE             TRUE        BTC               0.001
#> 2:              TRUE             TRUE        KCC              0.0008
#>    deposit_min_size withdraw_fee_rate withdrawal_min_fee is_withdraw_enabled
#>              <char>            <char>             <char>              <lgcl>
#> 1:           0.0002                 0             0.0005                TRUE
#> 2:          0.00002                 0            0.00002                TRUE
#>    is_deposit_enabled confirms pre_confirms   contract_address
#>                <lgcl>    <int>        <int>             <char>
#> 1:               TRUE        3            1                   
#> 2:               TRUE       20           20 0xfa93c12cd345c658
#>    withdraw_precision max_withdraw max_deposit need_tag chain_id
#>                 <int>       <lgcl>      <lgcl>   <lgcl>   <char>
#> 1:                  8           NA          NA    FALSE      btc
#> 2:                  8           NA          NA    FALSE      kcc

Symbol Info 

sym <- market$get_symbol("BTC-USDT")
sym
#>      symbol     name base_currency quote_currency fee_currency market
#>      <char>   <char>        <char>         <char>       <char> <char>
#> 1: BTC-USDT BTC-USDT           BTC           USDT         USDT   USDS
#>    base_min_size quote_min_size base_max_size quote_max_size base_increment
#>           <char>         <char>        <char>         <char>         <char>
#> 1:       0.00001            0.1   10000000000       99999999     0.00000001
#>    quote_increment price_increment price_limit_rate min_funds is_margin_enabled
#>             <char>          <char>           <char>    <char>            <lgcl>
#> 1:        0.000001             0.1              0.1       0.1              TRUE
#>    enable_trading fee_category maker_fee_coefficient taker_fee_coefficient
#>            <lgcl>        <int>                <char>                <char>
#> 1:           TRUE            1                  1.00                  1.00
#>        st
#>    <lgcl>
#> 1:  FALSE

Trading

The KucoinTrading class manages HF spot orders. All trading endpoints require authentication.

Place a Test Order

Test orders validate parameters without executing:

trading <- KucoinTrading$new()
result <- trading$add_order_test(
  type = "limit",
  symbol = "BTC-USDT",
  side = "buy",
  price = "50000",
  size = "0.0001"
)
result
#>                    order_id               client_oid
#>                      <char>                   <char>
#> 1: 670fd33bf9406e0007ab3945 5c52e11203aa677f33e493fb

Cancel an Order 

cancelled <- trading$cancel_order_by_id("670fd33bf9406e0007ab3945", symbol = "BTC-USDT")
cancelled
#>                    order_id
#>                      <char>
#> 1: 670fd33bf9406e0007ab3945

Query Open Orders 

open_orders <- trading$get_open_orders("BTC-USDT")
open_orders

Stop Orders 

stop <- KucoinStopOrders$new()
result <- stop$add_order(
  type = "limit",
  symbol = "BTC-USDT",
  side = "sell",
  price = "60000",
  size = "0.0001",
  stopPrice = "59000"
)
result
#>                    order_id     client_oid
#>                      <char>         <char>
#> 1: vs8hoo8q2ceshiue003b67c0 stop-limit-001

OCO Orders

An OCO (One-Cancels-Other) order pairs a limit order with a stop-limit order; when one side fills, the other is cancelled automatically.

oco <- KucoinOcoOrders$new()
result <- oco$add_order(
  symbol = "BTC-USDT",
  side = "sell",
  price = "110000",
  size = "0.0001",
  stopPrice = "90000",
  limitPrice = "89500"
)
result
#>                    order_id
#>                      <char>
#> 1: 674c40d38b4b2f00073deef3

Account Management

Account Summary 

account <- KucoinAccount$new()
summary <- account$get_summary()
summary
#>    level sub_quantity max_default_sub_quantity max_sub_quantity
#>    <int>        <int>                    <int>            <int>
#> 1:     1            3                        5                5
#>    spot_sub_quantity margin_sub_quantity futures_sub_quantity
#>                <int>               <int>                <int>
#> 1:                 2                   1                    0
#>    option_sub_quantity max_spot_sub_quantity max_margin_sub_quantity
#>                  <int>                 <int>                   <int>
#> 1:                   0                     5                       5
#>    max_futures_sub_quantity max_option_sub_quantity
#>                       <int>                   <int>
#> 1:                        5                       5

Spot Account Balances 

balances <- account$get_spot_accounts()
balances
#>                          id currency   type    balance available      holds
#>                      <char>   <char> <char>     <char>    <char>     <char>
#> 1: 6717422bd51c29000775ea01     USDT  trade   10000.50   9500.25     500.25
#> 2: 6717422bd51c29000775ea02      BTC  trade 1.23456789       1.0 0.23456789

Deposits

Get Deposit Addresses 

deposit <- KucoinDeposit$new()
addrs <- deposit$get_deposit_addresses(currency = "USDT")
addrs
#>                                       address   memo  chain chain_id     to
#>                                        <char> <char> <char>   <char> <char>
#> 1: 0x1a2b3c4d5e6f7890abcdef1234567890abcdef12         ERC20      eth   main
#> 2:    TXyz123abcDEF456ghiJKL789mnoPQR012stuVW         TRC20      trx   main
#>    currency                           contract_address chain_name
#>      <char>                                     <char>     <char>
#> 1:     USDT 0xdac17f958d2ee523a2206206994597c13d831ec7      ERC20
#> 2:     USDT         TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t      TRC20
#>    expiration_date
#>              <int>
#> 1:               0
#> 2:               0

Sync Orders and Modify

Sync variants return fill results in a single round trip:

# Place order and get immediate fill result
order <- trading$add_order_sync(
  type = "limit", symbol = "BTC-USDT", side = "buy",
  price = "50000", size = "0.0001"
)
cat("Status:", order$status, "Filled:", order$deal_size, "\n")

# Modify an existing order's price
modified <- trading$modify_order(
  symbol = "BTC-USDT",
  orderId = order$order_id,
  newPrice = "51000"
)
cat("New order ID:", modified$new_order_id, "\n")

Dead Connection Protection (DCP)

A dead-man’s switch that auto-cancels orders if your bot stops heartbeating:

# Enable: cancel all BTC-USDT orders if no request in 30 seconds
trading$set_dcp(timeout = 30, symbols = "BTC-USDT")

# Check current DCP settings
dcp <- trading$get_dcp()
cat("Timeout:", dcp$timeout, "s\n")

# Disable
trading$set_dcp(timeout = -1)

Fee Rates 

# Base fee rate (account tier default)
base_fees <- account$get_base_fee_rate()
cat("Base taker:", base_fees$taker_fee_rate, "\n")

# Per-symbol actual rates (after VIP/KCS discounts)
actual_fees <- account$get_fee_rate("BTC-USDT,ETH-USDT")
actual_fees

HF Trading Ledger

The HF ledger contains fills, fees, and settlements from HF orders (7-day window):

hf_ledger <- account$get_hf_ledger(currency = "USDT", bizType = "TRADE_EXCHANGE")
hf_ledger

Server Time and Service Status 

# Check clock drift
st <- market$get_server_time()
drift_ms <- as.numeric(lubridate::now()) * 1000 - st$server_time
cat("Clock drift:", round(drift_ms), "ms\n")

# Pre-flight: is the exchange operational?
status <- market$get_service_status()
if (status$status != "open") stop("Exchange not operational: ", status$msg)

Fiat Prices 

prices <- market$get_fiat_prices(base = "USD", currencies = "BTC,ETH,USDT")
prices

Fund Transfers

Deposits land in the main account, but HF spot orders require funds in the trade account. Use KucoinTransfer to move funds between account types.

box::use(kucoin[KucoinTransfer])

transfer <- KucoinTransfer$new()

# Check how much USDT is available to transfer
balance <- transfer$get_transferable(currency = "USDT", type = "MAIN")
balance

# Transfer USDT from main to trade account
result <- transfer$add_transfer(
  clientOid = "unique-id-here",
  currency = "USDT",
  amount = "100",
  type = "INTERNAL",
  fromAccountType = "MAIN",
  toAccountType = "TRADE"
)
result

Withdrawals

Use KucoinWithdrawal to check withdrawal limits, initiate withdrawals, and monitor withdrawal status.

box::use(kucoin[KucoinWithdrawal])

withdrawal <- KucoinWithdrawal$new()

# Check withdrawal quotas and fees
quotas <- withdrawal$get_withdrawal_quotas(currency = "USDT", chain = "trx")
quotas

# Withdraw USDT via TRC20
result <- withdrawal$add_withdrawal(
  currency = "USDT",
  toAddress = "your-trc20-address",
  amount = "10",
  withdrawType = "ADDRESS",
  chain = "trx"
)
result

# Check withdrawal history
history <- withdrawal$get_withdrawal_history(currency = "USDT")
history

Sub-Account Management

List Sub-Accounts 

sub <- KucoinSubAccount$new()
subs <- sub$get_sub_account_list()
subs

Clock Drift: Server Time Signing

By default, HMAC request signatures use your local machine’s clock. If your system time is out of sync with KuCoin’s servers, authenticated requests may fail. You can configure any class to fetch the server time before each authenticated request:

# Use server time for signing (adds one round trip per request)
trading <- KucoinTrading$new(time_source = "server")

# All authenticated calls now use the exchange clock
order <- trading$add_order_test(
  type = "limit", symbol = "BTC-USDT", side = "buy",
  price = "50000", size = "0.0001"
)

The time_source parameter is available on all class constructors: KucoinTrading, KucoinAccount, KucoinStopOrders, KucoinOcoOrders, KucoinDeposit, KucoinTransfer, KucoinWithdrawal, and KucoinSubAccount.

Next Steps