@lifi/perps-sdk-provider-hyperliquid 0.2.0-alpha.0

package/dist/types/websocket/HyperliquidWsProvider.d.ts

@@ -0,0 +1,61 @@
+import { type PerpsSDKClient, type ProviderGetQuoteParams, type QuoteListener, WsProviderBase, type WsProviderFactory } from '@lifi/perps-sdk';
+import { type Subscription } from '@lifi/perps-types';
+/**
+ * `WsProviderFactory` constructor for Hyperliquid — pass to
+ * `new PerpsWsClient(client, { wsProviders: { hyperliquid: hyperliquidWsProvider() } })`.
+ *
+ * Derives the active sub-DEX set from the `markets` list `PerpsWsClient`
+ * passes in (the provider's own key and `'spot'` are excluded — they
+ * aren't sub-DEX subscriptions on the HL wire). Higher-order shape mirrors
+ * `lighterWsProvider(options)` so the two factories register identically.
+ *
+ * @public
+ */
+export declare const hyperliquidWsProvider: () => WsProviderFactory;
+/**
+ * Hyperliquid realtime {@link WsProvider}: multiplexes prices, positions,
+ * orders, fills and spot balances over a single {@link ReconnectingWebSocket}.
+ * Construct via {@link hyperliquidWsProvider}.
+ *
+ * `orderUpdates` supports a single address per provider instance: HL delivers
+ * those frames without a user field, so frames from two concurrent address
+ * subscriptions on one socket cannot be attributed. Subscribing a second
+ * address rejects while the first still has listeners; once the first is
+ * released, an address switch reclaims the channel immediately.
+ *
+ * @public
+ */
+export declare class HyperliquidWsProvider extends WsProviderBase<object> {
+    private orderUpdatesKey;
+    private readonly subDexes;
+    private readonly client;
+    private readonly registry;
+    private midsBySubDex;
+    constructor(wsUrl: string, providerKey: string, subDexes: string[], client?: PerpsSDKClient);
+    subscribeQuote(params: ProviderGetQuoteParams, onQuote: QuoteListener): Promise<() => void>;
+    protected openChannel(sub: Subscription): Promise<() => void>;
+    /**
+     * Enforce the single-address `orderUpdates` invariant (HL frames carry no
+     * user field, so concurrent address subscriptions are unattributable). A
+     * listener-free lingering channel for another address is torn down eagerly
+     * so a wallet switch needn't wait out the teardown linger; a live one throws.
+     */
+    private claimOrderUpdatesKey;
+    /** Build sub-key + payload pairs for each sub-dex allMids subscription. */
+    private getPriceSubEntries;
+    protected onClose(): void;
+    protected sendSubscribe(payload: object): void;
+    protected toKey(sub: Subscription): string;
+    private toHlPayload;
+    protected handleMessage(raw: string): void;
+    private handleAllMids;
+    /** Latest mid per `Market.id`, merged across sub-dex allMids frames. */
+    private mergedMids;
+    private handleL2Book;
+    private handleCandle;
+    private handleOrderUpdates;
+    private handleUserFills;
+    private handleAllDexsClearinghouseState;
+    private handleSpotState;
+}
+//# sourceMappingURL=HyperliquidWsProvider.d.ts.map

package/dist/types/websocket/HyperliquidWsProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HyperliquidWsProvider.d.ts","sourceRoot":"","sources":["../../../src/websocket/HyperliquidWsProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAGlB,cAAc,EACd,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAIL,KAAK,YAAY,EAElB,MAAM,mBAAmB,CAAA;AA8B1B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAC5B,iBAIH,CAAA;AAEH;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,SAAQ,cAAc,CAAC,MAAM,CAAC;IAC/D,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,YAAY,CAA4C;gBAG9D,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,CAAC,EAAE,cAAc;IAWnB,cAAc,CAClB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;cAkBN,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAgDnE;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAiB5B,2EAA2E;IAC3E,OAAO,CAAC,kBAAkB;cAaP,OAAO,IAAI,IAAI;IAKlC,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAM9C,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM;IAmB1C,OAAO,CAAC,WAAW;IAqCnB,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM;IAyDnC,OAAO,CAAC,aAAa;IAYrB,wEAAwE;IACxE,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,kBAAkB;IA0D1B,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,+BAA+B;IAkBvC,OAAO,CAAC,eAAe;CAaxB"}

