opentrade-backtest 0.1.0__tar.gz

opentrade_backtest-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: opentrade-backtest
+Version: 0.1.0
+Summary: Open Trade backtest sessions from Python: the live API against a simulated clock
+License: Proprietary
+Project-URL: Documentation, https://opentrade.exchange/api-backtest/
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31
+Requires-Dist: websocket-client>=1.7
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == "pandas"
+Requires-Dist: pyarrow>=14; extra == "pandas"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: websockets>=13; extra == "test"
+Requires-Dist: pandas>=2.0; extra == "test"
+Requires-Dist: pyarrow>=14; extra == "test"

opentrade_backtest-0.1.0/opentrade_backtest/__init__.py

@@ -0,0 +1,21 @@
+from .auth import Credentials, StaticToken, TokenSource
+from .client import BacktestClient
+from .clock import SimClock, WallClock
+from .errors import (ApiError, AuthError, InvalidRequest, NotFound, NotPermitted, QuotaExceeded, RateLimited,
+                     SessionConflict, SessionEnded, Unauthorized, Unavailable, WrongAudience)
+from .live import cancel_body, live_endpoints, order_body, session_endpoints
+from .models import (Balance, ClientFee, ClockSpec, ClockTick, CreatedSession, Fill, FillModel, Latency, Order,
+                     Quota, Report, SessionSpec, Status, StepBatch)
+from .session import Session
+from .ws import SessionSocket
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ApiError", "AuthError", "BacktestClient", "Balance", "ClientFee", "ClockSpec", "ClockTick", "CreatedSession",
+    "Credentials", "Fill", "FillModel", "InvalidRequest", "Latency", "NotFound", "NotPermitted", "Order",
+    "Quota", "QuotaExceeded", "RateLimited", "Report", "Session", "SessionConflict", "SessionEnded",
+    "SessionSocket", "SessionSpec", "SimClock", "StaticToken", "Status", "StepBatch", "TokenSource",
+    "Unauthorized", "Unavailable", "WallClock", "WrongAudience", "cancel_body", "live_endpoints", "order_body",
+    "session_endpoints",
+]

