tickerall 0.1.0__py3-none-any.whl

tickerall/__init__.py

@@ -0,0 +1,80 @@
+"""TickerAll — official Python client for the TickerAll REST + WebSocket API.
+
+Place trades, stream live market data, and manage broker sessions
+programmatically — without an MT4/MT5 terminal in the path.
+
+    from tickerall import Tickerall
+
+    client = Tickerall(api_key="cf_live_...")
+    result = client.sessions.start(
+        broker="mt5", server="Exness-MT5Trial14",
+        account=415724042, password="...",
+    )
+    stream = client.stream.connect()
+    stream.on("tick", lambda e: print(e.symbol, e.bid, e.ask))
+    stream.subscribe_ticks(result.account_id, ["BTCUSDm"])
+"""
+
+from __future__ import annotations
+
+from .client import Tickerall
+from .errors import (
+    TickerallApiError,
+    TickerallAuthError,
+    TickerallBrokerError,
+    TickerallForbiddenError,
+    TickerallNotFoundError,
+    TickerallServiceUnavailableError,
+    TickerallValidationError,
+)
+from .namespaces.stream import TickerallStream
+from .types import (
+    AccountDetail,
+    AccountEvent,
+    AccountInfo,
+    AccountListing,
+    AccountSnapshot,
+    Candle,
+    ClosePositionResult,
+    HistoryTrade,
+    ModifyPositionResult,
+    PendingRearmAccount,
+    PlaceOrderResult,
+    Position,
+    PositionEvent,
+    SessionStartResult,
+    SymbolSpec,
+    TickEvent,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Tickerall",
+    "TickerallStream",
+    # errors
+    "TickerallApiError",
+    "TickerallAuthError",
+    "TickerallForbiddenError",
+    "TickerallValidationError",
+    "TickerallNotFoundError",
+    "TickerallBrokerError",
+    "TickerallServiceUnavailableError",
+    # types
+    "SessionStartResult",
+    "PendingRearmAccount",
+    "AccountListing",
+    "AccountInfo",
+    "AccountDetail",
+    "Position",
+    "SymbolSpec",
+    "Candle",
+    "HistoryTrade",
+    "PlaceOrderResult",
+    "ClosePositionResult",
+    "ModifyPositionResult",
+    "TickEvent",
+    "PositionEvent",
+    "AccountEvent",
+    "AccountSnapshot",
+]

tickerall/client.py

