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

package/src/utils/mapFill.ts

@@ -0,0 +1,48 @@
+import {
+  classifyFillFromPosition,
+  ExplorerChainId,
+  explorerTxUrl,
+} from '@lifi/perps-sdk'
+import type { Fill, MarketDisplay } from '@lifi/perps-types'
+import {
+  FillClassification,
+  FillStatus,
+  LiquidityRole,
+  OrderSide,
+  OrderType,
+} from '@lifi/perps-types'
+import { SPOT_MARKET_ID } from '../constants.js'
+import type { HlUserFill } from '../types/index.js'
+
+export { classifyFillFromPosition }
+
+/**
+ * Spot-ness comes from the resolved market's category, not the coin string —
+ * HL's canonical spot pair 0 is addressed as `PURR/USDC`, not `@0`.
+ * @public
+ */
+export const mapFill = (fill: HlUserFill, market: MarketDisplay): Fill => ({
+  ...(market.categoryId === SPOT_MARKET_ID
+    ? { realizedPnl: fill.closedPnl }
+    : { realizedPnl: fill.closedPnl === '0' ? null : fill.closedPnl }),
+  id: String(fill.tid),
+  orderId: String(fill.oid),
+  market,
+  side: fill.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
+  type: fill.dir?.includes('Limit') ? OrderType.LIMIT : OrderType.MARKET,
+  size: fill.sz,
+  price: fill.px,
+  status: FillStatus.FILLED,
+  liquidity: fill.crossed ? LiquidityRole.TAKER : LiquidityRole.MAKER,
+  filledSize: fill.sz,
+  fee: fill.fee,
+  startPosition: fill.startPosition,
+  explorerLink: explorerTxUrl(ExplorerChainId.HYPERLIQUID, fill.hash),
+  classification:
+    market.categoryId === SPOT_MARKET_ID
+      ? fill.side === 'B'
+        ? FillClassification.SPOT_BUY
+        : FillClassification.SPOT_SELL
+      : classifyFillFromPosition(fill.startPosition, fill.side, fill.sz),
+  createdAt: new Date(fill.time).toISOString(),
+})

package/src/utils/mapMarket.ts

@@ -0,0 +1,33 @@
+import type { PerpsMarket } from '@lifi/perps-types'
+import { PROVIDER_KEY } from '../constants.js'
+import type { HlUniverseItem } from '../types/index.js'
+import { calculateMaintenanceMarginRate } from './liquidation.js'
+import { coinAsset } from './marketDisplay.js'
+import { getMaxPriceDecimals } from './orderFormatting.js'
+
+/** Hyperliquid quotes every perp market in USDC. */
+const QUOTE_SYMBOL = 'USDC'
+
+/**
+ * Map a Hyperliquid universe entry to a {@link PerpsMarket}'s static instrument
+ * metadata. Live mark/stats fields live on the `/prices` item — see
+ * {@link mapMarketPrice}. `categoryId` is the `Provider.categories[].id` of the
+ * dex the entry was fetched from — known to the caller at fetch time, never
+ * re-derived from the coin string.
+ * @public
+ */
+export const mapMarket = (
+  universe: HlUniverseItem,
+  categoryId: string
+): PerpsMarket => ({
+  providerId: PROVIDER_KEY,
+  id: universe.name,
+  categoryId,
+  baseAsset: coinAsset(universe.name),
+  quoteAsset: coinAsset(QUOTE_SYMBOL),
+  szDecimals: universe.szDecimals,
+  priceDecimals: getMaxPriceDecimals(universe.szDecimals),
+  maxLeverage: universe.maxLeverage,
+  onlyIsolated: universe.onlyIsolated === true,
+  maintenanceMarginRate: calculateMaintenanceMarginRate(universe.maxLeverage),
+})

package/src/utils/mapMarketPrice.ts