opentrade_backtest-0.1.0/opentrade_backtest/auth.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Callable, Optional
+from urllib.parse import urlparse
+
+import requests
+
+from .errors import AuthError
+
+UAT_AUTH_HOST = "https://auth-uat.opentrade.exchange"
+PRODUCTION_AUTH_HOST = "https://auth.opentrade.exchange"
+BACKTEST_SCOPE = "BACKTEST_ACCESS"
+LIVE_SCOPE = "API_ACCESS"
+REFRESH_AT = 0.8
+FALLBACK_LIFETIME_SECONDS = 900.0
+MINIMUM_LIFETIME_SECONDS = 60.0
+
+
+@dataclass(frozen=True)
+class Credentials:
+    username: str
+    password: str = field(repr=False)
+    api_key: str
+    secret: str = field(repr=False)
+
+
+def parse_expiry(value: Optional[str]) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def bearer(token: str) -> str:
+    stripped = token.strip().strip('"')
+    return stripped if stripped.lower().startswith("bearer ") else f"Bearer {stripped}"
+
+
+def _login_refused(response: requests.Response) -> bool:
+    if response.status_code >= 400:
+        return True
+    location = response.headers.get("Location") or ""
+    return urlparse(location).path.rstrip("/").endswith("/login")
+
+
+class TokenSource:
+    def __init__(self, auth_host: str, creds: Credentials, scope: str = BACKTEST_SCOPE,
+                 http: Optional[requests.Session] = None, timeout: float = 15.0,
+                 monotonic: Callable[[], float] = time.monotonic,
+                 utcnow: Callable[[], datetime] = lambda: datetime.now(timezone.utc)):
+        self.auth_host = auth_host.rstrip("/")
+        self.creds = creds
+        self.scope = scope
+        self.timeout = timeout
+        self._http_factory = (lambda: http) if http is not None else requests.Session
+        self._monotonic = monotonic
+        self._utcnow = utcnow
+        self._lock = threading.Lock()
+        self._token: Optional[str] = None
+        self._refresh_at = 0.0
+        self.expires_at: Optional[datetime] = None
+        self.granted_scope: Optional[str] = None
+
+    def token(self) -> str:
+        with self._lock:
+            if self._token is None or self._monotonic() >= self._refresh_at:
+                self._mint()
+            return self._token
+
+    def invalidate(self) -> None:
+        with self._lock:
+            self._token = None
+
+    def _mint(self) -> None:
+        http = self._http_factory()
+        login = http.post(f"{self.auth_host}/login",
+                          data={"username": self.creds.username, "password": self.creds.password},
+                          allow_redirects=False, timeout=self.timeout)
+        if _login_refused(login):
+            raise AuthError("LOGIN_REFUSED", f"login was refused (HTTP {login.status_code})",
+                            login.status_code)
+        minted = http.post(f"{self.auth_host}/auth/jwt/clients/{self.creds.api_key}/token",
+                           params={"scopes": self.scope},
+                           headers={"accept": "*/*", "clientSecret": self.creds.secret},
+                           data="", timeout=self.timeout)
+        if minted.status_code != 200 or not minted.text.strip():
+            raise AuthError("TOKEN_REFUSED", f"the token request was refused (HTTP {minted.status_code})",
+                            minted.status_code)
+        issued = self._monotonic()
+        self._token = bearer(minted.text)
+        self.granted_scope = minted.headers.get("jwt-scope")
+        self.expires_at = parse_expiry(minted.headers.get("jwt-expire-at"))
+        lifetime = FALLBACK_LIFETIME_SECONDS
+        if self.expires_at is not None:
+            lifetime = max(MINIMUM_LIFETIME_SECONDS, (self.expires_at - self._utcnow()).total_seconds())
+        self._refresh_at = issued + REFRESH_AT * lifetime
+
+
+class StaticToken:
+    def __init__(self, token: str):
+        self._token = bearer(token)
+
+    def token(self) -> str:
+        return self._token
+
+    def invalidate(self) -> None:
+        return None

