feat: add Hyperliquid prediction market (HIP-4 outcome markets)

Author: realfishsam

changelog.md

@@ -2,6 +2,41 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.38.0] - 2026-05-08
+
+### Feat: Hyperliquid prediction market (HIP-4 Outcome Markets)
+
+Added Hyperliquid as the 12th supported exchange. Hyperliquid's HIP-4
+outcome markets are binary contracts that trade on the same HyperCore
+matching engine as their perps and spot, settling in USDH.
+
+**Read-only (no credentials required):**
+- `fetchMarkets` / `fetchEvents` -- discovers outcomes via `outcomeMeta`
+- `fetchOrderBook` -- L2 book via `#coin` notation
+- `fetchOHLCV` -- candle snapshots (1m through 1M intervals)
+- `fetchTrades` -- recent trades
+
+**User data (wallet address required):**
+- `fetchBalance` / `fetchPositions` / `fetchOpenOrders` / `fetchMyTrades`
+
+**Trading (private key required):**
+- `buildOrder` / `submitOrder` / `createOrder` / `cancelOrder`
+- Full EIP-712 phantom agent signing (msgpack + keccak256 action hash)
+- Outcome market orders use `grouping: "na"` per HIP-4 spec
+
+**Environment variables:**
+- `HYPERLIQUID_WALLET_ADDRESS` -- wallet address for read-only user data
+- `HYPERLIQUID_PRIVATE_KEY` -- EVM private key for trading (EIP-712)
+
+**New dependency:** `msgpackr` for Hyperliquid action hash serialization.
+
+### Files
+
+- `core/src/exchanges/hyperliquid/` -- 7 files (config, utils, errors,
+  fetcher, normalizer, auth, index)
+- `core/src/server/exchange-factory.ts` -- added `case "hyperliquid"`
+- `core/src/index.ts` -- added exports
+
 ## [2.37.14] - 2026-05-08
 
 ### Feat: Polymarket deposit wallet support (signatureType 3)

core/package.json

@@ -59,6 +59,7 @@
     "express": "^5.2.1",
     "isows": "^1.0.6",
     "jest": "^30.2.0",
+    "msgpackr": "^2.0.1",
     "polymarket-us": "0.1.1",
     "tsx": "^4.21.0",
     "ws": "^8.18.0"

core/src/exchanges/hyperliquid/auth.ts

