perp-cli 0.12.17 → 0.14.0

package/dist/mcp-trade-guard.d.ts

@@ -0,0 +1,16 @@
+import { type ExecutionRecord } from "./execution-log.js";
+import type { ExchangeAdapter } from "./exchanges/interface.js";
+import type { Network } from "./exchanges/venue-types.js";
+/** Refuse a reduce-only order up front on a venue whose reduce-only orders are gated (uniform CAPABILITY_UNSUPPORTED). */
+export declare function mcpReduceOnlyGate(adapter: ExchangeAdapter): void;
+/** PERP_NETWORK → network. Unset = "mainnet" (documented default); any other value must parse. */
+export declare function resolveMcpNetwork(env: string | undefined): Network;
+/** Pre-send gate for an MCP order: quarantine (non-reduce-only), then local risk limits (never forced). */
+export declare function mcpPreTradeGate(adapter: ExchangeAdapter, p: {
+    symbol: string;
+    size: number;
+    price: number | null;
+    reduceOnly: boolean;
+}, log: (msg: string) => void): Promise<void>;
+/** Execution-log entry for an MCP order (source + network recorded in meta). */
+export declare function logMcpExecution(network: Network, record: Omit<ExecutionRecord, "id" | "timestamp" | "dryRun">): ExecutionRecord;

package/dist/mcp-trade-guard.js

@@ -0,0 +1,59 @@
+/**
+ * MCP write-path safety (review N4): the MCP `trade_execute` / `trade_close` tools go through
+ * the same gates as `perp trade`:
+ *
+ *  - network: PERP_NETWORK, validated by the same parser as `-n` (unset = mainnet, the
+ *    documented default — never a silent substitution for an invalid value);
+ *  - quarantine: a non-reduce-only order on a quarantined symbol is refused (an earlier
+ *    unknown outcome must be resolved by a human first);
+ *  - local risk limits: enforceOrderRisk with force=false — there is NO force override over
+ *    MCP (an agent must not be able to bypass the user's limits);
+ *  - execution log: every placed / failed order is appended to ~/.perp/executions.jsonl,
+ *    tagged source "mcp" and the network;
+ *  - venue gates: a reduce-only order (trade_execute reduceOnly, trade_close) on a venue whose
+ *    reduce-only orders are currently refused (none today) fails with the uniform
+ *    CAPABILITY_UNSUPPORTED before any read or send (mcpReduceOnlyGate).
+ */
+import { parseNetwork } from "./cli-flags.js";
+import { PerpError } from "./errors.js";
+import { logExecution } from "./execution-log.js";
+import { quarantineEntryFor } from "./bot/quarantine.js";
+import { enforceOrderRisk } from "./trade-validator.js";
+import { reduceOnlyGateOf } from "./exchanges/trading-v2.js";
+/** Refuse a reduce-only order up front on a venue whose reduce-only orders are gated (uniform CAPABILITY_UNSUPPORTED). */
+export function mcpReduceOnlyGate(adapter) {
+    const gate = reduceOnlyGateOf(adapter);
+    if (gate !== null)
+        throw gate;
+}
+/** PERP_NETWORK → network. Unset = "mainnet" (documented default); any other value must parse. */
+export function resolveMcpNetwork(env) {
+    if (env === undefined)
+        return "mainnet";
+    return parseNetwork(env);
+}
+/** Pre-send gate for an MCP order: quarantine (non-reduce-only), then local risk limits (never forced). */
+export async function mcpPreTradeGate(adapter, p, log) {
+    if (p.reduceOnly)
+        mcpReduceOnlyGate(adapter);
+    if (!p.reduceOnly) {
+        const q = quarantineEntryFor(p.symbol, log);
+        if (q !== null) {
+            throw new PerpError("RISK_VIOLATION", `${p.symbol} is quarantined by ${q.strategy}: ${q.reason}`, {
+                exchange: adapter.name,
+                remediation: `${q.remediation} — only reduce-only orders are accepted until a human clears it (perp strategy quarantine-clear ${p.symbol})`,
+            });
+        }
+    }
+    await enforceOrderRisk(adapter, {
+        symbol: p.symbol,
+        size: p.size,
+        ...(p.price !== null ? { price: p.price } : {}),
+        reduceOnly: p.reduceOnly,
+        force: false,
+    });
+}
+/** Execution-log entry for an MCP order (source + network recorded in meta). */
+export function logMcpExecution(network, record) {
+    return logExecution({ ...record, dryRun: false, meta: { ...(record.meta ?? {}), source: "mcp", network } });
+}

