perp-cli 0.12.17 → 0.14.1

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/onchain-balances.d.ts

@@ -0,0 +1,40 @@
+export interface OnchainBalance {
+    /** Chain id in perp-cli terms (arbitrum, ethereum, base, bsc, robinhood, solana, …). */
+    chain: string;
+    token: string;
+    kind: "stable" | "native";
+    /** Decimal string; null = the read failed (see `error`). */
+    balance: string | null;
+    /** Stablecoins at $1; native tokens at the Hyperliquid mid; null when unknown. */
+    usdValue: number | null;
+    /** Why the balance read failed (balance null). */
+    error: string | null;
+    /** Why a native token's usdValue is null although its balance was read. */
+    priceError: string | null;
+}
+interface TokenPin {
+    symbol: string;
+    address: string;
+    decimals: number;
+}
+interface EvmChainPin {
+    label: string;
+    chainId: number;
+    rpcUrl: string;
+    native: string;
+    tokens: TokenPin[];
+}
+/** Mainnet EVM chains, in display order. */
+export declare function mainnetEvmChains(): Record<string, EvmChainPin>;
+/** Per-request timeout of every read here: a stuck public RPC becomes a per-row error, not a hang. */
+export declare const ONCHAIN_READ_TIMEOUT_MS = 10000;
+/** Gas token + stablecoins on every EVM chain (mainnet), or Arbitrum Sepolia (testnet). `only` limits the chains. */
+export declare function evmOnchainBalances(address: string, testnet: boolean, only?: readonly string[]): Promise<OnchainBalance[]>;
+/** SOL + USDC / USDT (mainnet) or USDP (devnet) of a Solana address. */
+export declare function solanaOnchainBalances(address: string, testnet: boolean): Promise<OnchainBalance[]>;
+/** Sum of the stablecoin balances that were read (failed reads are excluded and listed in `errors`). */
+export declare function stableTotal(rows: readonly OnchainBalance[]): {
+    usd: number;
+    errors: string[];
+};
+export {};

package/dist/onchain-balances.js

