perp-cli 0.14.2 → 0.15.0

package/dist/exchanges/pacifica-vaults.js

@@ -0,0 +1,264 @@
+/**
+ * Pacifica vaults ("lakes" in the API) — docs.pacifica.fi/vaults.md and pages under it,
+ * api-documentation/api/rest-api/vaults/*.
+ *
+ * Product: a vault is a real Pacifica account traded by its manager; depositors (LPs) get LP
+ * shares at NAV (lp_balance ÷ lp_shares, 1:1 when the LP class is empty). PnL is attributed to the
+ * LP / manager classes before every deposit or withdrawal; the manager takes `manager_profit_share`
+ * of profit above the high-water mark. Minimum deposit 10 USDC; `deposit_cap` caps the LP balance
+ * (manager deposits are not counted). A withdrawal redeems shares (amount = shares × NAV) straight
+ * into the depositor's own trading balance — the API has no destination field — and is allowed
+ * only when: enough shares; `deposit_min_duration_ms` elapsed since the depositor's LAST deposit
+ * (each deposit resets the lock for the whole balance); inside the withdrawal window when
+ * `withdraw_window_s` / `withdraw_duration_s` are set (open while now_s mod window < duration,
+ * epoch-anchored); and the vault has free balance (a fully deployed vault may pay partially).
+ * The venue publishes no APY: `apy` is null.
+ *
+ * Endpoints (GET unauthenticated; writes signed):
+ *   GET  /lake/list[?account=]                       vaults (+ the account's `user_share`)
+ *   GET  /lake/get_deposit_whitelist?lake=           deposit-address whitelist (app.pacifica.fi; not in the API docs)
+ *   GET  /account?account=<vault> · /positions       the vault account's live equity / positions
+ *   POST /lake/deposit   type deposit_to_lake        {lake, amount, idempotency_key?}
+ *   POST /lake/withdraw  type withdraw_from_lake     {lake, shares, idempotency_key?}
+ * Live 2026-10-19: absent config fields are omitted (→ null here), and `user_share` was null for a
+ * vault's own manager (it counts LP shares; the manager's are `manager_shares`).
+ */
+import { PerpError } from "../errors.js";
+import { mulDecimal, subDecimal } from "./precision.js";
+import { cmpDecimal, divDecimal, isPlainDecimal, trimDecimal } from "./pacifica-decimal.js";
+import { envelopeData, requireUsdcAmount, PLAIN_POSITIVE } from "./pacifica-print.js";
+import { buildPresigned } from "./pacifica-presigned.js";
+/** docs vaults/depositing: "Minimum deposit — Constant 10 USDC." */
+export const VAULT_MIN_DEPOSIT_USDC = "10";
+function bad(what, row) {
+    return new PerpError("EXCHANGE_ERROR", `Pacifica ${what}: ${JSON.stringify(row).slice(0, 200)}`, { exchange: "pacifica" });
+}
+function str(r, k) {
+    const v = r[k];
+    return typeof v === "string" && v !== "" ? v : null;
+}
+function dec(r, k) {
+    const v = r[k];
+    return isPlainDecimal(v) ? trimDecimal(v) : null;
+}
+function reqDec(r, k) {
+    const v = dec(r, k);
+    if (v === null)
+        throw bad(`/lake/list row without a decimal ${k}`, r);
+    return v;
+}
+function int(r, k) {
+    const v = r[k];
+    return typeof v === "number" && Number.isInteger(v) ? v : null;
+}
+function add(a, b) {
+    return subDecimal(a, `-${b}`.replace(/^--/, ""));
+}
+function parseConfig(x) {
+    const c = x !== null && typeof x === "object" && !Array.isArray(x) ? x : {};
+    return {
+        depositCap: dec(c, "deposit_cap"),
+        managerProfitShare: dec(c, "manager_profit_share"),
+        managerLossShare: dec(c, "manager_loss_share"),
+        depositMinDurationMs: int(c, "deposit_min_duration_ms"),
+        managerMinBalancePortion: dec(c, "manager_min_balance_portion"),
+        managerLiquidationBalancePortion: dec(c, "manager_liquidation_balance_portion"),
+        withdrawWindowS: int(c, "withdraw_window_s"),
+        withdrawDurationS: int(c, "withdraw_duration_s"),
+    };
+}
+export function parseVault(x) {
+    if (x === null || typeof x !== "object" || Array.isArray(x))
+        throw bad("/lake/list row is not an object", x);
+    const r = x;
+    const address = str(r, "address");
+    if (address === null)
+        throw bad("/lake/list row without an address", r);
+    const lpShares = reqDec(r, "lp_shares");
+    const managerShares = reqDec(r, "manager_shares");
+    const lpBalance = reqDec(r, "lp_balance");
+    const managerBalance = reqDec(r, "manager_balance");
+    const created = r.created_at;
+    return {
+        schema: 1,
+        address,
+        nickname: str(r, "nickname"),
+        creator: str(r, "creator"),
+        manager: str(r, "manager"),
+        referrer: str(r, "referrer"),
+        createdAt: typeof created === "number" && created > 0 ? created : null,
+        lpShares, managerShares, lpBalance, managerBalance,
+        tvl: add(lpBalance, managerBalance),
+        equitySnapshot: dec(r, "last_checked_equity"),
+        highWatermark: dec(r, "high_watermark"),
+        navPerLpShare: divDecimal(lpBalance, lpShares, 12),
+        navPerManagerShare: divDecimal(managerBalance, managerShares, 12),
+        apy: null,
+        config: parseConfig(r.config),
+        userShares: dec(r, "user_share"),
+    };
+}
+/** GET /lake/list `data` (`{lakes: [...]}`). */
+export function parseVaultList(data) {
+    const rows = data !== null && typeof data === "object" && !Array.isArray(data) ? data.lakes : undefined;
+    if (!Array.isArray(rows))
+        throw bad("/lake/list without a lakes list", data);
+    return rows.map(parseVault);
+}
+export async function fetchVaults(client, account) {
+    const env = await client.getEnvelope("/lake/list", account !== null ? { account } : {});
+    return parseVaultList(envelopeData(env, "/lake/list"));
+}
+/**
+ * Vault by address, or by a nickname (case-insensitive) that matches EXACTLY ONE vault. Nicknames
+ * are not unique in practice (live 2026-10-19: "Pacifica Vault" / "Pacifica vault", "Shark vault" /
+ * "shark vault"), so two or more matches are INVALID_PARAMS listing every candidate — never the
+ * first / newest one (a copycat vault must not receive a deposit).
+ */
+export function findVault(vaults, ref) {
+    const r = ref.trim();
+    const byAddress = vaults.find((x) => x.address === r);
+    if (byAddress !== undefined)
+        return byAddress;
+    const matches = vaults.filter((x) => x.nickname !== null && x.nickname.toLowerCase() === r.toLowerCase());
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length === 0) {
+        throw new PerpError("SYMBOL_NOT_FOUND", `No Pacifica vault "${ref}" (address or nickname)`, {
+            exchange: "pacifica", remediation: "List them: perp -e pacifica vault list",
+        });
+    }
+    const candidates = matches.map((x) => ({ address: x.address, nickname: x.nickname, manager: x.manager, tvl: x.tvl }));
+    throw new PerpError("INVALID_PARAMS", `Vault nickname "${ref}" is ambiguous — ${matches.length} vaults match: ${candidates.map((c) => `${c.address} (${c.nickname}, manager ${c.manager ?? "none"}, TVL ${c.tvl})`).join("; ")}`, {
+        exchange: "pacifica", candidates, remediation: "Pass the vault ADDRESS (check its manager first: perp -e pacifica vault info <address>)",
+    });
+}
+/** UNOFFICIAL endpoint (not in the API docs; used by app.pacifica.fi). Advisory only — the venue's own refusal is final. */
+export const DEPOSIT_WHITELIST_API_STATUS = "unofficial";
+export async function fetchDepositWhitelist(client, vault) {
+    const data = envelopeData(await client.getEnvelope("/lake/get_deposit_whitelist", { lake: vault }), "/lake/get_deposit_whitelist");
+    const a = data !== null && typeof data === "object" ? data.addresses : undefined;
+    if (!Array.isArray(a) || !a.every((s) => typeof s === "string"))
+        throw bad("/lake/get_deposit_whitelist without an addresses list", data);
+    return a;
+}
+/** docs: open while current_unix_time_s mod withdraw_window_s < withdraw_duration_s (epoch-anchored). */
+export function withdrawWindowAt(c, nowMs) {
+    if (c.withdrawWindowS === null || c.withdrawDurationS === null || c.withdrawWindowS <= 0)
+        return { restricted: false, open: true, nextChangeAt: null };
+    const now = Math.floor(nowMs / 1000);
+    const start = now - (now % c.withdrawWindowS);
+    const open = now % c.withdrawWindowS < c.withdrawDurationS;
+    return { restricted: true, open, nextChangeAt: (open ? start + c.withdrawDurationS : start + c.withdrawWindowS) * 1000 };
+}
+/** Shares this account holds in the vault: manager shares for the manager, else LP `user_share`. */
+export function heldShares(v, account) {
+    if (v.manager === account)
+        return { role: "manager", shares: v.managerShares, nav: v.navPerManagerShare };
+    return { role: "lp", shares: v.userShares, nav: v.navPerLpShare };
+}
+/**
+ * Validate a deposit (docs vaults/depositing: min 10 USDC, deposit cap on the LP balance,
+ * available_to_withdraw, deposit whitelist). Throws INVALID_PARAMS / INSUFFICIENT_BALANCE / POLICY_DENIED.
+ */
+export function planVaultDeposit(v, account, amountRaw, ctx) {
+    const amount = requireUsdcAmount(amountRaw, "vault deposit");
+    const where = `vault ${v.nickname ?? v.address}`;
+    if (cmpDecimal(amount, VAULT_MIN_DEPOSIT_USDC) < 0) {
+        throw new PerpError("INVALID_PARAMS", `${where}: deposit ${amount} USDC is below the ${VAULT_MIN_DEPOSIT_USDC} USDC minimum`, { exchange: "pacifica", remediation: `Deposit at least ${VAULT_MIN_DEPOSIT_USDC} USDC` });
+    }
+    const { role } = heldShares(v, account);
+    // NAV of the class receiving the deposit must be defined and positive (docs: shares = amount ×
+    // shares ÷ balance; 1:1 only when the class is EMPTY). Live: XAU_Stable_Growth had lp_shares 10,
+    // lp_balance 0 — a deposit there would be priced at NAV 0.
+    const [clsShares, clsBalance] = role === "lp" ? [v.lpShares, v.lpBalance] : [v.managerShares, v.managerBalance];
+    const sharesZero = cmpDecimal(clsShares, "0") === 0;
+    if (sharesZero ? cmpDecimal(clsBalance, "0") !== 0 : cmpDecimal(clsBalance, "0") <= 0) {
+        throw new PerpError("INVALID_PARAMS", `${where}: ${role} NAV is ${sharesZero ? "undefined" : "zero"} (${role} shares ${clsShares}, balance ${clsBalance}) — a deposit cannot be priced`, {
+            exchange: "pacifica", remediation: "Pick another vault (perp -e pacifica vault list)",
+        });
+    }
+    if (role === "lp" && v.config.depositCap !== null && cmpDecimal(add(v.lpBalance, amount), v.config.depositCap) > 0) {
+        throw new PerpError("INVALID_PARAMS", `${where}: LP balance ${v.lpBalance} + ${amount} exceeds the deposit cap ${v.config.depositCap} USDC`, {
+            exchange: "pacifica", remediation: `Deposit at most ${subDecimal(v.config.depositCap, v.lpBalance)} USDC`,
+        });
+    }
+    if (cmpDecimal(ctx.availableToWithdraw, amount) < 0) {
+        throw new PerpError("INSUFFICIENT_BALANCE", `${where}: deposit ${amount} USDC exceeds available_to_withdraw ${ctx.availableToWithdraw}`, { exchange: "pacifica", remediation: "Deposit less, or free margin first (perp -e pacifica portfolio)" });
+    }
+    const warnings = [
+        "A vault is a third-party trading pool: you can lose up to the whole deposit (Pacifica does not vet or insure managers).",
+        `Manager: ${v.manager ?? "none"} — verify this address is the manager you intend to fund.`,
+    ];
+    // Unofficial whitelist endpoint: advisory only; the venue's refusal is final.
+    if (ctx.whitelist === null)
+        warnings.push("Deposit whitelist unknown (unofficial endpoint unreadable); the venue refuses if the vault restricts depositors.");
+    else if (ctx.whitelist.length > 0 && !ctx.whitelist.includes(account))
+        warnings.push(`The vault's deposit whitelist (unofficial endpoint) lists ${ctx.whitelist.length} address(es), not ${account}: the venue will likely refuse.`);
+    const lock = v.config.depositMinDurationMs;
+    if (lock !== null && lock > 0)
+        warnings.push(`Lock-up: no withdrawal for ${(lock / 3_600_000).toFixed(2)} h after this deposit — and the timer restarts for your WHOLE balance in this vault.`);
+    if (v.config.withdrawWindowS !== null && v.config.withdrawDurationS !== null) {
+        warnings.push(`Withdrawals open only ${v.config.withdrawDurationS} s out of every ${v.config.withdrawWindowS} s (epoch-anchored window).`);
+    }
+    if (v.manager === null)
+        warnings.push("The vault has no manager yet (fresh vault): nobody trades it until a manager claims the seat.");
+    if (v.config.managerProfitShare !== null)
+        warnings.push(`Manager performance fee: ${v.config.managerProfitShare} of profit above the high-water mark.`);
+    return {
+        schema: 1, vault: v.address, nickname: v.nickname, manager: v.manager, role, amount,
+        // docs: shares_minted = amount × shares ÷ balance of the class (1:1 when the class is empty)
+        estimatedShares: role === "lp"
+            ? (cmpDecimal(v.lpShares, "0") === 0 ? amount : divDecimal(mulDecimal(amount, v.lpShares), v.lpBalance, 6))
+            : (cmpDecimal(v.managerShares, "0") === 0 ? amount : divDecimal(mulDecimal(amount, v.managerShares), v.managerBalance, 6)),
+        lockMs: lock, warnings,
+    };
+}
+/** Validate a withdrawal: shares held, withdrawal window. Throws POSITION_NOT_FOUND / INVALID_PARAMS / POLICY_DENIED. */
+export function planVaultWithdraw(v, account, sharesRaw, ctx) {
+    const where = `vault ${v.nickname ?? v.address}`;
+    const held = heldShares(v, account);
+    if (held.shares === null || cmpDecimal(held.shares, "0") <= 0) {
+        throw new PerpError("POSITION_NOT_FOUND", `${account} holds no ${held.role} shares in ${where}`, { exchange: "pacifica", remediation: "See your vault positions: perp -e pacifica vault positions" });
+    }
+    let shares;
+    if (sharesRaw === "all")
+        shares = held.shares;
+    else {
+        const s = String(sharesRaw).trim();
+        if (!PLAIN_POSITIVE.test(s) || !(Number(s) > 0))
+            throw new PerpError("INVALID_PARAMS", `shares must be a positive decimal number without leading zeros (got "${sharesRaw}")`, { exchange: "pacifica", remediation: "Pass the shares to redeem, or --all" });
+        shares = trimDecimal(s);
+    }
+    if (cmpDecimal(shares, held.shares) > 0) {
+        throw new PerpError("SIZE_TOO_LARGE", `${where}: redeeming ${shares} shares exceeds the ${held.shares} held`, { exchange: "pacifica", remediation: `Redeem at most ${held.shares} (or --all)` });
+    }
+    const window = withdrawWindowAt(v.config, ctx.nowMs);
+    if (!window.open) {
+        throw new PerpError("POLICY_DENIED", `${where}: the withdrawal window is closed; it next opens at ${new Date(window.nextChangeAt).toISOString()}`, {
+            exchange: "pacifica", remediation: "Withdraw while the window is open (perp -e pacifica vault info <vault> shows it)",
+        });
+    }
+    const estimatedAmount = held.nav === null ? null : trimDecimal(mulDecimal(shares, held.nav));
+    const warnings = [];
+    const lock = v.config.depositMinDurationMs;
+    if (lock !== null && lock > 0)
+        warnings.push(`The venue refuses a withdrawal within ${(lock / 3_600_000).toFixed(2)} h of your most recent deposit into this vault (not checkable here).`);
+    if (estimatedAmount !== null && ctx.vaultAvailableToWithdraw !== null && cmpDecimal(estimatedAmount, ctx.vaultAvailableToWithdraw) > 0) {
+        warnings.push(`The vault's free balance ${ctx.vaultAvailableToWithdraw} USDC is below the ≈${estimatedAmount} USDC redeemed: the venue may pay only part.`);
+    }
+    return { schema: 1, vault: v.address, nickname: v.nickname, manager: v.manager, role: held.role, shares, heldShares: held.shares, estimatedAmount, destination: account, window, warnings };
+}
+// ── Write requests (pure) ───────────────────────────────────────────────
+export function buildVaultDepositRequest(vault, amount, identity, opts) {
+    return buildPresigned({
+        type: "deposit_to_lake", path: "/lake/deposit", identity, timestamp: opts.timestamp, expiryWindow: opts.expiryWindow,
+        payload: { lake: vault, amount, idempotency_key: opts.idempotencyKey },
+    });
+}
+export function buildVaultWithdrawRequest(vault, shares, identity, opts) {
+    return buildPresigned({
+        type: "withdraw_from_lake", path: "/lake/withdraw", identity, timestamp: opts.timestamp, expiryWindow: opts.expiryWindow,
+        payload: { lake: vault, shares, idempotency_key: opts.idempotencyKey },
+    });
+}