package/dist/pacifica/client.d.ts

@@ -1,21 +1,47 @@
 import { type Network } from "./constants.js";
 import type { MarketInfo, PriceInfo, Orderbook, Trade, Kline, KlineInterval, AggLevel, AccountInfo, AccountSettings, Position, OrderInfo, MarketOrderParams, LimitOrderParams, StopOrderParams, EditOrderParams, CancelOrderParams, CancelAllOrdersParams, TWAPParams, CancelTWAPParams, TPSLParams, UpdateLeverageParams, WithdrawParams, TransferFundsParams, BatchAction, CreateLakeParams, LakeDepositParams, LakeWithdrawParams } from "./types/index.js";
 type SignMessageFn = (message: Uint8Array) => Promise<Uint8Array>;
+/** Per-request timeout of a POST (fetch + body read). */
+export declare const PACIFICA_POST_TIMEOUT_MS = 15000;
 export interface PacificaClientConfig {
     network?: Network;
     baseUrl?: string;
     apiKey?: string;
-    builderCode?: string;
 }
 export declare class PacificaClient {
     private baseUrl;
     private apiKey?;
-    private builderCode;
+    /**
+     * Agent-wallet pubkey for the current request signer, set by the adapter when an
+     * agent wallet (not the master) is signing. When present, signed bodies carry the
+     * `agent_wallet` field (with account = master) so Pacifica verifies the signature
+     * against the agent key. Undefined for master/PK signers.
+     */
+    private requestAgentWallet?;
+    /** Attach (or clear) the agent wallet used for subsequent signed requests. */
+    setRequestAgentWallet(agentWallet?: string): void;
+    /** Build a signed POST body, attaching agent_wallet when an agent is the active signer. */
+    private signedBody;
     constructor(config?: PacificaClientConfig);
     private headers;
     private get;
+    /**
+     * Signed POST. Every path except the listing reads (READ_POST_PATHS) is an account write: once
+     * the request is on the wire a connection reset / timeout / 5xx / unreadable body leaves the
+     * 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;
+   * on a listing read a timeout is TIMEOUT and any other transport failure EXCHANGE_UNREACHABLE.
+     */
     private post;
-    private addBuilderCode;
+    /**
+     * `builder_code` is attached only when the caller passes one — the adapter decides
+     * (settings builder.pacifica + confirmed approval, src/exchanges/builder-fee.ts).
+     * null = no builder code (the default, and always for spot: err 108).
+     */
+    private withBuilderCode;
     getInfo(): Promise<MarketInfo[]>;
     getPrices(): Promise<PriceInfo[]>;
     getBook(symbol: string, aggLevel?: AggLevel): Promise<Orderbook>;
@@ -26,7 +52,7 @@ export declare class PacificaClient {
         cursor?: string;
     }): Promise<unknown>;
     getAccount(account: string): Promise<AccountInfo>;
