@gbozee/ultimate 0.0.2-next.72 → 0.0.2-next.74

package/dist/index.js

@@ -71933,6 +71933,21 @@ class BaseExchange {
       });
     }
   }
+  async previewSpotMarginHedge(_payload) {
+    throw new Error("Spot margin hedge preview is not supported on this exchange");
+  }
+  async previewFuturesReplay(_payload) {
+    throw new Error("Futures replay preview is not supported on this exchange");
+  }
+  async placeSpotMarginHedge(_payload) {
+    throw new Error("Spot margin hedge placement is not supported on this exchange");
+  }
+  async placeFuturesReplay(_payload) {
+    throw new Error("Futures replay placement is not supported on this exchange");
+  }
+  async placeFuturesExactTrade(_payload) {
+    throw new Error("Futures exact trade placement is not supported on this exchange");
+  }
   async placeSpotLimitOrders(_payload) {}
   async buildCumulative(payload) {
     const {
@@ -72340,6 +72355,389 @@ class BaseExchange {
 
 // src/exchanges/binance/index.ts
 var import_p_limit = __toESM(require_p_limit(), 1);
+
+// src/exchanges/binance/futures-replay.ts
+function roundNumber(value2, digits = 8) {
+  return Number(value2.toFixed(digits));
+}
+function parseNumber2(value2) {
+  if (value2 === undefined || value2 === null || value2 === "")
+    return;
+  const parsed = Number(value2);
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    return;
+  return roundNumber(parsed);
+}
+function normalizeOrderInput(order) {
+  const stop = parseNumber2(order.stop) ?? parseNumber2(order.stopPrice) ?? parseNumber2(order.triggerPrice);
+  const type = order.type ? order.type.toUpperCase() : undefined;
+  const quantity = order.quantity ?? order.qty ?? 0;
+  return {
+    price: roundNumber(Number(order.price)),
+    quantity: roundNumber(Number(quantity)),
+    ...stop ? { stop } : {},
+    ...type && type !== "LIMIT" ? { type } : {}
+  };
+}
+function sortReplayOrders(orders) {
+  return [...orders].sort((left, right) => {
+    const leftTrigger = left.stop ?? left.price;
+    const rightTrigger = right.stop ?? right.price;
+    if (leftTrigger !== rightTrigger)
+      return leftTrigger - rightTrigger;
+    if (left.price !== right.price)
+      return left.price - right.price;
+    return left.quantity - right.quantity;
+  });
+}
+function buildReplayStopLimitPrice(payload) {
+  const spread = payload.stop > 30000 ? 1.00005 : 1.0002;
+  return roundNumber(payload.kind === "long" ? payload.stop * spread ** -1 : payload.stop * spread);
+}
+function normalizeRequestedEntryOrders(orders) {
+  return sortReplayOrders(orders.map((order) => ({
+    price: roundNumber(Number(order.price)),
+    quantity: roundNumber(Number(order.quantity))
+  })));
+}
+function normalizeRequestedStopOrders(payload) {
+  return sortReplayOrders(payload.orders.map((order) => {
+    const stop = parseNumber2(order.stop) ?? roundNumber(Number(order.price));
+    return {
+      price: order.price !== undefined ? roundNumber(Number(order.price)) : buildReplayStopLimitPrice({
+        kind: payload.kind,
+        stop
+      }),
+      quantity: roundNumber(Number(order.quantity)),
+      stop,
+      type: (order.type || "STOP").toUpperCase()
+    };
+  }));
+}
+function normalizeRequestedTakeProfitOrders(orders) {
+  return sortReplayOrders(orders.map((order) => {
+    const stop = parseNumber2(order.stop);
+    const type = order.type?.toUpperCase();
+    return {
+      price: roundNumber(Number(order.price)),
+      quantity: roundNumber(Number(order.quantity)),
+      ...stop ? { stop } : {},
+      ...type ? { type } : stop ? { type: "TAKE_PROFIT" } : {}
+    };
+  }));
+}
+function buildOrderKey(order) {
+  return [
+    order.type || "LIMIT",
+    order.price,
+    order.quantity,
+    order.stop ?? ""
+  ].join(":");
+}
+function buildComparisonBucket(options) {
+  const expected = sortReplayOrders(options.expected);
+  const actual = sortReplayOrders(options.actual);
+  const expected_keys = expected.map(buildOrderKey);
+  const actual_keys = actual.map(buildOrderKey);
+  return {
+    expected,
+    actual,
+    missing: expected_keys.filter((key) => !actual_keys.includes(key)),
+    extra: actual_keys.filter((key) => !expected_keys.includes(key))
+  };
+}
+function buildFuturesReplaySnapshot(payload) {
+  const entry_side = payload.kind === "long" ? "buy" : "sell";
+  const close_side = payload.kind === "long" ? "sell" : "buy";
+  const entry_orders = [];
+  const stop_orders = [];
+  const take_profit_orders = [];
+  for (const order of payload.open_orders) {
+    if (order.kind !== payload.kind)
+      continue;
+    const normalized_order = normalizeOrderInput(order);
+    const type = (normalized_order.type || "LIMIT").toUpperCase();
+    if (order.side === entry_side) {
+      entry_orders.push(normalized_order);
+      continue;
+    }
+    if (order.side !== close_side)
+      continue;
+    if (type.includes("TAKE_PROFIT") || normalized_order.stop === undefined) {
+      take_profit_orders.push(normalized_order);
+      continue;
+    }
+    stop_orders.push(normalized_order);
+  }
+  return {
+    symbol: payload.symbol,
+    kind: payload.kind,
+    current_price: payload.current_price,
+    position: payload.position,
+    open_orders: payload.open_orders.filter((order) => order.kind === payload.kind),
+    entry_orders: sortReplayOrders(entry_orders),
+    stop_orders: sortReplayOrders(stop_orders),
+    take_profit_orders: sortReplayOrders(take_profit_orders)
+  };
+}
+function inferFuturesReplayInputFromLiveOrders(payload) {
+  const snapshot = buildFuturesReplaySnapshot(payload);
+  return {
+    symbol: payload.symbol,
+    kind: payload.kind,
+    current_price: payload.current_price,
+    position: payload.position,
+    entry_orders: snapshot.entry_orders,
+    stop_orders: snapshot.stop_orders,
+    take_profit_orders: snapshot.take_profit_orders
+  };
+}
+function compareFuturesReplayOrders(payload) {
+  const entry = buildComparisonBucket({
+    expected: payload.entry_orders,
+    actual: payload.snapshot.entry_orders
+  });
+  const stop = buildComparisonBucket({
+    expected: payload.stop_orders,
+    actual: payload.snapshot.stop_orders
+  });
+  const take_profit = buildComparisonBucket({
+    expected: payload.take_profit_orders,
+    actual: payload.snapshot.take_profit_orders
+  });
+  return {
+    matches: entry.missing.length === 0 && entry.extra.length === 0 && stop.missing.length === 0 && stop.extra.length === 0 && take_profit.missing.length === 0 && take_profit.extra.length === 0,
+    entry,
+    stop,
+    take_profit
+  };
+}
+function buildFuturesReplayPlan(payload) {
+  return {
+    symbol: payload.symbol,
+    kind: payload.kind,
+    orders_to_cancel: payload.snapshot.open_orders,
+    orders_to_create: {
+      entry: sortReplayOrders(payload.entry_orders),
+      stop: sortReplayOrders(payload.stop_orders),
+      take_profit: sortReplayOrders(payload.take_profit_orders)
+    }
+  };
+}
+function normalizeFuturesReplayInput(payload) {
+  return {
+    entry_orders: normalizeRequestedEntryOrders(payload.entry_orders),
+    stop_orders: normalizeRequestedStopOrders({
+      kind: payload.kind,
+      orders: payload.stop_orders
+    }),
+    take_profit_orders: normalizeRequestedTakeProfitOrders(payload.take_profit_orders)
+  };
+}
+
+// src/exchanges/binance/spot-margin-hedge.ts
+function roundNumber2(value2, digits = 8) {
+  return Number(value2.toFixed(digits));
+}
+var STOP_LIMIT_SPREAD_PERCENT = 0.0005;
+function normalizeOrderInput2(order) {
+  return {
+    price: roundNumber2(order.price),
+    quantity: roundNumber2(order.quantity)
+  };
+}
+function sortOrderInputs(orders) {
+  return [...orders].map(normalizeOrderInput2).sort((left, right) => left.price - right.price);
+}
+function normalizeOrderForComparison(order) {
+  const type = (order.type || "limit").toLowerCase();
+  const raw_stop = "stop" in order && order.stop !== undefined ? order.stop : ("stopPrice" in order) ? order.stopPrice : undefined;
+  const parsed_stop = raw_stop === undefined || raw_stop === null || raw_stop === "" ? undefined : Number(raw_stop);
+  return {
+    side: order.side,
+    type,
+    price: roundNumber2(order.price),
+    quantity: roundNumber2(order.quantity),
+    stop: parsed_stop !== undefined && Number.isFinite(parsed_stop) && parsed_stop > 0 ? roundNumber2(parsed_stop) : undefined
+  };
+}
+function normalizeOrders(orders) {
+  return [...orders].map(normalizeOrderForComparison).sort((left, right) => {
+    if (left.side !== right.side)
+      return left.side.localeCompare(right.side);
+    if (left.type !== right.type)
+      return left.type.localeCompare(right.type);
+    if (left.price !== right.price)
+      return left.price - right.price;
+    return left.quantity - right.quantity;
+  });
+}
+function toPlannedOrders(orders) {
+  return normalizeOrders(orders).map((order) => ({
+    side: order.side,
+    type: order.type,
+    price: order.price,
+    quantity: order.quantity,
+    stop: order.stop
+  }));
+}
+function buildOrderKey2(order) {
+  return [
+    order.side,
+    order.type,
+    order.price,
+    order.quantity,
+    order.stop ?? ""
+  ].join(":");
+}
+function buildDiff(options) {
+  const expectedKeys = options.expected.map(buildOrderKey2);
+  const actualKeys = options.actual.map(buildOrderKey2);
+  return {
+    missing: expectedKeys.filter((key) => !actualKeys.includes(key)),
+    extra: actualKeys.filter((key) => !expectedKeys.includes(key))
+  };
+}
+function getQuoteAsset(symbol) {
+  const quoteAssets = ["USDT", "USDC", "BUSD", "BTC", "ETH"];
+  const target = quoteAssets.find((asset) => symbol.endsWith(asset));
+  return target || symbol.slice(-4);
+}
+function sumNotional(orders) {
+  return roundNumber2(orders.reduce((sum, order) => sum + order.price * order.quantity, 0), 8);
+}
+function sumQuantity(orders) {
+  return roundNumber2(orders.reduce((sum, order) => sum + order.quantity, 0), 8);
+}
+function buildLongOrderPlacement(options) {
+  const { order, current_price } = options;
+  if (order.price > current_price) {
+    return {
+      side: "buy",
+      type: "stop_loss_limit",
+      price: order.price,
+      stop: roundNumber2(order.price * (1 - STOP_LIMIT_SPREAD_PERCENT)),
+      quantity: order.quantity
+    };
+  }
+  return {
+    side: "buy",
+    type: "limit",
+    price: order.price,
+    quantity: order.quantity
+  };
+}
+function inferSpotMarginHedgeInputFromLiveOrders(options) {
+  const long_orders = sortOrderInputs([
+    ...options.spot_orders.filter((order) => order.side === "buy").map((order) => ({
+      price: order.price,
+      quantity: order.quantity
+    })),
+    ...options.margin_orders.filter((order) => order.side === "buy").map((order) => ({
+      price: order.price,
+      quantity: order.quantity
+    }))
+  ]);
+  const short_orders = sortOrderInputs([
+    ...options.spot_orders.filter((order) => order.side === "sell").map((order) => ({
+      price: order.price,
+      quantity: order.quantity
+    })),
+    ...options.margin_orders.filter((order) => order.side === "sell").map((order) => ({
+      price: order.price,
+      quantity: order.quantity
+    }))
+  ]);
+  return {
+    symbol: options.symbol,
+    margin_type: options.margin_type,
+    borrow_amount: sumNotional(long_orders),
+    long_orders,
+    short_orders,
+    placement_overrides: {
+      spot: toPlannedOrders(options.spot_orders),
+      margin: toPlannedOrders(options.margin_orders)
+    }
+  };
+}
+function buildSpotMarginHedgePlan(options) {
+  const max_spot_buy_orders = options.max_spot_buy_orders ?? 5;
+  const long_orders = sortOrderInputs(options.long_orders);
+  const short_orders = sortOrderInputs(options.short_orders);
+  const spot_long_orders = long_orders.slice(0, max_spot_buy_orders);
+  const margin_long_orders = long_orders.slice(max_spot_buy_orders);
+  const default_spot_orders_to_create = [
+    ...spot_long_orders.map((order) => buildLongOrderPlacement({
+      order,
+      current_price: options.current_price
+    })),
+    ...short_orders.map((order) => ({
+      side: "sell",
+      type: "limit",
+      price: order.price,
+      quantity: order.quantity
+    }))
+  ];
+  const default_margin_orders_to_create = margin_long_orders.map((order) => buildLongOrderPlacement({
+    order,
+    current_price: options.current_price
+  }));
+  const spot_orders_to_create = options.placement_overrides?.spot || default_spot_orders_to_create;
+  const margin_orders_to_create = options.placement_overrides?.margin || default_margin_orders_to_create;
+  const borrow_delta = roundNumber2(Math.max(0, options.borrow_amount - options.snapshot.borrowed_quote_amount));
+  const spot_long_notional = sumNotional(spot_long_orders);
+  const transfer_to_spot_amount = roundNumber2(Math.max(0, spot_long_notional - options.snapshot.spot_quote_free));
+  const short_quantity = sumQuantity(short_orders);
+  const transfer_base_to_spot_amount = roundNumber2(Math.max(0, short_quantity - options.snapshot.spot_base_free));
+  return {
+    borrow_amount: options.borrow_amount,
+    borrow_delta,
+    transfer_to_spot_amount,
+    transfer_to_spot_asset: getQuoteAsset(options.symbol),
+    transfer_base_to_spot_amount,
+    orders_to_cancel: {
+      spot: options.snapshot.spot_orders,
+      margin: options.snapshot.margin_orders
+    },
+    orders_to_create: {
+      spot: spot_orders_to_create,
+      margin: margin_orders_to_create
+    },
+    normalized: {
+      spot: normalizeOrders(spot_orders_to_create),
+      margin: normalizeOrders(margin_orders_to_create)
+    }
+  };
+}
+function compareSpotMarginHedgeOrders(options) {
+  const actualSpot = normalizeOrders(options.spot_orders);
+  const actualMargin = normalizeOrders(options.margin_orders);
+  const spotDiff = buildDiff({
+    expected: options.plan.normalized.spot,
+    actual: actualSpot
+  });
+  const marginDiff = buildDiff({
+    expected: options.plan.normalized.margin,
+    actual: actualMargin
+  });
+  return {
+    matches: spotDiff.missing.length === 0 && spotDiff.extra.length === 0 && marginDiff.missing.length === 0 && marginDiff.extra.length === 0,
+    spot: {
+      expected: options.plan.normalized.spot,
+      actual: actualSpot,
+      missing: spotDiff.missing,
+      extra: spotDiff.extra
+    },
+    margin: {
+      expected: options.plan.normalized.margin,
+      actual: actualMargin,
+      missing: marginDiff.missing,
+      extra: marginDiff.extra
+    }
+  };
+}
+
+// src/exchanges/binance/index.ts
 var CONSTANTS = {
   SPOT_TO_FIAT: "MAIN_C2C",
   SPOT_TO_USDT_FUTURE: "MAIN_UMFUTURE",
@@ -72828,12 +73226,20 @@ async function getCrossMarginAccountDetails(client) {
 async function cancelMarginOrders(client, symbol, isIsolated = false, orders) {
   try {
     if (orders && orders.length > 0) {
-      const cancelPromises = orders.map((order) => client.marginAccountCancelOrder({
-        symbol,
-        orderId: order.orderId,
-        origClientOrderId: order.origClientOrderId,
-        isIsolated: isIsolated ? "TRUE" : "FALSE"
-      }));
+      const cancelPromises = orders.map((order) => {
+        const payload = {
+          symbol,
+          isIsolated: isIsolated ? "TRUE" : "FALSE"
+        };
+        if (order.orderId !== undefined) {
+          payload.orderId = order.orderId;
+        }
+        const origClientOrderId = order.origClientOrderId ?? order.clientOrderId;
+        if (origClientOrderId !== undefined) {
+          payload.origClientOrderId = origClientOrderId;
+        }
+        return client.marginAccountCancelOrder(payload);
+      });
       return await Promise.all(cancelPromises);
     } else {
       return await client.marginAccountCancelOpenOrders({
@@ -73088,7 +73494,7 @@ async function placeStopOrder(client, payload) {
       });
     }
   }
-  const spread = 1.00005;
+  const spread = payload.stop > 30000 ? 1.00005 : 1.0002;
   const order = {
     kind: payload.kind,
     side: payload.kind === "long" ? "sell" : "buy",
@@ -73495,6 +73901,16 @@ async function getAllOpenOrders(payload) {
   const response = await client.getAllOpenOrders();
   return response;
 }
+function getPrintfFormatFromStepSize(stepSize, fallback) {
+  if (stepSize === undefined || stepSize === null) {
+    return fallback;
+  }
+  const normalized = String(stepSize);
+  const [, decimalPart = ""] = normalized.split(".");
+  const trimmed = decimalPart.replace(/0+$/, "");
+  const digits = trimmed.length;
+  return `%.${digits}f`;
+}
 
 class BinanceExchange extends BaseExchange {
   main_client;
@@ -73931,6 +74347,54 @@ class BinanceExchange extends BaseExchange {
       throw error;
     }
   }
+  async getFuturesSymbolFormats(symbol) {
+    if (typeof this.client.getExchangeInfo !== "function") {
+      return {
+        price_places: "%.8f",
+        decimal_places: "%.8f"
+      };
+    }
+    try {
+      const exchange_info = await this.client.getExchangeInfo();
+      const symbol_info = exchange_info?.symbols?.find((item) => item.symbol === symbol.toUpperCase());
+      const price_filter = symbol_info?.filters?.find((filter) => filter.filterType === "PRICE_FILTER");
+      const lot_size_filter = symbol_info?.filters?.find((filter) => filter.filterType === "LOT_SIZE");
+      return {
+        price_places: getPrintfFormatFromStepSize(price_filter?.tickSize, "%.8f"),
+        decimal_places: getPrintfFormatFromStepSize(lot_size_filter?.stepSize, "%.8f")
+      };
+    } catch (error) {
+      console.error("Error fetching futures symbol formats:", error);
+      return {
+        price_places: "%.8f",
+        decimal_places: "%.8f"
+      };
+    }
+  }
+  async getSpotSymbolFormats(symbol) {
+    if (!this.main_client || typeof this.main_client.getExchangeInfo !== "function") {
+      return {
+        price_places: "%.8f",
+        decimal_places: "%.8f"
+      };
+    }
+    try {
+      const exchange_info = await this.main_client.getExchangeInfo();
+      const symbol_info = exchange_info?.symbols?.find((item) => item.symbol === symbol.toUpperCase());
+      const price_filter = symbol_info?.filters?.find((filter) => filter.filterType === "PRICE_FILTER");
+      const lot_size_filter = symbol_info?.filters?.find((filter) => filter.filterType === "LOT_SIZE");
+      return {
+        price_places: getPrintfFormatFromStepSize(price_filter?.tickSize, "%.8f"),
+        decimal_places: getPrintfFormatFromStepSize(lot_size_filter?.stepSize, "%.8f")
+      };
+    } catch (error) {
+      console.error("Error fetching spot symbol formats:", error);
+      return {
+        price_places: "%.8f",
+        decimal_places: "%.8f"
+      };
+    }
+  }
   async createMarginLimitOrders(payload) {
     if (!this.main_client) {
       throw new Error("Main client not available for margin trading");
@@ -73961,6 +74425,317 @@ class BinanceExchange extends BaseExchange {
     }
     return await getMarginOpenOrders(this.main_client, symbol, isIsolated);
   }
+  async getFuturesReplaySnapshot(payload) {
+    const symbol = payload.symbol.toUpperCase();
+    const [open_orders, position_info, current_price] = await Promise.all([
+      this.getOpenOrders({ symbol }),
+      this.getPositionInfo(symbol),
+      this.getCurrentPrice(symbol)
+    ]);
+    return buildFuturesReplaySnapshot({
+      symbol,
+      kind: payload.kind,
+      current_price,
+      position: {
+        size: position_info[payload.kind]?.size || 0
+      },
+      open_orders
+    });
+  }
+  async previewFuturesReplay(payload) {
+    const snapshot = payload.snapshot ? {
+      ...payload.snapshot,
+      current_price: payload.snapshot.current_price ?? await this.getCurrentPrice(payload.symbol)
+    } : await this.getFuturesReplaySnapshot({
+      symbol: payload.symbol,
+      kind: payload.kind
+    });
+    const shouldInferEntryOrders = !payload.entry_orders || payload.entry_orders.length === 0;
+    const shouldInferStopOrders = !payload.stop_orders || payload.stop_orders.length === 0;
+    const shouldInferTakeProfitOrders = !payload.take_profit_orders || payload.take_profit_orders.length === 0;
+    const inferred_input = shouldInferEntryOrders || shouldInferStopOrders || shouldInferTakeProfitOrders ? inferFuturesReplayInputFromLiveOrders({
+      symbol: payload.symbol,
+      kind: payload.kind,
+      current_price: snapshot.current_price,
+      position: snapshot.position,
+      open_orders: snapshot.open_orders
+    }) : undefined;
+    const explicit_input = normalizeFuturesReplayInput({
+      kind: payload.kind,
+      entry_orders: payload.entry_orders || [],
+      stop_orders: payload.stop_orders || [],
+      take_profit_orders: payload.take_profit_orders || []
+    });
+    const entry_orders = shouldInferEntryOrders ? inferred_input?.entry_orders || [] : explicit_input.entry_orders;
+    const stop_orders = shouldInferStopOrders ? inferred_input?.stop_orders || [] : explicit_input.stop_orders;
+    const take_profit_orders = shouldInferTakeProfitOrders ? inferred_input?.take_profit_orders || [] : explicit_input.take_profit_orders;
+    const requested_input = {
+      symbol: payload.symbol,
+      kind: payload.kind,
+      entry_orders,
+      stop_orders,
+      take_profit_orders
+    };
+    const plan = buildFuturesReplayPlan({
+      ...requested_input,
+      snapshot
+    });
+    const comparison = compareFuturesReplayOrders({
+      ...requested_input,
+      snapshot
+    });
+    return {
+      snapshot,
+      inferred_input,
+      requested_input,
+      plan,
+      comparison
+    };
+  }
+  async placeFuturesReplay(payload) {
+    const preview = await this.previewFuturesReplay(payload);
+    if (!payload.place) {
+      return preview;
+    }
+    const symbol = payload.symbol.toUpperCase();
+    await cancelAllOrders(this.client, symbol, {
+      kind: payload.kind
+    });
+    const refreshed_snapshot = await this.getFuturesReplaySnapshot({
+      symbol,
+      kind: payload.kind
+    });
+    const execution_plan = buildFuturesReplayPlan({
+      symbol,
+      kind: payload.kind,
+      entry_orders: preview.requested_input.entry_orders,
+      stop_orders: preview.requested_input.stop_orders,
+      take_profit_orders: preview.requested_input.take_profit_orders,
+      snapshot: refreshed_snapshot
+    });
+    const { price_places, decimal_places } = await this.getFuturesSymbolFormats(symbol);
+    const entry_orders = execution_plan.orders_to_create.entry.map((order) => ({
+      ...order,
+      side: payload.kind === "long" ? "buy" : "sell",
+      kind: payload.kind
+    }));
+    const stop_orders = execution_plan.orders_to_create.stop.map((order) => ({
+      ...order,
+      side: payload.kind === "long" ? "sell" : "buy",
+      kind: payload.kind,
+      type: order.type || "STOP"
+    }));
+    const take_profit_orders = execution_plan.orders_to_create.take_profit.map((order) => ({
+      ...order,
+      side: payload.kind === "long" ? "sell" : "buy",
+      kind: payload.kind,
+      ...order.stop ? { type: order.type || "TAKE_PROFIT" } : {}
+    }));
+    const execution = entry_orders.length > 0 || stop_orders.length > 0 || take_profit_orders.length > 0 ? await createLimitPurchaseOrdersParallel(this.client, symbol, price_places, decimal_places, [...entry_orders, ...stop_orders, ...take_profit_orders]) : [];
+    return {
+      ...preview,
+      execution_plan,
+      refreshed_snapshot,
+      execution
+    };
+  }
+  async placeFuturesExactTrade(payload) {
+    return await this.placeFuturesReplay(payload);
+  }
+  async getSpotMarginHedgeSnapshot(payload) {
+    if (!this.main_client) {
+      throw new Error("Main client not available for spot and margin trading");
+    }
+    if (payload.margin_type !== "isolated") {
+      throw new Error(`Unsupported margin type: ${payload.margin_type}. Only isolated is supported for replay right now.`);
+    }
+    const symbol = payload.symbol.toUpperCase();
+    const quoteAssets = ["USDT", "USDC", "BUSD", "BTC", "ETH"];
+    const quoteAsset = quoteAssets.find((asset) => symbol.endsWith(asset)) || symbol.slice(-4);
+    const baseAsset = symbol.slice(0, symbol.length - quoteAsset.length);
+    const [spot_orders, margin_orders, spot_balances, isolated_margin_position] = await Promise.all([
+      this.getSpotOpenOrders(symbol),
+      this.getMarginOpenOrders(symbol, true),
+      this.getSpotBalances([baseAsset, quoteAsset]),
+      this.getIsolatedMarginPosition(symbol)
+    ]);
+    const current_price = await this.getSpotCurrentPrice(symbol);
+    const spot_quote_balance = spot_balances.find((balance) => balance.asset.toUpperCase() === quoteAsset);
+    const spot_base_balance = spot_balances.find((balance) => balance.asset.toUpperCase() === baseAsset);
+    const isolated_asset = isolated_margin_position?.assets?.[0];
+    const borrowed_quote_amount = parseFloat(isolated_asset?.quoteAsset?.borrowed?.toString?.() || "0");
+    return {
+      symbol,
+      margin_type: payload.margin_type,
+      quote_asset: quoteAsset,
+      base_asset: baseAsset,
+      borrowed_quote_amount,
+      spot_quote_free: parseFloat(spot_quote_balance?.free?.toString?.() || "0"),
+      spot_base_free: parseFloat(spot_base_balance?.free?.toString?.() || "0"),
+      spot_orders,
+      margin_orders,
+      current_price,
+      spot_balances,
+      isolated_margin_position
+    };
+  }
+  async previewSpotMarginHedge(payload) {
+    const snapshot = payload.snapshot ? {
+      ...payload.snapshot,
+      current_price: payload.snapshot.current_price ?? await this.getSpotCurrentPrice(payload.symbol)
+    } : await this.getSpotMarginHedgeSnapshot({
+      symbol: payload.symbol,
+      margin_type: payload.margin_type
+    });
+    const shouldInferLongOrders = !payload.long_orders || payload.long_orders.length === 0;
+    const shouldInferShortOrders = !payload.short_orders || payload.short_orders.length === 0;
+    const inferred_input = shouldInferLongOrders || shouldInferShortOrders ? inferSpotMarginHedgeInputFromLiveOrders({
+      symbol: payload.symbol,
+      margin_type: payload.margin_type,
+      spot_orders: snapshot.spot_orders,
+      margin_orders: snapshot.margin_orders
+    }) : undefined;
+    const long_orders = shouldInferLongOrders ? inferred_input?.long_orders || [] : payload.long_orders || [];
+    const short_orders = shouldInferShortOrders ? inferred_input?.short_orders || [] : payload.short_orders || [];
+    const borrow_amount = payload.borrow_amount ?? (long_orders.length > 0 ? sumNotional(long_orders) : inferred_input?.borrow_amount ?? 0);
+    const requested_input = {
+      borrow_amount,
+      symbol: payload.symbol,
+      margin_type: payload.margin_type,
+      long_orders,
+      short_orders,
+      current_price: snapshot.current_price,
+      max_spot_buy_orders: payload.max_spot_buy_orders,
+      placement_overrides: inferred_input?.placement_overrides
+    };
+    const plan = buildSpotMarginHedgePlan({
+      ...requested_input,
+      snapshot
+    });
+    const comparison = compareSpotMarginHedgeOrders({
+      plan,
+      spot_orders: snapshot.spot_orders,
+      margin_orders: snapshot.margin_orders
+    });
+    return {
+      snapshot,
+      inferred_input,
+      requested_input,
+      plan,
+      comparison
+    };
+  }
+  async placeSpotMarginHedge(payload) {
+    const preview = await this.previewSpotMarginHedge(payload);
+    if (!payload.place) {
+      return preview;
+    }
+    if (!this.main_client) {
+      throw new Error("Main client not available for spot and margin trading");
+    }
+    if (payload.margin_type !== "isolated") {
+      throw new Error(`Unsupported margin type: ${payload.margin_type}. Only isolated placement is supported right now.`);
+    }
+    const symbol = payload.symbol.toUpperCase();
+    const quoteAssets = ["USDT", "USDC", "BUSD", "BTC", "ETH"];
+    const quote_asset = quoteAssets.find((asset) => symbol.endsWith(asset)) || symbol.slice(-4);
+    const base_asset = symbol.slice(0, symbol.length - quote_asset.length);
+    const requested_input = preview.requested_input;
+    if (preview.snapshot.spot_orders.length > 0) {
+      await this.cancelSpotOrders(symbol, preview.snapshot.spot_orders.map((order) => ({
+        orderId: order.orderId || order.order_id || order.id,
+        origClientOrderId: order.origClientOrderId
+      })));
+    }
+    if (preview.snapshot.margin_orders.length > 0) {
+      await this.cancelMarginOrders(symbol, true, preview.snapshot.margin_orders.map((order) => ({
+        orderId: order.orderId || order.order_id || order.id,
+        origClientOrderId: order.origClientOrderId
+      })));
+    }
+    const refreshed_snapshot = await this.getSpotMarginHedgeSnapshot({
+      symbol,
+      margin_type: payload.margin_type
+    });
+    const symbol_formats = await this.getSpotSymbolFormats(symbol);
+    const execution_plan = buildSpotMarginHedgePlan({
+      borrow_amount: requested_input.borrow_amount,
+      symbol: requested_input.symbol,
+      margin_type: requested_input.margin_type,
+      long_orders: requested_input.long_orders,
+      short_orders: requested_input.short_orders,
+      current_price: refreshed_snapshot.current_price,
+      max_spot_buy_orders: requested_input.max_spot_buy_orders,
+      snapshot: refreshed_snapshot
+    });
+    let borrow_result = null;
+    if (execution_plan.borrow_delta > 0) {
+      borrow_result = await this.main_client.submitMarginAccountBorrowRepay({
+        asset: quote_asset,
+        amount: execution_plan.borrow_delta,
+        isIsolated: "TRUE",
+        symbol,
+        type: "BORROW"
+      });
+    }
+    let quote_transfer_result = null;
+    if (execution_plan.transfer_to_spot_amount > 0) {
+      quote_transfer_result = await this.main_client.isolatedMarginAccountTransfer({
+        asset: quote_asset,
+        amount: execution_plan.transfer_to_spot_amount,
+        symbol,
+        transFrom: "ISOLATED_MARGIN",
+        transTo: "SPOT"
+      });
+    }
+    let base_transfer_result = null;
+    if (execution_plan.transfer_base_to_spot_amount > 0) {
+      base_transfer_result = await this.main_client.isolatedMarginAccountTransfer({
+        asset: base_asset,
+        amount: execution_plan.transfer_base_to_spot_amount,
+        symbol,
+        transFrom: "ISOLATED_MARGIN",
+        transTo: "SPOT"
+      });
+    }
+    const spot_result = execution_plan.orders_to_create.spot.length > 0 ? await this.createSpotLimitOrders({
+      symbol,
+      orders: execution_plan.orders_to_create.spot,
+      price_places: symbol_formats.price_places,
+      decimal_places: symbol_formats.decimal_places
+    }) : [];
+    const margin_result = execution_plan.orders_to_create.margin.length > 0 ? await this.createMarginLimitOrders({
+      symbol,
+      orders: execution_plan.orders_to_create.margin,
+      isIsolated: true,
+      price_places: symbol_formats.price_places,
+      decimal_places: symbol_formats.decimal_places
+    }) : [];
+    return {
+      ...preview,
+      execution_plan,
+      refreshed_snapshot,
+      execution: {
+        borrow: borrow_result ? {
+          asset: quote_asset,
+          amount: execution_plan.borrow_delta,
+          response: borrow_result
+        } : null,
+        quote_transfer: quote_transfer_result ? {
+          asset: quote_asset,
+          amount: execution_plan.transfer_to_spot_amount,
+          response: quote_transfer_result
+        } : null,
+        base_transfer: base_transfer_result ? {
+          asset: base_asset,
+          amount: execution_plan.transfer_base_to_spot_amount,
+          response: base_transfer_result
+        } : null,
+        spot_orders: spot_result,
+        margin_orders: margin_result
+      }
+    };
+  }
   async getLastUserTrade(payload) {
     return await getLastUserTrade(this.client, payload.symbol);
   }