orionapi 2.24.0__tar.gz → 2.26.0__tar.gz

{orionapi-2.24.0 → orionapi-2.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionapi
-Version: 2.24.0
+Version: 2.26.0
 Summary: A python interface for the Orion Advisors platform web API
 Author: spencerogden-dsam
 Author-email: 67068943+spencerogden-dsam@users.noreply.github.com

{orionapi-2.24.0 → orionapi-2.26.0}/orionapi/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.24.0"
+__version__ = "2.26.0"
 
 import logging
 import re
@@ -55,6 +55,39 @@ TRADE_INSTANCE_SUBTYPES = {
     22: "Liquidate",
 }
 
+# TradingApplication mappings for the v2 /TradeOrder/Trades endpoints.
+# Not published in the Swagger (which lists the ints with no names) -- recovered
+# 2026-07-28 from the API's own rejection messages ("Trade Application <Name> is
+# not supported."). Only MANUAL_TRADE (11) actually creates trade orders; see
+# EclipseV2.create_trades.
+TRADING_APPLICATIONS = {
+    0: "BuySell",
+    1: "CashNeeds",
+    2: "GlobalTrades",
+    3: "ProrateCash",
+    4: "RaiseCash",
+    5: "Rebalance",
+    6: "SpendCash",
+    7: "(unnamed)",
+    8: "TaxLossHarvesting",
+    9: "TickerSwap",
+    10: "TradeToTargetPercent",
+    11: "ManualTrade",
+    12: "TacticalTrades",
+    13: "PartialShare",
+    14: "(unnamed, accepted but creates nothing)",
+    15: "TradeImport",
+    16: "RaiseCashByFund",
+    17: "OptionTrades",
+    18: "OutsourcedTradeExecution",
+}
+
+# The only TradingApplication value that creates trade orders on
+# POST /api/v2/TradeOrder/Trades. Every other value except 14 returns
+# 400 "Trade Application <Name> is not supported."; 14 returns 200 with an
+# empty ``tradeId`` list and creates nothing. Live-verified 2026-07-28.
+TRADING_APPLICATION_MANUAL = 11
+
 # Set-Aside Cash Constants (from Eclipse API)
 CASH_TYPE_DOLLAR = 1
 CASH_TYPE_PERCENT = 2
@@ -2855,6 +2888,14 @@ class EclipseV1(EclipseBase):
         Writes nothing. Use this as the pre-flight check for :meth:`create_trade`,
         which has no preview / view-only mode of its own.
 
+        .. deprecated:: 2.26.0
+            Use :meth:`EclipseV2.validate_trades` instead; this emits a
+            ``DeprecationWarning``. ``action_id=2`` returns HTTP 500 while a
+            byte-identical buy succeeds — the same upstream defect that affects
+            :meth:`create_trade`. Pairing this with the deprecated
+            :meth:`create_trade` also means validating and creating on the same
+            unreliable surface.
+
         Args:
             action_id: 1=Buy, 2=Sell, 3=Journal In, 4=Journal Out
             account_id: Optional account ID
@@ -2869,6 +2910,12 @@ class EclipseV1(EclipseBase):
             dict: ``message``, ``tradeAmount``, ``cashValuePostTrade`` and a
             ``warningMessage`` list (e.g. warnings about overspending cash)
         """
+        warnings.warn(
+            "EclipseV1.validate_trade is deprecated: the endpoint 500s on every sell. "
+            "Use EclipseV2.validate_trades (Eclipse().validate_trades).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         payload = {
             "actionId": action_id,
             "accountId": account_id,
@@ -2902,6 +2949,26 @@ class EclipseV1(EclipseBase):
     ):
         """Generate trade orders (``POST /tradeorder/trades``).
 
+        .. deprecated:: 2.26.0
+            Use :meth:`EclipseV2.create_trades` instead; this emits a
+            ``DeprecationWarning``. The endpoint is unreliable in two independent
+            ways -- only ``dollar_amount`` buys actually work. All live-verified
+            2026-07-28 and reported to Orion:
+
+            ===================  ===============================================
+            Input                Result
+            ===================  ===============================================
+            ``action_id=2``      HTTP 500 for **every** sell, across 5 securities,
+                                 all amount modes and every documented body shape
+            ``quantity=N``       HTTP 200 ``"No Trade is generated."`` -- creates
+                                 nothing; this wrapper now rejects it up front
+            ``percentage=N``     May create a zero-quantity, *disabled* order
+            ``dollar_amount=N``  Works
+            ===================  ===============================================
+
+            :meth:`EclipseV2.create_trades` handles buys *and* sells and honours
+            share count and dollar amount exactly.
+
         The generic per-trade creator behind Eclipse's Quick Trade / journal flows,
         as opposed to the ``/tradetool/`` generators (:meth:`cash_needs_trade`,
         :meth:`rebalance_trade`, ...) which operate on whole portfolios.
@@ -2943,9 +3010,25 @@ class EclipseV1(EclipseBase):
         Raises:
             ValueError: If the enum values are unknown, option trading is
                 requested (unsupported by Eclipse), neither an account nor a
-                portfolio is given, or a buy/sell does not specify exactly one of
+                portfolio is given, ``quantity`` is used (silently discarded
+                upstream), or a buy/sell does not specify exactly one of
                 ``dollar_amount`` / ``quantity`` / ``percentage``.
+            OrionAPIError: If Eclipse reports ``"No Trade is generated."`` -- a
+                200 response that created nothing.
         """
+        warnings.warn(
+            "EclipseV1.create_trade is deprecated: the endpoint 500s on every sell and "
+            "silently discards share-quantity buys. Use EclipseV2.create_trades "
+            "(Eclipse().create_trades), which handles both and honours shares/amount.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        if quantity is not None:
+            raise ValueError(
+                "quantity is silently ignored by this endpoint -- it returns 200 with "
+                '"No Trade is generated." and creates nothing. Use dollar_amount here, '
+                "or EclipseV2.create_trades(build_trade(..., shares=N)) for share counts."
+            )
         if action_id not in (1, 2, 3, 4):
             raise ValueError(
                 "action_id must be 1 (Buy), 2 (Sell), 3 (Journal In) or 4 (Journal Out)"
@@ -2998,6 +3081,13 @@ class EclipseV1(EclipseBase):
 
         res = self.api_request(f"{self.base_url}/tradeorder/trades", requests.post, json=payload)
         result = res.json()
+        # A 200 carrying this message means nothing was created. Do not let a
+        # silent no-op look like a successful write.
+        if isinstance(result, dict) and result.get("message") == "No Trade is generated.":
+            raise OrionAPIError(
+                "Eclipse returned 'No Trade is generated.' — the request succeeded but "
+                "created no trade orders. Use EclipseV2.create_trades instead."
+            )
         self._maybe_wait_for_analytics(sync)
         return result
 
@@ -7046,6 +7136,287 @@ class EclipseV2(EclipseBase):
         res = self.api_request(f"{self.base_url_v2}/Trading/ActiveBatchJobs", params=params)
         return res.json()
 
+    # --- TradeOrder / Trades (v2): batch create + validate -----------------------
+    # The v2 counterparts of EclipseV1.create_trade / validate_trade. Named in the
+    # plural because v2 takes a *list* of trades in one wrapper -- which also keeps
+    # them distinct from the v1 singular methods on the Eclipse unifier, whose
+    # __getattr__ resolves v1 first.
+    #
+    # Prefer these over the v1 pair for SELLS: the v1 endpoints return HTTP 500 for
+    # every sell (see EclipseV1.create_trade's docstring). Live-verified 2026-07-28:
+    # v2 validates sells correctly, returning isValid/tradeAmount/tradeShares.
+
+    @staticmethod
+    def build_trade(
+        account_id,
+        portfolio_id,
+        security_id,
+        action,
+        shares=None,
+        amount=None,
+        percent=None,
+        **extra,
+    ):
+        """Build one entry for the ``trades`` list of :meth:`validate_trades` /
+        :meth:`create_trades`.
+
+        Saves the caller from having to know the v2 ``ValidateTradeDto`` key names.
+
+        Exactly one of ``shares`` / ``amount`` / ``percent`` sets the trade size:
+
+        =========  ===================  =================================================
+        Parameter  Sent as              Meaning
+        =========  ===================  =================================================
+        ``shares`` ``tradeShares``      **Share count.** A whole or fractional number of
+                                        shares. Honoured exactly -- live-verified
+                                        ``shares=1`` produced an order of qty 1.0.
+        ``amount`` ``tradeAmount``      **Dollar amount.** Eclipse divides by the current
+                                        price and books the resulting (fractional) share
+                                        count -- ``amount=500`` on a $393 stock produced
+                                        qty 1.2711.
+        ``percent`` ``tradePercent``    Percent of the *existing position*. Only
+                                        meaningful for sells/trims, and a percent that
+                                        rounds to <1 share can yield a zero-quantity,
+                                        disabled order. Prefer ``shares`` or ``amount``.
+        =========  ===================  =================================================
+
+        Args:
+            account_id: Account ID (``accountId``)
+            portfolio_id: Portfolio ID (``portfolioId``). **Required** -- see the
+                warning on :meth:`validate_trades`; omitting it makes the API
+                silently return an empty list.
+            security_id: Security ID (``securityId``)
+            action: 1=Buy, 2=Sell, 3=Journal In, 4=Journal Out (``action``)
+            shares: Number of shares to buy/sell (``tradeShares``) -- preferred
+            amount: Dollar amount to buy/sell (``tradeAmount``) -- preferred
+            percent: Percent of the position (``tradePercent``); see caveat above
+            **extra: Any other ``ValidateTradeDto`` field, passed through verbatim
+
+        Returns:
+            dict: A single trade entry
+
+        Raises:
+            ValueError: If ``portfolio_id`` is missing, ``action`` is out of range,
+                or not exactly one of ``shares`` / ``amount`` / ``percent`` is set.
+
+        Example:
+            >>> e.build_trade(account_id=686, portfolio_id=209, security_id=73,
+            ...               action=1, shares=1)
+            {'accountId': 686, 'portfolioId': 209, 'securityId': 73,
+             'action': 1, 'tradeShares': 1}
+        """
+        if portfolio_id is None:
+            raise ValueError(
+                "portfolio_id is required; without portfolioId the v2 trade endpoints "
+                "return an empty list instead of validating"
+            )
+        if action not in (1, 2, 3, 4):
+            raise ValueError("action must be 1 (Buy), 2 (Sell), 3 (Journal In) or 4 (Journal Out)")
+        sizes = [s for s in (shares, amount, percent) if s]
+        if len(sizes) != 1:
+            raise ValueError("exactly one of shares, amount or percent must be set")
+
+        trade = {
+            "accountId": account_id,
+            "portfolioId": portfolio_id,
+            "securityId": security_id,
+            "action": action,
+        }
+        if shares is not None:
+            trade["tradeShares"] = shares
+        if amount is not None:
+            trade["tradeAmount"] = amount
+        if percent is not None:
+            trade["tradePercent"] = percent
+        trade.update(extra)
+        return trade
+
+    def _trade_wrapper(
+        self,
+        trades,
+        application,
+        trade_tool_selection,
+        trade_instance_type,
+        trade_instance_sub_type,
+        instance_notes,
+    ):
+        """Build and sanity-check the ``ValidateTradeWrapperDto`` body."""
+        if not trades:
+            raise ValueError("trades must be a non-empty list of trade dicts")
+        for i, t in enumerate(trades):
+            if t.get("portfolioId") is None:
+                raise ValueError(
+                    f"trades[{i}] is missing portfolioId; without it the v2 trade "
+                    "endpoints silently return an empty list instead of validating. "
+                    "Use build_trade() to construct entries."
+                )
+        body = {
+            "application": application,
+            "trades": trades,
+            "tradeToolSelection": trade_tool_selection,
+            "tradeInstanceType": trade_instance_type,
+            "tradeInstanceSubType": trade_instance_sub_type,
+        }
+        if instance_notes is not None:
+            body["instanceNotes"] = instance_notes
+        return body
+
+    def validate_trades(
+        self,
+        trades,
+        application=TRADING_APPLICATION_MANUAL,
+        trade_tool_selection=2,
+        trade_instance_type=5,
+        trade_instance_sub_type=11,
+        instance_notes=None,
+    ):
+        """Validate a batch of trades (``POST /TradeOrder/Trades/Action/Validate``).
+
+        Writes nothing. The v2 counterpart of :meth:`EclipseV1.validate_trade`, and
+        the one to use for **sells** -- the v1 endpoint 500s on every sell.
+
+        .. warning::
+            Every entry in ``trades`` must carry ``portfolioId``. Without it the API
+            returns ``200 []`` -- an empty list, not an error -- so an unvalidated
+            batch looks indistinguishable from a clean one. This method raises
+            ``ValueError`` rather than let that pass silently.
+
+        Note:
+            The response is not 1:1 with the input. Eclipse expands each requested
+            trade across the underlying tax lots / sleeve accounts, so one entry can
+            come back as several rows (live-verified: a 99,999-share sell returned 4).
+
+        Args:
+            trades: List of trade dicts; build them with :meth:`build_trade`.
+                Size each with ``shares`` (share count) or ``amount`` (dollars) --
+                see :meth:`build_trade` for the full parameter table.
+            application: ``TradingApplication`` -- see :data:`TRADING_APPLICATIONS`.
+                Defaults to 11 (ManualTrade), the only value that creates orders on
+                :meth:`create_trades`. This endpoint tolerates other values, but
+                keeping the two in step avoids validating under one application and
+                creating under another.
+            trade_tool_selection: 1=Portfolio, 2=Account, 3=Model, ... (default 2)
+            trade_instance_type: See :data:`TRADE_INSTANCE_TYPES` (default 5, Quick Trade)
+            trade_instance_sub_type: See :data:`TRADE_INSTANCE_SUBTYPES`
+                (default 11, Quick Trade)
+            instance_notes: Optional notes for the trade instance
+
+        Returns:
+            list: Validated trade dicts with ``isValid``, ``tradeAmount``,
+            ``tradeShares``, ``tradePercent``, ``warningMessage``,
+            ``zeroTradeReasons`` and gain/loss detail
+
+        Raises:
+            ValueError: If ``trades`` is empty or any entry lacks ``portfolioId``
+        """
+        body = self._trade_wrapper(
+            trades,
+            application,
+            trade_tool_selection,
+            trade_instance_type,
+            trade_instance_sub_type,
+            instance_notes,
+        )
+        res = self.api_request(
+            f"{self.base_url_v2}/TradeOrder/Trades/Action/Validate", requests.post, json=body
+        )
+        return res.json()
+
+    def create_trades(
+        self,
+        trades,
+        application=TRADING_APPLICATION_MANUAL,
+        trade_tool_selection=2,
+        trade_instance_type=5,
+        trade_instance_sub_type=11,
+        instance_notes=None,
+    ):
+        """Create a batch of trade orders (``POST /TradeOrder/Trades``).
+
+        **The recommended way to create trades.** Prefer this over
+        :meth:`EclipseV1.create_trade`, which is deprecated: v1 500s on every sell
+        and silently discards share-count buys.
+
+        Size each trade with **``shares`` (share count)** or **``amount``
+        (dollars)** via :meth:`build_trade` -- both are honoured exactly here.
+        Live-verified 2026-07-28: ``shares=1`` created an order of qty 1.0, and
+        ``amount=500`` on a $393 stock created qty 1.2711.
+
+        .. warning::
+            This writes. Call :meth:`validate_trades` first and check ``isValid`` /
+            ``warningMessage`` on every returned row; the same ``portfolioId``
+            requirement applies here.
+
+            Unlike the v1 endpoint there is no ``isSendImmediately`` field on this
+            surface at all, so created orders are always staged as pending. Setting
+            ``approvalStatus`` or ``orderStatus`` on a trade entry is rejected: that
+            would amount to creating and approving in one call, which this wrapper
+            deliberately does not allow. Review and execute in Eclipse.
+
+        Note:
+            No ``sync`` parameter: the analytics-wait helpers live on
+            :class:`EclipseV1`. Call ``Eclipse().v1.wait_for_analytics()`` if you
+            need to block until analytics settle.
+
+        Args:
+            trades: List of trade dicts; build them with :meth:`build_trade`.
+                Size each with ``shares`` (share count) or ``amount`` (dollars);
+                see :meth:`build_trade` for the full parameter table.
+            application: ``TradingApplication`` -- see :data:`TRADING_APPLICATIONS`.
+                **Only 11 (ManualTrade) creates orders**, and it is the default.
+                Every other value except 14 returns 400 "Trade Application <Name>
+                is not supported."; 14 returns 200 with an empty ``tradeId`` list
+                and creates nothing, so it is rejected here rather than allowed to
+                look like a success.
+            trade_tool_selection: 1=Portfolio, 2=Account, 3=Model, ... (default 2)
+            trade_instance_type: See :data:`TRADE_INSTANCE_TYPES` (default 5, Quick Trade)
+            trade_instance_sub_type: See :data:`TRADE_INSTANCE_SUBTYPES`
+                (default 11, Quick Trade)
+            instance_notes: Optional notes for the trade instance
+
+        Returns:
+            dict: ``instanceId``, ``tradeId`` (the created trade order IDs),
+            ``trades`` and ``excludeTrades``
+
+        Raises:
+            ValueError: If ``trades`` is empty, any entry lacks ``portfolioId``, any
+                entry sets ``approvalStatus`` / ``orderStatus``, or ``application``
+                is one that cannot create orders.
+
+        Example:
+            >>> t = e.build_trade(account_id=686, portfolio_id=209, security_id=73,
+            ...                   action=2, shares=1)          # SELL 1 share
+            >>> [r["isValid"] for r in e.validate_trades([t])]
+            [True]
+            >>> e.create_trades([t])["tradeId"]
+            [72495]
+        """
+        if application != TRADING_APPLICATION_MANUAL:
+            name = TRADING_APPLICATIONS.get(application, "unknown")
+            raise ValueError(
+                f"application={application} ({name}) does not create trade orders on "
+                f"this endpoint; only {TRADING_APPLICATION_MANUAL} (ManualTrade) does. "
+                "Other values return 400, and 14 returns 200 while creating nothing."
+            )
+        for i, t in enumerate(trades or []):
+            for banned in ("approvalStatus", "orderStatus"):
+                if t.get(banned) is not None:
+                    raise ValueError(
+                        f"trades[{i}] sets {banned}; creating and approving/executing a "
+                        "trade in one call is not supported by this wrapper. Create the "
+                        "orders here, then action them in Eclipse."
+                    )
+        body = self._trade_wrapper(
+            trades,
+            application,
+            trade_tool_selection,
+            trade_instance_type,
+            trade_instance_sub_type,
+            instance_notes,
+        )
+        res = self.api_request(f"{self.base_url_v2}/TradeOrder/Trades", requests.post, json=body)
+        return res.json()
+
     # --- Optimization (v2-only): per-batch / per-account detail reads ------------
 
     def get_optimization_accounts(self, batch_id):

{orionapi-2.24.0 → orionapi-2.26.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "orionapi"
-version = "2.24.0"
+version = "2.26.0"
 description = "A python interface for the Orion Advisors platform web API"
 authors = ["spencerogden-dsam <67068943+spencerogden-dsam@users.noreply.github.com>"]