@phantom/perps-client 0.1.1

package/src/actions.ts

@@ -0,0 +1,182 @@
+/**
+ * EIP-712 typed data builders for Hyperliquid exchange actions.
+ *
+ * Mirrors wallet2/wallet/packages/perps/src/sdk/orders/action.ts
+ */
+
+import { encode } from "@msgpack/msgpack";
+import { keccak256 } from "js-sha3";
+import type {
+  Eip712TypedData,
+  HlAction,
+  HlOrderAction,
+  HlCancelAction,
+  HlUpdateLeverageAction,
+  HlUsdClassTransferAction,
+} from "./types.js";
+import {
+  HYPERLIQUID_EXCHANGE_DOMAIN,
+  HYPERLIQUID_SIGN_TRANSACTION_DOMAIN,
+  EIP712_DOMAIN_TYPE,
+  APPROVE_EXCHANGE_TYPE,
+  USD_CLASS_TRANSFER_TYPE,
+  HYPERLIQUID_MAINNET_CHAIN_ID,
+  MARKET_ORDER_SLIPPAGE,
+} from "./constants.js";
+
+/**
+ * Computes the connectionId hash for exchange actions (orders, cancel, leverage).
+ * Mirrors OrderAction.hash(), CancelOrderAction.hash(), UpdateLeverageAction.hash()
+ */
+function hashAction(action: HlOrderAction | HlCancelAction | HlUpdateLeverageAction, nonce: number): string {
+  const msgPackBytes = encode(action);
+  // vaultAddress === null: 9 extra bytes (8 for nonce uint64 + 1 for null indicator)
+  const data = new Uint8Array(msgPackBytes.length + 9);
+  data.set(msgPackBytes);
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  view.setBigUint64(msgPackBytes.length, BigInt(nonce));
+  view.setUint8(msgPackBytes.length + 8, 0); // vaultAddress === null
+  return `0x${keccak256(data)}`;
+}
+
+/**
+ * Builds EIP-712 typed data for order/cancel/leverage exchange actions.
+ * These use the "Agent" signing pattern with a msgpack+keccak256 connectionId.
+ */
+export function buildExchangeActionTypedData(
+  action: HlOrderAction | HlCancelAction | HlUpdateLeverageAction,
+  nonce: number,
+  isTestnet = false,
+): Eip712TypedData {
+  const connectionId = hashAction(action, nonce);
+  return {
+    domain: HYPERLIQUID_EXCHANGE_DOMAIN,
+    primaryType: "Agent",
+    types: {
+      EIP712Domain: EIP712_DOMAIN_TYPE,
+      Agent: APPROVE_EXCHANGE_TYPE,
+    },
+    message: {
+      source: isTestnet ? "b" : "a",
+      connectionId,
+    },
+  };
+}
+
+/**
+ * Builds EIP-712 typed data for UsdClassTransfer (deposit spot→perp or withdraw perp→spot).
+ * chainId is derived from action.signatureChainId (hex string) with a fallback to mainnet.
+ */
+export function buildUsdClassTransferTypedData(action: HlUsdClassTransferAction): Eip712TypedData {
+  const chainId = action.signatureChainId ? parseInt(action.signatureChainId, 16) : HYPERLIQUID_MAINNET_CHAIN_ID;
+  return {
+    domain: {
+      ...HYPERLIQUID_SIGN_TRANSACTION_DOMAIN,
+      chainId,
+    },
+    primaryType: "HyperliquidTransaction:UsdClassTransfer",
+    types: {
+      EIP712Domain: EIP712_DOMAIN_TYPE,
+      "HyperliquidTransaction:UsdClassTransfer": USD_CLASS_TRANSFER_TYPE,
+    },
+    message: {
+      hyperliquidChain: action.hyperliquidChain,
+      amount: action.amount,
+      toPerp: action.toPerp,
+      nonce: action.nonce,
+    },
+  };
+}
+
+/** Monotonically increasing nonce (uses current timestamp, falls back to lastNonce+1) */
+let lastNonce = 0;
+export function nextNonce(): number {
+  const now = Date.now();
+  lastNonce = now > lastNonce ? now : lastNonce + 1;
+  return lastNonce;
+}
+
+/**
+ * Split a 65-byte signature into r, s, v components.
+ *
+ * PhantomClient.ethereumSignTypedData() returns a base64url-encoded signature
+ * (the KMS API comment says "Return the base64 encoded signature").
+ * We decode it to raw bytes then extract r (bytes 0-31), s (bytes 32-63), v (byte 64).
+ *
+ * Also handles legacy 0x-prefixed hex strings (0x + 130 hex chars) for compatibility.
+ */
+export function splitSignature(signature: string): { r: string; s: string; v: number } {
+  const raw = signature.startsWith("0x") ? signature.slice(2) : signature;
+
+  // Standard hex format: exactly 130 hex chars (65 bytes)
+  if (raw.length === 130 && /^[0-9a-fA-F]+$/.test(raw)) {
+    return {
+      r: `0x${raw.slice(0, 64)}`,
+      s: `0x${raw.slice(64, 128)}`,
+      v: parseInt(raw.slice(128, 130), 16),
+    };
+  }
+
+  // Base64url format (KMS response) — decode to bytes then extract components
+  const standardBase64 = raw.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = standardBase64 + "=".repeat((4 - (standardBase64.length % 4)) % 4);
+  const bytes = Buffer.from(padded, "base64");
+
+  if (bytes.length < 65) {
+    throw new Error(`Signature too short after base64 decode: expected 65 bytes, got ${bytes.length} (raw="${raw}")`);
+  }
+
+  return {
+    r: "0x" + bytes.slice(0, 32).toString("hex"),
+    s: "0x" + bytes.slice(32, 64).toString("hex"),
+    v: bytes[64],
+  };
+}
+
+/**
+ * Formats a price to the required decimal precision for Hyperliquid.
+ * Uses at most 5 significant figures.
+ */
+export function formatPrice(price: number, szDecimals: number): string {
+  // Hyperliquid tick size rule: price decimals = max(0, 6 - szDecimals - floor(log10(price)))
+  const decimals = Math.max(0, 6 - szDecimals - Math.floor(Math.log10(Math.abs(price) + 1e-9)));
+  return price.toFixed(decimals);
+}
+
+/**
+ * Formats a size to the required decimal precision for Hyperliquid.
+ */
+export function formatSize(size: number, szDecimals: number): string {
+  return size.toFixed(szDecimals);
+}
+
+/**
+ * Resolves the limit price string to submit to Hyperliquid.
+ *
+ * - "limit" orders: validates limitPrice is present and a finite positive number,
+ *   then formats it with the market's szDecimals.
+ * - "market" orders: applies MARKET_ORDER_SLIPPAGE to the current market price.
+ *
+ * Throws a descriptive error when a limit order is requested without a valid limitPrice.
+ */
+export function resolveLimitPrice(
+  orderType: "market" | "limit",
+  limitPrice: string | undefined,
+  marketPrice: number,
+  isBuy: boolean,
+  szDecimals: number,
+): string {
+  if (orderType === "limit") {
+    if (!limitPrice) {
+      throw new Error("limitPrice is required for limit orders");
+    }
+    const parsed = parseFloat(limitPrice);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      throw new Error(`limitPrice must be a finite positive number, got: ${limitPrice}`);
+    }
+    return formatPrice(parsed, szDecimals);
+  }
+  return formatPrice(marketPrice * (isBuy ? 1 + MARKET_ORDER_SLIPPAGE : 1 - MARKET_ORDER_SLIPPAGE), szDecimals);
+}
+
+export type { HlAction };