package/dist/types/websocket/index.d.ts

@@ -0,0 +1,2 @@
+export { HyperliquidWsProvider } from './HyperliquidWsProvider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/websocket/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/websocket/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@lifi/perps-sdk-provider-hyperliquid",
+  "version": "0.2.0-alpha.0",
+  "description": "Hyperliquid provider plugin for @lifi/perps-sdk",
+  "homepage": "https://github.com/lifinance/perps-sdk",
+  "bugs": {
+    "url": "https://github.com/lifinance/perps-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lifinance/perps-sdk.git"
+  },
+  "license": "Apache-2.0",
+  "author": "LI.FI <dev@li.fi>",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "typings": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/cjs/index.js"
+    },
+    "./realtime": {
+      "types": "./dist/types/realtime/index.d.ts",
+      "import": "./dist/esm/realtime/index.js",
+      "default": "./dist/cjs/realtime/index.js"
+    },
+    "./utils": {
+      "types": "./dist/types/utils/index.d.ts",
+      "import": "./dist/esm/utils/index.js",
+      "default": "./dist/cjs/utils/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**",
+    "!dist/**/*.tsbuildinfo",
+    "src/**/*.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.mock.ts",
+    "!src/**/*.handlers.ts",
+    "!src/**/*.tsbuildinfo",
+    "!**/__mocks__/**",
+    "!*.tmp",
+    "!*.env",
+    "!tsconfig.json"
+  ],
+  "dependencies": {
+    "big.js": "^7.0.1",
+    "@lifi/perps-types": "0.2.0-alpha.0"
+  },
+  "peerDependencies": {
+    "viem": "^2.48.8",
+    "@lifi/perps-sdk": "0.2.0-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "perps",
+    "perpetuals",
+    "trading",
+    "defi",
+    "lifi",
+    "sdk",
+    "hyperliquid"
+  ]
+}

package/src/HyperliquidProvider.ts

