Timestamps

Timestamps work differently on dYdX's two sides. This page covers the indexer's datetime convention -- the chain/gRPC side is a genuinely different mechanism and isn't covered here.

Indexer: Native datetime

Indexer endpoints that take a timestamp accept a Python datetime directly, and validated response fields come back as datetime too -- there's nothing to convert by hand.

from datetime import datetime, timezone

from typed_dydx import Dydx

async with Dydx.testnet(public=True) as client:
  candles = await client.indexer.data.get_candles(
    'BTC-USD',
    resolution='1HOUR',
    from_iso=datetime(2026, 1, 1, tzinfo=timezone.utc),
    limit=100,
  )
  print(candles['candles'][0]['startedAt'])  # already a datetime

Common Patterns

Pass a datetime directly wherever an indexer endpoint takes a time window -- fills, transfers, funding payments, historical PnL, and candles all follow this convention.

from datetime import datetime, timedelta

end = datetime.now()
start = end - timedelta(hours=1)

Raw Helpers

dydx.indexer.timestamp exports a single helper, dump(value: datetime) -> str, which serializes a datetime into the ISO-8601-with-Z string the indexer's query parameters expect. Every indexer endpoint that takes a timestamp already calls this internally -- you only need it yourself if you're building a raw request outside the generated methods.

from datetime import datetime

from typed_dydx.indexer import timestamp as ts

wire_value = ts.dump(datetime.now())

Unlike some other Typed clients' timestamp modules, there is no now() or parse() exported here -- just dump(). There's no need for a parse() counterpart: response fields are already typed and validated as datetime, not returned as raw strings.

Chain (gRPC / Comet): Proto-Native, Not This Convention

client.chain does not use the indexer's ts.dump() convention at all. gRPC responses carry datetime fields generated directly from google.protobuf.Timestamp by the proto bindings (for example Header.time), and Comet HTTP responses parse RFC3339 timestamps into datetime the same way. Neither side exposes a dump/parse helper, and chain-side queries are addressed by block height or transaction hash, not by a timestamp request parameter -- so there's no request-side conversion step to document here.