Deribit History Client

A lightweight and structured Python client for the Deribit Public Historical Market Data API, providing clean access to instruments and trade data — with an optional schema-based API change detection system.

This project is intentionally simple, dependency-light, and easy to integrate into trading analytics pipelines, automation scripts, or monitoring systems.

---

🗄️ Key Features

• High-level DeribitHistoryClient for Deribit historical data
• Low-level HTTP request layer (read.py)
• JSON Schema validation for API shape consistency
• Pre-generated schemas included with the package
• Script to regenerate schemas automatically
• Fully mocked unit tests
• Optional integration test using real Deribit live API (@pytest.mark.external)
• Sphinx documentation for the entire library
• GitHub Actions for linting, testing, and documentation deployment

---

⏱️ Timestamp Caveat (Important for Backtesting)

The historical trade data provided by the Deribit API contains exchange timestamps only.

No local receive timestamps or network latency–adjusted times are available. This means:

• All events are timestamped at the exchange matching engine level
• There is no notion of when data was observed by a client

As a consequence, this dataset is not suitable for market microstructure research or high-frequency backtesting where precise event ordering, latency modeling, or order book reaction timing is required.

However, it is perfectly appropriate for:

• Strategy research on higher timeframes (seconds and above)
• Statistical analysis and signal development
• Backtests that do not rely on execution-level timing accuracy

In short: great for macro/strategy-level work — not for HFT or latency-sensitive simulations.

---

📦 Project Structure

src/deribit_history_client/
    client.py
    read.py
    schemas/
        get_instrument.json
        get_instruments.json
        get_trades_by_sequence.json

scripts/
    generate_schemas.py

tests/
    unit/
    integration/

docs/
    conf.py
    index.rst
    api.rst

.github/workflows/
    ci.yaml
    lint.yaml
    docs.yaml

pyproject.toml
README.md

---

📥 Installation

From source

pip install -e .

From GitHub

pip install git+https://github.com/bxvtr/deribit-history-client.git

---

⚡ Quickstart Example

from deribit_history_client.client import DeribitHistoryClient

client = DeribitHistoryClient()

instrument = client.get_instrument("BTC-PERPETUAL")
print(instrument)

trades = client.get_trades_by_sequence("BTC-PERPETUAL", 1, 5000)
print(trades)

---

🧪 Running Tests

Unit tests:

pytest

Integration tests using the live Deribit API:

pytest -m external

---

🧩 API Shape Validation (Schema Checking)

This project includes JSON schema files under:

src/deribit_history_client/schemas/

To verify that Deribit’s API has not changed its response structure:

client.perform_api_check()

If the structure deviates from expectations, the validator prints warnings and details.

---

🛠 Regenerating JSON Schemas

A development-only script is included:

python scripts/generate_schemas.py

This script:

• Calls the live Deribit API
• Builds JSON Schemas using Genson
• Writes new schemas with metadata ($schema_generated_from, $generated_at)

Use this only when the API format changes and the schemas need to be updated.

---

📚 Documentation

Online documentation

Build locally:

cd docs
make html

Open:

docs/_build/html/index.html

---

🧑‍💻 Development

Install dev dependencies:

pip install -e .[dev]

Run Ruff:

ruff check .

Build documentation:

cd docs
make html