-    getAccountSettings(account: string): Promise<AccountSettings[]>;
+    getAccountSettings(account: string): Promise<AccountSettings>;
     getPositions(account: string): Promise<Position[]>;
     getOrders(account: string): Promise<OrderInfo[]>;
     getOrderHistory(account: string, opts?: {
@@ -56,9 +82,9 @@ export declare class PacificaClient {
     }): Promise<unknown>;
     getOrderHistoryById(orderId: number): Promise<unknown>;
     getTWAPOrders(account: string): Promise<unknown[]>;
-    createMarketOrder(params: MarketOrderParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
-    createLimitOrder(params: LimitOrderParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
-    createStopOrder(params: StopOrderParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
+    createMarketOrder(params: MarketOrderParams, account: string, signMessage: SignMessageFn, builderCode: string | null): Promise<unknown>;
+    createLimitOrder(params: LimitOrderParams, account: string, signMessage: SignMessageFn, builderCode: string | null): Promise<unknown>;
+    createStopOrder(params: StopOrderParams, account: string, signMessage: SignMessageFn, builderCode: string | null): Promise<unknown>;
     editOrder(params: EditOrderParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
     cancelOrder(params: CancelOrderParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
     cancelAllOrders(params: CancelAllOrdersParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
@@ -66,23 +92,28 @@ export declare class PacificaClient {
         symbol: string;
         order_id: number;
     }, account: string, signMessage: SignMessageFn): Promise<unknown>;
+    /** create_twap_order documents no builder_code, so a TWAP never carries one (builder-fee.ts). */
     createTWAP(params: TWAPParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
     cancelTWAP(params: CancelTWAPParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
-    setTPSL(params: TPSLParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
+    setTPSL(params: TPSLParams, account: string, signMessage: SignMessageFn, builderCode: string | null): Promise<unknown>;
     updateLeverage(params: UpdateLeverageParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
     updateMarginMode(params: {
         symbol: string;
         is_isolated: boolean;
     }, account: string, signMessage: SignMessageFn): Promise<unknown>;
     withdraw(params: WithdrawParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
-    createSubaccount(subaccountName: string, account: string, signMessage: SignMessageFn): Promise<unknown>;
     listSubaccounts(account: string, signMessage: SignMessageFn): Promise<unknown>;
     transferFunds(params: TransferFundsParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
     bindAgentWallet(agentWallet: string, account: string, signMessage: SignMessageFn): Promise<unknown>;
     listAgentWallets(account: string, signMessage: SignMessageFn): Promise<unknown>;
     revokeAgentWallet(agentWallet: string, account: string, signMessage: SignMessageFn): Promise<unknown>;
     revokeAllAgentWallets(account: string, signMessage: SignMessageFn): Promise<unknown>;
-    createApiKey(name: string, maxFeeRate: string, account: string, signMessage: SignMessageFn): Promise<unknown>;
+    /**
+     * API Config Key (rate-limit key). Docs (api/rate-limits/api-config-keys): the request body is
+     * account / signature / timestamp / expiry_window only; python-sdk rest/api_config_keys.py signs
+     * type "create_api_key" with `signature_payload = {}`.
+     */
+    createApiKey(account: string, signMessage: SignMessageFn): Promise<unknown>;
     listApiKeys(account: string, signMessage: SignMessageFn): Promise<unknown>;
     revokeApiKey(apiKey: string, account: string, signMessage: SignMessageFn): Promise<unknown>;
     createLake(params: CreateLakeParams, account: string, signMessage: SignMessageFn): Promise<unknown>;

package/dist/pacifica/client.js

@@ -1,14 +1,49 @@
-import { BUILDER_CODE, getNetworkConfig } from "./constants.js";
-import { buildSignedRequest } from "./signing.js";
+import { getNetworkConfig } from "./constants.js";
+import { buildSignedRequest, buildAgentSignedRequest } from "./signing.js";
+import { PerpError, extractErrorMessage, orderNotSent, orderOutcomeUnknown, sendFailure } from "../errors.js";
+import { invalidateCache } from "../cache.js";
+/** Per-request timeout of a POST (fetch + body read). */
+export const PACIFICA_POST_TIMEOUT_MS = 15_000;
+/**
+ * Account-setting writes whose HTTP 4xx is the venue's explicit refusal (nothing changed).
+ * docs.pacifica.fi (api-documentation/api/rest-api):
+ *   account/update-leverage:      "Status 400: Invalid request parameters" — {"error": "Invalid leverage", "code": 400}
+ *   orders/create-position-tp-sl: "Status 400: Bad request" — {"error": "Position not found", "code": 400}
+ * Both pages list only "Status 500: Internal server error" besides.
+ */
+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"]);
 export class PacificaClient {
     baseUrl;
     apiKey;
-    builderCode;
+    /**
+     * Agent-wallet pubkey for the current request signer, set by the adapter when an
+     * agent wallet (not the master) is signing. When present, signed bodies carry the
+     * `agent_wallet` field (with account = master) so Pacifica verifies the signature
+     * against the agent key. Undefined for master/PK signers.
+     */
+    requestAgentWallet;
+    /** 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) {
+        try {
+            return await (this.requestAgentWallet
+                ? buildAgentSignedRequest(operationType, payload, account, this.requestAgentWallet, signMessage)
+                : buildSignedRequest(operationType, payload, account, signMessage));
+        }
+        catch (e) {
+            // Signing failed before any request was sent: definitely not placed (never ORDER_PENDING).
+            throw orderNotSent("pacifica", operationType, e);
+        }
+    }
     constructor(config = {}) {
         this.baseUrl =
             config.baseUrl || getNetworkConfig(config.network).restUrl;
         this.apiKey = config.apiKey;
-        this.builderCode = config.builderCode || BUILDER_CODE;
     }
     headers() {
         const h = { "Content-Type": "application/json" };
@@ -36,23 +71,77 @@ export class PacificaClient {
         }
         return json;
     }
+    /**
+     * Signed POST. Every path except the listing reads (READ_POST_PATHS) is an account write: once
+     * the request is on the wire a connection reset / timeout / 5xx / unreadable body leaves the
+     * 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;
+   * on a listing read a timeout is TIMEOUT and any other transport failure EXCHANGE_UNREACHABLE.
+     */
     async post(path, body) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            method: "POST",
-            headers: this.headers(),
-            body: JSON.stringify(body),
-        });
-        if (!res.ok) {
-            const text = await res.text();
-            throw new Error(`POST ${path} failed (${res.status}): ${text}`);
+        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`;
+        try {
+            let res;
+            let text;
+            try {
+                res = await fetch(`${this.baseUrl}${path}`, {
+                    method: "POST",
+                    headers: this.headers(),
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(PACIFICA_POST_TIMEOUT_MS),
+                });
+                text = await res.text();
+            }
+            catch (e) {
+                if (write)
+                    throw sendFailure("pacifica", what, e, remediation);
+                // Signed listing read: nothing can have been executed — an ordinary retryable read failure.
+                const timedOut = e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError");
+                throw new PerpError(timedOut ? "TIMEOUT" : "EXCHANGE_UNREACHABLE", `Pacifica ${what} ${timedOut ? `timed out after ${PACIFICA_POST_TIMEOUT_MS} ms` : `failed: ${extractErrorMessage(e)}`} (read-only listing; nothing was changed)`, {
+                    exchange: "pacifica",
+                    remediation: "Retry; if it keeps failing check the network and Pacifica's status",
+                });
+            }
+            if (write && res.status >= 500) {
+                throw orderOutcomeUnknown("pacifica", what, new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`), remediation);
+            }
+            if (!res.ok) {
+                if (DEFINITE_4XX_PATHS.has(path) && res.status >= 400 && res.status < 500 && res.status !== 429) {
+                    throw new PerpError("ACTION_REJECTED", `Pacifica ${what} refused (HTTP ${res.status}, nothing was changed): ${text.slice(0, 300)}`, {
+                        exchange: "pacifica",
+                        httpStatus: res.status,
+                        remediation: "The venue rejected the request — fix the parameters named in the message and retry",
+                    });
+                }
+                throw new Error(`POST ${path} failed (${res.status}): ${text}`);
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (e) {
+                if (!write)
+                    throw e;
+                throw orderOutcomeUnknown("pacifica", what, new Error(`unreadable response (HTTP ${res.status}): ${text.slice(0, 200)}`), remediation);
+            }
         }
-        return res.json();
-    }
-    addBuilderCode(payload) {
-        if (this.builderCode) {
-            return { ...payload, builder_code: this.builderCode };
+        finally {
+            // 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");
         }
-        return payload;
+    }
+    /**
+     * `builder_code` is attached only when the caller passes one — the adapter decides
+     * (settings builder.pacifica + confirmed approval, src/exchanges/builder-fee.ts).
+     * null = no builder code (the default, and always for spot: err 108).
+     */
+    withBuilderCode(payload, builderCode) {
+        return builderCode === null ? payload : { ...payload, builder_code: builderCode };
     }
     // ==================== PUBLIC ENDPOINTS ====================
     async getInfo() {
@@ -158,135 +247,150 @@ export class PacificaClient {
         return this.get("/orders/twap", { account });
     }
     // ==================== AUTHENTICATED POST ENDPOINTS ====================
-    async createMarketOrder(params, account, signMessage) {
-        const payload = this.addBuilderCode({ ...params });
-        const body = await buildSignedRequest("create_market_order", payload, account, signMessage);
+    async createMarketOrder(params, account, signMessage, builderCode) {
+        const payload = this.withBuilderCode({ ...params }, builderCode);
+        const body = await this.signedBody("create_market_order", payload, account, signMessage);
         return this.post("/orders/create_market", body);
     }
-    async createLimitOrder(params, account, signMessage) {
-        const payload = this.addBuilderCode({ ...params });
-        const body = await buildSignedRequest("create_order", payload, account, signMessage);
+    async createLimitOrder(params, account, signMessage, builderCode) {
+        const payload = this.withBuilderCode({ ...params }, builderCode);
+        const body = await this.signedBody("create_order", payload, account, signMessage);
         return this.post("/orders/create", body);
     }
-    async createStopOrder(params, account, signMessage) {
-        const body = await buildSignedRequest("create_stop_order", params, account, signMessage);
+    async createStopOrder(params, account, signMessage, builderCode) {
+        // builder_code applies to every order-creation endpoint, stop orders included (builder-program docs).
+        const payload = this.withBuilderCode({ ...params }, builderCode);
+        const body = await this.signedBody("create_stop_order", payload, account, signMessage);
         return this.post("/orders/stop/create", body);
     }
     async editOrder(params, account, signMessage) {
-        const body = await buildSignedRequest("edit_order", params, account, signMessage);
+        const body = await this.signedBody("edit_order", params, account, signMessage);
         return this.post("/orders/edit", body);
     }
     async cancelOrder(params, account, signMessage) {
-        const body = await buildSignedRequest("cancel_order", params, account, signMessage);
+        const body = await this.signedBody("cancel_order", params, account, signMessage);
         return this.post("/orders/cancel", body);
     }
     async cancelAllOrders(params, account, signMessage) {
-        const body = await buildSignedRequest("cancel_all_orders", params, account, signMessage);
+        const body = await this.signedBody("cancel_all_orders", params, account, signMessage);
         return this.post("/orders/cancel_all", body);
     }
     async cancelStopOrder(params, account, signMessage) {
-        const body = await buildSignedRequest("cancel_stop_order", params, account, signMessage);
+        const body = await this.signedBody("cancel_stop_order", params, account, signMessage);
         return this.post("/orders/stop/cancel", body);
     }
+    /** create_twap_order documents no builder_code, so a TWAP never carries one (builder-fee.ts). */
     async createTWAP(params, account, signMessage) {
-        const payload = this.addBuilderCode({ ...params });
-        const body = await buildSignedRequest("create_twap_order", payload, account, signMessage);
+        const body = await this.signedBody("create_twap_order", { ...params }, account, signMessage);
         return this.post("/orders/twap/create", body);
     }
     async cancelTWAP(params, account, signMessage) {
-        const body = await buildSignedRequest("cancel_twap_order", params, account, signMessage);
+        const body = await this.signedBody("cancel_twap_order", params, account, signMessage);
         return this.post("/orders/twap/cancel", body);
     }
-    async setTPSL(params, account, signMessage) {
-        const body = await buildSignedRequest("set_position_tpsl", params, account, signMessage);
+    async setTPSL(params, account, signMessage, builderCode) {
+        // Position TP/SL creates orders and therefore takes builder_code too (POST /positions/tpsl).
+        const payload = this.withBuilderCode({ ...params }, builderCode);
+        const body = await this.signedBody("set_position_tpsl", payload, account, signMessage);
         return this.post("/positions/tpsl", body);
     }
     async updateLeverage(params, account, signMessage) {
-        const body = await buildSignedRequest("update_leverage", params, account, signMessage);
+        const body = await this.signedBody("update_leverage", params, account, signMessage);
         return this.post("/account/leverage", body);
     }
     async updateMarginMode(params, account, signMessage) {
-        const body = await buildSignedRequest("update_margin_mode", params, account, signMessage);
+        const body = await this.signedBody("update_margin_mode", params, account, signMessage);
         return this.post("/account/margin", body);
     }
     async withdraw(params, account, signMessage) {
-        const body = await buildSignedRequest("withdraw", params, account, signMessage);
+        const body = await this.signedBody("withdraw", params, account, signMessage);
         return this.post("/account/withdraw", body);
     }
     // ==================== SUBACCOUNT ====================
-    async createSubaccount(subaccountName, account, signMessage) {
-        // Step 1: Initiate
-        const initiateBody = await buildSignedRequest("subaccount_initiate", { subaccount_name: subaccountName }, account, signMessage);
-        await this.post("/account/subaccount/create", initiateBody);
-        // Step 2: Confirm
-        const confirmBody = await buildSignedRequest("subaccount_confirm", { subaccount_name: subaccountName }, account, signMessage);
-        return this.post("/account/subaccount/create", confirmBody);
-    }
+    // POST /account/subaccount/create is not implemented. Docs (rest-api/subaccounts/create-subaccount):
+    // "Both the main account and subaccount must sign to establish the relationship." — the body is
+    // {main_account, subaccount, main_signature, sub_signature, timestamp, expiry_window}; the
+    // subaccount keypair signs {account: <main>} ("subaccount_initiate") and the main account signs
+    // {signature: <sub_signature>} ("subaccount_confirm") (python-sdk rest/create_subaccount.py).
+    // perp-cli has no second (subaccount) keypair source, so `manage sub create` is gated.
     async listSubaccounts(account, signMessage) {
-        const body = await buildSignedRequest("list_subaccounts", {}, account, signMessage);
+        const body = await this.signedBody("list_subaccounts", {}, account, signMessage);
         return this.post("/account/subaccount/list", body);
     }
     async transferFunds(params, account, signMessage) {
-        const body = await buildSignedRequest("transfer_funds", params, account, signMessage);
+        const body = await this.signedBody("transfer_funds", params, account, signMessage);
         return this.post("/account/subaccount/transfer", body);
     }
     // ==================== AGENT WALLET ====================
     async bindAgentWallet(agentWallet, account, signMessage) {
-        const body = await buildSignedRequest("bind_agent_wallet", { agent_wallet: agentWallet }, account, signMessage);
+        const body = await this.signedBody("bind_agent_wallet", { agent_wallet: agentWallet }, account, signMessage);
         return this.post("/agent/bind", body);
     }
     async listAgentWallets(account, signMessage) {
-        const body = await buildSignedRequest("list_agent_wallets", {}, account, signMessage);
+        const body = await this.signedBody("list_agent_wallets", {}, account, signMessage);
         return this.post("/agent/list", body);
     }
     async revokeAgentWallet(agentWallet, account, signMessage) {
-        const body = await buildSignedRequest("revoke_agent_wallet", { agent_wallet: agentWallet }, account, signMessage);
+        const body = await this.signedBody("revoke_agent_wallet", { agent_wallet: agentWallet }, account, signMessage);
         return this.post("/agent/revoke", body);
     }
     async revokeAllAgentWallets(account, signMessage) {
-        const body = await buildSignedRequest("revoke_all_agent_wallets", {}, account, signMessage);
+        const body = await this.signedBody("revoke_all_agent_wallets", {}, account, signMessage);
         return this.post("/agent/revoke_all", body);
     }
     // ==================== API KEYS ====================
-    async createApiKey(name, maxFeeRate, account, signMessage) {
-        const body = await buildSignedRequest("create_api_key", { name, max_fee_rate: maxFeeRate }, account, signMessage);
+    /**
+     * API Config Key (rate-limit key). Docs (api/rate-limits/api-config-keys): the request body is
+     * account / signature / timestamp / expiry_window only; python-sdk rest/api_config_keys.py signs
+     * type "create_api_key" with `signature_payload = {}`.
+     */
+    async createApiKey(account, signMessage) {
+        const body = await this.signedBody("create_api_key", {}, account, signMessage);
         return this.post("/account/api_keys/create", body);
     }
     async listApiKeys(account, signMessage) {
-        const body = await buildSignedRequest("list_api_keys", {}, account, signMessage);
+        const body = await this.signedBody("list_api_keys", {}, account, signMessage);
         return this.post("/account/api_keys", body);
     }
     async revokeApiKey(apiKey, account, signMessage) {
-        const body = await buildSignedRequest("revoke_api_key", { api_key: apiKey }, account, signMessage);
+        const body = await this.signedBody("revoke_api_key", { api_key: apiKey }, account, signMessage);
         return this.post("/account/api_keys/revoke", body);
     }
     // ==================== LAKE ====================
     async createLake(params, account, signMessage) {
-        const body = await buildSignedRequest("create_lake", params, account, signMessage);
+        // Optional fields are omitted, not sent as null (the signed payload must equal the body).
+        const payload = {};
+        if (params.manager !== null)
+            payload.manager = params.manager;
+        if (params.nickname !== null)
+            payload.nickname = params.nickname;
+        if (params.initial_deposit !== null)
+            payload.initial_deposit = params.initial_deposit;
+        const body = await this.signedBody("create_lake", payload, account, signMessage);
         return this.post("/lake/create", body);
     }
     async depositToLake(params, account, signMessage) {
-        const body = await buildSignedRequest("deposit_to_lake", params, account, signMessage);
+        const body = await this.signedBody("deposit_to_lake", params, account, signMessage);
         return this.post("/lake/deposit", body);
     }
     async withdrawFromLake(params, account, signMessage) {
-        const body = await buildSignedRequest("withdraw_from_lake", params, account, signMessage);
+        const body = await this.signedBody("withdraw_from_lake", params, account, signMessage);
         return this.post("/lake/withdraw", body);
     }
     // ==================== BUILDER CODE ====================
     async approveBuilderCode(params, account, signMessage) {
-        const body = await buildSignedRequest("approve_builder_code", params, account, signMessage);
+        const body = await this.signedBody("approve_builder_code", params, account, signMessage);
         return this.post("/account/builder_codes/approve", body);
     }
     async revokeBuilderCode(params, account, signMessage) {
-        const body = await buildSignedRequest("revoke_builder_code", params, account, signMessage);
+        const body = await this.signedBody("revoke_builder_code", params, account, signMessage);
         return this.post("/account/builder_codes/revoke", body);
     }
     async getBuilderApprovals(account) {
         return this.get("/account/builder_codes/approvals", { account });
     }
     async updateBuilderFeeRate(params, account, signMessage) {
-        const body = await buildSignedRequest("update_builder_code_fee_rate", params, account, signMessage);
+        const body = await this.signedBody("update_builder_code_fee_rate", params, account, signMessage);
         return this.post("/builder/update_fee_rate", body);
     }
     async getBuilderOverview(account) {
@@ -300,7 +404,7 @@ export class PacificaClient {
     }
     // ==================== REFERRAL ====================
     async claimReferralCode(params, account, signMessage) {
-        const body = await buildSignedRequest("claim_referral_code", params, account, signMessage);
+        const body = await this.signedBody("claim_referral_code", params, account, signMessage);
         return this.post("/referral/user/code/claim", body);
     }
     // ==================== BATCH ====================

package/dist/pacifica/constants.d.ts

@@ -12,7 +12,6 @@ export declare const TESTNET_PACIFICA_VAULT = "5SDFdHZGTZbyRYu54CgmRkCGnPHC5pYaN
 export declare const TESTNET_USDC_MINT = "USDPqRbLidFGufty2s3oizmDEKdqx7ePTqzDMbf5ZKM";
 export declare const DEFAULT_EXPIRY_WINDOW = 5000;
 export declare const USDC_DECIMALS = 6;
-export declare const BUILDER_CODE = "PERPCLI";
 export type Network = "mainnet" | "testnet";
 export declare function getNetworkConfig(network?: Network): {
     restUrl: string;

package/dist/pacifica/constants.js

@@ -19,11 +19,6 @@ export const TESTNET_USDC_MINT = "USDPqRbLidFGufty2s3oizmDEKdqx7ePTqzDMbf5ZKM";
 export const DEFAULT_EXPIRY_WINDOW = 5000; // 5 seconds
 // USDC decimals
 export const USDC_DECIMALS = 6;
-// Builder code — 0% fee, used for Pacifica hackathon tracking
-// The actual 3-way fallback (env → settings.referralCodes.pacifica → "PERPCLI") is
-// resolved in index.ts before constructing PacificaAdapter. This constant is only
-// a last-resort default for direct PacificaClient usage without a builderCode arg.
-export const BUILDER_CODE = "PERPCLI";
 export function getNetworkConfig(network = "mainnet") {
     if (network === "testnet") {
         return {

package/dist/pacifica/deposit.d.ts

@@ -4,11 +4,38 @@ import { type Network } from "./constants.js";
  * Build a Pacifica deposit instruction.
  *
  * @param userPubkey - User's wallet public key
- * @param amount - Amount in USDC (e.g., 100 for $100)
+ * @param amount - Amount in USDC as a plain decimal string with at most 6 decimals (e.g. "100", "99.5");
+ *                 scaled exactly (no float math). Anything else → INVALID_PARAMS.
  * @param network - mainnet or testnet
  */
-export declare function buildDepositInstruction(userPubkey: PublicKey, amount: number, network?: Network): Promise<TransactionInstruction>;
+export declare function buildDepositInstruction(userPubkey: PublicKey, amount: string, network?: Network): Promise<TransactionInstruction>;
 /**
  * Build and send a deposit transaction.
  */
-export declare function deposit(connection: Connection, userPubkey: PublicKey, amount: number, signTransaction: (tx: Transaction) => Promise<Transaction>, network?: Network): Promise<TransactionSignature>;
+export declare function deposit(connection: Connection, userPubkey: PublicKey, amount: string, signTransaction: (tx: Transaction) => Promise<Transaction>, network?: Network): Promise<TransactionSignature>;
+/** Highest relayer fee (USDC) the CLI signs for a relayed deposit. Above it the transaction is refused. */
+export declare const PACIFICA_RELAY_FEE_CAP_USDC = 1;
+/**
+ * Verify a RELAYER-BUILT transaction before the master Solana key signs it. The relayer is an
+ * untrusted HTTP service (PERP_RELAYER_URL): whatever it returns is signed only when it is
+ * exactly
+ *  - ONE pinned Pacifica deposit instruction — the program id, every account (user, user USDC
+ *    ATA, central state, vault, mint, …, in order, same signer / writable flags) and the data
+ *    `buildDepositInstruction` would produce for `declared.netAmount`;
+ *  - any number of ComputeBudget instructions (they move no funds);
+ *  - at most ONE relayer fee transfer: an SPL Token Transfer / TransferChecked of exactly
+ *    `declared.fee` USDC from the user's USDC account, authority = user, to the token account the
+ *    build response declared (`feeRecipient`), with fee ≤ PACIFICA_RELAY_FEE_CAP_USDC;
+ * and fee + netAmount equals the amount the user asked to deposit, and the fee payer is not the
+ * user (the relayer sponsors gas). Anything else → POLICY_DENIED, nothing is signed.
+ */
+export declare function assertRelayedDepositTransaction(tx: Transaction, ctx: {
+    user: PublicKey;
+    requestedAmount: string;
+    network: Network;
+    declared: {
+        fee: number;
+        netAmount: number;
+        feeRecipient: string | null;
+    };
+}): Promise<void>;