Schema reference

Every venue, every dataset, one set of columns. A Binance trade and a Hyperliquid trade have the same shape, the same types and the same clock, so a query written for one venue runs on all of them.

This page documents schema version 0.9 (draft), which becomes 1.0 when the v1 API goes live with Phase 1. Column names on this page are final for 1.0; we may still add columns before then, and we will not remove or rename any without a changelog entry. Every response and file states the version it was written with (FDC-Schema-Version header on REST, fdc.schema_version in Parquet metadata).

Conventions

• Timestamps are int64 nanoseconds since the Unix epoch, UTC. No time zones, no ISO strings, no floats.
• Prices and sizes are decimal128(38,18) in Parquet and strings in JSON and CSV, so nothing is lost to binary floating point. Trailing zeros are dropped: a venue's "0.10" becomes "0.1".
• Sizes are in base units on every venue. Contract counts are converted with contract_size from instruments, which is why a Binance coin-margined contract and a Hyperliquid perpetual can be summed directly.
• Enums are lowercase strings, dictionary-encoded in Parquet. New enum values can appear in minor versions; code that reads them should pass unknown values through instead of failing.
• Null means the venue does not publish the value for that row. We never fill a missing value with zero or a guess.

Types

Common columns

Every market-data table (all tables on this page except instruments, gaps and the two chain tables) starts with these columns, in this order.

A row's identity is (venue, symbol, seq) plus its position within the message. Where seq is null, use (venue, symbol, ts_exchange, trade_id) for trades.

Datasets

Columns below are listed after the common columns. Tags show the lowest plan that includes the dataset; plan details are on Pricing.

trades

One row per execution as printed by the venue. When a single aggressive order sweeps several levels, venues differ: some print one trade per maker, some print one aggregated trade. We keep the venue's granularity; taker_order_id lets you aggregate where it is published.

Primary key: (venue, symbol, trade_id)

{"venue":"hyperliquid","symbol":"BTC-PERP","venue_symbol":"BTC",
 "ts_exchange":1789482600127000000,"ts_capture":1789482600131482113,
 "seq":1094102785458213,"source":"fdc_capture","region":"apne1",
 "price":"104318.5","size":"0.0421","side":"buy","trade_id":"812774190531627",
 "notional":"4391.80885","taker_order_id":"141092377410","maker_order_id":"141092371988",
 "is_block":false}

quotes

Level 1: best bid and offer. One row each time either side of the top of book changes.

candles

OHLCV bars built by us from trades, bucketed on ts_exchange (source = fdc_derived), or taken from a venue's licensed historical archive, where the agreement with that venue includes one (source = venue_archive). Intervals with no trades produce no row. For candles, ts_exchange is the time of the last trade in the bucket, ts_capture is when the bucket closed in our pipeline and seq is the sequence of the last trade.

Primary key: (venue, symbol, interval, ts_open)

book_l2

Price-level order book. One row per level per update. Order books are never backfilled: history starts on the day our capture of the venue began (Hyperliquid: November 2025). Read Order book depth before replaying: the semantics of snapshots, truncation and is_last matter.

book_l3

Order-by-order book: every add, modify, cancel and fill, on venues that publish order-level data. Hyperliquid L3 is built from validator node output, so it covers every order on the book.

book_l4

All book_l3 columns, in the same order, plus participant_id, counterparty_id and entity_id. Participant attribution comes from the venue, where it publishes it; entity_id needs the chain intelligence add-on. Chain-derived attribution across venues (L4+) lives in the chain tables.

funding

Predicted and settled funding rates for perpetuals. One settled row per contract per interval; predicted rows at the venue's publication cadence. Venues settle every hour, every 4 hours or every 8 hours, so compare venues on rate_1h.

Primary key: (venue, symbol, kind, ts_funding, ts_exchange)

Hourly grid

Funding is also published on a UTC hourly grid, one row per perpetual per hour, so venues with different intervals line up without resampling. Grid rows carry the common columns plus:

open_interest

Open interest per derivative contract, at the venue's push cadence or sampled every 5 seconds where the venue only offers a REST endpoint.

liquidations

