xtb-api-python

Unofficial — Reverse-engineered from xStation5. Not affiliated with XTB. Use at your own risk.

Python client for the XTB xStation5 trading platform. Dead-simple API that handles all authentication, token refresh, and transport selection transparently.

Features

• Single Client — One XTBClient handles everything, no mode selection needed
• Auto Auth — Full CAS login flow with automatic TGT/JWT refresh
• 2FA Support — Automatic TOTP handling when totp_secret is provided
• Real-time Data — Live quotes, positions, balance via WebSocket push events
• Trading — Buy/sell market orders with SL/TP via gRPC-web
• Volume-Validated Orders — buy/sell reject volume < 1 before touching the wire
• Persistent Instrument Cache — InstrumentRegistry caches symbol → instrument-ID lookups to disk
• Full Symbol Search — Search and resolve all listed instruments with caching
• Modern Python — async/await, Pydantic models, strict typing, Python 3.12+

Requirements

• Python 3.12 or 3.13
• Chromium browser (installed via playwright — see post-install step below)
• An XTB trading account

Install

pip install xtb-api-python

# With automatic 2FA handling:
pip install "xtb-api-python[totp]"

Post-install setup (REQUIRED)

This library uses Playwright to authenticate with XTB's servers (the REST login path is blocked by a WAF). After pip install, you must download the Chromium binary:

playwright install chromium

Without this step, the first call to client.connect() will fail with a CASError("BROWSER_CHROMIUM_MISSING", ...) and a pointer back here.

To verify your install is complete, run:

python -m xtb_api doctor

Development install

pip install -e ".[dev,totp]"
playwright install chromium
pre-commit install

Quick Start

import asyncio
from xtb_api import XTBClient

async def main():
    client = XTBClient(
        email="your@email.com",
        password="your-password",
        account_number=12345678,
        totp_secret="BASE32SECRET",      # optional, auto-handles 2FA
        session_file="~/.xtb_session",   # optional, persists auth across restarts
    )

    await client.connect()

    # Account data
    balance = await client.get_balance()
    print(f"Balance: {balance.balance} {balance.currency}")

    positions = await client.get_positions()
    orders = await client.get_orders()

    # Live quote
    quote = await client.get_quote("EURUSD")
    if quote:
        print(f"Bid: {quote.bid}, Ask: {quote.ask}")

    # Search instruments
    results = await client.search_instrument("Apple")

    # Persistent instrument cache (avoids re-fetching the full symbol list)
    from xtb_api import InstrumentRegistry
    registry = InstrumentRegistry("~/.xtb_instruments.json")
    matched = await registry.populate(client, ["AAPL.US", "EURUSD"])
    instrument_id = registry.get("AAPL.US")  # int | None

    # Trading (USE WITH CAUTION!)
    result = await client.buy("AAPL.US", volume=1, stop_loss=150.0, take_profit=200.0)
    print(f"Order: {result.order_id}")

    await client.disconnect()

asyncio.run(main())

Real-time Events

client.on("tick", lambda tick: print(f"{tick['symbol']}: {tick['bid']}/{tick['ask']}"))
client.on("position", lambda pos: print(f"Position update: {pos['symbol']}"))

await client.subscribe_ticks("EURUSD")

Advanced Trade Options

from xtb_api import TradeOptions

# Simple: flat kwargs
await client.buy("EURUSD", volume=1, stop_loss=1.0850, take_profit=1.0950)

# Advanced: TradeOptions object
await client.sell("CIG.PL", volume=100, options=TradeOptions(
    trailing_stop=50,
    amount=1000.0,  # amount-based sizing
))

Queued orders (market closed)

When the instrument's market is closed, XTB accepts the order and queues it until market open. The library surfaces this as TradeOutcome.QUEUED rather than lying about a fill:

result = await client.buy("AAPL.US", volume=1)

match result.status:
    case TradeOutcome.FILLED:
        print(f"Filled at {result.price}")
    case TradeOutcome.QUEUED:
        print(f"Queued {result.order_number}; cancelling...")
        cancel = await client.cancel_order(result.order_number)
        print(f"Cancel status: {cancel.status}")
    case _:
        print(f"Trade failed: {result.status} — {result.error}")

TradeResult.order_number is populated for both FILLED and QUEUED outcomes. cancel_order() returns a typed CancelResult with CancelOutcome values (CANCELLED, REJECTED, AMBIGUOUS).

TradeResult.price is populated by polling open positions immediately after fill. If the position cannot be located within the poll window, price remains None.

API Reference

XTBClient

Constructor Parameters

InstrumentRegistry

Persistent symbol → instrument-ID cache, stored as JSON.

Demo vs Real

Set XTB_ACCOUNT_TYPE=demo in your environment (or pass account_type="demo" to XTBClient) to connect to XTB's paper-trading environment instead of live. The library picks the correct WebSocket endpoint and account server as a pair — you never need to set both manually.

Defaults to real when unset, matching previous versions.

For non-standard endpoints or account servers, XTB_WS_URL and XTB_ACCOUNT_SERVER env vars override each field individually and win over the account_type preset — see .env.example.

Advanced: Direct Access

For advanced use cases, access the underlying clients:

# WebSocket client (always available)
ws = client.ws

# gRPC client (available after first trade)
grpc = client.grpc_client

# Auth manager (accessor, or import the public alias)
auth = client.auth
from xtb_api import XTBAuth  # public alias for the AuthManager class
tgt = await auth.get_tgt()

Architecture

XTBClient (public facade)
|
+-- AuthManager (shared auth session)
|   +-- CASClient (REST + Playwright browser auth)
|   +-- TGT cache (memory + disk)
|
+-- XTBWebSocketClient (quotes, positions, balance)
|   +-- Auto-reconnect with fresh service tickets
|
+-- GrpcClient (trading, lazy-initialized)
    +-- JWT auto-refresh from shared TGT

How Authentication Works

1. Login — REST CAS attempt, falls back to Playwright browser if WAF blocks
2. TGT — 8-hour token, cached in memory + optional session file
3. Service Ticket — Derived from TGT, used for WebSocket login
4. JWT — 5-minute token for gRPC trading, auto-refreshed from TGT
5. 2FA — Automatic TOTP if totp_secret provided

All token refresh is transparent. If a TGT expires mid-session, the full auth chain re-runs automatically.

Disclaimer

This is an unofficial, community-driven project. NOT affiliated with, endorsed by, or connected to XTB S.A.

• Use at your own risk — trading involves financial risk
• No warranty — provided "as is"
• API stability — XTB may change their internal APIs at any time
• Always test on demo accounts first

License

MIT