perp-cli 0.12.15 → 0.14.0

package/dist/exchanges/pacifica.d.ts

@@ -1,8 +1,161 @@
 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 { ResolvedSlippage } from "./slippage.js";
 import type { SolanaSigner } from "../signer/index.js";
 import type { AgentMeta } from "../settings.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
+ * aliases GTT → GTC and GTX → ALO; no TIF → GTC (uniform default). FOK (never
+ * emulated) and unknown values → uniform CAPABILITY_UNSUPPORTED.
+ */
+export declare function pacificaTif(tif: string | undefined): PacificaTif;
+export declare function pacificaClientOrderId(tif: PacificaTif): string;
+/**
+ * A caller's client order id: Pacifica takes a "Full UUID string" (docs.pacifica.fi rest-api
+ * orders/create-limit-order + create-market-order: `client_order_id` | Full UUID string | optional
+ * | "Client-defined order ID" | f47ac10b-58cc-4372-a567-0e02b2c3d479). Anything else →
+ * INVALID_PARAMS before sending. An id in the reserved generated layout (`5ac1f` + TIF code) must
+ * state the order's own TIF `tif` (amend trusts it); null `tif` = the order has none (market).
+ */
+export declare function requirePacificaClientOrderId(id: string, tif: PacificaTif | null): string;
+/** TIF encoded in a generated client_order_id; null = not generated here (attributes unknown). */
+export declare function pacificaTifOf(clientOrderId: unknown): PacificaTif | null;
+/**
+ * The order's current `/orders/history_by_id` row. The array position is not a documented
+ * ordering and is never used: the row with the largest `created_at` wins (a timestamp tie →
+ * the single terminal row among them; several terminal rows tied → null). When rows lack a
+ * numeric `created_at`, only an explicit terminal row (filled / cancelled / rejected) for
+ * that order id is taken, and only when it is the only one. null = not proven (the caller
+ * polls again or reports pending). Rows of another order id are ignored.
+ */
+export declare function pacificaLatestHistoryRow(rows: unknown, orderId: string): Record<string, unknown> | null;
+/**
+ * Venue-final state of a placed order, read from its `/orders/history_by_id` rows
+ * (order_status open / partially_filled / filled / cancelled / rejected — docs
+ * rest-api/orders/get-order-history-by-id). Attached to the raw create / edit result as
+ * `orderOutcome`. open = resting (or an untriggered stop); a resting / cancelled order with
+ * a fill → partiallyFilled.
+ */
+export interface PacificaOrderOutcome {
+    status: "open" | "partiallyFilled" | "filled" | "cancelled" | "rejected";
+    final: true;
+    /** Venue order_status / event_type of the row the outcome was read from. */
+    venueStatus: string;
+    eventType: string | null;
+    orderId: string;
+    filledSize: string;
+    /** The row's price / initial_amount as the venue reports them (null = not reported). */
+    price: string | null;
+    size: string | null;
+    source: "history_by_id";
+}
+/**
+ * The order's outcome from its history_by_id rows (pacificaLatestHistoryRow), or null when not
+ * proven: no row for `orderId`, an unknown order_status, or no decimal filled_amount.
+ * `terminalOnly` (IOC): an open / partially_filled row is not an outcome (the order never rests).
+ * `expect` (price / size sent): a row whose price or initial_amount differ is not this
+ * placement / edit yet → null.
+ */
+export declare function pacificaOrderOutcomeOf(rows: unknown, orderId: string, opts?: {
+    terminalOnly?: boolean;
+    expect?: {
+        price: string | null;
+        size: string | null;
+    };
+}): PacificaOrderOutcome | null;
+/**
+ * A create-order POST the venue refused with HTTP 422 (Pacifica "Business Logic Error", error-codes
+ * doc) is a definite pre-trade rejection — no order was created. Live testnet 2026-10-02:
+ * POST /orders/create_market 422 {"success":false,"error":"No reasonable price found for SOL-USDC",
+ * "code":0,"error_id":"no_reasonable_price"} (an empty book). → ORDER_REJECTED carrying the venue's
+ * error / code / error_id — but ONLY for the documented validation codes
+ * (PACIFICA_DEFINITE_CREATE_CODES / _ERROR_IDS). Internal or unknown codes → ORDER_PENDING (the
+ * order may exist). Anything else (other status, unparseable body, not a create path, already a
+ * PerpError) → `e` unchanged.
+ */
+export declare function pacificaCreateRejection(e: unknown, what: string): unknown;
+/**
+ * 422 business codes that say a create was validated and REFUSED (docs.pacifica.fi api
+ * error-codes, read 2026-10-05): 1 ACCOUNT_NOT_FOUND, 3 BOOK_NOT_FOUND, 4 INVALID_TICK_LEVEL,
+ * 5 INSUFFICIENT_BALANCE, 7/8 ORDER_AMOUNT_TOO_LOW/HIGH, 10 OPEN_ORDER_LIMIT_REACHED,
+ * 13 POSITION_NOT_FOUND, 16–23 stop / order-type / reduce-only validation, 25 NO_REASONABLE_PRICE,
+ * 28 IMMEDIATE_LIQUIDATION, 30 PRICE_TOO_FAR_FROM_MARK, 36 DUPLICATE_CLIENT_ORDER_ID,
+ * 38 TRADING_DISABLED, 41 OPEN_INTEREST_LIMIT_EXCEEDED, 49 POSITION_TPSL_LIMIT_EXCEEDED,
+ * 50 INVALID_BUILDER_CODE, 51 UNSUPPORTED_OPERATION, 52 INVALID_TICK_SIZE,
+ * 53 ORDER_BLOCKED_BY_LOAN_POOL_STRESS, 55/56 ASSET_NOT_FOUND/NOT_ACTIVE, 59 INVALID_AMOUNT,
+ * 62 INSUFFICIENT_SPOT_BALANCE, 63 MISSING_MARK_PRICE, 106–108 spot restrictions,
+ * 119 ORACLE_NOT_AVAILABLE. NOT listed (outcome unknown): 0 INTERNAL, 14 DATABASE_ERROR,
+ * 26 CHANNEL_CLOSED, 27 RESPONSE_DROPPED and every undocumented code.
+ */
+export declare const PACIFICA_DEFINITE_CREATE_CODES: ReadonlySet<number>;
+/**
+ * `error_id` values that are definite on their own: the venue sends some validation refusals
+ * under code 0 with a specific error_id (live testnet 2026-10-02: an empty book →
+ * {"code":0,"error_id":"no_reasonable_price"}).
+ * Live mainnet 2026-10-05: a reduce-only limit with no position →
+ * {"code":0,"error_id":"no_position_for_reduce_only_order"} ("No position found for reduce-only order").
+ */
+export declare const PACIFICA_DEFINITE_CREATE_ERROR_IDS: ReadonlySet<string>;
+/**
+ * Pacifica's documented USDC withdrawal minimum (docs.pacifica.fi "Deposits & Withdrawals":
+ * "Minimum withdrawal: $1. Fees: $1 per withdrawal (gas)"). Not the whole rule: testnet refused
+ * exactly 1 USDC on 2026-10-02 with 422 code 29 WITHDRAW_AMOUNT_TOO_LOW, so amounts at or just
+ * above it are left to the venue (pacificaWithdrawRejection maps the refusal).
+ */
+export declare const PACIFICA_WITHDRAW_MIN_USDC = "1";
+/**
+ * A withdraw POST the venue refused with HTTP 422 (Business Logic Error — nothing was withdrawn):
+ * code 29 WITHDRAW_AMOUNT_TOO_LOW → INVALID_PARAMS, code 9 OVER_WITHDRAWAL → INSUFFICIENT_BALANCE,
+ * any other explicit refusal → ACTION_REJECTED (codes: docs.pacifica.fi api error-codes). Anything
+ * else (other status, unparseable body, already a PerpError) → `e` unchanged (outcome unknown).
+ */
+export declare function pacificaWithdrawRejection(e: unknown, amount: string): unknown;
+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 = {
+    kind: "failed";
+    error: string;
+} | {
+    kind: "pending";
+    reason: string;
+};
+/**
+ * What a refused cancel (POST /orders/cancel 4xx, e.g. 422 {"error":"Failed to cancel order","code":5}
+ * for an already-filled market order — live testnet 2026-10-02) means for the order, from its
+ * history_by_id read (`history` = the read's data, or the read's error):
+ * - terminal row (filled / cancelled / rejected) → failed: nothing was cancelled by this request;
+ * - GET 404 "Order history not found" → failed: the venue has no such order;
+ * - a still-open row, no row, or any other read failure → pending (not proven either way).
+ * Never "cancelled".
+ */
+export declare function pacificaCancelRefusalOf(orderId: string, refusal: string, history: {
+    data: unknown;
+} | {
+    error: unknown;
+}): PacificaCancelRefusal;
+/** Result of a TIF-preserving amend (see PacificaAdapter.amendKeepingTif). */
+export interface PacificaAmendResult {
+    method: "nativeAmend" | "cancelReplace";
+    /** TIF of the amended / replacement order. */
+    tif: PacificaTif;
+    /** Order id after the amend: the edited order (native) or the replacement (null = no replacement placed). */
+    orderId: string | null;
+    clientOrderId: string | null;
+    filledBeforeCancel: string | null;
+    replacedSize: string | null;
+    /** The original order's terminal history row said "filled" (it filled completely before the cancel). */
+    filledCompletely: boolean;
+    /** Venue-final state of the edited / replacement order (history_by_id); null = unresolved or none placed. */
+    outcome: PacificaOrderOutcome | null;
+    notes: string[];
+    venueRaw: unknown;
+}
+/** Pacifica order_type of a stop / TP / SL order (stop_market, stop_limit, take_profit_*, stop_loss_*). */
+export declare function isPacificaStopType(type: string): boolean;
 export declare class PacificaAdapter implements ExchangeAdapter {
     readonly name = "pacifica";
     readonly chain = "solana";
@@ -27,8 +180,17 @@ export declare class PacificaAdapter implements ExchangeAdapter {
     private _marketsCache;
     private _marketsCacheTime;
     private static readonly CACHE_TTL;
-    constructor(keypair: Keypair, network?: Network, builderCode?: string, hasRealKey?: boolean);
+    /** Venue network — part of every account cache key (the same key exists on mainnet and testnet). */
+    private _network;
+    /**
+     * Builder-fee gate (settings builder.pacifica + confirmed approval); null = not configured.
+     * Set by createPacifica (venues/create-helpers.ts) — the adapter never reads settings.
+     */
+    builderFee: BuilderFeeGate | null;
+    constructor(keypair: Keypair, network?: Network, hasRealKey?: boolean);
     private ensureSigner;
+    /** Resolve the active signer tier and sync agent_wallet on the client (used by PacificaSpotAdapter). */
+    prepareSigning(): void;
     /**
      * Inject an external Solana signer (Tier 2 — OWS master).
      * Backward-compatible: existing callers (e.g. `perp -e pacifica --ows ...`
@@ -46,11 +208,27 @@ export declare class PacificaAdapter implements ExchangeAdapter {
     get activeSignerTier(): "agent" | "master" | "pk" | null;
     /** Resolve the active signer across three tiers. Mirrors AsterAdapter._resolveSigner. */
     private _resolveSigner;
+    /**
+     * The owner (master) Solana signer for on-chain transactions (deposit, test-token
+     * mint) — never the agent, which cannot move funds.
+     */
+    masterSolanaSigner(): SolanaSigner;
     /** Access the underlying Keypair (only available with LocalSolanaSigner). */
     get keypair(): Keypair;
     private _getPrices;
     private _getPositions;
     get publicKey(): string;
+    /** Builder decision for the next perp order (cached approval read; never throws). */
+    builderDecision(): Promise<BuilderDecision>;
+    /** builder_code to send with the next perp order, or null (not configured / not approved). */
+    private builderCode;
+    /**
+     * Approval of `target.identity` on this account (GET /account/builder_codes/approvals).
+     * Pacifica's builder sets its own rate up to the approved max_fee_rate, so the code is
+     * attached only while that max ≤ target.feeBps (the user's consent); a higher approved max
+     * is "aboveConsent" (not attached, real max reported).
+     */
+    builderApprovalOf(target: BuilderTarget): Promise<BuilderApproval>;
     get sdk(): PacificaClient;
     get signer(): (msg: Uint8Array) => Promise<Uint8Array>;
     getMarkets(): Promise<ExchangeMarketInfo[]>;
@@ -60,25 +238,131 @@ export declare class PacificaAdapter implements ExchangeAdapter {
     }>;
     getBalance(): Promise<ExchangeBalance>;
     getPositions(): Promise<ExchangePosition[]>;
+    /**
+     * The leverage this account applies to `symbol`: its GET /account/settings `margin_settings`
+     * entry ("Current leverage set by the user"); no entry → the market's max leverage (docs
+     * get-account-settings: "leverage default to max ... will return blank"). Unreadable → EXCHANGE_ERROR.
+     */
+    marketLeverage(symbol: string): Promise<number>;
     getOpenOrders(): Promise<ExchangeOrder[]>;
-    marketOrder(symbol: string, side: "buy" | "sell", size: string, opts?: {
-        reduceOnly?: boolean;
+    marketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
+        reduceOnly: boolean;
+        slippage: ResolvedSlippage;
+        clientOrderId?: string;
     }): Promise<unknown>;
+    /**
+     * Venue-final outcome of a raw marketOrder() result (IocOutcomeCapable, design §13.10 #4),
+     * 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),
+     * a poll that timed out or saw only non-terminal rows, any other raw value. Never guesses.
+     */
+    iocOutcomeOf(raw: unknown): IocOutcome | null;
+    /**
+     * Venue-final outcome of a placed / edited order: polls `/orders/history_by_id` (bounded,
+     * 6 × 500 ms) until pacificaOrderOutcomeOf proves one. null = still unknown (the caller
+     * reports pending). Read failures poll again; the last one is logged when nothing resolved.
+     */
+    resolveOrderOutcome(orderId: string, what: string, opts?: {
+        terminalOnly?: boolean;
+        expect?: {
+            price: string | null;
+            size: string | null;
+        };
+    }): Promise<PacificaOrderOutcome | null>;
+    /** The raw create result with its resolved `orderOutcome` attached (unchanged when there is no order id / a body error / no outcome). */
+    private withOrderOutcome;
+    /**
+     * Limit order. The create response is only an ack ({ order_id }); the placement outcome
+     * (resting / filled / cancelled / rejected) is read back from history_by_id and attached as
+     * `orderOutcome` (IOC: terminal rows only). Unresolved → no `orderOutcome` (pending).
+     */
     limitOrder(symbol: string, side: "buy" | "sell", price: string, size: string, opts?: {
         reduceOnly?: boolean;
         tif?: string;
+        clientOrderId?: string;
     }): Promise<unknown>;
     cancelOrder(symbol: string, orderId: string): Promise<unknown>;
-    cancelAllOrders(symbol?: string): Promise<unknown>;
+    /**
+     * The account's order carrying `clientOrderId`, from the venue's own listings — both document
+     * the field: GET /orders and GET /orders/history rows carry `client_order_id` ("CLOID of order
+     * if assigned by user", docs.pacifica.fi rest-api orders/get-open-orders, get-order-history).
+     * Open orders first, then the latest order-history page (the venue's default page, 100 rows).
+     * null = not among them. history_by_id itself takes only `order_id`, so this resolves the id.
+     */
+    orderByClientId(clientOrderId: string): Promise<{
+        orderId: string;
+        symbol: string;
+        type: string;
+        open: boolean;
+    } | null>;
+    /**
+     * Venue-final state of one order from a single `/orders/history_by_id` read (`trade status`).
+     * null outcome = the rows prove no state yet (reported pending). A 404 → ORDER_NOT_FOUND.
+     */
+    orderStatusById(orderId: string): Promise<{
+        outcome: PacificaOrderOutcome | null;
+        clientOrderId: string | null;
+        venueRaw: unknown;
+    }>;
+    /** A refused cancel of `orderId` (pacificaRefused error) settled from one history_by_id read (pacificaCancelRefusalOf). */
+    cancelRefusalOutcome(orderId: string, refusal: unknown): Promise<PacificaCancelRefusal>;
+    cancelAllOrders(symbol?: string): Promise<unknown[]>;
+    /** Stop / TP / SL rows (incl. position-level TP/SL) go to /orders/stop/cancel; /orders/cancel refuses them (422). */
+    private _cancelListed;
+    /**
+     * Native edit (POST /orders/edit). Venue semantics (docs rest-api/orders/edit-order,
+     * read 2026-10-02): the edit cancels the original and creates a new order with the same
+     * side, reduce-only and client_order_id, a new order_id, and TIF = ALO (post-only) —
+     * whatever the original TIF was. Post-only is therefore always kept (an ALO original
+     * stays ALO); a GTC / TOB original becomes ALO and is rejected instead of crossing.
+     * The original TIF is not readable (GET /orders has no tif field), so the conversion
+     * cannot be detected per order; callers report it (execution tifSent "ALO").
+     */
     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.
+     * 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).
+     *  - GTC / TOB: cancel → read the fill at cancel → replace with
+     *    size − (filledAtCancel − filledAtRead) at the same TIF / side / reduce-only (≤ 0 or below
+     *    the lot → no replacement, reported). Cancel outcome unknown → ORDER_PENDING (no replace);
+     *    cancel ok but the fill at cancel unreadable or the replacement refused → ORDER_PARTIAL
+     *    { cancelled, placed: null }; replacement outcome unknown → ORDER_PENDING.
+     */
+    amendKeepingTif(symbol: string, orderId: string, price: string, size: string, tif: PacificaTif | null, forceTif?: boolean): Promise<PacificaAmendResult>;
+    /** Cancel a stop / TP / SL order (POST /orders/stop/cancel). An explicit venue refusal → ORDER_REJECTED. */
+    cancelStopOrder(symbol: string, orderId: string): Promise<unknown>;
+    /** Open position-level TP/SL orders (order_type take_profit_* / stop_loss_*) on `symbol`. */
+    positionTpSlOrders(symbol: string): Promise<Array<{
+        orderId: string;
+        type: string;
+        stopPrice: string | null;
+    }>>;
+    /**
+     * Position-level TP/SL (POST /positions/tpsl). `positionSide` = the position's side; the
+     * venue's `side` field is the TP/SL orders' (CLOSING) side: long → "ask", short → "bid"
+     * (pacifica-fi/python-sdk rest/create_position_tpsl.py: a BTC long sends side "ask"; the
+     * position side was refused live on testnet 2026-10-02 with 422 "Invalid stop order side").
+     * Covers the whole position. An explicit venue refusal → ORDER_REJECTED.
+     */
+    setPositionTpSl(symbol: string, positionSide: "long" | "short", tpsl: {
+        tp: string | null;
+        tpLimit: string | null;
+        sl: string | null;
+    }): Promise<unknown>;
     setLeverage(symbol: string, leverage: number, marginMode?: "cross" | "isolated"): Promise<{
         symbol: string;
         leverage: number;
         marginMode: "cross" | "isolated";
     }>;
+    /** CLI trigger-type → Pacifica `trigger_price_type` value. Omitted ⇒ venue default (mark_price). */
+    private static readonly TRIGGER_TYPE;
     stopOrder(symbol: string, side: "buy" | "sell", size: string, triggerPrice: string, opts?: {
         limitPrice?: string;
         reduceOnly?: boolean;
+        triggerType?: "mark" | "last" | "mid";
     }): Promise<unknown>;
     withdraw(amount: string, destination: string, _opts?: {
         assetId?: number;