@@ -0,0 +1,381 @@
+import {
+  type ActionSignerContribution,
+  type LiquidationEstimateParams,
+  PerpsError,
+  PerpsErrorMessage,
+  type PerpsProviderPlugin,
+  type PerpsSDKClient,
+  type ProviderGetAccountParams,
+  type ProviderGetActivityParams,
+  type ProviderGetFillsParams,
+  type ProviderGetOrderParams,
+  type ProviderGetOrdersParams,
+  type ProviderGetPositionsParams,
+  type ProviderGetQuoteParams,
+  resolveQuote,
+  type SDKRequestOptions,
+  type SignActionsContext,
+  type StorageAdapter,
+} from '@lifi/perps-sdk'
+import {
+  type AccountConfig,
+  type AccountConfigSetting,
+  type AccountResponse,
+  type AccountSummary,
+  type ActionStep,
+  ActionType,
+  type ActivitiesResponse,
+  type FillsResponse,
+  type Market,
+  type Order,
+  type OrdersResponse,
+  PerpsErrorCode,
+  type PerpsMarket,
+  PerpsSigner,
+  type Position,
+  type PositionsResponse,
+  type ProviderAction,
+  type Quote,
+  type SignedActionStep,
+  type SigningMethod,
+} from '@lifi/perps-types'
+import { type Address, type Hex, isAddress } from 'viem'
+import { projectHyperliquidConfigSettings } from './accountConfig.js'
+import { summarizeHyperliquidAccount } from './accountSummary.js'
+import {
+  DEFAULT_HYPERLIQUID_API_URL,
+  HYPERLIQUID_FEE_TIER_FALLBACK,
+  PROVIDER_KEY,
+  SPOT_MARKET_ID,
+} from './constants.js'
+import { HyperliquidContextRef } from './context.js'
+import { getAccount } from './services/getAccount.js'
+import { getActivity } from './services/getActivity.js'
+import { getFills } from './services/getFills.js'
+import { getOrder } from './services/getOrder.js'
+import { getOrders } from './services/getOrders.js'
+import { getPositions } from './services/getPositions.js'
+import {
+  type HyperliquidAgent,
+  HyperliquidAgentStore,
+} from './signers/HyperliquidAgentStore.js'
+import { hyperliquidSignActions } from './signers/signActions.js'
+import type { HlExtraAgents } from './types/index.js'
+import { hlInfoOptions, infoRequest } from './utils/infoClient.js'
+import { calculateLiquidationPrice } from './utils/liquidation.js'
+import { formatOrderPrice, formatOrderSize } from './utils/orderFormatting.js'
+
+/**
+ * Options for {@link hyperliquidProvider}.
+ *
+ * @public
+ */
+export interface HyperliquidProviderOptions {
+  /**
+   * Base URL for the Hyperliquid REST surface. Defaults to
+   * `https://api.hyperliquid.xyz`. Override to point at a custom or
+   * third-party endpoint — e.g. a reverse proxy, a self-hosted mirror, or a
+   * rate-limit-managed gateway in front of Hyperliquid.
+   */
+  apiUrl?: string
+  /**
+   * Storage adapter for the user's per-address Hyperliquid agent keypair.
+   * Defaults to browser `localStorage`. Pass a custom adapter for SSR /
+   * non-browser hosts or encrypted storage.
+   */
+  storage?: StorageAdapter
+}
+
+/**
+ * Hyperliquid provider plugin extended with agent-keypair lifecycle methods.
+ * Hyperliquid signs trading actions with a per-user agent wallet the user
+ * approves via `APPROVE_AGENT`; the plugin owns that keypair's generation,
+ * persistence, and revocation. The base {@link PerpsProviderPlugin} contract
+ * stays provider-agnostic — this extension is opt-in for callers that
+ * explicitly type against it (e.g. to surface a "revoke agent" affordance).
+ */
+export interface HyperliquidPerpsProvider extends PerpsProviderPlugin {
+  /** Resolve the agent wallet address, throwing if none has been created. */
+  getAgentAddress(address: Address): Promise<Address>
+  /** Whether an agent keypair exists for the user address. */
+  hasAgent(address: Address): Promise<boolean>
+  /** Remove the user's agent keypair (revoke local authorization). */
+  removeAgent(address: Address): Promise<void>
+  /** Import an existing agent keypair for the user address. */
+  importAgent(address: Address, privateKey: Hex): Promise<HyperliquidAgent>
+}
+
+/**
+ * Factory for the Hyperliquid {@link PerpsProviderPlugin}.
+ *
+ * Account-specific state is read direct from `${apiUrl}/info`; enriched asset
+ * metadata and public/shared data come from the LI.FI backend (Valkey-cached).
+ * Pass to `createPerpsClient({ providers: [hyperliquidProvider()] })` and look
+ * up via `client.getProvider('hyperliquid')`.
+ *
+ * Write actions are EIP-712 typed data signed by the user's Hyperliquid agent
+ * keypair; the plugin owns that keypair (generation, storage, revocation) and
+ * dispatches the agent-signed arm via `signActions`.
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({
+ *   integrator: 'my-app',
+ *   providers: [hyperliquidProvider()],
+ * })
+ * ```
+ * @public
+ */
+export function hyperliquidProvider(
+  options: HyperliquidProviderOptions = {}
+): HyperliquidPerpsProvider {
+  const apiUrl = options.apiUrl ?? DEFAULT_HYPERLIQUID_API_URL
+  const agentStore = new HyperliquidAgentStore(options.storage)
+  const contextRef = new HyperliquidContextRef(apiUrl)
+
+  const toLowerAddress = (value: unknown): string | null =>
+    typeof value === 'string' && isAddress(value) ? value.toLowerCase() : null
+
+  const toValidUntilMs = (value: unknown): number | null => {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return value
+    }
+    if (typeof value === 'string') {
+      const parsed = Number(value)
+      return Number.isFinite(parsed) ? parsed : null
+    }
+    return null
+  }
+
+  const isKnownExpiredRemoteAgent = async (
+    address: Address,
+    localAgentAddress: Address
+  ): Promise<boolean> => {
+    let context: ReturnType<typeof contextRef.require> | null = null
+    try {
+      context = contextRef.require()
+    } catch {
+      // Unbound provider (e.g. direct unit tests) cannot query /info.
+      return false
+    }
+    const agents = await infoRequest<HlExtraAgents>(
+      apiUrl,
+      { type: 'extraAgents', user: address },
+      hlInfoOptions(context.client)
+    )
+    const local = localAgentAddress.toLowerCase()
+    const match = agents.find(
+      (agent) => toLowerAddress(agent.address) === local
+    ) as Record<string, unknown> | undefined
+    if (!match) {
+      return false
+    }
+    const validUntilMs = toValidUntilMs(match.validUntil)
+    return validUntilMs !== null && validUntilMs <= Date.now()
+  }
+
+  const resolveApproveAgentAddress = async (
+    address: Address
+  ): Promise<Address> => {
+    try {
+      const localAgent = await agentStore.get(address)
+      try {
+        if (await isKnownExpiredRemoteAgent(address, localAgent.address)) {
+          await agentStore.remove(address)
+          return (await agentStore.getOrCreate(address)).address
+        }
+      } catch {
+        // If the upstream extra-agent probe fails, keep the existing local key.
+      }
+      return localAgent.address
+    } catch (error) {
+      if (
+        error instanceof PerpsError &&
+        error.message === PerpsErrorMessage.AgentNotFound
+      ) {
+        return (await agentStore.getOrCreate(address)).address
+      }
+      throw error
+    }
+  }
+
+  return {
+    type: PROVIDER_KEY,
+
+    bind: (client: PerpsSDKClient): void => contextRef.bind(client),
+
+    getAgentAddress: async (address: Address): Promise<Address> =>
+      (await agentStore.get(address)).address,
+
+    hasAgent: (address: Address): Promise<boolean> => agentStore.has(address),
+
+    removeAgent: (address: Address): Promise<void> =>
+      agentStore.remove(address),
+
+    importAgent: (
+      address: Address,
+      privateKey: Hex
+    ): Promise<HyperliquidAgent> => agentStore.import(address, privateKey),
+
+    resolveActionRequest: async (
+      action: ActionType,
+      address: Address,
+      signers: PerpsSigner[]
+    ): Promise<ActionSignerContribution> => {
+      // APPROVE_AGENT is user-signed: the user authorises the agent, so the
+      // agent address rides as a param (not signerAddress). The agent is
+      // provisioned on first use so its address is known before the backend
+      // builds the typed data.
+      if (action === ActionType.APPROVE_AGENT) {
+        const agentAddress = await resolveApproveAgentAddress(address)
+        return { params: { agentAddress } }
+      }
+      // Agent-signed actions (trades, account-mode) carry the agent as the
+      // on-wire signerAddress. User-signed actions (builder-fee, withdrawal)
+      // contribute nothing — core submits under the user's own address.
+      if (signers.includes(PerpsSigner.AGENT)) {
+        const agent = await agentStore.get(address)
+        return { signerAddress: agent.address }
+      }
+      return {}
+    },
+
+    signActions: (
+      method: SigningMethod,
+      steps: ActionStep[],
+      address: Address,
+      ctx?: SignActionsContext
+    ): Promise<SignedActionStep[]> =>
+      hyperliquidSignActions(agentStore, method, steps, address, ctx),
+
+    getAccount: (
+      params: ProviderGetAccountParams,
+      opts?: SDKRequestOptions
+    ): Promise<AccountResponse> =>
+      getAccount(contextRef.require(), { address: params.address }, opts),
+
+    getPositions: (
+      params: ProviderGetPositionsParams,
+      opts?: SDKRequestOptions
+    ): Promise<PositionsResponse> =>
+      getPositions(
+        contextRef.require(),
+        {
+          address: params.address,
+          marketId: params.marketId,
+          limit: params.limit,
+        },
+        opts
+      ),
+
+    getOrders: (
+      params: ProviderGetOrdersParams,
+      opts?: SDKRequestOptions
+    ): Promise<OrdersResponse> =>
+      getOrders(
+        contextRef.require(),
+        {
+          address: params.address,
+          marketId: params.marketId,
+          limit: params.limit,
+        },
+        opts
+      ),
+
+    getOrder: (
+      params: ProviderGetOrderParams,
+      opts?: SDKRequestOptions
+    ): Promise<Order> =>
+      getOrder(
+        contextRef.require(),
+        { address: params.address, id: params.id },
+        opts
+      ),
+
+    getFills: (
+      params: ProviderGetFillsParams,
+      opts?: SDKRequestOptions
+    ): Promise<FillsResponse> =>
+      getFills(
+        contextRef.require(),
+        {
+          address: params.address,
+          limit: params.limit,
+          cursor: params.cursor,
+          startTime: params.startTime,
+          endTime: params.endTime,
+        },
+        opts
+      ),
+
+    getActivity: (
+      params: ProviderGetActivityParams,
+      opts?: SDKRequestOptions
+    ): Promise<ActivitiesResponse> =>
+      getActivity(
+        contextRef.require(),
+        {
+          address: params.address,
+          limit: params.limit,
+          cursor: params.cursor,
+          startTime: params.startTime,
+          endTime: params.endTime,
+          type: params.type,
+        },
+        opts
+      ),
+
+    getQuote: (
+      params: ProviderGetQuoteParams,
+      opts?: SDKRequestOptions
+    ): Promise<Quote> =>
+      resolveQuote(
+        contextRef.require().client,
+        PROVIDER_KEY,
+        params,
+        HYPERLIQUID_FEE_TIER_FALLBACK,
+        opts
+      ),
+
+    getPortfolioSummary: (
+      account: AccountResponse,
+      positions: Position[]
+    ): AccountSummary => summarizeHyperliquidAccount(account, positions),
+
+    formatOrderPrice: (market: Market, price: number): string =>
+      formatOrderPrice(
+        price,
+        market.szDecimals,
+        market.categoryId === SPOT_MARKET_ID ? 'spot' : undefined
+      ),
+
+    formatOrderSize: (market: Market, size: number): string =>
+      formatOrderSize(size, market.szDecimals),
+
+    estimateLiquidationPrice: (
+      market: PerpsMarket,
+      params: LiquidationEstimateParams
+    ): number | undefined =>
+      calculateLiquidationPrice(
+        params.entryPrice,
+        params.leverage,
+        params.isLong,
+        market.maxLeverage
+      ),
+
+    projectConfig: (
+      config: AccountConfig,
+      setup: ProviderAction[],
+      options: ProviderAction[]
+    ): AccountConfigSetting[] => {
+      if (config.provider !== PROVIDER_KEY) {
+        throw new PerpsError(
+          PerpsErrorCode.SDKError,
+          `hyperliquidProvider.projectConfig received config for provider ` +
+            `'${config.provider}'.`
+        )
+      }
+      return projectHyperliquidConfigSettings(config, setup, options)
+    },
+  }
+}