@@ -0,0 +1,173 @@
+/**
+ * On-chain wallet balances (`perp wallet balance`): the gas token plus the USD stablecoins
+ * (USDC / USDT; USDG on Robinhood Chain) on every chain perp-cli moves funds on.
+ *
+ * Token pins come from the registries the fund-movement code already uses (RELAY_CHAINS,
+ * ONDO_DEPOSIT_CHAINS); the two not in them are Tether's Ethereum USDT and Solana USDT
+ * (tether.to/en/supported-protocols). A read that fails is reported per token
+ * (balance null + error) — never shown as 0.
+ */
+import { HYPERLIQUID_API_URL } from "./api/public/urls.js";
+import { ONDO_DEPOSIT_CHAINS } from "./exchanges/venues/ondo.js";
+import { RELAY_CHAINS } from "./relay-swap.js";
+const relayToken = (chain, symbol) => {
+    const a = RELAY_CHAINS[chain]?.assets[symbol];
+    if (a === undefined)
+        throw new Error(`RELAY_CHAINS has no ${symbol} on ${chain}`);
+    return { symbol, address: a.address, decimals: a.decimals };
+};
+const relayRpc = (chain) => {
+    const url = RELAY_CHAINS[chain]?.rpcUrl;
+    if (url === null || url === undefined)
+        throw new Error(`RELAY_CHAINS has no RPC for ${chain}`);
+    return url;
+};
+/** Mainnet EVM chains, in display order. */
+export function mainnetEvmChains() {
+    return {
+        arbitrum: {
+            label: "Arbitrum", chainId: 42161, rpcUrl: relayRpc("arbitrum"), native: "ETH",
+            tokens: [relayToken("arbitrum", "USDC"), relayToken("arbitrum", "USDT")],
+        },
+        ethereum: {
+            label: "Ethereum", chainId: 1, rpcUrl: ONDO_DEPOSIT_CHAINS.ethereum.rpcUrl, native: "ETH",
+            tokens: [
+                { symbol: "USDC", address: ONDO_DEPOSIT_CHAINS.ethereum.usdc, decimals: 6 },
+                { symbol: "USDT", address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", decimals: 6 },
+            ],
+        },
+        base: {
+            label: "Base", chainId: 8453, rpcUrl: relayRpc("base"), native: "ETH",
+            tokens: [relayToken("base", "USDC")],
+        },
+        bsc: {
+            label: "BNB Chain", chainId: 56, rpcUrl: relayRpc("bsc"), native: "BNB",
+            tokens: [relayToken("bsc", "USDT"), relayToken("bsc", "USDC")],
+        },
+        robinhood: {
+            label: "Robinhood Chain", chainId: 4663, rpcUrl: relayRpc("robinhood"), native: "ETH",
+            tokens: [relayToken("robinhood", "USDG")],
+        },
+    };
+}
+const TESTNET_EVM_CHAINS = {
+    "arbitrum-sepolia": {
+        label: "Arbitrum Sepolia", chainId: 421614, rpcUrl: "https://sepolia-rollup.arbitrum.io/rpc", native: "ETH",
+        tokens: [{ symbol: "USDC", address: "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d", decimals: 6 }],
+    },
+};
+/** Built on use (not at import) so a registry change can only break `wallet balance`, never startup. */
+function solanaPins(testnet) {
+    return testnet
+        ? { rpcUrl: "https://api.devnet.solana.com", tokens: [{ symbol: "USDP", address: "USDPqRbLidFGufty2s3oizmDEKdqx7ePTqzDMbf5ZKM", decimals: 6 }] }
+        : {
+            rpcUrl: "https://api.mainnet-beta.solana.com",
+            tokens: [
+                { symbol: "USDC", address: relayToken("solana", "USDC").address, decimals: 6 },
+                { symbol: "USDT", address: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB", decimals: 6 },
+            ],
+        };
+}
+/** Per-request timeout of every read here: a stuck public RPC becomes a per-row error, not a hang. */
+export const ONCHAIN_READ_TIMEOUT_MS = 10_000;
+const timedFetch = (input, init) => fetch(input, { ...init, signal: AbortSignal.timeout(ONCHAIN_READ_TIMEOUT_MS) });
+const errText = (e) => (e instanceof Error ? e.message : String(e)).slice(0, 160);
+/**
+ * USD mids of the native gas tokens from Hyperliquid allMids. A failed / missing price leaves the
+ * native row's usdValue null and names the reason in `priceError`; balances are unaffected.
+ */
+async function nativePrices() {
+    const px = new Map();
+    try {
+        const res = await timedFetch(HYPERLIQUID_API_URL, {
+            method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "allMids" }),
+        });
+        if (!res.ok)
+            return { px, error: `Hyperliquid allMids HTTP ${res.status}` };
+        const mids = await res.json();
+        for (const sym of ["ETH", "BNB", "SOL"]) {
+            const v = Number(mids[sym]);
+            if (typeof mids[sym] === "string" && Number.isFinite(v) && v > 0)
+                px.set(sym, v);
+        }
+        return { px, error: null };
+    }
+    catch (e) {
+        return { px, error: `Hyperliquid allMids: ${errText(e)}` };
+    }
+}
+function row(chain, token, kind, balance, prices, error) {
+    let usdValue = null;
+    let priceError = null;
+    if (balance !== null) {
+        if (kind === "stable")
+            usdValue = Number(balance);
+        else if (prices.px.has(token))
+            usdValue = Number(balance) * prices.px.get(token);
+        else
+            priceError = prices.error ?? `no Hyperliquid mid for ${token}`;
+    }
+    return { chain, token, kind, balance, usdValue, error, priceError };
+}
+async function evmChainBalances(ethers, chain, pin, address, prices) {
+    const req = new ethers.FetchRequest(pin.rpcUrl);
+    req.timeout = ONCHAIN_READ_TIMEOUT_MS;
+    // batchMaxCount 1: one plain JSON-RPC call per read (not every public RPC accepts batches).
+    const provider = new ethers.JsonRpcProvider(req, pin.chainId, { staticNetwork: true, batchMaxCount: 1 });
+    const native = provider.getBalance(address)
+        .then(b => row(chain, pin.native, "native", ethers.formatEther(b), prices, null))
+        .catch(e => row(chain, pin.native, "native", null, prices, errText(e)));
+    const tokens = pin.tokens.map(t => {
+        const c = new ethers.Contract(t.address, ["function balanceOf(address) view returns (uint256)"], provider);
+        return c.balanceOf(address)
+            .then(b => row(chain, t.symbol, "stable", ethers.formatUnits(b, t.decimals), prices, null))
+            .catch(e => row(chain, t.symbol, "stable", null, prices, errText(e)));
+    });
+    return Promise.all([native, ...tokens]);
+}
+/** Gas token + stablecoins on every EVM chain (mainnet), or Arbitrum Sepolia (testnet). `only` limits the chains. */
+export async function evmOnchainBalances(address, testnet, only) {
+    const chains = testnet ? TESTNET_EVM_CHAINS : mainnetEvmChains();
+    const selected = Object.entries(chains).filter(([id]) => only === undefined || only.includes(id));
+    const [{ ethers }, prices] = await Promise.all([import("ethers"), nativePrices()]);
+    return (await Promise.all(selected.map(([id, pin]) => evmChainBalances(ethers, id, pin, address, prices)))).flat();
+}
+/** SOL + USDC / USDT (mainnet) or USDP (devnet) of a Solana address. */
+export async function solanaOnchainBalances(address, testnet) {
+    const { Connection, PublicKey } = await import("@solana/web3.js");
+    const cfg = solanaPins(testnet);
+    const chain = testnet ? "solana-devnet" : "solana";
+    const connection = new Connection(cfg.rpcUrl, { fetch: timedFetch });
+    const owner = new PublicKey(address);
+    const prices = await nativePrices();
+    const sol = connection.getBalance(owner)
+        .then(l => row(chain, "SOL", "native", (l / 1e9).toFixed(9).replace(/\.?0+$/, ""), prices, null))
+        .catch(e => row(chain, "SOL", "native", null, prices, errText(e)));
+    const tokens = cfg.tokens.map(t => connection.getParsedTokenAccountsByOwner(owner, { mint: new PublicKey(t.address) })
+        .then(res => {
+        let raw = 0n;
+        for (const { account } of res.value) {
+            const amount = account.data.parsed?.info?.tokenAmount?.amount;
+            if (typeof amount !== "string")
+                throw new Error(`token account without a raw amount for ${t.symbol}`);
+            raw += BigInt(amount);
+        }
+        const s = raw.toString().padStart(t.decimals + 1, "0");
+        const dec = `${s.slice(0, -t.decimals)}.${s.slice(-t.decimals)}`.replace(/\.?0+$/, "");
+        return row(chain, t.symbol, "stable", dec, prices, null);
+    })
+        .catch(e => row(chain, t.symbol, "stable", null, prices, errText(e))));
+    return Promise.all([sol, ...tokens]);
+}
+/** Sum of the stablecoin balances that were read (failed reads are excluded and listed in `errors`). */
+export function stableTotal(rows) {
+    let usd = 0;
+    const errors = [];
+    for (const r of rows) {
+        if (r.error !== null)
+            errors.push(`${r.chain} ${r.token}: ${r.error}`);
+        else if (r.kind === "stable")
+            usd += Number(r.balance);
+    }
+    return { usd, errors };
+}

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>;