perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/venues/pacifica.js

@@ -0,0 +1,95 @@
+/**
+ * Pacifica venue definition (design §10.1, §10.8, §10.13 #4).
+ * Adapter + public-data code are loaded lazily (§10.10).
+ */
+import { BUILDER_FEE_CAPABILITIES } from "../builder-fee.js";
+const publicData = {
+    async fetchFundingRates(net) {
+        return (await import("../../funding/legacy-public.js")).legacyPublicData("pacifica").fetchFundingRates(net);
+    },
+    async fetchMarkets(net) {
+        return (await import("../../funding/legacy-public.js")).legacyPublicData("pacifica").fetchMarkets(net);
+    },
+};
+/** Pacifica `client_order_id` format: "Full UUID string" (docs.pacifica.fi rest-api orders/create-limit-order). */
+export const PACIFICA_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const pacificaVenue = {
+    id: "pacifica",
+    aliases: ["pac"],
+    displayName: "Pacifica",
+    family: "pacifica",
+    masterKeyKind: "solana",
+    agentKeyKind: "solana",
+    secretStorage: { kind: "ows-wallet", dir: null },
+    // URLs: src/pacifica/constants.ts
+    networks: {
+        mainnet: {
+            restUrl: "https://api.pacifica.fi/api/v1",
+            wsUrl: "wss://ws.pacifica.fi/ws",
+            explorerUrl: null,
+            signingChainId: null,
+            settlementChain: "solana",
+            collateral: ["USDC"],
+            collateralAssetIndex: null,
+            rpcUrl: null,
+            depositPins: null,
+        },
+        testnet: {
+            restUrl: "https://test-api.pacifica.fi/api/v1",
+            wsUrl: "wss://test-ws.pacifica.fi/ws",
+            explorerUrl: null,
+            signingChainId: null,
+            settlementChain: "solana",
+            collateral: ["USDC"],
+            collateralAssetIndex: null,
+            rpcUrl: null,
+            depositPins: null,
+        },
+    },
+    fundingRateBasis: { kind: "perHours", hours: 1 },
+    settlementIntervalHours: 1,
+    fundingVerified: true,
+    roles: ["marketData", "account", "trading"],
+    capabilities: {
+        marketOrder: "slippageBounded",
+        timeInForce: ["GTC", "IOC", "ALO", "TOB"],
+        reduceOnlyTif: null,
+        // docs.pacifica.fi rest-api orders/create-limit-order: `client_order_id` | Full UUID string |
+        // optional | "Client-defined order ID"; orders/cancel-order accepts `client_order_id`
+        // ("required (if no OID)"). CLI rule: V2_CLIENT_ID_RULES (commands/trade.ts) / PACIFICA_UUID_RE.
+        clientOrderId: true,
+        orderAck: "sync",
+        tpsl: "positionLevel",
+        amend: "native",
+        batchPlaceMax: null,
+        marginModes: ["cross", "isolated"],
+        withdrawAssets: ["USDC"],
+    },
+    // docs.pacifica.fi "Rate limits": "Pacifica uses a credit-based rate limiting system with a
+    // 60-second rolling window." Tier "Unidentified IP | 125" base credits/60s (valid API Config
+    // Key: 300); "Standard request/action | 1" credit.
+    // Declared only — per §10.9 the limiter is applied to new venues + lighter-rh.
+    rateLimit: { capacity: 125, refillPerSec: 125 / 60, weights: null },
+    restrictedRegions: [],
+    symbolIdentity: "baseTicker",
+    publicData,
+    // §12: spot (SOL-USDC) shares the perp account — USDC is perp margin, no transfer.
+    spot: {
+        accountModel: "unified",
+        quoteAssets: { mainnet: ["USDC"], testnet: ["USDC"] },
+        capabilities: { limitOrder: true, orderbook: true, cancel: true, transfer: false },
+        async createSpot(perp) {
+            const [{ PacificaAdapter }, { PacificaSpotAdapter }] = await Promise.all([
+                import("../pacifica.js"), import("../pacifica-spot.js"),
+            ]);
+            if (!(perp instanceof PacificaAdapter))
+                throw new Error(`pacifica spot needs a PacificaAdapter (got ${perp.name})`);
+            const spot = new PacificaSpotAdapter(perp);
+            await spot.init();
+            return spot;
+        },
+    },
+    maxSlippageBps: 5000,
+    builderFee: BUILDER_FEE_CAPABILITIES["pacifica"],
+    create: async (ctx) => (await import("./create-helpers.js")).createPacifica(ctx),
+};

