topstep-client-py 0.1.0__py3-none-any.whl

topstep/__init__.py

@@ -0,0 +1,55 @@
+"""TopstepX Python Client — async SDK for the ProjectX Gateway API."""
+
+from topstep.client import TopstepClient
+from topstep.exceptions import (
+    APIError,
+    AuthenticationError,
+    HTTPError,
+    RateLimitError,
+    TopstepError,
+)
+from topstep.models import (
+    Account,
+    Bar,
+    BarUnit,
+    Bracket,
+    Contract,
+    Order,
+    OrderSide,
+    OrderStatus,
+    OrderType,
+    PlaceOrderRequest,
+    Position,
+    PositionType,
+    Trade,
+)
+from topstep.realtime import MarketHub, UserHub
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TopstepClient",
+    # Exceptions
+    "TopstepError",
+    "AuthenticationError",
+    "APIError",
+    "HTTPError",
+    "RateLimitError",
+    # Models
+    "Account",
+    "Bar",
+    "BarUnit",
+    "Bracket",
+    "Contract",
+    "Order",
+    "OrderSide",
+    "OrderStatus",
+    "OrderType",
+    "PlaceOrderRequest",
+    "Position",
+    "PositionType",
+    "Trade",
+    # Realtime
+    "MarketHub",
+    "UserHub",
+]

topstep/auth.py

@@ -0,0 +1,50 @@
+"""Authentication and token management."""
+
+from __future__ import annotations
+
+from topstep.exceptions import AuthenticationError
+from topstep.http import HTTPClient
+
+
+async def login_key(http: HTTPClient, username: str, api_key: str) -> str:
+    """Authenticate with username + API key. Returns the session token."""
+    data = await http.post("/api/Auth/loginKey", {
+        "userName": username,
+        "apiKey": api_key,
+    })
+
+    token = data.get("token")
+    if not token:
+        raise AuthenticationError("Login succeeded but no token returned")
+
+    return token
+
+
+async def login_app(
+    http: HTTPClient,
+    username: str,
+    password: str,
+    device_id: str,
+    app_id: str,
+    verify_key: str,
+) -> str:
+    """Authenticate as an authorized application. Returns the session token."""
+    data = await http.post("/api/Auth/loginApp", {
+        "userName": username,
+        "password": password,
+        "deviceId": device_id,
+        "appId": app_id,
+        "verifyKey": verify_key,
+    })
+
+    token = data.get("token")
+    if not token:
+        raise AuthenticationError("Login succeeded but no token returned")
+
+    return token
+
+
+async def validate_token(http: HTTPClient) -> str | None:
+    """Validate the current token and return a refreshed one if available."""
+    data = await http.post("/api/Auth/validate")
+    return data.get("newToken") or data.get("token")

topstep/client.py

@@ -0,0 +1,118 @@
+"""TopstepX API client — the main entry point."""
+
+from __future__ import annotations
+
+from topstep import auth
+from topstep.endpoints.accounts import AccountsEndpoint
+from topstep.endpoints.contracts import ContractsEndpoint
+from topstep.endpoints.history import HistoryEndpoint
+from topstep.endpoints.orders import OrdersEndpoint
+from topstep.endpoints.positions import PositionsEndpoint
+from topstep.endpoints.trades import TradesEndpoint
+from topstep.http import BASE_URL, HTTPClient
+from topstep.realtime.market_hub import MarketHub
+from topstep.realtime.user_hub import UserHub
+
+
+class TopstepClient:
+    """Async client for the TopstepX / ProjectX Gateway API.
+
+    Usage::
+
+        async with await TopstepClient.create(
+            username="you@email.com",
+            api_key="your-key",
+        ) as client:
+            accounts = await client.accounts.search()
+            bars = await client.history.retrieve_bars(contract_id, start, end)
+    """
+
+    def __init__(self, http: HTTPClient) -> None:
+        # Use TopstepClient.create() instead of calling __init__ directly.
+        self._http = http
+
+        # Namespaced REST endpoints
+        self.accounts = AccountsEndpoint(http)
+        self.contracts = ContractsEndpoint(http)
+        self.history = HistoryEndpoint(http)
+        self.orders = OrdersEndpoint(http)
+        self.positions = PositionsEndpoint(http)
+        self.trades = TradesEndpoint(http)
+
+        # Realtime hubs (lazily connected)
+        self._market_hub: MarketHub | None = None
+        self._user_hub: UserHub | None = None
+
+    @classmethod
+    async def create(
+        cls,
+        username: str,
+        api_key: str,
+        base_url: str = BASE_URL,
+        timeout: float = 30.0,
+    ) -> TopstepClient:
+        """Create and authenticate a new client.
+
+        This is the primary way to instantiate the client since
+        authentication is an async operation.
+        """
+        http = HTTPClient(base_url=base_url, timeout=timeout)
+        try:
+            token = await auth.login_key(http, username, api_key)
+        except Exception:
+            await http.close()
+            raise
+
+        http.token = token
+        return cls(http)
+
+    @property
+    def token(self) -> str | None:
+        """Current session token."""
+        return self._http.token
+
+    async def refresh_token(self) -> None:
+        """Validate and refresh the session token."""
+        new_token = await auth.validate_token(self._http)
+        if new_token:
+            self._http.token = new_token
+            if self._market_hub is not None:
+                self._market_hub.set_token(new_token)
+            if self._user_hub is not None:
+                self._user_hub.set_token(new_token)
+
+    @property
+    def market(self) -> MarketHub:
+        """Real-time market data hub (quotes, trades, depth).
+
+        The connection is created on first access. Call
+        ``await client.market.connect()`` before subscribing.
+        """
+        if self._market_hub is None:
+            self._market_hub = MarketHub(self._http.token or "")
+        return self._market_hub
+
+    @property
+    def user(self) -> UserHub:
+        """Real-time user hub (accounts, orders, positions, trades).
+
+        The connection is created on first access. Call
+        ``await client.user.connect()`` before subscribing.
+        """
+        if self._user_hub is None:
+            self._user_hub = UserHub(self._http.token or "")
+        return self._user_hub
+
+    async def close(self) -> None:
+        """Close all connections (HTTP + WebSocket hubs)."""
+        if self._market_hub is not None:
+            await self._market_hub.stop()
+        if self._user_hub is not None:
+            await self._user_hub.stop()
+        await self._http.close()
+
+    async def __aenter__(self) -> TopstepClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

