Finance Data Cloud
DOCS/ACCESS

REST API

Every dataset is available over HTTPS from one base URL, in JSON, CSV or Parquet. This page is the reference for API v1 (draft), which goes live with Phase 1.

https://api.financedatacloud.com/v1

All endpoints are read-only GET requests and are idempotent. Responses use schema 0.9 (draft), which becomes 1.0 at Phase 1. For multi-month or multi-year pulls, the S3 archive is faster and does not count against your rate limit.

Conventions

Authentication

Send your key in the Authorization header as a bearer token. Keys in query strings are rejected. fdc_live_ keys return what your plan includes; fdc_test_ keys return the sample day (Hyperliquid BTC-PERP, ETH-PERP and SOL-PERP on 2026-09-15 UTC, every dataset). Scopes, rotation and IP allowlists are on Authentication.

HTTP
GET /v1/trades?venue=hyperliquid&symbol=BTC-PERP&start=2026-09-15T14:30:00Z&end=2026-09-15T14:31:00Z HTTP/1.1
Host: api.financedatacloud.com
Authorization: Bearer fdc_live_...
Accept-Encoding: zstd, gzip

Headers

HeaderDirectionDescription
AuthorizationrequestBearer fdc_live_.... Required.
FDC-Schema-Versionrequest, responseSchema version. Optional on requests to pin a version that is still served; always present on responses.
AcceptrequestAlternative to format: application/json, text/csv or application/vnd.apache.parquet.
Accept-Encodingrequestzstd or gzip. See Compression.
X-Request-IdresponseUnique request id, also in error bodies. Quote it in support requests.
X-Next-CursorresponseNext-page cursor for CSV responses, which have no JSON envelope.
X-RateLimit-*responseRate limit state. See Rate limits.

Time parameters

start is inclusive and end is exclusive. Both accept ISO 8601 in UTC, up to nanosecond precision (2026-09-15T14:30:00.123456789Z), a date (2026-09-15, meaning 00:00 UTC), or an int64 count of nanoseconds since the Unix epoch (1789482600000000000).

By default the range applies to ts_capture, the clock that daily files are partitioned and sorted on. Pass clock=exchange to filter on ts_exchange instead, for example to match a venue's funding times. Rows with source = venue_archive have no ts_capture, so they are always filtered on ts_exchange. Candles filter on ts_open. Background is in Timestamps and clocks.

Pagination

JSON and CSV responses are paginated. Pass the returned cursor back as cursor, with every other parameter unchanged, to get the next page. When next_cursor is null, the range is exhausted. Cursors are opaque and valid for 24 hours.

JSON ENVELOPE
{
  "data": [ ... ],
  "next_cursor": "c_9TfQ2vRkL0xWmB7d"
}
ParameterDefaultMaximum
limit (JSON)1,00010,000
limit (CSV)100,0001,000,000

A page can hold fewer rows than limit without being the last one. Parquet responses are not paginated: see below.

Formats

Choose with format=json (default), format=csv or format=parquet. If both format and Accept are sent, format wins.

  • JSON returns the envelope above. Decimals (prices, sizes, rates, amounts) are strings so no precision is lost; timestamps are integers. Nanosecond timestamps exceed 253, so parse with a library that keeps 64-bit integers.
  • CSV has a header row, comma separators, quotes only where a value contains a comma, and nulls as empty fields.
  • Parquet returns the whole range in one response, up to 31 days per request, in the same layout as the S3 archive: one file per symbol per UTC day. A single file is returned as application/vnd.apache.parquet; several are returned as a tar archive of files named by their S3 paths. Types match Schema exactly.

Compression

JSON and CSV are compressed when you send Accept-Encoding: zstd or gzip; zstd is preferred when both are offered. Parquet is compressed internally with zstd and sent without transfer encoding.

Revisions

Corrections are published as new revisions; old data is never edited in place. Requests return the current revision by default. Pass revision=1 to read a specific revision, which stays available for 24 months. See Data quality.

Venues and symbols

venue takes a venue id from the venue reference; symbol takes a normalized symbol (Symbology). Both accept comma-separated lists, up to 50 symbols per request.

Market data endpoints

Every market data endpoint accepts these parameters. Endpoint sections list only their additional parameters. Responses contain the dataset's columns as listed on Schema, including the common columns.

