perp-cli 0.12.17 → 0.14.1

package/dist/exchanges/index.d.ts

@@ -10,3 +10,9 @@ export { LighterAdapter } from "./lighter.js";
 export { AsterAdapter } from "./aster.js";
 export { HyperliquidSpotAdapter } from "./hyperliquid-spot.js";
 export { LighterSpotAdapter } from "./lighter-spot.js";
+export { getVenue, listVenues, listVenuesWithRole, resolveVenueId, tryResolveVenueId, parseVenueRef, networkConfig, requireCapabilities, fundingBasisOf, settlementIntervalOf, isLegacyVenue, isVenueId, READ_ONLY_CREDENTIALS, } from "./venue.js";
+export type { VenueDefinition, VenueCapabilities, VenueCreateContext, VenueCredentials, VenueNetworkConfig, VenuePublicData, VenueRole, VenueRef, RateLimitPolicy, MasterKeyKind, AgentKeyKind, } from "./venue.js";
+export type { VenueId, LegacyVenueId, Network, FundingRateBasis, VenueMarket, VenueFundingRate, TimeInForce, OrderRequest, OrderResult } from "./venue-types.js";
+export { ensureVenuesRegistered, ALL_VENUES } from "./venues/index.js";
+export { isTradingV2, validateOrderRequest, validateLegacyTif } from "./trading-v2.js";
+export type { TradingV2 } from "./trading-v2.js";

package/dist/exchanges/index.js

@@ -9,3 +9,7 @@ export { LighterAdapter } from "./lighter.js";
 export { AsterAdapter } from "./aster.js";
 export { HyperliquidSpotAdapter } from "./hyperliquid-spot.js";
 export { LighterSpotAdapter } from "./lighter-spot.js";
+// Venue abstraction (docs/DESIGN-venue-abstraction.md §10)
+export { getVenue, listVenues, listVenuesWithRole, resolveVenueId, tryResolveVenueId, parseVenueRef, networkConfig, requireCapabilities, fundingBasisOf, settlementIntervalOf, isLegacyVenue, isVenueId, READ_ONLY_CREDENTIALS, } from "./venue.js";
+export { ensureVenuesRegistered, ALL_VENUES } from "./venues/index.js";
+export { isTradingV2, validateOrderRequest, validateLegacyTif } from "./trading-v2.js";

package/dist/exchanges/interface.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedSlippage } from "./slippage.js";
 /**
  * Common exchange interface for multi-DEX CLI support.
  * All exchange adapters (Pacifica, Hyperliquid, Lighter) implement this.
@@ -5,24 +6,51 @@
 export interface ExchangeMarketInfo {
     symbol: string;
     markPrice: string;
-    indexPrice: string;
+    /** null = venue does not publish an index/oracle price for this market */
+    indexPrice: string | null;
     fundingRate: string | null;
-    volume24h: string;
-    openInterest: string;
+    /** null = venue does not publish 24h volume */
+    volume24h: string | null;
+    /** null = venue does not publish open interest (never "0" as a stand-in) */
+    openInterest: string | null;
     maxLeverage: number;
-    sizeDecimals?: number;
-    stepSize?: string;
-    fundingHours?: number;
+    /** quantity precision (e.g. 0 = integers only, 2 = 0.01); null = unknown */
+    sizeDecimals: number | null;
+    /** lot step size (e.g. "1", "0.1", "0.001"); null = unknown */
+    stepSize: string | null;
+    /** hours one quoted fundingRate covers; null = use the venue definition's fundingRateBasis */
+    fundingHours: number | null;
+    /**
+     * Notional-tiered leverage caps, ascending by `lowerBound` (USD notional).
+     * `maxLeverage` above is the TOP tier — the cap falls as size grows, so a
+     * pre-trade check that uses it alone passes orders the venue will reject.
+     * Resolve with `maxLeverageForNotional()`. null when the venue does not
+     * publish tiers (then `maxLeverage` applies at every size).
+     */
+    marginTiers: Array<{
+        lowerBound: number;
+        maxLeverage: number;
+    }> | null;
 }