@@ -0,0 +1,341 @@
+"""The TickerAll client — synchronous REST + a background-thread WebSocket
+stream.
+
+Design mirrors the official TypeScript client: typed namespaces
+(``sessions`` / ``accounts`` / ``orders`` / ``positions`` / ``candles`` /
+``history`` / ``stream``), stable idempotency keys on state-changing calls,
+transparent re-arm of kept sessions, and a typed error hierarchy.
+
+All REST methods are synchronous and thread-safe, so this drops cleanly into
+sync codebases (incl. the ``MetaTrader5`` ecosystem) and into async apps via
+``asyncio.to_thread``.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .errors import (
+    TickerallApiError,
+    TickerallServiceUnavailableError,
+    map_error_response,
+)
+from .namespaces.accounts import AccountsNamespace
+from .namespaces.candles import CandlesNamespace
+from .namespaces.history import HistoryNamespace
+from .namespaces.orders import OrdersNamespace
+from .namespaces.positions import PositionsNamespace
+from .namespaces.sessions import SessionsNamespace
+from .namespaces.stream import StreamNamespace
+
+DEFAULT_BASE_URL = "https://api.tickerall.com"
+DEFAULT_STREAM_URL = "wss://api.tickerall.com/v1/stream"
+DEFAULT_TIMEOUT_S = 30.0
+SDK_VERSION = "0.1.0"
+
+# Ceiling on how long a queue_if_reconnecting call waits across replays.
+DEFAULT_QUEUE_MAX_S = 60.0
+# Backoff between replay attempts (seconds); each clamped to the remaining time.
+_REPLAY_DELAYS_S = [0.5, 1.0, 2.0, 4.0, 8.0]
+
+
+class Tickerall:
+    """Synchronous client for the TickerAll REST + WebSocket API.
+
+    Example::
+
+        from tickerall import Tickerall
+
+        client = Tickerall(api_key="cf_live_...")
+        result = client.sessions.start(
+            broker="mt5", server="Exness-MT5Trial14",
+            account=415724042, password="...",
+        )
+        bars = client.candles.get(result.account_id, symbol="BTCUSDm", hours=24)
+        client.sessions.end(result.account_id)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        stream_url: str = DEFAULT_STREAM_URL,
+        timeout: float = DEFAULT_TIMEOUT_S,
+        user_agent: Optional[str] = None,
+        http_client: Optional[httpx.Client] = None,
+        on_rearm: Optional["object"] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Tickerall: `api_key` is required.")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._stream_url = stream_url
+        self._timeout = timeout
+        self._user_agent = (
+            f"{user_agent} tickerall-python/{SDK_VERSION}"
+            if user_agent
+            else f"tickerall-python/{SDK_VERSION}"
+        )
+        self._on_rearm = on_rearm
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client()
+
+        # Kept-session credentials — RAM only, NEVER persisted. Lets the client
+        # transparently re-arm an account that has gone cold (e.g. an atlas
+        # restart dropped its server-side credentials).
+        self._kept_creds: Dict[str, Dict[str, Any]] = {}
+
+        # Namespaces
+        self.sessions = SessionsNamespace(self)
+        self.accounts = AccountsNamespace(self)
+        self.orders = OrdersNamespace(self)
+        self.positions = PositionsNamespace(self)
+        self.candles = CandlesNamespace(self)
+        self.history = HistoryNamespace(self)
+        self.stream = StreamNamespace(self, self._stream_url, self._api_key, self._user_agent)
+
+    # ── Context manager ──────────────────────────────────────────────────────
+
+    def __enter__(self) -> "Tickerall":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool (if the client owns it)."""
+        if self._owns_http:
+            self._http.close()
+
+    # ── Internal request machinery (used by namespaces) ──────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        expect_no_content: bool = False,
+        account_id: Optional[str] = None,
+    ) -> Any:
+        """Run a request, transparently re-arming a kept session and retrying
+        once if the target account has gone cold."""
+        return self._request_with_rearm(
+            method,
+            path,
+            body=body,
+            idempotency_key=idempotency_key,
+            timeout=timeout,
+            expect_no_content=expect_no_content,
+            account_id=account_id,
+            is_rearm_retry=False,
+        )
+
+    def _request_with_rearm(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any,
+        idempotency_key: Optional[str],
+        timeout: Optional[float],
+        expect_no_content: bool,
+        account_id: Optional[str],
+        is_rearm_retry: bool,
+    ) -> Any:
+        try:
+            return self._request_once(
+                method,
+                path,
+                body=body,
+                idempotency_key=idempotency_key,
+                timeout=timeout,
+                expect_no_content=expect_no_content,
+            )
+        except TickerallApiError as err:
+            if (
+                not is_rearm_retry
+                and account_id is not None
+                and account_id in self._kept_creds
+                and err.code == "BROKER_ACCOUNT_NOT_HOT"
+            ):
+                self.rearm(account_id)
+                return self._request_with_rearm(
+                    method,
+                    path,
+                    body=body,
+                    idempotency_key=idempotency_key,
+                    timeout=timeout,
+                    expect_no_content=expect_no_content,
+                    account_id=account_id,
+                    is_rearm_retry=True,
+                )
+            raise
+
+    def _request_once(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any,
+        idempotency_key: Optional[str],
+        timeout: Optional[float],
+        expect_no_content: bool,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": self._user_agent,
+            "Accept": "application/json",
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        try:
+            response = self._http.request(
+                method,
+                url,
+                headers=headers,
+                json=body if body is not None else None,
+                timeout=timeout if timeout is not None else self._timeout,
+            )
+        except httpx.TimeoutException as err:
+            raise TickerallServiceUnavailableError(
+                status=0, code="REQUEST_TIMEOUT", message=str(err) or "Request timed out"
+            ) from err
+        except httpx.RequestError as err:
+            # fetch threw before any response — TickerAll was unreachable.
+            raise TickerallServiceUnavailableError(
+                status=0,
+                code="NETWORK_ERROR",
+                message=str(err) or "Network request failed",
+                details=repr(err),
+            ) from err
+
+        request_id = response.headers.get("x-request-id")
+
+        if not response.is_success:
+            err_body = _safe_read_error_body(response)
+            raise map_error_response(
+                status=response.status_code,
+                code=(err_body or {}).get("error") or f"HTTP_{response.status_code}",
+                message=(err_body or {}).get("message")
+                or response.reason_phrase
+                or "Request failed",
+                request_id=request_id,
+                details=(err_body or {}).get("details"),
+            )
+
+        if expect_no_content or response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def _request_idempotent(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        account_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        queue_if_reconnecting: bool = False,
+        queue_max_s: float = DEFAULT_QUEUE_MAX_S,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        """State-changing request with a stable idempotency key.
+
+        The key is fixed ONCE so every replay attempt carries the same key —
+        the server then dedupes any attempt that already executed, which is
+        what makes queue-and-replay safe (no double trade).
+        """
+        key = idempotency_key or _generate_idempotency_key()
+        if not queue_if_reconnecting:
+            # Default: fail fast. A transient connectivity failure surfaces as
+            # TickerallServiceUnavailableError for the caller to re-decide.
+            return self._request(
+                method, path, body=body, idempotency_key=key, timeout=timeout, account_id=account_id
+            )
+
+        # Queue-and-replay: retry transient failures with backoff until the
+        # call succeeds or queue_max_s elapses. (Calls are sequential in a sync
+        # client, so in-order replay is naturally preserved.)
+        deadline = time.monotonic() + queue_max_s
+        attempt = 0
+        while True:
+            try:
+                return self._request(
+                    method, path, body=body, idempotency_key=key, timeout=timeout, account_id=account_id
+                )
+            except TickerallApiError as err:
+                remaining = deadline - time.monotonic()
+                if not err.transient or remaining <= 0:
+                    raise
+                base = _REPLAY_DELAYS_S[min(attempt, len(_REPLAY_DELAYS_S) - 1)]
+                attempt += 1
+                time.sleep(min(base, remaining))
+
+    # ── Kept sessions (auto re-arm) ──────────────────────────────────────────
+
+    def _register_kept_session(self, account_id: str, params: Dict[str, Any]) -> None:
+        self._kept_creds[account_id] = params
+
+    def _unregister_kept_session(self, account_id: str) -> None:
+        self._kept_creds.pop(account_id, None)
+
+    def kept_session_ids(self) -> List[str]:
+        """Account IDs currently kept alive (have cached re-arm credentials)."""
+        return list(self._kept_creds.keys())
+
+    def rearm(self, account_id: str) -> None:
+        """Re-supply credentials for a kept account (a fresh session.start) to
+        bring a cold connection back. Raises if the account isn't kept alive."""
+        creds = self._kept_creds.get(account_id)
+        if creds is None:
+            raise TickerallApiError(
+                status=0,
+                code="NO_KEPT_CREDENTIALS",
+                message=f"No kept credentials for account {account_id}; call sessions.keep_alive first.",
+            )
+        if callable(self._on_rearm):
+            try:
+                self._on_rearm(account_id)
+            except Exception:
+                pass
+        # session.start carries no account_id, so this never recurses into re-arm.
+        self._request_idempotent("POST", "/v1/sessions", body=creds)
+
+    def rearm_all(self) -> None:
+        """Re-arm every kept session — best-effort (one failure won't block the
+        others). Used after the stream reconnects (atlas may have restarted)."""
+        for account_id in list(self._kept_creds.keys()):
+            try:
+                self.rearm(account_id)
+            except Exception:
+                pass
+
+
+def _safe_read_error_body(response: httpx.Response) -> Optional[Dict[str, Any]]:
+    try:
+        text = response.text
+        if not text:
+            return None
+        try:
+            data = response.json()
+            return data if isinstance(data, dict) else {"error": "PARSE_ERROR", "message": text}
+        except Exception:
+            return {"error": "PARSE_ERROR", "message": text}
+    except Exception:
+        return None
+
+
+def _generate_idempotency_key() -> str:
+    return str(uuid.uuid4())

