@phantom/perps-client 0.1.1

package/src/PerpsClient.ts

@@ -0,0 +1,336 @@
+/**
+ * PerpsClient — Hyperliquid perpetuals trading via Phantom backend.
+ *
+ * Intentionally decoupled from PhantomClient: takes a plain EVM address and
+ * a signTypedData callback so it can be used in any context (MCP server,
+ * tests with a mock signer, other wallet backends, etc.).
+ */
+
+import type {
+  PerpAccountBalance,
+  PerpPosition,
+  PerpOrder,
+  PerpMarket,
+  HistoricalOrder,
+  FundingActivity,
+  OpenPositionParams,
+  ClosePositionParams,
+  CancelOrderParams,
+  UpdateLeverageParams,
+  ActionResponse,
+  HlOrderAction,
+  HlCancelAction,
+  HlUpdateLeverageAction,
+  Eip712TypedData,
+  PerpsLogger,
+} from "./types.js";
+import { noopLogger } from "./types.js";
+import { PerpsApi } from "./api.js";
+import {
+  buildExchangeActionTypedData,
+  buildUsdClassTransferTypedData,
+  nextNonce,
+  splitSignature,
+  formatPrice,
+  formatSize,
+  resolveLimitPrice,
+} from "./actions.js";
+import { DEFAULT_API_BASE_URL, HYPERCORE_MAINNET_CHAIN_ID, MARKET_ORDER_SLIPPAGE } from "./constants.js";
+import { assertPositiveDecimalString } from "./validate.js";
+
+export interface PerpsClientOptions {
+  /** The wallet's EVM address (0x-prefixed, checksummed or lowercase) */
+  evmAddress: string;
+  /**
+   * Signs EIP-712 typed data and returns the raw hex signature (0x-prefixed, 65 bytes).
+   * In the MCP server this is bound to PhantomClient.ethereumSignTypedData().
+   */
+  signTypedData: (typedData: Eip712TypedData) => Promise<string>;
+  apiBaseUrl?: string;
+  appId?: string;
+  /** Optional logger — if provided, all API calls and errors are logged */
+  logger?: PerpsLogger;
+}
+
+export class PerpsClient {
+  private readonly evmAddress: string;
+  private readonly signTypedData: (typedData: Eip712TypedData) => Promise<string>;
+  private readonly api: PerpsApi;
+  private readonly logger: PerpsLogger;
+
+  constructor(opts: PerpsClientOptions) {
+    this.evmAddress = opts.evmAddress.toLowerCase();
+    this.signTypedData = opts.signTypedData;
+    this.logger = opts.logger ?? noopLogger;
+    this.logger.debug(`PerpsClient initialized evmAddress=${this.evmAddress} taker=${this.getUserCaip19()}`);
+    this.api = new PerpsApi({
+      baseUrl: opts.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+      appId: opts.appId,
+      logger: this.logger,
+    });
+  }
+
+  // ── Read (no signing) ────────────────────────────────────────────────────
+
+  async getBalance(): Promise<PerpAccountBalance> {
+    return this.api.getAccountBalance(this.getUserCaip19());
+  }
+
+  async getPositions(): Promise<PerpPosition[]> {
+    const { positions } = await this.api.getPositionsAndOpenOrders(this.getUserCaip19());
+    return positions;
+  }
+
+  async getOpenOrders(): Promise<PerpOrder[]> {
+    const { openOrders } = await this.api.getPositionsAndOpenOrders(this.getUserCaip19());
+    return openOrders;
+  }
+
+  /** Returns all available perp markets. Used by the get_perp_markets MCP tool. */
+  async getMarkets(): Promise<PerpMarket[]> {
+    return this.api.getAllMarkets();
+  }
+
+  async getTradeHistory(): Promise<HistoricalOrder[]> {
+    return this.api.getTradeHistory(this.getUserCaip19());
+  }
+
+  async getFundingHistory(): Promise<FundingActivity[]> {
+    return this.api.getFundingHistory(this.getUserCaip19());
+  }
+
+  // ── Write (EIP-712 sign → submit) ────────────────────────────────────────
+
+  async openPosition(params: OpenPositionParams): Promise<ActionResponse> {
+    this.logger.info(
+      `openPosition market=${params.market} direction=${params.direction} sizeUsd=${params.sizeUsd} leverage=${params.leverage} orderType=${params.orderType} taker=${this.evmAddress}`,
+    );
+    assertPositiveDecimalString(params.sizeUsd, "sizeUsd");
+    const market = await this.findMarket(params.market);
+    if (!market) {
+      throw new Error(`Market not found: ${params.market}`);
+    }
+
+    // Set leverage before placing the order (required by Hyperliquid).
+    // Defaults to isolated margin — cross margin shares account balance across positions.
+    const leverageAction: HlUpdateLeverageAction = {
+      type: "updateLeverage",
+      asset: market.assetId,
+      isCross: params.marginType === "cross",
+      leverage: params.leverage,
+    };
+    const leverageNonce = nextNonce();
+    const leverageTypedData = buildExchangeActionTypedData(leverageAction, leverageNonce);
+    const leverageSig = await this.sign(leverageTypedData);
+    await this.api.postUpdateLeverage({
+      action: leverageAction,
+      nonce: leverageNonce,
+      signature: leverageSig,
+      taker: this.getUserCaip19(),
+    });
+
+    const isBuy = params.direction === "long";
+    const price = parseFloat(market.price);
+    if (!Number.isFinite(price) || price <= 0) {
+      throw new Error(`Invalid market price for ${params.market}: ${market.price}`);
+    }
+    const rawSize = parseFloat(params.sizeUsd) / price;
+    if (!Number.isFinite(rawSize) || rawSize <= 0) {
+      throw new Error(`Computed order size is invalid (sizeUsd=${params.sizeUsd}, price=${market.price})`);
+    }
+
+    const limitPx = resolveLimitPrice(params.orderType, params.limitPrice, price, isBuy, market.szDecimals);
+
+    // Round down so the required margin never exceeds the available balance.
+    // Rounding up (ceil) can cause "insufficient margin" rejections from Hyperliquid.
+    const factor = Math.pow(10, market.szDecimals);
+    const sz = (Math.floor(rawSize * factor) / factor).toFixed(market.szDecimals);
+    if (parseFloat(sz) <= 0) {
+      throw new Error(`Order size rounds to zero (sizeUsd=${params.sizeUsd}, price=${market.price})`);
+    }
+
+    const action: HlOrderAction = {
+      type: "order",
+      orders: [
+        {
+          a: market.assetId,
+          b: isBuy,
+          p: limitPx,
+          s: sz,
+          r: params.reduceOnly ?? false,
+          t: params.orderType === "limit" ? { limit: { tif: "Gtc" } } : { limit: { tif: "Ioc" } },
+        },
+      ],
+      grouping: "na",
+    };
+
+    const nonce = nextNonce();
+    this.logger.debug(`openPosition placing order market=${params.market} sz=${sz} limitPx=${limitPx} nonce=${nonce}`);
+    const typedData = buildExchangeActionTypedData(action, nonce);
+    const sig = await this.sign(typedData);
+    const result = await this.api.postPlaceOrder({ action, nonce, signature: sig, taker: this.getUserCaip19() });
+    this.logger.info(`openPosition result status=${result.status}`);
+    return { status: result.status, data: result };
+  }
+
+  async closePosition(params: ClosePositionParams): Promise<ActionResponse> {
+    this.logger.info(
+      `closePosition market=${params.market} sizePercent=${params.sizePercent ?? 100} taker=${this.evmAddress}`,
+    );
+    const [market, positions] = await Promise.all([this.findMarket(params.market), this.getPositions()]);
+
+    if (!market) {
+      throw new Error(`Market not found: ${params.market}`);
+    }
+
+    const position = positions.find(p => p.coin.trim().toUpperCase() === market.symbol.trim().toUpperCase());
+    if (!position) {
+      throw new Error(`No open position for market: ${params.market}`);
+    }
+
+    const sizePercent = (params.sizePercent ?? 100) / 100;
+    const positionSize = Math.abs(parseFloat(position.size));
+    if (!Number.isFinite(positionSize) || positionSize <= 0) {
+      throw new Error(`Invalid position size for ${params.market}: ${position.size}`);
+    }
+    const sizeToClose = positionSize * sizePercent;
+    const sz = formatSize(sizeToClose, market.szDecimals);
+    if (parseFloat(sz) <= 0) {
+      throw new Error(`Close size rounds to zero (size=${position.size}, sizePercent=${params.sizePercent ?? 100})`);
+    }
+
+    const isBuy = position.direction === "short"; // close long = sell, close short = buy
+    const price = parseFloat(market.price);
+    const limitPx = formatPrice(
+      price * (isBuy ? 1 + MARKET_ORDER_SLIPPAGE : 1 - MARKET_ORDER_SLIPPAGE),
+      market.szDecimals,
+    );
+
+    const action: HlOrderAction = {
+      type: "order",
+      orders: [{ a: market.assetId, b: isBuy, p: limitPx, s: sz, r: true, t: { limit: { tif: "Ioc" } } }],
+      grouping: "na",
+    };
+
+    const nonce = nextNonce();
+    this.logger.debug(
+      `closePosition placing order market=${params.market} direction=${position.direction} sz=${sz} limitPx=${limitPx} nonce=${nonce}`,
+    );
+    const typedData = buildExchangeActionTypedData(action, nonce);
+    const sig = await this.sign(typedData);
+    const result = await this.api.postPlaceOrder({ action, nonce, signature: sig, taker: this.getUserCaip19() });
+    this.logger.info(`closePosition result status=${result.status}`);
+    return { status: result.status, data: result };
+  }
+
+  async cancelOrder(params: CancelOrderParams): Promise<ActionResponse> {
+    this.logger.info(`cancelOrder market=${params.market} orderId=${params.orderId} taker=${this.evmAddress}`);
+    const market = await this.findMarket(params.market);
+    if (!market) {
+      throw new Error(`Market not found: ${params.market}`);
+    }
+
+    const action: HlCancelAction = {
+      type: "cancel",
+      cancels: [{ a: market.assetId, o: params.orderId }],
+    };
+
+    const nonce = nextNonce();
+    const typedData = buildExchangeActionTypedData(action, nonce);
+    const sig = await this.sign(typedData);
+    const result = await this.api.postCancelOrder({ action, nonce, signature: sig, taker: this.getUserCaip19() });
+    this.logger.info(`cancelOrder result status=${result.status}`);
+    return { status: "ok", data: result };
+  }
+
+  async updateLeverage(params: UpdateLeverageParams): Promise<ActionResponse> {
+    this.logger.info(
+      `updateLeverage market=${params.market} leverage=${params.leverage} marginType=${params.marginType} taker=${this.evmAddress}`,
+    );
+    const market = await this.findMarket(params.market);
+    if (!market) {
+      throw new Error(`Market not found: ${params.market}`);
+    }
+
+    const action: HlUpdateLeverageAction = {
+      type: "updateLeverage",
+      asset: market.assetId,
+      isCross: params.marginType === "cross",
+      leverage: params.leverage,
+    };
+
+    const nonce = nextNonce();
+    const typedData = buildExchangeActionTypedData(action, nonce);
+    const sig = await this.sign(typedData);
+    const result = await this.api.postUpdateLeverage({ action, nonce, signature: sig, taker: this.getUserCaip19() });
+    return { status: "ok", data: result };
+  }
+
+  /**
+   * Moves USDC from the Hyperliquid spot account to the perps account.
+   * Both accounts are on Hypercore — this is NOT a cross-chain bridge.
+   */
+  async deposit(amountUsdc: string): Promise<ActionResponse> {
+    this.logger.info(`deposit amountUsdc=${amountUsdc} taker=${this.evmAddress}`);
+    assertPositiveDecimalString(amountUsdc, "amountUsdc");
+    const nonce = nextNonce();
+    const action = {
+      type: "usdClassTransfer" as const,
+      hyperliquidChain: "Mainnet" as const,
+      signatureChainId: "0xa4b1" as const,
+      amount: amountUsdc,
+      toPerp: true,
+      nonce,
+    };
+
+    const typedData = buildUsdClassTransferTypedData(action);
+    const sig = await this.sign(typedData);
+    const result = await this.api.postTransferUsdcSpotPerp({ action, nonce, signature: sig });
+    return { status: "ok", data: result };
+  }
+
+  /**
+   * Moves USDC from the perps account back to the Hyperliquid spot account.
+   */
+  async withdraw(amountUsdc: string): Promise<ActionResponse> {
+    this.logger.info(`withdraw amountUsdc=${amountUsdc} taker=${this.evmAddress}`);
+    assertPositiveDecimalString(amountUsdc, "amountUsdc");
+    const nonce = nextNonce();
+    const action = {
+      type: "usdClassTransfer" as const,
+      hyperliquidChain: "Mainnet" as const,
+      signatureChainId: "0xa4b1" as const,
+      amount: amountUsdc,
+      toPerp: false,
+      nonce,
+    };
+
+    const typedData = buildUsdClassTransferTypedData(action);
+    const sig = await this.sign(typedData);
+    const result = await this.api.postTransferUsdcSpotPerp({ action, nonce, signature: sig });
+    return { status: "ok", data: result };
+  }
+
+  // ── Internal helpers ──────────────────────────────────────────────────────
+
+  /**
+   * Fetches a single market by symbol (e.g. "BTC") using its CAIP-19 token address.
+   * More efficient than fetching all markets when only one is needed.
+   */
+  private async findMarket(symbol: string): Promise<PerpMarket> {
+    const caip19 = `${HYPERCORE_MAINNET_CHAIN_ID}/address:${symbol.toUpperCase()}`;
+    const markets = await this.api.getMarkets([caip19]);
+    const market = markets.find(m => m.symbol.toUpperCase() === symbol.toUpperCase());
+    if (!market) throw new Error(`Market not found: ${symbol}`);
+    return market;
+  }
+
+  private getUserCaip19(): string {
+    return `${HYPERCORE_MAINNET_CHAIN_ID}/address:${this.evmAddress}`;
+  }
+
+  private async sign(typedData: Eip712TypedData): Promise<ReturnType<typeof splitSignature>> {
+    const signature = await this.signTypedData(typedData);
+    return splitSignature(signature);
+  }
+}

