Timestamps & clocks

Every row carries two timestamps: the venue's and ours. They answer different questions, and most timing bugs in crypto research come from using one where the other belongs.

Two clocks

Both are stored as integers. We never convert to floating-point seconds, because a float64 cannot hold a nanosecond epoch timestamp exactly (it keeps about 0.24 µs of resolution at today's dates).

How ts_capture is taken

ts_capture is the kernel receive timestamp of the network read that delivered the message, recorded with SO_TIMESTAMPING and carried through TLS decryption and parsing. Decompression, parsing and normalization all happen after the timestamp, so our own processing time never leaks into it. When one read delivers several venue messages, they share a ts_capture and keep their order through seq.

Clock synchronization

Capture hosts run on AWS Nitro instances with the Amazon Time Sync Service exposed as a PTP hardware clock on the network adapter. chrony disciplines the system clock against that hardware clock, and a separate monitor reads the clock error bound every 16 seconds. If the bound on any host exceeds 50 µs, the affected interval is listed with that day's quality metrics on Status, with start and end times on the same clock. The rows are kept; you decide whether to drop them.

Error budget

Worst-case contributions to the difference between ts_capture and true UTC on a Tokyo capture host, at the 99th percentile:

A 50 µs bound is three orders of magnitude below the latency between a venue and our hosts, so it is fine for ordering events across venues and for measuring feed latency. It is not fine for comparing two events that our hosts received 10 µs apart; for those, treat the order as unknown unless they share a seq stream.

Venue timestamp precision

ts_exchange is always scaled to nanoseconds, but it is only as precise as the venue publishes. A millisecond venue's timestamps always end in six zeros. The field we read and its precision, by venue:

Every venue other than Hyperliquid is planned, subject to a data agreement with the exchange. Their rows follow each venue's public API documentation and will be confirmed with the venue before capture starts; any change is recorded in the changelog. Per-venue details are on Venues.

Which clock to use

Extended fields are computed on ts_capture for the same reason, and published on a 100 ms grid of that clock. See Extended fields.

As-of join across venues

import polars as pl
from fdc import Client

fdc = Client()
window = dict(symbol="BTC-PERP", start="2027-09-01T00:00:00Z", end="2027-09-01T01:00:00Z")

hl = fdc.trades(venue="hyperliquid", **window).to_polars()
bn = (fdc.trades(venue="binance", **window).to_polars()
        .select("ts_capture", pl.col("price").alias("binance_price")))

# for each Hyperliquid trade, the last Binance trade we had received by then
joined = hl.sort("ts_capture").join_asof(
    bn.sort("ts_capture"),
    on="ts_capture", strategy="backward",
)

Both venues in this example are captured in Tokyo, so ts_capture on both sides comes from the same region. Joining on ts_exchange instead would mix two venue clocks with different precision and unknown offsets.

Multi-region capture

Each venue is captured independently from two regions: Tokyo (ap-northeast-1, primary) and Ireland (eu-west-1, secondary), with N. Virginia (us-east-1) added in Phase 2. The streams are merged by venue sequence number. In the merged stream, ts_capture is the earliest receive time across the regions, and the region column names the region that received the message first.

• Earliest receive wins. When both regions have a message, the row keeps the earlier of the two receive times. For a Tokyo-hosted venue that is Tokyo for all but a few messages in ten thousand, usually during a brief stall on the Tokyo side.
• Secondary fills. When only the secondary region has a message, that row is used and marked region = euw1. Its ts_capture is honest Ireland time, which for a Tokyo-hosted venue is roughly 105 ms later than Tokyo would have recorded. We do not adjust it.
• Consequence for latency work. Filter to region = apne1 before computing latency statistics, or the secondary fills will fatten the tail.
• Consequence for ordering. A secondary fill can carry a ts_capture later than the next primary row. Replays that need venue order should sort by seq.

The merge procedure and how often secondary fills occur are on Data quality.

Latency distribution

The difference ts_capture − ts_exchange combines the venue's internal delay, network transit and the venue clock's error. The example below shows the shape for Hyperliquid BTC-PERP trades captured in Tokyo.

SYNTHETIC: illustrative figures that show the shape of the distribution.

Three things to expect when you compute this yourself:

• Venue time is often the block or batch time. On Hyperliquid every event in a block shares a timestamp, so latency within a block varies with the event's position in it.
• Millisecond truncation adds up to 1 ms. A venue that truncates to milliseconds reports the event up to 999 µs early, which inflates measured latency by that amount.
• Negative values can happen. If a venue clock and ours differ by more than the feed latency, some rows show ts_capture before ts_exchange. We publish them as recorded and never clamp or shift venue timestamps.

For a longer treatment of measured latency and clock offsets, see Capture versus exchange timestamps.

Live stream timing

On the WebSocket stream, rows carry the same ts_capture as in the historical archive, so live and historical data line up. The rare exception is a message that reached the other region earlier but arrived at the live merger later; the historical merge then records the earlier time. Our target for added delivery latency is under 5 ms at the median, measured from ts_capture to the moment the message is written to your connection in the same region. Each delivered message also carries ts_send, our send time on the same clock, so you can measure that leg yourself; see WebSocket.