fidelity-trader-api 0.1.0__py3-none-any.whl

fidelity_trader/__init__.py

@@ -0,0 +1,22 @@
+from fidelity_trader.client import FidelityClient
+from fidelity_trader.async_client import AsyncFidelityClient
+from fidelity_trader.exceptions import (
+    FidelityError,
+    AuthenticationError,
+    SessionExpiredError,
+    CSRFTokenError,
+    APIError,
+    DryRunError,
+)
+
+__all__ = [
+    "FidelityClient",
+    "AsyncFidelityClient",
+    "FidelityError",
+    "AuthenticationError",
+    "SessionExpiredError",
+    "CSRFTokenError",
+    "APIError",
+    "DryRunError",
+]
+__version__ = "0.1.0"

fidelity_trader/_http.py

@@ -0,0 +1,75 @@
+import uuid
+import httpx
+
+from fidelity_trader.retry import RetryTransport
+
+BASE_URL = "https://digital.fidelity.com"
+AUTH_URL = "https://ecaap.fidelity.com"
+
+REQUEST_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/146.0.0.0 Safari/537.36 Edg/146.0.0.0 "
+        "ATPNext/4.4.1.7 FTPlusDesktop/4.4.1.7"
+    ),
+    "AppId": "RETAIL-CC-LOGIN-SDK",
+    "AppName": "PILoginExperience",
+    "Content-Type": "application/json",
+    "Accept": "*/*",
+    "Origin": BASE_URL,
+    "Referer": f"{BASE_URL}/",
+    "Accept-Token-Type": "ET",
+    "Accept-Token-Location": "HEADER",
+    "Token-Location": "HEADER",
+    "Cache-Control": "no-cache, no-store, must-revalidate",
+}
+
+# Data/Trading API host (from captured traffic)
+DPSERVICE_URL = "https://dpservice.fidelity.com"
+ALERTS_URL = "https://ecawsgateway.fidelity.com"
+STREAMING_NEWS_URL = "https://streaming-news.mds.fidelity.com"
+FASTQUOTE_URL = "https://fastquote.fidelity.com"
+
+# Headers used by Fidelity Trader+ desktop app for data APIs
+# (different from login headers which use RETAIL-CC-LOGIN-SDK)
+ATP_HEADERS = {
+    "AppId": "AP149323",
+    "AppName": "Active Trader Desktop for Windows",
+    "User-Agent": "ATPNext/4.4.1.7 FTPlusDesktop/4.4.1.7",
+    "Content-Type": "application/json; charset=utf-8",
+    "Accept": "application/json",
+}
+
+def create_session(timeout: float = 30.0) -> httpx.Client:
+    return httpx.Client(follow_redirects=True, timeout=timeout, headers=REQUEST_HEADERS)
+
+def create_atp_session(
+    timeout: float = 30.0,
+    max_retries: int = 0,
+    retry_delay: float = 1.0,
+    backoff_factor: float = 2.0,
+) -> httpx.Client:
+    """Create a pre-configured httpx client for Fidelity Trader+ data APIs.
+
+    When *max_retries* > 0, the underlying transport is wrapped in a
+    :class:`RetryTransport` that retries on transient failures (connection
+    errors, timeouts, 429/5xx status codes) with exponential backoff.
+    The default (*max_retries=0*) preserves existing behaviour with no retry.
+    """
+    transport: httpx.BaseTransport | None = None
+    if max_retries > 0:
+        transport = RetryTransport(
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            backoff_factor=backoff_factor,
+        )
+    return httpx.Client(
+        follow_redirects=True,
+        timeout=timeout,
+        headers=ATP_HEADERS,
+        transport=transport,
+    )
+
+def make_req_id() -> str:
+    return f"REQ{uuid.uuid4().hex}"

fidelity_trader/alerts/__init__.py

@@ -0,0 +1,4 @@
+"""Alerts subscription module for Fidelity Trader+."""
+from fidelity_trader.alerts.subscription import AlertsAPI
+
+__all__ = ["AlertsAPI"]

fidelity_trader/alerts/price_triggers.py

