@phantom/perps-client 0.1.1

package/src/types.ts

@@ -0,0 +1,227 @@
+/**
+ * Types for Hyperliquid perpetuals trading via Phantom backend.
+ */
+
+/**
+ * Minimal logger interface — satisfied by the MCP server Logger class
+ * or any standard logger (console, pino, etc.).
+ */
+export interface PerpsLogger {
+  info(message: string): void;
+  error(message: string): void;
+  debug(message: string): void;
+}
+
+/** No-op logger used when no logger is provided */
+export const noopLogger: PerpsLogger = {
+  info: () => {},
+  error: () => {},
+  debug: () => {},
+};
+
+export interface PerpAccountBalance {
+  accountValue: string;
+  availableBalance: string;
+  availableToTrade: string;
+}
+
+export interface PerpPosition {
+  coin: string;
+  direction: "long" | "short";
+  size: string;
+  margin: string;
+  entryPrice: string;
+  leverage: { type: "isolated" | "cross" | "unknown"; value: number };
+  unrealizedPnl: string;
+  liquidationPrice: string | null;
+}
+
+export interface PerpOrder {
+  id: string;
+  coin: string;
+  side: "long" | "short";
+  type: "limit" | "take_profit_market" | "stop_market";
+  isTrigger: boolean;
+  limitPrice: string;
+  triggerPrice?: string;
+  size: string;
+  reduceOnly: boolean;
+  timestamp: number;
+}
+
+export interface PerpMarket {
+  symbol: string;
+  assetId: number;
+  maxLeverage: number;
+  szDecimals: number;
+  price: string;
+  fundingRate: string;
+  openInterest: string;
+  volume24h: string;
+}
+
+export interface HistoricalOrder {
+  id: string;
+  coin: string;
+  type: string;
+  timestamp: number;
+  price: string;
+  size: string;
+  tradeValue: string;
+  fee: string;
+  closedPnl?: string;
+}
+
+export interface FundingActivity {
+  /** CAIP-19 encoded transaction ID */
+  id?: string;
+  type: string;
+  /** USDC amount for this deposit or withdrawal */
+  amount: string;
+  timestamp: number;
+}
+
+export interface OpenPositionParams {
+  /** Coin symbol e.g. "BTC", "ETH" */
+  market: string;
+  direction: "long" | "short";
+  /** Size in USD */
+  sizeUsd: string;
+  leverage: number;
+  /** Margin type — defaults to "isolated" (safer). Use "cross" to share account balance across positions. */
+  marginType?: "isolated" | "cross";
+  orderType: "market" | "limit";
+  limitPrice?: string;
+  reduceOnly?: boolean;
+}
+
+export interface ClosePositionParams {
+  market: string;
+  /** 0-100, defaults to 100 (full close) */
+  sizePercent?: number;
+}
+
+export interface CancelOrderParams {
+  market: string;
+  orderId: number;
+}
+
+export interface UpdateLeverageParams {
+  market: string;
+  leverage: number;
+  marginType: "cross" | "isolated";
+}
+
+export interface ActionResponse {
+  status: string;
+  data?: unknown;
+}
+
+/** Response from cancel-order, update-leverage, and transfer-usdc-spot-perp endpoints. */
+export interface HlDefaultResponse {
+  status: string;
+  response: { type: string };
+}
+
+/** Response from cancel-order endpoint. */
+export interface HlCancelOrderResponse {
+  status: string;
+  response: {
+    type: string;
+    data: { statuses: Array<string | { error: string }> };
+  };
+}
+
+// Internal types for EIP-712 and action submission
+
+export interface Eip712TypedData {
+  domain: {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: string;
+  };
+  primaryType: string;
+  types: Record<string, { name: string; type: string }[]>;
+  message: Record<string, unknown>;
+}
+
+export interface SignatureComponents {
+  r: string;
+  s: string;
+  v: number;
+}
+
+// Low-level Hyperliquid order structs (mirrors wallet2's order.ts)
+
+type TimeInForce = "Alo" | "Ioc" | "Gtc";
+
+interface LimitOrderType {
+  limit: {
+    tif: TimeInForce;
+  };
+}
+
+interface TriggerOrderType {
+  trigger: {
+    isMarket: boolean;
+    triggerPx: string;
+    tpsl: "tp" | "sl";
+  };
+}
+
+export interface HlOrder {
+  a: number; // asset id
+  b: boolean; // isBuy
+  p: string; // price
+  s: string; // size
+  r: boolean; // reduceOnly
+  t: LimitOrderType | TriggerOrderType;
+}
+
+export interface HlOrderAction {
+  type: "order";
+  orders: HlOrder[];
+  grouping: "na";
+}
+
+export interface HlCancelAction {
+  type: "cancel";
+  cancels: { a: number; o: number }[];
+}
+
+export interface HlUpdateLeverageAction {
+  type: "updateLeverage";
+  asset: number;
+  isCross: boolean;
+  leverage: number;
+}
+
+export interface HlUsdClassTransferAction {
+  type: "usdClassTransfer";
+  hyperliquidChain: "Mainnet" | "Testnet";
+  signatureChainId: "0xa4b1" | "0x66eee";
+  amount: string;
+  toPerp: boolean;
+  nonce: number;
+}
+
+export type HlAction = HlOrderAction | HlCancelAction | HlUpdateLeverageAction | HlUsdClassTransferAction;
+
+/** Response from POST /swap/v2/place-order (matches backend OrderResponse DTO) */
+export interface HlOrderResponseStatus {
+  resting?: { oid: number };
+  filled?: { totalSz: string; avgPx: string; oid: number };
+  error?: string;
+}
+
+export interface HlOrderResponse {
+  status: string;
+  response: {
+    type: string;
+    data: {
+      statuses: HlOrderResponseStatus[];
+    };
+  };
+  filled?: { totalSz: string; avgPx: string; oid: number };
+}

package/src/validate.ts

@@ -0,0 +1,18 @@
+/**
+ * Validation helpers for PerpsClient string parameters.
+ *
+ * Numeric types (number, boolean, enum unions) are sufficiently constrained by
+ * TypeScript and validated by callers (e.g. the MCP layer). String parameters,
+ * however, carry no format guarantee — any string value satisfies `string` — so
+ * the client must enforce canonical format before embedding them in signed payloads.
+ */
+
+/**
+ * Throws if value is not a canonical positive decimal string (e.g. "100" or "10.5").
+ * Rejects leading/trailing whitespace, scientific notation, negative values, and zero.
+ */
+export function assertPositiveDecimalString(value: unknown, name: string): asserts value is string {
+  if (typeof value !== "string" || value !== value.trim() || !/^\d+(\.\d+)?$/.test(value) || parseFloat(value) <= 0) {
+    throw new Error(`${name} must be a positive number string (e.g. "100" or "10.5")`);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}