perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/pacifica-vaults.d.ts

@@ -0,0 +1,130 @@
+import type { PacificaClient } from "../pacifica/client.js";
+import { type PresignedIdentity, type PresignedRequest } from "./pacifica-presigned.js";
+/** docs vaults/depositing: "Minimum deposit — Constant 10 USDC." */
+export declare const VAULT_MIN_DEPOSIT_USDC = "10";
+export interface VaultConfig {
+    depositCap: string | null;
+    managerProfitShare: string | null;
+    managerLossShare: string | null;
+    depositMinDurationMs: number | null;
+    managerMinBalancePortion: string | null;
+    managerLiquidationBalancePortion: string | null;
+    withdrawWindowS: number | null;
+    withdrawDurationS: number | null;
+}
+export interface PacificaVault {
+    schema: 1;
+    address: string;
+    nickname: string | null;
+    creator: string | null;
+    manager: string | null;
+    referrer: string | null;
+    createdAt: number | null;
+    lpShares: string;
+    managerShares: string;
+    lpBalance: string;
+    managerBalance: string;
+    /** lp_balance + manager_balance (USDC attributed to the two share classes). */
+    tvl: string;
+    /** last_checked_equity — the equity snapshot used for vault accounting. */
+    equitySnapshot: string | null;
+    highWatermark: string | null;
+    /** lp_balance ÷ lp_shares (null when the LP class is empty — the next deposit mints 1:1). */
+    navPerLpShare: string | null;
+    navPerManagerShare: string | null;
+    /** Not published by the venue. */
+    apy: null;
+    config: VaultConfig;
+    /** The queried account's LP shares (`user_share`); null when none / not queried. */
+    userShares: string | null;
+}
+export declare function parseVault(x: unknown): PacificaVault;
+/** GET /lake/list `data` (`{lakes: [...]}`). */
+export declare function parseVaultList(data: unknown): PacificaVault[];
+type Reader = Pick<PacificaClient, "getEnvelope">;
+export declare function fetchVaults(client: Reader, account: string | null): Promise<PacificaVault[]>;
+/**
+ * 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 declare function findVault(vaults: PacificaVault[], ref: string): PacificaVault;
+/** UNOFFICIAL endpoint (not in the API docs; used by app.pacifica.fi). Advisory only — the venue's own refusal is final. */
+export declare const DEPOSIT_WHITELIST_API_STATUS: "unofficial";
+export declare function fetchDepositWhitelist(client: Reader, vault: string): Promise<string[]>;
+/**
+ * The advisory whitelist read for display: `addresses` null = unreadable, with the error CODE that
+ * made it so (never a bare null that looks like "no whitelist data"). The venue's refusal of a
+ * deposit stays final either way.
+ */
+export declare function readDepositWhitelist(client: Reader, vault: string): Promise<{
+    addresses: string[] | null;
+    error: string | null;
+}>;
+export interface WithdrawWindow {
+    /** No window configured: always open (subject to the other rules). */
+    restricted: boolean;
+    open: boolean;
+    /** Current window closes (open) or next one opens (closed), ms; null when unrestricted. */
+    nextChangeAt: number | null;
+}
+/** docs: open while current_unix_time_s mod withdraw_window_s < withdraw_duration_s (epoch-anchored). */
+export declare function withdrawWindowAt(c: VaultConfig, nowMs: number): WithdrawWindow;
+/** Shares this account holds in the vault: manager shares for the manager, else LP `user_share`. */
+export declare function heldShares(v: PacificaVault, account: string): {
+    role: "manager" | "lp";
+    shares: string | null;
+    nav: string | null;
+};
+export interface VaultDepositPlan {
+    schema: 1;
+    vault: string;
+    nickname: string | null;
+    manager: string | null;
+    role: "manager" | "lp";
+    amount: string;
+    /** amount × shares ÷ balance of the class now (the venue mints at the post-sync NAV). */
+    estimatedShares: string | null;
+    lockMs: number | null;
+    warnings: string[];
+}
+/**
+ * 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 declare function planVaultDeposit(v: PacificaVault, account: string, amountRaw: string, ctx: {
+    availableToWithdraw: string;
+    whitelist: string[] | null;
+}): VaultDepositPlan;
+export interface VaultWithdrawPlan {
+    schema: 1;
+    vault: string;
+    nickname: string | null;
+    manager: string | null;
+    role: "manager" | "lp";
+    shares: string;
+    heldShares: string;
+    /** shares × NAV now (the venue pays at the post-sync NAV; may pay partially when the vault is deployed). */
+    estimatedAmount: string | null;
+    /** Always the account itself — the API has no destination. */
+    destination: string;
+    window: WithdrawWindow;
+    warnings: string[];
+}
+/** Validate a withdrawal: shares held, withdrawal window. Throws POSITION_NOT_FOUND / INVALID_PARAMS / POLICY_DENIED. */
+export declare function planVaultWithdraw(v: PacificaVault, account: string, sharesRaw: string | "all", ctx: {
+    nowMs: number;
+    vaultAvailableToWithdraw: string | null;
+}): VaultWithdrawPlan;
+export declare function buildVaultDepositRequest(vault: string, amount: string, identity: PresignedIdentity, opts: {
+    timestamp: number;
+    idempotencyKey: string;
+    expiryWindow?: number;
+}): PresignedRequest;
+export declare function buildVaultWithdrawRequest(vault: string, shares: string, identity: PresignedIdentity, opts: {
+    timestamp: number;
+    idempotencyKey: string;
+    expiryWindow?: number;
+}): PresignedRequest;
+export {};

