perp-cli 0.12.15 → 0.14.0

package/dist/smart-order.js

@@ -16,11 +16,34 @@
  * - Saves 5-50+ bps vs raw market orders on thin books
  * - Predictable execution price
  *
+ * Order-outcome typing (design §12.3): every failure BEFORE the IOC is sent (orderbook read,
+ * empty book, unusable price), an explicit venue rejection embedded in the response, and an
+ * explicit IOC no-match (nothing filled, nothing rests) throw a definite ORDER_REJECTED
+ * (orderNotSent), so placePerpVerified does not quarantine a leg that never traded. Anything
+ * else the IOC call throws is rethrown unchanged (placePerpVerified measures it).
+ *
  * SSOT rule #2: silent fallback is forbidden. The opt-in `fallback: true` flag
  * is preserved for callers that explicitly want best-effort market substitution
  * after IOC reject, but the DEFAULT is `false` — failure must surface as a
  * thrown error, never a silent market sweep.
  */
+import { alignComputedLimitPrice } from "./bot/quote-rules.js";
+import { PerpError, orderNotSent } from "./errors.js";
+import { resolveAdapterSlippage } from "./exchanges/slippage.js";
+/**
+ * IOC "no match" signalled explicitly in the venue response (nothing filled, nothing rests):
+ * a Binance-style terminal status (Aster: EXPIRED / CANCELED / REJECTED) with executedQty 0.
+ * HL embedded errors (incl. "could not immediately match") are caught by hasOrderError.
+ */
+function isIocNoMatch(result) {
+    if (!result || typeof result !== "object")
+        return false;
+    const r = result;
+    const status = typeof r.status === "string" ? r.status.toUpperCase() : "";
+    if (!["EXPIRED", "CANCELED", "CANCELLED", "REJECTED"].includes(status))
+        return false;
+    return r.executedQty !== undefined && Number(r.executedQty) === 0;
+}
 /**
  * Infer tick size from orderbook prices.
  * Uses the minimum price increment visible in the book.
@@ -112,14 +135,25 @@ function describeOrderError(result) {
  */
 export async function smartOrder(adapter, symbol, side, size, opts = {}) {
     const { tickTolerance = 1, fallback = false, reduceOnly = false } = opts;
-    // 1. Fetch orderbook
-    const book = await adapter.getOrderbook(symbol);
+    const venue = adapter.name;
+    const what = `smart ${side} ${size} ${symbol}${reduceOnly ? " (reduce-only)" : ""}`;
+    const marketFallback = () => adapter.marketOrder(symbol, side, size, {
+        reduceOnly, slippage: opts.slippage ?? resolveAdapterSlippage(adapter, null),
+    });
+    // 1. Fetch orderbook (failure = nothing sent)
+    let book;
+    try {
+        book = await adapter.getOrderbook(symbol);
+    }
+    catch (e) {
+        throw orderNotSent(venue, `${what} (orderbook read failed)`, e);
+    }
     // 2. Validate book has liquidity on the relevant side
     const relevantSide = side === "buy" ? book.asks : book.bids;
     if (relevantSide.length === 0) {
         if (!fallback)
-            throw new Error(`No ${side === "buy" ? "asks" : "bids"} in orderbook for ${symbol}`);
-        const result = await adapter.marketOrder(symbol, side, size);
+            throw new PerpError("ORDER_REJECTED", `${venue} ${what} not sent: No ${side === "buy" ? "asks" : "bids"} in orderbook for ${symbol}`, { exchange: venue });
+        const result = await marketFallback();
         return { result, method: "market_fallback", price: "0", bestBookPrice: "0", tickSize: "0" };
     }
     // 3. Get best price and tick size
@@ -131,7 +165,11 @@ export async function smartOrder(adapter, symbol, side, size, opts = {}) {
     const limitPrice = side === "buy"
         ? bestPrice + tick * tickTolerance // 1 tick above best ask
         : bestPrice - tick * tickTolerance; // 1 tick below best bid
-    const formattedPrice = limitPrice.toFixed(decimals);
+    // Book-inferred tick; venues without a published tick (HL) are then put on their own grid (passive side).
+    const formattedPrice = await alignComputedLimitPrice(adapter, symbol, side, limitPrice.toFixed(decimals));
+    if (!(Number.isFinite(bestPrice) && bestPrice > 0 && Number(formattedPrice) > 0)) {
+        throw new PerpError("ORDER_REJECTED", `${venue} ${what} not sent: unusable limit price ${formattedPrice} (best ${bestEntry[0]}, tick ${tick})`, { exchange: venue });
+    }
     // 5. Place IOC limit order at calculated price
     try {
         const result = await adapter.limitOrder(symbol, side, formattedPrice, size, {
@@ -145,7 +183,7 @@ export async function smartOrder(adapter, symbol, side, size, opts = {}) {
         // result for a rejected order and treat the failure as success.
         if (hasOrderError(result)) {
             if (fallback) {
-                const fallbackResult = await adapter.marketOrder(symbol, side, size);
+                const fallbackResult = await marketFallback();
                 return {
                     result: fallbackResult,
                     method: "market_fallback",
@@ -154,7 +192,14 @@ export async function smartOrder(adapter, symbol, side, size, opts = {}) {
                     tickSize: tick.toFixed(decimals),
                 };
             }
-            throw new Error(`smartOrder: exchange rejected IOC limit (${describeOrderError(result)})`);
+            throw new PerpError("ORDER_REJECTED", `${venue} ${what}: exchange rejected IOC limit (${describeOrderError(result)})`, { exchange: venue });
+        }
+        if (isIocNoMatch(result)) {
+            if (fallback) {
+                const fallbackResult = await marketFallback();
+                return { result: fallbackResult, method: "market_fallback", price: formattedPrice, bestBookPrice: bestEntry[0], tickSize: tick.toFixed(decimals) };
+            }
+            throw new PerpError("ORDER_REJECTED", `${venue} ${what}: IOC limit ${formattedPrice} matched nothing (nothing rests)`, { exchange: venue });
         }
         return {
             result,
@@ -168,7 +213,7 @@ export async function smartOrder(adapter, symbol, side, size, opts = {}) {
         if (!fallback)
             throw err;
         // Fallback to raw market order for reliability
-        const result = await adapter.marketOrder(symbol, side, size);
+        const result = await marketFallback();
         return {
             result,
             method: "market_fallback",

package/dist/strategies/dca.d.ts

@@ -12,7 +12,11 @@ export interface DCAState {
     ordersPlaced: number;
     totalFilled: number;
     totalCost: number;
-    avgPrice: number;
+    /**
+     * Average fill price from the VENUE-reported average fill of every order (reportedAvgFillPrice),
+     * never the protection / limit price sent; null when any filled order reported none.
+     */
+    avgPrice: number | null;
     errors: number;
     startedAt: number;
     running: boolean;
@@ -20,6 +24,6 @@ export interface DCAState {
 export declare function runDCA(adapter: ExchangeAdapter, params: DCAParams, jobId?: string, log?: (msg: string) => void): Promise<{
     ordersPlaced: number;
     totalFilled: number;
-    avgPrice: number;
+    avgPrice: number | null;
     runtime: number;
 }>;

package/dist/strategies/dca.js

@@ -1,12 +1,22 @@
+import { symbolMatch } from "../utils.js";
+import { assertCanClosePositions } from "../exchanges/trading-v2.js";
+import { resolveAdapterSlippage } from "../exchanges/slippage.js";
 import { updateJobState } from "../jobs.js";
+import { reportedAvgFillPrice } from "../exchanges/ioc-outcome.js";
+import { filledOf } from "../bot/fill-size.js";
+import { isOutcomeUnknown } from "../bot/perp-order.js";
+import { pendingStop } from "./pending-stop.js";
+import { formatComputedPrice } from "../exchanges/precision.js";
+import { venueRateString } from "../utils/numeric.js";
 export async function runDCA(adapter, params, jobId, log = console.log) {
+    assertCanClosePositions(adapter, `DCA on ${adapter.name}`);
     const { symbol, side, amountPerOrder, intervalSec, totalOrders } = params;
     const maxRuntime = (params.maxRuntime ?? 0) * 1000;
     const state = {
         ordersPlaced: 0,
         totalFilled: 0,
         totalCost: 0,
-        avgPrice: 0,
+        avgPrice: null,
         errors: 0,
         startedAt: Date.now(),
         running: true,
@@ -20,6 +30,9 @@ export async function runDCA(adapter, params, jobId, log = console.log) {
     const shutdown = () => { state.running = false; };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
+    let everyOrderPriced = true;
+    /** Set when an order's outcome / fill is unknown: the run stops and surfaces ORDER_PENDING. */
+    let pending = null;
     try {
         while (state.running) {
             // Check if we've reached order limit
@@ -32,41 +45,58 @@ export async function runDCA(adapter, params, jobId, log = console.log) {
                 log(`[DCA] Max runtime reached. Stopping.`);
                 break;
             }
-            // Check price limit
+            // Check price limit — the order goes out only when the price is KNOWN to be within it:
+            // a failed read / missing market / non-numeric price skips this order (never sent blind).
             if (params.priceLimit) {
+                let price = null;
+                let why = "";
                 try {
                     const markets = await adapter.getMarkets();
-                    const market = markets.find(m => m.symbol.toUpperCase() === symbol.toUpperCase());
-                    if (market) {
-                        const price = parseFloat(market.markPrice);
-                        if (side === "buy" && price > params.priceLimit) {
-                            log(`[DCA] Price $${price.toFixed(2)} > limit $${params.priceLimit}. Skipping.`);
-                            await sleep(intervalSec * 1000);
-                            continue;
-                        }
-                        if (side === "sell" && price < params.priceLimit) {
-                            log(`[DCA] Price $${price.toFixed(2)} < limit $${params.priceLimit}. Skipping.`);
-                            await sleep(intervalSec * 1000);
-                            continue;
-                        }
+                    const market = markets.find(m => symbolMatch(m.symbol, symbol));
+                    if (market === undefined)
+                        why = `${symbol} not listed on ${adapter.name}`;
+                    else {
+                        const p = parseFloat(market.markPrice);
+                        if (Number.isFinite(p) && p > 0)
+                            price = p;
+                        else
+                            why = `mark price "${market.markPrice}" is not a price`;
                     }
                 }
-                catch {
-                    // non-critical, proceed with order
+                catch (e) {
+                    why = `price read failed: ${e instanceof Error ? e.message : String(e)}`;
+                }
+                const skip = price === null
+                    ? `[DCA] Price unknown (${why}) — cannot check the $${params.priceLimit} limit. Skipping this order.`
+                    : side === "buy" && price > params.priceLimit ? `[DCA] Price $${price.toFixed(2)} > limit $${params.priceLimit}. Skipping.`
+                        : side === "sell" && price < params.priceLimit ? `[DCA] Price $${price.toFixed(2)} < limit $${params.priceLimit}. Skipping.`
+                            : null;
+                if (skip !== null) {
+                    log(skip);
+                    await sleep(intervalSec * 1000);
+                    continue;
                 }
             }
             // Place market order
             try {
-                const result = await adapter.marketOrder(symbol, side, String(amountPerOrder));
+                const result = await adapter.marketOrder(symbol, side, String(amountPerOrder), { reduceOnly: false, slippage: resolveAdapterSlippage(adapter, null) });
                 state.ordersPlaced++;
-                state.totalFilled += amountPerOrder;
-                const fillPrice = Number(result?.price ?? result?.avg_price ?? result?.fill_price ?? 0);
-                if (fillPrice > 0) {
-                    state.totalCost += amountPerOrder * fillPrice;
-                    state.avgPrice = state.totalCost / state.totalFilled;
+                // Filled size: the venue-reported fill only (IOC outcome / OrderResult.filledSize) — never the size sent.
+                const filled = filledOf(adapter, result);
+                if (filled === null) {
+                    pending = pendingStop("dca", adapter, symbol, `DCA ${side} ${amountPerOrder} ${symbol} on ${adapter.name}: accepted but the venue reported no fill size`, log);
+                    break;
                 }
+                state.totalFilled = Number(venueRateString(state.totalFilled + filled, "DCA filled total")); // sum without float noise
+                // The venue-reported average fill only: the result's `price` is the protection price that was sent.
+                const fillPrice = reportedAvgFillPrice(result);
+                if (fillPrice === null)
+                    everyOrderPriced = false;
+                else
+                    state.totalCost += filled * Number(fillPrice);
+                state.avgPrice = everyOrderPriced && state.totalFilled > 0 ? Number(formatComputedPrice(state.totalCost / state.totalFilled)) : null;
                 const progress = totalOrders > 0 ? ` (${state.ordersPlaced}/${totalOrders})` : "";
-                log(`[DCA] Order #${state.ordersPlaced}${progress}: ${side} ${amountPerOrder} ${symbol}${state.avgPrice > 0 ? ` @ $${state.avgPrice.toFixed(2)} avg` : ""}`);
+                log(`[DCA] Order #${state.ordersPlaced}${progress}: ${side} ${filled} ${symbol}${fillPrice !== null ? ` @ $${fillPrice}` : " (fill price not reported)"}${state.avgPrice !== null ? `, avg $${state.avgPrice}` : ""}`);
                 // Update job state
                 if (jobId) {
                     updateJobState(jobId, {
@@ -81,8 +111,13 @@ export async function runDCA(adapter, params, jobId, log = console.log) {
                 }
             }
             catch (err) {
-                state.errors++;
                 const msg = err instanceof Error ? err.message : String(err);
+                if (isOutcomeUnknown(err)) {
+                    // Unknown outcome: never resubmitted — the run stops and the symbol is quarantined.
+                    pending = pendingStop("dca", adapter, symbol, `DCA ${side} ${amountPerOrder} ${symbol} on ${adapter.name}: outcome unknown (${msg})`, log);
+                    break;
+                }
+                state.errors++;
                 log(`[DCA] Order error: ${msg}`);
                 if (state.errors > 10 && state.errors > state.ordersPlaced) {
                     log(`[DCA] Too many errors. Stopping.`);
@@ -100,7 +135,12 @@ export async function runDCA(adapter, params, jobId, log = console.log) {
         process.removeListener("SIGTERM", shutdown);
     }
     const runtime = Math.floor((Date.now() - state.startedAt) / 1000);
-    log(`[DCA] Done. ${state.ordersPlaced} orders, ${state.totalFilled} filled, avg $${state.avgPrice.toFixed(2)}, ${state.errors} errors, ${runtime}s`);
+    log(`[DCA] Done. ${state.ordersPlaced} orders, ${state.totalFilled} filled, avg ${state.avgPrice !== null ? `$${state.avgPrice}` : "not reported by the venue"}, ${state.errors} errors, ${runtime}s`);
+    if (pending !== null) {
+        if (jobId)
+            updateJobState(jobId, { status: "error", result: { error: pending.message, ordersPlaced: state.ordersPlaced, totalFilled: state.totalFilled, avgPrice: state.avgPrice, runtime } });
+        throw pending;
+    }
     if (jobId) {
         updateJobState(jobId, {
             status: "done",

package/dist/strategies/funding-arb.d.ts

@@ -1,4 +1,4 @@
-import type { ExchangeAdapter } from "../exchanges/index.js";
+import { type ExchangeAdapter } from "../exchanges/index.js";
 export interface FundingArbParams {
     minSpread: number;
     closeSpread: number;
@@ -12,4 +12,14 @@ export interface FundingArbParams {
     rebalanceThreshold?: number;
     maxDrawdown?: number;
 }
+/**
+ * `perp strategy funding-arb` loop. With autoExecute (design §12.3):
+ *  - entry = openPerpPairVerified (long, then the short sized to the long's VERIFIED fill;
+ *    definite short failure → reduce-only rollback; unknown outcome → quarantine). A lot-size
+ *    rejection is never resubmitted blindly: the long is re-sized only when it was definitely
+ *    not placed; a rejected short is placed once at the lot-floored verified long fill;
+ *  - close / max-drawdown close = closePerpPairVerified with the venue position size strings
+ *    (reduce-only, verified, one residual close, quarantine on unknown / unhedged);
+ *  - quarantined symbols (src/bot/quarantine.ts) are never entered or closed.
+ */
 export declare function runFundingArb(adapters: Map<string, ExchangeAdapter>, params: FundingArbParams, jobId?: string, log?: (msg: string) => void): Promise<void>;