@phantom/perps-client 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @phantom/perps-client
+
+## 0.1.1
+
+### Patch Changes
+
+- 92e3472: Perps Support

package/README.md

@@ -0,0 +1,147 @@
+# @phantom/perps-client
+
+Hyperliquid perpetuals trading client for Phantom Wallet. Handles EIP-712 signing and Phantom backend API calls for the full perpetuals lifecycle — from funding deposits through position management.
+
+## Architecture
+
+```
+PerpsClient
+    ├── Read operations  →  Phantom backend API  →  Hyperliquid data
+    └── Write operations →  EIP-712 sign  →  Phantom backend  →  Hyperliquid exchange
+```
+
+The client is intentionally decoupled from `PhantomClient`. It receives a plain EVM address and a `signTypedData` callback, making it testable with any signer and reusable outside the MCP server.
+
+## Installation
+
+```bash
+yarn add @phantom/perps-client
+```
+
+## Usage
+
+```typescript
+import { PerpsClient } from "@phantom/perps-client";
+
+const client = new PerpsClient({
+  evmAddress: "0xYourEvmAddress",
+  signTypedData: async typedData => {
+    // Sign EIP-712 typed data and return 0x-prefixed hex signature
+    return phantomClient.ethereumSignTypedData({
+      walletId,
+      typedData,
+      networkId: "eip155:42161", // Arbitrum — used for all Hyperliquid signing
+      derivationIndex: 0,
+    });
+  },
+  apiBaseUrl: "https://api.phantom.app", // optional
+});
+
+// Read
+const balance = await client.getBalance();
+const positions = await client.getPositions();
+const orders = await client.getOpenOrders();
+const markets = await client.getMarkets();
+
+// Write
+await client.openPosition({ market: "BTC", direction: "long", sizeUsd: "100", leverage: 10, orderType: "market" });
+await client.closePosition({ market: "BTC" });
+await client.cancelOrder({ market: "BTC", orderId: 12345 });
+await client.updateLeverage({ market: "BTC", leverage: 5, marginType: "cross" });
+
+// Internal transfers (both accounts on Hypercore)
+await client.deposit("100"); // spot → perp
+await client.withdraw("50"); // perp → spot
+
+// Deposit flow helpers (used by the MCP deposit_to_hyperliquid tool)
+const funding = await client.getFundingAddress("solana:101");
+// ... user sends tokens to funding.depositAddress on the source chain ...
+const destinationAmount = await client.pollBridgeDeposit(txHash, funding.depositAddress, Date.now());
+const usdcAmount = await client.sellSpotToUsdc(funding.spotAssetId, destinationAmount, funding.spotSzDecimals);
+await client.deposit(usdcAmount);
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new PerpsClient(options: PerpsClientOptions)
+```
+
+| Option          | Type                                              | Description                                               |
+| --------------- | ------------------------------------------------- | --------------------------------------------------------- |
+| `evmAddress`    | `string`                                          | The wallet's EVM address (0x-prefixed)                    |
+| `signTypedData` | `(typedData: Eip712TypedData) => Promise<string>` | Signs EIP-712 data, returns 0x-prefixed hex signature     |
+| `apiBaseUrl`    | `string?`                                         | Phantom API base URL (default: `https://api.phantom.app`) |
+
+### Read Methods
+
+| Method                | Returns              | Endpoint                                      |
+| --------------------- | -------------------- | --------------------------------------------- |
+| `getBalance()`        | `PerpAccountBalance` | `GET /swap/v2/perp/balance`                   |
+| `getPositions()`      | `PerpPosition[]`     | `GET /swap/v2/perp/positions-and-open-orders` |
+| `getOpenOrders()`     | `PerpOrder[]`        | `GET /swap/v2/perp/positions-and-open-orders` |
+| `getMarkets()`        | `PerpMarket[]`       | `GET /swap/v2/perp/markets`                   |
+| `getTradeHistory()`   | `HistoricalOrder[]`  | `GET /swap/v2/perp/trade-history`             |
+| `getFundingHistory()` | `FundingActivity[]`  | `GET /swap/v2/perp/deposits-and-withdrawals`  |
+
+### Write Methods
+
+| Method                   | Signs                              | Endpoint                                |
+| ------------------------ | ---------------------------------- | --------------------------------------- |
+| `openPosition(params)`   | Exchange/Agent EIP-712             | `POST /swap/v2/exchange`                |
+| `closePosition(params)`  | Exchange/Agent EIP-712             | `POST /swap/v2/exchange`                |
+| `cancelOrder(params)`    | Exchange/Agent EIP-712             | `POST /swap/v2/exchange`                |
+| `updateLeverage(params)` | Exchange/Agent EIP-712             | `POST /swap/v2/exchange`                |
+| `deposit(amountUsdc)`    | HyperliquidSignTransaction EIP-712 | `POST /swap/v2/transfer-usdc-spot-perp` |
+| `withdraw(amountUsdc)`   | HyperliquidSignTransaction EIP-712 | `POST /swap/v2/transfer-usdc-spot-perp` |
+
+### Deposit Flow Helpers
+
+| Method                                                             | Description                                          |
+| ------------------------------------------------------------------ | ---------------------------------------------------- |
+| `getFundingAddress(sourceNetworkId)`                               | Gets the deposit address on the source chain         |
+| `pollBridgeDeposit(txHash, depositAddress, startedAt, timeoutMs?)` | Polls until bridge confirms (default 10 min timeout) |
+| `sellSpotToUsdc(assetId, amount, szDecimals)`                      | Sells bridged token on Hyperliquid spot for USDC     |
+
+## EIP-712 Signing
+
+Hyperliquid uses two EIP-712 signing patterns:
+
+**Exchange actions** (orders, cancel, leverage): The action is msgpack-encoded and keccak256-hashed to produce a `connectionId`. The typed data has `primaryType: "Agent"` with `domain.chainId: 1337` ("off-chain").
+
+**Transfer actions** (deposit/withdraw): Direct EIP-712 with `primaryType: "HyperliquidTransaction:UsdClassTransfer"` and `domain.chainId: 42161` (Arbitrum mainnet).
+
+In both cases, the signed message is sent to the Phantom backend which proxies it to Hyperliquid.
+
+## User Address Format
+
+The Phantom perps API identifies users by their EVM address in CAIP-19 format:
+
+```
+hypercore:mainnet/address:0xyourevmaddress
+```
+
+This is derived from `evmAddress` automatically.
+
+## Deposit Flow
+
+Bridging funds from an external chain to Hyperliquid perps requires five steps:
+
+```
+Source chain (Solana/EVM)
+        ↓  POST /swap/v2/spot/funding
+        ↓  → deposit address on source chain
+        ↓
+Send tokens to deposit address
+        ↓
+Hyperunit/Relay bridge completes
+        ↓  GET /swap/v2/spot/bridge-operations (polled every 2s)
+        ↓
+[If non-USDC] Sell on Hyperliquid spot  →  USDC
+        ↓
+POST /swap/v2/transfer-usdc-spot-perp (spot → perp)
+```
+
+The `deposit_to_hyperliquid` MCP tool orchestrates this entire flow.