package/src/accountConfig.ts

@@ -0,0 +1,89 @@
+import { PerpsError } from '@lifi/perps-sdk'
+import type {
+  AccountConfigSetting,
+  HyperliquidAccountConfig,
+  ProviderAction,
+} from '@lifi/perps-types'
+import { ActionType, PerpsErrorCode } from '@lifi/perps-types'
+
+function assertNever(value: never): never {
+  throw new Error(
+    `Unreachable: exhaustiveness check failed for value ${JSON.stringify(value)}`
+  )
+}
+
+/**
+ * Project a single Hyperliquid descriptor against the typed
+ * `HyperliquidAccountConfig` into an `AccountConfigSetting`.
+ *
+ * Mapping table:
+ *
+ * | descriptor.type       | projected values
+ * |-----------------------|----------------------------------------------
+ * | APPROVE_AGENT         | []                  (no parameters)
+ * | APPROVE_BUILDER_FEE   | []                  (no parameters)
+ * | ACCOUNT_MODE          | [{ name: 'mode', value: config.abstractionMode }]
+ *
+ * The switch is exhaustive over `ActionType` so enum additions force a
+ * compile error in the `default` arm. ActionTypes that are not valid on
+ * `Provider.setup` / `Provider.options` for Hyperliquid throw at runtime.
+ */
+function projectHyperliquidDescriptor(
+  descriptor: ProviderAction,
+  config: HyperliquidAccountConfig
+): AccountConfigSetting {
+  switch (descriptor.type) {
+    case ActionType.APPROVE_AGENT:
+    case ActionType.APPROVE_BUILDER_FEE:
+      return { type: descriptor.type, values: [] }
+
+    case ActionType.ACCOUNT_MODE:
+      return {
+        type: descriptor.type,
+        values: [{ name: 'mode', value: config.abstractionMode }],
+      }
+
+    case ActionType.ACCOUNT_TYPE:
+    case ActionType.SEND_ASSET:
+    case ActionType.WITHDRAWAL:
+    case ActionType.TRANSFER:
+    case ActionType.PLACE_ORDER:
+    case ActionType.PLACE_TRIGGER_ORDER:
+    case ActionType.CANCEL_ORDER:
+    case ActionType.CANCEL_ALL_ORDERS:
+    case ActionType.MODIFY_ORDER:
+    case ActionType.UPDATE_LEVERAGE:
+    case ActionType.UPDATE_POSITION_MARGIN:
+    case ActionType.REGISTER_API_KEY:
+    case ActionType.APPROVE_READ_ONLY_TOKEN:
+    case ActionType.DEPOSIT:
+    case ActionType.META_VOTE:
+    case ActionType.META_ACCEPT_TERMS:
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Hyperliquid account-config mapper has no projection for ` +
+          `descriptor type '${descriptor.type}' — this ActionType is not ` +
+          `valid on Provider.setup / Provider.options for Hyperliquid.`
+      )
+
+    default:
+      return assertNever(descriptor.type)
+  }
+}
+
+/**
+ * Project the union of Hyperliquid setup + options descriptors against the
+ * typed `HyperliquidAccountConfig`. Produces exactly one
+ * `AccountConfigSetting` per descriptor, in `setup`-then-`options` order.
+ *
+ * @public
+ */
+export function projectHyperliquidConfigSettings(
+  config: HyperliquidAccountConfig,
+  setup: ProviderAction[],
+  options: ProviderAction[]
+): AccountConfigSetting[] {
+  return [...setup, ...options].map((descriptor) =>
+    projectHyperliquidDescriptor(descriptor, config)
+  )
+}

package/src/accountSummary.ts

@@ -0,0 +1,32 @@
+import { summarizeAccount } from '@lifi/perps-sdk'
+import type {
+  AccountResponse,
+  AccountSummary,
+  Position,
+} from '@lifi/perps-types'
+import { HlAbstractionMode } from './types/index.js'
+
+/**
+ * In `unifiedAccount`/`portfolioMargin` the whole account lives in spot, so the
+ * collateral rows are already gross holdings (locked margin included). In
+ * `disabled`/`dexAbstraction` (and the unset/standard mode) the venue rows hold
+ * `accountValue`, which Hyperliquid reports net of locked margin — i.e. free.
+ */
+const isUnifiedMode = (account: AccountResponse): boolean =>
+  account.config.provider === 'hyperliquid' &&
+  (account.config.abstractionMode === HlAbstractionMode.UNIFIED_ACCOUNT ||
+    account.config.abstractionMode === HlAbstractionMode.PORTFOLIO_MARGIN)
+
+/**
+ * Roll a Hyperliquid {@link AccountResponse} up into an {@link AccountSummary},
+ * branching on the abstraction mode so the gross/free meaning of the collateral
+ * rows is interpreted correctly.
+ *
+ * @public
+ */
+export function summarizeHyperliquidAccount(
+  account: AccountResponse,
+  positions: Position[]
+): AccountSummary {
+  return summarizeAccount(account, positions, isUnifiedMode(account))
+}

package/src/constants.ts

@@ -0,0 +1,47 @@
+import type { FeeTier } from '@lifi/perps-types'
+
+/**
+ * Hyperliquid provider key (exported from the package index as
+ * `HYPERLIQUID_PROVIDER_KEY`).
+ *
+ * @public
+ */
+export const PROVIDER_KEY = 'hyperliquid'
+
+/**
+ * Default Hyperliquid REST base URL.
+ *
+ * @public
+ */
+export const DEFAULT_HYPERLIQUID_API_URL = 'https://api.hyperliquid.xyz'
+
+/**
+ * Approximate published baseline maker/taker fee tier for Hyperliquid, used to
+ * seed fee math before the live account `feeTier` resolves. Rates are fractions
+ * (not basis points): `0.00015` = 0.015% maker, `0.00045` = 0.045% taker.
+ *
+ * @public
+ */
+export const HYPERLIQUID_FEE_TIER_FALLBACK: FeeTier = {
+  maker: '0.00015',
+  taker: '0.00045',
+}
+
+/** @internal */
+export const DEFAULT_HISTORY_LIMIT = 50
+/** @internal */
+export const MAX_HISTORY_LIMIT = 200
+/** @internal */
+export const NINETY_DAYS_MS = 90 * 24 * 60 * 60 * 1000
+
+/**
+ * Main perps DEX uses an empty sub-dex name on the wire; surfaced as
+ * 'hyperliquid' in normalised market IDs.
+ *
+ * @internal
+ */
+export const MAIN_DEX_NAME = ''
+/** @internal */
+export const MAIN_MARKET_ID = 'hyperliquid'
+/** @internal */
+export const SPOT_MARKET_ID = 'spot'