xtb-api-python 0.5.2__py3-none-any.whl

xtb_api/instruments.py

@@ -0,0 +1,132 @@
+"""Persistent instrument-ID cache for symbol lookups.
+
+Downstream consumers (e.g. trading bots) need to map a symbol to the XTB
+instrument ID that the gRPC trading endpoint requires. Looking this up on
+every trade is slow; caching it in memory only loses the mapping on restart.
+
+This module persists the mapping to disk as JSON so restarts stay cheap.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Protocol
+
+from xtb_api.types.instrument import InstrumentSearchResult
+
+logger = logging.getLogger(__name__)
+
+
+class _SearchClient(Protocol):
+    async def search_instrument(self, query: str) -> list[InstrumentSearchResult]: ...
+
+
+class InstrumentRegistry:
+    """Symbol → instrument-ID cache, persisted as JSON.
+
+    Example::
+
+        from xtb_api import XTBClient, InstrumentRegistry
+
+        client = XTBClient(email=..., password=..., account_number=...)
+        await client.connect()
+
+        reg = InstrumentRegistry("data/instrument_ids.json")
+        matched = await reg.populate(client, ["CIG.PL", "AAPL.US"])
+        print(f"Matched {len(matched)} instruments")
+
+        # Later:
+        instrument_id = reg.get("CIG.PL")  # 12345
+    """
+
+    def __init__(self, path: Path | str) -> None:
+        self._path = Path(path)
+        self._ids: dict[str, int] = {}
+        self._load()
+
+    def _load(self) -> None:
+        if not self._path.exists():
+            return
+        try:
+            raw = json.loads(self._path.read_text())
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.warning("Failed to load instrument IDs from %s: %s", self._path, exc)
+            return
+        if not isinstance(raw, dict) or not all(isinstance(k, str) and isinstance(v, int) for k, v in raw.items()):
+            logger.warning("Instrument ID file %s has unexpected structure, ignoring", self._path)
+            return
+        self._ids = raw
+        logger.info("Loaded %d instrument IDs from %s", len(self._ids), self._path)
+
+    def _save(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(json.dumps(self._ids, indent=2, sort_keys=True))
+
+    def get(self, symbol: str) -> int | None:
+        """Return the cached instrument ID for `symbol`, or None."""
+        return self._ids.get(symbol)
+
+    def set(self, symbol: str, instrument_id: int) -> None:
+        """Cache `symbol → instrument_id` and persist to disk immediately."""
+        self._ids[symbol] = instrument_id
+        self._save()
+
+    @property
+    def ids(self) -> dict[str, int]:
+        """Read-only view of the full cache."""
+        return dict(self._ids)
+
+    async def populate(
+        self,
+        client: _SearchClient,
+        symbols: Iterable[str],
+    ) -> dict[str, int]:
+        """Download the full instrument list via `client.search_instrument` and
+        match every requested symbol against it. Persist the matches.
+
+        Matches are case-insensitive. If a symbol like `BRK.B.US` does not
+        appear in the downloaded list, fall back to the dot-less variant
+        (`BRKB.US`).
+
+        Symbols are stored under the caller's original casing; subsequent
+        calls to `get()` must use the same case.
+
+        Returns a dict of the matches written during this call (does not
+        include pre-existing entries).
+        """
+        # Prime the client's in-memory cache (first call downloads all 11,888+
+        # instruments under the WS client's lock). Then read the full cache
+        # directly — search_instrument() only returns up to 100 filtered matches,
+        # which isn't enough for matching against a full universe.
+        await client.search_instrument("a")
+
+        ws = getattr(client, "ws", client)
+        raw = getattr(ws, "_symbols_cache", None)
+        if isinstance(raw, list) and raw:
+            all_results: list[InstrumentSearchResult] = list(raw)
+        else:
+            # Fallback when caller isn't an XTBClient (e.g., pure protocol implementer).
+            all_results = await client.search_instrument("a")
+
+        index = {r.symbol.upper(): r.instrument_id for r in all_results}
+
+        matched: dict[str, int] = {}
+        for sym in symbols:
+            key = sym.upper()
+            if key in index:
+                matched[sym] = index[key]
+                continue
+            # Dot-less fallback: BRK.B.US → BRKB.US. Skip symbols with no inner
+            # dots (e.g. AAPL.US) where the dot-less variant would be identical.
+            base, _, suffix = key.rpartition(".")
+            if base and "." in base:
+                alt = base.replace(".", "") + "." + suffix
+                if alt in index:
+                    matched[sym] = index[alt]
+
+        self._ids.update(matched)
+        self._save()
+        return matched

xtb_api/types/__init__.py

@@ -0,0 +1,6 @@
+"""XTB API type definitions."""
+
+from xtb_api.types.enums import *  # noqa: F403
+from xtb_api.types.instrument import *  # noqa: F403
+from xtb_api.types.trading import *  # noqa: F403
+from xtb_api.types.websocket import *  # noqa: F403

xtb_api/types/enums.py

@@ -0,0 +1,92 @@
+"""Enumerations for XTB API protocol."""
+
+from enum import IntEnum, StrEnum
+
+
+class Xs6Side(IntEnum):
+    """Trade side enumeration for buy/sell operations (WebSocket protocol).
+
+    WARNING: These values (BUY=0, SELL=1) differ from the gRPC protocol
+    constants in ``grpc.proto`` (SIDE_BUY=1, SIDE_SELL=2). Do NOT pass
+    ``Xs6Side`` values to gRPC functions or vice-versa.
+    """
+
+    BUY = 0  # WebSocket only — gRPC uses SIDE_BUY=1
+    SELL = 1  # WebSocket only — gRPC uses SIDE_SELL=2
+
+
+class TradeCommand(IntEnum):
+    """Trade command types for different order types."""
+
+    BUY = 0
+    SELL = 1
+    BUY_LIMIT = 2
+    SELL_LIMIT = 3
+    BUY_STOP = 4
+    SELL_STOP = 5
+
+
+class TradeType(IntEnum):
+    """Trade type classification for order execution."""
+
+    MARKET = 0
+    LIMIT = 1
+    STOP = 2
+
+
+class RequestTradeData(IntEnum):
+    """Field identifiers for trade request data."""
+
+    TYPE = 1
+    TRADE_TYPE = 2
+    SIDE = 3
+    VOLUME = 4
+    AMOUNT = 5
+    SL = 6
+    TP = 7
+    OFFSET = 8
+    PRICE = 9
+    EXPIRATION = 10
+    ORDER_ID = 11
+    INSTRUMENT_ID = 12
+    SL_AMOUNT = 13
+    TP_AMOUNT = 14
+    SYMBOL_KEY = 15
+
+
+class SymbolSessionType(IntEnum):
+    """Symbol trading session status."""
+
+    CLOSED = 0
+    OPEN = 1
+    LOBBY = 2
+
+
+class SocketStatus(StrEnum):
+    """WebSocket connection status."""
+
+    CONNECTING = "CONNECTING"
+    CONNECTED = "CONNECTED"
+    DISCONNECTING = "DISCONNECTING"
+    CLOSED = "CLOSED"
+    ERROR = "SOCKET_ERROR"
+
+
+class XTBEnvironment(StrEnum):
+    """XTB trading environment type."""
+
+    REAL = "real"
+    DEMO = "demo"
+
+
+class SubscriptionEid(IntEnum):
+    """Element IDs for WebSocket data subscriptions."""
+
+    POSITIONS = 1
+    TICKS = 2
+    SYMBOLS = 3
+    SYMBOL_GROUPS = 4
+    GROUP_SETTINGS = 5
+    REQUEST_STATUS = 6
+    ORDERS = 7
+    TOTAL_BALANCE = 1043

xtb_api/types/instrument.py

@@ -0,0 +1,45 @@
+"""Instrument and quote type definitions."""
+
+from pydantic import BaseModel
+
+
+class InstrumentSymbol(BaseModel):
+    """Complete instrument symbol definition from XTB."""
+
+    name: str
+    quote_id: int
+    instrument_id: int
+    id_asset_class: int
+    display_name: str
+    description: str
+    full_description: str = ""
+    group_id: int
+    search_group: str = ""
+    precision: int = 2
+    lot_min: float = 1.0
+    lot_step: float = 1.0
+    instrument_tag: str | None = None
+    has_depth: bool | None = None
+
+
+class Quote(BaseModel):
+    """Real-time quote/tick data."""
+
+    symbol: str
+    ask: float
+    bid: float
+    spread: float
+    high: float | None = None
+    low: float | None = None
+    time: int | None = None
+
+
+class InstrumentSearchResult(BaseModel):
+    """Instrument search result."""
+
+    symbol: str
+    instrument_id: int
+    name: str
+    description: str
+    asset_class: str
+    symbol_key: str

xtb_api/types/trading.py

@@ -0,0 +1,139 @@
+"""Trading type definitions."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+from xtb_api.types.enums import Xs6Side
+
+
+class IPrice(BaseModel):
+    """Price representation with value and scale.
+
+    Actual price = value × 10^(-scale)
+    """
+
+    value: int
+    scale: int
+
+
+class IVolume(BaseModel):
+    """Volume representation with value and scale."""
+
+    value: int
+    scale: int = 0
+
+
+class ISize(BaseModel):
+    """Trade size specification — either volume or amount."""
+
+    volume: IVolume | None = None
+    amount: float | None = None
+
+
+class IStopLossInput(BaseModel):
+    """Stop loss configuration."""
+
+    price: IPrice | None = None
+    trailingstopinput: dict | None = None
+
+
+class ITakeProfitInput(BaseModel):
+    """Take profit configuration."""
+
+    price: IPrice | None = None
+
+
+class INewMarketOrder(BaseModel):
+    """Market order definition for WebSocket trading."""
+
+    instrumentid: int
+    size: ISize
+    side: Xs6Side
+    stoploss: IStopLossInput | None = None
+    takeprofit: ITakeProfitInput | None = None
+
+
+class IXs6AuthAccount(BaseModel):
+    """Account information for trade events."""
+
+    number: int
+    server: str
+    currency: str
+
+
+class INewMarketOrderEvent(BaseModel):
+    """Complete market order event for WebSocket API."""
+
+    order: INewMarketOrder
+    uiTrackingId: str | None = None
+    account: IXs6AuthAccount
+
+
+class TradeOptions(BaseModel):
+    """Simplified trade options for high-level API."""
+
+    stop_loss: float | None = None
+    take_profit: float | None = None
+    trailing_stop: float | None = None
+    amount: float | None = None
+
+
+class Position(BaseModel):
+    """Open trading position information."""
+
+    symbol: str
+    instrument_id: int | None = None
+    volume: float
+    current_price: float = 0.0
+    open_price: float
+    stop_loss: float | None = None
+    take_profit: float | None = None
+    profit_percent: float = 0.0
+    profit_net: float = 0.0
+    swap: float | None = None
+    side: Literal["buy", "sell"]
+    order_id: str | None = None
+    commission: float | None = None
+    margin: float | None = None
+    open_time: int | None = None
+
+
+class PendingOrder(BaseModel):
+    """Pending (limit/stop) order information."""
+
+    symbol: str
+    instrument_id: int | None = None
+    volume: float
+    price: float
+    stop_loss: float | None = None
+    take_profit: float | None = None
+    side: Literal["buy", "sell"]
+    order_id: str | None = None
+    order_type: str | None = None
+    expiration: int | None = None
+    open_time: int | None = None
+
+
+class AccountBalance(BaseModel):
+    """Account balance and equity information."""
+
+    balance: float
+    equity: float
+    free_margin: float
+    currency: str
+    account_number: int
+
+
+class TradeResult(BaseModel):
+    """Trade execution result."""
+
+    success: bool
+    order_id: str | None = None
+    symbol: str
+    side: Literal["buy", "sell"]
+    volume: float | None = None
+    price: float | None = None
+    error: str | None = None