tickerall/errors.py

@@ -0,0 +1,138 @@
+"""Typed exceptions for the TickerAll SDK.
+
+Mirrors the error model of the TypeScript client: a single base class
+(:class:`TickerallApiError`) carrying ``status`` / ``code`` / ``request_id`` /
+``details`` / ``transient``, plus narrow subclasses you can catch
+selectively. :func:`map_error_response` turns an HTTP error body into the
+right subclass.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class TickerallApiError(Exception):
+    """Base error for every failed TickerAll request.
+
+    Attributes:
+        status: HTTP status code (0 for failures that never reached a response,
+            e.g. a network error or timeout).
+        code: Machine-readable error code, e.g. ``BROKER_REJECTED`` or
+            ``REQUEST_TIMEOUT``.
+        request_id: The ``x-request-id`` header, when present — quote it in
+            support requests.
+        details: Optional structured detail the server attached.
+        transient: ``True`` when the failure was a momentary connectivity issue
+            (network blip, deploy, restart) that is safe to retry. ``False``
+            for application errors (auth, validation, broker rejection) that
+            will not change on retry.
+    """
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        message: str,
+        request_id: Optional[str] = None,
+        details: Any = None,
+        transient: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.details = details
+        self.transient = transient
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        rid = f" (request_id={self.request_id})" if self.request_id else ""
+        return f"[{self.code}] {self.message}{rid}"
+
+
+class TickerallAuthError(TickerallApiError):
+    """401 — your API key is missing, malformed, or revoked."""
+
+
+class TickerallForbiddenError(TickerallApiError):
+    """403 — authenticated, but not allowed to do this (plan limit, reserved
+    resource, role)."""
+
+
+class TickerallValidationError(TickerallApiError):
+    """400 / 422 — the request itself was malformed (bad symbol, missing
+    field, out-of-range volume)."""
+
+
+class TickerallNotFoundError(TickerallApiError):
+    """404 — the account, position, or resource does not exist."""
+
+
+class TickerallBrokerError(TickerallApiError):
+    """The broker rejected or could not satisfy the request (rejected trade,
+    auth failure at the broker, account not hot, …)."""
+
+
+class TickerallServiceUnavailableError(TickerallApiError):
+    """TickerAll was momentarily unreachable — a network blip, a deploy, or
+    the service restarting.
+
+    This is NOT your fault and NOT a broker rejection: the request never
+    reached a verdict, so it is safe to retry. ``transient`` is always
+    ``True``. By default a trade fails fast with this error so you can
+    re-decide with fresh prices; pass ``queue_if_reconnecting=True`` to
+    instead queue-and-replay it (with its stable idempotency key, so it
+    cannot double-execute) once connectivity returns.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        kwargs["transient"] = True
+        super().__init__(**kwargs)
+
+
+_BROKER_CODES = frozenset(
+    {
+        "BROKER_REJECTED",
+        "BROKER_AUTH_FAILED",
+        "BROKER_UNREACHABLE",
+        "BROKER_ACCOUNT_NOT_HOT",
+        "BROKER_ACCOUNT_ALREADY_LINKED",
+        "BROKER_ACCOUNT_NOT_FOUND",
+        "TICKET_NOT_FOUND",
+    }
+)
+
+
+def map_error_response(
+    *,
+    status: int,
+    code: str,
+    message: str,
+    request_id: Optional[str] = None,
+    details: Any = None,
+) -> TickerallApiError:
+    """Pick the right exception subclass for a server error response."""
+    init = dict(
+        status=status, code=code, message=message, request_id=request_id, details=details
+    )
+    # The pool draining for a deploy/restart is the canonical transient case —
+    # a retry lands on the fresh instance.
+    if code == "POOL_SHUTTING_DOWN":
+        return TickerallServiceUnavailableError(**init)
+    if code in _BROKER_CODES:
+        return TickerallBrokerError(**init)
+    if status == 401:
+        return TickerallAuthError(**init)
+    if status == 403:
+        return TickerallForbiddenError(**init)
+    if status == 404:
+        return TickerallNotFoundError(**init)
+    if status in (400, 422):
+        return TickerallValidationError(**init)
+    # A bare 502/503 with no recognised broker code is the proxy reporting
+    # TickerAll itself as momentarily down (e.g. mid-deploy) — transient.
+    if status in (502, 503):
+        return TickerallServiceUnavailableError(**init)
+    return TickerallApiError(**init)