package/dist/exchanges/venues/qfex.d.ts

@@ -0,0 +1,28 @@
+/**
+ * QFEX venue definition (design §14.1 as amended by §14.12).
+ *
+ * TradFi perpetuals (equities, indices, commodities; no spot) on a custodial, off-chain
+ * matching engine. All markets are cross-margin, margin asset USDC. Orders go over the Trade
+ * WebSocket only; account reads, leverage and transfers over REST; deposits / withdrawals over
+ * the separate "banker" host. Hot-path key = HMAC API key created on the QFEX website (2FA),
+ * stored in ~/.perp/qfex-agents/<publicKey>.json (SSOT Rule #3). There is no wallet signature.
+ * Not registered here; the registry module owns registerVenue().
+ */
+import type { VenueDefinition } from "../venue.js";
+import type { Network } from "../venue-types.js";
+/**
+ * Hosts per network. VenueNetworkConfig carries only two (rest + ws), so the MDS and banker
+ * hosts live here. Testnet = QFEX "UAT": "identical API and behaviour, separate exchange
+ * instance with no real funds" (official CLI README "Environments").
+ */
+export declare const QFEX_ENDPOINTS: Readonly<Record<Network, {
+    rest: string;
+    tradeWs: string;
+    mdsWs: string;
+    banker: string;
+}>>;
+/** Chain QFEX USDC deposits / withdrawals use in perp-cli (banker network ARBITRUM_ONE). */
+export declare const QFEX_WITHDRAW_NETWORK = "arbitrum";
+/** Banker `network` value for QFEX_WITHDRAW_NETWORK. */
+export declare const QFEX_BANKER_NETWORK = "ARBITRUM_ONE";
+export declare const qfexVenue: VenueDefinition;

package/dist/exchanges/venues/qfex.js