ParameterRequiredDescription
venueyesVenue id or comma-separated list.
symbolyes*Symbol or list. *Optional on funding, open interest and liquidations, where omitting it returns every contract.
start, endyes, noTime range. end defaults to now.
clocknocapture (default) or exchange.
fieldsnoComma-separated columns to return. Common columns are always included.
format, limit, cursor, revisionnoAs above.

Trades

GET/v1/trades

Every execution with aggressor side. Additional parameter: source (fdc_capture or venue_archive).

curl -G https://api.financedatacloud.com/v1/trades \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d symbol=BTC-PERP \
  -d start=2026-09-15T14:30:00Z -d limit=1

Quotes

GET/v1/quotes

Best bid and offer, one row per change. Additional parameter: origin (venue or book).

curl -G https://api.financedatacloud.com/v1/quotes \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d symbol=ETH-PERP \
  -d start=2026-09-15T14:30:00Z -d limit=1

Candles

GET/v1/candles

Additional parameter: interval (required): 1s, 1m, 5m, 1h or 1d. Candles are built from trades and bucketed on ts_exchange; empty buckets produce no row. Where the agreement with a venue includes its licensed historical archive, those rows carry source = "venue_archive".

curl -G https://api.financedatacloud.com/v1/candles \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d symbol=SOL-PERP -d interval=1m \
  -d start=2026-09-15T14:30:00Z -d limit=1

Order book L2

GET/v1/book/l2

One row per price level per update. The first rows of every response are a synthetic snapshot of the book as of start (is_snapshot = true, snapshot_reason = "checkpoint"), built from the nearest earlier hourly snapshot plus the deltas in between; deltas follow. Rows from one venue message share seq, and the last has is_last = true. Rebuilding the book is covered in Order book depth.

ParameterDefaultDescription
levelsfull depthTruncate to the top N levels per side.
is_snapshotbothtrue for snapshot rows only, false for deltas only.
 
curl -G https://api.financedatacloud.com/v1/book/l2 \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d symbol=BTC-PERP -d levels=20 \
  -d start=2026-09-15T14:30:00Z -d limit=2

Order book L3

GET/v1/book/l3

Order-level events: add, modify, cancel, fill. Desk plan or above. Like L2, a response starts with a synthetic snapshot of every resting order at start, in queue order. Additional parameter: event, a comma-separated filter.

curl -G https://api.financedatacloud.com/v1/book/l3 \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d symbol=BTC-PERP -d event=fill \
  -d start=2026-09-15T14:30:00Z -d limit=1

Order book L4

GET/v1/book/l4

All L3 columns plus participant_id, counterparty_id (on fills) and entity_id. entity_id is filled only for accounts with chain intelligence and is null otherwise. Desk plan or above, on venues that publish attribution. Additional parameter: participant_id to filter to one or more accounts.

curl -G https://api.financedatacloud.com/v1/book/l4 \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d symbol=BTC-PERP -d event=fill \
  -d start=2026-09-15T14:30:00Z -d limit=1

Funding

GET/v1/funding
ParameterDefaultDescription
kindbothsettled (one row per settlement) or predicted (each published change).
gridnone1h returns one row per contract per UTC hour, with the rate scaled to one hour, so venues with different intervals line up.

rate is the rate for one interval of interval_s seconds, and rate_1h is the same rate scaled to one hour. rate_ann is simple, not compounded: rate_1h times 8,760. With grid=1h, rows carry ts_grid, predicted_rate_1h, stale and age_s instead (see Schema). Deribit accrues funding continuously; its rows use an 8-hour reference interval. Cross-venue comparisons are discussed in Aligning funding across venues.

curl -G https://api.financedatacloud.com/v1/funding \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d symbol=BTC-PERP -d kind=settled \
  -d start=2026-09-15 -d limit=1

Open interest

GET/v1/open-interest

Open interest in contracts, base units and USD, at the venue's push cadence or sampled every 5 seconds (origin = "poll").

curl -G https://api.financedatacloud.com/v1/open-interest \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d symbol=ETH-PERP -d start=2026-09-15 -d limit=1

Liquidations

GET/v1/liquidations

Forced closes as published by the venue. side is the side of the liquidation order (sell closes a long). participant_id is returned on Desk and Enterprise where the venue attributes it.