xtb_api/types/websocket.py

@@ -0,0 +1,164 @@
+"""WebSocket protocol type definitions."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+
+class CoreAPIPayload(BaseModel):
+    """Inner CoreAPI command payload."""
+
+    endpoint: str
+    accountId: str | None = None
+    subscribeElement: dict | None = None
+    unsubscribeElement: dict | None = None
+    getAndSubscribeElement: dict | None = None
+    ping: dict | None = None
+    tradeTransaction: dict | None = None
+    registerClientInfo: dict | None = None
+    logonWithServiceTicket: dict | None = None
+
+    model_config = {"extra": "allow"}
+
+
+class CoreAPICommand(BaseModel):
+    """CoreAPI command wrapper."""
+
+    CoreAPI: CoreAPIPayload
+
+
+class WSRequest(BaseModel):
+    """WebSocket request message format."""
+
+    reqId: str
+    command: list[CoreAPICommand]
+
+
+class WSResponse(BaseModel):
+    """WebSocket response message format."""
+
+    reqId: str = ""
+    response: list[Any] | None = None
+    data: Any | None = None
+    error: dict | None = None
+    status: int | None = None
+    events: list[dict] | None = None
+
+    model_config = {"extra": "allow"}
+
+
+class WSAuthOptions(BaseModel):
+    """Authentication options for WebSocket client."""
+
+    service_ticket: str | None = None
+    tgt: str | None = None
+    credentials: WSCredentials | None = None
+    browser_auth: bool = False
+
+
+class WSCredentials(BaseModel):
+    """Email/password credentials."""
+
+    email: str
+    password: str
+
+
+class WSClientConfig(BaseModel):
+    """WebSocket client configuration."""
+
+    url: str
+    account_number: int
+    endpoint: str = "meta1"
+    ping_interval: int = 10000
+    auto_reconnect: bool = True
+    max_reconnect_delay: int = 30000
+    app_name: str = "xStation5"
+    app_version: str = "2.94.1"
+    device: str = "Linux x86_64"
+    auth: WSAuthOptions | None = None
+
+
+class ClientInfo(BaseModel):
+    """Client information for registerClientInfo command."""
+
+    appName: str
+    appVersion: str
+    appBuildNumber: str = "0"
+    device: str
+    osVersion: str = ""
+    comment: str = "Python"
+    apiVersion: str = "2.73.0"
+    osType: int = 0
+    deviceType: int = 1
+
+
+class XLoginAccountInfo(BaseModel):
+    """Account info from login result."""
+
+    accountNo: int
+    currency: str
+    endpointType: str
+
+
+class XLoginResult(BaseModel):
+    """Login response data from successful authentication."""
+
+    accountList: list[XLoginAccountInfo] = []
+    endpointList: list[str] = []
+    userData: dict = {}
+
+
+class WSPushEventRow(BaseModel):
+    """Push event row data."""
+
+    key: str = ""
+    value: dict = {}
+
+    model_config = {"extra": "allow"}
+
+
+class WSPushEvent(BaseModel):
+    """Push event in a push message."""
+
+    eid: int
+    row: WSPushEventRow
+
+    model_config = {"extra": "allow"}
+
+
+class WSPushMessage(BaseModel):
+    """Push message structure for real-time data updates."""
+
+    reqId: str = ""
+    status: int = 1
+    events: list[WSPushEvent] = []
+
+    model_config = {"extra": "allow"}
+
+
+class CASLoginSuccess(BaseModel):
+    """Successful CAS login result."""
+
+    type: Literal["success"] = "success"
+    tgt: str
+    expires_at: float
+
+
+class CASLoginTwoFactorRequired(BaseModel):
+    """CAS login requiring two-factor authentication."""
+
+    type: Literal["requires_2fa"] = "requires_2fa"
+    login_ticket: str
+    session_id: str = ""  # backward compat (may be same as login_ticket or empty)
+    two_factor_auth_type: str = "SMS"
+    methods: list[str] = ["TOTP"]
+    expires_at: float
+
+
+CASLoginResult = CASLoginSuccess | CASLoginTwoFactorRequired
+
+
+# Backward-compatible re-export — canonical location is xtb_api.exceptions
+from xtb_api.exceptions import CASError as CASError  # noqa: E402, F401

xtb_api/utils.py

@@ -0,0 +1,62 @@
+"""Utility functions for price/volume conversion and helpers."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+
+from pydantic import BaseModel
+
+from xtb_api.types.trading import IPrice, IVolume
+
+
+def price_from_decimal(price: float, precision: int) -> IPrice:
+    """Create IPrice from decimal: price_from_decimal(2.62, 2) → IPrice(value=262, scale=2)"""
+    value = round(price * (10**precision))
+    return IPrice(value=value, scale=precision)
+
+
+def price_to_decimal(price: IPrice) -> float:
+    """Convert IPrice to decimal: price_to_decimal(IPrice(value=262, scale=2)) → 2.62"""
+    return float(price.value) * float(10 ** (-price.scale))
+
+
+def volume_from(qty: int, scale: int = 0) -> IVolume:
+    """Create IVolume: volume_from(19) → IVolume(value=19, scale=0)"""
+    return IVolume(value=qty, scale=scale)
+
+
+def generate_req_id(prefix: str) -> str:
+    """Generate unique request ID."""
+    return f"{prefix}_{int(time.time() * 1000)}_{random.randint(0, 999)}"
+
+
+def build_account_id(account_number: int, endpoint: str = "meta1") -> str:
+    """Build accountId: 'meta1_{accountNumber}'"""
+    return f"{endpoint}_{account_number}"
+
+
+class ParsedSymbolKey(BaseModel):
+    """Parsed symbol key components."""
+
+    asset_class_id: int
+    symbol_name: str
+    group_id: int
+
+
+def parse_symbol_key(key: str) -> ParsedSymbolKey | None:
+    """Parse symbol key: '9_CIG.PL_6' → ParsedSymbolKey(9, 'CIG.PL', 6)"""
+    parts = key.split("_")
+    if len(parts) < 3:
+        return None
+    return ParsedSymbolKey(
+        asset_class_id=int(parts[0]),
+        symbol_name="_".join(parts[1:-1]),
+        group_id=int(parts[-1]),
+    )
+
+
+async def sleep(ms: int) -> None:
+    """Sleep helper (milliseconds)."""
+    await asyncio.sleep(ms / 1000)

xtb_api/ws/__init__.py

@@ -0,0 +1,3 @@
+"""WebSocket client module."""
+
+from xtb_api.ws.ws_client import XTBWebSocketClient as XTBWebSocketClient