package/src/actions.test.ts

@@ -0,0 +1,298 @@
+import {
+  splitSignature,
+  nextNonce,
+  formatPrice,
+  formatSize,
+  resolveLimitPrice,
+  buildExchangeActionTypedData,
+  buildUsdClassTransferTypedData,
+} from "./actions";
+import type { HlOrderAction, HlCancelAction, HlUpdateLeverageAction, HlUsdClassTransferAction } from "./types";
+
+// ── splitSignature ───────────────────────────────────────────────────────────
+
+describe("splitSignature", () => {
+  it("splits a 65-byte hex signature into r, s, v", () => {
+    const r = "a".repeat(64);
+    const s = "b".repeat(64);
+    const v = "1b"; // 27
+    const result = splitSignature(`0x${r}${s}${v}`);
+    expect(result.r).toBe(`0x${r}`);
+    expect(result.s).toBe(`0x${s}`);
+    expect(result.v).toBe(27);
+  });
+
+  it("handles v = 28 (0x1c) in hex format", () => {
+    const sig = `0x${"0".repeat(64)}${"0".repeat(64)}1c`;
+    expect(splitSignature(sig).v).toBe(28);
+  });
+
+  it("decodes a base64url-encoded 65-byte signature (KMS format)", () => {
+    // Build known 65 bytes: r = 0xaa*32, s = 0xbb*32, v = 0x1b (27)
+    const bytes = Buffer.alloc(65);
+    bytes.fill(0xaa, 0, 32);
+    bytes.fill(0xbb, 32, 64);
+    bytes[64] = 0x1b;
+    const base64url = bytes.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+    // Wrap with 0x prefix as PhantomClient returns it
+    const sig = `0x${base64url}`;
+
+    const result = splitSignature(sig);
+
+    expect(result.r).toBe("0x" + "aa".repeat(32));
+    expect(result.s).toBe("0x" + "bb".repeat(32));
+    expect(result.v).toBe(27);
+  });
+
+  it("throws when base64-decoded bytes are too short", () => {
+    const short = Buffer.alloc(10).toString("base64url");
+    expect(() => splitSignature(`0x${short}`)).toThrow("Signature too short");
+  });
+});
+
+// ── nextNonce ────────────────────────────────────────────────────────────────
+
+describe("nextNonce", () => {
+  it("returns a positive integer", () => {
+    const n = nextNonce();
+    expect(Number.isInteger(n)).toBe(true);
+    expect(n).toBeGreaterThan(0);
+  });
+
+  it("returns strictly increasing values on successive calls", () => {
+    const a = nextNonce();
+    const b = nextNonce();
+    const c = nextNonce();
+    expect(b).toBeGreaterThan(a);
+    expect(c).toBeGreaterThan(b);
+  });
+});
+
+// ── formatPrice ──────────────────────────────────────────────────────────────
+
+describe("formatPrice", () => {
+  // Hyperliquid rule: decimals = max(0, 6 - szDecimals - floor(log10(price)))
+
+  it("BTC ~$70k (szDecimals=5) → 0 decimal places", () => {
+    // 6 - 5 - floor(log10(70000)) = 6 - 5 - 4 = -3 → max(0,-3) = 0
+    expect(formatPrice(70000, 5)).toBe("70000");
+    expect(formatPrice(77493.9, 5)).toBe("77494");
+  });
+
+  it("SOL ~$100 (szDecimals=2) → 2 decimal places", () => {
+    // 6 - 2 - floor(log10(100)) = 6 - 2 - 2 = 2
+    expect(formatPrice(100.567, 2)).toBe("100.57");
+  });
+
+  it("small token ~$0.001 (szDecimals=0) → 8 decimal places", () => {
+    // 6 - 0 - floor(log10(0.001)) = 6 - 0 - (-3) = 9 → 9 decimals
+    const result = formatPrice(0.001234, 0);
+    expect(parseFloat(result)).toBeCloseTo(0.001234, 6);
+  });
+
+  it("returns a string", () => {
+    expect(typeof formatPrice(50000, 5)).toBe("string");
+  });
+
+  it("zero price — epsilon trick prevents -Infinity log; returns many decimal places", () => {
+    // log10(0 + 1e-9) = -9 → decimals = max(0, 6 - szDecimals + 9)
+    const result = formatPrice(0, 5);
+    expect(parseFloat(result)).toBe(0);
+    expect(Number.isFinite(parseFloat(result))).toBe(true);
+  });
+
+  it("very large price (1e8, szDecimals=5) → 0 decimal places", () => {
+    // 6 - 5 - floor(log10(1e8)) = 6 - 5 - 8 = -7 → max(0,-7) = 0
+    expect(formatPrice(1e8, 5)).toBe("100000000");
+  });
+
+  it("returns a finite string for very small positive price", () => {
+    const result = formatPrice(1e-10, 0);
+    expect(Number.isFinite(parseFloat(result))).toBe(true);
+  });
+});
+
+// ── formatSize ───────────────────────────────────────────────────────────────
+
+describe("formatSize", () => {
+  it("formats to the given number of decimal places", () => {
+    expect(formatSize(1.23456, 3)).toBe("1.235");
+    expect(formatSize(0.1, 1)).toBe("0.1");
+    expect(formatSize(10, 0)).toBe("10");
+  });
+
+  it("zero size returns all-zero string", () => {
+    expect(formatSize(0, 5)).toBe("0.00000");
+    expect(formatSize(0, 0)).toBe("0");
+  });
+
+  it("rounds fractional size to the specified decimal places", () => {
+    // 0.123456789 rounded to 5 places → "0.12346"
+    expect(formatSize(0.123456789, 5)).toBe("0.12346");
+  });
+
+  it("very small size that rounds to zero at given precision", () => {
+    // 0.000001 with 5 decimals → "0.00000"
+    expect(formatSize(0.000001, 5)).toBe("0.00000");
+  });
+});
+
+// ── resolveLimitPrice ────────────────────────────────────────────────────────
+
+describe("resolveLimitPrice", () => {
+  const SZ_DECIMALS = 5;
+  const MARKET_PRICE = 50000;
+
+  describe("market orders", () => {
+    it("buy: applies +10% slippage to market price", () => {
+      const result = resolveLimitPrice("market", undefined, MARKET_PRICE, true, SZ_DECIMALS);
+      expect(result).toBe(formatPrice(MARKET_PRICE * 1.1, SZ_DECIMALS));
+    });
+
+    it("sell: applies -10% slippage to market price", () => {
+      const result = resolveLimitPrice("market", undefined, MARKET_PRICE, false, SZ_DECIMALS);
+      expect(result).toBe(formatPrice(MARKET_PRICE * 0.9, SZ_DECIMALS));
+    });
+
+    it("ignores any limitPrice passed for a market order", () => {
+      const result = resolveLimitPrice("market", "99999", MARKET_PRICE, true, SZ_DECIMALS);
+      expect(result).toBe(formatPrice(MARKET_PRICE * 1.1, SZ_DECIMALS));
+    });
+  });
+
+  describe("limit orders", () => {
+    it("returns formatPrice of the parsed limitPrice", () => {
+      const result = resolveLimitPrice("limit", "48000", MARKET_PRICE, true, SZ_DECIMALS);
+      expect(result).toBe(formatPrice(48000, SZ_DECIMALS));
+    });
+
+    it("throws when limitPrice is absent", () => {
+      expect(() => resolveLimitPrice("limit", undefined, MARKET_PRICE, true, SZ_DECIMALS)).toThrow(
+        "limitPrice is required for limit orders",
+      );
+    });
+
+    it("throws when limitPrice is an empty string", () => {
+      expect(() => resolveLimitPrice("limit", "", MARKET_PRICE, true, SZ_DECIMALS)).toThrow(
+        "limitPrice is required for limit orders",
+      );
+    });
+
+    it.each([["0"], ["-1000"], ["abc"], ["NaN"], ["Infinity"]])(
+      "throws for non-positive or non-finite limitPrice=%j",
+      bad => {
+        expect(() => resolveLimitPrice("limit", bad, MARKET_PRICE, true, SZ_DECIMALS)).toThrow(
+          "limitPrice must be a finite positive number",
+        );
+      },
+    );
+  });
+});
+
+// ── buildExchangeActionTypedData ─────────────────────────────────────────────
+
+describe("buildExchangeActionTypedData", () => {
+  const orderAction: HlOrderAction = {
+    type: "order",
+    orders: [{ a: 0, b: true, p: "50000", s: "0.001", r: false, t: { limit: { tif: "Ioc" } } }],
+    grouping: "na",
+  };
+
+  it("uses the Exchange domain (chainId 1337)", () => {
+    const td = buildExchangeActionTypedData(orderAction, 1000);
+    expect(td.domain.name).toBe("Exchange");
+    expect(td.domain.chainId).toBe(1337);
+    expect(td.domain.verifyingContract).toBe("0x0000000000000000000000000000000000000000");
+  });
+
+  it("uses Agent as primaryType", () => {
+    const td = buildExchangeActionTypedData(orderAction, 1000);
+    expect(td.primaryType).toBe("Agent");
+  });
+
+  it("message.source is 'a' for mainnet", () => {
+    const td = buildExchangeActionTypedData(orderAction, 1000, false);
+    expect(td.message.source).toBe("a");
+  });
+
+  it("message.source is 'b' for testnet", () => {
+    const td = buildExchangeActionTypedData(orderAction, 1000, true);
+    expect(td.message.source).toBe("b");
+  });
+
+  it("message.connectionId is a 0x-prefixed hex string", () => {
+    const td = buildExchangeActionTypedData(orderAction, 1000);
+    expect(typeof td.message.connectionId).toBe("string");
+    expect(td.message.connectionId as string).toMatch(/^0x[0-9a-f]{64}$/);
+  });
+
+  it("produces a different connectionId for a different nonce", () => {
+    const td1 = buildExchangeActionTypedData(orderAction, 1000);
+    const td2 = buildExchangeActionTypedData(orderAction, 2000);
+    expect(td1.message.connectionId).not.toBe(td2.message.connectionId);
+  });
+
+  it("works for CancelAction", () => {
+    const cancel: HlCancelAction = { type: "cancel", cancels: [{ a: 1, o: 42 }] };
+    const td = buildExchangeActionTypedData(cancel, 1000);
+    expect(td.primaryType).toBe("Agent");
+  });
+
+  it("works for UpdateLeverageAction", () => {
+    const leverage: HlUpdateLeverageAction = { type: "updateLeverage", asset: 0, isCross: true, leverage: 10 };
+    const td = buildExchangeActionTypedData(leverage, 1000);
+    expect(td.primaryType).toBe("Agent");
+  });
+});
+
+// ── buildUsdClassTransferTypedData ───────────────────────────────────────────
+
+describe("buildUsdClassTransferTypedData", () => {
+  const action: HlUsdClassTransferAction = {
+    type: "usdClassTransfer",
+    hyperliquidChain: "Mainnet",
+    signatureChainId: "0xa4b1",
+    amount: "100",
+    toPerp: true,
+    nonce: 12345,
+  };
+
+  it("uses HyperliquidSignTransaction domain and derives chainId from signatureChainId", () => {
+    const td = buildUsdClassTransferTypedData(action);
+    expect(td.domain.name).toBe("HyperliquidSignTransaction");
+    expect(td.domain.chainId).toBe(42161); // 0xa4b1 = 42161
+  });
+
+  it("uses chainId 421614 when signatureChainId is testnet (0x66eee)", () => {
+    const testnetAction = { ...action, signatureChainId: "0x66eee" as const };
+    const td = buildUsdClassTransferTypedData(testnetAction);
+    expect(td.domain.chainId).toBe(421614);
+  });
+
+  it("primaryType is HyperliquidTransaction:UsdClassTransfer", () => {
+    const td = buildUsdClassTransferTypedData(action);
+    expect(td.primaryType).toBe("HyperliquidTransaction:UsdClassTransfer");
+  });
+
+  it("types include the UsdClassTransfer fields", () => {
+    const td = buildUsdClassTransferTypedData(action);
+    const fields = td.types["HyperliquidTransaction:UsdClassTransfer"];
+    const names = fields.map((f: { name: string }) => f.name);
+    expect(names).toContain("hyperliquidChain");
+    expect(names).toContain("amount");
+    expect(names).toContain("toPerp");
+    expect(names).toContain("nonce");
+  });
+
+  it("message contains only the USD_CLASS_TRANSFER_TYPE fields", () => {
+    const td = buildUsdClassTransferTypedData(action);
+    expect(td.message).toEqual({
+      hyperliquidChain: "Mainnet",
+      amount: "100",
+      toPerp: true,
+      nonce: 12345,
+    });
+    expect(td.message).not.toHaveProperty("type");
+    expect(td.message).not.toHaveProperty("signatureChainId");
+  });
+});