package/src/api.ts

@@ -0,0 +1,366 @@
+/**
+ * Thin HTTP wrapper for Phantom backend perps endpoints.
+ * Logs every request URL + params and every error response body.
+ */
+
+import axios, { AxiosError } from "axios";
+import type {
+  PerpAccountBalance,
+  PerpPosition,
+  PerpOrder,
+  PerpMarket,
+  HistoricalOrder,
+  FundingActivity,
+  SignatureComponents,
+  HlOrderAction,
+  HlCancelAction,
+  HlUpdateLeverageAction,
+  HlUsdClassTransferAction,
+  HlOrderResponse,
+  HlDefaultResponse,
+  HlCancelOrderResponse,
+  PerpsLogger,
+} from "./types.js";
+import { noopLogger } from "./types.js";
+
+const DEFAULT_PHANTOM_VERSION = "mcp-server";
+
+/** Keys whose values are redacted from debug logs. EVM addresses are public, only signatures are sensitive. */
+const SENSITIVE_LOG_KEYS = new Set(["pubkey", "signature", "sig"]);
+
+function sanitizeForLog(obj: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    result[k] = SENSITIVE_LOG_KEYS.has(k.toLowerCase()) ? "[redacted]" : v;
+  }
+  return result;
+}
+
+export interface PerpsApiOptions {
+  baseUrl: string;
+  appId?: string;
+  logger?: PerpsLogger;
+}
+
+export class PerpsApi {
+  private readonly baseUrl: string;
+  private readonly headers: Record<string, string>;
+  private readonly logger: PerpsLogger;
+
+  constructor(options: PerpsApiOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.logger = options.logger ?? noopLogger;
+
+    this.headers = {
+      "x-phantom-platform": "ext-sdk",
+      "x-phantom-client": "mcp",
+      "X-Phantom-Version": process.env.PHANTOM_VERSION ?? DEFAULT_PHANTOM_VERSION,
+    };
+    if (options.appId) {
+      this.headers["x-api-key"] = options.appId;
+      this.headers["X-App-Id"] = options.appId;
+    }
+  }
+
+  private async get<T>(path: string, params?: Record<string, string>): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const safeParams = params ? sanitizeForLog(params as Record<string, unknown>) : undefined;
+    const paramStr = safeParams ? `?${new URLSearchParams(safeParams as Record<string, string>).toString()}` : "";
+    this.logger.debug(`GET ${url}${paramStr}`);
+    try {
+      const r = await axios.get<T>(url, { params, headers: this.headers });
+      this.logger.debug(`GET ${path} → ${r.status}`);
+      return r.data;
+    } catch (err) {
+      throw this.wrapAxiosError(err, "GET", url);
+    }
+  }
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const safeBody = body && typeof body === "object" ? sanitizeForLog(body as Record<string, unknown>) : body;
+    this.logger.debug(`POST ${url} body=${JSON.stringify(safeBody)}`);
+    try {
+      const r = await axios.post<T>(url, body, { headers: this.headers });
+      this.logger.debug(`POST ${path} → ${r.status}`);
+      return r.data;
+    } catch (err) {
+      throw this.wrapAxiosError(err, "POST", url);
+    }
+  }
+
+  /**
+   * Wraps an AxiosError so the response body is visible in logs and error messages.
+   */
+  private wrapAxiosError(err: unknown, method: string, url: string): Error {
+    if (err instanceof AxiosError) {
+      const status = err.response?.status ?? "no-response";
+      const body = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+      const message = `Phantom API ${method} ${url} failed: HTTP ${status} — ${body}`;
+      this.logger.error(message);
+      return new Error(message);
+    }
+    return err instanceof Error ? err : new Error(String(err));
+  }
+
+  async getAccountBalance(user: string): Promise<PerpAccountBalance> {
+    this.logger.info(`getAccountBalance user=${user}`);
+    return this.get<PerpAccountBalance>("/swap/v2/perp/balance", { user });
+  }
+
+  async getFundingHistory(user: string): Promise<FundingActivity[]> {
+    this.logger.info(`getFundingHistory user=${user}`);
+    const data = await this.get<{ depositAndWithdrawals: RawFundingActivity[] }>(
+      "/swap/v2/perp/deposits-and-withdrawals",
+      { user },
+    );
+    return data.depositAndWithdrawals.map(mapFundingActivity);
+  }
+
+  async getPositionsAndOpenOrders(user: string): Promise<{ positions: PerpPosition[]; openOrders: PerpOrder[] }> {
+    this.logger.info(`getPositionsAndOpenOrders user=${user}`);
+    const data = await this.get<{ positions: RawPosition[]; openOrders: RawOpenOrder[] }>(
+      "/swap/v2/perp/positions-and-open-orders",
+      { user },
+    );
+    return {
+      positions: data.positions.map(mapPosition),
+      openOrders: data.openOrders.map(mapOpenOrder),
+    };
+  }
+
+  async getTradeHistory(user: string): Promise<HistoricalOrder[]> {
+    this.logger.info(`getTradeHistory user=${user}`);
+    const data = await this.get<{ tradeHistory: RawHistoricalOrder[] }>("/swap/v2/perp/trade-history", { user });
+    return data.tradeHistory.map(mapHistoricalOrder);
+  }
+
+  /**
+   * Fetch specific markets by CAIP-19 token address (e.g. "hypercore:mainnet/address:BTC").
+   * The backend requires at least one token — this is for targeted lookups.
+   */
+  async getMarkets(tokens: string[]): Promise<PerpMarket[]> {
+    this.logger.info(`getMarkets tokens=${tokens.join(",")}`);
+    const data = await this.get<{ markets: RawMarket[] | Record<string, RawMarket> }>("/swap/v2/perp/markets", {
+      tokens: tokens.join(","),
+    });
+    // The API returns either an array or a keyed record depending on version
+    const items = Array.isArray(data.markets) ? data.markets : Object.values(data.markets);
+    return items.map(mapMarket);
+  }
+
+  /**
+   * Fetch trending/popular markets (no per-market tokens needed).
+   * Requires chainId, sortBy, sortDirection per backend DTO.
+   */
+  async getTrendingMarkets(): Promise<PerpMarket[]> {
+    this.logger.info(`getTrendingMarkets`);
+    const data = await this.get<{ trendingMarkets: RawMarket[] }>("/swap/v2/perp/trending-markets", {
+      chainId: "hypercore:mainnet",
+      sortBy: "trending",
+      sortDirection: "desc",
+    });
+    return (data.trendingMarkets ?? []).map(mapMarket);
+  }
+
+  /**
+   * Fetch all available markets via the market-lists endpoint.
+   * Deduplicates across categories so each market symbol appears once.
+   */
+  async getAllMarkets(): Promise<PerpMarket[]> {
+    this.logger.info(`getAllMarkets`);
+    const data = await this.get<Record<string, { markets: RawMarket[] }>>("/swap/v2/perp/market-lists");
+    const seen = new Set<string>();
+    const markets: PerpMarket[] = [];
+    for (const category of Object.values(data)) {
+      for (const raw of category.markets ?? []) {
+        if (!seen.has(raw.symbol)) {
+          seen.add(raw.symbol);
+          markets.push(mapMarket(raw));
+        }
+      }
+    }
+    return markets;
+  }
+
+  /**
+   * POST /swap/v2/place-order — place a single order (open/close position).
+   * Requires `taker` (user CAIP-19 address) unlike the generic /exchange endpoint.
+   */
+  async postPlaceOrder(body: {
+    action: HlOrderAction;
+    nonce: number;
+    signature: SignatureComponents;
+    taker: string;
+  }): Promise<HlOrderResponse> {
+    this.logger.info(`postPlaceOrder nonce=${body.nonce} taker=${body.taker}`);
+    return this.post<HlOrderResponse>("/swap/v2/place-order", body);
+  }
+
+  /**
+   * POST /swap/v2/cancel-order — cancel an open order.
+   * Requires `taker` (user CAIP-19 address) so the backend can identify the user.
+   */
+  async postCancelOrder(body: {
+    action: HlCancelAction;
+    nonce: number;
+    signature: SignatureComponents;
+    taker: string;
+  }): Promise<HlCancelOrderResponse> {
+    this.logger.info(`postCancelOrder nonce=${body.nonce} taker=${body.taker}`);
+    return this.post<HlCancelOrderResponse>("/swap/v2/cancel-order", body);
+  }
+
+  /**
+   * POST /swap/v2/perp/update-leverage — update leverage for a market.
+   * Requires `taker` (user CAIP-19 address) so the backend can identify the user.
+   */
+  async postUpdateLeverage(body: {
+    action: HlUpdateLeverageAction;
+    nonce: number;
+    signature: SignatureComponents;
+    taker: string;
+  }): Promise<HlDefaultResponse> {
+    this.logger.info(
+      `postUpdateLeverage asset=${body.action.asset} leverage=${body.action.leverage} taker=${body.taker}`,
+    );
+    return this.post<HlDefaultResponse>("/swap/v2/perp/update-leverage", body);
+  }
+
+  async postTransferUsdcSpotPerp(body: {
+    action: HlUsdClassTransferAction;
+    nonce: number;
+    signature: SignatureComponents;
+  }): Promise<HlDefaultResponse> {
+    this.logger.info(`postTransferUsdcSpotPerp amount=${body.action.amount} toPerp=${body.action.toPerp}`);
+    return this.post<HlDefaultResponse>("/swap/v2/transfer-usdc-spot-perp", body);
+  }
+}
+
+// ── Raw response shapes from Phantom backend ────────────────────────────────
+
+interface RawPosition {
+  direction: "long" | "short";
+  leverage: string;
+  size: string;
+  margin: string;
+  entryPrice: string;
+  fundingPayments?: string;
+  market: { token: { address: string; chainId?: string }; logoUri?: string };
+  unrealizedPnl: { amount: string; percentage?: string } | null;
+  liquidationPrice: string;
+}
+
+interface RawOpenOrder {
+  id: string;
+  market: { token: { address: string } };
+  isTrigger?: boolean;
+  direction: "long" | "short";
+  type: "limit" | "take_profit_market" | "stop_market";
+  limitPrice: string;
+  triggerPrice?: string;
+  size: string;
+  reduceOnly: boolean;
+  /** Backend sends timestamp as a string. */
+  timestamp: string;
+}
+
+interface RawHistoricalOrder {
+  id: string;
+  market: { token: { address: string; chainId?: string }; logoUri?: string; szDecimals?: number };
+  type: string;
+  timestamp: number;
+  price: string;
+  size: string;
+  tradeValue: string;
+  fee: string;
+  closedPnl?: string;
+}
+
+interface RawMarket {
+  symbol: string;
+  /** Numeric Hyperliquid asset index — used to construct orders. */
+  assetId: number;
+  name?: string;
+  logoUri?: string;
+  maxLeverage: number;
+  szDecimals: number;
+  price: string;
+  fundingRate: string;
+  openInterest: string;
+  volume24h: string;
+}
+
+/** Raw shape of a single deposit-or-withdrawal item from the backend. */
+interface RawFundingActivity {
+  id: string;
+  type: string;
+  /** Amount in USDC. */
+  usdcAmount: string;
+  timestamp: number;
+}
+
+function mapPosition(raw: RawPosition): PerpPosition {
+  const leverage = parseFloat(raw.leverage);
+  return {
+    coin: raw.market.token.address,
+    direction: raw.direction,
+    size: raw.size,
+    margin: raw.margin,
+    entryPrice: raw.entryPrice,
+    leverage: { type: "unknown", value: leverage },
+    unrealizedPnl: raw.unrealizedPnl?.amount ?? "0",
+    liquidationPrice: raw.liquidationPrice || null,
+  };
+}
+
+function mapOpenOrder(raw: RawOpenOrder): PerpOrder {
+  return {
+    id: raw.id,
+    coin: raw.market.token.address,
+    side: raw.direction,
+    type: raw.type,
+    isTrigger: raw.isTrigger ?? false,
+    limitPrice: raw.limitPrice,
+    triggerPrice: raw.triggerPrice,
+    size: raw.size,
+    reduceOnly: raw.reduceOnly,
+    timestamp: parseInt(raw.timestamp, 10),
+  };
+}
+
+function mapHistoricalOrder(raw: RawHistoricalOrder): HistoricalOrder {
+  return {
+    id: raw.id,
+    coin: raw.market.token.address,
+    type: raw.type,
+    timestamp: raw.timestamp,
+    price: raw.price,
+    size: raw.size,
+    tradeValue: raw.tradeValue,
+    fee: raw.fee,
+    closedPnl: raw.closedPnl,
+  };
+}
+
+function mapMarket(raw: RawMarket): PerpMarket {
+  return {
+    symbol: raw.symbol,
+    assetId: raw.assetId,
+    maxLeverage: raw.maxLeverage,
+    szDecimals: raw.szDecimals,
+    price: raw.price,
+    fundingRate: raw.fundingRate,
+    openInterest: raw.openInterest,
+    volume24h: raw.volume24h,
+  };
+}
+
+function mapFundingActivity(raw: RawFundingActivity): FundingActivity {
+  return {
+    id: raw.id,
+    type: raw.type,
+    amount: raw.usdcAmount,
+    timestamp: raw.timestamp,
+  };
+}