opentrade_backtest-0.1.0/opentrade_backtest/client.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
+
+import requests
+
+from .auth import BACKTEST_SCOPE, PRODUCTION_AUTH_HOST, UAT_AUTH_HOST, Credentials, TokenSource
+from .errors import error_for
+from .models import CreatedSession, Instant, Quota, SessionSpec, Status, instant_text
+from .session import Session
+
+UAT_GATEWAY = "https://gateway-public-uat.opentrade.exchange"
+PRODUCTION_GATEWAY = "https://gateway-public.opentrade.exchange"
+SERVICE_PATH = "/hermes-backtest"
+CONTROL_PATH = SERVICE_PATH + "/api/backtest"
+
+
+def _day(value: Instant) -> str:
+    return instant_text(value)[:10]
+
+
+def _socket_url(http_url: str) -> str:
+    scheme, rest = http_url.split("://", 1)
+    return ("wss" if scheme == "https" else "ws") + "://" + rest
+
+
+class BacktestClient:
+    def __init__(self, gateway: str, token_source: Any, http: Optional[requests.Session] = None,
+                 timeout: float = 30.0):
+        self.gateway = gateway.rstrip("/")
+        self.token_source = token_source
+        self.timeout = timeout
+        self._http = http or requests.Session()
+
+    @classmethod
+    def uat(cls, creds: Credentials, **options: Any) -> "BacktestClient":
+        return cls(UAT_GATEWAY, TokenSource(UAT_AUTH_HOST, creds, scope=BACKTEST_SCOPE), **options)
+
+    @classmethod
+    def production(cls, creds: Credentials, **options: Any) -> "BacktestClient":
+        return cls(PRODUCTION_GATEWAY, TokenSource(PRODUCTION_AUTH_HOST, creds, scope=BACKTEST_SCOPE), **options)
+
+    @property
+    def control_base(self) -> str:
+        return self.gateway + CONTROL_PATH
+
+    def session_base(self, session_id: int) -> str:
+        return f"{self.gateway}{SERVICE_PATH}/s/{session_id}"
+
+    def _send(self, method: str, url: str, params: Optional[Mapping[str, Any]] = None,
+              json: Any = None, stream: bool = False) -> requests.Response:
+        response = None
+        for attempt in range(2):
+            headers = {"Authorization": self.token_source.token(), "Accept": "application/json"}
+            response = self._http.request(method, url, params=params, json=json, headers=headers,
+                                          timeout=self.timeout, stream=stream)
+            if response.status_code != 401 or attempt == 1:
+                break
+            self.token_source.invalidate()
+        if response.status_code >= 400:
+            try:
+                body = response.json()
+            except ValueError:
+                body = {}
+            raise error_for(response.status_code, body, response.headers)
+        return response
+
+    def _absolute(self, method: str, url: str, params: Optional[Mapping[str, Any]] = None,
+                  json: Any = None) -> Any:
+        response = self._send(method, url, params=params, json=json)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def _control(self, method: str, path: str, params: Optional[Mapping[str, Any]] = None,
+                 json: Any = None) -> Any:
+        return self._absolute(method, self.control_base + path, params=params, json=json)
+
+    def create_session(self, spec: Union[SessionSpec, Mapping[str, Any]]) -> Session:
+        body = spec.to_json() if isinstance(spec, SessionSpec) else dict(spec)
+        created = CreatedSession.from_json(self._control("POST", "/sessions", json=body))
+        return Session(self, created.session_id, created.base_url, created.rest_base, created.ws_url, created)
+
+    def session(self, session_id: int) -> Session:
+        base = self.session_base(session_id)
+        return Session(self, session_id, base, base + "/api/rest", _socket_url(base) + "/ws")
+
+    def sessions(self, active: bool = True, page: int = 0, size: int = 100) -> List[Status]:
+        answer = self._control("GET", "/sessions",
+                               params={"state": "active" if active else "all", "page": page, "size": size})
+        return [Status.from_json(row) for row in (answer or {}).get("sessions") or []]
+
+    def runs(self, page: int = 0, size: int = 50) -> Dict[str, Any]:
+        return self._control("GET", "/runs", params={"page": page, "size": size})
+
+    def run(self, run_id: int) -> Dict[str, Any]:
+        return self._control("GET", f"/runs/{run_id}")
+
+    def run_orders(self, run_id: int, page: int = 0) -> Dict[str, Any]:
+        return self._control("GET", f"/runs/{run_id}/orders", params={"page": page})
+
+    def run_fills(self, run_id: int, page: int = 0) -> Dict[str, Any]:
+        return self._control("GET", f"/runs/{run_id}/fills", params={"page": page})
+
+    def compare(self, ids: Sequence[int]) -> Dict[str, Any]:
+        return self._control("GET", "/runs/compare", params=[("id", run_id) for run_id in ids])
+
+    def update_run(self, run_id: int, name: Optional[str] = None, pinned: Optional[bool] = None) -> Any:
+        body = {key: value for key, value in (("name", name), ("pinned", pinned)) if value is not None}
+        return self._control("PUT", f"/runs/{run_id}", json=body)
+
+    def delete_run(self, run_id: int) -> None:
+        self._control("DELETE", f"/runs/{run_id}")
+
+    def quota(self) -> Quota:
+        return Quota.from_json(self._control("GET", "/quota"))
+
+    def coverage(self, dataset: str, start: Instant, end: Instant, venue: Optional[str] = None,
+                 pair: Optional[str] = None, period: Optional[str] = None) -> Dict[str, Any]:
+        params = {"dataset": dataset, "from": _day(start), "to": _day(end), "venue": venue, "pair": pair,
+                  "period": period}
+        return self._control("GET", "/coverage", params={k: v for k, v in params.items() if v is not None})
+
+    def download(self, dataset: str, venue: Optional[str], pair: Optional[str], start: Instant, end: Instant,
+                 fmt: str = "parquet", period: Optional[str] = None,
+                 path: Optional[Union[str, Path]] = None) -> Union[bytes, Path]:
+        params = {"from": _day(start), "to": _day(end), "venue": venue, "pair": pair, "period": period,
+                  "format": fmt}
+        response = self._send("GET", f"{self.control_base}/data/{dataset}",
+                              params={k: v for k, v in params.items() if v is not None}, stream=path is not None)
+        if path is None:
+            return response.content
+        target = Path(path)
+        with target.open("wb") as out:
+            for chunk in response.iter_content(chunk_size=1 << 16):
+                out.write(chunk)
+        return target

