@kinetiq-research/markets-assets/src/normalize-asset-category.ts

Asset metadata (descriptions, oracle references) for Kinetiq markets

// Hyperliquid's concise-annotations endpoint returns a free-form string for
// each universe item's `category`. Normalize observed values to a narrow
// union. Unknown values fall back to `'stock'` so new listings still render
// somewhere sensible. Main Hyperliquid perps are not annotated and use the
// `isMainHyperliquid` flag to short-circuit to `'crypto'`.

export type AssetCategory =
  | 'commodity'
  | 'crypto'
  | 'currency'
  | 'index'
  | 'stock'

const ALIASES: Record<string, AssetCategory> = {
  commodities: 'commodity',
  commodity: 'commodity',
  crypto: 'crypto',
  currencies: 'currency',
  currency: 'currency',
  equities: 'stock',
  equity: 'stock',
  forex: 'currency',
  fx: 'currency',
  index: 'index',
  indexes: 'index',
  indices: 'index',
  stock: 'stock',
  stocks: 'stock',
}

export const normalizeAssetCategory = ({
  fallback = 'stock',
  isMainHyperliquid = false,
  raw,
}: {
  /**
   * Category for unknown/absent raw values. HIP-3 listings default to
   * `'stock'` (equities dominate them); spot tokens should pass `'crypto'` —
   * an unannotated or free-form-annotated spot token is still a crypto token.
   */
  fallback?: AssetCategory
  isMainHyperliquid?: boolean
  raw: string | undefined
}): AssetCategory => {
  if (isMainHyperliquid) {
    return 'crypto'
  }
  return ALIASES[raw?.toLowerCase() ?? ''] ?? fallback
}