@lifi/perps-types 0.1.1-alpha.8 → 0.2.0-alpha.0

package/src/asset.ts

@@ -0,0 +1,88 @@
+export interface FundingInfo {
+  rate: string
+  nextFundingTime: number
+}
+
+export interface AssetIdentity {
+  assetId: string // provider's canonical identity: "BTC", "xyz:PURR", "@142"
+  market: string // market category from /providers.markets: "hyperliquid", "xyz", "spot"
+}
+
+export interface Asset extends AssetIdentity {
+  displaySymbol: string // UI base name: "BTC", "PURR"; spot keeps full pair: "PURR/USDC"
+  displayQuote: string | null // quote asset for perps: "USDC", "USDH"; null for spot
+  displayName?: string // future: "Bitcoin", "Ethereum"
+  logoURI: string
+  szDecimals: number
+  maxLeverage: number
+  onlyIsolated: boolean
+  isMarginCollateral?: boolean
+  funding: FundingInfo
+  openInterest?: string
+  volume24h?: string
+  prevDayPrice?: string
+  markPrice: string
+}
+
+export type AssetDisplay = Pick<
+  Asset,
+  'assetId' | 'market' | 'displaySymbol' | 'displayQuote'
+>
+
+export interface AssetPrice {
+  assetId: string
+  price: string
+}
+
+export interface AssetsResponse {
+  assets: Asset[]
+}
+
+export interface PricesResponse {
+  prices: AssetPrice[]
+}
+
+export interface Candle {
+  t: number
+  o: string
+  h: string
+  l: string
+  c: string
+  v: string
+}
+
+export interface OhlcvResponse {
+  provider: string
+  assetId: string
+  interval: string
+  candles: Candle[]
+}
+
+export type OhlcvInterval =
+  | '1m'
+  | '3m'
+  | '5m'
+  | '15m'
+  | '30m'
+  | '1h'
+  | '2h'
+  | '4h'
+  | '8h'
+  | '12h'
+  | '1d'
+  | '3d'
+  | '1w'
+  | '1M'
+
+export interface OrderbookLevel {
+  price: string
+  size: string
+}
+
+export interface OrderbookResponse {
+  provider: string
+  assetId: string
+  bids: OrderbookLevel[]
+  asks: OrderbookLevel[]
+  timestamp: number
+}

package/src/enums.ts