opentrade_backtest-0.1.0/opentrade_backtest/clock.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable, Mapping, Optional
+
+from .models import ClockTick
+
+
+class WallClock:
+    def now(self) -> float:
+        return time.time()
+
+    def now_ms(self) -> int:
+        return int(time.time() * 1000)
+
+    def utcnow(self) -> datetime:
+        return datetime.now(timezone.utc)
+
+    def sleep(self, seconds: float) -> None:
+        time.sleep(seconds)
+
+
+class SimClock:
+    def __init__(self, stepper: Optional[Callable[[int], None]] = None):
+        self._stepper = stepper
+        self._millis: Optional[int] = None
+        self.last: Optional[ClockTick] = None
+
+    @property
+    def started(self) -> bool:
+        return self._millis is not None
+
+    def feed(self, data: Mapping[str, Any]) -> ClockTick:
+        tick = ClockTick.from_json(data)
+        self.last = tick
+        self._millis = tick.sim_time_ms
+        return tick
+
+    def _require(self) -> int:
+        if self._millis is None:
+            raise RuntimeError("the simulated clock has not ticked yet; start the session and read a step first")
+        return self._millis
+
+    def now(self) -> float:
+        return self._require() / 1000.0
+
+    def now_ms(self) -> int:
+        return self._require()
+
+    def utcnow(self) -> datetime:
+        return datetime.fromtimestamp(self._require() / 1000.0, tz=timezone.utc)
+
+    def sleep(self, seconds: float) -> None:
+        if self._stepper is None:
+            raise RuntimeError("this clock is not attached to a session socket")
+        target = self.now_ms() + int(round(seconds * 1000))
+        while self.now_ms() < target:
+            self._stepper(target)

