@huskly/ibkr-client 0.12.0 → 0.14.0

package/dist/ibkr/ibkrClient.js

@@ -268,6 +268,170 @@ export class IbkrClient {
         });
         return this.normalizeOrderSubmission(response, request.clientOrderId);
     }
+    async submitDerivativeSingleOrder(request) {
+        this.validateSingleOrder(request);
+        const cmeOperatorMetadata = this.cmeOperatorMetadata(request.contract.assetClass, request);
+        const diagnostics = await this.getTradingDiagnostics(request.accountId);
+        if (!diagnostics.authenticated || diagnostics.competingSession) {
+            throw new Error("IBKR brokerage session is not safely authenticated for submission");
+        }
+        await this.prepareBrokerageAccount(request.accountId);
+        const response = await this.singleAttemptRequest({
+            path: `iserver/account/${request.accountId}/orders`,
+            method: "POST",
+            data: {
+                orders: [
+                    {
+                        ...this.singleOrderTicket(request),
+                        ...(request.clientOrderId !== undefined ? { cOID: request.clientOrderId } : {}),
+                        ...(request.parentId !== undefined ? { parentId: request.parentId } : {}),
+                        ...cmeOperatorMetadata,
+                    },
+                ],
+            },
+        });
+        return this.normalizeOrderSubmission(response, request.clientOrderId ?? null);
+    }
+    async submitDerivativeContingentOrders(request) {
+        const { accountId, parent, child } = request;
+        if (!accountId.trim())
+            throw new Error("An explicit IBKR account ID is required");
+        if (parent.accountId !== accountId || child.accountId !== accountId) {
+            throw new Error("Contingent parent and child orders must target the exact same account");
+        }
+        this.validateSingleOrderFields(parent);
+        this.validateSingleOrderFields(child);
+        if (typeof parent.clientOrderId !== "string" ||
+            !parent.clientOrderId.trim() ||
+            parent.clientOrderId.length > 64) {
+            throw new Error("Parent client order ID must contain 1 to 64 characters");
+        }
+        if ("clientOrderId" in child || "parentId" in child) {
+            throw new Error("Contingent child identity is derived from the parent order");
+        }
+        const parentMetadata = this.cmeOperatorMetadata(parent.contract.assetClass, parent);
+        const childMetadata = this.cmeOperatorMetadata(child.contract.assetClass, child);
+        const diagnostics = await this.getTradingDiagnostics(accountId);
+        if (!diagnostics.authenticated || diagnostics.competingSession) {
+            throw new Error("IBKR brokerage session is not safely authenticated for submission");
+        }
+        await this.prepareBrokerageAccount(accountId);
+        const response = await this.singleAttemptRequest({
+            path: `iserver/account/${accountId}/orders`,
+            method: "POST",
+            data: {
+                orders: [
+                    {
+                        ...this.singleOrderTicket(parent),
+                        cOID: parent.clientOrderId,
+                        ...parentMetadata,
+                    },
+                    {
+                        ...this.singleOrderTicket(child),
+                        parentId: parent.clientOrderId,
+                        ...childMetadata,
+                    },
+                ],
+            },
+        });
+        return this.normalizeMultiOrderSubmission(response, parent.clientOrderId);
+    }
+    async submitDerivativeOrderGraph(request) {
+        this.validateOrderGraph(request);
+        const diagnostics = await this.getTradingDiagnostics(request.accountId);
+        if (!diagnostics.authenticated || diagnostics.competingSession) {
+            throw new Error("IBKR brokerage session is not safely authenticated for submission");
+        }
+        await this.prepareBrokerageAccount(request.accountId);
+        const response = await this.singleAttemptRequest({
+            path: `iserver/account/${request.accountId}/orders`,
+            method: "POST",
+            data: { orders: request.nodes.map((node) => this.graphOrderTicket(request, node)) },
+        });
+        return this.normalizeOrderGraphSubmission(response, request, []);
+    }
+    async acknowledgeDerivativeOrderGraphWarning(input) {
+        if (input.confirmed !== true)
+            throw new Error("Order warning confirmation must be true");
+        this.validateOrderGraph(input.continuation.request);
+        if (!input.continuation.replyId.trim())
+            throw new Error("An exact warning reply ID is required");
+        const diagnostics = await this.getTradingDiagnostics(input.continuation.request.accountId);
+        if (!diagnostics.authenticated || diagnostics.competingSession) {
+            throw new Error("IBKR brokerage session is not safely authenticated for submission");
+        }
+        await this.prepareBrokerageAccount(input.continuation.request.accountId);
+        const response = await this.singleAttemptRequest({
+            path: `iserver/reply/${encodeURIComponent(input.continuation.replyId)}`,
+            method: "POST",
+            data: { confirmed: true },
+        });
+        return this.normalizeOrderGraphSubmission(response, input.continuation.request, input.continuation.members);
+    }
+    async recoverDerivativeOrderGraph(input, request) {
+        this.validateOrderGraph(request);
+        if (input.accountId !== request.accountId)
+            throw new Error("Graph recovery account does not match request");
+        await this.prepareBrokerageAccount(input.accountId);
+        const response = await this.req({
+            path: "iserver/account/orders",
+            params: { force: true, accountId: input.accountId },
+        });
+        const accountOrders = (response.orders ?? []).filter((order) => this.orderBelongsToAccount(order, input.accountId));
+        const byMemberId = new Map();
+        for (const node of request.nodes) {
+            const matches = accountOrders.filter((order) => this.liveOrderMatchesGraphNode(request, node, order));
+            const [match] = matches;
+            if (matches.length === 1 && match !== undefined)
+                byMemberId.set(node.memberId, match);
+        }
+        const candidates = [...byMemberId.values()];
+        const linkedOrders = accountOrders.filter((order) => (order.cOID ?? order.order_ref) === request.rootClientOrderId ||
+            String(order.parentId ?? "") === request.rootClientOrderId);
+        const candidateSet = new Set(candidates);
+        if (input.orderId !== undefined &&
+            !candidates.some((order) => String(order.order_id ?? order.orderId) === input.orderId)) {
+            throw new Error(`Broker order ${input.orderId} is not a member of the requested graph`);
+        }
+        if (input.rootClientOrderId !== undefined &&
+            input.rootClientOrderId !== request.rootClientOrderId) {
+            throw new Error("Root client order ID does not match the requested graph");
+        }
+        const members = request.nodes.map((node) => {
+            const order = byMemberId.get(node.memberId);
+            return this.graphMemberEvidence(request, node, order);
+        });
+        const ids = members.flatMap(({ orderId }) => (orderId === null ? [] : [orderId]));
+        const brokerParentsMatch = request.nodes.every((node) => {
+            if (node.parentMemberId === undefined)
+                return true;
+            return (byMemberId.get(node.memberId) !== undefined &&
+                String(byMemberId.get(node.memberId)?.parentId ?? "") === request.rootClientOrderId);
+        });
+        if (candidates.length !== request.nodes.length ||
+            linkedOrders.length !== request.nodes.length ||
+            linkedOrders.some((order) => !candidateSet.has(order)) ||
+            new Set(ids).size !== request.nodes.length ||
+            !brokerParentsMatch) {
+            return {
+                state: "recovery_required",
+                rootClientOrderId: request.rootClientOrderId,
+                members,
+                reasons: [
+                    "Exact graph recovery found incomplete, duplicated, or ambiguous member evidence",
+                ],
+                warnings: [],
+                errors: [],
+                unrecognizedResponses: [],
+            };
+        }
+        return {
+            state: "accepted",
+            rootClientOrderId: request.rootClientOrderId,
+            members: this.attachGraphParentOrderIds(members),
+            warnings: [],
+        };
+    }
     async acknowledgeOrderWarning(input) {
         if (!input.replyId.trim())
             throw new Error("An exact warning reply ID is required");
@@ -278,6 +442,24 @@ export class IbkrClient {
         });
         return this.normalizeOrderSubmission(response, null);
     }