@@ -0,0 +1,33 @@
+import type { MarketPrice } from '@lifi/perps-types'
+import type { HlAssetCtx } from '../types/index.js'
+
+const NEXT_FUNDING_INTERVAL_MS = 60 * 60 * 1000 // 1 hour
+
+/**
+ * Map a Hyperliquid asset context plus its mid to a {@link MarketPrice} — the
+ * live mark/stats data for the `/prices` item. `mid` is the market mid from
+ * `allMids`, known to the caller; `HlAssetCtx` carries no mid of its own.
+ * @public
+ */
+export const mapMarketPrice = (
+  marketId: string,
+  assetCtx: HlAssetCtx,
+  mid: string
+): MarketPrice => {
+  const now = Date.now()
+  const nextFundingTime =
+    Math.ceil(now / NEXT_FUNDING_INTERVAL_MS) * NEXT_FUNDING_INTERVAL_MS
+
+  return {
+    marketId,
+    price: mid,
+    markPrice: assetCtx.markPx,
+    prevDayPrice: assetCtx.prevDayPx,
+    volume24h: assetCtx.dayNtlVlm,
+    openInterest: assetCtx.openInterest,
+    funding: {
+      rate: assetCtx.funding,
+      nextFundingTime,
+    },
+  }
+}

package/src/utils/mapOrder.ts