opentrade_backtest-0.1.0/opentrade_backtest/errors.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+class ApiError(Exception):
+    def __init__(self, code: Optional[str], message: str, status: Optional[int] = None,
+                 body: Optional[Mapping[str, Any]] = None):
+        super().__init__(f"{code}: {message}" if code else message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.body = dict(body or {})
+
+
+class AuthError(ApiError):
+    pass
+
+
+class Unauthorized(ApiError):
+    pass
+
+
+class InvalidRequest(ApiError):
+    @property
+    def field(self) -> Optional[str]:
+        return self.body.get("field")
+
+    @property
+    def missing(self) -> list:
+        return list(self.body.get("missing") or [])
+
+
+class WrongAudience(ApiError):
+    pass
+
+
+class NotPermitted(ApiError):
+    pass
+
+
+class NotFound(ApiError):
+    pass
+
+
+class SessionConflict(ApiError):
+    pass
+
+
+class QuotaExceeded(ApiError):
+    def __init__(self, code: Optional[str], message: str, status: Optional[int] = None,
+                 body: Optional[Mapping[str, Any]] = None):
+        super().__init__(code, message, status, body)
+        self.quota = self.body.get("quota")
+        self.limit = self.body.get("limit")
+        self.used = self.body.get("used")
+        self.resets_at = self.body.get("resetsAt")
+
+
+class RateLimited(ApiError):
+    def __init__(self, code: Optional[str], message: str, status: Optional[int] = None,
+                 body: Optional[Mapping[str, Any]] = None, retry_after: Optional[float] = None):
+        super().__init__(code, message, status, body)
+        self.retry_after = retry_after
+
+
+class Unavailable(ApiError):
+    def __init__(self, code: Optional[str], message: str, status: Optional[int] = None,
+                 body: Optional[Mapping[str, Any]] = None, retry_after: Optional[float] = None):
+        super().__init__(code, message, status, body)
+        self.retry_after = retry_after
+
+
+class SessionEnded(ApiError):
+    pass
+
+
+def _retry_after(headers: Mapping[str, str]) -> Optional[float]:
+    value = headers.get("Retry-After") if headers is not None else None
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None
+
+
+def error_for(status: int, body: Any, headers: Optional[Mapping[str, str]] = None) -> ApiError:
+    payload = body if isinstance(body, dict) else {}
+    code = payload.get("code")
+    message = str(payload.get("message") or payload.get("error") or f"HTTP {status}")
+    retry_after = _retry_after(headers or {})
+    if status == 400:
+        return InvalidRequest(code, message, status, payload)
+    if status == 401:
+        return Unauthorized(code, message, status, payload)
+    if status == 403:
+        if code == "WRONG_AUDIENCE":
+            return WrongAudience(code, message, status, payload)
+        return NotPermitted(code, message, status, payload)
+    if status == 404:
+        return NotFound(code, message, status, payload)
+    if status == 409:
+        return SessionConflict(code, message, status, payload)
+    if status == 429:
+        if code == "QUOTA_EXCEEDED":
+            return QuotaExceeded(code, message, status, payload)
+        return RateLimited(code, message, status, payload, retry_after)
+    if status == 503:
+        return Unavailable(code, message, status, payload, retry_after)
+    return ApiError(code, message, status, payload)

opentrade_backtest-0.1.0/opentrade_backtest/export.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import io
+from typing import Any, Dict, List, Optional
+
+from .models import Instant, Report
+
+NAV_COLUMNS = ["time", "nav", "hold"]
+FILL_COLUMNS = ["order_id", "client_order_id", "venue", "pair", "time", "side", "price", "quantity", "liquidity",
+                "venue_fee", "venue_fee_asset", "client_fee", "client_fee_asset"]
+ORDER_COLUMNS = ["order_id", "client_order_id", "parent_order_id", "request_type", "venue", "pair", "order_type",
+                 "time_in_force", "side", "price", "trigger_price", "quantity", "filled_quantity", "avg_fill_price",
+                 "status", "reject_reason", "sent_at", "arrived_at", "closed_at"]
+METRIC_COLUMNS = ["scope", "scope_key", "metric", "value", "asset"]
+
+TIME_COLUMNS = {"time", "sent_at", "arrived_at", "closed_at"}
+NUMBER_COLUMNS = {"nav", "hold", "price", "quantity", "venue_fee", "client_fee", "trigger_price", "filled_quantity",
+                  "avg_fill_price", "value"}
+
+
+def _pandas():
+    try:
+        import pandas
+    except ImportError as missing:
+        raise ImportError("pandas is needed for frames; install opentrade-backtest[pandas]") from missing
+    return pandas
+
+
+def _frame(rows: List[Any], columns: List[str]):
+    pandas = _pandas()
+    records = [{column: getattr(row, column) for column in columns} for row in rows]
+    frame = pandas.DataFrame.from_records(records, columns=columns)
+    for column in columns:
+        if column in TIME_COLUMNS:
+            frame[column] = pandas.to_datetime(frame[column], utc=True, format="ISO8601")
+        elif column in NUMBER_COLUMNS:
+            frame[column] = pandas.to_numeric(frame[column].map(lambda v: None if v is None else float(v)))
+    return frame
+
+
+def report_frames(report: Report) -> Dict[str, Any]:
+    return {
+        "nav": _frame(list(report.nav), NAV_COLUMNS),
+        "fills": _frame(list(report.fills), FILL_COLUMNS),
+        "orders": _frame(list(report.orders), ORDER_COLUMNS),
+        "metrics": _frame(list(report.metrics), METRIC_COLUMNS),
+    }
+
+
+def download_frame(client: Any, dataset: str, venue: Optional[str], pair: Optional[str], start: Instant,
+                   end: Instant, period: Optional[str] = None):
+    pandas = _pandas()
+    content = client.download(dataset, venue, pair, start, end, fmt="parquet", period=period)
+    return pandas.read_parquet(io.BytesIO(content))

opentrade_backtest-0.1.0/opentrade_backtest/live.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional, Tuple
+
+from .models import Amount, to_decimal
+
+LIVE_ENDPOINTS: Dict[str, Tuple[str, str]] = {
+    "uat": ("https://gateway-public-uat.opentrade.exchange/hermes-ws-gateway/api/rest",
+            "wss://uat.opentrade.exchange/ws"),
+    "production": ("https://gateway-public.opentrade.exchange/hermes-ws-gateway/api/rest",
+                   "wss://opentrade.exchange/ws"),
+}
+
+
+def _number(value: Amount) -> float:
+    return float(to_decimal(value))
+
+
+def order_body(pair: str, direction: str, order_type: str, amount: Amount, price: Optional[Amount] = None,
+               time_in_force: str = "GTC", client_order_id: Optional[str] = None,
+               exchange: Optional[str] = None) -> Dict[str, Any]:
+    body: Dict[str, Any] = {
+        "class": "Order",
+        "globalInstrumentCd": pair,
+        "direction": direction.upper(),
+        "orderType": order_type.upper(),
+        "timeInForce": time_in_force.upper(),
+    }
+    if price is not None:
+        body["price"] = _number(price)
+    body["amount"] = _number(amount)
+    if client_order_id is not None:
+        body["clientOrderId"] = str(client_order_id)
+    if exchange is not None and exchange.upper() != "OPENTRADE":
+        body["exchange"] = exchange.upper()
+        body["requestType"] = "DIRECT"
+    return body
+
+
+def cancel_body(pair: str, client_order_id: Optional[str] = None, exchange_order_id: Optional[str] = None,
+                exchange: Optional[str] = None) -> Dict[str, Any]:
+    if not client_order_id and not exchange_order_id:
+        raise ValueError("a cancel without clientOrderId or exchangeOrderId cancels every order on the pair; "
+                         "name the order")
+    body: Dict[str, Any] = {"class": "Order", "action": "Cancel", "globalInstrumentCd": pair}
+    if client_order_id:
+        body["clientOrderId"] = str(client_order_id)
+    if exchange_order_id:
+        body["exchangeOrderId"] = str(exchange_order_id)
+    if exchange is not None and exchange.upper() != "OPENTRADE":
+        body["exchange"] = exchange.upper()
+        body["requestType"] = "DIRECT"
+    return body
+
+
+def wire(message: Any) -> str:
+    return json.dumps(message, separators=(",", ":"))
+
+
+def live_endpoints(env: str, ws_url: Optional[str] = None) -> Tuple[str, str]:
+    try:
+        rest_base, default_ws = LIVE_ENDPOINTS[env.lower()]
+    except KeyError:
+        raise ValueError(f"unknown environment {env!r}; use one of {sorted(LIVE_ENDPOINTS)}") from None
+    return rest_base, ws_url or default_ws
+
+
+def session_endpoints(session: Any) -> Tuple[str, str]:
+    return session.rest_base, session.ws_url