Timestamps

Common Patterns

Most validated response timestamp fields come back as a datetime (UTC) — the client decodes KuCoin's epoch integers automatically, via the shared TimestampMillis (or, for a handful of endpoints, TimestampSeconds) type used across Spot, Margin, Futures, Earn and streaming responses. You don't parse these yourself.

from typed_kucoin import KuCoin

async with KuCoin.new() as client:
  orders = await client.spot.stop_orders.get_list()
  for order in orders['items']:
    print(order['createdAt'])  # a datetime

A few response fields are the exception and stay a plain millisecond int instead of datetime — for example account.ledgers's createdAt. Check the field's own type in the generated response before assuming it's a datetime.

Every start_at/end_at-shaped request parameter across the client (order-history endpoints like spot.orders_hf.get_trade_history, spot.orders_hf.get_closed_orders, spot.oco_orders.get_list, spot.stop_orders.get_list and their margin.* equivalents, account/broker/convert history endpoints, and futures/affiliate windows) accepts a real datetime directly — the client converts it to KuCoin's own epoch integer for you, so you never build the raw integer by hand:

from datetime import datetime, timedelta
from typed_kucoin import KuCoin

async with KuCoin.new() as client:
  trades = await client.spot.orders_hf.get_trade_history(
    symbol='BTC-USDT',
    start_at=datetime.now() - timedelta(days=1),
    end_at=datetime.now(),
  )

The one thing that's not uniform is the wire unit the client converts your datetime into. Most endpoints (for example futures.funding_fees.private_funding_history's start_at/end_at, affiliate.trade_history's trade_start_at/trade_end_at) encode Unix milliseconds, matching every response field. spot.klines's start_at/end_at are the one exception: Unix seconds, not milliseconds. This is purely an internal conversion detail; you always pass a datetime either way.

from datetime import datetime, timedelta
from typed_kucoin import KuCoin

async with KuCoin.new(public=True) as client:
  candles = await client.spot.klines(     # start_at/end_at encode Unix SECONDS on the wire
    symbol='BTC-USDT', type='1hour',
    start_at=datetime.now() - timedelta(hours=1), end_at=datetime.now(),
  )
  history = await client.futures.funding_fees.private_funding_history(  # ms on the wire
    symbol='XBTUSDTM',
    start_at=datetime.now() - timedelta(hours=1), end_at=datetime.now(),
  )

Raw Helpers

Use typed_kucoin.core.timestamp_millis (or timestamp_seconds, for spot.klines's second-based start_at/end_at) when you need to convert a datetime to/from KuCoin's epoch integer by hand.

from datetime import datetime
from typed_kucoin.core import timestamp_millis

timestamp_ms = timestamp_millis.dump(datetime.now())
current_ms = timestamp_millis.now()
parsed = timestamp_millis.parse(1715200000000)