@@ -0,0 +1,218 @@
+import type {
+  MarketDisplay,
+  OpenOrder,
+  Order,
+  TriggerOrder,
+} from '@lifi/perps-types'
+import {
+  OrderSide,
+  OrderStatus,
+  OrderType,
+  TimeInForce,
+} from '@lifi/perps-types'
+import type { HlFrontendOpenOrder, HlOrderDetail } from '../types/index.js'
+
+/**
+ * Map a Hyperliquid orderType string to the OrderType enum.
+ *
+ * @public
+ */
+export const mapOrderType = (orderType: string): OrderType => {
+  switch (orderType) {
+    case 'Take Profit Market':
+      return OrderType.TAKE_PROFIT_MARKET
+    case 'Take Profit Limit':
+      return OrderType.TAKE_PROFIT_LIMIT
+    case 'Stop Market':
+      return OrderType.STOP_MARKET
+    case 'Stop Limit':
+      return OrderType.STOP_LIMIT
+    case 'Market':
+      return OrderType.MARKET
+    default:
+      return OrderType.LIMIT
+  }
+}
+
+/** @public */
+export const isTriggerType = (type: OrderType): boolean =>
+  type === OrderType.TAKE_PROFIT_MARKET ||
+  type === OrderType.TAKE_PROFIT_LIMIT ||
+  type === OrderType.STOP_MARKET ||
+  type === OrderType.STOP_LIMIT
+
+/**
+ * Decide whether a raw Hyperliquid order belongs in the cross-provider
+ * `triggerOrders` bucket. Single source of truth for both the REST
+ * `getOrders` path (`HlFrontendOpenOrder` payload) and the `orderUpdates`
+ * WS handler (`HlOrderDetail.order`, a strict subset).
+ *
+ * Authoritative signals, in order:
+ *   1. `isTrigger` — REST-only boolean Hyperliquid sets on
+ *      `frontendOpenOrders`. Definitive when present.
+ *   2. `isPositionTpsl` — REST-only flag for TP/SL legs attached to a
+ *      position.
+ *   3. `triggerCondition !== 'N/A'` — present on both REST and WS payloads.
+ *      Non-trigger orders carry the literal `'N/A'`.
+ *   4. `triggerPx` non-null and non-zero — present on both. The reliable
+ *      trigger signal on the WS wire when `orderType` lies (HL pushes
+ *      `'Limit'` for a freshly-placed TP/SL until REST refetch lands the
+ *      corrected type).
+ *   5. `orderType` — final fall-back via `isTriggerType`.
+ * @public
+ */
+export const isTriggerOrder = (
+  o: HlFrontendOpenOrder | HlOrderDetail['order']
+): boolean => {
+  if ('isTrigger' in o && o.isTrigger === true) {
+    return true
+  }
+  if ('isPositionTpsl' in o && o.isPositionTpsl === true) {
+    return true
+  }
+  if (o.triggerCondition && o.triggerCondition !== 'N/A') {
+    return true
+  }
+  if (
+    o.triggerPx != null &&
+    o.triggerPx !== '' &&
+    parseFloat(o.triggerPx) > 0
+  ) {
+    return true
+  }
+  return isTriggerType(mapOrderType(o.orderType))
+}
+
+/** @public */
+export const mapOpenOrder = (
+  o: HlFrontendOpenOrder,
+  market: MarketDisplay
+): OpenOrder => ({
+  orderId: String(o.oid),
+  market,
+  side: o.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
+  type: mapOrderType(o.orderType),
+  size: o.sz,
+  price: o.limitPx,
+  filledSize: o.origSz
+    ? (parseFloat(o.origSz) - parseFloat(o.sz)).toString()
+    : '0',
+  reduceOnly: o.reduceOnly ?? false,
+  label: o.isTrigger ? o.triggerCondition : undefined,
+  createdAt: new Date(o.timestamp).toISOString(),
+})
+
+/** @public */
+export const mapTriggerOrder = (
+  o: HlFrontendOpenOrder,
+  market: MarketDisplay
+): TriggerOrder => {
+  const type = mapOrderType(o.orderType)
+  const isLimit =
+    type === OrderType.TAKE_PROFIT_LIMIT || type === OrderType.STOP_LIMIT
+  return {
+    orderId: String(o.oid),
+    market,
+    type,
+    size: o.sz,
+    triggerPrice: o.triggerPx,
+    ...(isLimit ? { limitPrice: o.limitPx } : {}),
+    label: o.triggerCondition,
+    createdAt: new Date(o.timestamp).toISOString(),
+  }
+}
+
+/** @public */
+export const mapOrderStatus = (status: string): OrderStatus => {
+  switch (status) {
+    case 'open':
+    case 'resting':
+      return OrderStatus.OPEN
+    case 'filled':
+      return OrderStatus.FILLED
+    case 'canceled':
+    case 'cancelled':
+      return OrderStatus.CANCELLED
+    case 'rejected':
+      return OrderStatus.REJECTED
+    case 'triggered':
+      return OrderStatus.TRIGGERED
+    case 'marginCanceled':
+      return OrderStatus.CANCELLED
+    default:
+      return OrderStatus.PENDING
+  }
+}
+
+/**
+ * Map a raw Hyperliquid order status to a short English sentence
+ * describing *why* the order ended in a terminal non-FILLED state. Bare
+ * `canceled`/`cancelled`/`rejected` carry no actionable detail and
+ * return `undefined`; so do non-terminal and unknown values.
+ * @public
+ */
+export const mapStatusReason = (status: string): string | undefined => {
+  switch (status) {
+    case 'iocCanceled':
+      return 'Order cancelled: not enough liquidity to fill immediately.'
+    case 'reduceOnlyCanceled':
+      return 'Order cancelled: would not reduce your position.'
+    case 'marginCanceled':
+      return 'Order cancelled: insufficient margin.'
+    case 'liquidatedCanceled':
+      return 'Order cancelled: account was liquidated.'
+    case 'siblingFilledCanceled':
+      return 'Order cancelled: sibling OCO order filled first.'
+    case 'selfTradeCanceled':
+      return 'Order cancelled: would self-trade against your own resting order.'
+    case 'tickRejected':
+      return 'Order rejected: price did not match the tick size.'
+    case 'minTradeNtlRejected':
+      return 'Order rejected: notional value below the minimum trade size.'
+    case 'delistedRejected':
+      return 'Order rejected: market has been delisted.'
+    default:
+      return undefined
+  }
+}
+
+const mapTimeInForce = (tif: string | undefined): TimeInForce | undefined => {
+  switch (tif) {
+    case 'Gtc':
+      return TimeInForce.GTC
+    case 'Ioc':
+      return TimeInForce.IOC
+    case 'Alo':
+      return TimeInForce.POST_ONLY
+    default:
+      return undefined
+  }
+}
+
+/** @public */
+export const mapOrder = (
+  detail: HlOrderDetail,
+  market: MarketDisplay
+): Order => {
+  const o = detail.order
+  const filled = parseFloat(o.origSz) - parseFloat(o.sz)
+
+  return {
+    orderId: String(o.oid),
+    market,
+    side: o.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
+    type: mapOrderType(o.orderType),
+    price: o.limitPx,
+    originalSize: o.origSz,
+    remainingSize: o.sz,
+    filledSize: filled.toString(),
+    timeInForce: mapTimeInForce(o.tif ?? undefined),
+    reduceOnly: o.reduceOnly ?? undefined,
+    isTrigger: o.triggerCondition !== undefined && o.triggerCondition !== 'N/A',
+    triggerPrice: o.triggerPx ?? undefined,
+    status: mapOrderStatus(detail.status),
+    statusReason: mapStatusReason(detail.status),
+    createdAt: new Date(o.timestamp).toISOString(),
+    updatedAt: new Date(detail.statusTimestamp).toISOString(),
+  }
+}