+/**
+ * Effective max leverage for an order of `notional` USD.
+ *
+ * A venue that publishes no tiers (`marginTiers === null`) has one flat cap,
+ * `maxLeverage`, at every size — that is the venue's definition, not a fallback.
+ */
+export declare function maxLeverageForNotional(market: ExchangeMarketInfo, notional: number): number;
 export interface ExchangePosition {
     symbol: string;
     side: "long" | "short";
     size: string;
     entryPrice: string;
     markPrice: string;
-    liquidationPrice: string;
+    /** null = venue does not report a liquidation price */
+    liquidationPrice: string | null;
     unrealizedPnl: string;
     leverage: number;
+    /** Margin mode of the position, set only by adapters whose venue reports it per position. */
+    marginMode?: "cross" | "isolated";
 }
 export interface ExchangeOrder {
     orderId: string;
@@ -33,6 +61,8 @@ export interface ExchangeOrder {
     filled: string;
     status: string;
     type: string;
+    /** Trigger (stop) price of a stop / TP / SL order; null for plain orders or when the venue does not report it. */
+    triggerPrice: string | null;
 }
 export interface ExchangeBalance {
     equity: string;
@@ -60,7 +90,8 @@ export interface ExchangeKline {
     low: string;
     close: string;
     volume: string;
-    trades: number;
+    /** null = venue does not publish a trade count for the candle */
+    trades: number | null;
 }
 export interface ExchangeAdapter {
     readonly name: string;
@@ -87,8 +118,13 @@ export interface ExchangeAdapter {
     getOrderHistory(limit?: number): Promise<ExchangeOrder[]>;
     getTradeHistory(limit?: number): Promise<ExchangeTrade[]>;
     getFundingPayments(limit?: number): Promise<ExchangeFundingPayment[]>;
-    marketOrder(symbol: string, side: "buy" | "sell", size: string, opts?: {
-        reduceOnly?: boolean;
+    /**
+     * Market order = IOC within the resolved slippage bound (design §13.2). `opts` is
+     * required so every caller states reduceOnly and passes resolveSlippage() output.
+     */
+    marketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
+        reduceOnly: boolean;
+        slippage: ResolvedSlippage;
     }): Promise<unknown>;
     limitOrder(symbol: string, side: "buy" | "sell", price: string, size: string, opts?: {
         reduceOnly?: boolean;
@@ -98,8 +134,25 @@ export interface ExchangeAdapter {
     cancelOrder(symbol: string, orderId: string): Promise<unknown>;
     cancelAllOrders(symbol?: string): Promise<unknown>;
     setLeverage(symbol: string, leverage: number, marginMode?: "cross" | "isolated"): Promise<unknown>;
+    /**
+     * triggerType selects the trigger price source where the venue supports it
+     * (currently Pacifica: "mark" | "last" | "mid"). Adapters that don't support
+     * a configurable trigger source ignore the field and use their venue default.
+     * `slippage` (resolveSlippage() output) bounds the execution price of a market
+     * trigger on venues that send it as a protection-priced limit once triggered
+     * (Lighter, Arcus: required there for a market trigger — adapters never read
+     * settings, design §13.10 #1); venue-native market triggers ignore it.
+     * `kind` ("tp" | "sl") states the protective intent explicitly: venues with distinct
+     * take-profit / stop-loss trigger types (Aster, Lighter) send that type as given — no
+     * price-based classification — and a trigger already crossed is left for the venue to
+     * reject. Omitted (plain `trade stop`): the adapter classifies from the trigger vs its
+     * reference price. Venues with a single trigger type ignore it.
+     */
     stopOrder(symbol: string, side: "buy" | "sell", size: string, triggerPrice: string, opts?: {
         limitPrice?: string;
         reduceOnly?: boolean;
+        triggerType?: "mark" | "last" | "mid";
+        slippage?: ResolvedSlippage;
+        kind?: "tp" | "sl";
     }): Promise<unknown>;
 }

package/dist/exchanges/interface.js

@@ -1,5 +1,20 @@
 /**
- * Common exchange interface for multi-DEX CLI support.
- * All exchange adapters (Pacifica, Hyperliquid, Lighter) implement this.
+ * Effective max leverage for an order of `notional` USD.
+ *
+ * A venue that publishes no tiers (`marginTiers === null`) has one flat cap,
+ * `maxLeverage`, at every size — that is the venue's definition, not a fallback.
  */
-export {};
+export function maxLeverageForNotional(market, notional) {
+    if (!Number.isFinite(notional)) {
+        throw new Error(`maxLeverageForNotional: notional must be finite (got ${notional})`);
+    }
+    const tiers = market.marginTiers;
+    if (tiers === null || tiers.length === 0)
+        return market.maxLeverage;
+    let effective = market.maxLeverage;
+    for (const t of tiers) {
+        if (notional >= t.lowerBound)
+            effective = t.maxLeverage;
+    }
+    return effective;
+}

package/dist/exchanges/ioc-outcome.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Venue-final IOC / market order outcome (design `docs/DESIGN-venue-abstraction.md` §13.10 #4).
+ *
+ * An adapter whose market / IOC responses report the order's FINAL filled size (nothing
+ * of the order can still execute) implements `iocOutcomeOf(raw)` on the RAW result its
+ * legacy `marketOrder` / `limitOrder(tif IOC)` / `spotMarketOrder` returned:
+ *  - returns `{ filledSize, final: true }` only when `raw` is such a response AND the venue
+ *    reported the final filled size of THAT order (e.g. HL `statuses[0].filled.totalSz`,
+ *    Lighter tx `event_info` status "filled" or accountOrders `filled_base_amount`, Aster `executedQty` with a terminal status);
+ *    `filledSize` is a plain decimal string in base units, "0" = definitely nothing filled;
+ *  - returns `null` for anything else (unrecognized shape, resting / open order, no fill
+ *    report, not final) — the caller then measures the fill (position / balance delta).
+ * It never throws and never guesses: a missing report is `null`, never "0".
+ *
+ * Consumers (`placePerpVerified`, `closePerpVerified`, `spotMarketFill`) still cross-check
+ * the reported fill against a measured delta. Adapters without the method are measured as
+ * before (`isIocOutcomeCapable` handles absence).
+ */
+export interface IocOutcome {
+    /** Final filled size in base units (plain decimal string, "0" = nothing filled). */
+    filledSize: string;
+    final: true;
+}
+export interface IocOutcomeCapable {
+    iocOutcomeOf(raw: unknown): IocOutcome | null;
+}
+export declare function isIocOutcomeCapable(a: unknown): a is IocOutcomeCapable;
+/**
+ * Tolerance for comparing a venue-final fill with the order size or a measured delta.
+ * Never derived from the decimals of the strings ("5" vs "4" would give a 1-lot tolerance
+ * and call a partial fill complete):
+ *  - market `stepSize` known (> 0) → half a lot: lot multiples differ by at least one lot,
+ *    so anything below half a lot is representation noise;
+ *  - unknown → float-noise epsilon max(size, fill) × 1e-9.
+ */
+export declare function iocLotTolerance(size: string, filledSize: string, stepSize?: string | number | null): number;
+/**
+ * The average FILL price the venue reported in a raw order result (plain positive decimal
+ * string), or null when it reports none. Read only from fill fields — Hyperliquid
+ * `response.data.statuses[0].filled.avgPx`; `avgPrice` of an Aster order object or of a
+ * TradingV2 OrderResult — and never from the order's own `price` (the limit / slippage
+ * protection price that was SENT, which is not where it filled).
+ */
+export declare function reportedAvgFillPrice(raw: unknown): string | null;

package/dist/exchanges/ioc-outcome.js

@@ -0,0 +1,57 @@
+/**
+ * Venue-final IOC / market order outcome (design `docs/DESIGN-venue-abstraction.md` §13.10 #4).
+ *
+ * An adapter whose market / IOC responses report the order's FINAL filled size (nothing
+ * of the order can still execute) implements `iocOutcomeOf(raw)` on the RAW result its
+ * legacy `marketOrder` / `limitOrder(tif IOC)` / `spotMarketOrder` returned:
+ *  - returns `{ filledSize, final: true }` only when `raw` is such a response AND the venue
+ *    reported the final filled size of THAT order (e.g. HL `statuses[0].filled.totalSz`,
+ *    Lighter tx `event_info` status "filled" or accountOrders `filled_base_amount`, Aster `executedQty` with a terminal status);
+ *    `filledSize` is a plain decimal string in base units, "0" = definitely nothing filled;
+ *  - returns `null` for anything else (unrecognized shape, resting / open order, no fill
+ *    report, not final) — the caller then measures the fill (position / balance delta).
+ * It never throws and never guesses: a missing report is `null`, never "0".
+ *
+ * Consumers (`placePerpVerified`, `closePerpVerified`, `spotMarketFill`) still cross-check
+ * the reported fill against a measured delta. Adapters without the method are measured as
+ * before (`isIocOutcomeCapable` handles absence).
+ */
+export function isIocOutcomeCapable(a) {
+    return a !== null && typeof a === "object" && typeof a.iocOutcomeOf === "function";
+}
+/**
+ * Tolerance for comparing a venue-final fill with the order size or a measured delta.
+ * Never derived from the decimals of the strings ("5" vs "4" would give a 1-lot tolerance
+ * and call a partial fill complete):
+ *  - market `stepSize` known (> 0) → half a lot: lot multiples differ by at least one lot,
+ *    so anything below half a lot is representation noise;
+ *  - unknown → float-noise epsilon max(size, fill) × 1e-9.
+ */
+export function iocLotTolerance(size, filledSize, stepSize) {
+    const step = stepSize === undefined || stepSize === null ? NaN : Number(stepSize);
+    if (Number.isFinite(step) && step > 0)
+        return step / 2;
+    const mag = Math.max(Math.abs(Number(size)), Math.abs(Number(filledSize)));
+    return (Number.isFinite(mag) ? mag : 0) * 1e-9;
+}
+/**
+ * The average FILL price the venue reported in a raw order result (plain positive decimal
+ * string), or null when it reports none. Read only from fill fields — Hyperliquid
+ * `response.data.statuses[0].filled.avgPx`; `avgPrice` of an Aster order object or of a
+ * TradingV2 OrderResult — and never from the order's own `price` (the limit / slippage
+ * protection price that was SENT, which is not where it filled).
+ */
+export function reportedAvgFillPrice(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const r = raw;
+    const statuses = r.response?.data?.statuses;
+    const first = Array.isArray(statuses) ? statuses[0] : null;
+    const hl = first !== null && typeof first === "object" ? first.filled?.avgPx : undefined;
+    for (const v of [r.avgPrice, hl]) {
+        const s = typeof v === "number" && Number.isFinite(v) ? String(v) : v;
+        if (typeof s === "string" && /^\d+(\.\d+)?$/.test(s) && Number(s) > 0)
+            return s;
+    }
+    return null;
+}

package/dist/exchanges/legacy-trading-v2.d.ts

@@ -0,0 +1,39 @@
+/**
+ * TradingV2 for the four pre-existing venues (pacifica, hyperliquid, lighter /
+ * lighter-rh, aster) — design §13.7, §13.10 #8.
+ *
+ * Composition, not modification: the legacy ExchangeAdapter methods keep returning
+ * their raw venue responses (in-process contract for smart-order, perp-order,
+ * plan-executor, grid). This wrapper calls the same adapter methods (same send
+ * path) and normalizes the raw response into an OrderResult + execution record.
+ * The raw response is kept verbatim in `venueRaw`.
+ *
+ * Status rules (SSOT Rule #2): a status / fill is reported only when the venue
+ * response proves it; otherwise "accepted" with finality "pending".
+ */
+import type { ExchangeAdapter } from "./interface.js";
+import type { ResolvedSlippage } from "./slippage.js";
+import { type TradingV2 } from "./trading-v2.js";
+import { type Network, type OrderResult } from "./venue-types.js";
+export declare function tradingV2Of(adapter: ExchangeAdapter, network: Network): TradingV2;
+export declare function toTradingV2(adapter: ExchangeAdapter, network: Network): TradingV2;
+/** One reduce-only protective trigger (TP or SL) of a separateOrders venue (design §13.5). */
+export interface TpSlLeg {
+    symbol: string;
+    /** Side that closes the protected position (sell closes a long). */
+    closeSide: "buy" | "sell";
+    /** Positive size (the verified fill or the live position) — never "0". */
+    size: string;
+    trigger: string;
+    kind: "tp" | "sl";
+    /** Limit price once triggered; null = market trigger. */
+    limitPrice: string | null;
+    /** Resolved bound for protection-priced market triggers (Lighter); native triggers ignore it. */
+    slippage: ResolvedSlippage;
+}
+/**
+ * Place one reduce-only TP/SL trigger on a separateOrders venue (hyperliquid, lighter /
+ * lighter-rh, aster) and normalize the result. HL tags the trigger "tp"/"sl" natively;
+ * Lighter / Aster receive the leg kind explicitly and send take-profit / stop-loss as given.
+ */
+export declare function placeTpSlLeg(adapter: ExchangeAdapter, network: Network, leg: TpSlLeg): Promise<OrderResult>;