perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/trading-v2.js

@@ -0,0 +1,301 @@
+/**
+ * TradingV2 — normalized order entry for venues added under the venue
+ * abstraction (docs/DESIGN-venue-abstraction.md §3 L3, §10.7, §10.10).
+ *
+ * Method names deliberately do not overlap the legacy ExchangeAdapter trading
+ * methods, so an adapter can implement both without overloads.
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { PerpError } from "../errors.js";
+import { orderRefOf } from "./venue-types.js";
+import { requirePositive } from "./precision.js";
+export function isTradingV2(a) {
+    const r = a;
+    return !!r
+        && typeof r.placeOrder === "function"
+        && typeof r.cancelByRef === "function"
+        && typeof r.getOrderStatus === "function"
+        && typeof r.getVenueMarkets === "function";
+}
+/**
+ * Uniform "not supported" response (design §13.6, §13.10 #13): CAPABILITY_UNSUPPORTED
+ * with details { venue, feature, reason } and an alternative in `remediation`.
+ * `venue` is a venue id or display name; `feature` a short capability name
+ * ("limitOrder", "fok", "postOnly", "amend", "trading", "orderbook", ...).
+ */
+export function unsupported(venue, feature, reason, remediation) {
+    return new PerpError("CAPABILITY_UNSUPPORTED", `${venue} does not support ${feature} — ${reason}`, {
+        venue, feature, reason, remediation,
+    });
+}
+/**
+ * An adapter whose reduce-only orders are currently refused (a venue whose reduce-only wire
+ * format is not set; none today) reports why. Callers that will need a reduce-only order
+ * LATER in a flow ask first — an entry carrying --tp/--sl is refused BEFORE the entry is sent
+ * (never "entry filled, protection failed"), and a close is refused before any read. Adapters
+ * without the method have no such gate.
+ */
+export function reduceOnlyGateOf(adapter) {
+    const fn = adapter?.reduceOnlyGate;
+    if (typeof fn !== "function")
+        return null;
+    const gate = fn.call(adapter);
+    return gate instanceof PerpError ? gate : null;
+}
+/**
+ * An adapter whose STOP orders are currently refused (QFEX until stop acknowledgements can be
+ * correlated) reports why. `--tp/--sl` entries and `trade tpsl` ask first, so an entry is never
+ * sent when its protective legs would be refused. Adapters without the method have no such gate.
+ */
+export function stopOrderGateOf(adapter) {
+    const fn = adapter?.stopOrderGate;
+    if (typeof fn !== "function")
+        return null;
+    const gate = fn.call(adapter);
+    return gate instanceof PerpError ? gate : null;
+}
+/**
+ * An adapter on which UNATTENDED automation is currently refused (QFEX while its stop orders are
+ * refused) reports why. Bots, plans, TWAP, DCA, grid, funding-arb, trailing stop and background
+ * jobs ask before they start; manual commands never ask. Adapters without the method have no
+ * such gate.
+ */
+export function automationGateOf(adapter) {
+    const fn = adapter?.automationGate;
+    if (typeof fn !== "function")
+        return null;
+    const gate = fn.call(adapter);
+    return gate instanceof PerpError ? gate : null;
+}
+/**
+ * Refuse to START anything that trades unattended on a venue that cannot close or protect its
+ * positions. Bots, plans, TWAP, DCA, grid, funding-arb, trailing stop and background jobs all
+ * need a reduce-only order later (close / stop / drawdown exit): on a venue whose reduce-only
+ * orders are gated (reduceOnlyGateOf) they would open a position they cannot close, and on a
+ * venue that refuses automation (automationGateOf) they would run without a protective exit.
+ * Throws the gate before the first order.
+ */
+export function assertCanClosePositions(adapter, what) {
+    const reduceOnly = reduceOnlyGateOf(adapter);
+    if (reduceOnly !== null)
+        throw startRefusal(what, "it could open a position it cannot close", reduceOnly);
+    const automation = automationGateOf(adapter);
+    if (automation !== null)
+        throw startRefusal(what, "it would trade unattended", automation);
+}
+/** The gate's own code / details / remediation, with what was refused and why in front. */
+export function startRefusal(what, why, gate) {
+    const remediation = gate.structured.remediation;
+    return new PerpError(gate.structured.code, `${what} refused: ${why} — ${gate.message}`, {
+        ...(gate.structured.details === undefined ? {} : gate.structured.details),
+        ...(remediation === undefined ? {} : { remediation }),
+    });
+}
+/**
+ * Validate an order request against the venue's declared capabilities BEFORE
+ * anything is sent. Throws; never adjusts the request.
+ */
+export function validateOrderRequest(venue, caps, req) {
+    const isStop = req.type === "stopMarket" || req.type === "stopLimit";
+    const needsPrice = req.type === "limit" || req.type === "stopLimit";
+    const isMarketLike = req.type === "market" || req.type === "stopMarket";
+    if (needsPrice && req.price === null) {
+        throw new PerpError("INVALID_PARAMS", `${req.type} order requires a price`);
+    }
+    if (isStop && req.triggerPrice === null) {
+        throw new PerpError("INVALID_PARAMS", `${req.type} order requires a trigger price`);
+    }
+    if (!isStop && req.triggerPrice !== null) {
+        throw new PerpError("INVALID_PARAMS", `triggerPrice is only valid for stop orders`);
+    }
+    // A zero / negative / non-decimal price is never sent to the venue.
+    if (req.price !== null)
+        requirePositive(req.price, "price");
+    if (req.triggerPrice !== null)
+        requirePositive(req.triggerPrice, "triggerPrice");
+    // Callers resolve the common default (GTC, design §13.3) before building the request;
+    // a missing TIF here is a programming error, never a user-facing TIF_REQUIRED.
+    if (needsPrice && req.tif === null) {
+        throw new PerpError("INVALID_PARAMS", `${venue.displayName} ${req.type} order is missing its resolved time-in-force`);
+    }
+    if (req.tif !== null) {
+        if (isMarketLike) {
+            throw new PerpError("INVALID_PARAMS", `time-in-force is not valid for ${req.type} orders`);
+        }
+        if (!caps.timeInForce.includes(req.tif)) {
+            throw unsupported(venue.displayName, "timeInForce", `time-in-force ${req.tif} is not offered`, `Use one of: ${caps.timeInForce.join(", ")}`);
+        }
+    }
+    // A reduce-only limit order may only carry the TIFs the venue allows for it (Ondo: IOC only —
+    // a resting reduce-only order is refused there); refused before anything is sent.
+    if (req.reduceOnly && req.type === "limit" && req.tif !== null && caps.reduceOnlyTif !== null && !caps.reduceOnlyTif.includes(req.tif)) {
+        const alternative = `set a take-profit / stop-loss on the position instead: perp trade tpsl ${req.symbol} <long|short> --tp <price>${caps.tpsl !== null && caps.tpsl !== "positionLevel" ? " [--size <qty>]" : ""} -e ${venue.id}`;
+        throw unsupported(venue.displayName, "restingReduceOnly", `a reduce-only limit order can only be ${caps.reduceOnlyTif.join(" / ")} (got ${req.tif})`, `Use --tif ${caps.reduceOnlyTif.join(" | ")}, or ${alternative}`);
+    }
+    // Callers always pass resolveSlippage() output for market orders (§13.10 #1); a
+    // missing bound here is a programming error, never "send unbounded".
+    if (req.type === "market" && req.slippage === null) {
+        throw new PerpError("INVALID_PARAMS", `${venue.displayName} market order is missing its resolved slippage bound`);
+    }
+    if (req.slippage !== null && (!Number.isFinite(req.slippage.bps) || req.slippage.bps < 1 || req.slippage.bps > venue.maxSlippageBps)) {
+        throw new PerpError("INVALID_PARAMS", `slippage ${req.slippage.bps} bps is outside 1..${venue.maxSlippageBps} for ${venue.displayName}`);
+    }
+    if (caps.orderAck === "async" && req.clientOrderId === null) {
+        throw new PerpError("INVALID_PARAMS", `${venue.displayName} acknowledges orders asynchronously; a clientOrderId is required`);
+    }
+    if (req.clientOrderId !== null && !caps.clientOrderId) {
+        throw unsupported(venue.displayName, "clientOrderId", "the venue has no client order ids", "Omit the client order id");
+    }
+    if (req.tpsl !== null) {
+        if (req.tpsl.tp === null && req.tpsl.sl === null) {
+            throw new PerpError("INVALID_PARAMS", "tpsl given but neither tp nor sl is set");
+        }
+        if (caps.tpsl !== "attached" && caps.tpsl !== "batchGroup") {
+            throw unsupported(venue.displayName, "tpslAttached", "TP/SL cannot be attached to an entry order", `Place the entry, then run: perp trade tpsl -e ${venue.id}`);
+        }
+    }
+    if (isStop && caps.tpsl === "batchGroup" && !req.reduceOnly) {
+        throw unsupported(venue.displayName, "openingStop", "stop orders cannot open a position", "Stop orders on this venue must be reduce-only");
+    }
+}
+/**
+ * Common TIF aliases (design §13.3): a common name the venue lists under its own
+ * spelling, and venue spellings accepted for the common name. Only same-meaning
+ * pairs: GTC ↔ GTT (resting until cancelled / venue expiry), ALO ↔ GTX (post-only).
+ */
+const TIF_ALIASES = {
+    GTC: ["GTT"],
+    GTT: ["GTC"],
+    ALO: ["GTX"],
+    GTX: ["ALO"],
+};
+/**
+ * Resolve a CLI TIF input (common GTC/IOC/FOK/ALO or a venue alias GTT/GTX/TOB,
+ * case-insensitive) to a value the venue declares in its capabilities. Never
+ * substitutes a different meaning: FOK is never emulated (§13.3) and an
+ * unknown / unoffered value is the uniform CAPABILITY_UNSUPPORTED response.
+ */
+export function validateLegacyTif(venue, caps, tif) {
+    const upper = tif.trim().toUpperCase();
+    if (caps.timeInForce.includes(upper))
+        return upper;
+    for (const alias of TIF_ALIASES[upper] ?? []) {
+        if (caps.timeInForce.includes(alias))
+            return alias;
+    }
+    if (upper === "FOK") {
+        throw unsupported(venue.displayName, "fok", "fill-or-kill is not offered and is never emulated (a partial IOC fill cannot be undone)", `Use --tif IOC (partial fills possible) or one of: ${caps.timeInForce.join(", ")}`);
+    }
+    const feature = upper === "ALO" || upper === "GTX" ? "postOnly" : "timeInForce";
+    throw unsupported(venue.displayName, feature, `time-in-force ${tif} is not offered`, `Use one of: ${caps.timeInForce.join(", ")}`);
+}
+const FINAL_STATUSES = new Set(["filled", "rejected", "cancelled"]);
+/**
+ * Poll getOrderStatus until the order reaches a final state, is resting ("open"),
+ * or the timeout elapses. On timeout returns the last observation with
+ * finality "pending" — never guesses a fill.
+ *
+ * `untilResting`: treat "open"/"partiallyFilled" as a stopping point (limit orders).
+ * `ack`: the placement acknowledgement of an async venue. When set, an
+ * ORDER_NOT_FOUND from getOrderStatus inside this loop means "acknowledged but
+ * not yet visible on the read path" (Arcus forwards to the engine before the
+ * order store has it) and the ack itself (status "accepted") stands as the
+ * observation. Outside this loop ORDER_NOT_FOUND is never reinterpreted.
+ */
+export async function awaitOrderFinal(adapter, symbol, ref, opts) {
+    if (!(opts.timeoutMs > 0) || !(opts.pollMs > 0)) {
+        throw new PerpError("INVALID_PARAMS", "awaitOrderFinal: timeoutMs and pollMs must be positive");
+    }
+    if (opts.ack !== null && opts.ack.status !== "accepted") {
+        throw new PerpError("INVALID_PARAMS", `awaitOrderFinal: ack must have status "accepted" (got ${opts.ack.status})`);
+    }
+    const deadline = Date.now() + opts.timeoutMs;
+    let last = null;
+    for (;;) {
+        try {
+            last = await adapter.getOrderStatus(symbol, ref);
+        }
+        catch (e) {
+            if (opts.ack === null || !(e instanceof PerpError) || e.structured.code !== "ORDER_NOT_FOUND")
+                throw e;
+            last = opts.ack;
+        }
+        if (FINAL_STATUSES.has(last.status))
+            return { ...last, finality: "final" };
+        if (opts.untilResting && (last.status === "open" || last.status === "partiallyFilled")) {
+            return { ...last, finality: "final" };
+        }
+        if (Date.now() + opts.pollMs > deadline)
+            return { ...last, finality: "pending" };
+        await new Promise(r => setTimeout(r, opts.pollMs));
+    }
+}
+/** Generate a client order id: time-ordered, 20 chars max, [0-9a-z]. */
+export function newClientOrderId(prefix = "p") {
+    const t = Date.now().toString(36);
+    const r = Math.floor(Math.random() * 36 ** 6).toString(36).padStart(6, "0");
+    return `${prefix}${t}${r}`.slice(0, 20);
+}
+/**
+ * Client order id in the venue's format: Lighter-family `clientOrderIndex` is a
+ * decimal integer ≤ 2^48 − 1 (ms timestamp × 100 + 2 random digits); QFEX and Pacifica take a
+ * UUID (QFEX: the format the venue itself generates; Pacifica: "Full UUID string"); Hyperliquid a
+ * 128-bit cloid ("0x" + 32 hex); every other venue (Aster: [.A-Z:/a-z0-9_-]{1,36}) takes
+ * newClientOrderId().
+ */
+export function newVenueClientOrderId(venue) {
+    if (venue.family === "lighter")
+        return String(Date.now() * 100 + Math.floor(Math.random() * 100));
+    if (venue.family === "qfex" || venue.family === "pacifica")
+        return randomUUID();
+    if (venue.family === "hyperliquid")
+        return `0x${randomBytes(16).toString("hex")}`;
+    return newClientOrderId();
+}
+/** Finality wait after an async (orderAck "async") placement ack. */
+const ASYNC_ACK_TIMEOUT_MS = 15_000;
+const ASYNC_ACK_POLL_MS = 1_000;
+/**
+ * Place through TradingV2 and settle the outcome as far as the venue can prove it:
+ * async-ack venues are polled with awaitOrderFinal until final / resting (non-market)
+ * or ASYNC_ACK_TIMEOUT_MS. A non-final result carries a "do NOT resubmit" remediation;
+ * a failed status poll after the ack is never reported as a failed order.
+ */
+export async function placeAndConfirm(adapter, caps, req) {
+    const placed = await adapter.placeOrder(req);
+    const def = adapter.venue;
+    const listHint = `perp account orders -e ${def.id} / perp account positions -e ${def.id}`;
+    if (placed.finality === "final")
+        return { ...placed, remediation: null };
+    // The venue's own acknowledgement already reports a resting order (Arcus answers OPEN with the
+    // full remaining size; its order read can 404 for a moment after that): for a resting TIF that
+    // is the order's settled state — the same stopping point awaitOrderFinal uses (untilResting).
+    if (req.type !== "market" && req.tif !== "IOC" && req.tif !== "FOK" && (placed.status === "open" || placed.status === "partiallyFilled")) {
+        return { ...placed, finality: "final", remediation: null };
+    }
+    if (caps.orderAck !== "async" || (placed.orderId === null && placed.clientOrderId === null)) {
+        return { ...placed, remediation: `${def.displayName} acknowledged the order without a final status — do NOT resubmit; verify with: ${listHint}` };
+    }
+    const ref = placed.clientOrderId !== null ? `c:${placed.clientOrderId}` : placed.orderId;
+    const statusHint = `perp trade status ${ref} --symbol ${req.symbol} -e ${def.id}`;
+    let result;
+    try {
+        result = await awaitOrderFinal(adapter, req.symbol, orderRefOf(placed), {
+            timeoutMs: ASYNC_ACK_TIMEOUT_MS,
+            pollMs: ASYNC_ACK_POLL_MS,
+            untilResting: req.type !== "market",
+            ack: placed.status === "accepted" ? placed : null,
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return {
+            ...placed,
+            remediation: `Order was accepted by ${def.displayName} but its status could not be confirmed (${msg}). Do NOT resubmit — check: ${statusHint}`,
+        };
+    }
+    if (result.finality === "pending") {
+        return { ...result, remediation: `Order not final after ${ASYNC_ACK_TIMEOUT_MS / 1000}s — do NOT resubmit; check: ${statusHint}` };
+    }
+    return { ...result, remediation: null };
+}

package/dist/exchanges/venue-types.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Venue-level data contracts (docs/DESIGN-venue-abstraction.md §10).
+ *
+ * SSOT Rule #2: every "unknown" value is `T | null`, never optional, never a
+ * silently substituted default.
+ */
+import type { ExchangeMarketInfo } from "./interface.js";
+import type { ResolvedSlippage, SlippageSource } from "./slippage.js";
+import type { AppliedBuilderFee } from "./builder-fee.js";
+export type VenueId = "pacifica" | "hyperliquid" | "lighter" | "aster" | "lighter-rh" | "ondo" | "arcus" | "qfex";
+export type LegacyVenueId = "pacifica" | "hyperliquid" | "lighter" | "aster";
+export declare const VENUE_IDS: readonly VenueId[];
+export declare const LEGACY_VENUE_IDS: readonly LegacyVenueId[];
+export declare function isVenueId(s: string): s is VenueId;
+export declare function isLegacyVenueId(s: string): s is LegacyVenueId;
+export type Network = "mainnet" | "testnet";
+/** How many hours one quoted funding rate covers (used for normalization). */
+export type FundingRateBasis = {
+    kind: "perHours";
+    hours: number;
+} | {
+    kind: "annualized";
+};
+/** Convert a raw quoted rate to a per-hour rate. */
+export declare function rateToHourly(rate: number, basis: FundingRateBasis): number;
+export type AssetClass = "crypto" | "equity" | "index" | "etf" | "commodity" | "fx" | "preIpo";
+export interface MarketSession {
+    /** Whether the underlying (e.g. US equity) market is open right now. */
+    underlyingOpen: boolean;
+    /** Venue-enforced price band while the underlying is closed (Ondo weekend band, Arcus). */
+    priceBand: {
+        lower: string;
+        upper: string;
+    } | null;
+    /** Initial-margin multiplier while the underlying is closed (Arcus 1.5x). */
+    marginMultiplier: number | null;
+}
+export interface VenueMarket {
+    venue: VenueId;
+    /** Venue-native identifier used on the wire ("TSLA-USD.P", "16", "BTC"). */
+    venueSymbol: string;
+    /** Display symbol used by the CLI (e.g. "TSLA", "BTC"). */
+    symbol: string;
+    /** Cross-venue matching key from canonical-symbols.ts; null = not matchable. */
+    canonical: string | null;
+    assetClass: AssetClass;
+    settle: string;
+    /**
+     * Currency prices are quoted in ("USD", "KRW", ...); null = this venue's data path does not
+     * record it. A non-USD quote is never traded through perp-cli (sizing, risk limits and
+     * notionals assume USD) — see QFEX, design §14.12 #7.
+     */
+    quoteAsset: string | null;
+    markPrice: string;
+    indexPrice: string | null;
+    fundingRate: string | null;
+    fundingRateBasis: FundingRateBasis;
+    settlementIntervalHours: number;
+    openInterest: string | null;
+    volume24h: string | null;
+    /** null = venue publishes no tick (read-only venues). Trading venues must set it. */
+    tickSize: string | null;
+    /** null = venue publishes no lot step (read-only venues). Trading venues must set it. */
+    stepSize: string | null;
+    minSize: string | null;
+    minNotional: string | null;
+    /** null = venue publishes no leverage cap (read-only venues). */
+    maxLeverage: number | null;
+    marginTiers: Array<{
+        lowerBound: number;
+        maxLeverage: number;
+    }> | null;
+    session: MarketSession | null;
+    /** false = listed but not tradable right now (offline / paused / corporate action). */
+    tradable: boolean;
+}
+/** Pure mapping used by new-venue adapters to serve the legacy getMarkets(). */
+/** Tick/step/leverage required for order entry. Throws when the venue did not publish them. */
+export declare function requireTradingPrecision(m: VenueMarket): {
+    tickSize: string;
+    stepSize: string;
+    maxLeverage: number;
+};
+export declare function toLegacyMarketInfo(m: VenueMarket): ExchangeMarketInfo;
+export interface VenueFundingRate {
+    venue: VenueId;
+    venueSymbol: string;
+    symbol: string;
+    canonical: string | null;
+    rate: string;
+    basis: FundingRateBasis;
+    markPrice: string | null;
+    nextFundingTime: number | null;
+}
+/** CLI-level TIF inputs. "TOB" = Pacifica top-of-book, "GTX" = Aster post-only. */
+export type TimeInForce = "GTC" | "GTT" | "IOC" | "FOK" | "ALO" | "TOB" | "GTX";
+export type OrderType = "market" | "limit" | "stopMarket" | "stopLimit";
+export interface OrderRequest {
+    symbol: string;
+    side: "buy" | "sell";
+    type: OrderType;
+    size: string;
+    /** Required for limit/stopLimit. */
+    price: string | null;
+    /** Required for stopMarket/stopLimit. */
+    triggerPrice: string | null;
+    triggerSource: "mark" | "last" | "mid" | null;
+    /** Required for limit/stopLimit; only null is allowed for market/stopMarket. */
+    tif: TimeInForce | null;
+    reduceOnly: boolean;
+    /** Required when the venue's orderAck is "async". */
+    clientOrderId: string | null;
+    /**
+     * Resolved slippage bound (resolveSlippage(), design §13.10 #1). Required for
+     * type "market"; adapters whose stopMarket / TP-SL legs are protection-priced
+     * (Arcus) require it there too. null only for orders that carry no market leg.
+     */
+    slippage: ResolvedSlippage | null;
+    tpsl: {
+        tp: string | null;
+        sl: string | null;
+    } | null;
+}
+export type OrderStatus = "accepted" | "open" | "partiallyFilled" | "filled" | "rejected" | "cancelled";
+export interface OrderResult {
+    venue: VenueId;
+    symbol: string;
+    status: OrderStatus;
+    /** "pending" = not final yet (async venue ack, or awaitOrderFinal timed out). */
+    finality: "final" | "pending";
+    /**
+     * Invariant: orderId !== null || clientOrderId !== null — except for an order the
+     * venue acknowledged without any id (e.g. a legacy-venue trigger order); that
+     * result says so in execution.notes and orderRefOf() refuses it.
+     */
+    orderId: string | null;
+    clientOrderId: string | null;
+    /** Filled base size; null = the venue response does not report it (never "0" as a stand-in). */
+    filledSize: string | null;
+    avgPrice: string | null;
+    /** How the venue adapter actually executed the request (design §13.1 #3, §13.10 #14). */
+    execution: OrderExecution;
+    venueRaw: unknown;
+}
+/**
+ * Transparent record of the venue-specific handling behind a uniform order
+ * (design §13.1 #3, §13.2, §13.10 #14). Every field is required; a value the
+ * venue / adapter did not report is null (SSOT Rule #2), never a guess.
+ */
+export interface OrderExecution {
+    /**
+     * Execution method, e.g. "protectedIoc" (IOC limit at a protection price),
+     * "venueSlippage" (venue applies a slippage percent), "limit", "trigger",
+     * "triggerLimit", "nativeAmend", "cancelReplace".
+     */
+    method: string;
+    /** Slippage bound actually applied (after price-grid rounding when the adapter reports it). */
+    slippageBps: number | null;
+    slippageSource: SlippageSource | null;
+    /** Limit price sent with a market-type order; null = not echoed / computed by the venue. */
+    protectionPrice: string | null;
+    /** Reference price the protection price was derived from (mark / mid / trigger). */
+    referencePrice: string | null;
+    /** TIF as requested by the caller (common or venue alias). */
+    tifRequested: string | null;
+    /** Venue-native TIF actually sent (e.g. "Gtc", "GTT", "GTX"). */
+    tifSent: string | null;
+    /** Unix ms when a resting order expires (GTC mapped to GTT); null = no venue expiry. */
+    expiresAt: number | null;
+    /**
+     * Builder fee this order carried (settings builder.<venue> + confirmed approval); null = none.
+     * A configured fee that was NOT attached says why in `notes`.
+     */
+    builderFee: AppliedBuilderFee | null;
+    notes: string[];
+}
+/**
+ * Attach an execution record to a result built without one. Fields of `partial`
+ * that are absent are recorded as null (unknown), never defaulted to a value.
+ */
+export declare function withExecution(result: Omit<OrderResult, "execution">, method: string, partial: Partial<Omit<OrderExecution, "method">>): OrderResult;
+export type OrderRef = {
+    kind: "orderId";
+    value: string;
+} | {
+    kind: "clientOrderId";
+    value: string;
+};
+export interface AmendRequest {
+    symbol: string;
+    ref: OrderRef;
+    price: string;
+    size: string;
+    /**
+     * Time-in-force of the replacement. null = keep the resting order's own TIF
+     * (venues that can read it back, e.g. Arcus); cancel→replace venues that cannot
+     * read post-only back (Ondo) refuse null.
+     */
+    tif: TimeInForce | null;
+    /**
+     * Allow an explicit `tif` that flips the post-only flag encoded in the order's generated
+     * client id (Ondo / Pacifica): without it such a conflict is INVALID_PARAMS (CLI --force-tif).
+     */
+    forceTif?: boolean;
+}
+export interface CancelResult {
+    venue: VenueId;
+    /** Only orders whose cancel the venue result proves (per order). */
+    cancelled: OrderRef[];
+    failed: Array<{
+        ref: OrderRef | null;
+        error: string;
+    }>;
+    /** Cancels sent but not proven by the venue result — status pending; verify before acting again. */
+    pending?: Array<{
+        ref: OrderRef | null;
+        reason: string;
+        remediation: string;
+    }>;
+    venueRaw: unknown;
+}
+export interface LeverageResult {
+    venue: VenueId;
+    symbol: string;
+    leverage: number;
+    marginMode: "cross" | "isolated";
+    venueRaw: unknown;
+}
+export declare function orderRefOf(r: Pick<OrderResult, "orderId" | "clientOrderId">): OrderRef;
+/** Parse a CLI order reference: "c:<id>" → clientOrderId, otherwise orderId. */
+export declare function parseOrderRef(s: string): OrderRef;

package/dist/exchanges/venue-types.js

@@ -0,0 +1,87 @@
+/**
+ * Venue-level data contracts (docs/DESIGN-venue-abstraction.md §10).
+ *
+ * SSOT Rule #2: every "unknown" value is `T | null`, never optional, never a
+ * silently substituted default.
+ */
+export const VENUE_IDS = [
+    "pacifica", "hyperliquid", "lighter", "aster",
+    "lighter-rh", "ondo", "arcus", "qfex",
+];
+export const LEGACY_VENUE_IDS = ["pacifica", "hyperliquid", "lighter", "aster"];
+export function isVenueId(s) {
+    return VENUE_IDS.includes(s);
+}
+export function isLegacyVenueId(s) {
+    return LEGACY_VENUE_IDS.includes(s);
+}
+/** Convert a raw quoted rate to a per-hour rate. */
+export function rateToHourly(rate, basis) {
+    if (basis.kind === "perHours")
+        return rate / basis.hours;
+    return rate / (24 * 365);
+}
+function decimalsOf(step) {
+    const s = step.includes("e") || step.includes("E") ? Number(step).toFixed(20).replace(/0+$/, "") : step;
+    const dot = s.indexOf(".");
+    return dot === -1 ? 0 : s.length - dot - 1;
+}
+/** Pure mapping used by new-venue adapters to serve the legacy getMarkets(). */
+/** Tick/step/leverage required for order entry. Throws when the venue did not publish them. */
+export function requireTradingPrecision(m) {
+    if (m.tickSize === null || m.stepSize === null || m.maxLeverage === null) {
+        throw new Error(`${m.venue} ${m.symbol}: tick size / step size / max leverage not published — market is not tradable via API`);
+    }
+    return { tickSize: m.tickSize, stepSize: m.stepSize, maxLeverage: m.maxLeverage };
+}
+export function toLegacyMarketInfo(m) {
+    const p = requireTradingPrecision(m);
+    const hours = m.fundingRateBasis.kind === "perHours" ? m.fundingRateBasis.hours : null;
+    return {
+        symbol: m.symbol,
+        markPrice: m.markPrice,
+        indexPrice: m.indexPrice,
+        fundingRate: m.fundingRate,
+        volume24h: m.volume24h,
+        openInterest: m.openInterest,
+        maxLeverage: p.maxLeverage,
+        sizeDecimals: decimalsOf(p.stepSize),
+        stepSize: p.stepSize,
+        fundingHours: hours,
+        marginTiers: m.marginTiers,
+    };
+}
+/**
+ * Attach an execution record to a result built without one. Fields of `partial`
+ * that are absent are recorded as null (unknown), never defaulted to a value.
+ */
+export function withExecution(result, method, partial) {
+    return {
+        ...result,
+        execution: {
+            method,
+            slippageBps: partial.slippageBps ?? null,
+            slippageSource: partial.slippageSource ?? null,
+            protectionPrice: partial.protectionPrice ?? null,
+            referencePrice: partial.referencePrice ?? null,
+            tifRequested: partial.tifRequested ?? null,
+            tifSent: partial.tifSent ?? null,
+            expiresAt: partial.expiresAt ?? null,
+            builderFee: partial.builderFee ?? null,
+            notes: partial.notes ?? [],
+        },
+    };
+}
+export function orderRefOf(r) {
+    if (r.orderId !== null)
+        return { kind: "orderId", value: r.orderId };
+    if (r.clientOrderId !== null)
+        return { kind: "clientOrderId", value: r.clientOrderId };
+    throw new Error("OrderResult invariant violated: neither orderId nor clientOrderId is set");
+}
+/** Parse a CLI order reference: "c:<id>" → clientOrderId, otherwise orderId. */
+export function parseOrderRef(s) {
+    if (s.startsWith("c:"))
+        return { kind: "clientOrderId", value: s.slice(2) };
+    return { kind: "orderId", value: s };
+}