topstep/endpoints/__init__.py

@@ -0,0 +1,17 @@
+"""Endpoint service classes."""
+
+from topstep.endpoints.accounts import AccountsEndpoint
+from topstep.endpoints.contracts import ContractsEndpoint
+from topstep.endpoints.history import HistoryEndpoint
+from topstep.endpoints.orders import OrdersEndpoint
+from topstep.endpoints.positions import PositionsEndpoint
+from topstep.endpoints.trades import TradesEndpoint
+
+__all__ = [
+    "AccountsEndpoint",
+    "ContractsEndpoint",
+    "HistoryEndpoint",
+    "OrdersEndpoint",
+    "PositionsEndpoint",
+    "TradesEndpoint",
+]

topstep/endpoints/accounts.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from topstep.http import HTTPClient
+from topstep.models.account import Account
+
+
+class AccountsEndpoint:
+    """Operations on trading accounts."""
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    async def search(self, only_active: bool = True) -> list[Account]:
+        """Search accounts. By default returns only active accounts."""
+        data = await self._http.post("/api/Account/search", {
+            "onlyActiveAccounts": only_active,
+        })
+        return [Account.model_validate(a) for a in data.get("accounts", [])]

topstep/endpoints/contracts.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from topstep.http import HTTPClient
+from topstep.models.contract import Contract
+
+
+class ContractsEndpoint:
+    """Operations on futures contracts."""
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    async def available(self, live: bool = False) -> list[Contract]:
+        """List all available contracts."""
+        data = await self._http.post("/api/Contract/available", {"live": live})
+        return [Contract.model_validate(c) for c in data.get("contracts", [])]
+
+    async def search(self, text: str, live: bool = False) -> list[Contract]:
+        """Search contracts by name/description (max 20 results)."""
+        data = await self._http.post("/api/Contract/search", {
+            "searchText": text,
+            "live": live,
+        })
+        return [Contract.model_validate(c) for c in data.get("contracts", [])]
+
+    async def search_by_id(self, contract_id: str) -> Contract:
+        """Look up a single contract by its ID."""
+        data = await self._http.post("/api/Contract/searchById", {
+            "contractId": contract_id,
+        })
+        return Contract.model_validate(data["contract"])

topstep/endpoints/history.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from topstep.http import HTTPClient
+from topstep.models.bar import Bar, BarUnit
+
+
+class HistoryEndpoint:
+    """Historical market data."""
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    async def retrieve_bars(
+        self,
+        contract_id: str,
+        start: datetime,
+        end: datetime,
+        unit: BarUnit = BarUnit.MINUTE,
+        unit_number: int = 1,
+        limit: int = 20000,
+        include_partial_bar: bool = False,
+    ) -> list[Bar]:
+        """Retrieve historical OHLCV bars.
+
+        Args:
+            contract_id: The contract to fetch bars for.
+            start: Start of the time range (UTC).
+            end: End of the time range (UTC).
+            unit: Bar timeframe unit (second, minute, hour, etc.).
+            unit_number: Number of units per bar (e.g. 5 for 5-minute bars).
+            limit: Maximum number of bars to return (API max: 20000).
+            include_partial_bar: Whether to include the current incomplete bar.
+
+        Rate limit: 50 requests per 30 seconds.
+        """
+        data = await self._http.post("/api/History/retrieveBars", {
+            "contractId": contract_id,
+            "live": False,
+            "startTime": start.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "endTime": end.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "unit": int(unit),
+            "unitNumber": unit_number,
+            "limit": limit,
+            "includePartialBar": include_partial_bar,
+        })
+        return [Bar.model_validate(b) for b in data.get("bars", [])]