tickerall/namespaces/__init__.py

@@ -0,0 +1 @@
+"""Typed API namespaces for the TickerAll client."""

tickerall/namespaces/accounts.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Optional
+from urllib.parse import quote
+
+from ..types import AccountDetail, AccountListing, SymbolSpec
+
+if TYPE_CHECKING:
+    from ..client import Tickerall
+
+
+class AccountsNamespace:
+    """List and inspect your connected broker accounts."""
+
+    def __init__(self, client: "Tickerall") -> None:
+        self._client = client
+
+    def list(self, *, timeout: Optional[float] = None) -> List[AccountListing]:
+        """All broker accounts linked to your API key."""
+        res = self._client._request("GET", "/v1/accounts", timeout=timeout)
+        return [AccountListing.from_dict(a) for a in res or []]
+
+    def get(self, account_id: str, *, timeout: Optional[float] = None) -> AccountDetail:
+        """A full snapshot of one account — balance/equity info and open
+        positions when online, or an offline hint when its connection is
+        cold."""
+        res = self._client._request(
+            "GET",
+            f"/v1/accounts/{quote(account_id, safe='')}",
+            account_id=account_id,
+            timeout=timeout,
+        )
+        return AccountDetail.from_dict(res)
+
+    def symbols(self, account_id: str, *, timeout: Optional[float] = None) -> List[str]:
+        """The broker-native symbol names this account can trade."""
+        res = self._client._request(
+            "GET",
+            f"/v1/accounts/{quote(account_id, safe='')}/symbols",
+            account_id=account_id,
+            timeout=timeout,
+        )
+        return list((res or {}).get("symbols", []))
+
+    def symbol_specs(self, account_id: str, *, timeout: Optional[float] = None) -> List[SymbolSpec]:
+        """Per-symbol volume specs (min / max / step) for validating an order
+        size before placing it. Each spec carries ``spec_source``: ``'broker'``
+        (authoritative) or ``'derived'`` (best-effort). MT5 only; an MT4
+        account returns an empty list."""
+        res = self._client._request(
+            "GET",
+            f"/v1/accounts/{quote(account_id, safe='')}/symbol-specs",
+            account_id=account_id,
+            timeout=timeout,
+        )
+        return [SymbolSpec.from_dict(s) for s in (res or {}).get("specs", [])]