@@ -0,0 +1,194 @@
+import { Wallet, utils } from 'ethers';
+import { Packr } from 'msgpackr';
+import { ExchangeCredentials } from '../../BaseExchange';
+import { AuthenticationError } from '../../errors';
+import { EXCHANGE_CHAIN_ID } from './config';
+
+// Standard msgpack encoder — variableMapSize ensures fixmap/fixarray encoding
+// which matches the Python/Rust msgpack libraries that Hyperliquid's server uses.
+const packr = new Packr({ useRecords: false, variableMapSize: true });
+
+// ----------------------------------------------------------------------------
+// EIP-712 domain and types for Hyperliquid L1 action signing
+// ----------------------------------------------------------------------------
+
+const EIP712_DOMAIN = {
+    name: 'Exchange',
+    version: '1',
+    chainId: EXCHANGE_CHAIN_ID,
+    verifyingContract: '0x0000000000000000000000000000000000000000',
+};
+
+const AGENT_TYPES = {
+    Agent: [
+        { name: 'source', type: 'string' },
+        { name: 'connectionId', type: 'bytes32' },
+    ],
+};
+
+// ----------------------------------------------------------------------------
+// Signature type
+// ----------------------------------------------------------------------------
+
+export interface HyperliquidSignature {
+    r: string;
+    s: string;
+    v: number;
+}
+
+// ----------------------------------------------------------------------------
+// msgpack helpers -- Hyperliquid requires int64 encoding for large integers
+// ----------------------------------------------------------------------------
+
+function convertLargeInts(obj: unknown): unknown {
+    if (typeof obj === 'number' && Number.isInteger(obj) &&
+        (obj >= 0x100000000 || obj < -0x80000000)) {
+        return BigInt(obj);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(convertLargeInts);
+    }
+    if (typeof obj === 'object' && obj !== null) {
+        const result: Record<string, unknown> = {};
+        for (const [key, val] of Object.entries(obj)) {
+            if (val !== undefined) {
+                result[key] = convertLargeInts(val);
+            }
+        }
+        return result;
+    }
+    return obj;
+}
+
+// ----------------------------------------------------------------------------
+// Action hash -- constructs the connectionId for the phantom agent
+// ----------------------------------------------------------------------------
+
+function computeActionHash(
+    action: Record<string, unknown>,
+    vaultAddress: string | null,
+    nonce: number,
+): string {
+    // 1. msgpack-encode the action (large ints as int64)
+    const actionBytes = packr.pack(convertLargeInts(action));
+
+    // 2. nonce as 8 bytes big-endian
+    const nonceBytes = Buffer.alloc(8);
+    nonceBytes.writeBigUInt64BE(BigInt(nonce));
+
+    // 3. vault address marker
+    const parts: Buffer[] = [Buffer.from(actionBytes), nonceBytes];
+
+    if (vaultAddress) {
+        parts.push(Buffer.from([0x01]));
+        parts.push(Buffer.from(vaultAddress.replace('0x', ''), 'hex'));
+    } else {
+        parts.push(Buffer.from([0x00]));
+    }
+
+    // 4. keccak256 of concatenated bytes
+    return utils.keccak256(Buffer.concat(parts));
+}
+
+// ----------------------------------------------------------------------------
+// Price/size formatting -- must match Hyperliquid's wire format
+// ----------------------------------------------------------------------------
+
+export function floatToWire(x: number): string {
+    const rounded = x.toFixed(8);
+    if (Math.abs(parseFloat(rounded) - x) >= 1e-12) {
+        throw new Error(`floatToWire causes rounding: ${x}`);
+    }
+    return parseFloat(rounded).toString();
+}
+
+// ----------------------------------------------------------------------------
+// Auth class
+// ----------------------------------------------------------------------------
+
+export class HyperliquidAuth {
+    private readonly wallet: Wallet;
+    private readonly isMainnet: boolean;
+
+    constructor(credentials: ExchangeCredentials, testnet: boolean) {
+        if (!credentials.privateKey) {
+            throw new AuthenticationError(
+                'Hyperliquid trading requires a privateKey for EIP-712 signing.',
+                'Hyperliquid',
+            );
+        }
+
+        let privateKey = credentials.privateKey;
+        if (privateKey.includes('\\n')) {
+            privateKey = privateKey.replace(/\\n/g, '\n');
+        }
+
+        const stripped = privateKey.startsWith('0x') ? privateKey.slice(2) : privateKey;
+        if (!/^[0-9a-fA-F]{64}$/.test(stripped)) {
+            throw new AuthenticationError(
+                'Invalid private key format. Hyperliquid requires a 32-byte hex EVM private key (e.g. 0xabc123...).',
+                'Hyperliquid',
+            );
+        }
+
+        this.wallet = new Wallet(privateKey);
+        this.isMainnet = !testnet;
+    }
+
+    getAddress(): string {
+        return this.wallet.address;
+    }
+
+    /**
+     * Sign an L1 action using the phantom agent EIP-712 scheme.
+     *
+     * Flow:
+     *   1. msgpack-encode the action
+     *   2. Append nonce (8 bytes BE) + vault marker
+     *   3. keccak256 -> connectionId
+     *   4. EIP-712 sign {source, connectionId} with domain "Exchange"
+     */
+    async signL1Action(
+        action: Record<string, unknown>,
+        vaultAddress: string | null = null,
+        nonce: number = Date.now(),
+    ): Promise<{ signature: HyperliquidSignature; nonce: number }> {
+        const connectionId = computeActionHash(action, vaultAddress, nonce);
+
+        const message = {
+            source: this.isMainnet ? 'a' : 'b',
+            connectionId,
+        };
+
+        // ethers v5 uses _signTypedData (underscore prefix)
+        const sig = await this.wallet._signTypedData(EIP712_DOMAIN, AGENT_TYPES, message);
+        const split = utils.splitSignature(sig);
+
+        return {
+            signature: {
+                r: split.r,
+                s: split.s,
+                v: split.v,
+            },
+            nonce,
+        };
+    }
+
+    /**
+     * Build and sign a complete exchange request body.
+     */
+    async signExchangeRequest(
+        action: Record<string, unknown>,
+        vaultAddress: string | null = null,
+    ): Promise<Record<string, unknown>> {
+        const nonce = Date.now();
+        const { signature } = await this.signL1Action(action, vaultAddress, nonce);
+
+        return {
+            action,
+            nonce,
+            signature,
+            vaultAddress,
+        };
+    }
+}

core/src/exchanges/hyperliquid/config.ts