package/src/utils/mapPosition.ts

@@ -0,0 +1,40 @@
+import type { MarketDisplay, Position } from '@lifi/perps-types'
+import { MarginMode, PositionSide } from '@lifi/perps-types'
+import type { HlAssetPosition } from '../types/index.js'
+
+/**
+ * True when the assetPosition has non-zero size. Hyperliquid keeps zero-size
+ * rows in clearinghouse states after a close; both the REST and WS positions
+ * paths drop them so a close surfaces as absence from the open set.
+ * @public
+ */
+export const isOpenAssetPosition = (ap: HlAssetPosition): boolean =>
+  Number.parseFloat(ap.position.szi) !== 0
+
+/** @public */
+export const mapPosition = (
+  ap: HlAssetPosition,
+  market: MarketDisplay
+): Position => {
+  const pos = ap.position
+  const szi = parseFloat(pos.szi)
+
+  return {
+    market,
+    side: szi >= 0 ? PositionSide.LONG : PositionSide.SHORT,
+    size: Math.abs(szi).toString(),
+    entryPrice: pos.entryPx ?? '0',
+    markPrice:
+      pos.positionValue && szi !== 0
+        ? (parseFloat(pos.positionValue) / Math.abs(szi)).toString()
+        : '0',
+    liquidationPrice: pos.liquidationPx ?? '0',
+    unrealizedPnl: pos.unrealizedPnl,
+    leverage: ap.position.leverage.value,
+    marginUsed: pos.marginUsed,
+    marginMode:
+      ap.position.leverage.type === 'cross'
+        ? MarginMode.CROSS
+        : MarginMode.ISOLATED,
+  }
+}

package/src/utils/marketDisplay.ts

@@ -0,0 +1,38 @@
+import type { Asset, Market } from '@lifi/perps-types'
+import {
+  MAIN_DEX_NAME,
+  MAIN_MARKET_ID,
+  PROVIDER_KEY,
+  SPOT_MARKET_ID,
+} from '../constants.js'
+
+/**
+ * Synthesise the {@link Asset} for a Hyperliquid wire coin. `id` and `logoURI`
+ * keep the raw coin — the logo CDN is keyed by it, HIP-3 `dex:` prefix
+ * included. `displaySymbol` drops the prefix: the category is carried by
+ * `categoryId`, never by the display string.
+ * @public
+ */
+export const coinAsset = (coin: string): Asset => ({
+  providerId: PROVIDER_KEY,
+  id: coin,
+  displaySymbol: coin.includes(':') ? coin.slice(coin.indexOf(':') + 1) : coin,
+  logoURI: `https://app.hyperliquid.xyz/coins/${coin}.svg`,
+})
+
+/**
+ * Distinct wire `dex` names to fan `clearinghouseState` / `frontendOpenOrders`
+ * reads across, derived from the backend market list. Spot is excluded (it has
+ * no clearinghouseState); the main perp dex maps to the empty string.
+ * @public
+ */
+export const perpsDexNames = (markets: readonly Market[]): string[] => {
+  const names = new Set<string>()
+  for (const m of markets) {
+    if (m.categoryId === SPOT_MARKET_ID) {
+      continue
+    }
+    names.add(m.categoryId === MAIN_MARKET_ID ? MAIN_DEX_NAME : m.categoryId)
+  }
+  return [...names]
+}

package/src/utils/orderFormatting.ts

