perp-cli 0.14.3 → 0.16.0

package/dist/pacifica/client.js

@@ -1,7 +1,9 @@
 import { getNetworkConfig } from "./constants.js";
-import { buildSignedRequest, buildAgentSignedRequest } from "./signing.js";
+import { buildSignedRequest, buildAgentSignedRequest, signWithWallet } from "./signing.js";
 import { PerpError, extractErrorMessage, orderNotSent, orderOutcomeUnknown, sendFailure } from "../errors.js";
 import { invalidateCache } from "../cache.js";
+import { requireSolanaAddress } from "../exchanges/address.js";
+import { PACIFICA_COST_CANCEL, PACIFICA_COST_STANDARD, PACIFICA_MAX_THROTTLE_WAIT_MS, PACIFICA_READ_NEED, PACIFICA_SIGNED_MAX_WAIT_MS, pacificaRateLimiter, } from "./rate-limit.js";
 /** Per-request timeout of a POST (fetch + body read). */
 export const PACIFICA_POST_TIMEOUT_MS = 15_000;
 /**
@@ -14,6 +16,37 @@ export const PACIFICA_POST_TIMEOUT_MS = 15_000;
 const DEFINITE_4XX_PATHS = new Set(["/positions/tpsl", "/account/leverage"]);
 /** POST endpoints that only read (signed listings): a failure there is an ordinary read error. */
 const READ_POST_PATHS = new Set(["/account/subaccount/list", "/agent/list", "/account/api_keys"]);