@@ -0,0 +1,140 @@
+"""Price triggers API — list, create, and delete price-based alert triggers."""
+from __future__ import annotations
+
+from typing import List, Optional
+
+import httpx
+
+from fidelity_trader._http import DPSERVICE_URL
+from fidelity_trader.models.price_trigger import (
+    DEFAULT_DEVICES,
+    PriceTriggerCreateRequest,
+    PriceTriggerCreateResponse,
+    PriceTriggerDeleteRequest,
+    PriceTriggerDeleteResponse,
+    PriceTriggerDevice,
+    PriceTriggersResponse,
+)
+
+_PRICE_TRIGGERS_BASE = (
+    "/ftgw/dp/retail-price-triggers/v1"
+    "/investments/research/alert/price-triggers"
+)
+
+_PRICE_TRIGGERS_PATH = f"{_PRICE_TRIGGERS_BASE}/list"
+_PRICE_TRIGGERS_CREATE_PATH = f"{_PRICE_TRIGGERS_BASE}/create"
+_PRICE_TRIGGERS_DELETE_PATH = f"{_PRICE_TRIGGERS_BASE}/delete"
+
+
+class PriceTriggersAPI:
+    """Client for the Fidelity price triggers endpoints (list, create, delete)."""
+
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def get_price_triggers(
+        self,
+        symbol: str,
+        status: str = "active",
+        offset: int = 0,
+    ) -> PriceTriggersResponse:
+        """Fetch the list of price triggers for a given symbol.
+
+        GETs ``/ftgw/dp/retail-price-triggers/v1/investments/research/alert/
+        price-triggers/list`` with query parameters ``symbol``, ``status``,
+        and ``offset``.
+
+        Args:
+            symbol: Ticker symbol to query (e.g. ``"QS"``).
+            status: Filter by trigger status (default ``"active"``).
+            offset: Pagination offset (default ``0``).
+
+        Returns:
+            A :class:`~fidelity_trader.models.price_trigger.PriceTriggersResponse`.
+
+        Raises:
+            httpx.HTTPStatusError: on non-2xx responses.
+        """
+        params = {
+            "symbol": symbol,
+            "status": status,
+            "offset": offset,
+        }
+        resp = self._http.get(
+            f"{DPSERVICE_URL}{_PRICE_TRIGGERS_PATH}",
+            params=params,
+        )
+        resp.raise_for_status()
+        return PriceTriggersResponse.from_api_response(resp.json())
+
+    def create_price_trigger(
+        self,
+        symbol: str,
+        operator: str,
+        value: float,
+        currency: str = "USD",
+        notes: str = "",
+        devices: Optional[List[PriceTriggerDevice]] = None,
+    ) -> PriceTriggerCreateResponse:
+        """Create a new price trigger.
+
+        POSTs to ``/ftgw/dp/retail-price-triggers/v1/investments/research/
+        alert/price-triggers/create``.
+
+        Args:
+            symbol: Ticker symbol (e.g. ``"SPY"``).
+            operator: Trigger operator. Captured values:
+                ``"lessThanPercent"``, ``"greaterThanPercent"``,
+                ``"lessThan"``, ``"greaterThan"``.
+            value: Trigger threshold value.
+            currency: Currency code (default ``"USD"``).
+            notes: Optional note text (default ``""``).
+            devices: Notification devices. Defaults to
+                Active Trader Pro and Fidelity mobile applications.
+
+        Returns:
+            A :class:`~fidelity_trader.models.price_trigger.PriceTriggerCreateResponse`.
+
+        Raises:
+            httpx.HTTPStatusError: on non-2xx responses.
+        """
+        request = PriceTriggerCreateRequest(
+            symbol=symbol,
+            operator=operator,
+            value=value,
+            currency=currency,
+            notes=notes,
+            devices=devices if devices is not None else list(DEFAULT_DEVICES),
+        )
+        resp = self._http.post(
+            f"{DPSERVICE_URL}{_PRICE_TRIGGERS_CREATE_PATH}",
+            json=request.to_api_payload(),
+        )
+        resp.raise_for_status()
+        return PriceTriggerCreateResponse.from_api_response(resp.json())
+
+    def delete_price_triggers(
+        self,
+        trigger_ids: List[str],
+    ) -> PriceTriggerDeleteResponse:
+        """Delete one or more price triggers by ID.
+
+        POSTs to ``/ftgw/dp/retail-price-triggers/v1/investments/research/
+        alert/price-triggers/delete``.
+
+        Args:
+            trigger_ids: List of trigger ID strings to delete.
+
+        Returns:
+            A :class:`~fidelity_trader.models.price_trigger.PriceTriggerDeleteResponse`.
+
+        Raises:
+            httpx.HTTPStatusError: on non-2xx responses.
+        """
+        request = PriceTriggerDeleteRequest(trigger_ids=trigger_ids)
+        resp = self._http.post(
+            f"{DPSERVICE_URL}{_PRICE_TRIGGERS_DELETE_PATH}",
+            json=request.to_api_payload(),
+        )
+        resp.raise_for_status()
+        return PriceTriggerDeleteResponse.from_api_response(resp.json())