@@ -0,0 +1,93 @@
+/**
+ * Hyperliquid order size and price formatting for exchange submission.
+ *
+ * These encode Hyperliquid-specific order submission rules. Getting size/price
+ * formatting wrong causes rejected orders.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size
+ */
+
+import Big from 'big.js'
+
+/**
+ * Max combined decimals (size + price) enforced by Hyperliquid.
+ * Perps: 6, Spot: 8
+ */
+const MAX_DECIMALS_PERPS = 6
+const MAX_DECIMALS_SPOT = 8
+
+function getMaxDecimals(market?: string): number {
+  return market === 'spot' ? MAX_DECIMALS_SPOT : MAX_DECIMALS_PERPS
+}
+
+/**
+ * Derive the maximum number of price decimal places for a given asset.
+ *
+ * @param szDecimals - The asset's szDecimals (from market meta)
+ * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
+ * @returns Maximum allowed price decimals
+ * @public
+ */
+export function getMaxPriceDecimals(
+  szDecimals: number,
+  market?: string
+): number {
+  return Math.max(0, getMaxDecimals(market) - szDecimals)
+}
+
+/**
+ * Format a size value for order submission.
+ *
+ * Per Hyperliquid docs (tick-and-lot-size):
+ * - Size must be rounded to the asset's szDecimals
+ * - Trailing zeroes must be removed for signing
+ *
+ * @param size - The size value to format
+ * @param szDecimals - Number of decimal places allowed for this asset (from meta)
+ * @returns Size as a string with correct precision, no trailing zeros
+ * @public
+ */
+export function formatOrderSize(size: number, szDecimals: number): string {
+  // Big.roundDown truncates toward zero — never round a size up, it could
+  // exceed available balance. Exact decimal arithmetic: flooring the float
+  // product dropped a lot step (0.29 * 100 === 28.999999999999996).
+  const truncated = new Big(size).round(szDecimals, Big.roundDown)
+  // toFixed() with no dp always emits plain notation; eq(0) guards '-0'
+  return truncated.eq(0) ? '0' : truncated.toFixed()
+}
+
+/**
+ * Format a price value for order submission.
+ *
+ * Per Hyperliquid docs (tick-and-lot-size):
+ * - Maximum 5 significant figures
+ * - Max decimals = MAX_DECIMALS - szDecimals (6 for perps, 8 for spot)
+ * - Integer prices always allowed regardless of significant figures
+ * - Trailing zeroes must be removed for signing
+ *
+ * Rounding is half-up (away from zero at exact halfway) on the true decimal
+ * value, not on the binary float — (1.005).toFixed(2) would give '1.00'.
+ *
+ * @param price - The price value to format
+ * @param szDecimals - The asset's szDecimals (affects max price decimals)
+ * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
+ * @returns Price as a string with correct precision, no trailing zeros
+ * @public
+ */
+export function formatOrderPrice(
+  price: number,
+  szDecimals: number,
+  market?: string
+): string {
+  const maxPriceDecimals = getMaxPriceDecimals(szDecimals, market)
+
+  let rounded = new Big(price).round(maxPriceDecimals, Big.roundHalfUp)
+
+  // Integer prices bypass the 5 sig-fig rule; prec() is a no-op below 6 sig figs
+  if (!rounded.mod(1).eq(0)) {
+    rounded = rounded.prec(5, Big.roundHalfUp)
+  }
+
+  // toFixed() with no dp always emits plain notation; eq(0) guards '-0'
+  return rounded.eq(0) ? '0' : rounded.toFixed()
+}

package/src/utils/priceStepToAggregation.ts