Forced closures as published by the venue. Coverage follows what each venue publishes and is confirmed with the venue before capture starts; see Venues.

mark_index

Mark, index and oracle prices for derivatives, at the venue's publication cadence.

options_chain

Top of book, mark, implied volatility and greeks per option, as published by the venue (planned for Deribit, OKX, Bybit and Binance). In v1 we do not compute IV or greeks ourselves. A full-chain snapshot is written every minute, with change rows in between.

instruments

Reference data with full history, versioned daily. Each row describes one instrument for one period; a tick size change closes the old row and opens a new one. Join on (venue, symbol) with valid_from <= ts < valid_to to get the contract specs in force at any moment. Common columns present: venue, symbol, venue_symbol, source.

Primary key: (venue, symbol, valid_from)

extended

Derived microstructure fields computed on ts_capture. Stored in long format: one row per field, variant and timestamp. The SDK (wide=True) and REST (layout=wide) can return a wide layout instead, with one column per field and variant (ofi_ml_l1, ofi_ml_l5, vpin and so on). Field definitions, parameters and units are on Extended fields.

chain_entities

Address-to-entity links from our blockchain intelligence. Core columns are below; the full column list, methods and coverage are on Chain intelligence.

chain_flows

On-chain transfers between resolved entities and venue wallets. Core columns are below; direction, trade links and confidence are documented on Chain intelligence.

gaps

Every interval that survived dual-region merging without data. A gap is recorded, never filled. How gaps are detected is on Data quality.

Primary key: gap_id

Parquet layout

Bulk files follow one path pattern for every dataset. Access is granted per customer through cross-account S3 permissions; setup is on Bulk S3.

s3://fdc-archive/{dataset}/venue={venue}/date={YYYY-MM-DD}/{symbol}.parquet

s3://fdc-archive/book_l3/venue=hyperliquid/date=2026-09-15/BTC-PERP.parquet
s3://fdc-archive/trades/venue=hyperliquid/date=2026-09-15/ETH-PERP.parquet

• Partitioning. One file per symbol per UTC day. A row belongs to the day of its ts_capture. Rows with source = venue_archive (from a venue's licensed historical archive, where the agreement with that venue includes one) have null ts_capture and seq; they are partitioned and sorted by ts_exchange.
• Sort order. Rows are sorted by ts_capture, then seq, then position within the message. Row group statistics on ts_capture let Arrow, DuckDB, Polars and Spark skip row groups when you filter on time.
• Row groups. Up to 1,000,000 rows each. Compression is zstd level 3. Enum and string columns are dictionary-encoded.
• Book files start with the 00:00 UTC full-depth snapshot, so each daily file can be replayed on its own. Further snapshots follow at every UTC hour.
• Names use the normalized symbol. Characters outside [A-Z0-9-] do not occur in symbols, so no escaping is needed.

File metadata

Each file carries key-value metadata in its Parquet footer.

Reading a file

import polars as pl

path = "s3://fdc-archive/trades/venue=hyperliquid/date=2026-09-15/BTC-PERP.parquet"
df = (
    pl.scan_parquet(path)
      .filter(pl.col("ts_capture") >= 1789482600000000000)  # 14:30 UTC
      .select("ts_capture", "price", "size", "side")
      .collect()
)

SELECT venue, side, count(*) AS n, sum(size) AS base_volume
FROM read_parquet('s3://fdc-archive/trades/venue=*/date=2026-09-15/BTC-PERP.parquet',
                  hive_partitioning = true)
GROUP BY venue, side
ORDER BY venue, side;

CSV and JSON

CSV and newline-delimited JSON contain the same columns in the same order as Parquet. CSV files have a header row, use a comma separator, quote only when a value contains a comma, and write null as an empty field. JSON rows omit nothing: null values are written as null. Both are gzip-compressed in bulk delivery (.csv.gz, .jsonl.gz).

Versioning

Within a major schema version, changes are additive: new columns go at the end of a table and new enum values may appear. Renaming a column, changing its type or changing its meaning requires a new major version, announced at least 90 days ahead on the changelog, with both versions served in parallel for at least 12 months. Data corrections are a separate mechanism (revisions, not schema versions) and are covered on Data quality.