+    async acknowledgeContingentOrderWarning(input) {
+        const confirmed = input.confirmed;
+        if (confirmed !== true) {
+            throw new Error("Order warning confirmation must be true");
+        }
+        if (!input.continuation.replyId.trim()) {
+            throw new Error("An exact warning reply ID is required");
+        }
+        if (!input.continuation.parentClientOrderId.trim()) {
+            throw new Error("An exact parent client order ID is required");
+        }
+        const response = await this.singleAttemptRequest({
+            path: `iserver/reply/${encodeURIComponent(input.continuation.replyId)}`,
+            method: "POST",
+            data: { confirmed: true },
+        });
+        return this.normalizeMultiOrderSubmission(response, input.continuation.parentClientOrderId);
+    }
     async getDerivativeOrderStatus(accountId, orderId) {
         if (!accountId.trim() || !orderId.trim()) {
             throw new Error("Exact account and order IDs are required");
@@ -325,6 +507,59 @@ export class IbkrClient {
         }
         return this.getDerivativeOrderStatus(input.accountId, String(orderId));
     }
+    async listActiveDerivativeOrders(accountId) {
+        if (!accountId.trim())
+            throw new Error("An exact account ID is required");
+        await this.prepareBrokerageAccount(accountId);
+        const response = await this.req({
+            path: "iserver/account/orders",
+            params: { force: true, accountId },
+        });
+        if (response.snapshot !== true || !Array.isArray(response.orders)) {
+            throw new Error("IBKR active-order snapshot is incomplete");
+        }
+        const flattened = this.flattenActiveOrders(response.orders);
+        const invalidAccountEvidence = flattened.find(({ order }) => {
+            const returnedAccounts = [order.account, order.acct];
+            const providedAccounts = returnedAccounts.filter((value) => value !== undefined);
+            return (providedAccounts.length === 0 ||
+                providedAccounts.some((returnedAccount) => typeof returnedAccount !== "string" || returnedAccount !== accountId));
+        });
+        if (invalidAccountEvidence !== undefined) {
+            throw new Error("IBKR active-order response did not provide unambiguous account identity");
+        }
+        const normalized = flattened.map(({ order, nestedParent }) => this.normalizeActiveDerivativeOrder(accountId, order, nestedParent));
+        const byOrderId = new Map();
+        const byClientId = new Map();
+        for (const order of normalized) {
+            if (order.orderId !== null) {
+                const members = byOrderId.get(order.orderId) ?? [];
+                members.push(order);
+                byOrderId.set(order.orderId, members);
+            }
+            if (order.clientOrderId !== null) {
+                const members = byClientId.get(order.clientOrderId) ?? [];
+                members.push(order);
+                byClientId.set(order.clientOrderId, members);
+            }
+        }
+        for (const order of normalized) {
+            if (order.orderId !== null && (byOrderId.get(order.orderId)?.length ?? 0) > 1) {
+                this.addOrderUncertainty(order, "DUPLICATE_MEMBER");
+            }
+            const parentIdentity = order.parentOrderId ?? order.parentClientOrderId;
+            if (parentIdentity === null)
+                continue;
+            const brokerMatches = byOrderId.get(parentIdentity) ?? [];
+            const clientMatches = byClientId.get(parentIdentity) ?? [];
+            const matches = new Set([...brokerMatches, ...clientMatches]);
+            if (matches.size === 0)
+                this.addOrderUncertainty(order, "MISSING_PARENT");
+            if (matches.size > 1)
+                this.addOrderUncertainty(order, "AMBIGUOUS_PARENT");
+        }
+        return normalized;
+    }
     async getDerivativeExecutions(input) {
         if (!input.accountId.trim())
             throw new Error("An exact account ID is required");
@@ -616,6 +851,193 @@ export class IbkrClient {
             }
         }
     }