package/dist/exchanges/pacifica.d.ts

@@ -1,6 +1,6 @@
 import { Keypair } from "@solana/web3.js";
 import { PacificaClient, type Network } from "../pacifica/index.js";
-import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
+import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangePublicTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
 import type { ResolvedSlippage } from "./slippage.js";
 import type { SolanaSigner } from "../signer/index.js";
 import type { AgentMeta } from "../settings.js";
@@ -8,7 +8,7 @@ import type { TimeInForce as PacificaTif } from "../pacifica/types/order.js";
 import type { IocOutcome } from "./ioc-outcome.js";
 import { type BuilderApproval, type BuilderDecision, type BuilderFeeGate, type BuilderTarget } from "./builder-fee.js";
 /**
- * CLI TIF → Pacifica TIF (design §13.3). GTC / IOC / ALO / TOB are native; venue
+ * CLI TIF → Pacifica TIF. GTC / IOC / ALO / TOB are native; venue
  * aliases GTT → GTC and GTX → ALO; no TIF → GTC (uniform default). FOK (never
  * emulated) and unknown values → uniform CAPABILITY_UNSUPPORTED.
  */
@@ -114,6 +114,7 @@ export declare const PACIFICA_WITHDRAW_MIN_USDC = "1";
  * else (other status, unparseable body, already a PerpError) → `e` unchanged (outcome unknown).
  */
 export declare function pacificaWithdrawRejection(e: unknown, amount: string): unknown;
