Python SDK

The fdc package wraps the REST API, the WebSocket stream and bulk file downloads behind one client. Every method returns the same normalized rows, whichever transport delivers them.

This reference covers fdc 0.9, which targets API v1 (draft) and schema 0.9. If you have not made a request yet, start with the quickstart.

Install

pip install fdc                 # core: iterators of dicts, Arrow tables, downloads
pip install "fdc[pandas]"       # adds .to_pandas()
pip install "fdc[polars]"       # adds .to_polars()
pip install "fdc[all]"          # both

Python 3.9 or later on Linux, macOS and Windows. The core package depends on httpx, websockets and pyarrow.

Client

from fdc import Client

fdc = Client(
    api_key="fdc_live_...",     # or leave out and set FDC_API_KEY
    timeout=30.0,
    region="ap-northeast-1",
    retries=3,
)

A client holds a connection pool and is safe to share between threads. Use it as a context manager, or call fdc.close(), to release connections and stop open streams.

Common arguments

Every data method accepts these keyword arguments. Method-specific arguments are listed under each method.

Methods

Data methods return a Stream (see Return types). Nothing is fetched until you iterate it or convert it.

trades, quotes

source filters trades to "fdc_capture" or "venue_archive". origin filters quotes to "venue" or "book".

candles

interval is "1s", "1m", "5m", "1h" or "1d". With live=True a candle is yielded when its bucket closes.

book

The first rows are a synthetic snapshot of the book as of start, then deltas (L2) or order events (L3, L4) follow. Semantics are in Order book depth.

funding

kind is "settled", "predicted" or None for both. grid="1h" returns one row per contract per UTC hour with the rate scaled to one hour, so Hyperliquid's hourly funding and Binance's 8-hour funding line up row for row. Omitting symbol returns every perpetual on the selected venues.

open_interest, liquidations, mark_index

extended

fields takes field keys ("ofi_ml", "vpin", "queue", "cxl_fill", "resil", "lambda", "markout", "part") or "field:variant" pairs. emit is "grid", "event" or None for both. wide=True returns one column per field and variant. Definitions are in Extended fields.

instruments

Reference data with full history. as_of returns the rows in force at a past time, including instruments since delisted; history=True returns every version.

gaps

Recorded gaps: intervals every capture region missed. reason filters on the gap reason, for example "seq_break". See Data quality.

chain_flows, chain_entities

Need the chain scope. Columns are in Chain intelligence.

usage

Requests, rows and bytes for the current billing month, or for month="2027-03".

download

Writes one file per symbol per UTC day under path, in the same layout as the S3 archive, and returns the file paths. format is "parquet", "csv" (written as .csv.gz) or "json" (.jsonl.gz). Downloads go through the API with your key and need the historical scope; no AWS account is required. Each file is checked against the fdc.sha256 digest before the call returns. Omitting symbol downloads every symbol of the dataset on that venue.

paths = fdc.download(
    dataset="liquidations",
    venue="hyperliquid",
    start="2026-07-01", end="2026-08-01",
    path="./fdc-data",
)
# ['./fdc-data/liquidations/venue=hyperliquid/date=2026-07-01/BTC-PERP.parquet', ...]

For many months of book data, reading S3 directly is faster.

Return types

A Stream is an iterator of plain dicts, one per row, with the columns in Schema. Decimal columns (prices, sizes, rates, amounts) are decimal.Decimal. Timestamps are int nanoseconds.

Converting reads the stream to its end, so to_pandas() and to_polars() need a finite range; calling them on a live=True stream with no end raises ValueError. A stream can be iterated once.

Live mode

With live=True the SDK delivers history and live data as one stream, in sequence order, with each message exactly once. The handover works like this:

The live buffer holds up to 2,000,000 messages (buffer= to change it). If backfill is slow enough to overflow it, the SDK discards the buffer, extends the backfill and resubscribes with resume_from, so no message is lost. On a disconnect the client reconnects and resumes from stream.last_seq; if the outage outlasts the server's replay buffer, the missing range is backfilled over REST first. Your loop keeps running in both cases. If you pass end as well, the stream finishes when ts_capture passes end.

A gap in the live stream is handled by on_gap exactly as in history: with the default the stream raises fdc.GapError, and with "resync" it continues from the venue snapshot that follows the gap.

def went_live(stream):
    log.info("caught up at %s", stream.last_seq)

with fdc.book(
    venue="hyperliquid", symbol="BTC-PERP", depth="L3",
    start="2027-01-15T00:00:00Z", live=True,
    on_live=went_live, on_gap="resync",
) as book:
    for msg in book:
        handle(msg)

With several venues, rows are ordered on ts_capture during backfill and yielded in arrival order once live, since sorting would add latency. Each (venue, symbol) stays in seq order in both phases.

Async usage

AsyncClient takes the same constructor arguments and has the same methods. Data methods return an AsyncStream, iterated with async for; conversions are awaited.

import asyncio
from fdc import AsyncClient

async def main(queue):
    async with AsyncClient() as fdc:
        hourly = await fdc.funding(
            venues=["hyperliquid", "binance"], symbol="BTC-PERP",
            grid="1h", start="2027-09-01", end="2027-10-01",
        ).to_polars()

        async for t in fdc.trades(
            venue="hyperliquid", symbol="SOL-PERP",
            start="2027-01-15", live=True,
        ):
            await queue.put(t)

asyncio.run(main(asyncio.Queue()))

One AsyncClient can run many streams concurrently on one event loop. Streams on the same client share WebSocket connections, up to 250 subscriptions per connection. Plan limits are on Rate limits.

Exceptions

All exceptions can be imported from fdc and derive from fdc.FdcError, which carries status, code, message and request_id. The codes are the API's error codes; quote the request_id when you contact support.

import time
import fdc as fdclib

try:
    df = fdc.book(venue="hyperliquid", symbol="BTC-PERP", depth="L4",
                  start="2026-09-15", end="2026-09-15T01:00:00Z").to_polars()
except fdclib.PermissionDeniedError as e:
    print(e.code, e.request_id)       # plan_required req_01JA7Q3V8K2M...
except fdclib.RateLimitError as e:
    time.sleep(e.retry_after)

Logging

The SDK logs through the standard logging module under the fdc logger and installs no handlers. At INFO it logs phase changes, reconnects and gaps. At DEBUG it logs each request with URL, status, duration and request_id, and every WebSocket control frame. Keys are always masked to the prefix and last four characters (fdc_live_…3dFu).

import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger("fdc").setLevel(logging.DEBUG)

# or, without code changes:  FDC_LOG=debug python script.py

Versions and compatibility

• The SDK follows semantic versioning. Until 1.0, a minor release (0.9 to 0.10) may change behavior; patch releases do not. Pin with fdc~=0.9.0 in production.
• Each SDK minor version matches a schema version. fdc 0.9.x sends FDC-Schema-Version: 0.9 on every request and checks the version on every response.
• Breaking schema changes are announced at least 90 days ahead, and the old and new versions are served in parallel for at least 12 months. The SDK logs a warning when your pinned version has a scheduled end date.
• Optional dependencies: pandas 1.5 or later, polars 0.20 or later.

Release notes for the SDK, the APIs and the schema are kept together in the changelog.