tickerall/namespaces/candles.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Optional
+from urllib.parse import quote, urlencode
+
+from ..types import Candle, Timeframe
+
+if TYPE_CHECKING:
+    from ..client import Tickerall
+
+
+class CandlesNamespace:
+    """Fetch historical OHLC candles."""
+
+    def __init__(self, client: "Tickerall") -> None:
+        self._client = client
+
+    def get(
+        self,
+        account_id: str,
+        *,
+        symbol: str,
+        hours: int,
+        timeframe: Optional[Timeframe] = None,
+        timeout: Optional[float] = None,
+    ) -> List[Candle]:
+        """Historical OHLC candles for ``symbol`` from a connected account.
+
+        Coarser timeframes reach further back; pass a large ``hours`` and take
+        what comes back. Deep look-backs are served on an isolated history
+        connection and won't disturb your live tick stream.
+
+        Example::
+
+            bars = client.candles.get(account_id, symbol="BTCUSDm", hours=8760, timeframe="D1")
+        """
+        query = {"symbol": symbol, "hours": str(hours)}
+        if timeframe:
+            query["timeframe"] = timeframe
+        path = f"/v1/accounts/{quote(account_id, safe='')}/candles?{urlencode(query)}"
+        res = self._client._request("GET", path, timeout=timeout)
+        return [Candle.from_dict(c) for c in (res or {}).get("candles", [])]