@@ -0,0 +1,132 @@
+/**
+ * QFEX venue definition (design §14.1 as amended by §14.12).
+ *
+ * TradFi perpetuals (equities, indices, commodities; no spot) on a custodial, off-chain
+ * matching engine. All markets are cross-margin, margin asset USDC. Orders go over the Trade
+ * WebSocket only; account reads, leverage and transfers over REST; deposits / withdrawals over
+ * the separate "banker" host. Hot-path key = HMAC API key created on the QFEX website (2FA),
+ * stored in ~/.perp/qfex-agents/<publicKey>.json (SSOT Rule #3). There is no wallet signature.
+ * Not registered here; the registry module owns registerVenue().
+ */
+import { BUILDER_FEE_CAPABILITIES } from "../builder-fee.js";
+import { QFEX_MODIFY_KEEPS_CLIENT_ID, QFEX_RESTING_REDUCE_ONLY_VERIFIED } from "../qfex/signing.js";
+/**
+ * Hosts per network. VenueNetworkConfig carries only two (rest + ws), so the MDS and banker
+ * hosts live here. Testnet = QFEX "UAT": "identical API and behaviour, separate exchange
+ * instance with no real funds" (official CLI README "Environments").
+ */
+export const QFEX_ENDPOINTS = {
+    mainnet: { rest: "https://api.qfex.com", tradeWs: "wss://trade.qfex.com", mdsWs: "wss://mds.qfex.com", banker: "https://banker.qfex.com" },
+    testnet: { rest: "https://api.qfex.io", tradeWs: "wss://trade.qfex.io", mdsWs: "wss://mds.qfex.io", banker: "https://banker.qfex.io" },
+};
+/** Chain QFEX USDC deposits / withdrawals use in perp-cli (banker network ARBITRUM_ONE). */
+export const QFEX_WITHDRAW_NETWORK = "arbitrum";
+/** Banker `network` value for QFEX_WITHDRAW_NETWORK. */
+export const QFEX_BANKER_NETWORK = "ARBITRUM_ONE";
+/** Lazy: public.ts (and `ws`) is only loaded when market data is actually requested. */
+const publicData = {
+    async fetchFundingRates(net) {
+        return (await import("../qfex/public.js")).qfexPublicData.fetchFundingRates(net);
+    },
+    async fetchMarkets(net) {
+        return (await import("../qfex/public.js")).qfexPublicData.fetchMarkets(net);
+    },
+};
+function network(net) {
+    return {
+        restUrl: QFEX_ENDPOINTS[net].rest,
+        wsUrl: QFEX_ENDPOINTS[net].tradeWs,
+        explorerUrl: null,
+        signingChainId: null,
+        settlementChain: "offchain",
+        collateral: ["USDC"],
+        collateralAssetIndex: null,
+        rpcUrl: null,
+        depositPins: null,
+    };
+}
+export const qfexVenue = {
+    id: "qfex",
+    aliases: ["qf"],
+    displayName: "QFEX",
+    family: "qfex",
+    // Custodial: there is no owner-wallet signing path at all.
+    masterKeyKind: "none",
+    agentKeyKind: "hmac",
+    secretStorage: { kind: "perp-keystore", dir: "qfex-agents" },
+    networks: { mainnet: network("mainnet"), testnet: network("testnet") },
+    // Docs /qfex/funding: settled every 60 minutes.
+    fundingRateBasis: { kind: "perHours", hours: 1 },
+    settlementIntervalHours: 1,
+    // Q4: the unit of `funding_rate` (and funding_rate vs next_funding_rate) is not verified
+    // against settled payments, and equity funding accrues only ~120 of 168 hours a week, so
+    // hourly × 8760 overstates it. Until both are settled QFEX is not a funding-arb venue.
+    fundingVerified: false,
+    roles: ["marketData", "account", "trading"],
+    capabilities: {
+        // The venue offers a native MARKET order (bounded only by the price band — docs /qfex/risk-limits
+        // "Dynamic price bands": 1.65%–10% by product preset and session; "integrations should use
+        // that live value rather than hardcoding a percentage"); the
+        // adapter sends every market order as an IOC LIMIT at the tick-aligned protection price
+        // (mark ± resolved slippage, design §13.2) — the same declaration as Ondo.
+        marketOrder: "native",
+        // ALO = order_type "ALO" + GTC.
+        timeInForce: ["GTC", "IOC", "FOK", "ALO"],
+        // Reduce-only (Q2, production 2026-10-05: `reduce_only` is a JSON boolean; rejected with no
+        // position, but an order larger than the position is accepted and RESTS at full size). The
+        // adapter enforces side and size against the live position before each send, which covers
+        // an immediate order only — a resting one is refused until match-time capping is proven
+        // (QFEX_RESTING_REDUCE_ONLY_VERIFIED, qfex/signing.ts).
+        reduceOnlyTif: QFEX_RESTING_REDUCE_ONLY_VERIFIED === true ? null : ["IOC"],
+        clientOrderId: true,
+        // The ACK arrives first; fills / rejections follow as separate events. Client order ids
+        // are GENERATED only (venue ids are not unique) — a user --client-id is refused.
+        orderAck: "async",
+        // Attached take_profit / stop_loss exists on add_order, but the stop quantity on a partial
+        // or zero-fill entry and the id of the resulting stop are unverified (Q7) → separate
+        // reduce-only TAKE_PROFIT / STOP_LOSS stop orders sized to the verified fill (Q21 passed on
+        // production 2026-10-12: the stop ACK echoes the client id — qfex/signing.ts QFEX_STOP_CLIENT_ID_ECHO).
+        tpsl: "separateOrders",
+        // modify_order returns a NEW order id; the MODIFIED frame keeps the client id (Q5, production
+        // 2026-10-12 — QFEX_MODIFY_KEEPS_CLIENT_ID) → native amend correlated by client id.
+        amend: QFEX_MODIFY_KEEPS_CLIENT_ID === true ? "native" : null,
+        batchPlaceMax: null,
+        marginModes: ["cross"],
+        // TRON USDT and USD bank rails are out of scope.
+        withdrawAssets: ["USDC"],
+    },
+    // Venue budget: 12,000 weight / 60 s per USER across all connections and keys (general and
+    // cancel buckets separate). This process takes 25% (50/s, burst 100); the rest is left to the
+    // user's other processes, the QFEX web app and the official CLI. Weights: docs /websocket/rate.
+    rateLimit: {
+        capacity: 100,
+        refillPerSec: 50,
+        weights: {
+            add_order: 1, cancel_order: 1, modify_order: 1, get_order: 2, get_user_orders: 5, cancel_all_orders: 2,
+            get_user_trades: 0.5, subscribe: 0.1, unsubscribe: 0.1, set_user_leverage: 0.1, cancel_stop_order: 1,
+            modify_stop_order: 1,
+        },
+    },
+    // Docs /qfex/faq + prohibited-jurisdictions ("including but not limited to"). Warn-only.
+    restrictedRegions: ["US", "GB", "ES", "UA", "SY", "IR", "RU", "KP", "MM", "BY", "VE", "SD"],
+    symbolIdentity: "explicit",
+    publicData,
+    spot: null,
+    // Widest documented price band (equities at the open: 10%). The order's own band is checked before sending.
+    maxSlippageBps: 1000,
+    builderFee: BUILDER_FEE_CAPABILITIES["qfex"],
+    create: async (ctx) => {
+        const { QfexAdapter } = await import("../qfex/adapter.js");
+        const adapter = new QfexAdapter(qfexVenue, ctx);
+        // Builder code: only settings builder.qfex (off by default); no approval step. It rides on
+        // the connection's auth, so --no-builder / testnet use a session without it.
+        const { loadSettings } = await import("../../settings.js");
+        const { resolveBuilderGate } = await import("../builder-fee.js");
+        const settings = loadSettings();
+        adapter.builderFee = resolveBuilderGate("qfex", ctx, settings.builder, null, () => "");
+        // Withdraw gate (settings.withdraw.qfex): absent = withdraw() refuses.
+        const gate = settings.withdraw.qfex;
+        adapter.withdrawGate = gate === undefined ? null : gate;
+        return adapter;
+    },
+};