+/** A POST the venue refused with HTTP 4xx — incl. RATE_LIMITED (429 / pre-send throttle, nothing sent). */
 export declare function pacificaRefused(e: unknown): boolean;
 /** A cancel the venue refused (HTTP 4xx), settled from the order's own history_by_id rows. */
 export type PacificaCancelRefusal = {
@@ -156,6 +157,12 @@ export interface PacificaAmendResult {
 }
 /** Pacifica order_type of a stop / TP / SL order (stop_market, stop_limit, take_profit_*, stop_loss_*). */
 export declare function isPacificaStopType(type: string): boolean;
+/**
+ * Trade direction of a Pacifica fill `side` (position effect): open_long / close_short buy,
+ * open_short / close_long sell; bid / ask for rows that carry an order side. Anything else →
+ * EXCHANGE_ERROR (never a guessed direction). Used by the public tape and the account fills.
+ */
+export declare function pacificaFillSide(side: string, endpoint: string): "buy" | "sell";
 export declare class PacificaAdapter implements ExchangeAdapter {
     readonly name = "pacifica";
     readonly chain = "solana";
@@ -213,6 +220,17 @@ export declare class PacificaAdapter implements ExchangeAdapter {
      * mint) — never the agent, which cannot move funds.
      */
     masterSolanaSigner(): SolanaSigner;
+    /**
+     * The active signer for an account request whose body the caller builds itself (Print / vault
+     * writes): `account` (master address) and `agentWallet` (agent pubkey, or null when the master
+     * signs). Resolving it signs nothing. NO_SIGNER_AVAILABLE / AGENT_EXPIRED as `_resolveSigner`.
+     */
+    signingIdentity(): {
+        tier: "agent" | "master" | "pk";
+        account: string;
+        agentWallet: string | null;
+        signMessage: (msg: Uint8Array) => Promise<Uint8Array>;
+    };
     /** Access the underlying Keypair (only available with LocalSolanaSigner). */
     get keypair(): Keypair;
     private _getPrices;
@@ -251,7 +269,7 @@ export declare class PacificaAdapter implements ExchangeAdapter {
         clientOrderId?: string;
     }): Promise<unknown>;
     /**
-     * Venue-final outcome of a raw marketOrder() result (IocOutcomeCapable, design §13.10 #4),
+     * Venue-final outcome of a raw marketOrder() result (IocOutcomeCapable),
      * parsed from the result's content (so copies of it work): its `fillReport` — the terminal
      * history_by_id row (filled / cancelled / rejected) with a reported filled_amount — for the
      * same order id as the create response. null otherwise — reduce-only orders (not polled),
@@ -321,7 +339,7 @@ export declare class PacificaAdapter implements ExchangeAdapter {
      */
     editOrder(symbol: string, orderId: string, price: string, size: string): Promise<unknown>;
     /**
-     * Amend that keeps the order's TIF (design §13.4, §13.10 #10). `size` = new open size.
+     * Amend that keeps the order's TIF. `size` = new open size.
      * TIF = `tif` when the caller gives one, else the TIF encoded in the order's generated
      * client_order_id; unknown → uniform CAPABILITY_UNSUPPORTED (never guessed).
      *  - ALO: native edit (the venue re-creates the order as ALO, keeping its client_order_id).
@@ -368,7 +386,16 @@ export declare class PacificaAdapter implements ExchangeAdapter {
         assetId?: number;
         routeType?: number;
     }): Promise<unknown>;
-    getRecentTrades(symbol: string, _limit?: number): Promise<ExchangeTrade[]>;
+    /**
+     * Public tape (GET /trades). Every fill is listed TWICE — a `fulfill_taker` row and a
+     * `fulfill_maker` row, each with that party's position effect as `side` (live 2026-10-14:
+     * taker `open_short` paired with maker `close_short` at the same time / price / amount). The
+     * tape is the taker rows, with the taker's direction: open_long / close_short buy, open_short /
+     * close_long sell (the same mapping as the account fills, PACIFICA_FILL_*_SIDES). Was every row
+     * of both parties mapped through `side === "bid"` → all "sell". No de-duplication: two taker
+     * rows with equal time / price / amount are two fills (one order filling two makers).
+     */
+    getRecentTrades(symbol: string, _limit?: number): Promise<ExchangePublicTrade[]>;
     getFundingHistory(symbol: string, limit?: number): Promise<{
         time: number;
         rate: string;

package/dist/exchanges/pacifica.js

@@ -1,6 +1,10 @@
+import { nonEmptyOrListed, symbolNotFound } from "./unknown-symbol.js";
+import { withTapeSkipped } from "./interface.js";
 import { PacificaClient } from "../pacifica/index.js";
+import { isPacificaRateLimited } from "../pacifica/rate-limit.js";
 import { LocalSolanaSigner } from "../signer/index.js";
 import { isExpired } from "../agent-wallet/expiry.js";
+import { isPacificaPerpetual } from "../ws/pacifica-instrument.js";
 import { randomUUID } from "crypto";
 import { PerpError, extractErrorMessage, isDefiniteOrderFailure, orderNotSent, orderOutcomeUnknown } from "../errors.js";
 import { parseFiniteVenueNumber, venueRateField } from "../utils/numeric.js";
@@ -10,7 +14,7 @@ import { requireCapabilities } from "./venue.js";
 import { PACIFICA_UUID_RE, pacificaVenue } from "./venues/pacifica.js";
 import { approvalFromCeiling, builderGateOf, rateToBps, requireFeeBps, NO_BUILDER } from "./builder-fee.js";
 /**
- * CLI TIF → Pacifica TIF (design §13.3). GTC / IOC / ALO / TOB are native; venue
+ * CLI TIF → Pacifica TIF. GTC / IOC / ALO / TOB are native; venue
  * aliases GTT → GTC and GTX → ALO; no TIF → GTC (uniform default). FOK (never
  * emulated) and unknown values → uniform CAPABILITY_UNSUPPORTED.
  */
@@ -20,7 +24,7 @@ export function pacificaTif(tif) {
     return validateLegacyTif(pacificaVenue, requireCapabilities(pacificaVenue), tif);
 }
 /**
- * Generated client_order_id carrying the order's TIF (design §13.4, §13.10 #10, like Ondo's
+ * Generated client_order_id carrying the order's TIF (like Ondo's
  * `pcli-<p|n>-…`): Pacifica takes a full UUID and never returns the TIF (GET /orders has no
  * tif field), so amend recovers it from the id. Layout: a UUID v4 whose first 6 hex digits are
  * `5ac1f` + TIF code (1 GTC, 2 IOC, 3 ALO, 4 TOB). The native edit keeps the client_order_id.
@@ -274,7 +278,10 @@ export function pacificaWithdrawRejection(e, amount) {
     }
     return new PerpError("ACTION_REJECTED", `Pacifica withdraw ${amount} USDC refused (nothing was withdrawn): ${body.error}`, details);
 }
+/** A POST the venue refused with HTTP 4xx — incl. RATE_LIMITED (429 / pre-send throttle, nothing sent). */
 export function pacificaRefused(e) {
+    if (isPacificaRateLimited(e))
+        return true;
     return !(e instanceof PerpError) && /^POST \S+ failed \(4\d\d\)/.test(extractErrorMessage(e));
 }
 /**
@@ -320,13 +327,13 @@ function requireInstrumentType(rows) {
     }
     return rows;
 }
-/** Perp markets of /info (spot rows such as SOL-USDC excluded, design §12). */
+/** Perp markets of /info: instrument_type "perpetual" only (spot rows such as SOL-USDC, or any other type, excluded). */
 function perpInfoRows(rows) {
-    return requireInstrumentType(rows).filter((m) => m.instrument_type !== "spot");
+    return requireInstrumentType(rows).filter(isPacificaPerpetual);
 }
-/** Wire symbols of /info spot markets. */
-function spotInfoSymbols(rows) {
-    return new Set(requireInstrumentType(rows).filter((m) => m.instrument_type === "spot").map((m) => m.symbol));
+/** Wire symbols of /info markets that are not perps (spot, any other instrument_type). */
+function nonPerpInfoSymbols(rows) {
+    return new Set(requireInstrumentType(rows).filter((m) => !isPacificaPerpetual(m)).map((m) => m.symbol));
 }
 /** Pacifica order_type of a stop / TP / SL order (stop_market, stop_limit, take_profit_*, stop_loss_*). */
 export function isPacificaStopType(type) {
@@ -335,6 +342,18 @@ export function isPacificaStopType(type) {
 /** Fill sides of GET /trades/history (position effect) plus the order sides bid / ask. */
 const PACIFICA_FILL_BUY_SIDES = new Set(["open_long", "close_short", "bid"]);
 const PACIFICA_FILL_SELL_SIDES = new Set(["open_short", "close_long", "ask"]);
+/**
+ * Trade direction of a Pacifica fill `side` (position effect): open_long / close_short buy,
+ * open_short / close_long sell; bid / ask for rows that carry an order side. Anything else →
+ * EXCHANGE_ERROR (never a guessed direction). Used by the public tape and the account fills.
+ */
+export function pacificaFillSide(side, endpoint) {
+    if (PACIFICA_FILL_BUY_SIDES.has(side))
+        return "buy";
+    if (PACIFICA_FILL_SELL_SIDES.has(side))
+        return "sell";
+    throw new PerpError("EXCHANGE_ERROR", `Pacifica ${endpoint} row with unknown side "${side}"`, { exchange: "pacifica" });
+}
 /** `created_at` (ms) of a Pacifica history row; non-numeric → EXCHANGE_ERROR (never NaN). */
 function pacificaTime(row, endpoint) {
     const t = Number(pacificaField(row, "created_at", endpoint));
@@ -491,6 +510,15 @@ export class PacificaAdapter {
             remediation: "Select the master wallet (--ows <wallet> or perp wallet use <wallet>), or do it on the Pacifica website",
         });
     }
+    /**
+     * The active signer for an account request whose body the caller builds itself (Print / vault
+     * writes): `account` (master address) and `agentWallet` (agent pubkey, or null when the master
+     * signs). Resolving it signs nothing. NO_SIGNER_AVAILABLE / AGENT_EXPIRED as `_resolveSigner`.
+     */
+    signingIdentity() {
+        const r = this._resolveSigner();
+        return { tier: r.tier, account: this.account, agentWallet: r.tier === "agent" ? r.address : null, signMessage: (msg) => r.signer.signMessage(msg) };
+    }
     /** Access the underlying Keypair (only available with LocalSolanaSigner). */
     get keypair() {
         if (this._solanaSigner instanceof LocalSolanaSigner) {
@@ -552,7 +580,7 @@ export class PacificaAdapter {
             this._getPrices(),
         ]);
         const priceMap = new Map(prices.map((p) => [p.symbol, p]));
-        // /info also lists spot markets (e.g. SOL-USDC); those are not perps (§12).
+        // /info also lists spot markets (e.g. SOL-USDC); those are not perps.
         const result = perpInfoRows(markets).map((m) => {
             const p = priceMap.get(m.symbol);
             // Derive sizeDecimals from lot_size (e.g. "0.001" → 3, "1" → 0)
@@ -579,7 +607,12 @@ export class PacificaAdapter {
         return result;
     }
     async getOrderbook(symbol) {
-        const book = await this.client.getBook(symbol);
+        const book = await this.client.getBook(symbol).catch((e) => {
+            // GET /book for an unlisted symbol: HTTP 400 {"error":"Book not found: NOPE"} (live 2026-10-14).
+            if (e instanceof Error && /^GET \/book failed \(400\):.*Book not found/.test(e.message))
+                throw symbolNotFound("pacifica", symbol);
+            throw e;
+        });
         return {
             bids: book.l[0].map((e) => [e.p, e.a]),
             asks: book.l[1].map((e) => [e.p, e.a]),
@@ -736,8 +769,8 @@ export class PacificaAdapter {
             throw new Error("No private key configured — account data unavailable. Run: perp setup");
         // GET /orders covers every market; spot orders (SOL-USDC) belong to the spot adapter.
         const [orders, info] = await Promise.all([this.client.getOrders(this.account), this.client.getInfo()]);
-        const spotSymbols = spotInfoSymbols(info);
-        return orders.filter((o) => !spotSymbols.has(String(o.symbol))).map((o) => {
+        const nonPerp = nonPerpInfoSymbols(info);
+        return orders.filter((o) => !nonPerp.has(String(o.symbol))).map((o) => {
             const raw = o;
             return {
                 orderId: String(raw.order_id),
@@ -786,7 +819,7 @@ export class PacificaAdapter {
                         const filled = parseFloat(String(latest.filled_amount ?? "0"));
                         if (status === "filled" || filled > 0) {
                             // Terminal row (filled / cancelled remainder) with a reported filled_amount = the
-                            // order's final fill (design §13.10 #4). A non-terminal partial row is not final.
+                            // order's final fill. A non-terminal partial row is not final.
                             const reported = latest.filled_amount;
                             const terminal = status === "filled" || status === "cancelled" || status === "rejected";
                             if (terminal && reported !== undefined && reported !== null && String(reported).trim() !== ""
@@ -830,7 +863,7 @@ export class PacificaAdapter {
         return result;
     }
     /**
-     * Venue-final outcome of a raw marketOrder() result (IocOutcomeCapable, design §13.10 #4),
+     * Venue-final outcome of a raw marketOrder() result (IocOutcomeCapable),
      * parsed from the result's content (so copies of it work): its `fillReport` — the terminal
      * history_by_id row (filled / cancelled / rejected) with a reported filled_amount — for the
      * same order id as the create response. null otherwise — reduce-only orders (not polled),
@@ -891,7 +924,7 @@ export class PacificaAdapter {
      */
     async limitOrder(symbol, side, price, size, opts) {
         this.ensureSigner();
-        const tif = pacificaTif(opts?.tif); // §13.3 common mapping; FOK → CAPABILITY_UNSUPPORTED
+        const tif = pacificaTif(opts?.tif); // common mapping; FOK → CAPABILITY_UNSUPPORTED
         // The caller's client order id (validated UUID) is sent as given; without one a generated
         // client_order_id records the TIF for a later TIF-preserving amend. Either way the id sent
         // rides on the result (`clientOrderId`).
@@ -1034,7 +1067,7 @@ export class PacificaAdapter {
         return this.client.editOrder({ symbol, order_id: Number(orderId), price, amount: size }, this.account, this.signMessage);
     }
     /**
-     * Amend that keeps the order's TIF (design §13.4, §13.10 #10). `size` = new open size.
+     * Amend that keeps the order's TIF. `size` = new open size.
      * TIF = `tif` when the caller gives one, else the TIF encoded in the order's generated
      * client_order_id; unknown → uniform CAPABILITY_UNSUPPORTED (never guessed).
      *  - ALO: native edit (the venue re-creates the order as ALO, keeping its client_order_id).
@@ -1314,48 +1347,85 @@ export class PacificaAdapter {
         return this.client.withdraw({ amount }, this.account, (msg) => master.signMessage(msg))
             .catch((e) => { throw pacificaWithdrawRejection(e, amount); });
     }
+    /**
+     * Public tape (GET /trades). Every fill is listed TWICE — a `fulfill_taker` row and a
+     * `fulfill_maker` row, each with that party's position effect as `side` (live 2026-10-14:
+     * taker `open_short` paired with maker `close_short` at the same time / price / amount). The
+     * tape is the taker rows, with the taker's direction: open_long / close_short buy, open_short /
+     * close_long sell (the same mapping as the account fills, PACIFICA_FILL_*_SIDES). Was every row
+     * of both parties mapped through `side === "bid"` → all "sell". No de-duplication: two taker
+     * rows with equal time / price / amount are two fills (one order filling two makers).
+     */
     async getRecentTrades(symbol, _limit = 20) {
         const trades = await this.client.getTrades(symbol);
-        // Deduplicate by time+price+size+side (API sometimes returns duplicate entries)
-        const seen = new Set();
-        const unique = trades.filter((t) => {
-            const key = `${t.created_at}:${t.price}:${t.amount}:${t.side}`;
-            if (seen.has(key))
-                return false;
-            seen.add(key);
-            return true;
-        });
-        return unique.slice(0, _limit).map((t) => ({
-            time: Number(t.created_at ?? 0),
-            symbol,
-            side: t.side === "bid" ? "buy" : "sell",
-            price: t.price,
-            size: t.amount,
-            fee: String(t.fee ?? "0"),
-        }));
+        if (!Array.isArray(trades)) {
+            throw new PerpError("EXCHANGE_ERROR", `Pacifica /trades returned no trade list (${JSON.stringify(trades).slice(0, 120)})`, { exchange: "pacifica" });
+        }
+        // The docs list event_type fulfill_taker / fulfill_maker and side open_long / open_short /
+        // close_long / close_short without declaring the sets closed: a row with any other value is
+        // skipped (stderr warning + meta.skippedRows), never given a guessed direction, and does not
+        // fail the rest of the tape.
+        const skippedWhy = [];
+        const rows = [];
+        for (const t of trades) {
+            const ev = pacificaField(t, "event_type", "/trades");
+            if (ev === "fulfill_maker")
+                continue;
+            if (ev !== "fulfill_taker") {
+                skippedWhy.push(`undocumented event_type "${ev}"`);
+                continue;
+            }
+            const side = pacificaField(t, "side", "/trades");
+            if (!PACIFICA_FILL_BUY_SIDES.has(side) && !PACIFICA_FILL_SELL_SIDES.has(side)) {
+                skippedWhy.push(`undocumented side "${side}"`);
+                continue;
+            }
+            if (rows.length >= _limit)
+                continue;
+            rows.push({
+                time: pacificaTime(t, "/trades"),
+                symbol,
+                side: pacificaFillSide(side, "/trades"),
+                price: pacificaField(t, "price", "/trades"),
+                size: pacificaField(t, "amount", "/trades"),
+                fee: null, // the public tape carries no fee
+            });
+        }
+        const skipped = skippedWhy.length === 0 ? null : { count: skippedWhy.length, reason: [...new Set(skippedWhy)].join(", ") };
+        if (skipped !== null)
+            process.stderr.write(`[pacifica] /trades: skipped ${skipped.count} row(s) — ${skipped.reason}\n`);
+        return withTapeSkipped(await nonEmptyOrListed(this, symbol, rows), skipped);
     }
     async getFundingHistory(symbol, limit = 10) {
-        const result = await this.client.getFundingHistory(symbol, { limit });
-        const data = (result.data ?? result);
-        if (!Array.isArray(data))
-            return [];
-        return data.map((h) => ({
-            time: Number(h.created_at ?? 0),
-            rate: venueRateField(h.funding_rate, "funding history funding_rate", "pacifica"),
-            price: String(h.oracle_price ?? "0"),
+        // The client unwraps the {success, data} envelope: the answer is the row list itself.
+        const data = await this.client.getFundingHistory(symbol, { limit });
+        if (!Array.isArray(data)) {
+            throw new PerpError("EXCHANGE_ERROR", `Pacifica /funding_rate/history returned no row list (${JSON.stringify(data).slice(0, 120)})`, { exchange: "pacifica" });
+        }
+        // `200 []` for an unlisted symbol (live): checked against the market directory.
+        return nonEmptyOrListed(this, symbol, data.map((h) => {
+            const oracle = h.oracle_price;
+            return {
+                time: pacificaTime(h, "/funding_rate/history"),
+                rate: venueRateField(h.funding_rate, "funding history funding_rate", "pacifica"),
+                // absent → null (unknown), never "0"
+                price: (typeof oracle === "string" && oracle !== "") || (typeof oracle === "number" && Number.isFinite(oracle)) ? String(oracle) : null,
+            };
         }));
     }
     async getKlines(symbol, interval, startTime, endTime) {
         const klines = await this.client.getKline(symbol, interval, startTime, endTime);
-        return klines.map((k) => ({
+        // `200 []` for an unlisted symbol (live): checked against the market directory.
+        return nonEmptyOrListed(this, symbol, klines.map((k) => ({
             time: k.t,
             open: k.o,
             high: k.h,
             low: k.l,
             close: k.c,
             volume: k.v,
+            quoteVolume: null, // /kline carries base volume only
             trades: k.n,
-        }));
+        })));
     }
     /**
      * Recent orders, newest first (GET /orders/history; PacificaClient.get already unwraps the
@@ -1402,15 +1472,11 @@ export class PacificaAdapter {
             throw new PerpError("EXCHANGE_ERROR", `Pacifica /trades/history returned no list (${JSON.stringify(rows).slice(0, 120)})`, { exchange: "pacifica" });
         }
         return rows.slice(0, limit).map((t) => {
-            const side = pacificaField(t, "side", "/trades/history");
-            const buy = PACIFICA_FILL_BUY_SIDES.has(side);
-            if (!buy && !PACIFICA_FILL_SELL_SIDES.has(side)) {
-                throw new PerpError("EXCHANGE_ERROR", `Pacifica /trades/history row with unknown side "${side}"`, { exchange: "pacifica" });
-            }
+            const side = pacificaFillSide(pacificaField(t, "side", "/trades/history"), "/trades/history");
             return {
                 time: pacificaTime(t, "/trades/history"),
                 symbol: pacificaField(t, "symbol", "/trades/history"),
-                side: buy ? "buy" : "sell",
+                side,
                 price: pacificaField(t, "price", "/trades/history"),
                 size: pacificaField(t, "amount", "/trades/history"),
                 fee: pacificaField(t, "fee", "/trades/history"),