package/dist/exchanges/pacifica-vaults.js

@@ -0,0 +1,277 @@
+/**
+ * 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, classifyError } 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;
+}
+/**
+ * The advisory whitelist read for display: `addresses` null = unreadable, with the error CODE that
+ * made it so (never a bare null that looks like "no whitelist data"). The venue's refusal of a
+ * deposit stays final either way.
+ */
+export async function readDepositWhitelist(client, vault) {
+    try {
+        return { addresses: await fetchDepositWhitelist(client, vault), error: null };
+    }
+    catch (e) {
+        return { addresses: null, error: classifyError(e, "pacifica").code };
+    }
+}
+/** 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,14 +1,18 @@
+import { type FundingHistoryRow } from "./interface.js";
 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";
+import type { PriceInfo } from "../pacifica/types/market.js";
+import type { Position } from "../pacifica/types/position.js";
+import type { AccountInfo } from "../pacifica/types/account.js";
 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 +118,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 = {
@@ -154,8 +159,49 @@ export interface PacificaAmendResult {
     notes: string[];
     venueRaw: unknown;
 }
+/** GET /trades answers the last 20 fills (40 taker + maker rows); no limit or cursor. */
+export declare const PACIFICA_TRADES_CAP = 20;
+/** GET /funding_rate/history `limit` maximum per request (docs; live 4001 → 4000). */
+export declare const PACIFICA_FUNDING_PAGE = 4000;
+/** GET /kline: "Max range: 4000 candles" per request (HTTP 400 beyond, live 2026-10-19). */
+export declare const PACIFICA_KLINE_MAX_BARS = 4000;
+/** Requests one funding / kline read may send (the venue meters reads by credits). */
+export declare const PACIFICA_MAX_PAGES = 10;
+/**
+ * GET /kline intervals (venue error text, live 2026-10-19: "Must be one of 1m, 3m, 5m, 15m, 30m,
+ * 1h, 2h, 4h, 8h, 12h, 1d, 1w, 1M"; each answered 200 with rows labelled `i` = the interval).
+ * The ms length sizes the 4000-bar request windows (1M: 31 days, the longest month).
+ */
+export declare const PACIFICA_KLINE_INTERVALS: Readonly<Record<string, number>>;
 /** 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";
+/** Pacifica balance with its extras (USDC balance / loan, pending interest, withdrawable). */
+export type PacificaBalance = ExchangeBalance & {
+    usdcBalance: string;
+    borrowedUsdc: string;
+    pendingInterest: string | null;
+    availableToWithdraw: string;
+};
+/**
+ * Balance of a Pacifica account from GET /account, its positions and /info/prices — the one
+ * implementation behind PacificaAdapter.getBalance() and the keyless `account balance --address`.
+ */
+export declare function pacificaBalanceOf(info: AccountInfo, positions: Position[], prices: PriceInfo[]): PacificaBalance;
+/**
+ * Open positions of one Pacifica account (`GET /positions?account=`), marked with `/info/prices`.
+ * The ONE mapper of the keyed `getPositions` and the public-address read: unresolved leverage is
+ * read from the account's `/account/settings` (public, by address), then the market max.
+ */
+export declare function pacificaPositionRows(positions: Position[], prices: PriceInfo[], deps: {
+    accountSettings: () => Promise<unknown>;
+    maxLeverage: () => Promise<Map<string, number | null>>;
+}): Promise<ExchangePosition[]>;
 export declare class PacificaAdapter implements ExchangeAdapter {
     readonly name = "pacifica";
     readonly chain = "solana";
@@ -179,6 +225,7 @@ export declare class PacificaAdapter implements ExchangeAdapter {
     private signMessage;
     private _marketsCache;
     private _marketsCacheTime;
+    private _infoCache;
     private static readonly CACHE_TTL;
     /** Venue network — part of every account cache key (the same key exists on mainnet and testnet). */
     private _network;
@@ -213,6 +260,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;
@@ -230,8 +288,37 @@ export declare class PacificaAdapter implements ExchangeAdapter {
      */
     builderApprovalOf(target: BuilderTarget): Promise<BuilderApproval>;
     get sdk(): PacificaClient;
+    /**
+     * The configured account for an account read (settings, TWAP orders, …): no Pacifica key
+     * configured → NO_SIGNER_AVAILABLE. A keyless adapter holds a generated throwaway keypair, whose
+     * empty account would otherwise read as "no settings / no orders".
+     */
+    accountForReads(): string;
     get signer(): (msg: Uint8Array) => Promise<Uint8Array>;
+    /** GET /info rows (every instrument type), one CACHE_TTL cache for symbol resolution and getMarkets. */
+    private infoRows;
     getMarkets(): Promise<ExchangeMarketInfo[]>;
+    /**
+     * The venue's own spelling of a perp market typed by the user. Pacifica's API is
+     * case-sensitive (kBONK / kPEPE / kSHIB: `KPEPE` answers `200 []` on /trades, /kline and
+     * /funding_rate/history and 400 "Book not found" on /book — live 2026-10-19), and the CLI
+     * upper-cases the argument. Matched against /info exactly first, then case-insensitively
+     * (a "-PERP" display suffix ignored), as `market info` does. A listed non-perp (spot SOL-USDC)
+     * is refused before any request: this adapter serves perps only (isPacificaPerpetual).
+     */
+    wireSymbol(symbol: string): Promise<string>;
+    /**
+     * wireSymbol for an order entry point (market / limit / stop / edit): a resolution failure is
+     * a definite "not sent" (orderNotSent re-types a read error), never a retryable code.
+     */
+    private orderSymbol;
+    /**
+     * The venue's spelling for a cancel / TP-SL on an existing order or position: resolved as in
+     * wireSymbol when /info lists it (any instrument type, case-insensitive); otherwise — not listed
+     * (a delisted market) or /info unreadable — sent as typed: a cancel must still reach the venue,
+     * whose own answer is final.
+     */
+    private listedSymbol;
     getOrderbook(symbol: string): Promise<{
         bids: [string, string][];
         asks: [string, string][];
@@ -251,7 +338,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 +408,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,12 +455,23 @@ export declare class PacificaAdapter implements ExchangeAdapter {
         assetId?: number;
         routeType?: number;
     }): Promise<unknown>;
-    getRecentTrades(symbol: string, _limit?: number): Promise<ExchangeTrade[]>;
-    getFundingHistory(symbol: string, limit?: number): Promise<{
-        time: number;
-        rate: string;
-        price: string | null;
-    }[]>;
+    /**
+     * 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<FundingHistoryRow[]>;
+    /**
+     * GET /kline over [startTime, endTime]. The venue refuses a range over 4000 candles (HTTP 400
+     * "Time range too large … Max range: 4000 candles"), so a longer window is read in consecutive
+     * 4000-bar windows (at most PACIFICA_MAX_PAGES), merged by open time. Intervals outside
+     * PACIFICA_KLINE_INTERVALS are refused locally with INVALID_PARAMS (the venue: HTTP 400).
+     */
     getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
     /**
      * Recent orders, newest first (GET /orders/history; PacificaClient.get already unwraps the