package/dist/execution-log.js

@@ -11,13 +11,21 @@ function genId() {
 }
 /** Append an execution record to the log */
 export function logExecution(record) {
-    ensureDir();
     const full = {
         id: genId(),
         timestamp: new Date().toISOString(),
         ...record,
     };
-    appendFileSync(LOG_FILE, JSON.stringify(full) + "\n", { mode: 0o600 });
+    // The log is a record OF an outcome, never part of it: a write failure (disk full, read-only
+    // home, permissions) must not turn a filled order into a thrown "failed" one. It is reported
+    // on stderr and the caller continues with the real result.
+    try {
+        ensureDir();
+        appendFileSync(LOG_FILE, JSON.stringify(full) + "\n", { mode: 0o600 });
+    }
+    catch (e) {
+        process.stderr.write(`[perp] Warning: could not write the execution log (${LOG_FILE}): ${e instanceof Error ? e.message : String(e)} — the ${record.type} on ${record.exchange} was recorded as "${record.status}" in memory only\n`);
+    }
     return full;
 }
 /** Read execution log with optional filters */

package/dist/funding/legacy-public.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Public market data for the legacy venues without a native `getVenueMarkets`
+ * (pacifica, hyperliquid core, aster) — design §10.6. Lighter uses
+ * exchanges/lighter-public.ts.
+ *
+ * Network-aware: the REST base comes from `legacyPublicBaseUrl(venue, net)`,
+ * never from the mutable `*_API_URL` globals. A network without a known public
+ * API throws NOT_IMPLEMENTED.
+ *
+ * FUNDING BASIS / SETTLEMENT
+ *   pacifica, hyperliquid: the venue definition (fundingBasisOf / settlementIntervalOf).
+ *   aster: per symbol from GET /fapi/v3/fundingInfo `fundingIntervalHours`
+ *     (live 2026-09-30: 1h/2h/4h/8h mixed). One quoted rate covers one interval,
+ *     so basis hours == settlement hours. A symbol missing from fundingInfo is
+ *     excluded with a warning (its period would be a guess).
+ *
+ * ASSET CLASS
+ *   hyperliquid core: crypto (HIP-3 dexes are not served here).
+ *   pacifica: crypto-centric; PACIFICA_NON_CRYPTO lists every non-crypto perp
+ *     listed on 2026-09-30.
+ *   aster: exchangeInfo `underlyingSubType` (STOCK / ETF / Commodities / pre-launch).
+ *   AMBIGUOUS tickers are excluded with a warning so they cannot produce a false
+ *   cross-venue match (SPX = the SPX6900 token, whose ticker equals the S&P 500
+ *   canonical key).
+ *
+ * Fields a venue does not publish on this path are null (HL has no fixed tick
+ * size; Aster leverage brackets need a signed call; Aster OI is per-symbol only).
+ */
+import type { VenuePublicData } from "../exchanges/venue.js";
+export type LegacyPublicVenue = "pacifica" | "hyperliquid" | "aster";
+export declare function legacyPublicData(venue: LegacyPublicVenue): VenuePublicData;