revolut-x-python 1.0.0__py3-none-any.whl

revolut_x/account.py

@@ -0,0 +1,203 @@
+"""Account and wallet methods for the Revolut X API.
+
+This module provides :class:`AccountMixin`, which is mixed into
+:class:`~revolut_x.client.RevolutXClient` to add authenticated endpoints
+for account balances, transaction history, and private trade history.
+
+All methods in this mixin **require** an API key and private key.
+"""
+
+from __future__ import annotations
+import logging
+from typing import Any, TYPE_CHECKING
+from revolut_x.types import Balance, Trade
+
+if TYPE_CHECKING:
+    from revolut_x._http import HttpClient
+
+logger = logging.getLogger(__name__)
+
+
+class AccountMixin:
+    """Authenticated account endpoints — balances, transactions, private trades.
+
+    This mixin is not meant to be used directly.  It is mixed into
+    :class:`~revolut_x.client.RevolutXClient`.
+    """
+
+    # Provided by RevolutXClient
+    _http: HttpClient
+
+    # ------------------------------------------------------------------
+    # Balances
+    # ------------------------------------------------------------------
+
+    def get_balances(self) -> list[Balance]:
+        """Retrieve current balances for all currencies on the account.
+
+        Returns:
+            A list of :class:`~revolut_x.types.Balance` dictionaries, each
+            containing ``currency``, ``available``, ``reserved``, and
+            ``total`` fields.
+
+        Raises:
+            AuthenticationError: If the client is not authenticated.
+            ApiError: If the API returns a non-2xx response.
+
+        Example::
+
+            >>> balances = client.get_balances()
+            >>> for b in balances:
+            ...     if float(b["total"]) > 0:
+            ...         print(f"{b['currency']}: {b['available']} available")
+            EUR: 150.00 available
+            BTC: 0.00050463 available
+        """
+        _status, data = self._http.request(
+            "GET", "/balances", authenticated=True
+        )
+        return data if isinstance(data, list) else []
+
+    def get_balance(self, currency: str) -> Balance:
+        """Retrieve the balance for a specific currency.
+
+        Args:
+            currency: Currency symbol (e.g. ``'EUR'``, ``'BTC'``, ``'ETH'``).
+                Case-insensitive.
+
+        Returns:
+            A :class:`~revolut_x.types.Balance` dictionary.  If the currency
+            is not found on the account, returns a zero-balance entry.
+
+        Raises:
+            AuthenticationError: If the client is not authenticated.
+
+        Example::
+
+            >>> eur = client.get_balance("EUR")
+            >>> print(f"Available: {eur['available']} EUR")
+            Available: 150.00 EUR
+        """
+        balances = self.get_balances()
+        target = currency.upper()
+
+        for item in balances:
+            if isinstance(item, dict) and item.get("currency", "").upper() == target:
+                return item
+
+        # Currency not found — return zero balance
+        return {
+            "currency": target,
+            "available": "0.00",
+            "reserved": "0.00",
+            "total": "0.00",
+        }
+
+    # ------------------------------------------------------------------
+    # Transactions
+    # ------------------------------------------------------------------
+
+    def get_transactions(
+        self,
+        *,
+        limit: int = 50,
+        cursor: str | None = None,
+    ) -> tuple[list[dict[str, Any]], str | None]:
+        """Retrieve account transaction history (ledger).
+
+        Transactions include deposits, withdrawals, trade settlements, and
+        fee charges.  Each entry shows the source and destination amounts
+        and currencies.
+
+        Args:
+            limit: Number of transactions per page (default: 50).
+            cursor: Pagination cursor from a previous response.
+
+        Returns:
+            A tuple of ``(transactions, next_cursor)``.  Each transaction is
+            a dictionary with keys like ``source``, ``destination``,
+            ``created_date``, ``processed_date``.  ``next_cursor`` is ``None``
+            if there are no more pages.
+
+        Raises:
+            AuthenticationError: If the client is not authenticated.
+
+        Example::
+
+            >>> txns, cursor = client.get_transactions(limit=10)
+            >>> for tx in txns:
+            ...     print(f"{tx['source']['currency']} -> {tx['destination']['currency']}")
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+
+        _status, resp = self._http.request(
+            "GET", "/transactions", params=params, authenticated=True
+        )
+
+        if isinstance(resp, dict):
+            transactions = resp.get("data", [])
+            next_cursor = resp.get("metadata", {}).get("next_cursor")
+        else:
+            transactions = resp if isinstance(resp, list) else []
+            next_cursor = None
+
+        return transactions, next_cursor
+
+    # ------------------------------------------------------------------
+    # Private Trades
+    # ------------------------------------------------------------------
+
+    def get_account_trades(
+        self,
+        symbol: str,
+        *,
+        limit: int = 50,
+        cursor: str | None = None,
+    ) -> tuple[list[Trade], str | None]:
+        """Retrieve private (your own) trade history for a trading pair.
+
+        Unlike public trades from :meth:`get_trades`, these are your
+        personal executed trades with full fee information.
+
+        Args:
+            symbol: Trading pair (e.g. ``'BTC-EUR'``).
+            limit: Number of trades per page (default: 50).
+            cursor: Pagination cursor from a previous response.
+
+        Returns:
+            A tuple of ``(trades, next_cursor)`` where ``trades`` is a list
+            of :class:`~revolut_x.types.Trade` dicts with your private
+            execution details.
+
+        Raises:
+            AuthenticationError: If the client is not authenticated.
+            ApiError: If the API returns a non-2xx response.
+
+        Example::
+
+            >>> trades, cursor = client.get_account_trades("BTC-EUR", limit=10)
+            >>> for t in trades:
+            ...     print(f"{t['side']} {t['quantity']} BTC @ {t['price']} EUR")
+        """
+        api_symbol = symbol.replace("/", "-").upper()
+        params: dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+
+        _status, resp = self._http.request(
+            "GET",
+            f"/trades/private/{api_symbol}",
+            params=params,
+            authenticated=True,
+        )
+
+        if isinstance(resp, dict):
+            trades = resp.get("data", [])
+            next_cursor = resp.get("metadata", {}).get("next_cursor")
+        else:
+            trades = resp if isinstance(resp, list) else []
+            next_cursor = None
+
+        return trades, next_cursor

revolut_x/client.py

@@ -0,0 +1,170 @@
+"""Main client for the Revolut X Crypto Exchange REST API.
+
+This module provides :class:`RevolutXClient`, the single entry point for all
+Revolut X API operations.  It combines public market data, order management,
+and account endpoints into one unified interface.
+
+Example — public data (no API key needed)::
+
+    from revolut_x import RevolutXClient
+
+    client = RevolutXClient()
+    ticker = client.get_ticker("BTC-EUR")
+    print(f"BTC price: {ticker['last_price']} EUR")
+
+Example — trading (requires API key and private key)::
+
+    from revolut_x import RevolutXClient, OrderSide
+
+    client = RevolutXClient(
+        api_key="Vw7fXD...",
+        private_key_path="keys/private.pem",
+    )
+    order = client.place_market_order("BTC-EUR", OrderSide.BUY, quote_size="50.00")
+    print(f"Order ID: {order['venue_order_id']}")
+"""
+
+from __future__ import annotations
+import logging
+from pathlib import Path
+from revolut_x._auth import load_private_key
+from revolut_x._http import HttpClient
+from revolut_x.account import AccountMixin
+from revolut_x.market import MarketMixin
+from revolut_x.orders import OrdersMixin
+
+logger = logging.getLogger(__name__)
+
+
+class RevolutXClient(MarketMixin, OrdersMixin, AccountMixin):
+    """Client for the Revolut X Crypto Exchange REST API.
+
+    Provides complete access to:
+
+    * **Public market data** (no API key needed): trading pair configuration,
+      currency info, tickers, order book, OHLCV candles, and public trades.
+    * **Order management** (API key required): place market/limit orders,
+      cancel orders, inspect fills, view active and historical orders.
+    * **Account data** (API key required): balances, transaction ledger,
+      private trade history.
+
+    Args:
+        api_key: Your Revolut X API key.  Required only for authenticated
+            endpoints (orders, balances, etc.).  Get it from your
+            `Revolut X account settings <https://revx.revolut.com>`_.
+        private_key_path: Path to your Ed25519 private key PEM file.
+            Mutually exclusive with ``private_key_bytes``.
+        private_key_bytes: Ed25519 private key as raw PEM bytes.
+            Mutually exclusive with ``private_key_path``.
+        base_url: API base URL (default: ``'https://revx.revolut.com/api'``).
+            Change for sandbox/testing environments.
+        api_version: API version string (default: ``'1.0'``).
+        request_delay: Minimum seconds between HTTP requests to respect
+            rate limits (default: ``0.85``).  The Revolut X public API
+            allows 1 request per second.
+        timeout: HTTP request timeout in seconds (default: ``15``).
+        max_retries: Maximum retry attempts for rate-limited (429) or
+            failed requests (default: ``3``).
+
+    Raises:
+        AuthenticationError: If ``private_key_path`` is provided but the
+            file does not exist or contains an invalid key.
+
+    Example::
+
+        # Public data only — no credentials needed
+        client = RevolutXClient()
+        pairs = client.get_pairs()
+        candles = client.get_candles("BTC-EUR", Interval.HOUR_1)
+
+        # Full access — trading and account management
+        client = RevolutXClient(
+            api_key="your-api-key",
+            private_key_path="/path/to/private.pem",
+        )
+        balances = client.get_balances()
+        order = client.place_market_order("BTC-EUR", OrderSide.BUY, quote_size="50")
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        private_key_path: str | Path | None = None,
+        private_key_bytes: bytes | None = None,
+        base_url: str = "https://revx.revolut.com/api",
+        api_version: str = "1.0",
+        request_delay: float = 0.85,
+        timeout: int = 15,
+        max_retries: int = 3,
+        timestamp_offset_ms: int = 0,
+    ) -> None:
+        # Load private key if credentials are provided
+        private_key = None
+        if private_key_path is not None:
+            private_key = load_private_key(private_key_path)
+            logger.info("Ed25519 private key loaded from %s", private_key_path)
+        elif private_key_bytes is not None:
+            private_key = load_private_key(private_key_bytes)
+            logger.info("Ed25519 private key loaded from bytes")
+
+        # Create the internal HTTP client shared by all mixins
+        self._http = HttpClient(
+            base_url=base_url,
+            api_version=api_version,
+            api_key=api_key,
+            private_key=private_key,
+            request_delay=request_delay,
+            timeout=timeout,
+            max_retries=max_retries,
+            timestamp_offset_ms=timestamp_offset_ms,
+        )
+
+        # Store for diagnostics
+        self._api_key = api_key
+        self._has_private_key = private_key is not None
+
+    @property
+    def timestamp_offset(self) -> int:
+        """Timestamp clock offset in milliseconds."""
+        return self._http.timestamp_offset_ms
+
+    @timestamp_offset.setter
+    def timestamp_offset(self, val: int) -> None:
+        self._http.timestamp_offset_ms = int(val)
+
+    @property
+    def timestamp_offset_ms(self) -> int:
+        """Alias for timestamp_offset."""
+        return self._http.timestamp_offset_ms
+
+    @timestamp_offset_ms.setter
+    def timestamp_offset_ms(self, val: int) -> None:
+        self._http.timestamp_offset_ms = int(val)
+
+    def sync_time(self) -> int:
+        """Synchronize timestamp offset with Revolut X server time."""
+        return self._http.sync_time()
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Whether the client has API key and private key configured.
+
+        Returns:
+            ``True`` if both ``api_key`` and a private key were provided,
+            meaning authenticated endpoints (orders, balances) can be used.
+
+        Example::
+
+            >>> client = RevolutXClient()
+            >>> client.is_authenticated
+            False
+            >>> client = RevolutXClient(api_key="...", private_key_path="...")
+            >>> client.is_authenticated
+            True
+        """
+        return bool(self._api_key and self._has_private_key)
+
+    def __repr__(self) -> str:
+        auth = "authenticated" if self.is_authenticated else "public-only"
+        return f"<RevolutXClient({auth}, base_url='{self._http.base_url}')>"

revolut_x/exceptions.py

@@ -0,0 +1,147 @@
+"""Custom exceptions for the revolut-x-python library.
+
+Exception hierarchy::
+
+    RevolutXError (base)
+    ├── AuthenticationError   — missing/invalid API key or private key
+    ├── RateLimitError        — HTTP 429, retry after N seconds
+    ├── ApiError              — any non-2xx API response
+    ├── OrderValidationError  — payload violates exchange rules
+    └── NetworkError          — connection timeout, DNS failure, etc.
+
+All exceptions inherit from :class:`RevolutXError`, so you can catch them all
+with a single ``except RevolutXError`` block, or handle each type individually.
+"""
+
+from __future__ import annotations
+from typing import Any
+
+
+class RevolutXError(Exception):
+    """Base exception for all errors raised by the revolut-x-python library.
+
+    You can catch this to handle any library error generically::
+
+        try:
+            client.get_ticker("BTC-EUR")
+        except RevolutXError as exc:
+            logging.error("Revolut X error: %s", exc)
+    """
+
+
+class AuthenticationError(RevolutXError):
+    """Raised when authentication is missing, misconfigured, or rejected.
+
+    Common causes:
+
+    * ``api_key`` was not provided when creating :class:`RevolutXClient`.
+    * The private key file does not exist or has an invalid format.
+    * The API returned HTTP 401 or 403 (expired key, wrong signature, …).
+
+    Attributes:
+        hint: A human-readable suggestion on how to fix the problem.
+    """
+
+    def __init__(self, message: str, *, hint: str | None = None) -> None:
+        self.hint = hint
+        full = message
+        if hint:
+            full = f"{message}\n  Hint: {hint}"
+        super().__init__(full)
+
+
+class RateLimitError(RevolutXError):
+    """Raised when the Revolut X API returns HTTP 429 (Too Many Requests).
+
+    The library retries automatically up to ``max_retries`` times.  This
+    exception is raised only when all retries have been exhausted.
+
+    Attributes:
+        retry_after_seconds: Suggested wait time (from the ``Retry-After``
+            header), in seconds.  May be ``None`` if the header was absent.
+        endpoint: The API endpoint that triggered the rate limit.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after_seconds: float | None = None,
+        endpoint: str | None = None,
+    ) -> None:
+        self.retry_after_seconds = retry_after_seconds
+        self.endpoint = endpoint
+        super().__init__(message)
+
+
+class ApiError(RevolutXError):
+    """Raised when the Revolut X API returns a non-2xx HTTP status code.
+
+    This covers client errors (4xx) and server errors (5xx) that are not
+    authentication (401/403) or rate-limit (429) related.
+
+    Attributes:
+        status_code: The HTTP status code returned by the API (e.g. 400, 404, 500).
+        response_body: The parsed JSON response body, or raw text if parsing failed.
+        endpoint: The API endpoint that was called (e.g. ``POST /api/1.0/orders``).
+        method: The HTTP method used (e.g. ``GET``, ``POST``).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        response_body: Any = None,
+        endpoint: str = "",
+        method: str = "",
+    ) -> None:
+        self.status_code = status_code
+        self.response_body = response_body
+        self.endpoint = endpoint
+        self.method = method
+        super().__init__(message)
+
+
+class OrderValidationError(RevolutXError, ValueError):
+    """Raised when an order payload violates exchange rules before submission.
+
+    This is a **client-side** validation — the order is not sent to the
+    exchange.  Fix the payload and try again.
+
+    Attributes:
+        errors: A list of human-readable strings describing each violated rule.
+
+    Example::
+
+        try:
+            client.place_market_order("BTC-EUR", OrderSide.BUY, quote_size="0.01")
+        except OrderValidationError as exc:
+            for err in exc.errors:
+                print(f"  - {err}")
+    """
+
+    def __init__(self, message: str, *, errors: list[str] | None = None) -> None:
+        self.errors = errors or []
+        if self.errors:
+            details = "\n".join(f"  - {e}" for e in self.errors)
+            full = f"{message}\n{details}"
+        else:
+            full = message
+        super().__init__(full)
+
+
+class NetworkError(RevolutXError):
+    """Raised when a network-level error prevents the request from completing.
+
+    This wraps connection timeouts, DNS resolution failures, refused
+    connections, and other transport-layer errors.
+
+    Attributes:
+        original_error: The underlying :class:`requests.RequestException`
+            (or similar) that caused this error.
+    """
+
+    def __init__(self, message: str, *, original_error: Exception | None = None) -> None:
+        self.original_error = original_error
+        super().__init__(message)