Timestamps

Deribit's own wire format is raw epoch integers everywhere, but the generated surface never hands you one directly: every documented timestamp field and parameter — request and response, across .http, .ws, and .streams — is a real Python datetime. Conversion happens automatically through pydantic validation on the way in, and through the same converter on the way out when a request is built for the wire.

Three types cover it, all importable from typed_deribit.core:

• TimestampMillis — millisecond-epoch UTC. This is the vast majority of Deribit's timestamp fields: order and trade creation_timestamp, timestamp, instrument expiration_timestamp, the start_timestamp/end_timestamp window bounds on market-data and account endpoints, and more.
• TimestampNanos — nanosecond-epoch UTC, used only for Starbase's own causal timestamps: starbase_timestamp (on trades) and starbase_last_update_timestamp (on orders).
• DateIso — a plain calendar date with no time component, used only for get_delivery_prices's date field (e.g. 2026-08-03).

All three are Annotated aliases over datetime/date — real types you can use in your own code, not internal implementation details.

Passing A Timestamp

A windowed request takes real datetime objects for its bounds:

from datetime import datetime, timezone
from typed_deribit import Deribit

async with Deribit.new(public=True) as client:
  history = await client.http.market_data.get_funding_rate_history(
    instrument_name='BTC-PERPETUAL',
    start_timestamp=datetime(2023, 11, 14, 22, 13, 20, tzinfo=timezone.utc),
    end_timestamp=datetime(2023, 11, 14, 23, 13, 20, tzinfo=timezone.utc),
  )

A naive datetime (no tzinfo) works too — Deribit's converter treats it as UTC — but passing an explicit timezone.utc reads clearest and avoids relying on that default.

Reading A Timestamp

Response timestamp fields (Ticker.timestamp, BookSummaryItem.creation_timestamp, order and trade timestamps, ...) come back as real datetime values, already converted:

from typed_deribit import Deribit

async with Deribit.new(public=True) as client:
  ticker = await client.http.market_data.ticker(instrument_name='BTC-PERPETUAL')
  print(ticker['timestamp'], ticker['timestamp'].tzinfo)

Starbase Nanosecond Fields

starbase_timestamp/starbase_last_update_timestamp (trade and order fields) are typed TimestampNanos instead — same datetime shape, converted from a nanosecond-epoch wire value rather than milliseconds. No special handling is needed on your side; the field just carries more precision than every other timestamp in the client.

Raw Helpers

TimestampMillis/TimestampNanos/DateIso are pydantic-validated type aliases, not converter objects themselves. The converters behind them (timestamp_millis, timestamp_nanos, date_iso) are also importable from typed_deribit.core, if you ever need to convert a datetime to a raw epoch value by hand — for example, to compare against a value read from somewhere outside the client:

from datetime import datetime, timezone
from typed_deribit.core import timestamp_millis

now_ms = timestamp_millis.dump(datetime.now(timezone.utc))
as_datetime = timestamp_millis.parse(now_ms)