package/jest.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testMatch: ["**/*.test.ts"],
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+  // Allow Jest to transform @msgpack/msgpack (ESM package)
+  transformIgnorePatterns: ["node_modules/(?!(@msgpack)/)"],
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@phantom/perps-client",
+  "version": "0.1.1",
+  "description": "Hyperliquid perpetuals client for Phantom Wallet",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "lint": "tsc --noEmit && eslint --cache src --ext .ts,.tsx",
+    "check-types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "eslint": "8.53.0",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.1.2",
+    "tsup": "^6.7.0",
+    "typescript": "^5.0.4"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.0.0",
+    "@phantom/client": "workspace:^",
+    "axios": "^1.6.7",
+    "js-sha3": "^0.9.3"
+  }
+}

package/src/PerpsClient.test.ts

@@ -0,0 +1,216 @@
+/**
+ * Unit tests for PerpsClient.
+ *
+ * PerpsApi is mocked so tests run without HTTP. Focuses on order-size computation
+ * and API response handling — input validation is the responsibility of callers.
+ */
+
+import { PerpsClient } from "./PerpsClient.js";
+
+// ── PerpsApi mock ─────────────────────────────────────────────────────────────
+
+const mockApi = {
+  getAccountBalance: jest.fn(),
+  getPositionsAndOpenOrders: jest.fn(),
+  getTradeHistory: jest.fn(),
+  getFundingHistory: jest.fn(),
+  getMarkets: jest.fn(),
+  getAllMarkets: jest.fn(),
+  getTrendingMarkets: jest.fn(),
+  postPlaceOrder: jest.fn(),
+  postCancelOrder: jest.fn(),
+  postUpdateLeverage: jest.fn(),
+  postTransferUsdcSpotPerp: jest.fn(),
+};
+
+jest.mock("./api.js", () => ({
+  PerpsApi: jest.fn().mockImplementation(() => mockApi),
+}));
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const MOCK_MARKET = {
+  symbol: "BTC",
+  assetId: 0,
+  maxLeverage: 50,
+  szDecimals: 5,
+  price: "50000",
+  fundingRate: "0.0001",
+  openInterest: "1000000",
+  volume24h: "5000000",
+};
+
+const MOCK_POSITION = {
+  coin: "BTC",
+  direction: "long" as const,
+  size: "0.01",
+  margin: "500",
+  entryPrice: "50000",
+  leverage: { type: "unknown" as const, value: 10 },
+  unrealizedPnl: "0",
+  liquidationPrice: null,
+};
+
+const OK_RESPONSE = { status: "ok", response: { type: "order", data: { statuses: [] } } };
+
+function makeClient(): PerpsClient {
+  return new PerpsClient({
+    evmAddress: "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+    signTypedData: () => Promise.resolve("0x" + "a".repeat(64) + "b".repeat(64) + "1b"),
+  });
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockApi.getMarkets.mockResolvedValue([MOCK_MARKET]);
+  mockApi.getPositionsAndOpenOrders.mockResolvedValue({ positions: [MOCK_POSITION], openOrders: [] });
+  mockApi.postPlaceOrder.mockResolvedValue(OK_RESPONSE);
+  mockApi.postCancelOrder.mockResolvedValue({ status: "ok" });
+  mockApi.postUpdateLeverage.mockResolvedValue({ status: "ok" });
+  mockApi.postTransferUsdcSpotPerp.mockResolvedValue({ status: "ok" });
+});
+
+// ── openPosition ──────────────────────────────────────────────────────────────
+
+describe("openPosition", () => {
+  const VALID: Parameters<PerpsClient["openPosition"]>[0] = {
+    market: "BTC",
+    direction: "long",
+    sizeUsd: "100",
+    leverage: 10,
+    orderType: "market",
+  };
+
+  it("succeeds with valid params", async () => {
+    const client = makeClient();
+    await expect(client.openPosition(VALID)).resolves.toBeDefined();
+  });
+
+  it.each([["0"], ["-100"], ["abc"], ["1e5"], [" 100"], ["100 "]])("rejects sizeUsd=%j", async bad => {
+    const client = makeClient();
+    await expect(client.openPosition({ ...VALID, sizeUsd: bad })).rejects.toThrow("sizeUsd");
+  });
+
+  it("rejects when market price is zero/NaN", async () => {
+    mockApi.getMarkets.mockResolvedValue([{ ...MOCK_MARKET, price: "0" }]);
+    const client = makeClient();
+    await expect(client.openPosition(VALID)).rejects.toThrow("Invalid market price");
+  });
+
+  it("rejects when order size rounds to zero", async () => {
+    // sizeUsd=0.000001 at price=50000 → rawSize ~2e-11 → rounds to 0 at 5 decimals
+    mockApi.getMarkets.mockResolvedValue([{ ...MOCK_MARKET, price: "50000" }]);
+    const client = makeClient();
+    await expect(client.openPosition({ ...VALID, sizeUsd: "0.000001" })).rejects.toThrow("Order size rounds to zero");
+  });
+});
+
+// ── closePosition ─────────────────────────────────────────────────────────────
+
+describe("closePosition", () => {
+  it("succeeds with no sizePercent (full close)", async () => {
+    const client = makeClient();
+    await expect(client.closePosition({ market: "BTC" })).resolves.toBeDefined();
+  });
+
+  it("succeeds with valid sizePercent", async () => {
+    const client = makeClient();
+    await expect(client.closePosition({ market: "BTC", sizePercent: 50 })).resolves.toBeDefined();
+  });
+
+  it("rejects when no open position exists", async () => {
+    mockApi.getPositionsAndOpenOrders.mockResolvedValue({ positions: [], openOrders: [] });
+    const client = makeClient();
+    await expect(client.closePosition({ market: "BTC" })).rejects.toThrow("No open position for market: BTC");
+  });
+
+  it("rejects when position.size is '0' (zero position)", async () => {
+    mockApi.getPositionsAndOpenOrders.mockResolvedValue({
+      positions: [{ ...MOCK_POSITION, size: "0" }],
+      openOrders: [],
+    });
+    const client = makeClient();
+    await expect(client.closePosition({ market: "BTC" })).rejects.toThrow("Invalid position size");
+  });
+
+  it("rejects when position.size is malformed (NaN)", async () => {
+    mockApi.getPositionsAndOpenOrders.mockResolvedValue({
+      positions: [{ ...MOCK_POSITION, size: "not-a-number" }],
+      openOrders: [],
+    });
+    const client = makeClient();
+    await expect(client.closePosition({ market: "BTC" })).rejects.toThrow("Invalid position size");
+  });
+
+  it("handles short positions (negative size) correctly via Math.abs", async () => {
+    // Shorts are represented with negative size; Math.abs must normalise it
+    mockApi.getPositionsAndOpenOrders.mockResolvedValue({
+      positions: [{ ...MOCK_POSITION, size: "-0.01", direction: "short" }],
+      openOrders: [],
+    });
+    const client = makeClient();
+    await expect(client.closePosition({ market: "BTC" })).resolves.toBeDefined();
+  });
+
+  it("rejects when sizePercent is so small the close size rounds to zero", async () => {
+    // position.size = 0.000001 → formatSize(0.000001, 5) = "0.00000" → rejects
+    mockApi.getPositionsAndOpenOrders.mockResolvedValue({
+      positions: [{ ...MOCK_POSITION, size: "0.000001" }],
+      openOrders: [],
+    });
+    const client = makeClient();
+    await expect(client.closePosition({ market: "BTC" })).rejects.toThrow("Close size rounds to zero");
+  });
+});
+
+// ── cancelOrder ───────────────────────────────────────────────────────────────
+
+describe("cancelOrder", () => {
+  it("succeeds with a valid safe integer orderId", async () => {
+    const client = makeClient();
+    await expect(client.cancelOrder({ market: "BTC", orderId: 42 })).resolves.toBeDefined();
+  });
+});
+
+// ── updateLeverage ────────────────────────────────────────────────────────────
+
+describe("updateLeverage", () => {
+  const VALID: Parameters<PerpsClient["updateLeverage"]>[0] = {
+    market: "BTC",
+    leverage: 10,
+    marginType: "isolated",
+  };
+
+  it("succeeds with valid params", async () => {
+    const client = makeClient();
+    await expect(client.updateLeverage(VALID)).resolves.toBeDefined();
+  });
+});
+
+// ── deposit ───────────────────────────────────────────────────────────────────
+
+describe("deposit", () => {
+  it("succeeds with a valid amount", async () => {
+    const client = makeClient();
+    await expect(client.deposit("100")).resolves.toBeDefined();
+  });
+
+  it.each([["0"], ["-50"], ["all"], ["abc"], ["   "], [""], [" 100"], ["1e5"]])("rejects amountUsdc=%j", async bad => {
+    const client = makeClient();
+    await expect(client.deposit(bad)).rejects.toThrow("amountUsdc");
+  });
+});
+
+// ── withdraw ──────────────────────────────────────────────────────────────────
+
+describe("withdraw", () => {
+  it("succeeds with a valid amount", async () => {
+    const client = makeClient();
+    await expect(client.withdraw("50.5")).resolves.toBeDefined();
+  });
+
+  it.each([["0"], ["-10"], ["all"], ["abc"], [" 50"], ["1e5"]])("rejects amountUsdc=%j", async bad => {
+    const client = makeClient();
+    await expect(client.withdraw(bad)).rejects.toThrow("amountUsdc");
+  });
+});