orionapi 2.23.0__tar.gz → 2.26.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionapi
-Version: 2.23.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.23.0 → orionapi-2.26.0}/orionapi/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.23.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
@@ -2748,33 +2781,68 @@ class EclipseV1(EclipseBase):
             self.wait_for_analytics()
 
     def get_orders(self):
-        """Get all completed (non-pending) trade orders.
+        """Deprecated alias of ``get_trades(is_pending=False)``.
+
+        Both hit the same ``/tradeorder/trades`` endpoint; :meth:`get_trades` is the
+        superset and also exposes the portfolio, block, filter and account filters.
+        Emits a ``DeprecationWarning`` and will be removed in a future major release.
 
         Returns:
             list: List of completed trade order dicts
         """
-        return self.api_request(f"{self.base_url}/tradeorder/trades?isPending=false").json()
+        warnings.warn(
+            "get_orders is deprecated; use get_trades(is_pending=False).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.get_trades(is_pending=False)
 
     def get_orders_pending(self):
-        """Get all pending trade orders.
+        """Deprecated alias of ``get_trades(is_pending=True)``.
+
+        Both hit the same ``/tradeorder/trades`` endpoint; :meth:`get_trades` is the
+        superset and also exposes the portfolio, block, filter and account filters.
+        Emits a ``DeprecationWarning`` and will be removed in a future major release.
 
         Returns:
             list: List of pending trade order dicts
         """