+    validateOrderGraph(request) {
+        if (!request.accountId.trim())
+            throw new Error("An explicit IBKR account ID is required");
+        if (!request.rootClientOrderId.trim() || request.rootClientOrderId.length > 48) {
+            throw new Error("Root client order ID must contain 1 to 48 characters");
+        }
+        if (request.nodes.length < 1 || request.nodes.length > 8) {
+            throw new Error("Derivative order graphs require 1 to 8 members");
+        }
+        const seen = new Set();
+        let roots = 0;
+        for (const node of request.nodes) {
+            if (!node.memberId.trim() ||
+                node.memberId.length > 15 ||
+                !/^[A-Za-z0-9_-]+$/.test(node.memberId)) {
+                throw new Error("Graph member IDs must contain 1 to 15 safe characters");
+            }
+            if (seen.has(node.memberId))
+                throw new Error("Graph member IDs must be unique");
+            if (node.accountId !== request.accountId)
+                throw new Error("Every graph member must target the graph account");
+            if (node.parentMemberId === undefined)
+                roots += 1;
+            else if (!seen.has(node.parentMemberId))
+                throw new Error("Graph parents must precede their children");
+            else if (node.parentMemberId !== request.nodes[0]?.memberId)
+                throw new Error("Derivative order graphs support only root-to-child attachments");
+            if ("legs" in node) {
+                this.validateComboPreview(node);
+            }
+            else {
+                this.validateGraphSingleNode(node);
+            }
+            seen.add(node.memberId);
+        }
+        if (roots !== 1 || request.nodes[0]?.parentMemberId !== undefined) {
+            throw new Error("Derivative order graphs require exactly one root as the first member");
+        }
+    }
+    validateGraphSingleNode(node) {
+        const orderType = node.orderType;
+        if (orderType !== "LMT" && orderType !== "STP" && orderType !== "MKT") {
+            throw new Error("Graph single order type must be LMT, STP, or MKT");
+        }
+        if (!Number.isSafeInteger(node.quantity) || node.quantity <= 0)
+            throw new Error("Order quantity must be a positive integer");
+        if (!Number.isSafeInteger(node.contract.conid) || node.contract.conid <= 0)
+            throw new Error("Order contract has an invalid IBKR conid");
+        if (node.orderType === "LMT" && (!Number.isFinite(node.limit) || node.limit <= 0))
+            throw new Error("LIMIT order requires a positive limit price");
+        if (node.orderType === "STP" && (!Number.isFinite(node.stopPrice) || node.stopPrice <= 0))
+            throw new Error("STOP order requires a positive stop price");
+        this.cmeOperatorMetadata(node.contract.assetClass, node);
+    }
+    graphClientOrderId(request, node) {
+        return node.parentMemberId === undefined
+            ? request.rootClientOrderId
+            : `${request.rootClientOrderId}:${node.memberId}`;
+    }
+    graphOrderTicket(request, node) {
+        const parent = request.nodes.find(({ memberId }) => memberId === node.parentMemberId);
+        if (node.parentMemberId !== undefined && parent === undefined) {
+            throw new Error("Graph parent evidence was lost after validation");
+        }
+        const identity = parent === undefined
+            ? { cOID: this.graphClientOrderId(request, node) }
+            : { parentId: this.graphClientOrderId(request, parent) };
+        if ("legs" in node)
+            return {
+                ...this.comboOrderTicket(node),
+                ...identity,
+                ...this.cmeOperatorMetadata(node.legs[0].contract.assetClass, node),
+            };
+        return {
+            acctId: node.accountId,
+            conid: node.contract.conid,
+            orderType: node.orderType,
+            side: node.side,
+            ...(node.orderType === "LMT"
+                ? { price: node.limit }
+                : node.orderType === "STP"
+                    ? { price: node.stopPrice }
+                    : {}),
+            tif: node.tif,
+            quantity: node.quantity,
+            outsideRTH: node.session === "OVERNIGHT",
+            ...identity,
+            ...this.cmeOperatorMetadata(node.contract.assetClass, node),
+        };
+    }
+    liveOrderMatchesGraphNode(request, node, order) {
+        if (node.parentMemberId === undefined) {
+            if ((order.cOID ?? order.order_ref) !== request.rootClientOrderId)
+                return false;
+            if (String(order.parentId ?? "").trim() !== "")
+                return false;
+        }
+        else if (String(order.parentId ?? "") !== request.rootClientOrderId)
+            return false;
+        if ("legs" in node) {
+            const liveLegs = this.parseComboLegs(order.conidex);
+            const orderType = this.normalizeOrderType(order.order_type ?? order.orderType);
+            const side = this.normalizeOrderSide(order.side);
+            const quantity = this.firstPositiveNumber(order.total_size, order.totalSize, order.size);
+            const price = this.firstNumber(order.limitPrice, order.limit_price, order.price);
+            const expectedPrice = node.priceEffect === "CREDIT" ? -node.limit : node.limit;
+            const outsideRth = order.outsideRTH ?? order.outside_rth;
+            return (liveLegs.length === node.legs.length &&
+                node.legs.every((leg, index) => {
+                    const liveLeg = liveLegs[index];
+                    return liveLeg?.conid === leg.contract.conid && liveLeg.ratio === leg.ratio;
+                }) &&
+                orderType === this.normalizeOrderType("LMT") &&
+                side === "BUY" &&
+                quantity === node.quantity &&
+                price === expectedPrice &&
+                (order.tif === undefined || order.tif.toUpperCase() === node.tif) &&
+                (outsideRth === undefined || outsideRth === (node.session === "OVERNIGHT")));
+        }
+        const orderType = this.normalizeOrderType(order.order_type ?? order.orderType);
+        const expectedOrderType = this.normalizeOrderType(node.orderType);
+        const side = this.normalizeOrderSide(order.side);
+        const quantity = this.firstPositiveNumber(order.total_size, order.totalSize, order.size);
+        const price = node.orderType === "LMT"
+            ? this.firstNumber(order.limitPrice, order.limit_price, order.price)
+            : node.orderType === "STP"
+                ? this.firstNumber(order.stopPrice, order.price)
+                : undefined;
+        const expectedPrice = node.orderType === "LMT" ? node.limit : node.orderType === "STP" ? node.stopPrice : undefined;
+        const outsideRth = order.outsideRTH ?? order.outside_rth;
+        return (order.conid === node.contract.conid &&
+            orderType === expectedOrderType &&
+            side === node.side &&
+            quantity === node.quantity &&
+            price === expectedPrice &&
+            (order.tif === undefined || order.tif.toUpperCase() === node.tif) &&
+            (outsideRth === undefined || outsideRth === (node.session === "OVERNIGHT")));
+    }
+    validateSingleOrder(request) {
+        this.validateSingleOrderFields(request);
+        const identityFields = request;
+        const hasClientOrderId = "clientOrderId" in identityFields;
+        const hasParentId = "parentId" in identityFields;
+        if (hasClientOrderId && typeof identityFields.clientOrderId !== "string") {
+            throw new Error("Client order ID must be a string");
+        }
+        if (hasParentId && typeof identityFields.parentId !== "string") {
+            throw new Error("Parent order ID must be a string");
+        }
+        const clientOrderId = hasClientOrderId ? identityFields.clientOrderId : undefined;
+        const parentId = hasParentId ? identityFields.parentId : undefined;
+        if (clientOrderId !== undefined && parentId !== undefined) {
+            throw new Error("Attached child orders must not include a client order ID");
+        }
+        const identity = clientOrderId ?? parentId;
+        if (!identity?.trim() || identity.length > 64) {
+            throw new Error(parentId === undefined
+                ? "Client order ID must contain 1 to 64 characters"
+                : "Parent order ID must contain 1 to 64 characters");
+        }
+    }
+    validateSingleOrderFields(request) {
+        if (!request.accountId.trim())
+            throw new Error("An explicit IBKR account ID is required");
+        const orderType = request.orderType;
+        if (orderType !== "LMT" && orderType !== "STP") {
+            throw new Error("Order type must be LMT or STP");
+        }
+        if (!Number.isSafeInteger(request.quantity) || request.quantity <= 0) {
+            throw new Error("Order quantity must be a positive integer");
+        }
+        if (!Number.isSafeInteger(request.contract.conid) || request.contract.conid <= 0) {
+            throw new Error("Order contract has an invalid IBKR conid");
+        }
+        if (request.orderType === "LMT") {
+            const limit = request.limit;
+            if (typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0) {
+                throw new Error("LIMIT order requires a positive limit price");
+            }
+        }
+        if (request.orderType === "STP") {
+            const stopPrice = request.stopPrice;
+            if (typeof stopPrice !== "number" || !Number.isFinite(stopPrice) || stopPrice <= 0) {
+                throw new Error("STOP order requires a positive stop price");
+            }
+        }
+    }
     cmeOperatorMetadata(assetClass, input) {
         if (assetClass === "OPT")
             return {};
@@ -643,58 +1065,366 @@ export class IbkrClient {
             outsideRTH: request.session === "OVERNIGHT",
         };
     }