fidelity_trader/alerts/subscription.py

@@ -0,0 +1,147 @@
+"""Alerts subscription API — wraps the ATBTSubscription SOAP endpoint."""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+
+import httpx
+
+from fidelity_trader._http import ALERTS_URL
+from fidelity_trader.models.alerts import AlertActivation, AlertsResponse
+
+_SUBSCRIBE_PATH = "/ftgw/alerts/services/ATBTSubscription"
+_ALERTS_PATH = "/ftgw/alerts/services/ATBTAlerts"
+
+# XML namespaces (match the captured request exactly)
+_NS_SOAP = "http://schemas.xmlsoap.org/soap/envelope/"
+_NS_PROD = "http://xmlns.fmr.com/institutional/common/headers/2011/08/ProductIdentity"
+_NS_PRIN = "http://xmlns.fmr.com/institutional/common/headers/2012/09/PrincipalIdentity"
+_NS_AUT = "http://xmlns.fmr.com/institutional/eca/fens/2014/06/AutoSubscription"
+
+
+def _build_get_alerts_envelope(msg_from: int = 1, msg_to: int = 100) -> bytes:
+    """Build the GetAlerts SOAP request body as UTF-8 bytes.
+
+    Uses a raw XML template matching the captured request format.
+    """
+    return (
+        "<soapenv:Envelope"
+        " xmlns:prin='http://xmlns.fmr.com/institutional/common/headers/2012/09/PrincipalIdentity'"
+        " xmlns:prod='http://xmlns.fmr.com/institutional/common/headers/2011/08/ProductIdentity'"
+        " xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'"
+        " xmlns:xsd='http://www.w3.org/2001/XMLSchema'"
+        " xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>"
+        "<soapenv:Header>"
+        "<prin:PrincipalIdentity>"
+        "<prin:RequestorId>Fidelity</prin:RequestorId>"
+        "<prin:AuthMethod>Basic</prin:AuthMethod>"
+        "<prin:PrincipalDomain>Retail</prin:PrincipalDomain>"
+        "<prin:RequestorType>Standard</prin:RequestorType>"
+        "<prin:PrincipalRole>Owner</prin:PrincipalRole>"
+        "</prin:PrincipalIdentity>"
+        "<prod:ProductIdentity>"
+        "<prod:AppId>AP002304</prod:AppId>"
+        "<prod:AppName>ATP</prod:AppName>"
+        "<prod:AppVersion>4.5.1</prod:AppVersion>"
+        "<prod:ProductId>ATP</prod:ProductId>"
+        "<prod:SubSystem>ActiveTrader</prod:SubSystem>"
+        "</prod:ProductIdentity>"
+        "</soapenv:Header>"
+        "<soapenv:Body>"
+        "<GetAlerts xmlns='http://xmlns.fmr.com/brokerage/fens/service/ALERTS/2009-09'>"
+        f"<MsgIndexFrom>{msg_from}</MsgIndexFrom>"
+        f"<MsgIndexTo>{msg_to}</MsgIndexTo>"
+        "</GetAlerts>"
+        "</soapenv:Body>"
+        "</soapenv:Envelope>"
+    ).encode("utf-8")
+
+
+def _build_soap_envelope() -> bytes:
+    """Build the CustomerSignOn SOAP request body as UTF-8 bytes."""
+    # Register namespace prefixes so ElementTree uses clean tags
+    ET.register_namespace("soapenv", _NS_SOAP)
+    ET.register_namespace("prod", _NS_PROD)
+    ET.register_namespace("prin", _NS_PRIN)
+    ET.register_namespace("aut", _NS_AUT)
+
+    envelope = ET.Element(f"{{{_NS_SOAP}}}Envelope")
+
+    # --- Header ---
+    header = ET.SubElement(envelope, f"{{{_NS_SOAP}}}Header")
+
+    principal = ET.SubElement(header, f"{{{_NS_PRIN}}}PrincipalIdentity")
+    ET.SubElement(principal, f"{{{_NS_PRIN}}}RequestorId").text = "fidelity"
+    ET.SubElement(principal, f"{{{_NS_PRIN}}}AuthMethod").text = "Basic"
+    ET.SubElement(principal, f"{{{_NS_PRIN}}}PrincipalDomain").text = "Retail"
+    ET.SubElement(principal, f"{{{_NS_PRIN}}}PrincipalRole").text = "Owner"
+
+    product = ET.SubElement(header, f"{{{_NS_PROD}}}ProductIdentity")
+    ET.SubElement(product, f"{{{_NS_PROD}}}AppId").text = "AP002304"
+    ET.SubElement(product, f"{{{_NS_PROD}}}AppName").text = "ATP"
+    ET.SubElement(product, f"{{{_NS_PROD}}}AppVersion").text = "0.0.1"
+    ET.SubElement(product, f"{{{_NS_PROD}}}ProductId").text = "ATP"
+    ET.SubElement(product, f"{{{_NS_PROD}}}SubSystem").text = "ActiveTrader"
+
+    # --- Body ---
+    body = ET.SubElement(envelope, f"{{{_NS_SOAP}}}Body")
+    sign_on = ET.SubElement(body, f"{{{_NS_AUT}}}CustomerSignOn")
+    ET.SubElement(sign_on, f"{{{_NS_AUT}}}AlertCode").text = "ATBT"
+
+    return ET.tostring(envelope, encoding="unicode", xml_declaration=False).encode("utf-8")
+
+
+class AlertsAPI:
+    """Client for the Fidelity alerts subscription (ATBTSubscription) SOAP service."""
+
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def subscribe(self) -> AlertActivation:
+        """Subscribe to ATP/ATBT alerts.
+
+        POSTs the ``CustomerSignOn`` SOAP envelope to the ATBTSubscription
+        endpoint.  Returns an :class:`~fidelity_trader.models.alerts.AlertActivation`
+        containing the STOMP/JMS credentials and server URL needed to connect
+        to the real-time alert stream.
+
+        Raises:
+            httpx.HTTPStatusError: on non-2xx responses.
+            ValueError: if the SOAP response cannot be parsed.
+        """
+        soap_body = _build_soap_envelope()
+        resp = self._http.post(
+            f"{ALERTS_URL}{_SUBSCRIBE_PATH}",
+            content=soap_body,
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+                "SOAPAction": "CustomerSignOn",
+            },
+        )
+        resp.raise_for_status()
+        return AlertActivation.from_xml(resp.content)
+
+    def get_alerts(self, msg_from: int = 1, msg_to: int = 100) -> AlertsResponse:
+        """Retrieve alert messages (order fills, cancellations, etc.).
+
+        POSTs the ``GetAlerts`` SOAP envelope to the ATBTAlerts endpoint.
+        Returns an :class:`~fidelity_trader.models.alerts.AlertsResponse`
+        containing the total message count and parsed alert messages.
+
+        Args:
+            msg_from: Starting message index (1-based, default 1).
+            msg_to: Ending message index (default 100).
+
+        Raises:
+            httpx.HTTPStatusError: on non-2xx responses.
+            ValueError: if the SOAP response cannot be parsed.
+        """
+        soap_body = _build_get_alerts_envelope(msg_from, msg_to)
+        resp = self._http.post(
+            f"{ALERTS_URL}{_ALERTS_PATH}",
+            content=soap_body,
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+        )
+        resp.raise_for_status()
+        return AlertsResponse.from_soap_response(resp.content)

