debyko-ccxt 0.1.0__tar.gz

debyko_ccxt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DEBYKO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

debyko_ccxt-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include tests/conftest.py
+recursive-include tests/fixtures *.json

debyko_ccxt-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: debyko-ccxt
+Version: 0.1.0
+Summary: Read-only CCXT-compatible funding, open interest and liquidations from DEBYKO
+Author: DEBYKO
+License-Expression: MIT
+Project-URL: Repository, https://github.com/debyko/debyko-ccxt
+Project-URL: Issues, https://github.com/debyko/debyko-ccxt/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Requires-Dist: ccxt==4.5.92; extra == "dev"
+Dynamic: license-file
+
+# debyko-ccxt
+
+Four synchronous, read-only methods with [CCXT unified structures](https://github.com/ccxt/ccxt/wiki/Manual), backed by [DEBYKO](https://docs.debyko.com/): funding settlements, current funding rates, sampled open interest and liquidation events. MIT. Python ≥3.10; **zero runtime dependencies**. Contract tests use CCXT 4.5.92.
+
+## Keep CCXT for orders; swap one line for history
+
+After the owner publishes: `pip install debyko-ccxt`. Before publication: `pip install git+https://github.com/debyko/debyko-ccxt.git@main`.
+
+```python
+import os
+import ccxt
+from debyko_ccxt import DebykoCCXT
+
+orders = ccxt.binance()  # retain your existing exchange/order configuration
+history = DebykoCCXT(api_key=os.environ["DEBYKO_API_KEY"], venue="BINANCE-USDM")
+symbol = "BTC/USDT:USDT"
+since = orders.parse8601("2026-11-08T00:00:00Z")
+funding = history.fetchFundingRateHistory(symbol, since, limit=100)
+oi = history.fetchOpenInterestHistory(symbol, "5m", since, limit=100)
+```
+
+CCXT is needed by your order code, not by this package. There are no order, balance or withdrawal methods.
+
+| Method (snake_case aliases also available) | DEBYKO endpoint |
+| --- | --- |
+| `fetchFundingRateHistory(symbol, since=None, limit=None, params=None)` | `GET /v2/funding/settlements` |
+| `fetchFundingRates(symbols=None, params=None)` | Read-only `POST /v2/snapshots` |
+| `fetchOpenInterestHistory(symbol, timeframe="5m", since=None, limit=None, params=None)` | Read-only `POST /v2/snapshots/history` |
+| `fetchLiquidations(symbol, since=None, limit=None, params=None)` | Read-only `POST /v2/liquidations` |
+
+Native perpetual identities come from `GET /v2/instruments`, fetched per call. Unified symbols keep quote/settlement distinctions, e.g. `BTC/USDT:USDT` versus `BTC/USDC:USDC`. An unknown settlement identity or ambiguous mapping raises `BadSymbol`; it is never guessed.
+
+`since` is inclusive Unix milliseconds; `params={"until": ...}` sets the inclusive historical end. Default limit: 1,000 rows. Without `since`, funding uses the API's default settlement window (currently seven days), OI uses the latest requested number of buckets, liquidations use the last hour. Current funding rejects `until`. OI intervals: `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `12h`, `1d`. Pagination/chunking is automatic, capped at **100 HTTP requests per method call**, including registry reads; change via `params={"max_requests": ...}`. Budget exhaustion raises instead of returning a silent partial answer. HTTP timeout defaults to 20 seconds.
+
+## Structure and units
+
+- Numbers are floats; timestamps are integer milliseconds and `datetime` is UTC ISO 8601. Every result's `info` retains DEBYKO's `venue_ts` and `status`, with source metadata. Funding history uses settlement time; OI uses `bucket_end`, retaining the actual source time separately in `info`.
+- Funding is the published **fraction for the native interval**, never an 8h-normalized rate. `fundingTimestamp` is the upcoming payment time; a subsequent period/rate is not invented.
+- OI amount and liquidation `contracts` are contracts, not base currency. Conversion uses the registry's contract size; base and quote values stay distinct. No historical price is invented to fill `openInterestValue`. Unknown fields are `None`.
+- Non-present funding/OI retain their status and have `None` values, not zero. OI is an as-of sample, not an exchange aggregate. Liquidation side is the forced order's `buy`/`sell`, not the liquidated position's side. Event gaps remain in `info`; an empty window with known gaps raises `DataUnavailable`, as `[]` would hide them.
+- These are CCXT-shaped answers, not an Exchange subclass or CCXT's exception hierarchy. API refusals raise `DebykoError` with `.status` and `.response`; there are no automatic retries of 429/5xx and no exchange fallback.
+
+## Authentication / explicit x402
+
+`DebykoCCXT()` reads `DEBYKO_API_KEY`. Keys go only in the Authorization header, never URLs. Redirects are refused. No key means an authentication error **before any network call** by default.
+
+Keyless access requires `DebykoCCXT(api_key="", x402=True, payment_handler=sign)`. `sign(challenge)` must validate an **x402 v2** challenge, enforce your network/asset/payee/spending policy, and return the encoded `PAYMENT-SIGNATURE` header. The package retries that request once. It contains no wallet or signer, never pays implicitly, and never falls back from an invalid key to payment. Registry/page requests can each require payment: budget these in your signer. No real payments are made by tests.
+
+## Which exchange windows does this avoid?
+
+The adapter reads DEBYKO's stored observations instead of the venue's historical endpoint. It avoids the **native API** constraints below only where DEBYKO actually retained the requested data and your plan permits it. It does not extend DEBYKO retention, recover pre-collection history, or guarantee more history than the exchange has today.
+
+| Native endpoint constraint (checked 8 Nov 2026) | When using this adapter |
+| --- | --- |
+| [OKX funding history: up to three months](https://www.okx.com/docs-v5/en/#public-data-rest-api-get-funding-rate-history) | Read retained DEBYKO settlements, independent of OKX's rolling window. No promise of >3 months currently recorded. |
+| [Binance USD-M OI statistics: latest one month, ≤500 per call](https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Open-Interest-Statistics) | Read retained DEBYKO OI samples with automatic chunking; sample semantics differ from native statistics. |
+| [Bybit funding history: ≤200 per call](https://bybit-exchange.github.io/docs/v5/market/history-fund-rate) | Automatic DEBYKO settlement pagination. This is a page limit, not a claimed retention limit. |
+
+## Develop / publish
+
+`pip install -e '.[dev]'`, then `ruff check .`, `ruff format --check .`, `pytest`, `python -m build`, `twine check dist/*`.
+Fixtures are recorded public market responses from 8 Nov 2026, with no credentials. Every test blocks external connections. CI tests Python 3.10/3.12/3.14 and installs the built wheel without dependencies.
+
+**Not published automatically.** The owner configures PyPI Trusted Publishing for this repository, workflow `publish.yml`, environment `pypi` (prefer a required reviewer), then manually dispatches **Publish to PyPI** on `main`. The workflow reruns CI and publishes its exact built artifacts, without repository API tokens. It does not run on pushes or tags. Python first; TypeScript is deferred.

debyko_ccxt-0.1.0/README.md

@@ -0,0 +1,64 @@
+# debyko-ccxt
+
+Four synchronous, read-only methods with [CCXT unified structures](https://github.com/ccxt/ccxt/wiki/Manual), backed by [DEBYKO](https://docs.debyko.com/): funding settlements, current funding rates, sampled open interest and liquidation events. MIT. Python ≥3.10; **zero runtime dependencies**. Contract tests use CCXT 4.5.92.
+
+## Keep CCXT for orders; swap one line for history
+
+After the owner publishes: `pip install debyko-ccxt`. Before publication: `pip install git+https://github.com/debyko/debyko-ccxt.git@main`.
+
+```python
+import os
+import ccxt
+from debyko_ccxt import DebykoCCXT
+
+orders = ccxt.binance()  # retain your existing exchange/order configuration
+history = DebykoCCXT(api_key=os.environ["DEBYKO_API_KEY"], venue="BINANCE-USDM")
+symbol = "BTC/USDT:USDT"
+since = orders.parse8601("2026-11-08T00:00:00Z")
+funding = history.fetchFundingRateHistory(symbol, since, limit=100)
+oi = history.fetchOpenInterestHistory(symbol, "5m", since, limit=100)
+```
+
+CCXT is needed by your order code, not by this package. There are no order, balance or withdrawal methods.
+
+| Method (snake_case aliases also available) | DEBYKO endpoint |
+| --- | --- |
+| `fetchFundingRateHistory(symbol, since=None, limit=None, params=None)` | `GET /v2/funding/settlements` |
+| `fetchFundingRates(symbols=None, params=None)` | Read-only `POST /v2/snapshots` |
+| `fetchOpenInterestHistory(symbol, timeframe="5m", since=None, limit=None, params=None)` | Read-only `POST /v2/snapshots/history` |
+| `fetchLiquidations(symbol, since=None, limit=None, params=None)` | Read-only `POST /v2/liquidations` |
+
+Native perpetual identities come from `GET /v2/instruments`, fetched per call. Unified symbols keep quote/settlement distinctions, e.g. `BTC/USDT:USDT` versus `BTC/USDC:USDC`. An unknown settlement identity or ambiguous mapping raises `BadSymbol`; it is never guessed.
+
+`since` is inclusive Unix milliseconds; `params={"until": ...}` sets the inclusive historical end. Default limit: 1,000 rows. Without `since`, funding uses the API's default settlement window (currently seven days), OI uses the latest requested number of buckets, liquidations use the last hour. Current funding rejects `until`. OI intervals: `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `12h`, `1d`. Pagination/chunking is automatic, capped at **100 HTTP requests per method call**, including registry reads; change via `params={"max_requests": ...}`. Budget exhaustion raises instead of returning a silent partial answer. HTTP timeout defaults to 20 seconds.
+
+## Structure and units
+
+- Numbers are floats; timestamps are integer milliseconds and `datetime` is UTC ISO 8601. Every result's `info` retains DEBYKO's `venue_ts` and `status`, with source metadata. Funding history uses settlement time; OI uses `bucket_end`, retaining the actual source time separately in `info`.
+- Funding is the published **fraction for the native interval**, never an 8h-normalized rate. `fundingTimestamp` is the upcoming payment time; a subsequent period/rate is not invented.
+- OI amount and liquidation `contracts` are contracts, not base currency. Conversion uses the registry's contract size; base and quote values stay distinct. No historical price is invented to fill `openInterestValue`. Unknown fields are `None`.
+- Non-present funding/OI retain their status and have `None` values, not zero. OI is an as-of sample, not an exchange aggregate. Liquidation side is the forced order's `buy`/`sell`, not the liquidated position's side. Event gaps remain in `info`; an empty window with known gaps raises `DataUnavailable`, as `[]` would hide them.
+- These are CCXT-shaped answers, not an Exchange subclass or CCXT's exception hierarchy. API refusals raise `DebykoError` with `.status` and `.response`; there are no automatic retries of 429/5xx and no exchange fallback.
+
+## Authentication / explicit x402
+
+`DebykoCCXT()` reads `DEBYKO_API_KEY`. Keys go only in the Authorization header, never URLs. Redirects are refused. No key means an authentication error **before any network call** by default.
+
+Keyless access requires `DebykoCCXT(api_key="", x402=True, payment_handler=sign)`. `sign(challenge)` must validate an **x402 v2** challenge, enforce your network/asset/payee/spending policy, and return the encoded `PAYMENT-SIGNATURE` header. The package retries that request once. It contains no wallet or signer, never pays implicitly, and never falls back from an invalid key to payment. Registry/page requests can each require payment: budget these in your signer. No real payments are made by tests.
+
+## Which exchange windows does this avoid?
+
+The adapter reads DEBYKO's stored observations instead of the venue's historical endpoint. It avoids the **native API** constraints below only where DEBYKO actually retained the requested data and your plan permits it. It does not extend DEBYKO retention, recover pre-collection history, or guarantee more history than the exchange has today.
+
+| Native endpoint constraint (checked 8 Nov 2026) | When using this adapter |
+| --- | --- |
+| [OKX funding history: up to three months](https://www.okx.com/docs-v5/en/#public-data-rest-api-get-funding-rate-history) | Read retained DEBYKO settlements, independent of OKX's rolling window. No promise of >3 months currently recorded. |
+| [Binance USD-M OI statistics: latest one month, ≤500 per call](https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Open-Interest-Statistics) | Read retained DEBYKO OI samples with automatic chunking; sample semantics differ from native statistics. |
+| [Bybit funding history: ≤200 per call](https://bybit-exchange.github.io/docs/v5/market/history-fund-rate) | Automatic DEBYKO settlement pagination. This is a page limit, not a claimed retention limit. |
+
+## Develop / publish
+
+`pip install -e '.[dev]'`, then `ruff check .`, `ruff format --check .`, `pytest`, `python -m build`, `twine check dist/*`.
+Fixtures are recorded public market responses from 8 Nov 2026, with no credentials. Every test blocks external connections. CI tests Python 3.10/3.12/3.14 and installs the built wheel without dependencies.
+
+**Not published automatically.** The owner configures PyPI Trusted Publishing for this repository, workflow `publish.yml`, environment `pypi` (prefer a required reviewer), then manually dispatches **Publish to PyPI** on `main`. The workflow reruns CI and publishes its exact built artifacts, without repository API tokens. It does not run on pushes or tags. Python first; TypeScript is deferred.

debyko_ccxt-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "debyko-ccxt"
+version = "0.1.0"
+description = "Read-only CCXT-compatible funding, open interest and liquidations from DEBYKO"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "DEBYKO"}]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/debyko/debyko-ccxt"
+Issues = "https://github.com/debyko/debyko-ccxt/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.8", "build>=1.2", "twine>=6", "ccxt==4.5.92"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]

debyko_ccxt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

debyko_ccxt-0.1.0/src/debyko_ccxt/__init__.py

@@ -0,0 +1,13 @@
+"""Small read-only CCXT-shaped adapter. There is no runtime CCXT dependency."""
+
+from .client import DebykoCCXT
+from .transport import AuthenticationError, BadResponse, BadSymbol, DataUnavailable, DebykoError
+
+__all__ = [
+    "DebykoCCXT",
+    "DebykoError",
+    "AuthenticationError",
+    "BadResponse",
+    "BadSymbol",
+    "DataUnavailable",
+]

debyko_ccxt-0.1.0/src/debyko_ccxt/client.py

@@ -0,0 +1,316 @@
+"""Four read-only methods; snake_case and CCXT's camelCase aliases."""
+
+import json
+import re
+import time
+
+from . import mapping as m
+from .transport import BadResponse, BadSymbol, DataUnavailable, Rest
+
+TIMEFRAMES = {
+    "1m": 60_000,
+    "5m": 300_000,
+    "15m": 900_000,
+    "30m": 1_800_000,
+    "1h": 3_600_000,
+    "4h": 14_400_000,
+    "12h": 43_200_000,
+    "1d": 86_400_000,
+}
+SYMBOL = re.compile(r"^[A-Z0-9._-]+/[A-Z0-9._-]+:[A-Z0-9._-]+$")
+DAY = 86_400_000
+
+
+def integer(value, name, minimum=0):
+    if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
+        raise ValueError(f"{name} must be an integer >= {minimum}")
+    return value
+
+
+def _symbol(value):
+    if not isinstance(value, str) or not SYMBOL.fullmatch(value):
+        raise BadSymbol("Use a unified perpetual symbol, e.g. BTC/USDT:USDT")
+    return value
+
+
+class DebykoCCXT:
+    def __init__(
+        self, api_key=None, venue="BINANCE-USDM", *, x402=False, payment_handler=None, timeout=20
+    ):
+        if not isinstance(venue, str) or not re.fullmatch(r"[A-Z0-9-]+", venue):
+            raise ValueError("venue must be a DEBYKO venue code")
+        if (
+            isinstance(timeout, bool)
+            or not isinstance(timeout, (int, float))
+            or not 0 < timeout <= 120
+        ):
+            raise ValueError("timeout must be in (0, 120] seconds")
+        self.venue = venue
+        self._rest = Rest(api_key, x402=x402, payment_handler=payment_handler, timeout=timeout)
+
+    @staticmethod
+    def _now():
+        return time.time_ns() // 1_000_000
+
+    def _call(self, params):
+        params = {} if params is None else dict(params)
+        if set(params) - {"until", "max_requests"}:
+            raise ValueError("Supported params: until (inclusive ms), max_requests")
+        until = integer(params.get("until", self._now()), "until")
+        maximum = integer(params.get("max_requests", 100), "max_requests", 1)
+        count = 0
+
+        def call(method, path, **kwargs):
+            nonlocal count
+            count += 1
+            if count > maximum:
+                raise DataUnavailable(
+                    "Request budget reached; narrow the window or increase max_requests"
+                )
+            return self._rest.request(method, path, **kwargs)
+
+        return call, until
+
+    def _markets(self, call, requested):
+        """Paginated registry, fetched per call; no cached data or cross-key access."""
+        query = {
+            "where": "venue = " + self.venue,
+            "kind": "perpetual",
+            "include_raw": "true",
+            "number_format": "string",
+            "limit": 500,
+        }
+        result, cursors, unsupported = {}, set(), False
+        while True:
+            page = call("GET", "/v2/instruments", query=query.copy())
+            for row in page["items"]:
+                if row.get("venue") != self.venue or not row.get("instrument"):
+                    continue
+                try:
+                    listing = m.market(row)
+                except BadSymbol:
+                    unsupported = True
+                    continue
+                key = listing["symbol"]
+                if key in result and result[key]["id"] != listing["id"]:
+                    raise BadSymbol("Ambiguous unified symbol: " + key)
+                result[key] = listing
+            cursor = page.get("next_cursor")
+            if not cursor:
+                break
+            if cursor in cursors:
+                raise BadResponse("Registry cursor repeated")
+            cursors.add(cursor)
+            query["cursor"] = cursor
+        if requested is None:
+            if unsupported:
+                raise BadSymbol(
+                    "Some listings lack settlement identity; request explicit supported symbols"
+                )
+            return result
+        for key in requested:
+            if key not in result:
+                raise BadSymbol(f"No unambiguous supported {key} listing on {self.venue}")
+        return {key: result[key] for key in requested}
+
+    def _where(self, listing):
+        return f"venue = {self.venue} and symbol = {json.dumps(listing['id'])}"
+
+    @staticmethod
+    def _limit(limit):
+        return 1000 if limit is None else integer(limit, "limit", 1)
+
+    @staticmethod
+    def _item(payload, listing, venue):
+        rows = [
+            row
+            for row in payload["items"]
+            if row.get("venue") == venue and row.get("venue_symbol") == listing["id"]
+        ]
+        if len(rows) != 1:
+            raise DataUnavailable("Expected exactly one selected listing", response=payload)
+        return rows[0]
+
+    def fetch_funding_rates(self, symbols=None, params=None):
+        if params and "until" in params:
+            raise ValueError("Current funding rates do not accept a historical until")
+        if symbols is not None:
+            if isinstance(symbols, str):
+                raise BadSymbol("symbols must be a sequence of unified symbols")
+            symbols = [_symbol(s) for s in symbols]
+            if not symbols:
+                return {}
+        call, _ = self._call(params)
+        markets = self._markets(call, symbols)
+        result = {}
+        # Bounded snapshot selections, including when a venue lists >500 markets.
+        listings = list(markets.values())
+        for offset in range(0, len(listings), 100):
+            batch = listings[offset : offset + 100]
+            ids = ", ".join(json.dumps(x["id"]) for x in batch)
+            data = call(
+                "POST",
+                "/v2/snapshots",
+                body={
+                    "where": f"venue = {self.venue} and symbol in ({ids})",
+                    "kind": "perpetual",
+                    "layers": ["funding", "mark"],
+                    "units": "published",
+                    "number_format": "string",
+                },
+            )
+            for listing in batch:
+                row = self._item(data, listing, self.venue)
+                result[listing["symbol"]] = m.funding_rate(row, listing)
+        return result
+
+    def fetch_funding_rate_history(self, symbol, since=None, limit=None, params=None):
+        key, limit = _symbol(symbol), self._limit(limit)
+        if since is not None:
+            since = integer(since, "since")
+        call, until = self._call(params)
+        if since is not None and since > until:
+            raise ValueError("since must be <= until")
+        listing = self._markets(call, [key])[key]
+        query = {
+            "where": self._where(listing),
+            "to": m.iso(until),
+            "order": "asc" if since is not None else "desc",
+            "number_format": "string",
+        }
+        if since is not None:
+            query["from"] = m.iso(since - 1)  # API (from,to]; CCXT since is inclusive
+        rows, cursors = [], set()
+        while len(rows) < limit:
+            query["limit"] = min(1000, limit - len(rows))
+            data = call("GET", "/v2/funding/settlements", query=query.copy())
+            if any(r.get("venue") == self.venue for r in data.get("not_recorded", [])):
+                raise DataUnavailable("Settlements are not recorded for this venue", response=data)
+            for row in data["items"]:
+                if row.get("venue") != self.venue or row.get("venue_symbol") != listing["id"]:
+                    raise BadResponse("Settlement page includes an unexpected listing")
+                item = m.funding_history(row, key)
+                if (since is None or since <= item["timestamp"]) and item["timestamp"] <= until:
+                    rows.append(item)
+            cursor = data.get("next_cursor")
+            if not cursor:
+                break
+            if cursor in cursors:
+                raise BadResponse("Settlement cursor repeated")
+            cursors.add(cursor)
+            query["cursor"] = cursor
+        return sorted(rows[:limit], key=lambda r: r["timestamp"])
+
+    def fetch_open_interest_history(
+        self, symbol, timeframe="5m", since=None, limit=None, params=None
+    ):
+        key, limit = _symbol(symbol), self._limit(limit)
+        if timeframe not in TIMEFRAMES:
+            raise ValueError("Unsupported DEBYKO sample interval")
+        step = TIMEFRAMES[timeframe]
+        call, until = self._call(params)
+        end = until // step * step
+        first = end - (limit - 1) * step if since is None else integer(since, "since")
+        if first > until:
+            raise ValueError("since must be <= until")
+        start = ((first + step - 1) // step) * step
+        listing = self._markets(call, [key])[key]
+        result = []
+        while start <= end and len(result) < limit:
+            last = min(end, start + (min(2000, limit - len(result)) - 1) * step)
+            data = call(
+                "POST",
+                "/v2/snapshots/history",
+                body={
+                    "where": self._where(listing),
+                    "from": m.iso(start - 1),
+                    "to": m.iso(last),
+                    "interval": timeframe,
+                    "layers": ["oi"],
+                    "units": "published",
+                    "number_format": "string",
+                    "include_gaps": True,
+                },
+            )
+            layer = self._item(data, listing, self.venue).get("layers", {}).get("oi")
+            if not isinstance(layer, dict) or not isinstance(layer.get("rows"), list):
+                raise BadResponse("Missing OI sample rows")
+            rows = layer["rows"]
+            expected = (last - start) // step + 1
+            if len(rows) != expected:
+                raise BadResponse(
+                    "OI response omitted expected buckets; refusing an incomplete history"
+                )
+            for index, row in enumerate(rows):
+                if m.milliseconds(row.get("bucket_end")) != start + index * step:
+                    raise BadResponse("OI sample grid changed")
+                # Historical units belong to the returned layer, not today's instrument.
+                result.append(m.open_interest(row, layer.get("units", {}).get("oi"), listing))
+            start = last + step
+        return result
+
+    def fetch_liquidations(self, symbol, since=None, limit=None, params=None):
+        key, limit = _symbol(symbol), self._limit(limit)
+        call, until = self._call(params)
+        start = until - 3_600_000 if since is None else integer(since, "since") - 1
+        if start >= until:
+            raise ValueError("since must be <= until")
+        listing = self._markets(call, [key])[key]
+        result, seen = [], set()
+        window = DAY
+        while start < until and (since is None or len(result) < limit):
+            end = min(until, start + window)
+            data = call(
+                "POST",
+                "/v2/liquidations",
+                body={
+                    "where": self._where(listing),
+                    "from": m.iso(start),
+                    "to": m.iso(end),
+                    "limit": 1000,
+                    "units": "published",
+                    "number_format": "string",
+                    "include_gaps": True,
+                },
+            )
+            item = self._item(data, listing, self.venue)
+            if item.get("status") != "present":
+                raise DataUnavailable(
+                    "Liquidations are unavailable for this listing", response=data
+                )
+            if item.get("truncated"):
+                if end - start <= 1:
+                    raise DataUnavailable(
+                        "Liquidations cannot be paged without losing tied events", response=data
+                    )
+                window = max(1, (end - start) // 2)
+                continue
+            if item.get("gaps") and not item.get("events"):
+                raise DataUnavailable("Empty liquidation window has data gaps", response=data)
+            for event in item.get("events", []):
+                ts = m.milliseconds(event.get("event_time"))
+                if (
+                    not m.instant(m.iso(start))
+                    < m.instant(event["event_time"])
+                    <= m.instant(m.iso(end))
+                ):
+                    raise BadResponse("Liquidation event is outside the requested window")
+                if since is not None and ts < since:
+                    continue
+                # Only venue IDs are identities. Distinct equal-size/time events
+                # without IDs must not be deduplicated by their values.
+                uid = event.get("venue_uid")
+                if uid is not None and uid in seen:
+                    continue
+                if uid is not None:
+                    seen.add(uid)
+                result.append(m.liquidation(event, item, listing))
+            start = end
+            window = DAY
+        result.sort(key=lambda r: r["timestamp"])
+        return result[:limit] if since is not None else result[-limit:]
+
+    fetchFundingRateHistory = fetch_funding_rate_history
+    fetchFundingRates = fetch_funding_rates
+    fetchOpenInterestHistory = fetch_open_interest_history
+    fetchLiquidations = fetch_liquidations