+    singleOrderTicket(request) {
+        return {
+            acctId: request.accountId,
+            conid: request.contract.conid,
+            orderType: request.orderType,
+            side: request.side,
+            price: request.orderType === "LMT" ? request.limit : request.stopPrice,
+            tif: request.tif,
+            quantity: request.quantity,
+            outsideRTH: request.session === "OVERNIGHT",
+        };
+    }
     normalizeOrderSubmission(response, clientOrderId) {
+        const decoded = this.decodeOrderSubmission(response);
+        const correlatedClientOrderId = decoded.orders.length === 1 ? clientOrderId : null;
+        const orders = decoded.orders.map((order) => ({
+            ...order,
+            clientOrderId: correlatedClientOrderId,
+        }));
+        const hasWarnings = decoded.warnings.length > 0;
+        const hasErrors = decoded.errors.length > 0;
+        const hasUnknown = decoded.unrecognizedResponses.length > 0;
+        const hasPendingCancel = decoded.pendingCancelOrderIds.length > 0;
+        if (decoded.warnings.length === 1 && !hasErrors && orders.length === 0 && !hasUnknown) {
+            return { state: "warning", warnings: decoded.warnings };
+        }
+        if (hasErrors &&
+            !decoded.responseIsArray &&
+            !hasWarnings &&
+            orders.length === 0 &&
+            !hasUnknown) {
+            return {
+                state: "rejected",
+                reasons: decoded.errors.map(({ message }) => message),
+                errors: decoded.errors,
+            };
+        }
+        if (!hasWarnings && !hasErrors && !hasUnknown && !hasPendingCancel && orders.length === 1) {
+            const order = orders[0];
+            if (order === undefined)
+                throw new Error("Single-order normalization lost order evidence");
+            if (order.status === "REJECTED" || order.status === "CANCELED") {
+                return {
+                    state: "rejected",
+                    reasons: [`Order ${order.orderId} returned terminal status ${order.status}`],
+                    errors: [],
+                    orders,
+                };
+            }
+            if (order.status !== "UNKNOWN") {
+                return { state: "accepted", ...order, warnings: [] };
+            }
+        }
+        return this.singleOrderRecoveryResult(decoded, orders);
+    }
+    graphMemberEvidence(request, node, order) {
+        const index = request.nodes.findIndex(({ memberId }) => memberId === node.memberId);
+        let depth = 0;
+        let parentId = node.parentMemberId;
+        while (parentId !== undefined) {
+            depth += 1;
+            parentId = request.nodes.find(({ memberId }) => memberId === parentId)?.parentMemberId;
+        }
+        const rawId = order?.order_id ?? order?.orderId;
+        const orderId = typeof rawId === "string" || typeof rawId === "number" ? String(rawId).trim() || null : null;
+        const filledQuantity = this.firstNumber(order?.cum_fill, order?.cumFill, order?.filledQuantity, order?.filled);
+        const quantity = this.firstPositiveNumber(order?.total_size, order?.totalSize, order?.size);
+        const remainingQuantity = this.firstNumber(order?.remainingQuantity, order?.remaining_size, order?.remaining) ??
+            (quantity !== undefined && filledQuantity !== undefined
+                ? Math.max(0, quantity - filledQuantity)
+                : undefined);
+        return {
+            memberId: node.memberId,
+            role: index < 0
+                ? "unknown"
+                : depth === 0
+                    ? "root"
+                    : depth === 1
+                        ? "child"
+                        : depth === 2
+                            ? "grandchild"
+                            : "descendant",
+            parentMemberId: node.parentMemberId ?? null,
+            parentOrderId: null,
+            orderId,
+            status: order === undefined
+                ? "WARNING_PENDING"
+                : this.normalizeDerivativeOrderStatus(order.order_status ?? order.orderStatus ?? order.status, filledQuantity ?? 0, remainingQuantity ?? 0),
+            clientOrderId: this.graphClientOrderId(request, node),
+            request: node,
+        };
+    }
+    attachGraphParentOrderIds(members) {
+        const ids = new Map(members.map(({ memberId, orderId }) => [memberId, orderId]));
+        return members.map((member) => ({
+            ...member,
+            parentOrderId: member.parentMemberId === null ? null : (ids.get(member.parentMemberId) ?? null),
+        }));
+    }
+    normalizeOrderGraphSubmission(response, request, previousMembers) {
+        const decoded = this.decodeOrderSubmission(response);
+        const cleanOrders = decoded.warnings.length === 0 &&
+            decoded.errors.length === 0 &&
+            decoded.unrecognizedResponses.length === 0;
+        const distinct = new Set(decoded.orders.map(({ orderId }) => orderId)).size === decoded.orders.length;
+        const canCorrelatePositionally = cleanOrders && distinct && decoded.orders.length === request.nodes.length;
+        const members = this.attachGraphParentOrderIds(request.nodes.map((node, index) => {
+            const order = canCorrelatePositionally ? decoded.orders[index] : undefined;
+            if (order === undefined)
+                return (previousMembers.find(({ memberId }) => memberId === node.memberId) ??
+                    this.graphMemberEvidence(request, node));
+            const evidence = this.graphMemberEvidence(request, node, {
+                order_id: order.orderId,
+                order_status: order.status,
+            });
+            return { ...evidence, status: order.status };
+        }));
+        if (decoded.warnings.length === 1 &&
+            decoded.orders.length === 0 &&
+            decoded.errors.length === 0 &&
+            decoded.unrecognizedResponses.length === 0) {
+            const warning = decoded.warnings[0];
+            if (warning === undefined)
+                throw new Error("Graph warning evidence was lost");
+            return {
+                state: "warning",
+                rootClientOrderId: request.rootClientOrderId,
+                members,
+                warnings: decoded.warnings,
+                continuation: { replyId: warning.replyId, request, members },
+            };
+        }
+        if (decoded.errors.length > 0 &&
+            !decoded.responseIsArray &&
+            decoded.orders.length === 0 &&
+            decoded.warnings.length === 0 &&
+            decoded.unrecognizedResponses.length === 0) {
+            return {
+                state: "rejected",
+                rootClientOrderId: request.rootClientOrderId,
+                members,
+                reasons: decoded.errors.map(({ message }) => message),
+                errors: decoded.errors,
+            };
+        }
+        if (cleanOrders &&
+            distinct &&
+            decoded.orders.length === request.nodes.length &&
+            decoded.pendingCancelOrderIds.length === 0 &&
+            decoded.orders.every(({ status }) => status !== "UNKNOWN" && status !== "REJECTED" && status !== "CANCELED")) {
+            return {
+                state: "accepted",
+                rootClientOrderId: request.rootClientOrderId,
+                members,
+                warnings: [],
+            };
+        }
+        return {
+            state: "recovery_required",
+            rootClientOrderId: request.rootClientOrderId,
+            members,
+            reasons: [
+                this.submissionRecoveryReason(decoded, decoded.orders.length, request.nodes.length),
+            ],
+            warnings: decoded.warnings,
+            errors: decoded.errors,
+            unrecognizedResponses: canCorrelatePositionally
+                ? decoded.unrecognizedResponses
+                : [...decoded.unrecognizedResponses, ...decoded.orders],
+        };
+    }
+    normalizeMultiOrderSubmission(response, parentClientOrderId) {
+        const decoded = this.decodeOrderSubmission(response);
+        const hasDistinctBrokerOrderIds = decoded.orders.length === 2 &&
+            new Set(decoded.orders.map(({ orderId }) => orderId)).size === 2;
+        const rolesArePositionallyComplete = decoded.orders.length === 2 &&
+            hasDistinctBrokerOrderIds &&
+            decoded.warnings.length === 0 &&
+            decoded.errors.length === 0 &&
+            decoded.unrecognizedResponses.length === 0;
+        const orders = decoded.orders.map((order, index) => ({
+            ...order,
+            clientOrderId: rolesArePositionallyComplete && index === 0 ? parentClientOrderId : null,
+            role: rolesArePositionallyComplete && index === 0
+                ? "parent"
+                : rolesArePositionallyComplete && index === 1
+                    ? "child"
+                    : "unknown",
+        }));
+        const hasWarnings = decoded.warnings.length > 0;
+        const hasErrors = decoded.errors.length > 0;
+        const hasUnknown = decoded.unrecognizedResponses.length > 0;
+        if (decoded.warnings.length === 1 && !hasErrors && orders.length === 0 && !hasUnknown) {
+            const warning = decoded.warnings[0];
+            if (warning === undefined)
+                throw new Error("Contingent warning evidence was lost");
+            return {
+                state: "warning",
+                warnings: decoded.warnings,
+                continuation: { replyId: warning.replyId, parentClientOrderId },
+            };
+        }
+        if (hasErrors &&
+            !decoded.responseIsArray &&
+            !hasWarnings &&
+            orders.length === 0 &&
+            !hasUnknown) {
+            return {
+                state: "rejected",
+                parentClientOrderId,
+                reasons: decoded.errors.map(({ message }) => message),
+                errors: decoded.errors,
+            };
+        }
+        if (!hasWarnings &&
+            !hasErrors &&
+            !hasUnknown &&
+            decoded.pendingCancelOrderIds.length === 0 &&
+            orders.length === 2 &&
+            hasDistinctBrokerOrderIds) {
+            const [parent, child] = orders;
+            if (parent !== undefined && child !== undefined) {
+                const terminalFailure = orders.find(({ status }) => status === "REJECTED" || status === "CANCELED");
+                const unknownStatus = orders.find(({ status }) => status === "UNKNOWN");
+                if (terminalFailure === undefined && unknownStatus === undefined) {
+                    return { state: "accepted", orders: [parent, child], warnings: [] };
+                }
+            }
+        }
+        return this.contingentRecoveryResult(decoded, orders, parentClientOrderId);
+    }
+    decodeOrderSubmission(response) {
         const items = Array.isArray(response) ? response : [response];
-        const warnings = items.flatMap((item) => {
-            if (!("id" in item) || typeof item.id !== "string")
-                return [];
-            const messageIds = Array.isArray(item.messageIds)
-                ? item.messageIds.filter((value) => typeof value === "string")
-                : [];
-            return [
-                {
-                    replyId: item.id,
-                    messages: Array.isArray(item.message)
-                        ? item.message.filter((value) => typeof value === "string")
+        const decoded = {
+            responseIsArray: Array.isArray(response),
+            orders: [],
+            pendingCancelOrderIds: [],
+            warnings: [],
+            errors: [],
+            unrecognizedResponses: [],
+        };
+        for (const item of items) {
+            if (typeof item !== "object" || item === null || Array.isArray(item)) {
+                decoded.unrecognizedResponses.push(item);
+                continue;
+            }
+            const record = item;
+            let recognized = false;
+            const rawWarningId = record["id"];
+            if (typeof rawWarningId === "string" && rawWarningId.trim()) {
+                const rawMessageIds = record["messageIds"];
+                const messageIds = Array.isArray(rawMessageIds)
+                    ? rawMessageIds.filter((value) => typeof value === "string")
+                    : [];
+                decoded.warnings.push({
+                    replyId: rawWarningId.trim(),
+                    messages: Array.isArray(record["message"])
+                        ? record["message"].filter((value) => typeof value === "string")
                         : [],
                     messageIds,
-                    known: messageIds.length > 0 && messageIds.every((id) => KNOWN_ORDER_WARNING_IDS.has(id)),
-                },
-            ];
-        });
-        if (warnings.length > 0)
-            return { state: "warning", warnings };
-        const errors = items.flatMap((item) => {
-            if (!("error" in item) || item.error === undefined || item.error === null)
-                return [];
-            return [this.normalizeBrokerError(item.error, item)];
-        });
-        if (errors.length > 0) {
-            return { state: "rejected", reasons: errors.map(({ message }) => message), errors };
-        }
-        const accepted = items.find((item) => "order_id" in item || "orderId" in item);
-        if (accepted !== undefined) {
-            const orderId = ("order_id" in accepted ? accepted.order_id : undefined) ??
-                ("orderId" in accepted ? accepted.orderId : undefined);
-            if (typeof orderId === "string" || typeof orderId === "number") {
-                const orderStatus = ("order_status" in accepted ? accepted.order_status : undefined) ??
-                    ("orderStatus" in accepted ? accepted.orderStatus : undefined);
-                return {
-                    state: "accepted",
-                    orderId: String(orderId),
+                    known: Array.isArray(rawMessageIds) &&
+                        rawMessageIds.length > 0 &&
+                        rawMessageIds.every((id) => typeof id === "string" && KNOWN_ORDER_WARNING_IDS.has(id)),
+                });
+                recognized = true;
+            }
+            else if ("id" in record) {
+                decoded.unrecognizedResponses.push({ ...record });
+                recognized = true;
+            }
+            if (record["error"] !== undefined && record["error"] !== null) {
+                if (this.isMeaningfulBrokerError(record["error"], record)) {
+                    decoded.errors.push(this.normalizeBrokerError(record["error"], record));
+                }
+                else {
+                    decoded.unrecognizedResponses.push({ ...record });
+                }
+                recognized = true;
+            }
+            const hasOrderId = "order_id" in record || "orderId" in record;
+            const rawOrderId = record["order_id"] ?? record["orderId"];
+            const orderId = typeof rawOrderId === "string" && rawOrderId.trim()
+                ? rawOrderId.trim()
+                : typeof rawOrderId === "number" && Number.isSafeInteger(rawOrderId) && rawOrderId > 0
+                    ? String(rawOrderId)
+                    : null;
+            if (orderId !== null) {
+                const orderStatus = record["order_status"] ?? record["orderStatus"];
+                if (typeof orderStatus === "string" &&
+                    this.canonicalIbkrOrderStatus(orderStatus) === "PENDING_CANCEL") {
+                    decoded.pendingCancelOrderIds.push(orderId);
+                }
+                decoded.orders.push({
+                    orderId,
                     status: this.normalizeDerivativeOrderStatus(typeof orderStatus === "string" ? orderStatus : undefined, 0, 0),
-                    clientOrderId,
-                    warnings: [],
-                };
+                    clientOrderId: null,
+                });
+                recognized = true;
             }
+            else if (hasOrderId) {
+                decoded.unrecognizedResponses.push({ ...record });
+                recognized = true;
+            }
+            if (!recognized)
+                decoded.unrecognizedResponses.push({ ...record });
         }
-        const unknown = "IBKR returned an unknown order response";
+        if (items.length === 0)
+            decoded.unrecognizedResponses.push({});
+        return decoded;
+    }
+    singleOrderRecoveryResult(decoded, orders) {
         return {
-            state: "rejected",
-            reasons: [unknown],
-            errors: [{ message: unknown, code: null, statusCode: null, details: {} }],
+            state: "recovery_required",
+            reasons: [this.submissionRecoveryReason(decoded, orders.length, 1)],
+            orders,
+            warnings: decoded.warnings,
+            errors: decoded.errors,
+            unrecognizedResponses: decoded.unrecognizedResponses,
         };
     }
+    contingentRecoveryResult(decoded, orders, parentClientOrderId) {
+        return {
+            state: "recovery_required",
+            parentClientOrderId,
+            reasons: [this.submissionRecoveryReason(decoded, orders.length, 2)],
+            orders,
+            warnings: decoded.warnings,
+            errors: decoded.errors,
+            unrecognizedResponses: decoded.unrecognizedResponses,
+        };
+    }
+    submissionRecoveryReason(decoded, orderCount, expectedOrderCount) {
+        const pendingCancelOrderId = decoded.pendingCancelOrderIds[0];
+        if (pendingCancelOrderId !== undefined) {
+            return `Order ${pendingCancelOrderId} has a pending cancellation`;
+        }
+        const terminal = decoded.orders.find(({ status }) => status === "REJECTED" || status === "CANCELED");
+        if (terminal !== undefined) {
+            return `Order ${terminal.orderId} returned terminal status ${terminal.status}`;
+        }
+        if (decoded.orders.some(({ status }) => status === "UNKNOWN")) {
+            return "IBKR returned an order ID with an unknown status";
+        }
+        if (new Set(decoded.orders.map(({ orderId }) => orderId)).size < decoded.orders.length) {
+            return "IBKR returned duplicate broker order IDs";
+        }
+        if (decoded.errors.length > 0 && decoded.warnings.length > 0) {
+            return "IBKR returned both warnings and rejections for one submission";
+        }
+        if (decoded.warnings.length > 1) {
+            return "IBKR returned multiple warning continuations for one submission";
+        }
+        if (orderCount !== expectedOrderCount) {
+            return `IBKR returned ${String(orderCount)} of ${String(expectedOrderCount)} expected order acknowledgements`;
+        }
+        if (decoded.unrecognizedResponses.length > 0) {
+            return "IBKR returned one or more unrecognized order responses";
+        }
+        return "IBKR returned mixed or incomplete order evidence";
+    }
     normalizeBrokerError(error, response) {
         const nested = typeof error === "object" && error !== null ? error : undefined;
         const nestedMessage = nested ? nested.message : undefined;
@@ -714,6 +1444,20 @@ export class IbkrClient {
             details: response,
         };
     }
+    isMeaningfulBrokerError(error, response) {
+        const nested = typeof error === "object" && error !== null ? error : undefined;
+        const nestedRecord = nested;
+        const messages = [error, nestedRecord?.["message"], response["message"]];
+        if (messages.some((value) => typeof value === "string" && value.trim()))
+            return true;
+        const code = nestedRecord?.["code"] ?? response["code"];
+        if ((typeof code === "string" && code.trim()) ||
+            (typeof code === "number" && Number.isFinite(code))) {
+            return true;
+        }
+        const status = nestedRecord?.["statusCode"] ?? nestedRecord?.["status"] ?? response["statusCode"];
+        return typeof status === "number" && Number.isFinite(status) && status >= 400;
+    }
     normalizeDerivativeOrderLifecycle(accountId, orderId, order) {
         const quantity = this.firstPositiveNumber(order.total_size, order.totalSize, order.size);
         const filledQuantity = this.firstNumber(order.cum_fill, order.cumFill, order.filledQuantity, order.filled);
@@ -742,6 +1486,167 @@ export class IbkrClient {
             updatedAt: this.parseOrderTime(order)?.toISOString() ?? null,
         };
     }
+    flattenActiveOrders(orders, nestedParent = null) {
+        return orders.flatMap((order) => {
+            const children = [...new Set([...(order.childOrders ?? []), ...(order.children ?? [])])];
+            return [{ order, nestedParent }, ...this.flattenActiveOrders(children, order)];
+        });
+    }
+    normalizeActiveDerivativeOrder(accountId, order, nestedParent) {
+        const uncertainty = [];
+        const total = this.firstNumber(order.total_size, order.totalSize, order.size) ?? null;
+        const filled = this.firstNumber(order.cum_fill, order.cumFill, order.filledQuantity, order.filled) ?? null;
+        const remaining = this.firstNumber(order.remainingQuantity, order.remaining_size, order.remaining) ??
+            (total !== null && filled !== null ? Math.max(0, total - filled) : null);
+        if (total === null || filled === null || remaining === null)
+            uncertainty.push("INCOMPLETE_QUANTITIES");
+        const rawStatus = order.order_status ?? order.orderStatus ?? order.status;
+        const status = this.normalizeDerivativeOrderStatus(rawStatus, filled ?? 0, remaining ?? 0);
+        if (status === "UNKNOWN")
+            uncertainty.push("UNKNOWN_STATUS");
+        const rawOrderId = order.order_id ?? order.orderId;
+        if (rawOrderId === undefined)
+            uncertainty.push("MISSING_BROKER_ORDER_ID");
+        const explicitParentOrderId = order.parent_order_id ?? order.parentOrderId ?? order.parent_id;
+        const explicitParentClientId = order.parentClientOrderId ?? order.parent_order_ref ?? order.parentId;
+        const nestedBrokerId = nestedParent?.order_id ?? nestedParent?.orderId;
+        const nestedClientId = nestedParent?.cOID ?? nestedParent?.order_ref;
+        if (nestedParent !== null &&
+            explicitParentOrderId === undefined &&
+            explicitParentClientId === undefined) {
+            uncertainty.push("PARTIAL_GRAPH");
+        }
+        const legs = this.normalizeActiveDerivativeLegs(order, total, uncertainty);
+        const orderTime = this.parseOrderTime(order)?.toISOString() ?? null;
+        return {
+            accountId,
+            orderId: rawOrderId === undefined ? null : String(rawOrderId),
+            clientOrderId: order.cOID ?? order.order_ref ?? null,
+            parentOrderId: explicitParentOrderId === undefined
+                ? nestedBrokerId === undefined
+                    ? null
+                    : String(nestedBrokerId)
+                : String(explicitParentOrderId),
+            parentClientOrderId: explicitParentClientId === undefined
+                ? (nestedClientId ?? null)
+                : String(explicitParentClientId),
+            graphRole: nestedParent !== null ||
+                explicitParentOrderId !== undefined ||
+                explicitParentClientId !== undefined
+                ? "CHILD"
+                : rawOrderId === undefined
+                    ? "UNKNOWN"
+                    : "ROOT",
+            status,
+            totalQuantity: total,
+            filledQuantity: filled,
+            remainingQuantity: remaining,
+            tif: order.tif ?? order.timeInForce ?? null,
+            session: order.outsideRTH === true || order.outside_rth === true
+                ? "OVERNIGHT"
+                : order.outsideRTH === false || order.outside_rth === false
+                    ? "REGULAR"
+                    : "UNKNOWN",
+            orderType: this.normalizeOrderType(order.order_type ?? order.orderType) ?? null,
+            limitPrice: this.firstNumber(order.limitPrice, order.limit_price, order.price) ?? null,
+            stopPrice: this.firstNumber(order.stopPrice) ?? null,
+            enteredAt: orderTime,
+            updatedAt: order.lastExecutionTime_r !== undefined || order.lastExecutionTime !== undefined
+                ? orderTime
+                : null,
+            legs,
+            uncertainty,
+        };
+    }
+    normalizeActiveDerivativeLegs(order, total, orderUncertainty) {
+        const description = [
+            order.orderDescriptionWithContract,
+            order.order_description_with_contract,
+            order.contractDescription1,
+            order.contract_description_1,
+            order.description1,
+            order.symbol,
+        ]
+            .filter((value) => typeof value === "string")
+            .join(" ");
+        const describedOptions = [...description.matchAll(/([A-Z ]{1,6}\d{6}[CP]\d{8})/gi)].flatMap((match) => {
+            const symbol = match[1]?.toUpperCase() ?? "";
+            const parsed = parseOsiOptionSymbol(symbol);
+            return parsed === null ? [] : [{ symbol, ...parsed }];
+        });
+        const uniqueDescribedOptions = describedOptions.filter((option, index) => describedOptions.findIndex((candidate) => candidate.symbol === option.symbol) === index);
+        const side = this.normalizeOrderSide(order.side);
+        const signedSide = side === "BUY" ? 1 : side === "SELL" ? -1 : null;
+        let rawLegs = [];
+        const conidex = typeof order.conidex === "string" ? order.conidex.trim() : null;
+        if (conidex?.includes(";;;")) {
+            const match = /^(\d+)(?:@[A-Za-z0-9._-]+)?;;;(.+)$/.exec(conidex);
+            if (match?.[1] !== "28812380") {
+                orderUncertainty.push("MALFORMED_CONIDEX");
+            }
+            else {
+                rawLegs = (match[2] ?? "").split(",").map((member) => {
+                    const legMatch = /^(\d+)\/([+-]?\d+)$/.exec(member.trim());
+                    const conid = Number(legMatch?.[1]);
+                    const ratio = Number(legMatch?.[2]);
+                    if (!legMatch ||
+                        !Number.isSafeInteger(conid) ||
+                        conid <= 0 ||
+                        !Number.isSafeInteger(ratio) ||
+                        ratio === 0) {
+                        return { conid: null, ratio: null, quantityRatio: null };
+                    }
+                    return {
+                        conid,
+                        ratio: signedSide === null ? null : signedSide * ratio,
+                        quantityRatio: Math.abs(ratio),
+                    };
+                });
+                if (rawLegs.length === 0 || rawLegs.some((leg) => leg.conid === null)) {
+                    orderUncertainty.push("MALFORMED_CONIDEX");
+                }
+            }
+            if (rawLegs.length === 0)
+                orderUncertainty.push("AGGREGATE_ONLY");
+        }
+        else if (Number.isSafeInteger(order.conid) && Number(order.conid) > 0) {
+            rawLegs = [{ conid: Number(order.conid), ratio: signedSide, quantityRatio: 1 }];
+        }
+        else {
+            if (conidex)
+                orderUncertainty.push("MALFORMED_CONIDEX");
+            orderUncertainty.push("MISSING_LEG_IDENTITY");
+        }
+        if (rawLegs.length === 0) {
+            rawLegs = [{ conid: null, ratio: null, quantityRatio: null }];
+        }
+        return rawLegs.map((leg) => {
+            const legUncertainty = [];
+            if (leg.conid === null)
+                legUncertainty.push("MISSING_LEG_IDENTITY");
+            if (leg.ratio === null) {
+                const directionUncertainty = leg.conid !== null && signedSide === null ? "UNKNOWN_SIDE" : "MALFORMED_CONIDEX";
+                legUncertainty.push(directionUncertainty);
+                if (!orderUncertainty.includes(directionUncertainty)) {
+                    orderUncertainty.push(directionUncertainty);
+                }
+            }
+            return {
+                conid: leg.conid,
+                ratio: leg.ratio,
+                side: leg.ratio === null ? "UNKNOWN" : leg.ratio > 0 ? "BUY" : "SELL",
+                quantity: total === null || leg.quantityRatio === null ? null : total * leg.quantityRatio,
+                option: rawLegs.length === 1 && uniqueDescribedOptions.length === 1
+                    ? (uniqueDescribedOptions[0] ?? null)
+                    : null,
+                uncertainty: legUncertainty,
+            };
+        });
+    }
+    addOrderUncertainty(order, uncertainty) {
+        if (!order.uncertainty.includes(uncertainty))
+            order.uncertainty.push(uncertainty);
+    }
     normalizeDerivativeExecution(accountId, trade) {
         if (!trade.execution_id || !Number.isSafeInteger(trade.conid) || Number(trade.conid) <= 0) {
             return undefined;
@@ -954,24 +1859,27 @@ export class IbkrClient {
         });
     }
     normalizeDerivativeOrderStatus(value, filledQuantity, remainingQuantity) {
-        const status = value
-            ?.replace(/([a-z])([A-Z])/g, "$1_$2")
-            .replace(/\s+/g, "_")
-            .toUpperCase();
-        if (filledQuantity > 0 && remainingQuantity > 0)
-            return "PARTIALLY_FILLED";
+        const status = this.canonicalIbkrOrderStatus(value);
         if (status === "FILLED")
             return "FILLED";
         if (status === "CANCELLED" || status === "CANCELED")
             return "CANCELED";
         if (status === "INACTIVE" || status === "REJECTED")
             return "REJECTED";
+        if (filledQuantity > 0 && remainingQuantity > 0)
+            return "PARTIALLY_FILLED";
         if (status === "API_PENDING" || status === "PENDING_SUBMIT")
             return "PENDING";
         if (status !== undefined && IBKR_WORKING_STATUSES.has(status))
             return "WORKING";
         return "UNKNOWN";
     }
+    canonicalIbkrOrderStatus(value) {
+        return value
+            ?.replace(/([a-z])([A-Z])/g, "$1_$2")
+            .replace(/\s+/g, "_")
+            .toUpperCase();
+    }
     normalizeComboPreview(accountId, diagnostics, response) {
         const commission = this.whatIfNumber(response.amount?.commission);
         const initialMargin = this.whatIfMargin(response.initial);
@@ -1021,11 +1929,14 @@ export class IbkrClient {
         if (brokerageAccounts.accounts && !brokerageAccounts.accounts.includes(accountId)) {
             throw new Error(`IBKR account ${accountId} is not available for trading/order queries.`);
         }
-        await this.req({
+        const switchedAccount = await this.req({
             path: "iserver/account",
             method: "POST",
             data: { acctId: accountId },
         });
+        if (switchedAccount.set !== true || switchedAccount.acctId !== accountId) {
+            throw new Error(`IBKR account switch was not confirmed for ${accountId}.`);
+        }
     }
     normalizeStockListing(symbol, listing) {
         const assetType = listing.assetClass === "STK" ? "EQUITY" : listing.assetClass;