topstep/endpoints/orders.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from topstep.http import HTTPClient
+from topstep.models.order import Order, PlaceOrderRequest
+
+
+class OrdersEndpoint:
+    """Operations on orders."""
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    async def place(self, order: PlaceOrderRequest) -> int:
+        """Place a new order. Returns the order ID."""
+        data = await self._http.post("/api/Order/place", order.to_api_dict())
+        return data["orderId"]
+
+    async def modify(
+        self,
+        account_id: int,
+        order_id: int,
+        size: Optional[int] = None,
+        limit_price: Optional[float] = None,
+        stop_price: Optional[float] = None,
+        trail_price: Optional[float] = None,
+    ) -> None:
+        """Modify an open order."""
+        payload: dict = {
+            "accountId": account_id,
+            "orderId": order_id,
+        }
+        if size is not None:
+            payload["size"] = size
+        if limit_price is not None:
+            payload["limitPrice"] = limit_price
+        if stop_price is not None:
+            payload["stopPrice"] = stop_price
+        if trail_price is not None:
+            payload["trailPrice"] = trail_price
+
+        await self._http.post("/api/Order/modify", payload)
+
+    async def cancel(self, account_id: int, order_id: int) -> None:
+        """Cancel an open order."""
+        await self._http.post("/api/Order/cancel", {
+            "accountId": account_id,
+            "orderId": order_id,
+        })
+
+    async def search(
+        self,
+        account_id: int,
+        start: datetime,
+        end: Optional[datetime] = None,
+    ) -> list[Order]:
+        """Search orders by time range."""
+        payload: dict = {
+            "accountId": account_id,
+            "startTimestamp": start.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        }
+        if end is not None:
+            payload["endTimestamp"] = end.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        data = await self._http.post("/api/Order/search", payload)
+        return [Order.model_validate(o) for o in data.get("orders", [])]
+
+    async def search_open(self, account_id: int) -> list[Order]:
+        """Get all currently open orders for an account."""
+        data = await self._http.post("/api/Order/searchOpen", {
+            "accountId": account_id,
+        })
+        return [Order.model_validate(o) for o in data.get("orders", [])]

topstep/endpoints/positions.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from topstep.http import HTTPClient
+from topstep.models.position import Position
+
+
+class PositionsEndpoint:
+    """Operations on positions."""
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    async def search_open(self, account_id: int) -> list[Position]:
+        """Get all open positions for an account."""
+        data = await self._http.post("/api/Position/searchOpen", {
+            "accountId": account_id,
+        })
+        return [Position.model_validate(p) for p in data.get("positions", [])]
+
+    async def close(self, account_id: int, contract_id: str) -> None:
+        """Close all positions for a contract."""
+        await self._http.post("/api/Position/closeContract", {
+            "accountId": account_id,
+            "contractId": contract_id,
+        })
+
+    async def partial_close(self, account_id: int, contract_id: str, size: int) -> None:
+        """Partially close a position (specify number of contracts to close)."""
+        await self._http.post("/api/Position/partialCloseContract", {
+            "accountId": account_id,
+            "contractId": contract_id,
+            "size": size,
+        })

topstep/endpoints/trades.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from topstep.http import HTTPClient
+from topstep.models.trade import Trade
+
+
+class TradesEndpoint:
+    """Operations on trade history."""
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    async def search(
+        self,
+        account_id: int,
+        start: datetime,
+        end: Optional[datetime] = None,
+    ) -> list[Trade]:
+        """Search trades by time range."""
+        payload: dict = {
+            "accountId": account_id,
+            "startTimestamp": start.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        }
+        if end is not None:
+            payload["endTimestamp"] = end.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        data = await self._http.post("/api/Trade/search", payload)
+        return [Trade.model_validate(t) for t in data.get("trades", [])]

topstep/exceptions.py

