OKX Quant Toolkit

An open, read-only toolkit for collecting public OKX market data and turning it into research-ready datasets.

It covers spot, margin, perpetual swaps, futures and options. It downloads candles, trades, funding, order books, open interest, mark and index prices, instrument metadata and derivatives statistics. It can also record bounded WebSocket feeds and rebuild an incremental local book.

Everything needed to learn and run the project lives in this repository. No API key is required. The package cannot place or cancel orders.

Prefer Spanish? Read README_ES.md.

What is included

Data	REST	WebSocket	Research examples
Trade-price candles	Yes	Yes	returns, momentum, volatility
Mark and index candles	Yes	Yes	basis, dislocations, risk context
Individual trades	Yes	Yes	signed flow, tick bars, impact
Order books and RPI depth	Yes	Yes	spread, imbalance, liquidity
Funding rates	Yes	Yes	carry, crowded positioning
Open interest	Yes	Yes	leverage and regime changes
Tickers, mark and index levels	Yes	Yes	monitoring and joins
Instrument metadata	Yes	Yes	valid universes and contract units
Option summaries and Greeks	Yes	Yes	volatility surfaces
Liquidation events	—	Yes	stress and cascade studies
Contract statistics	Yes	—	long/short and taker panels

The dataset map in DATA.md explains fields, units, retention and common mistakes. Run oqt catalog to inspect the same map from the terminal.

Quick start

Python 3.10 or newer is required.

python -m venv .venv
python -m pip install -e .[all]
oqt demo

Download confirmed hourly candles. The interval is [start, end), in UTC.

oqt candles BTC-USDT --bar 1H \
  --start 2025-01-01 --end 2025-02-01 \
  --output data/btc_usdt_1h.parquet

Download mark-price bars for a perpetual swap.

oqt candles BTC-USDT-SWAP --bar 1H --price-type mark \
  --start 2025-01-01 --end 2025-02-01 \
  --output data/btc_swap_mark_1h.csv

Use Python when a research pipeline needs the dataframe directly.

from okx_quant_toolkit import CandleRequest, OkxRestClient, audit_candles

with OkxRestClient() as client:
    candles = client.fetch_candles(CandleRequest(
        "BTC-USDT", "1H", "2025-01-01", "2025-02-01"
    ))

report = audit_candles(candles, "1H", start="2025-01-01", end="2025-02-01")
report.require_clean()

See the full quick start for trades, funding, books, bulk ranges and streams.

Design rules

• Read-only public data. There is no account or execution code.
• UTC everywhere. Ranges are half-open.
• Fixed hosts. User input never becomes a network host.
• Retries are bounded. Timeouts are explicit.
• Raw WebSocket messages are kept as NDJSON before interpretation.
• Canonical dataframes are sorted and typed.
• CSV and Parquet outputs receive optional provenance sidecars.
• Large ranges can be split into resumable chunks with a manifest.
• Data-quality failures are visible. They are never silently filled.

Project map

src/okx_quant_toolkit/  REST, WebSocket, schemas, books, storage and audits
docs/                   bilingual guides and research methodology
examples/               complete scripts and a synthetic offline sample
notebooks/              English and Spanish teaching notebooks
tests/                  deterministic tests with no live network dependency
.github/workflows/      inactive template for explicitly approved one-off checks

Important OKX details

Instrument IDs contain hyphens: BTC-USDT, BTC-USDT-SWAP and dated futures or option IDs. Size units change by product. Spot size is normally an asset amount. Derivative size is normally contracts. Always join instrument metadata before comparing notional exposure.

The candle fields volume, volume_currency and volume_quote have product-dependent meanings. The confirmed field distinguishes a closed bar from the current bar. Historical downloads exclude incomplete bars by default.

Funding intervals can change. Do not hard-code eight hours. Use the timestamps returned with each rate.

Incremental books use prevSeqId and seqId. A repeated sequence may be a valid keepalive. The legacy checksum was deprecated and may be zero, so this toolkit validates sequence continuity instead.

REST market-data services can use independent caches. Two nearby requests may not be perfectly monotonic. Prefer one stream for event ordering and preserve exchange and receipt timestamps.

Documentation

• Data dictionary
• Quick start · Spanish
• Choosing data · Spanish
• Methodology · Spanish
• Order-book reconstruction · Spanish
• Research recipes · Spanish
• Examples

Scope and responsibility

This is research infrastructure, not a profitable strategy and not investment advice. Public data can be delayed, revised, incomplete or unavailable. Validate files, model fees and slippage, prevent look-ahead bias, and test execution assumptions before trusting a result.

Contributions are welcome. Read CONTRIBUTING.md, SECURITY.md and LICENSE.

GitHub Actions is intentionally disabled by default. This repository is a public distribution and archival surface; routine verification runs locally.