-        return self.api_request(f"{self.base_url}/tradeorder/trades?isPending=true").json()
+        warnings.warn(
+            "get_orders_pending is deprecated; use get_trades(is_pending=True).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.get_trades(is_pending=True)
 
-    def get_trades(self, portfolio_id=None, top=None, is_pending=None):
-        """Get trade orders with optional portfolio / paging / pending filters.
+    def get_trades(
+        self,
+        portfolio_id=None,
+        top=None,
+        is_pending=None,
+        block_id=None,
+        filter_id=None,
+        account_ids=None,
+    ):
+        """Get trade orders with optional portfolio / block / filter / pending filters.
 
-        Hits the same ``/tradeorder/trades`` endpoint as :meth:`get_orders` /
-        :meth:`get_orders_pending`, but lets the caller filter by portfolio and cap
-        the result count.
+        The canonical accessor for ``GET /tradeorder/trades``. Supersedes the
+        deprecated :meth:`get_orders` / :meth:`get_orders_pending`, which only
+        varied ``is_pending``.
 
         Args:
             portfolio_id: Optional portfolio ID filter (maps to ``portfolioId``)
-            top: Optional max number of results (maps to ``$top``)
+            top: Deprecated and ignored. ``$top`` is not a documented param on this
+                endpoint, and Eclipse silently drops unknown query params rather
+                than erroring — live-verified 2026-07-28: with 10 trades in the
+                tenant, ``$top=3`` still returned all 10. Slice the result instead.
             is_pending: Optional bool; when set, filter by pending status
                 (maps to ``isPending``)
+            block_id: Optional trade block ID filter (maps to ``blockId``)
+            filter_id: Optional trade filter type ID (maps to ``filterId``); see
+                the ``/tradeorder/trades/filterTypes`` endpoint for valid values
+            account_ids: Optional account ID filter (maps to ``accountIds``);
+                accepts a list/tuple of IDs, which is joined to a comma-separated
+                string, or a pre-formatted string
 
         Returns:
             list: Trade order dicts
@@ -2783,12 +2851,246 @@ class EclipseV1(EclipseBase):
         if portfolio_id is not None:
             params["portfolioId"] = portfolio_id
         if top is not None:
-            params["$top"] = top
+            warnings.warn(
+                "get_trades(top=...) is ignored by Eclipse: $top is not a supported "
+                "param on /tradeorder/trades and the server silently drops it. "
+                "Slice the returned list instead. This parameter will be removed in "
+                "a future major release.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         if is_pending is not None:
             params["isPending"] = str(is_pending).lower()
+        if block_id is not None:
+            params["blockId"] = block_id
+        if filter_id is not None:
+            params["filterId"] = filter_id
+        if account_ids is not None:
+            if isinstance(account_ids, (list, tuple)):
+                account_ids = ",".join(str(a) for a in account_ids)
+            params["accountIds"] = account_ids
         res = self.api_request(f"{self.base_url}/tradeorder/trades", params=params)
         return res.json()
 
+    def validate_trade(
+        self,
+        action_id,
+        account_id=None,
+        portfolio_id=None,
+        security_id=None,
+        dollar_amount=None,
+        quantity=None,
+        percentage=None,
+        is_auto_allocate=None,
+    ):
+        """Validate a trade before creating it (``POST /tradeorder/trades/validate``).
+
+        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
+            portfolio_id: Optional portfolio ID
+            security_id: Optional security ID
+            dollar_amount: Optional dollar amount to buy/sell
+            quantity: Optional number of shares to buy/sell
+            percentage: Optional percent of the position to buy/sell
+            is_auto_allocate: Optional bool (maps to ``isAutoAllocate``)
+
+        Returns:
+            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,
+            "portfolioId": portfolio_id,
+            "securityId": security_id,
+            "dollarAmount": dollar_amount,
+            "quantity": quantity,
+            "percentage": percentage,
+            "isAutoAllocate": is_auto_allocate,
+        }
+        payload = {k: v for k, v in payload.items() if v is not None}
+
+        res = self.api_request(
+            f"{self.base_url}/tradeorder/trades/validate", requests.post, json=payload
+        )
+        return res.json()
+
+    def create_trade(
+        self,
+        action_id,
+        trade_tool_selection,
+        trade_instance_type,
+        trade_instance_sub_type,
+        account_id=None,
+        portfolio_id=None,
+        security_id=None,
+        dollar_amount=None,
+        quantity=None,
+        percentage=None,
+        sync=True,
+    ):
+        """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.
+
+        .. warning::
+            This endpoint has **no view-only mode** — it always writes. Call
+            :meth:`validate_trade` first to preview the trade amount, the resulting
+            cash balance and any warnings.
+
+            Trades are always created as pending orders: the wrapper hardcodes
+            ``isSendImmediately: false`` and deliberately does not expose it, so a
+            single call can never both create and execute a trade. Review and
+            execute the resulting orders in Eclipse.
+
+        Args:
+            action_id: 1=Buy, 2=Sell, 3=Journal In, 4=Journal Out. (The Eclipse
+                docs list both journal directions as ``3``; ``4`` is accepted on
+                the assumption that Journal Out is ``4``.)
+            trade_tool_selection: 1=Portfolio, 2=Account, 3=Model,
+                4=Account Trade Group, 5=Sleeve Portfolio, 6=Excel Import,
+                7=Portfolio Trade Group, 8=Security Import, 9=Individual Sleeve,
+                10=Tactical Tool
+            trade_instance_type: Trade instance type ID; see
+                :data:`TRADE_INSTANCE_TYPES`
+            trade_instance_sub_type: Trade instance sub-type ID; see
+                :data:`TRADE_INSTANCE_SUBTYPES`
+            account_id: Account ID (required unless ``portfolio_id`` is given)
+            portfolio_id: Portfolio ID (required unless ``account_id`` is given)
+            security_id: Security ID; required for buys and sells
+            dollar_amount: Dollar amount to buy/sell
+            quantity: Number of shares to buy/sell
+            percentage: Percent of the position to buy/sell
+            sync: Wait for analytics to complete (default True)
+
+        Returns:
+            dict: Either ``{"message": ...}`` or ``{"issues": [...],
+            "success": [...], "instanceId": ...}``
+
+        Raises:
+            ValueError: If the enum values are unknown, option trading is
+                requested (unsupported by Eclipse), neither an account nor a
+                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)"
+            )
+        if trade_tool_selection not in range(1, 11):
+            raise ValueError("trade_tool_selection must be an integer between 1 and 10")
+        if trade_instance_type not in TRADE_INSTANCE_TYPES:
+            raise ValueError(
+                f"trade_instance_type must be one of {sorted(TRADE_INSTANCE_TYPES)}, "
+                f"got {trade_instance_type!r}"
+            )
+        if trade_instance_sub_type not in TRADE_INSTANCE_SUBTYPES:
+            raise ValueError(
+                f"trade_instance_sub_type must be one of {sorted(TRADE_INSTANCE_SUBTYPES)}, "
+                f"got {trade_instance_sub_type!r}"
+            )
+        # Eclipse documents option trading as "not supported" on this endpoint.
+        if trade_instance_type == 4 or trade_instance_sub_type == 9:
+            raise ValueError("Option Trading is not supported by the /tradeorder/trades endpoint")
+        if account_id is None and portfolio_id is None:
+            raise ValueError("at least one of account_id or portfolio_id is required")
+
+        is_buy_or_sell = action_id in (1, 2)
+        if is_buy_or_sell:
+            if security_id is None:
+                raise ValueError("security_id is required for buys and sells")
+            amounts = [a for a in (dollar_amount, quantity, percentage) if a]
+            if len(amounts) != 1:
+                raise ValueError(
+                    "exactly one of dollar_amount, quantity or percentage must be set "
+                    "for buys and sells"
+                )
+
+        # Buys/sells send 0 for the unused amount fields; journals send null.
+        unset = 0 if is_buy_or_sell else None
+        payload = {
+            "accountId": account_id,
+            "portfolioId": portfolio_id,
+            "actionId": action_id,
+            "securityId": security_id,
+            "dollarAmount": dollar_amount if dollar_amount is not None else unset,
+            "quantity": quantity if quantity is not None else unset,
+            "percentage": percentage if percentage is not None else unset,
+            # Never expose this: creating and executing a trade must stay separate.
+            "isSendImmediately": False,
+            "tradeToolSelection": trade_tool_selection,
+            "tradeInstanceType": trade_instance_type,
+            "tradeInstanceSubType": trade_instance_sub_type,
+        }
+
+        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
+
     def cash_needs_trade(
         self,
         portfolio_ids,
@@ -6834,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.23.0 → orionapi-2.26.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "orionapi"
-version = "2.23.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>"]