curl -G https://api.financedatacloud.com/v1/liquidations \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d start=2026-09-15 -d end=2026-09-16 -d limit=1

Mark, index and oracle prices

GET/v1/mark-index
curl -G https://api.financedatacloud.com/v1/mark-index \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d symbol=BTC-PERP -d start=2026-09-15T14:30:00Z -d limit=1

Reference and derived endpoints

Instruments

GET/v1/instruments
ParameterDefaultDescription
venue, symbol, venue_symbolallFilter by venue, normalized symbol or native symbol.
baseallNormalized base asset, for example BTC.
instrument_typeallspot, perp, future or option.
as_ofnowReturn the rows in force at that time, including since-delisted instruments.
historyfalsetrue returns every version of each instrument.
 
curl -G https://api.financedatacloud.com/v1/instruments \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d symbol=BTC-PERP

Extended fields

GET/v1/extended
ParameterDefaultDescription
fieldsallField keys or field:variant pairs, comma-separated.
emitbothgrid or event to return one kind only.
layoutlongwide returns one column per field and variant.
profiledefaultCustom parameter profile (Enterprise).

Rows are filtered on ts_capture regardless of clock. Fields and variants are defined in Extended fields.

curl -G https://api.financedatacloud.com/v1/extended \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d symbol=BTC-PERP -d fields=ofi_ml:l5,vpin \
  -d emit=grid -d start=2026-09-15T14:30:00Z -d limit=2

Chain flows and entities

GET/v1/chain_flows
GET/v1/chain_entities

Requires the chain scope (Enterprise, or Desk with the add-on). /v1/chain_flows filters by entity_id, chain, venue, direction, link_type, min_confidence and time; /v1/chain_entities by address, entity_id, chain and as_of. Columns and examples are in Chain intelligence.

Gaps

GET/v1/gaps

Intervals that survived dual-region merging without data. Intervals where data is present but a quality bound was missed are not gaps; they are reported with the daily quality metrics on Data quality. Additional parameters: dataset (for example book_l3) and reason. symbol is optional; venue-wide gaps have symbol = null.

curl -G https://api.financedatacloud.com/v1/gaps \
  -H "Authorization: Bearer $FDC_API_KEY" \
  -d venue=hyperliquid -d dataset=book_l3 \
  -d start=2026-06-01 -d end=2026-07-01

Usage

GET/v1/usage

Usage for your account in a billing month. Optional parameter: month (YYYY-MM, default the current month). Not paginated and not counted against your rate limit.

curl -G https://api.financedatacloud.com/v1/usage \
  -H "Authorization: Bearer $FDC_API_KEY" -d month=2027-03

Errors

Errors use standard HTTP status codes and the same JSON body for every format. The request_id is also returned in the X-Request-Id header.

HTTP 403
{
  "error": {
    "status": 403,
    "code": "plan_required",
    "message": "book_l3 is not included in the Researcher plan.",
    "request_id": "req_01JA7Q3V8K2M4XR9T6WZB5NDHC"
  }
}
StatusCodeMeaning
400invalid_requestMalformed or unknown parameter, or a bad time format.
400invalid_cursorCursor older than 24 hours, or used with different parameters.
400range_too_largeA Parquet request spanning more than 31 days. Split it, or use S3.
400too_many_symbolsMore than 50 symbols in one request.
401missing_api_keyNo Authorization header, or a scheme other than Bearer.
401malformed_api_keyNot a prefix plus 32 base62 characters.
401invalid_api_keyWell-formed but unknown.
401revoked_api_key, expired_api_keyRevoked, or past its scheduled expiry.
403insufficient_scopeThe key lacks the scope for this interface.
403plan_requiredThe dataset, venue or profile is not in your plan.
403test_key_out_of_rangeA test key asked for data outside the sample day or symbols.
403ip_not_allowedSource address not on the key's allowlist.
403account_suspendedContact daniel@financedatacloud.com.
404not_foundUnknown endpoint, venue or symbol.
404venue_not_availableThe venue is planned but not live yet. See Coverage.
429rate_limitedRequest rate exceeded. Wait for Retry-After seconds.
500internal_errorOur fault. Safe to retry with backoff.
503unavailableTemporary overload or maintenance. Safe to retry; see Status.

Retry 429 and 5xx with backoff. Other 4xx errors will not succeed until the request, key or plan changes.