@@ -5,6 +5,7 @@ export enum PerpsErrorCode {
   ValidationError = 2002,
   TimeoutError = 2003,
   ThirdPartyError = 2004,
+  SDKError = 2005,
 
   // Auth errors (2010-2019)
   SignatureInvalid = 2010,
@@ -17,6 +18,7 @@ export enum PerpsErrorCode {
   MarketNotFound = 2023,
   OrderNotFound = 2024,
   PositionNotFound = 2025,
+  AccountNotFound = 2026,
 
   // Nonce errors (2040-2049)
   InvalidNonce = 2040,
@@ -38,6 +40,11 @@ export enum OrderSide {
 export enum OrderType {
   MARKET = 'MARKET',
   LIMIT = 'LIMIT',
+  STOP_MARKET = 'STOP_MARKET',
+  STOP_LIMIT = 'STOP_LIMIT',
+  TAKE_PROFIT_MARKET = 'TAKE_PROFIT_MARKET',
+  TAKE_PROFIT_LIMIT = 'TAKE_PROFIT_LIMIT',
+  TRIGGER_ONLY = 'TRIGGER_ONLY',
 }
 
 export enum PositionSide {
@@ -68,18 +75,46 @@ export enum OrderStatus {
   TRIGGERED = 'TRIGGERED',
 }
 
-export enum HistoryItemStatus {
+export enum FillStatus {
   FILLED = 'FILLED',
   PARTIALLY_FILLED = 'PARTIALLY_FILLED',
   CANCELLED = 'CANCELLED',
   REJECTED = 'REJECTED',
 }
 
-export enum OrderActionType {
-  UPDATE_LEVERAGE = 'updateLeverage',
+export enum LiquidityRole {
+  MAKER = 'maker',
+  TAKER = 'taker',
+}
+
+export enum ActionType {
+  APPROVE_AGENT = 'approveAgent',
+  APPROVE_BUILDER_FEE = 'approveBuilderFee',
+  /**
+   * Generic account-level operating mode (e.g. Hyperliquid abstraction
+   * variants, Lighter UTA / Simple). HL maps it to the appropriate
+   * EIP-712 typed-data builder internally.
+   */
+  ACCOUNT_MODE = 'accountMode',
+  /**
+   * Generic account-level fee/latency tier (e.g. Lighter standard /
+   * premium). Providers that have no tiering (Hyperliquid) omit this
+   * action from their descriptor list.
+   */
+  ACCOUNT_TYPE = 'accountType',
+  SEND_ASSET = 'sendAsset',
+  WITHDRAWAL = 'withdrawal',
+  TRANSFER = 'transfer',
   PLACE_ORDER = 'placeOrder',
   PLACE_TRIGGER_ORDER = 'placeTriggerOrder',
   CANCEL_ORDER = 'cancelOrder',
+  CANCEL_ALL_ORDERS = 'cancelAllOrders',
+  MODIFY_ORDER = 'modifyOrder',
+  UPDATE_LEVERAGE = 'updateLeverage',
+  UPDATE_POSITION_MARGIN = 'updatePositionMargin',
+  REGISTER_API_KEY = 'registerApiKey',
+  APPROVE_READ_ONLY_TOKEN = 'approveReadOnlyToken',
+  DEPOSIT = 'deposit',
 }
 
 export enum TriggerCondition {
@@ -97,3 +132,57 @@ export enum TriggerOrderStatus {
   TRIGGERED = 'TRIGGERED',
   CANCELLED = 'CANCELLED',
 }
+
+export enum ActivityType {
+  DEPOSIT = 'DEPOSIT',
+  WITHDRAWAL = 'WITHDRAWAL',
+  LIQUIDATION = 'LIQUIDATION',
+  FUNDING = 'FUNDING',
+  TRANSFER = 'TRANSFER',
+}
+
+export enum FillClassification {
+  OPENED_LONG = 'Opened Long',
+  OPENED_SHORT = 'Opened Short',
+  INCREASED_LONG = 'Increased Long',
+  INCREASED_SHORT = 'Increased Short',
+  REDUCED_LONG = 'Reduced Long',
+  REDUCED_SHORT = 'Reduced Short',
+  CLOSED_LONG = 'Closed Long',
+  CLOSED_SHORT = 'Closed Short',
+  SWITCHED_LONG = 'Switched Long',
+  SWITCHED_SHORT = 'Switched Short',
+  SPOT_BUY = 'Spot Buy',
+  SPOT_SELL = 'Spot Sell',
+}
+
+export enum LiquidationClassification {
+  LIQUIDATED = 'Liquidated',
+}
+
+export enum FundingClassification {
+  FUNDING = 'Funding',
+}
+
+export enum TransferClassification {
+  DEPOSIT = 'Deposit',
+  WITHDRAWAL = 'Withdrawal',
+}
+
+export type ActivityClassification =
+  | FillClassification
+  | LiquidationClassification
+  | FundingClassification
+  | TransferClassification
+
+export enum PerpsSigner {
+  USER = 'USER',
+  AGENT = 'AGENT',
+  API_KEY = 'API_KEY',
+}
+
+export enum SigningMethod {
+  EIP712 = 'eip712',
+  WASM_BLOB = 'wasmBlob',
+  EVM_TX = 'evmTx',
+}

package/src/index.ts

@@ -1,9 +1,8 @@
 export * from './typedData.js'
 export * from './enums.js'
-export * from './market.js'
-export * from './authorization.js'
+export * from './providers.js'
+export * from './asset.js'
+export * from './action.js'
 export * from './account.js'
-export * from './trading.js'
-export * from './withdrawal.js'
 export * from './errors.js'
 export * from './subscriptions.js'

package/src/providers/_shared/fillClassification.ts

@@ -0,0 +1,50 @@
+import { FillClassification } from '../../enums.js'
+
+/**
+ * Classify a perpetual fill into the Open/Close/Increase/Reduce/Switch
+ * taxonomy from `FillClassification`.
+ *
+ * @param startPosition Signed position held BEFORE this fill (`> 0` long,
+ *   `< 0` short, `0` flat).
+ * @param side Hyperliquid-style: `'B'` for buy, anything else for sell.
+ * @param sz Unsigned fill size, parsed with `parseFloat`.
+ */
+export function classifyFillFromPosition(
+  startPosition: string,
+  side: string,
+  sz: string
+): FillClassification {
+  const start = parseFloat(startPosition)
+  const delta = side === 'B' ? parseFloat(sz) : -parseFloat(sz)
+  const end = start + delta
+
+  if (start === 0) {
+    return end > 0
+      ? FillClassification.OPENED_LONG
+      : FillClassification.OPENED_SHORT
+  }
+
+  if (start > 0) {
+    if (end === 0) {
+      return FillClassification.CLOSED_LONG
+    }
+    if (end < 0) {
+      return FillClassification.SWITCHED_SHORT
+    }
+    if (end > start) {
+      return FillClassification.INCREASED_LONG
+    }
+    return FillClassification.REDUCED_LONG
+  }
+
+  if (end === 0) {
+    return FillClassification.CLOSED_SHORT
+  }
+  if (end > 0) {
+    return FillClassification.SWITCHED_LONG
+  }
+  if (end < start) {
+    return FillClassification.INCREASED_SHORT
+  }
+  return FillClassification.REDUCED_SHORT
+}

package/src/providers/hyperliquid/assetId.ts

@@ -1,26 +1,32 @@
+/** Spot asset IDs use the @pairIndex format (e.g. "@230"). */
+export const assetIsSpot = (assetId: string): boolean => assetId.startsWith('@')
+
 /**
- * Calculate the asset ID for a given DEX index and asset index.
+ * Calculate the asset ID for a given provider index and asset index.
  *
- * Main DEX (dex = ''): assetId = indexInDex
- * HIP-3 DEXes (dex = 'xyz'): assetId = 100_000 + perpDexIndex * 10_000 + indexInDex
+ * Main provider (provider = ''): assetId = indexInProvider
+ * HIP-3 providers (provider = 'xyz'): assetId = 100_000 + perpDexIndex * 10_000 + indexInProvider
  */
 export const calculateAssetId = (
-  dexIndex: number,
-  indexInDex: number
+  providerIndex: number,
+  indexInProvider: number
 ): number => {
-  if (dexIndex === 0) {
-    return indexInDex
+  if (providerIndex === 0) {
+    return indexInProvider
   }
-  return 100_000 + dexIndex * 10_000 + indexInDex
+  return 100_000 + providerIndex * 10_000 + indexInProvider
 }
 
 /**
- * Get the DEX index from the given list of dex names.
+ * Get the provider index from the given list of provider names.
  */
-export const getDexIndex = (dex: string, dexNames: string[]): number => {
-  const index = dexNames.indexOf(dex)
+export const getProviderIndex = (
+  provider: string,
+  providerNames: string[]
+): number => {
+  const index = providerNames.indexOf(provider)
   if (index === -1) {
-    throw new Error(`Unknown sub-dex: ${dex}`)
+    throw new Error(`Unknown sub-provider: ${provider}`)
   }
   return index
 }

package/src/providers/hyperliquid/mappers/_market.ts

@@ -0,0 +1,21 @@
+/**
+ * Derive the `AssetIdentity.market` value (a `/providers.markets[].id`) from
+ * a Hyperliquid `assetId`:
+ * - `"BTC"`      → main USDC perp dex → `"hyperliquid"`
+ * - `"xyz:PURR"` → HIP-3 sub-dex      → `"xyz"`
+ * - `"@142"`     → spot pair          → `"spot"`
+ *
+ * Must stay in lockstep with `lifi-perps-backend`'s `toProviderMarketId` /
+ * `buildAssetMarketLookup` — they define the same `/providers.markets[].id`
+ * taxonomy on the wire.
+ */
+export const deriveMarket = (assetId: string): string => {
+  if (assetId.startsWith('@')) {
+    return 'spot'
+  }
+  const colon = assetId.indexOf(':')
+  if (colon > 0) {
+    return assetId.slice(0, colon)
+  }
+  return 'hyperliquid'
+}

package/src/providers/hyperliquid/mappers/activity.ts

@@ -0,0 +1,169 @@
+import { ActivityType } from '../../../enums.js'
+import type {
+  ActivityItem,
+  DepositActivity,
+  WithdrawalActivity,
+  LiquidationActivity,
+  FundingActivity,
+  TransferActivity,
+} from '../../../account.js'
+import { isSendAssetDelta, isSpotTransferDelta } from '../types.js'
+import type { HlLedgerUpdate, HlFundingUpdate } from '../types.js'
+import { deriveMarket } from './_market.js'
+
+/**
+ * Map a Hyperliquid non-funding ledger entry to an ActivityItem.
+ *
+ * Direction for `spotTransfer` and `sendAsset` is derived from
+ * `queriedAddress` matching the delta's `user` (OUT) or `destination` (IN).
+ * Returns null for unsupported delta types and for same-user `sendAsset`
+ * dex moves (where `user === destination === queriedAddress`).
+ */
+export const mapLedgerEntry = (
+  entry: HlLedgerUpdate,
+  providerKey: string,
+  queriedAddress: string
+): ActivityItem | null => {
+  const { delta } = entry
+  const base = {
+    id: entry.hash,
+    provider: providerKey,
+    timestamp: new Date(entry.time).toISOString(),
+  }
+
+  // Handled before the switch: the catch-all arm of `HlLedgerDelta` is a
+  // structural supertype of the concrete delta, so a `switch (delta.type)`
+  // cannot narrow off the discriminant. The user-defined type guard does.
+  if (isSpotTransferDelta(delta)) {
+    const queried = queriedAddress.toLowerCase()
+    const sender = delta.user.toLowerCase()
+    const recipient = delta.destination.toLowerCase()
+    const direction: 'IN' | 'OUT' = queried === sender ? 'OUT' : 'IN'
+    const counterpartyAddress = direction === 'OUT' ? recipient : sender
+    const meta: Record<string, unknown> = {
+      transferType: 'spotTransfer',
+    }
+    if (delta.usdcValue !== undefined) {
+      meta.usdcValue = delta.usdcValue
+    }
+    if (delta.fee !== undefined) {
+      meta.fee = delta.fee
+    }
+    if (delta.nativeTokenFee !== undefined) {
+      meta.nativeTokenFee = delta.nativeTokenFee
+    }
+    if (delta.nonce !== undefined) {
+      meta.nonce = delta.nonce
+    }
+    return {
+      ...base,
+      type: ActivityType.TRANSFER,
+      direction,
+      counterpartyAddress,
+      asset: delta.token,
+      amount: delta.amount,
+      meta,
+    } satisfies TransferActivity
+  }
+
+  // `sendAsset` (wire `type === 'send'`) covers cross-user transfers
+  // (modelled as TRANSFER) and same-user dex moves (returned as null —
+  // overloading TRANSFER for those would lie about direction). Pre-switch
+  // narrowing for the same reason as spotTransfer.
+  if (isSendAssetDelta(delta)) {
+    const queried = queriedAddress.toLowerCase()
+    const sender = delta.user.toLowerCase()
+    const recipient = delta.destination.toLowerCase()
+
+    if (sender === recipient && sender === queried) {
+      return null
+    }
+
+    const direction: 'IN' | 'OUT' = queried === sender ? 'OUT' : 'IN'
+    const counterpartyAddress = direction === 'OUT' ? recipient : sender
+    const meta: Record<string, unknown> = {
+      transferType: 'sendAsset',
+      sourceDex: delta.sourceDex,
+      destinationDex: delta.destinationDex,
+      usdcValue: delta.usdcValue,
+      fee: delta.fee,
+      nativeTokenFee: delta.nativeTokenFee,
+      feeToken: delta.feeToken,
+      nonce: delta.nonce,
+    }
+    return {
+      ...base,
+      type: ActivityType.TRANSFER,
+      direction,
+      counterpartyAddress,
+      asset: delta.token,
+      amount: delta.amount,
+      meta,
+    } satisfies TransferActivity
+  }
+
+  switch (delta.type) {
+    case 'deposit':
+      return {
+        ...base,
+        type: ActivityType.DEPOSIT,
+        amount: delta.usdc ?? '0',
+      } satisfies DepositActivity
+
+    case 'withdraw':
+      return {
+        ...base,
+        type: ActivityType.WITHDRAWAL,
+        amount: delta.usdc ?? '0',
+        fee: (delta as { fee?: string }).fee ?? '0',
+      } satisfies WithdrawalActivity
+
+    case 'liquidation': {
+      const d = delta as unknown as {
+        type: string
+        liquidatedNtlPos: string
+        accountValue: string
+        leverageType: string
+        liquidatedPositions?: { coin: string; szi: string }[]
+      }
+      return {
+        ...base,
+        type: ActivityType.LIQUIDATION,
+        liquidatedNotionalPosition: d.liquidatedNtlPos,
+        accountValue: d.accountValue,
+        leverageType: d.leverageType,
+        liquidatedPositions: (d.liquidatedPositions ?? []).map((p) => ({
+          asset: {
+            assetId: p.coin,
+            market: deriveMarket(p.coin),
+            displaySymbol: p.coin,
+            displayQuote: null,
+          },
+          size: p.szi,
+        })),
+      } satisfies LiquidationActivity
+    }
+
+    default:
+      return null
+  }
+}
+
+export const mapFundingActivity = (
+  entry: HlFundingUpdate,
+  providerKey: string
+): FundingActivity => ({
+  id: entry.hash,
+  provider: providerKey,
+  timestamp: new Date(entry.time).toISOString(),
+  type: ActivityType.FUNDING,
+  asset: {
+    assetId: entry.delta.coin,
+    market: deriveMarket(entry.delta.coin),
+    displaySymbol: entry.delta.coin,
+    displayQuote: null,
+  },
+  amount: entry.delta.usdc,
+  positionSize: entry.delta.szi,
+  fundingRate: entry.delta.fundingRate,
+})

package/src/providers/hyperliquid/mappers/{market.ts → asset.ts}

@@ -1,26 +1,23 @@
-import type { Market } from '../../../market.js'
-import { calculateAssetId } from '../assetId.js'
+import type { Asset } from '../../../asset.js'
 import type { HlAssetCtx, HlUniverseItem } from '../types.js'
+import { deriveMarket } from './_market.js'
 
 const NEXT_FUNDING_INTERVAL_MS = 60 * 60 * 1000 // 1 hour
 
-export const mapMarket = (
+export const mapAsset = (
   universe: HlUniverseItem,
-  assetCtx: HlAssetCtx,
-  dexIndex: number,
-  indexInDex: number,
-  dexKey: string
-): Market => {
+  assetCtx: HlAssetCtx
+): Asset => {
   const now = Date.now()
   const nextFundingTime =
     Math.ceil(now / NEXT_FUNDING_INTERVAL_MS) * NEXT_FUNDING_INTERVAL_MS
 
   return {
-    symbol: universe.name,
-    name: universe.name,
+    assetId: universe.name,
+    market: deriveMarket(universe.name),
+    displaySymbol: universe.name,
+    displayQuote: null,
     logoURI: `https://app.hyperliquid.xyz/coins/${universe.name}.svg`,
-    assetId: calculateAssetId(dexIndex, indexInDex),
-    dex: dexKey,
     szDecimals: universe.szDecimals,
     maxLeverage: universe.maxLeverage,
     onlyIsolated: universe.onlyIsolated === true,
@@ -30,6 +27,7 @@ export const mapMarket = (
     },
     openInterest: assetCtx.openInterest,
     volume24h: assetCtx.dayNtlVlm,
+    prevDayPrice: assetCtx.prevDayPx,
     markPrice: assetCtx.markPx,
   }
 }

package/src/providers/hyperliquid/mappers/fill.ts

@@ -0,0 +1,41 @@
+import {
+  FillClassification,
+  FillStatus,
+  LiquidityRole,
+  OrderSide,
+  OrderType,
+} from '../../../enums.js'
+import type { Fill } from '../../../account.js'
+import type { HlUserFill } from '../types.js'
+import { assetIsSpot } from '../assetId.js'
+import { classifyFillFromPosition } from '../../_shared/fillClassification.js'
+import { deriveMarket } from './_market.js'
+
+export { classifyFillFromPosition }
+
+export const mapFill = (fill: HlUserFill): Fill => ({
+  id: String(fill.tid),
+  orderId: String(fill.oid),
+  asset: {
+    assetId: fill.coin,
+    market: deriveMarket(fill.coin),
+    displaySymbol: fill.coin,
+    displayQuote: null,
+  },
+  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,
+  realizedPnl: fill.closedPnl === '0' ? null : fill.closedPnl,
+  startPosition: fill.startPosition,
+  classification: assetIsSpot(fill.coin)
+    ? fill.side === 'B'
+      ? FillClassification.SPOT_BUY
+      : FillClassification.SPOT_SELL
+    : classifyFillFromPosition(fill.startPosition, fill.side, fill.sz),
+  createdAt: new Date(fill.time).toISOString(),
+})

package/src/providers/hyperliquid/mappers/index.ts

@@ -1,5 +1,11 @@
-export { resolveAssetIdFromLookup } from './shared.js'
-export { mapMarket } from './market.js'
-export { mapOpenOrder, mapOrder } from './order.js'
+export { mapAsset } from './asset.js'
+export {
+  isTriggerType,
+  mapOpenOrder,
+  mapOrder,
+  mapOrderType,
+  mapTriggerOrder,
+} from './order.js'
 export { mapPosition } from './position.js'
-export { mapHistoryItem } from './history.js'
+export { classifyFillFromPosition, mapFill } from './fill.js'
+export { mapLedgerEntry, mapFundingActivity } from './activity.js'