package/src/constants.ts

@@ -0,0 +1,65 @@
+/**
+ * Constants for Hyperliquid EIP-712 signing and Phantom backend URLs.
+ */
+
+export const HYPERLIQUID_MAINNET_CHAIN_ID = 42161;
+export const HYPERLIQUID_TESTNET_CHAIN_ID = 421614;
+
+/** EIP-712 domain for UsdClassTransfer actions (deposit/withdraw) */
+export const HYPERLIQUID_SIGN_TRANSACTION_DOMAIN = {
+  name: "HyperliquidSignTransaction",
+  version: "1",
+  verifyingContract: "0x0000000000000000000000000000000000000000" as const,
+};
+
+/** EIP-712 domain for Exchange actions (orders, cancel, leverage) */
+export const HYPERLIQUID_EXCHANGE_DOMAIN = {
+  name: "Exchange",
+  version: "1",
+  chainId: 1337,
+  verifyingContract: "0x0000000000000000000000000000000000000000" as const,
+};
+
+export const EIP712_DOMAIN_TYPE = [
+  { name: "name", type: "string" },
+  { name: "version", type: "string" },
+  { name: "chainId", type: "uint256" },
+  { name: "verifyingContract", type: "address" },
+];
+
+export const APPROVE_EXCHANGE_TYPE = [
+  { name: "source", type: "string" },
+  { name: "connectionId", type: "bytes32" },
+];
+
+export const USD_CLASS_TRANSFER_TYPE = [
+  { name: "hyperliquidChain", type: "string" },
+  { name: "amount", type: "string" },
+  { name: "toPerp", type: "bool" },
+  { name: "nonce", type: "uint64" },
+];
+
+export const DEFAULT_API_BASE_URL = "https://api.phantom.app";
+
+/** Arbitrum network ID used for EIP-712 signing on Hyperliquid */
+export const ARBITRUM_NETWORK_ID = "eip155:42161";
+
+/** CAIP-19 prefix for Hypercore (Hyperliquid) mainnet */
+export const HYPERCORE_MAINNET_CHAIN_ID = "hypercore:mainnet";
+
+/** 10% slippage for market orders */
+export const MARKET_ORDER_SLIPPAGE = 0.1;
+
+/** 2% slippage for spot sell orders (mirrors wallet2's BUY_SELL_PRICE_MULTIPLIER = 0.98) */
+export const SPOT_SELL_SLIPPAGE = 0.02;
+
+/** USDC token ID on Hyperliquid spot — no sell step needed when this is the bridged token */
+export const USDC_SPOT_TOKEN_ID = "USDC";
+
+/** Well-known USDC contract addresses on EVM chains */
+export const USDC_ADDRESSES: Record<string, string> = {
+  "eip155:1": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+  "eip155:8453": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+  "eip155:42161": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
+  "eip155:137": "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
+};

package/src/index.ts

@@ -0,0 +1,16 @@
+export { PerpsClient } from "./PerpsClient.js";
+export type { PerpsClientOptions } from "./PerpsClient.js";
+export type {
+  PerpAccountBalance,
+  PerpPosition,
+  PerpOrder,
+  PerpMarket,
+  HistoricalOrder,
+  FundingActivity,
+  OpenPositionParams,
+  ClosePositionParams,
+  CancelOrderParams,
+  UpdateLeverageParams,
+  ActionResponse,
+} from "./types.js";
+export type { PerpsLogger } from "./types.js";