@@ -0,0 +1,38 @@
+export const DEFAULT_HYPERLIQUID_BASE_URL = 'https://api.hyperliquid.xyz';
+export const HYPERLIQUID_TESTNET_BASE_URL = 'https://api.hyperliquid-testnet.xyz';
+
+export const HYPERLIQUID_WS_URL = 'wss://api.hyperliquid.xyz/ws';
+export const HYPERLIQUID_TESTNET_WS_URL = 'wss://api.hyperliquid-testnet.xyz/ws';
+
+// HIP-4 Outcome Markets asset ID encoding
+// Asset ID = 100_000_000 + (10 * outcome_id) + side
+// side: 0 = Yes, 1 = No
+export const OUTCOME_ASSET_BASE = 100_000_000;
+export const OUTCOME_MULTIPLIER = 10;
+export const SIDE_YES = 0;
+export const SIDE_NO = 1;
+
+// EIP-712 signing constants
+export const EXCHANGE_DOMAIN = 'Exchange';
+export const EXCHANGE_CHAIN_ID = 1337;
+
+// Minimum order value in USDH
+export const MIN_ORDER_VALUE = 10;
+
+export interface HyperliquidApiConfig {
+    baseUrl: string;
+    wsUrl: string;
+    testnet: boolean;
+}
+
+export function getHyperliquidConfig(
+    baseUrlOverride?: string,
+    testnet?: boolean,
+): HyperliquidApiConfig {
+    const isTestnet = testnet ?? false;
+    return {
+        baseUrl: baseUrlOverride ?? (isTestnet ? HYPERLIQUID_TESTNET_BASE_URL : DEFAULT_HYPERLIQUID_BASE_URL),
+        wsUrl: isTestnet ? HYPERLIQUID_TESTNET_WS_URL : HYPERLIQUID_WS_URL,
+        testnet: isTestnet,
+    };
+}

core/src/exchanges/hyperliquid/errors.ts

@@ -0,0 +1,74 @@
+import axios from 'axios';
+import { ErrorMapper } from '../../utils/error-mapper';
+import {
+    AuthenticationError,
+    BadRequest,
+    InsufficientFunds,
+    InvalidOrder,
+    RateLimitExceeded,
+} from '../../errors';
+
+/**
+ * Maps Hyperliquid API errors to PMXT unified error classes.
+ *
+ * Hyperliquid returns errors as plain strings or JSON objects in
+ * the response body. Common patterns:
+ *   - "User has no account" -> AuthenticationError
+ *   - "Insufficient margin" -> InsufficientFunds
+ *   - "Invalid order" -> InvalidOrder
+ */
+export class HyperliquidErrorMapper extends ErrorMapper {
+    constructor() {
+        super('Hyperliquid');
+    }
+
+    protected extractErrorMessage(error: any): string {
+        if (axios.isAxiosError(error) && error.response?.data) {
+            const data = error.response.data;
+            if (typeof data === 'string') {
+                return `[${error.response.status}] ${data}`;
+            }
+            if (data.status === 'err' && data.response) {
+                return `[${error.response.status}] ${data.response}`;
+            }
+        }
+        return super.extractErrorMessage(error);
+    }
+
+    protected mapBadRequestError(message: string, data: any): BadRequest {
+        const lowerMessage = message.toLowerCase();
+        const responseStr = typeof data === 'object' && data?.response
+            ? String(data.response).toLowerCase()
+            : lowerMessage;
+
+        if (responseStr.includes('insufficient margin') || responseStr.includes('not enough')) {
+            return new InsufficientFunds(message, this.exchangeName);
+        }
+
+        if (responseStr.includes('invalid order') || responseStr.includes('price out of range')) {
+            return new InvalidOrder(message, this.exchangeName);
+        }
+
+        if (responseStr.includes('no account') || responseStr.includes('not authorized')) {
+            return new AuthenticationError(message, this.exchangeName);
+        }
+
+        return super.mapBadRequestError(message, data);
+    }
+
+    mapError(error: any): ReturnType<ErrorMapper['mapError']> {
+        if (axios.isAxiosError(error) && error.response?.status === 429) {
+            const retryAfter = error.response.headers?.['retry-after'];
+            const retryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : undefined;
+            return new RateLimitExceeded(
+                this.extractErrorMessage(error),
+                retryAfterSeconds,
+                this.exchangeName,
+            );
+        }
+
+        return super.mapError(error);
+    }
+}
+
+export const hyperliquidErrorMapper = new HyperliquidErrorMapper();