+/** Cancels cost 0.5 credits (docs: rate-limits "Order cancellation 0.5"), by path and by signed operation type. */
+const CANCEL_POST_PATHS = new Set(["/orders/cancel", "/orders/stop/cancel", "/orders/cancel_all", "/orders/twap/cancel"]);
+const CANCEL_OPERATIONS = new Set(["cancel_order", "cancel_stop_order", "cancel_all_orders", "cancel_twap_order"]);
+/** Signed operation types of the READ_POST_PATHS listings: the read need applies before and after signing. */
+const READ_OPERATIONS = new Set(["list_subaccounts", "list_agent_wallets", "list_api_keys"]);
+/**
+ * A signed write needs only its own cost (never the read reserve); `maxWaitMs` = how long it may
+ * wait at this point (before signing: the normal bound; after signing: inside expiry_window).
+ */
+function writeNeed(cancel, maxWaitMs) {
+    const cost = cancel ? PACIFICA_COST_CANCEL : PACIFICA_COST_STANDARD;
+    return { cost, reserve: 0, maxWaitMs };
+}
+/**
+ * Credits ×10 reserved for one POST /orders/batch. The docs (api/rate-limits "Credit Costs") price
+ * a "Standard request/action" at 1 credit and an "Order cancellation" at 0.5 and say nothing
+ * batch-specific (batch-order page: no cost); every action is individually signed and processed,
+ * so the batch is reserved per ACTION — the conservative reading (over-reserving only throttles
+ * earlier; the venue's ratelimit headers on the response settle the real count).
+ */
+export function pacificaBatchCost(types) {
+    return types.reduce((a, t) => a + (t === "Cancel" || t === "CancelStopOrder" ? PACIFICA_COST_CANCEL : PACIFICA_COST_STANDARD), 0);
+}
+/** Query parameters that carry a Solana address (account reads, Print orders, vaults). */
+const ADDRESS_PARAMS = new Set(["account", "game_account", "lake"]);
+export { requireSolanaAddress };
+function checkAddressParams(params) {
+    for (const [k, v] of Object.entries(params ?? {}))
+        if (ADDRESS_PARAMS.has(k) && v !== undefined && v !== null)
+            requireSolanaAddress(v, k);
+}
 export class PacificaClient {
     baseUrl;
     apiKey;
@@ -24,12 +57,21 @@ export class PacificaClient {
      * against the agent key. Undefined for master/PK signers.
      */
     requestAgentWallet;
+    /** Credit-quota state for this base URL + key tier (rate-limit.ts; process-local): unsigned GETs (IP quota) … */
+    rate;
+    /** … and signed POSTs (may report the account's quota) kept apart. */
+    signedRate;
     /** Attach (or clear) the agent wallet used for subsequent signed requests. */
     setRequestAgentWallet(agentWallet) {
         this.requestAgentWallet = agentWallet;
     }
     /** Build a signed POST body, attaching agent_wallet when an agent is the active signer. */
     async signedBody(operationType, payload, account, signMessage) {
+        // Throttle BEFORE signing: a wait after signing would eat into the body's expiry_window.
+        // A fail-fast RATE_LIMITED here sent nothing (details.sent === false).
+        await this.signedRate.awaitCapacity(operationType, READ_OPERATIONS.has(operationType)
+            ? PACIFICA_READ_NEED
+            : writeNeed(CANCEL_OPERATIONS.has(operationType), PACIFICA_MAX_THROTTLE_WAIT_MS));
         try {
             return await (this.requestAgentWallet
                 ? buildAgentSignedRequest(operationType, payload, account, this.requestAgentWallet, signMessage)
@@ -44,6 +86,8 @@ export class PacificaClient {
         this.baseUrl =
             config.baseUrl || getNetworkConfig(config.network).restUrl;
         this.apiKey = config.apiKey;
+        this.rate = pacificaRateLimiter(this.baseUrl, this.apiKey, "unsigned");
+        this.signedRate = pacificaRateLimiter(this.baseUrl, this.apiKey, "signed");
     }
     headers() {
         const h = { "Content-Type": "application/json" };
@@ -52,6 +96,7 @@ export class PacificaClient {
         return h;
     }
     async get(path, params) {
+        checkAddressParams(params);
         const url = new URL(`${this.baseUrl}${path}`);
         if (params) {
             Object.entries(params).forEach(([k, v]) => {
@@ -59,9 +104,20 @@ export class PacificaClient {
                     url.searchParams.set(k, v);
             });
         }
-        const res = await fetch(url.toString(), { headers: this.headers() });
+        const ticket = await this.rate.acquire(`GET ${path}`, PACIFICA_READ_NEED);
+        let res;
+        try {
+            res = await fetch(url.toString(), { headers: this.headers() });
+        }
+        finally {
+            ticket.release();
+        }
+        this.rate.observe(res);
         if (!res.ok) {
             const text = await res.text();
+            // Structural (by status): RATE_LIMITED with retryAfterMs; never retried here.
+            if (res.status === 429)
+                throw this.rate.rateLimitedError(`GET ${path}`, res, text);
             throw new Error(`GET ${path} failed (${res.status}): ${text}`);
         }
         const json = await res.json();
@@ -77,14 +133,21 @@ export class PacificaClient {
      * outcome unknown → ORDER_PENDING (sendFailure), never a retryable network error. No connection
      * at all → not sent. A 4xx is the venue's refusal and keeps the plain `POST <path> failed
      * (<status>): <body>` error the adapters map (422 business codes) — except on
-     * DEFINITE_4XX_PATHS, where it is a definite ACTION_REJECTED (429 stays the plain error →
-     * RATE_LIMITED). A fetch timeout (PACIFICA_POST_TIMEOUT_MS) on a write is ORDER_PENDING too;
+     * DEFINITE_4XX_PATHS, where it is a definite ACTION_REJECTED. HTTP 429 → RATE_LIMITED
+     * (details.sent === false, retryAfterMs) — never retried, a write is never resubmitted.
+     * "429 = not executed" is our reading of the docs ("When credits are exhausted, requests return
+     * HTTP 429"), not an explicit Pacifica statement. Before sending, the credit throttle may wait up
+     * to PACIFICA_SIGNED_MAX_WAIT_MS (the body is already signed) or fail fast with RATE_LIMITED
+     * (nothing sent). A write needs only its own cost, never the read reserve. A fetch timeout (PACIFICA_POST_TIMEOUT_MS) on a write is ORDER_PENDING too;
    * on a listing read a timeout is TIMEOUT and any other transport failure EXCHANGE_UNREACHABLE.
      */
-    async post(path, body) {
+    async post(path, body, needOverride) {
         const write = !READ_POST_PATHS.has(path);
         const what = `POST ${path}`;
         const remediation = `Do NOT resubmit — the request may have been executed. Check open orders, positions and balances first: perp -e pacifica account orders / portfolio`;
+        const ticket = await this.signedRate.acquire(what, needOverride !== undefined ? needOverride : write
+            ? writeNeed(CANCEL_POST_PATHS.has(path), PACIFICA_SIGNED_MAX_WAIT_MS)
+            : { ...PACIFICA_READ_NEED, maxWaitMs: PACIFICA_SIGNED_MAX_WAIT_MS });
         try {
             let res;
             let text;
@@ -95,6 +158,7 @@ export class PacificaClient {
                     body: JSON.stringify(body),
                     signal: AbortSignal.timeout(PACIFICA_POST_TIMEOUT_MS),
                 });
+                ticket.settle(res);
                 text = await res.text();
             }
             catch (e) {
@@ -110,8 +174,11 @@ export class PacificaClient {
             if (write && res.status >= 500) {
                 throw orderOutcomeUnknown("pacifica", what, new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`), remediation);
             }
+            // Refused before processing (credits exhausted): nothing executed, never resubmitted here.
+            if (res.status === 429)
+                throw this.signedRate.rateLimitedError(what, res, text);
             if (!res.ok) {
-                if (DEFINITE_4XX_PATHS.has(path) && res.status >= 400 && res.status < 500 && res.status !== 429) {
+                if (DEFINITE_4XX_PATHS.has(path) && res.status >= 400 && res.status < 500) {
                     throw new PerpError("ACTION_REJECTED", `Pacifica ${what} refused (HTTP ${res.status}, nothing was changed): ${text.slice(0, 300)}`, {
                         exchange: "pacifica",
                         httpStatus: res.status,
@@ -130,6 +197,7 @@ export class PacificaClient {
             }
         }
         finally {
+            ticket.release(); // no-op once settled; a transport failure frees the reservation
             // Every POST is an account write (order / cancel / TP/SL / leverage / transfer): drop the
             // shared acct: disk cache so no later read serves the pre-write positions / orders.
             invalidateCache("acct");
@@ -377,6 +445,71 @@ export class PacificaClient {
         const body = await this.signedBody("withdraw_from_lake", params, account, signMessage);
         return this.post("/lake/withdraw", body);
     }
+    // ==================== PRINT (game) + VAULT READS / PRE-SIGNED WRITES ====================
+    // Shapes and parsing live in src/exchanges/pacifica-print.ts / pacifica-vaults.ts.
+    /**
+     * Unauthenticated GET that keeps the whole {success, data, has_more, next_cursor} envelope.
+     * Same credit limiter as get() (unsigned IP quota, PACIFICA_READ_NEED: may wait for the window,
+     * else RATE_LIMITED sent:false); the response headers are recorded; HTTP 429 → RATE_LIMITED
+     * (structural, never retried). Timeout → TIMEOUT, transport failure → EXCHANGE_UNREACHABLE,
+     * non-JSON / non-object body → EXCHANGE_ERROR (a read: nothing can have changed).
+     */
+    async getEnvelope(path, params = {}) {
+        checkAddressParams(params);
+        const url = new URL(`${this.baseUrl}${path}`);
+        for (const [k, v] of Object.entries(params))
+            url.searchParams.set(k, v);
+        const what = `GET ${path}`;
+        const ticket = await this.rate.acquire(what, PACIFICA_READ_NEED);
+        let res;
+        let text;
+        try {
+            res = await fetch(url.toString(), { headers: this.headers(), signal: AbortSignal.timeout(PACIFICA_POST_TIMEOUT_MS) });
+            ticket.settle(res);
+            text = await res.text();
+        }
+        catch (e) {
+            const timedOut = e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError");
+            throw new PerpError(timedOut ? "TIMEOUT" : "EXCHANGE_UNREACHABLE", `Pacifica GET ${path} ${timedOut ? `timed out after ${PACIFICA_POST_TIMEOUT_MS} ms` : `failed: ${extractErrorMessage(e)}`}`, {
+                exchange: "pacifica", remediation: "Retry; if it keeps failing check the network and Pacifica's status",
+            });
+        }
+        finally {
+            ticket.release(); // no-op once settled; a transport failure frees the reservation
+        }
+        if (res.status === 429)
+            throw this.rate.rateLimitedError(what, res, text);
+        if (!res.ok)
+            throw new Error(`GET ${path} failed (${res.status}): ${text}`);
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new PerpError("EXCHANGE_ERROR", `Pacifica GET ${path} returned a non-JSON body (HTTP ${res.status}): ${text.slice(0, 160)}`, { exchange: "pacifica" });
+        }
+        if (json === null || typeof json !== "object" || Array.isArray(json)) {
+            throw new PerpError("EXCHANGE_ERROR", `Pacifica GET ${path} returned a non-object body: ${text.slice(0, 160)}`, { exchange: "pacifica" });
+        }
+        return json;
+    }
+    /**
+     * POST a body the caller already built and signed (Print / vault writes sign their own canonical
+     * message so `--dry-run` can show the exact body). Same unknown-outcome rules as every write.
+     */
+    async postPresigned(path, body) {
+        return this.post(path, body);
+    }
+    /**
+     * Pre-sign credit wait for a pre-signed write (same rule as signedBody / amend): call BEFORE
+     * building + signing, so the post-sign wait in post() (≤ PACIFICA_SIGNED_MAX_WAIT_MS, inside the
+     * 5 s expiry_window) finds credits. Cost: the docs' rate-limits table lists no Print / vault
+     * entry — "Standard request/action: 1 credit" applies (end_game is not an order cancellation).
+     * Fail-fast RATE_LIMITED here sent and signed nothing (details.sent === false).
+     */
+    async awaitPresignedCapacity(operationType) {
+        await this.signedRate.awaitCapacity(operationType, writeNeed(false, PACIFICA_MAX_THROTTLE_WAIT_MS));
+    }
     // ==================== BUILDER CODE ====================
     async approveBuilderCode(params, account, signMessage) {
         const body = await this.signedBody("approve_builder_code", params, account, signMessage);
@@ -408,7 +541,47 @@ export class PacificaClient {
         return this.post("/referral/user/code/claim", body);
     }
     // ==================== BATCH ====================
-    async batchOrders(actions) {
-        return this.post("/orders/batch", { actions });
+    /**
+     * POST /orders/batch with the per-action cost (pacificaBatchCost) reserved. `maxWaitMs` caps the
+     * post-sign throttle wait (default PACIFICA_SIGNED_MAX_WAIT_MS, never more): a caller with a
+     * tighter signature deadline passes what is left of it, so a wait can never send an expired batch
+     * — a longer wait fails fast with RATE_LIMITED (sent: false, nothing sent).
+     */
+    async batchOrders(actions, opts = {}) {
+        const maxWaitMs = Math.max(0, Math.min(opts.maxWaitMs !== undefined ? opts.maxWaitMs : PACIFICA_SIGNED_MAX_WAIT_MS, PACIFICA_SIGNED_MAX_WAIT_MS));
+        return this.post("/orders/batch", { actions }, { cost: pacificaBatchCost(actions.map(a => a.type)), reserve: 0, maxWaitMs });
+    }
+    /**
+     * Pre-sign throttle for a batch (like signedBody does for single writes): wait — up to
+     * PACIFICA_MAX_THROTTLE_WAIT_MS, else RATE_LIMITED with nothing signed or sent — until the
+     * batch's whole cost fits, so the post-sign acquire in batchOrders normally finds the credits.
+     */
+    async awaitBatchCapacity(types) {
+        await this.signedRate.awaitCapacity("POST /orders/batch", { cost: pacificaBatchCost(types), reserve: 0, maxWaitMs: PACIFICA_MAX_THROTTLE_WAIT_MS });
+    }
+    /**
+     * One signed batch action body (docs rest-api/orders/batch-order: "Batch orders are not signed
+     * as a whole, but rather by its individual actions components"; each action's `data` carries the
+     * fields of its standalone endpoint, signed with that endpoint's operation type). Nothing is sent.
+     * `header` fixes the signed timestamp / expiry window, so every action of one batch can share
+     * one timestamp. agent_wallet is attached when an agent is the active signer. A signing failure
+     * → ORDER_REJECTED (orderNotSent).
+     */
+    async signBatchAction(operationType, payload, account, signMessage, header) {
+        const full = { type: operationType, timestamp: header.timestamp, expiry_window: header.expiry_window };
+        try {
+            const [, signature] = await signWithWallet(full, payload, signMessage);
+            return {
+                account,
+                ...(this.requestAgentWallet ? { agent_wallet: this.requestAgentWallet } : {}),
+                signature,
+                timestamp: full.timestamp,
+                expiry_window: full.expiry_window,
+                ...payload,
+            };
+        }
+        catch (e) {
+            throw orderNotSent("pacifica", operationType, e);
+        }
     }
 }

package/dist/pacifica/rate-limit.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Pacifica credit rate limit, read from the venue's own response headers.
+ *
+ * docs.pacifica.fi api-documentation/api/rate-limits (read 2026-10-19): credit-based, rolling
+ * 60 s window; 100 credits / 60 s per unidentified IP, 300 with a valid API Config Key (more for
+ * higher fee tiers); standard request 1, cancel 0.5, heavy GET 3-12 (1-4 with a key). Exhausted →
+ * HTTP 429. "All credit values are multiplied by 10 to support fractional costs":
+ *
+ *   ratelimit: "credits";r=1200;t=32        r = remaining (×10), t = seconds until refresh
+ *   ratelimit-policy: "credits";q=1250;w=60 q = quota per window (×10), w = window seconds
+ *
+ * Live mainnet GET /info/prices (2026-10-19, no key): `ratelimit: "credits";r=980;t=22`,
+ * `ratelimit-policy: "credits";q=1000;w=60`. Values below stay in those ×10 units.
+ *
+ * CloudFront caches some GETs (/info: `x-cache: Hit from cloudfront`, `age: 16`): a cache hit
+ * replays the headers of whoever filled the cache (live: q=3000, a keyed caller) — not this
+ * caller's quota, so a hit carries no information.
+ *
+ * Scope: one state per REST base URL (mainnet / testnet), credential tier (no key = IP quota;
+ * an API Config Key has its own) and request kind (signed POST vs unsigned GET). Process-local: other perp-cli processes (CLI + MCP + bots) on the
+ * same IP spend the same quota unseen, so a 429 can still happen — it is then surfaced as
+ * RATE_LIMITED, never retried here.
+ */
+import { PerpError } from "../errors.js";
+/** One parsed `ratelimit` (+ optional `ratelimit-policy`) observation, in credits ×10. */
+export interface PacificaRateLimitInfo {
+    remaining: number;
+    resetSec: number;
+    /** null = `ratelimit-policy` absent or malformed. */
+    quota: number | null;
+    windowSec: number | null;
+}
+/**
+ * Strict parse of the `ratelimit` / `ratelimit-policy` header values. `ratelimit` absent or
+ * malformed (no `"credits"` item, missing / non-integer / duplicate r or t) → null: no info, never
+ * a guessed value. A malformed policy only nulls quota / windowSec.
+ */
+export declare function parsePacificaRateLimit(ratelimit: string | null, policy: string | null): PacificaRateLimitInfo | null;
+/** `Retry-After` in delta-seconds → ms; absent / HTTP-date / malformed → null. */
+export declare function parseRetryAfterMs(raw: string | null): number | null;
+type HeaderSource = {
+    headers?: {
+        get(name: string): string | null;
+    };
+} | null | undefined;
+/** Parsed rate-limit info of a response this caller's request produced; null = no info. */
+export declare function pacificaRateLimitOf(res: HeaderSource): PacificaRateLimitInfo | null;
+/** Read reserve (credits ×10): the largest documented heavy-GET cost (12 credits) stays unspent after a read. */
+export declare const PACIFICA_READ_RESERVE = 120;
+/** Cost (credits ×10) of a standard request / action (docs: 1 credit). */
+export declare const PACIFICA_COST_STANDARD = 10;
+/** Cost (credits ×10) of an order cancellation (docs: 0.5 credits). */
+export declare const PACIFICA_COST_CANCEL = 5;
+/** Longest pre-send wait before failing fast with RATE_LIMITED. */
+export declare const PACIFICA_MAX_THROTTLE_WAIT_MS = 15000;
+/** Longest wait between signing and sending (signed bodies expire after expiry_window = 5 s). */
+export declare const PACIFICA_SIGNED_MAX_WAIT_MS = 2000;
+export interface RateClock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+/** What a request needs before it may be sent. */
+export interface RateNeed {
+    /** Credits ×10 this request is assumed to cost (PACIFICA_COST_*). */
+    cost: number;
+    /**
+     * Credits ×10 that must still be left after this request (observed remaining − in flight − cost):
+     * reads keep the heavy-GET reserve (PACIFICA_READ_RESERVE); writes 0 — a write needs only its own
+     * cost, so an amend's replacement leg is never blocked by the read reserve.
+     */
+    reserve: number;
+    /** Longest pre-send wait; longer → RATE_LIMITED fail-fast (0 = never wait). */
+    maxWaitMs: number;
+}
+export declare const PACIFICA_READ_NEED: RateNeed;
+/** A reserved request: settle with its response (or release on a transport failure). Idempotent. */
+export interface RateTicket {
+    settle(res: HeaderSource): PacificaRateLimitInfo | null;
+    release(): void;
+}
+export declare class PacificaRateLimiter {
+    private readonly label;
+    private readonly clock;
+    private obs;
+    /** Credits ×10 reserved by requests sent and not yet settled — not reset by observe(). */
+    private inFlight;
+    private lastRaw;
+    private skew;
+    constructor(label: string, clock?: RateClock);
+    /** clock.now() made monotonic: a backwards step is absorbed instead of restarting elapsed time. */
+    private now;
+    /** ms until the observed window refreshes; null = no live observation. */
+    private resetWaitMs;
+    /** Current state for diagnostics (credits ×10); null = no live observation. */
+    snapshot(): {
+        remaining: number;
+        inFlight: number;
+        effectiveRemaining: number;
+        resetInMs: number;
+    } | null;
+    /** ms to wait before a request with `need` may be sent: 0 = now (no info, or enough credits left). */
+    waitMs(need: Pick<RateNeed, "cost" | "reserve">): number;
+    private ticket;
+    /**
+     * Pre-send throttle + reservation. Enough credits (or no info) → the cost is reserved
+     * synchronously, before any await, so concurrent callers see each other. Otherwise waits for the
+     * window to refresh (total ≤ need.maxWaitMs) or fails fast with RATE_LIMITED (sent: false).
+     */
+    acquire(what: string, need: RateNeed): Promise<RateTicket>;
+    /** Like acquire but never waits or refuses (health probe): reserves and records only. */
+    track(cost: number): RateTicket;
+    /** Wait (no reservation) until `need` would pass — used before signing, so the post-sign acquire finds credits. */
+    awaitCapacity(what: string, need: RateNeed): Promise<void>;
+    private throttled;
+    /**
+     * Record a response's headers (any status). No / malformed / cached headers → unchanged. Within
+     * the live window an observation with a higher `r` (a late response from before others landed)
+     * or a different `q` (another quota: account vs IP) is dropped.
+     */
+    observe(res: HeaderSource): PacificaRateLimitInfo | null;
+    /**
+     * HTTP 429 → RATE_LIMITED (structural, by status). retryAfterMs = `Retry-After`, else the
+     * ratelimit reset `t`, else absent (clamped to the window). The quota is recorded as exhausted.
+     *
+     * `sent: false` ("not executed") is OUR reading of the docs — "When credits are exhausted,
+     * requests return HTTP 429" — i.e. the request is refused before processing. Pacifica does not
+     * state explicitly that a 429'd write was not executed.
+     */
+    rateLimitedError(what: string, res: HeaderSource & {
+        status: number;
+    }, body: string): PerpError;
+}
+/** A Pacifica RATE_LIMITED that sent nothing (pre-send throttle or HTTP 429): a definite refusal. */
+export declare function isPacificaRateLimited(e: unknown): boolean;
+/**
+ * The process-local limiter for a REST base URL + credential tier (no key = IP quota) + request
+ * kind. Signed POSTs are kept apart from unsigned GETs: credits are shared per main account and
+ * scale with its fee tier, so signed responses can report an account quota (e.g. q=3000) while
+ * keyless GETs report the IP quota (q=1000).
+ */
+export declare function pacificaRateLimiter(baseUrl: string, apiKey: string | undefined, kind: "signed" | "unsigned"): PacificaRateLimiter;
+/** Test hook: forget every limiter's state. */
+export declare function resetPacificaRateLimiters(): void;
+export {};