@@ -0,0 +1,32 @@
+"""Exception hierarchy for the TopstepX client."""
+
+
+class TopstepError(Exception):
+    """Base exception for all TopstepX client errors."""
+
+
+class AuthenticationError(TopstepError):
+    """Raised when authentication fails (invalid credentials, expired token)."""
+
+
+class APIError(TopstepError):
+    """Raised when the API returns success=False in its response."""
+
+    def __init__(self, message: str, error_code: int = 0):
+        self.error_code = error_code
+        super().__init__(f"[{error_code}] {message}" if error_code else message)
+
+
+class HTTPError(TopstepError):
+    """Raised for non-200 HTTP status codes."""
+
+    def __init__(self, status_code: int, detail: str = ""):
+        self.status_code = status_code
+        super().__init__(f"HTTP {status_code}: {detail}" if detail else f"HTTP {status_code}")
+
+
+class RateLimitError(HTTPError):
+    """Raised when the API returns HTTP 429 (too many requests)."""
+
+    def __init__(self, detail: str = "Rate limit exceeded"):
+        super().__init__(status_code=429, detail=detail)

topstep/http.py

@@ -0,0 +1,102 @@
+"""Low-level async HTTP client with auth headers, retry, and error handling."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+
+from topstep.exceptions import APIError, AuthenticationError, HTTPError, RateLimitError
+
+# TopstepX base URLs
+BASE_URL = "https://api.topstepx.com"
+WS_USER_HUB = "https://rtc.topstepx.com/hubs/user"
+WS_MARKET_HUB = "https://rtc.topstepx.com/hubs/market"
+
+# Default retry config
+MAX_RETRIES = 3
+RETRY_BACKOFF = 1.0  # seconds, doubles each retry
+
+
+class HTTPClient:
+    """Async HTTP wrapper that handles auth headers, retries, and error parsing."""
+
+    def __init__(self, base_url: str = BASE_URL, timeout: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self._token: str | None = None
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+        )
+
+    @property
+    def token(self) -> str | None:
+        return self._token
+
+    @token.setter
+    def token(self, value: str | None) -> None:
+        self._token = value
+        if value:
+            self._client.headers["Authorization"] = f"Bearer {value}"
+        else:
+            self._client.headers.pop("Authorization", None)
+
+    async def post(self, path: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Make a POST request with retry logic and error handling.
+
+        Returns the parsed JSON response body (the API envelope is validated
+        and stripped — callers get the raw dict to pick out domain fields).
+        """
+        last_exc: Exception | None = None
+
+        for attempt in range(MAX_RETRIES):
+            try:
+                response = await self._client.post(path, json=payload or {})
+            except httpx.TimeoutException as exc:
+                last_exc = HTTPError(408, f"Request timed out: {exc}")
+                await asyncio.sleep(RETRY_BACKOFF * (2**attempt))
+                continue
+            except httpx.HTTPError as exc:
+                last_exc = HTTPError(0, str(exc))
+                await asyncio.sleep(RETRY_BACKOFF * (2**attempt))
+                continue
+
+            # Rate limit — wait and retry
+            if response.status_code == 429:
+                last_exc = RateLimitError()
+                await asyncio.sleep(RETRY_BACKOFF * (2**attempt))
+                continue
+
+            # Auth failure — no point retrying
+            if response.status_code == 401:
+                raise AuthenticationError("Unauthorized — invalid or expired token")
+
+            # Other HTTP errors
+            if response.status_code != 200:
+                raise HTTPError(response.status_code, response.text)
+
+            # Parse JSON envelope
+            data = response.json()
+            if not data.get("success", False):
+                error_code = data.get("errorCode", 0)
+                error_msg = data.get("errorMessage") or "Unknown API error"
+                raise APIError(error_msg, error_code)
+
+            return data
+
+        # All retries exhausted
+        raise last_exc  # type: ignore[misc]
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> HTTPClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

topstep/models/__init__.py

@@ -0,0 +1,31 @@
+"""Pydantic models for TopstepX API responses."""
+
+from topstep.models.account import Account
+from topstep.models.bar import Bar, BarUnit
+from topstep.models.contract import Contract
+from topstep.models.order import (
+    Bracket,
+    Order,
+    OrderSide,
+    OrderStatus,
+    OrderType,
+    PlaceOrderRequest,
+)
+from topstep.models.position import Position, PositionType
+from topstep.models.trade import Trade
+
+__all__ = [
+    "Account",
+    "Bar",
+    "BarUnit",
+    "Bracket",
+    "Contract",
+    "Order",
+    "OrderSide",
+    "OrderStatus",
+    "OrderType",
+    "PlaceOrderRequest",
+    "Position",
+    "PositionType",
+    "Trade",
+]

topstep/models/account.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel, Field
+
+
+class Account(BaseModel):
+    """A TopstepX trading account."""
+
+    model_config = {"populate_by_name": True}
+
+    id: int
+    name: str
+    balance: float
+    can_trade: bool = Field(alias="canTrade")
+    is_visible: bool = Field(alias="isVisible")