perp-cli 0.12.15 → 0.14.0

package/dist/exchanges/spot-factory.js

@@ -0,0 +1,431 @@
+/**
+ * Spot adapter factory — the only place spot adapters are created (design §12.4 #1).
+ *
+ * - `getSpotAdapter` returns null iff the venue has no spot (`def.spot === null`).
+ *   Creation / init / network errors propagate (SSOT Rule #2 — no catch).
+ * - `createSpot` (venue definition) constructs and init()s the adapter.
+ * - Cached per perp adapter instance (each instance is bound to one venue + network,
+ *   so the key is the adapter's own network, not the process-wide one) and per
+ *   on-chain-approve option. Read-only and signed perp adapters keep separate entries.
+ *
+ * Bot scope (§12.4 #3): bots only trade spot on venues where `isBotSpotVenue(def)`.
+ * Quote/base detection (§12.4 #6) goes through `def.spot.quoteAssets`.
+ */
+import { classifyError, extractErrorMessage, PerpError } from "../errors.js";
+import { unsupported } from "./trading-v2.js";
+import { sharedApiNetwork } from "../api/public/urls.js";
+import { canonicalFor, isNeverMatch } from "./canonical-symbols.js";
+import { floorSize } from "./precision.js";
+import { isSpotFreshBalancesCapable, isSpotHoldingPricesCapable, isSpotPricesCapable, isSpotTransferCapable, MAX_PRICE_DEVIATION_PCT } from "./spot-interface.js";
+import { getVenue, listVenues, tryResolveVenueId } from "./venue.js";
+import "./venues/index.js";
+/** Options for every non-CLI caller: on-chain approve txs are never sent implicitly. */
+export const NO_ONCHAIN_APPROVE = { confirmOnchainApprove: false };
+/** perp adapter → `${venueId}:${confirmOnchainApprove}` → spot adapter. */
+const _cache = new WeakMap();
+/**
+ * spot adapter → (venue, perp adapter, network) it was created for; used by the transfer /
+ * quote helpers. `net` is the process's selected network (sharedApiNetwork — the -n the perp
+ * adapter was created with) and decides the spot quote (spotQuoteAssets).
+ */
+const _owner = new WeakMap();
+function hasSpot(def) {
+    return def.spot !== null;
+}
+/** Venues with spot support, for remediation text. */
+export function listSpotVenues() {
+    return listVenues().filter(hasSpot);
+}
+/**
+ * Get (or create + init) the spot adapter for a venue. null iff the venue has no spot.
+ * `opts` defaults to NO_ONCHAIN_APPROVE (the safe deny); only the CLI passes --yes.
+ */
+export async function getSpotAdapter(venue, perp, opts = NO_ONCHAIN_APPROVE) {
+    const def = getVenue(venue);
+    if (!hasSpot(def))
+        return null;
+    let perPerp = _cache.get(perp);
+    if (perPerp === undefined) {
+        perPerp = new Map();
+        _cache.set(perp, perPerp);
+    }
+    const key = `${def.id}:${opts.confirmOnchainApprove}`;
+    const hit = perPerp.get(key);
+    if (hit !== undefined)
+        return hit;
+    const net = sharedApiNetwork();
+    const spot = def.spot.createSpot(perp, opts).then(s => {
+        _owner.set(s, { def, perp, net });
+        return s;
+    });
+    perPerp.set(key, spot);
+    try {
+        return await spot;
+    }
+    catch (e) {
+        // Do not cache a failed creation; the error itself propagates.
+        if (perPerp.get(key) === spot)
+            perPerp.delete(key);
+        throw e;
+    }
+}
+/** The venue's spot definition, or CAPABILITY_UNSUPPORTED. */
+export function requireSpotDefinition(def) {
+    if (!hasSpot(def)) {
+        throw unsupported(def.displayName, "spot", "the venue has no spot trading", `Spot venues: ${listSpotVenues().map(v => v.id).join(", ")}`);
+    }
+    return def.spot;
+}
+/** CLI form: throws CAPABILITY_UNSUPPORTED when the venue has no spot. */
+export async function requireSpotAdapter(venue, perp, opts = NO_ONCHAIN_APPROVE) {
+    requireSpotDefinition(getVenue(venue));
+    const spot = await getSpotAdapter(venue, perp, opts);
+    if (spot === null)
+        throw new Error(`unreachable: ${venue} spot definition present but no adapter`);
+    return spot;
+}
+// ── Bot scope (§12.4 #3) ──
+/**
+ * Bots (funding-arb*, spot-perp-*, arb-auto, arb/index) only use spot venues with a
+ * separate (or runtime-decided) spot balance and a spot↔perp transfer. Pacifica
+ * (shared margin) and Arcus (on-chain swap) are excluded.
+ */
+export function isBotSpotVenue(def) {
+    return def.spot !== null
+        && (def.spot.accountModel === "separate" || def.spot.accountModel === "runtime")
+        && def.spot.capabilities.transfer;
+}
+export function listBotSpotVenues() {
+    return listVenues().filter(isBotSpotVenue);
+}
+/** Bot form: throws CAPABILITY_UNSUPPORTED for venues outside the bot spot scope. */
+export function requireBotSpotVenue(venue) {
+    const def = getVenue(venue);
+    if (!hasSpot(def) || !isBotSpotVenue(def)) {
+        throw unsupported(def.displayName, "botSpot", "bots/arb need a separate spot balance with spot↔perp transfer", `Bot spot venues: ${listBotSpotVenues().map(v => v.id).join(", ")}. Trade ${def.id} spot manually: perp -e ${def.id} trade spot-buy ...`);
+    }
+    return def;
+}
+/**
+ * Bot spot adapter for an adapter-map name. null when the name is not a venue, or the
+ * venue is outside the bot spot scope. Creation errors propagate.
+ */
+export async function getBotSpotAdapter(name, perp) {
+    const id = tryResolveVenueId(name);
+    if (id === null || !isBotSpotVenue(getVenue(id)))
+        return null;
+    return getSpotAdapter(id, perp);
+}
+// ── Quote / base helpers (§12.4 #6) ──
+/** Upper-cased token with venue balance suffixes removed ("USDC_SPOT" / "PURR-SPOT" → base). */
+export function spotTokenBase(token) {
+    return token.toUpperCase().replace(/[-_]SPOT$/, "");
+}
+/** The venue's spot quote assets on `net` (network-keyed: Lighter RH quotes USDG on mainnet, USDC on testnet). */
+export function spotQuoteAssets(def, net) {
+    return requireSpotDefinition(def).quoteAssets[net];
+}
+/** Default quote on `net` (bare-base symbols, transfers). */
+export function defaultSpotQuote(def, net) {
+    const quote = spotQuoteAssets(def, net)[0];
+    if (quote === undefined)
+        throw new Error(`${def.id} spot definition has no ${net} quoteAssets`);
+    return quote;
+}
+/** The network a spot adapter was created for (getSpotAdapter). */
+export function spotNetworkOf(spot) {
+    return ownerOf(spot).net;
+}
+export function isSpotQuoteAsset(def, net, token) {
+    return spotQuoteAssets(def, net).includes(spotTokenBase(token));
+}
+/** "BASE/QUOTE" for a bare base on this venue (quoteAssets[net][0]). */
+export function spotPairSymbol(def, net, base) {
+    return `${base.toUpperCase()}/${defaultSpotQuote(def, net)}`;
+}
+/** The balance row of the venue's default quote asset (transfer asset), or null. */
+export function findSpotQuoteBalance(def, net, balances) {
+    const quote = defaultSpotQuote(def, net);
+    return balances.find(b => spotTokenBase(b.token) === quote) ?? null;
+}
+/** Non-quote balances with a positive total (the "holdings" side of spot-perp hedges). */
+export function nonQuoteSpotBalances(def, net, balances) {
+    return balances.filter(b => Number(b.total) > 0 && !isSpotQuoteAsset(def, net, b.token));
+}
+/**
+ * true when spot quote balance is the same money as perp margin for this perp
+ * adapter: accountModel "unified", or "runtime" with a unified perp account (HL).
+ */
+export function spotSharesPerpMargin(def, perp) {
+    const spot = requireSpotDefinition(def);
+    if (spot.accountModel === "unified")
+        return true;
+    if (spot.accountModel === "runtime")
+        return perp.isUnifiedAccount === true;
+    return false;
+}
+/**
+ * USD value of positive spot balances. Quote assets (stablecoins) are 1:1; other
+ * tokens use the venue's spot mark price. Tokens without a usable price are
+ * EXCLUDED and reported via `warn` — never valued at 0 (SSOT Rule #2).
+ * `shared` is carried through so aggregators can skip money already in perp equity.
+ */
+export function valueSpotBalances(def, net, balances, markets, warn) {
+    // markPrice null = no usable price (§12 SpotMarketInfo) → the token is excluded below.
+    const prices = new Map(markets.flatMap(m => (m.markPrice === null ? [] : [[m.baseToken.toUpperCase(), Number(m.markPrice)]])));
+    const out = [];
+    for (const b of balances) {
+        const total = Number(b.total);
+        if (!(total > 0))
+            continue;
+        if (isSpotQuoteAsset(def, net, b.token)) {
+            out.push({ ...b, valueUsd: total });
+            continue;
+        }
+        const px = prices.get(spotTokenBase(b.token));
+        if (px === undefined || !Number.isFinite(px) || px <= 0) {
+            warn(`${def.displayName} spot ${b.token}: no market price — excluded from value totals`);
+            continue;
+        }
+        out.push({ ...b, valueUsd: px * total });
+    }
+    return out;
+}
+/** Timeout for one venue's spot valuation (balances + prices) in aggregate views (portfolio, landing). */
+export const SPOT_VALUATION_TIMEOUT_MS = 5_000;
+/**
+ * Prices used to value `balances`. Wallet-model venues (Arcus) price only the held
+ * non-quote tokens (`getSpotPrices`); exchange venues use `getSpotMarkets()`, plus — when the
+ * adapter is SpotHoldingPricesCapable — `getHoldingPrices()` for held tokens that are not a spot
+ * market (Hyperliquid HIP-4 outcome tokens). A holding price counts only when it is quoted in one of
+ * the venue's spot quote assets (valued 1:1 like the quote balance); any other quote (or an unknown
+ * one) → markPrice null → the token stays unpriced (never 0).
+ */
+export async function spotMarketsForValuation(def, spot, balances, net) {
+    if (requireSpotDefinition(def).accountModel !== "wallet") {
+        const markets = await spot.getSpotMarkets();
+        if (!isSpotHoldingPricesCapable(spot))
+            return markets;
+        const listed = new Set(markets.map(m => m.baseToken.toUpperCase()));
+        const unlisted = nonQuoteSpotBalances(def, net, balances).map(b => spotTokenBase(b.token)).filter(t => !listed.has(t));
+        if (unlisted.length === 0)
+            return markets;
+        const quotes = spotQuoteAssets(def, net);
+        const held = (await spot.getHoldingPrices(unlisted)).map(p => ({
+            baseToken: p.token,
+            markPrice: p.quoteToken !== null && quotes.includes(p.quoteToken.toUpperCase()) ? p.markPrice : null,
+        }));
+        return [...markets, ...held];
+    }
+    if (!isSpotPricesCapable(spot)) {
+        throw new Error(`${def.id} is a wallet-model spot venue but its adapter has no getSpotPrices()`);
+    }
+    const held = nonQuoteSpotBalances(def, net, balances).map(b => spotTokenBase(b.token));
+    return held.length === 0 ? [] : spot.getSpotPrices(held);
+}
+/**
+ * Balances + valuation for aggregate views, bounded by `timeoutMs` (rejects with a
+ * TIMEOUT error; the caller reports it — never a partial or zero value).
+ */
+export async function fetchValuedSpotBalances(def, spot, warn, timeoutMs = SPOT_VALUATION_TIMEOUT_MS) {
+    return withSpotTimeout((async () => {
+        const net = spotNetworkOf(spot);
+        const balances = await spot.getSpotBalances();
+        const markets = await spotMarketsForValuation(def, spot, balances, net);
+        return valueSpotBalances(def, net, balances, markets, warn);
+    })(), `${def.displayName} spot valuation`, timeoutMs);
+}
+/** Reject with TIMEOUT after `timeoutMs` (the timer is cleared either way). */
+export async function withSpotTimeout(p, what, timeoutMs = SPOT_VALUATION_TIMEOUT_MS) {
+    let timer;
+    const timeout = new Promise((_, rej) => {
+        timer = setTimeout(() => rej(new PerpError("TIMEOUT", `${what} timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([p, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ── Transfers (§12.4 #4) ──
+function ownerOf(spot) {
+    const o = _owner.get(spot);
+    if (!o)
+        throw new Error(`spot adapter "${spot.name}" was not created by getSpotAdapter()`);
+    return o;
+}
+async function transferQuote(spot, amount, to) {
+    const { def, perp, net } = ownerOf(spot);
+    if (spotSharesPerpMargin(def, perp))
+        return false;
+    if (!def.spot.capabilities.transfer || !isSpotTransferCapable(spot)) {
+        throw unsupported(def.displayName, "spotTransfer", `spot account model is "${def.spot.accountModel}"`, `${def.id}: fund spot directly`);
+    }
+    if (!Number.isFinite(amount) || amount <= 0) {
+        throw new PerpError("INVALID_PARAMS", `Transfer amount must be positive (got ${amount})`);
+    }
+    const asset = defaultSpotQuote(def, net);
+    const wire = transferAmountString(amount);
+    if (to === "spot")
+        await spot.transferToSpot(wire, asset);
+    else
+        await spot.transferToPerp(wire, asset);
+    return true;
+}
+/** Quote-asset transfer grid (USDC / USDT / USDG are 6-decimal tokens). */
+const TRANSFER_STEP = "0.000001";
+/**
+ * Fixed-point decimal string for a transfer amount, floored to TRANSFER_STEP — never
+ * `String(n)` (exponent "1e-7" or float artefacts "0.30000000000000004").
+ */
+export function transferAmountString(amount) {
+    // toFixed(12) is plain decimal for any amount below 1e21; floorSize re-checks the form.
+    return floorSize(amount.toFixed(12), TRANSFER_STEP);
+}
+/**
+ * Move the venue's quote asset (quoteAssets[0]) perp → spot.
+ * Returns false (no-op, nothing moved) when spot and perp share margin; throws
+ * CAPABILITY_UNSUPPORTED when the venue has no transfer. Callers log "Transferred" only on true.
+ */
+export function transferQuoteToSpot(spot, amount) {
+    return transferQuote(spot, amount, "spot");
+}
+/**
+ * A spot↔perp transfer the venue refused for lack of funds (classifyError → INSUFFICIENT_BALANCE,
+ * e.g. HL "Insufficient balance for withdrawal.") → INSUFFICIENT_BALANCE that says how much the
+ * SOURCE side can move OF THE TRANSFER ASSET (`readAvailable`: perp withdrawable for to-spot, spot
+ * quote available for to-perp) — never an account-wide equity figure: a multi-asset margin
+ * account can hold margin and none of the asset. A failed read is reported as such (never a
+ * guessed figure). Any other error → unchanged.
+ */
+export async function transferShortfallError(e, opts) {
+    if (classifyError(e).code !== "INSUFFICIENT_BALANCE")
+        return e;
+    const source = opts.direction === "to-spot" ? "perp" : "spot";
+    const from = opts.direction === "to-spot" ? "perp withdrawable" : "spot available";
+    let have;
+    let available = null;
+    try {
+        const n = await opts.readAvailable();
+        if (!Number.isFinite(n))
+            throw new Error(`venue reported a non-numeric balance (${String(n)})`);
+        // transferAmountString refuses 0 (it formats an amount to SEND); nothing to move is "0".
+        available = n >= Number(TRANSFER_STEP) ? transferAmountString(n) : "0";
+        have = `${from} is ${available} ${opts.asset}`;
+    }
+    catch (re) {
+        have = `${from} could not be read (${extractErrorMessage(re)})`;
+    }
+    return new PerpError("INSUFFICIENT_BALANCE", `${opts.venue} ${opts.direction} transfer of ${opts.amount} ${opts.asset} refused: ${extractErrorMessage(e)} — ${have}`, {
+        exchange: opts.venue, requested: opts.amount, available, asset: opts.asset,
+        remediation: available === null
+            ? `Check balances: perp -e ${opts.venue} portfolio / trade spot-balance`
+            : Number(available) > 0
+                ? `Transfer at most ${available} ${opts.asset}, or fund the ${source} account first`
+                : `The ${source} account holds no transferable ${opts.asset} — this command moves ${opts.asset} only (margin held in another asset is not ${opts.asset}). Fund the ${source} account with ${opts.asset} first; check: perp -e ${opts.venue} portfolio / trade spot-balance`,
+    });
+}
+/** Spot → perp counterpart of transferQuoteToSpot. */
+export function transferQuoteToPerp(spot, amount) {
+    return transferQuote(spot, amount, "perp");
+}
+/**
+ * Spot quote (quoteAssets[0]) `available` read UNCACHED; 0 when the venue holds no
+ * quote row. Errors propagate. Used as the baseline for sweepSpotQuoteToPerp().
+ */
+export async function readSpotQuoteAvailableFresh(spot) {
+    const { def, net } = ownerOf(spot);
+    const bals = isSpotFreshBalancesCapable(spot) ? await spot.getSpotBalancesFresh() : await spot.getSpotBalances();
+    const bal = findSpotQuoteBalance(def, net, bals);
+    if (bal === null)
+        return 0;
+    const n = Number(bal.available);
+    if (!Number.isFinite(n))
+        throw new PerpError("EXCHANGE_ERROR", `${spot.name} spot ${bal.token} available is not a number: ${bal.available}`, { exchange: spot.name });
+    return n;
+}
+/**
+ * Sweep back to perp ONLY the spot quote this trade produced / left over: the part of
+ * the (uncached) available balance above `keep` (the quote that was there before the
+ * trade — never touched), capped at `max` (e.g. what this trade transferred in; null =
+ * no cap). Returns the amount moved; 0 when the balance is shared with perp or the
+ * amount is ≤ minAmount. Errors propagate — callers surface them (funds remain in spot).
+ */
+export async function sweepSpotQuoteToPerp(spot, minAmount, opts) {
+    const { def, perp, net } = ownerOf(spot);
+    if (spotSharesPerpMargin(def, perp))
+        return 0;
+    const bals = isSpotFreshBalancesCapable(spot) ? await spot.getSpotBalancesFresh() : await spot.getSpotBalances();
+    const bal = findSpotQuoteBalance(def, net, bals);
+    if (bal === null || bal.shared)
+        return 0;
+    const available = Number(bal.available);
+    if (!Number.isFinite(available))
+        throw new PerpError("EXCHANGE_ERROR", `${spot.name} spot ${bal.token} available is not a number: ${bal.available}`, { exchange: spot.name });
+    let movable = available - opts.keep;
+    if (opts.max !== null)
+        movable = Math.min(movable, opts.max);
+    const amount = Math.floor(movable * 100) / 100;
+    if (!(amount > minAmount))
+        return 0;
+    return (await transferQuoteToPerp(spot, amount)) ? amount : 0;
+}
+/**
+ * Match a spot venue's markets (default quote only) to a perp venue's markets by
+ * canonical symbol — `canonicalFor(spotVenue, base, perp.assetClass)` must equal the
+ * perp market's canonical (`null` never matches, NEVER_MATCH pairs excluded) — plus a
+ * price guard: |spot − perp mark| ≤ MAX_PRICE_DEVIATION_PCT. Spot markets without a
+ * price cannot be validated and are not matched. Bare-ticker equality is never enough.
+ *
+ * `perpMarkets` = the perp venue's public markets (`fetchPerpMarketsForMatching`).
+ * Returns spot base (upper-case) → match.
+ */
+export function matchSpotPerp(spotVenue, spotMarkets, perpVenue, perpMarkets, warn, net) {
+    const spotDef = getVenue(spotVenue);
+    const perpDef = getVenue(perpVenue);
+    const quote = defaultSpotQuote(spotDef, net);
+    const classes = new Set(perpMarkets.map(m => m.assetClass));
+    // (assetClass, canonical) → perp market
+    const perpByKey = new Map();
+    for (const m of perpMarkets) {
+        if (m.canonical !== null)
+            perpByKey.set(`${m.assetClass}|${m.canonical}`, m);
+    }
+    const out = new Map();
+    const deviating = [];
+    for (const sm of spotMarkets) {
+        if (sm.quoteToken.toUpperCase() !== quote || sm.markPrice === null)
+            continue;
+        const spotPrice = Number(sm.markPrice);
+        if (!Number.isFinite(spotPrice) || spotPrice <= 0)
+            continue;
+        const base = sm.baseToken.toUpperCase();
+        for (const cls of classes) {
+            const canonical = canonicalFor(spotDef.id, base, cls);
+            if (canonical === null)
+                continue;
+            const pm = perpByKey.get(`${cls}|${canonical}`);
+            if (pm === undefined || isNeverMatch(base, pm.symbol.toUpperCase()))
+                continue;
+            const perpPrice = Number(pm.markPrice);
+            if (!Number.isFinite(perpPrice) || perpPrice <= 0)
+                continue;
+            const deviationPct = Math.abs(spotPrice - perpPrice) / perpPrice * 100;
+            if (deviationPct > MAX_PRICE_DEVIATION_PCT) {
+                deviating.push(`${base}/${quote}↔${pm.symbol} ${deviationPct.toFixed(1)}%`);
+                continue;
+            }
+            out.set(base, { spotBase: base, perpSymbol: pm.symbol, canonical, assetClass: cls, spotPrice, perpPrice, deviationPct });
+            break;
+        }
+    }
+    if (deviating.length > 0) {
+        warn(`${spotDef.displayName} spot ↔ ${perpDef.displayName} perp: ${deviating.length} same-symbol pair(s) excluded, price deviation > ${MAX_PRICE_DEVIATION_PCT}%: ${deviating.join(", ")}`);
+    }
+    return out;
+}
+/** The perp venue's public markets (canonical + asset class + mark) on `net` (default: process network). */
+export function fetchPerpMarketsForMatching(perpVenue, net = sharedApiNetwork()) {
+    return getVenue(perpVenue).publicData.fetchMarkets(net);
+}

package/dist/exchanges/spot-interface.d.ts

@@ -3,14 +3,25 @@
  * Separate from ExchangeAdapter because spot uses balance-based tracking
  * (not position-based) and has no leverage, liquidation, or funding concepts.
  *
- * Supported: Hyperliquid, Lighter (Pacifica is perp-only)
+ * Venues declare spot support in their VenueDefinition (`spot`, design §12);
+ * adapters are created only through `getSpotAdapter()` in spot-factory.ts.
+ *
+ * Symbol rule (§12.4 #6): `SpotMarketInfo.symbol` is "BASE/QUOTE". Adapter
+ * methods accept a bare base ("ETH" → BASE/quoteAssets[0]) or "BASE/QUOTE"
+ * and translate to the venue's wire form.
  */
+import type { ResolvedSlippage } from "./slippage.js";
 export interface SpotMarketInfo {
     symbol: string;
     baseToken: string;
     quoteToken: string;
-    markPrice: string;
-    volume24h: string;
+    /**
+     * null = the venue has no usable price for this market right now (no mark and no
+     * two-sided book). Never "0" or a stale last trade (Rule #2). Consumers skip it for
+     * valuation / matching.
+     */
+    markPrice: string | null;
+    volume24h: string | null;
     sizeDecimals: number;
     priceDecimals: number;
 }
@@ -20,7 +31,87 @@ export interface SpotBalance {
     available: string;
     held: string;
     entryNtl?: string;
+    /**
+     * true = this balance is the same money as the perp account (Pacifica USDC,
+     * HL unified). Aggregators must not add it on top of perp equity (§12.4 #8).
+     */
+    shared: boolean;
+}
+/** Normalized spot order result for venues added under §12 (legacy HL/Lighter return unknown). */
+export interface SpotOrderResult {
+    venue: string;
+    symbol: string;
+    orderId: string | null;
+    status: "filled" | "partial" | "open" | "pending" | "rejected" | "cancelled";
+    /** null = venue did not report it */
+    filledSize: string | null;
+    avgPrice: string | null;
+    /** "pending" = submitted but not confirmed final — do NOT resubmit. */
+    finality: "final" | "pending";
+    /** Token actually received (Arcus router may deliver a wrapped token); null when not applicable. */
+    receivedToken: string | null;
+    remediation: string | null;
+    venueRaw: unknown;
+}
+/**
+ * `venueRaw.fillSource` marker for a fill parsed from a tx event (Lighter event_info
+ * `is` − `rs`): spotMarketFill() cross-checks such fills against a fresh balance delta.
+ */
+export declare const TX_EVENT_FILL_SOURCE = "tx-event-info";
+/** Spot ↔ perp transfer for `accountModel: "separate" | "runtime"` venues. Amount is a decimal string. */
+export interface SpotTransferCapable {
+    transferToSpot(amount: string, asset: string): Promise<unknown>;
+    transferToPerp(amount: string, asset: string): Promise<unknown>;
+}
+/**
+ * Uncached balance read. REQUIRED for any adapter whose getSpotBalances() is served
+ * from the shared TTL cache (src/cache.ts `acct:` keys — Lighter, Hyperliquid): fill
+ * measurement and post-trade verification must never see a pre-trade cached row.
+ * Adapters without it read live on every getSpotBalances() call.
+ */
+export interface SpotFreshBalancesCapable {
+    getSpotBalancesFresh(): Promise<SpotBalance[]>;
+}
+export declare function isSpotFreshBalancesCapable(a: SpotAdapter): a is SpotAdapter & SpotFreshBalancesCapable;
+export interface SpotOpenOrdersCapable {
+    getSpotOpenOrders(symbol: string | null): Promise<Array<{
+        orderId: string;
+        symbol: string;
+        side: "buy" | "sell";
+        price: string;
+        size: string;
+        filled: string;
+    }>>;
 }
+export interface SpotCancelAllCapable {
+    spotCancelAllOrders(symbol: string | null): Promise<unknown>;
+}
+/**
+ * Price only the given base tokens (same SpotMarketInfo shape as getSpotMarkets).
+ * Required for `accountModel: "wallet"` venues, where pricing the whole market
+ * universe is too slow for valuation (Arcus: one router /price call per token).
+ */
+export interface SpotPricesCapable {
+    getSpotPrices(tokens: readonly string[]): Promise<SpotMarketInfo[]>;
+}
+export declare function isSpotPricesCapable(a: SpotAdapter): a is SpotAdapter & SpotPricesCapable;
+/**
+ * A held token's price for valuation only — a token the venue holds in spot but does not list as a
+ * spot market (Hyperliquid HIP-4 outcome tokens "+<encoding>"). `quoteToken` = the token its price is
+ * quoted in; null = unknown (then the price is unusable). `markPrice` null = no usable price (Rule #2).
+ */
+export interface SpotHoldingPrice {
+    token: string;
+    quoteToken: string | null;
+    markPrice: string | null;
+}
+/** Prices for held tokens without a spot market (valuation: portfolio, bot equity). Unpriceable tokens may be omitted. */
+export interface SpotHoldingPricesCapable {
+    getHoldingPrices(tokens: readonly string[]): Promise<SpotHoldingPrice[]>;
+}
+export declare function isSpotHoldingPricesCapable(a: SpotAdapter): a is SpotAdapter & SpotHoldingPricesCapable;
+export declare function isSpotTransferCapable(a: SpotAdapter): a is SpotAdapter & SpotTransferCapable;
+export declare function isSpotOpenOrdersCapable(a: SpotAdapter): a is SpotAdapter & SpotOpenOrdersCapable;
 export interface SpotOrderParams {
     symbol: string;
     side: "buy" | "sell";
@@ -38,7 +129,10 @@ export interface SpotAdapter {
         asks: [string, string][];
     }>;
     getSpotBalances(): Promise<SpotBalance[]>;
-    spotMarketOrder(symbol: string, side: "buy" | "sell", size: string): Promise<unknown>;
+    /** Market order within the resolved slippage bound (design §13.2 — same rule as perps). */
+    spotMarketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
+        slippage: ResolvedSlippage;
+    }): Promise<unknown>;
     spotLimitOrder(symbol: string, side: "buy" | "sell", price: string, size: string, opts?: {
         tif?: string;
     }): Promise<unknown>;

package/dist/exchanges/spot-interface.js

@@ -3,8 +3,34 @@
  * Separate from ExchangeAdapter because spot uses balance-based tracking
  * (not position-based) and has no leverage, liquidation, or funding concepts.
  *
- * Supported: Hyperliquid, Lighter (Pacifica is perp-only)
+ * Venues declare spot support in their VenueDefinition (`spot`, design §12);
+ * adapters are created only through `getSpotAdapter()` in spot-factory.ts.
+ *
+ * Symbol rule (§12.4 #6): `SpotMarketInfo.symbol` is "BASE/QUOTE". Adapter
+ * methods accept a bare base ("ETH" → BASE/quoteAssets[0]) or "BASE/QUOTE"
+ * and translate to the venue's wire form.
+ */
+/**
+ * `venueRaw.fillSource` marker for a fill parsed from a tx event (Lighter event_info
+ * `is` − `rs`): spotMarketFill() cross-checks such fills against a fresh balance delta.
  */
+export const TX_EVENT_FILL_SOURCE = "tx-event-info";
+export function isSpotFreshBalancesCapable(a) {
+    return typeof a.getSpotBalancesFresh === "function";
+}
+export function isSpotPricesCapable(a) {
+    return typeof a.getSpotPrices === "function";
+}
+export function isSpotHoldingPricesCapable(a) {
+    return typeof a.getHoldingPrices === "function";
+}
+export function isSpotTransferCapable(a) {
+    const r = a;
+    return typeof r.transferToSpot === "function" && typeof r.transferToPerp === "function";
+}
+export function isSpotOpenOrdersCapable(a) {
+    return typeof a.getSpotOpenOrders === "function";
+}
 // ── Token mapping & price verification ──
 /**
  * U-token (Unit protocol) → underlying perp symbol mapping.

package/dist/exchanges/spot-result.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Spot order outcome → filled size, for bots / arb (design §12.4 #5).
+ *
+ * A resolved `spotMarketOrder()` promise does NOT mean "filled": the §12 adapters
+ * return a `SpotOrderResult` (rejected / cancelled / pending / partial / filled),
+ * and the legacy Hyperliquid / Lighter adapters return a venue payload. Every bot /
+ * arb spot leg goes through `spotMarketFill()` so the hedge is sized to what
+ * actually filled:
+ *
+ *  - rejected / cancelled (nothing filled)        → throws ORDER_REJECTED
+ *  - pending / open / fill size not reported      → throws ORDER_PENDING (do NOT retry)
+ *  - the order call itself throws                 → a PerpError with a definite code
+ *    (isDefiniteOrderFailure: validation / policy / explicit venue rejection) is
+ *    rethrown as a definite failure; ANYTHING else (non-PerpError, EXCHANGE_UNREACHABLE,
+ *    TIMEOUT, EXCHANGE_ERROR, RATE_LIMITED, UNKNOWN, …) becomes ORDER_PENDING — the
+ *    request may have reached the venue, so callers quarantine instead of retrying.
+ *  - partial                                      → returns the filled size
+ *  - filled                                       → returns the filled size
+ *
+ * Legacy results:
+ *  - Hyperliquid: `response.data.statuses[0].filled.totalSz` (resting → pending).
+ *  - Lighter: the adapter reads the fill from Lighter's own /tx event_info (taker
+ *    order "filled") or, for any other status, the order's accountOrders row
+ *    (filled_base_amount), and returns a final SpotOrderResult that iocOutcomeOf() reports
+ *    (venueFinalSpotFill below). A SpotOrderResult marked TX_EVENT_FILL_SOURCE that is not
+ *    routed through iocOutcomeOf is cross-checked as follows; because
+ *    the is/rs semantics are not venue-documented, that fill must be backed by a fresh
+ *    base-balance delta of ≥ 80% (else ORDER_PENDING). Only when the venue gives no fill
+ *    report does it return the raw tx hash; the fill is then MEASURED as the base-token
+ *    balance delta around the order using UNCACHED reads (readSpotBalancesFresh). A
+ *    zero delta is ORDER_PENDING (the IOC may still be unconfirmed), never "nothing
+ *    filled"; a failed read is never zero.
+ *
+ * Venue-final IOC outcome (design §13.10 #4): when the spot adapter is IocOutcomeCapable
+ * and iocOutcomeOf(result) reports the order's FINAL filled size, that report is used in
+ * preference to the balance delta, cross-checked against a fresh base-balance delta:
+ *  - final 0 and the balance did not move (≤ one lot) → ORDER_REJECTED (definite);
+ *    the balance DID move → the measured delta is used (discrepancy logged to stderr);
+ *  - final > 0 → filledSize = the reported size when the delta is ≥ 80% of it (base-token
+ *    fees), else ORDER_PENDING; an unreadable balance → ORDER_PENDING.
+ */
+import { type SpotAdapter, type SpotBalance } from "./spot-interface.js";
+export interface SpotFill {
+    status: "filled" | "partial";
+    /** Base units actually filled (> 0). */
+    filledSize: number;
+    avgPrice: number | null;
+    orderId: string | null;
+    /** The adapter's raw result (for logs). */
+    raw: unknown;
+}
+/**
+ * Interpret a spot order result. `measuredFill` = base balance delta measured around
+ * the order (null when not measured); used only for results that carry no fill report.
+ */
+export declare function interpretSpotFill(venue: string, symbol: string, result: unknown, requestedSize: number, measuredFill: number | null): SpotFill;
+/**
+ * Uncached spot balances: getSpotBalancesFresh() on adapters whose getSpotBalances()
+ * is TTL-cached (SpotFreshBalancesCapable contract), getSpotBalances() on adapters that
+ * read live. Use for fill measurement and post-trade verification. Throws on failure.
+ */
+export declare function readSpotBalancesFresh(spot: SpotAdapter): Promise<SpotBalance[]>;
+/**
+ * Place a spot market order and return what filled (see header). The base balance is
+ * read before the order so venues without a fill report can be measured; a failure of
+ * that read aborts BEFORE anything is placed. After the order, errors never throw a
+ * retryable error: an unreadable outcome is ORDER_PENDING.
+ */
+export declare function spotMarketFill(spot: SpotAdapter, symbol: string, side: "buy" | "sell", size: string, stepSize?: string | null): Promise<SpotFill>;
+/** Decimal string for a filled size (no exponent), floored to `decimals`. */
+export declare function fillSizeString(filled: number, decimals: number): string;
+/** Decimal places of a plain decimal size string ("0.0100" → 4). */
+export declare function sizeDecimalsOf(size: string): number;
+/**
+ * Spot lot step (10^-sizeDecimals) from the venue's spot market info. `symbol` is "BASE/QUOTE"
+ * or a bare base; a bare base whose markets disagree on the lot, or an unknown market, throws
+ * (Rule #2: never size off the typed decimals).
+ */
+export declare function spotLotStepOf(spot: SpotAdapter, symbol: string): Promise<string>;