@@ -0,0 +1,58 @@
+/** Significant-figure bounds Hyperliquid's `l2Book` accepts; `undefined` is full precision. */
+const HL_MIN_SIG_FIGS = 2
+const HL_MAX_SIG_FIGS = 5
+/** Mantissa sub-steps HL honours, but only when `nSigFigs === 5`. */
+const HL_MANTISSA_VALUES: readonly [number, ...number[]] = [1, 2, 5]
+
+/** Snap a leading-digit ratio to the nearest mantissa HL accepts (1, 2 or 5). */
+function snapToMantissa(ratio: number): number {
+  let closest = HL_MANTISSA_VALUES[0]
+  for (const m of HL_MANTISSA_VALUES) {
+    if (Math.abs(ratio - m) < Math.abs(ratio - closest)) {
+      closest = m
+    }
+  }
+  return closest
+}
+
+/**
+ * Map a desired price `step` to Hyperliquid's server-side aggregation hint
+ * `(nSigFigs, mantissa)` against the order of magnitude of `referencePrice`
+ * (the market's mark price gives the digit count). HL buckets the book to
+ * `nSigFigs` significant figures, so the figures resolving a price to `step`
+ * granularity are `floor(log10(referencePrice)) - floor(log10(step)) + 1`.
+ *
+ * Returns `{}` (full precision) when the step is finer than HL's 5-sig-fig
+ * grid or the inputs are unusable; clamps to {@link HL_MIN_SIG_FIGS} when the
+ * step is coarser than HL's lowest granularity. `mantissa` is emitted only for
+ * a non-power-of-ten step that lands on the 5-sig-fig grid, since HL ignores
+ * it below `nSigFigs === 5`.
+ *
+ * @public
+ */
+export function priceStepToAggregation(
+  step: number,
+  referencePrice: number
+): { nSigFigs?: number; mantissa?: number } {
+  if (!Number.isFinite(step) || step <= 0) {
+    return {}
+  }
+  if (!Number.isFinite(referencePrice) || referencePrice <= 0) {
+    return {}
+  }
+
+  const stepExp = Math.floor(Math.log10(step))
+  const priceExp = Math.floor(Math.log10(referencePrice))
+  const nSigFigs = priceExp - stepExp + 1
+
+  if (nSigFigs > HL_MAX_SIG_FIGS) {
+    return {}
+  }
+
+  const clamped = Math.max(HL_MIN_SIG_FIGS, nSigFigs)
+  const mantissa = snapToMantissa(step / 10 ** stepExp)
+  if (clamped === HL_MAX_SIG_FIGS && mantissa !== 1) {
+    return { nSigFigs: clamped, mantissa }
+  }
+  return { nSigFigs: clamped }
+}

package/src/utils/spotBalance.ts

@@ -0,0 +1,51 @@
+import { stringToFloat } from '@lifi/perps-sdk'
+import type { Asset, Balance, Market } from '@lifi/perps-types'
+import { SPOT_MARKET_ID } from '../constants.js'
+import type { HlSpotBalance } from '../types/index.js'
+import { coinAsset } from './marketDisplay.js'
+
+/**
+ * USD price keyed by spot token index: each spot market's live USD price
+ * (from `priceByMarketId`, keyed by `Market.id`) under its base-asset id, and
+ * every market's quote-asset id at $1. A spot market absent from
+ * `priceByMarketId` values its token at 0.
+ */
+export const spotPriceById = (
+  markets: readonly Market[],
+  priceByMarketId: ReadonlyMap<string, number>
+): Map<string, number> => {
+  const map = new Map<string, number>()
+  for (const m of markets) {
+    if (m.categoryId === SPOT_MARKET_ID) {
+      map.set(m.baseAsset.id, priceByMarketId.get(m.id) ?? 0)
+    }
+  }
+  for (const m of markets) {
+    if (!map.has(m.quoteAsset.id)) {
+      map.set(m.quoteAsset.id, 1)
+    }
+  }
+  return map
+}
+
+/**
+ * The held spot {@link Asset} for an HL balance: the venue token index
+ * (`b.token`) as `Asset.id` — equal to that token's spot `Market.baseAsset.id`
+ * — with display fields derived from the coin.
+ */
+export const spotAssetFromToken = (b: HlSpotBalance): Asset => ({
+  ...coinAsset(b.coin),
+  id: String(b.token),
+})
+
+/** Assemble a typed spot {@link Balance} from its resolved asset and raw size. */
+export const spotBalance = (
+  asset: Asset,
+  total: string,
+  priceById: Map<string, number>
+): Balance => ({
+  categoryId: SPOT_MARKET_ID,
+  asset,
+  units: total,
+  valueUsd: (stringToFloat(total) * (priceById.get(asset.id) ?? 0)).toString(),
+})