fidelity_trader/async_client.py

@@ -0,0 +1,216 @@
+"""Async wrapper around FidelityClient using asyncio.to_thread."""
+
+import asyncio
+
+from fidelity_trader.client import FidelityClient
+
+
+class AsyncFidelityClient:
+    """Async variant of FidelityClient.
+
+    Wraps the sync client and delegates calls to a thread executor
+    via asyncio.to_thread, so they don't block the event loop.
+
+    Usage:
+        async with AsyncFidelityClient() as client:
+            await client.login(username, password)
+            positions = await client.get_positions(["Z12345678"])
+    """
+
+    def __init__(self, **kwargs) -> None:
+        self._sync = FidelityClient(**kwargs)
+
+    # ------------------------------------------------------------------
+    # Auth lifecycle
+    # ------------------------------------------------------------------
+
+    async def login(
+        self, username: str, password: str, totp_secret: str = None
+    ) -> dict:
+        return await asyncio.to_thread(
+            self._sync.login, username, password, totp_secret
+        )
+
+    async def logout(self) -> None:
+        await asyncio.to_thread(self._sync.logout)
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._sync.is_authenticated
+
+    # ------------------------------------------------------------------
+    # Auto-refresh (sync — just delegates, no I/O)
+    # ------------------------------------------------------------------
+
+    def enable_auto_refresh(self, interval: int = 300) -> None:
+        self._sync.enable_auto_refresh(interval)
+
+    def disable_auto_refresh(self) -> None:
+        self._sync.disable_auto_refresh()
+
+    # ------------------------------------------------------------------
+    # Close / context manager
+    # ------------------------------------------------------------------
+
+    async def close(self) -> None:
+        await asyncio.to_thread(self._sync.close)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    # ------------------------------------------------------------------
+    # Module accessors — expose the sync module objects directly.
+    # Users can wrap individual calls via asyncio.to_thread themselves:
+    #   result = await asyncio.to_thread(client.research.get_earnings, ...)
+    # ------------------------------------------------------------------
+
+    @property
+    def positions(self):
+        return self._sync.positions
+
+    @property
+    def balances(self):
+        return self._sync.balances
+
+    @property
+    def option_summary(self):
+        return self._sync.option_summary
+
+    @property
+    def transactions(self):
+        return self._sync.transactions
+
+    @property
+    def order_status(self):
+        return self._sync.order_status
+
+    @property
+    def equity_orders(self):
+        return self._sync.equity_orders
+
+    @property
+    def option_orders(self):
+        return self._sync.option_orders
+
+    @property
+    def cancel_order(self):
+        return self._sync.cancel_order
+
+    @property
+    def single_option_orders(self):
+        return self._sync.single_option_orders
+
+    @property
+    def cancel_replace(self):
+        return self._sync.cancel_replace
+
+    @property
+    def research(self):
+        return self._sync.research
+
+    @property
+    def search(self):
+        return self._sync.search
+
+    @property
+    def streaming(self):
+        return self._sync.streaming
+
+    @property
+    def watchlists(self):
+        return self._sync.watchlists
+
+    @property
+    def accounts(self):
+        return self._sync.accounts
+
+    @property
+    def option_chain(self):
+        return self._sync.option_chain
+
+    @property
+    def chart(self):
+        return self._sync.chart
+
+    @property
+    def option_analytics(self):
+        return self._sync.option_analytics
+
+    @property
+    def alerts(self):
+        return self._sync.alerts
+
+    @property
+    def closed_positions(self):
+        return self._sync.closed_positions
+
+    @property
+    def loaned_securities(self):
+        return self._sync.loaned_securities
+
+    @property
+    def tax_lots(self):
+        return self._sync.tax_lots
+
+    @property
+    def available_markets(self):
+        return self._sync.available_markets
+
+    @property
+    def preferences(self):
+        return self._sync.preferences
+
+    @property
+    def security_context(self):
+        return self._sync.security_context
+
+    @property
+    def session_keepalive(self):
+        return self._sync.session_keepalive
+
+    @property
+    def holiday_calendar(self):
+        return self._sync.holiday_calendar
+
+    @property
+    def staged_orders(self):
+        return self._sync.staged_orders
+
+    @property
+    def price_triggers(self):
+        return self._sync.price_triggers
+
+    @property
+    def conditional_orders(self):
+        return self._sync.conditional_orders
+
+    @property
+    def screener(self):
+        return self._sync.screener
+
+    # ------------------------------------------------------------------
+    # Async convenience methods for the most common operations.
+    # For everything else, access the module property and wrap the call:
+    #   result = await asyncio.to_thread(client.research.get_earnings, ...)
+    # ------------------------------------------------------------------
+
+    async def get_positions(self, account_numbers, **kwargs):
+        """Async shortcut for positions.get_positions()."""
+        return await asyncio.to_thread(
+            self._sync.positions.get_positions, account_numbers, **kwargs
+        )
+
+    async def get_balances(self, account_numbers, **kwargs):
+        """Async shortcut for balances.get_balances()."""
+        return await asyncio.to_thread(
+            self._sync.balances.get_balances, account_numbers, **kwargs
+        )
+
+    async def get_order_status(self, account_numbers, **kwargs):
+        """Async shortcut for order_status.get_order_status()."""
+        return await asyncio.to_thread(
+            self._sync.order_status.get_order_status, account_numbers, **kwargs
+        )

fidelity_trader/auth/__init__.py

@@ -0,0 +1,3 @@
+from fidelity_trader.auth.session import AuthSession
+
+__all__ = ["AuthSession"]