@luxexchange/prices 1.0.0

package/.depcheckrc

@@ -0,0 +1,14 @@
+ignores: [
+    # Dependencies that depcheck incorrectly marks as unused
+    "typescript",
+    "@typescript/native-preview",
+    "depcheck",
+
+    # Internal packages / workspaces
+    "prices",
+    "@universe/prices",
+
+    # TODO: remove once used in tests
+    "@testing-library/react",
+    "@vitest/coverage-v8",
+  ]

package/.eslintrc.js

@@ -0,0 +1,20 @@
+module.exports = {
+  extends: ['@luxfi/eslint-config/lib'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+  },
+  overrides: [
+    {
+      files: ['*.ts', '*.tsx'],
+      rules: {
+        'no-relative-import-paths/no-relative-import-paths': [
+          'error',
+          {
+            allowSameFolder: false,
+            prefix: '@universe/prices',
+          },
+        ],
+      },
+    },
+  ],
+}

package/README.md

@@ -0,0 +1,3 @@
+# @universe/prices
+
+// TODO

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@luxexchange/prices",
+  "version": "1.0.0",
+  "dependencies": {
+    "@tanstack/react-query": "5.90.20",
+    "@uniswap/sdk-core": "7.10.1",
+    "@luxexchange/api": "^1.0.0",
+    "@luxexchange/websocket": "^1.0.0",
+    "@luxfi/utilities": "^1.0.0"
+  },
+  "peerDependencies": {
+    "react": "19.0.3"
+  },
+  "devDependencies": {
+    "@testing-library/react": "16.3.0",
+    "@types/node": "22.13.1",
+    "@typescript/native-preview": "7.0.0-dev.20260108.1",
+    "@luxfi/eslint-config": "^1.0.0",
+    "@vitest/coverage-v8": "3.2.1",
+    "depcheck": "1.4.7",
+    "eslint": "8.57.1",
+    "react": "19.0.3",
+    "typescript": "5.8.3",
+    "vitest": "3.2.1"
+  },
+  "scripts": {
+    "test": "nx test prices",
+    "test:coverage": "nx test:coverage prices",
+    "typecheck": "nx typecheck prices",
+    "typecheck:tsgo": "nx typecheck:tsgo prices",
+    "lint": "nx lint prices",
+    "lint:fix": "nx lint:fix prices",
+    "lint:biome": "nx lint:biome prices",
+    "lint:biome:fix": "nx lint:biome:fix prices",
+    "lint:eslint": "nx lint:eslint prices",
+    "lint:eslint:fix": "nx lint:eslint:fix prices",
+    "check:deps:usage": "nx check:deps:usage prices"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "main": "src/index.ts",
+  "private": false,
+  "sideEffects": false
+}

package/project.json

@@ -0,0 +1,26 @@
+{
+  "name": "@universe/prices",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "pkgs/prices/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "test": {
+      "command": "vitest run --passWithNoTests",
+      "options": { "cwd": "{projectRoot}" }
+    },
+    "test:coverage": {
+      "command": "vitest run --coverage --passWithNoTests",
+      "options": { "cwd": "{projectRoot}" }
+    },
+    "typecheck": {},
+    "typecheck:tsgo": {},
+    "lint:biome": {},
+    "lint:biome:fix": {},
+    "lint:eslint": {},
+    "lint:eslint:fix": {},
+    "lint": {},
+    "lint:fix": {},
+    "check:deps:usage": {}
+  }
+}

package/src/context/PriceServiceContext.test.tsx

@@ -0,0 +1,63 @@
+// @vitest-environment jsdom
+
+import type { QueryClient } from '@tanstack/react-query'
+import { renderHook } from '@testing-library/react'
+import { PriceServiceProvider, usePricesContext } from '@luxexchange/prices/src/context/PriceServiceContext'
+import type { TokenPriceMessage, TokenSubscriptionParams } from '@luxexchange/prices/src/types'
+import type { WebSocketClient } from '@luxexchange/websocket'
+import type { ReactNode } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+
+function createMockWsClient(): WebSocketClient<TokenSubscriptionParams, TokenPriceMessage['data']> {
+  return {
+    isConnected: vi.fn(() => false),
+    getConnectionStatus: vi.fn(() => 'disconnected' as const),
+    getConnectionId: vi.fn(() => null),
+    subscribe: vi.fn(() => vi.fn()),
+    onStatusChange: vi.fn(() => vi.fn()),
+    onConnectionEstablished: vi.fn(() => vi.fn()),
+  }
+}
+
+function createMockQueryClient(): QueryClient {
+  return { setQueryData: vi.fn() } as unknown as QueryClient
+}
+
+describe('PriceServiceContext', () => {
+  it('usePricesContext throws when used outside PriceServiceProvider', () => {
+    expect(() => {
+      renderHook(() => usePricesContext())
+    }).toThrow('usePricesContext must be used within a PriceServiceProvider')
+  })
+
+  it('usePricesContext returns wsClient and queryClient when inside PriceServiceProvider', () => {
+    const mockWsClient = createMockWsClient()
+    const mockQueryClient = createMockQueryClient()
+
+    const wrapper = ({ children }: { children: ReactNode }): ReactNode => (
+      <PriceServiceProvider wsClient={mockWsClient} queryClient={mockQueryClient}>
+        {children}
+      </PriceServiceProvider>
+    )
+
+    const { result } = renderHook(() => usePricesContext(), { wrapper })
+
+    expect(result.current.wsClient).toBe(mockWsClient)
+    expect(result.current.queryClient).toBe(mockQueryClient)
+  })
+
+  it('PriceServiceProvider renders children', () => {
+    const mockWsClient = createMockWsClient()
+    const mockQueryClient = createMockQueryClient()
+
+    const wrapper = ({ children }: { children: ReactNode }): ReactNode => (
+      <PriceServiceProvider wsClient={mockWsClient} queryClient={mockQueryClient}>
+        {children}
+      </PriceServiceProvider>
+    )
+
+    const { result } = renderHook(() => 'rendered', { wrapper })
+
+    expect(result.current).toBe('rendered')
+  })
+})

package/src/context/PriceServiceContext.tsx

@@ -0,0 +1,31 @@
+import type { QueryClient } from '@tanstack/react-query'
+import type { TokenPriceMessage, TokenSubscriptionParams } from '@luxexchange/prices/src/types'
+import type { WebSocketClient } from '@luxexchange/websocket'
+import { createContext, type ReactElement, type ReactNode, useContext } from 'react'
+
+interface PricesContextValue {
+  wsClient: WebSocketClient<TokenSubscriptionParams, TokenPriceMessage['data']>
+  queryClient: QueryClient
+}
+
+const PricesContext = createContext<PricesContextValue | null>(null)
+
+export function PriceServiceProvider({
+  wsClient,
+  queryClient,
+  children,
+}: {
+  wsClient: WebSocketClient<TokenSubscriptionParams, TokenPriceMessage['data']>
+  queryClient: QueryClient
+  children: ReactNode
+}): ReactElement {
+  return <PricesContext.Provider value={{ wsClient, queryClient }}>{children}</PricesContext.Provider>
+}
+
+export function usePricesContext(): PricesContextValue {
+  const context = useContext(PricesContext)
+  if (!context) {
+    throw new Error('usePricesContext must be used within a PriceServiceProvider')
+  }
+  return context
+}

package/src/hooks/useConnectionStatus.ts

@@ -0,0 +1,11 @@
+import { usePricesContext } from '@luxexchange/prices/src/context/PriceServiceContext'
+import type { ConnectionStatus } from '@luxexchange/websocket'
+import { useSyncExternalStore } from 'react'
+
+/**
+ * Hook to get the current WebSocket connection status.
+ */
+export function useConnectionStatus(): ConnectionStatus {
+  const { wsClient } = usePricesContext()
+  return useSyncExternalStore(wsClient.onStatusChange, wsClient.getConnectionStatus, wsClient.getConnectionStatus)
+}

package/src/hooks/usePrice.ts

@@ -0,0 +1,44 @@
+import { queryOptions, skipToken, useQuery } from '@tanstack/react-query'
+import { usePricesContext } from '@luxexchange/prices/src/context/PriceServiceContext'
+import { priceKeys } from '@luxexchange/prices/src/queries/priceKeys'
+import { tokenPriceQueryOptions } from '@luxexchange/prices/src/queries/tokenPriceQueryOptions'
+import type { TokenPriceData } from '@luxexchange/prices/src/types'
+import { useEffect } from 'react'
+
+interface UsePriceOptions {
+  chainId: number | undefined
+  address: string | undefined
+  live?: boolean
+}
+
+/**
+ * Hook to get the live price for a token.
+ * Reads from React Query cache and auto-subscribes via websocket.
+ *
+ * Requires a PriceServiceProvider in the tree.
+ */
+export function usePrice(options: UsePriceOptions): number | undefined {
+  const { chainId, address, live = true } = options
+  const { wsClient } = usePricesContext()
+
+  const enabled = chainId !== undefined && !!address
+
+  // Data is populated externally via queryClient.setQueryData from WS messages.
+  const { data } = useQuery(
+    enabled
+      ? tokenPriceQueryOptions(chainId, address)
+      : queryOptions<TokenPriceData>({ queryKey: priceKeys.all, queryFn: skipToken, enabled: false }),
+  )
+
+  useEffect(() => {
+    if (!enabled || !live) {
+      return undefined
+    }
+    return wsClient.subscribe({
+      channel: 'token_price',
+      params: { chainId, tokenAddress: address.toLowerCase() },
+    })
+  }, [enabled, live, chainId, address, wsClient])
+
+  return enabled ? (data?.price ?? undefined) : undefined
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+// Types
+
+export {
+  isConnectionEstablishedMessage,
+  isRawTokenPriceMessage,
+  parseConnectionMessage,
+  parseTokenPriceMessage,
+} from '@luxexchange/prices/src/sources/websocket/messageParser'
+// Internals (testing / custom setups)
+export { createPriceSubscriptionHandler } from '@luxexchange/prices/src/sources/websocket/subscriptionApi'
+export type {
+  ConnectionEstablishedMessage,
+  Logger,
+  PriceKey,
+  RawTokenPriceMessage,
+  TokenIdentifier,
+  TokenInput,
+  TokenPrice,
+  TokenPriceData,
+  TokenPriceMessage,
+  TokenSubscriptionParams,
+} from '@luxexchange/prices/src/types'
+export {
+  createPriceKey,
+  createPriceKeyFromToken,
+  filterValidTokens,
+  isCurrency,
+  isTokenIdentifier,
+  normalizeToken,
+  parsePriceKey,
+  toSubscriptionParams,
+} from '@luxexchange/prices/src/utils/tokenIdentifier'
+export type { ConnectionStatus } from '@luxexchange/websocket'
+export { PriceServiceProvider, usePricesContext } from './context/PriceServiceContext'
+export { useConnectionStatus } from './hooks/useConnectionStatus'
+// Consumer hooks
+// Backward-compat alias
+export { usePrice, usePrice as useLivePrice } from './hooks/usePrice'
+// Query utilities (advanced / UDL)
+export { priceKeys } from './queries/priceKeys'
+export { tokenPriceQueryOptions } from './queries/tokenPriceQueryOptions'

package/src/queries/priceKeys.test.ts

@@ -0,0 +1,23 @@
+import { priceKeys } from '@luxexchange/prices/src/queries/priceKeys'
+import { ReactQueryCacheKey } from '@luxfi/utilities/src/reactQuery/cache'
+import { describe, expect, it } from 'vitest'
+
+describe('priceKeys', () => {
+  describe('all', () => {
+    it('returns array with TokenPrice cache key', () => {
+      expect(priceKeys.all).toEqual([ReactQueryCacheKey.TokenPrice])
+    })
+  })
+
+  describe('token', () => {
+    it('returns key with chainId and lowercased address', () => {
+      const key = priceKeys.token(1, '0xABC')
+      expect(key).toEqual([ReactQueryCacheKey.TokenPrice, 1, '0xabc'])
+    })
+
+    it('handles already lowercased address', () => {
+      const key = priceKeys.token(42161, '0xdef')
+      expect(key).toEqual([ReactQueryCacheKey.TokenPrice, 42161, '0xdef'])
+    })
+  })
+})

package/src/queries/priceKeys.ts

@@ -0,0 +1,6 @@
+import { ReactQueryCacheKey } from '@luxfi/utilities/src/reactQuery/cache'
+
+export const priceKeys = {
+  all: [ReactQueryCacheKey.TokenPrice] as const,
+  token: (chainId: number, address: string) => [ReactQueryCacheKey.TokenPrice, chainId, address.toLowerCase()] as const,
+} as const

package/src/queries/tokenPriceQueryOptions.ts

@@ -0,0 +1,15 @@
+import { queryOptions, skipToken } from '@tanstack/react-query'
+import { priceKeys } from '@luxexchange/prices/src/queries/priceKeys'
+import type { TokenPriceData } from '@luxexchange/prices/src/types'
+
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function tokenPriceQueryOptions(chainId: number, address: string) {
+  return queryOptions<TokenPriceData>({
+    queryKey: priceKeys.token(chainId, address),
+    queryFn: skipToken,
+    staleTime: Infinity,
+    refetchOnWindowFocus: false,
+    refetchOnMount: false,
+    structuralSharing: false,
+  })
+}

package/src/sources/websocket/messageParser.ts

@@ -0,0 +1,79 @@
+import type { ConnectionEstablishedMessage, RawTokenPriceMessage, TokenPriceMessage } from '@luxexchange/prices/src/types'
+import { createPriceKey } from '@luxexchange/prices/src/utils/tokenIdentifier'
+
+/**
+ * Type guard for RawTokenPriceMessage
+ */
+export function isRawTokenPriceMessage(message: unknown): message is RawTokenPriceMessage {
+  return (
+    typeof message === 'object' &&
+    message !== null &&
+    'type' in message &&
+    message.type === 'token_price_update' &&
+    'payload' in message &&
+    typeof message.payload === 'object' &&
+    message.payload !== null
+  )
+}
+
+/**
+ * Type guard for ConnectionEstablishedMessage
+ */
+export function isConnectionEstablishedMessage(message: unknown): message is ConnectionEstablishedMessage {
+  return (
+    typeof message === 'object' &&
+    message !== null &&
+    'connectionEstablished' in message &&
+    typeof message.connectionEstablished === 'object' &&
+    message.connectionEstablished !== null &&
+    'connectionId' in message.connectionEstablished
+  )
+}
+
+/**
+ * Parses a raw WebSocket message into a typed price update.
+ * Returns null if the message is not a price update.
+ *
+ * Used both as the `parseMessage` config for createWebSocketClient
+ * and in the `onRawMessage` callback to write to React Query cache.
+ */
+export function parseTokenPriceMessage(raw: unknown): TokenPriceMessage | null {
+  if (!isRawTokenPriceMessage(raw)) {
+    return null
+  }
+
+  const { chainId, tokenAddress, priceUsd } = raw.payload
+  const price = parseFloat(priceUsd)
+
+  if (Number.isNaN(price)) {
+    return null
+  }
+
+  const timestamp = new Date(raw.timestamp).getTime()
+  const key = createPriceKey(chainId, tokenAddress)
+
+  return {
+    channel: 'token_price',
+    key,
+    data: {
+      chainId,
+      tokenAddress: tokenAddress.toLowerCase(),
+      priceUsd: price,
+      timestamp,
+    },
+  }
+}
+
+/**
+ * Parses a raw WebSocket message for connection establishment.
+ * Returns null if the message is not a connection message.
+ */
+export function parseConnectionMessage(raw: unknown): { connectionId: string } | null {
+  if (!isConnectionEstablishedMessage(raw)) {
+    return null
+  }
+
+  return {
+    connectionId: raw.connectionEstablished.connectionId,
+  }
+}

package/src/sources/websocket/subscriptionApi.ts

@@ -0,0 +1,105 @@
+import type { FetchClient } from '@luxexchange/api'
+import type { TokenSubscriptionParams } from '@luxexchange/prices/src/types'
+import type { SubscriptionHandler } from '@luxexchange/websocket'
+
+const EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE = 'EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE'
+
+export interface SubscriptionApiOptions {
+  client: FetchClient
+  onError?: (error: unknown, operation: string) => void
+}
+
+/**
+ * Creates a subscription handler for token price subscriptions.
+ * This implements the SubscriptionHandler interface from @luxexchange/websocket.
+ */
+export function createPriceSubscriptionHandler(
+  options: SubscriptionApiOptions,
+): SubscriptionHandler<TokenSubscriptionParams> {
+  const { client, onError } = options
+
+  async function subscribe(connectionId: string, params: TokenSubscriptionParams): Promise<void> {
+    try {
+      await client.post('/lux.notificationservice.v1.EventSubscriptionService/Subscribe', {
+        body: JSON.stringify({
+          eventSubscriptionType: EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE,
+          connectionId,
+          events: [{ token: { chainId: params.chainId, tokenAddress: params.tokenAddress } }],
+        }),
+      })
+    } catch (error) {
+      onError?.(error, 'subscribe')
+    }
+  }
+
+  async function unsubscribe(connectionId: string, params: TokenSubscriptionParams): Promise<void> {
+    try {
+      await client.post('/lux.notificationservice.v1.EventSubscriptionService/Unsubscribe', {
+        body: JSON.stringify({
+          eventSubscriptionType: EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE,
+          connectionId,
+          events: [{ token: { chainId: params.chainId, tokenAddress: params.tokenAddress } }],
+        }),
+      })
+    } catch (error) {
+      onError?.(error, 'unsubscribe')
+    }
+  }
+
+  async function subscribeBatch(connectionId: string, paramsList: TokenSubscriptionParams[]): Promise<void> {
+    if (paramsList.length === 0) {
+      return
+    }
+
+    try {
+      await client.post('/lux.notificationservice.v1.EventSubscriptionService/Subscribe', {
+        body: JSON.stringify({
+          eventSubscriptionType: EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE,
+          connectionId,
+          events: paramsList.map((p) => ({ token: { chainId: p.chainId, tokenAddress: p.tokenAddress } })),
+        }),
+      })
+    } catch (error) {
+      onError?.(error, 'subscribeBatch')
+    }
+  }
+
+  async function unsubscribeBatch(connectionId: string, paramsList: TokenSubscriptionParams[]): Promise<void> {
+    if (paramsList.length === 0) {
+      return
+    }
+
+    try {
+      await client.post('/lux.notificationservice.v1.EventSubscriptionService/Unsubscribe', {
+        body: JSON.stringify({
+          eventSubscriptionType: EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE,
+          connectionId,
+          events: paramsList.map((p) => ({ token: { chainId: p.chainId, tokenAddress: p.tokenAddress } })),
+        }),
+      })
+    } catch (error) {
+      onError?.(error, 'unsubscribeBatch')
+    }
+  }
+
+  async function refreshSession(connectionId: string): Promise<void> {
+    try {
+      await client.post('/lux.notificationservice.v1.EventSubscriptionService/RefreshSession', {
+        body: JSON.stringify({
+          eventSubscriptionType: EVENT_SUBSCRIPTION_TYPE_TOKEN_PRICE,
+          connectionId,
+        }),
+      })
+    } catch (error) {
+      onError?.(error, 'refreshSession')
+    }
+  }
+
+  return {
+    subscribe,
+    unsubscribe,
+    subscribeBatch,
+    unsubscribeBatch,
+    refreshSession,
+  }
+}

package/src/types.ts

@@ -0,0 +1,96 @@
+import type { Currency } from '@uniswap/sdk-core'
+
+/**
+ * A token identifier with chain and address.
+ * Can be used instead of a full Currency object.
+ */
+export interface TokenIdentifier {
+  chainId: number
+  address: string
+}
+
+/**
+ * Token price data with timestamp.
+ */
+export interface TokenPrice {
+  price: number
+  timestamp: number
+}
+
+/**
+ * Shape stored in the React Query cache for each token price.
+ */
+export interface TokenPriceData {
+  price: number
+  timestamp: number
+}
+
+/**
+ * Key used to identify a token price in the store.
+ * Format: "chainId-address" (e.g., "1-0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2")
+ * Matches CurrencyId convention from lx/src/utils/currencyId.ts
+ */
+export type PriceKey = string
+
+/**
+ * Token identifier format used by the subscription API.
+ */
+export interface TokenSubscriptionParams {
+  chainId: number
+  tokenAddress: string
+}
+
+/**
+ * Parsed WebSocket message for token price updates.
+ * Wraps channel, key, and the inner data payload.
+ */
+export interface TokenPriceMessage {
+  channel: string
+  key: string
+  data: {
+    chainId: number
+    tokenAddress: string
+    priceUsd: number
+    timestamp: number
+  }
+}
+
+/**
+ * Raw WebSocket message format from server (strings, optional fields).
+ * Parsed into {@link TokenPriceMessage} by messageParser before app consumption.
+ */
+export interface RawTokenPriceMessage {
+  type: 'token_price_update'
+  payload: {
+    chainId: number
+    tokenAddress: string
+    priceUsd: string
+    symbol?: string
+    timestamp?: string
+  }
+  timestamp: string
+}
+
+/**
+ * Connection established message from server.
+ */
+export interface ConnectionEstablishedMessage {
+  connectionEstablished: {
+    connectionId: string
+    timestamp: string
+  }
+}
+
+/**
+ * Logger interface for optional logging.
+ */
+export interface Logger {
+  debug: (tag: string, context: string, message: string, data?: unknown) => void
+  warn: (tag: string, context: string, message: string, data?: unknown) => void
+  error: (tag: string, context: string, message: string, data?: unknown) => void
+}
+
+/**
+ * Type guard input - any token that can provide chain and address.
+ */
+export type TokenInput = TokenIdentifier | Currency

package/src/utils/tokenIdentifier.test.ts

@@ -0,0 +1,136 @@
+import { Token } from '@uniswap/sdk-core'
+import type { TokenIdentifier } from '@luxexchange/prices'
+import {
+  createPriceKey,
+  createPriceKeyFromToken,
+  filterValidTokens,
+  isCurrency,
+  isTokenIdentifier,
+  normalizeToken,
+  parsePriceKey,
+  toSubscriptionParams,
+} from '@luxexchange/prices'
+import { describe, expect, it } from 'vitest'
+
+const WETH_ADDRESS = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
+const USDC_ADDRESS = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
+
+describe('tokenIdentifier utilities', () => {
+  describe('isCurrency', () => {
+    it('returns true for Token instances', () => {
+      const token = new Token(1, WETH_ADDRESS, 18, 'WETH', 'Wrapped Ether')
+      expect(isCurrency(token)).toBe(true)
+    })
+
+    it('returns false for TokenIdentifier', () => {
+      const identifier: TokenIdentifier = { chainId: 1, address: WETH_ADDRESS }
+      expect(isCurrency(identifier)).toBe(false)
+    })
+  })
+
+  describe('isTokenIdentifier', () => {
+    it('returns true for TokenIdentifier objects', () => {
+      const identifier: TokenIdentifier = { chainId: 1, address: WETH_ADDRESS }
+      expect(isTokenIdentifier(identifier)).toBe(true)
+    })
+
+    it('returns false for Token instances', () => {
+      const token = new Token(1, WETH_ADDRESS, 18, 'WETH', 'Wrapped Ether')
+      expect(isTokenIdentifier(token)).toBe(false)
+    })
+  })
+
+  describe('normalizeToken', () => {
+    it('normalizes TokenIdentifier with lowercase address', () => {
+      const identifier: TokenIdentifier = { chainId: 1, address: WETH_ADDRESS }
+      const result = normalizeToken(identifier)
+      expect(result).toEqual({
+        chainId: 1,
+        address: WETH_ADDRESS.toLowerCase(),
+      })
+    })
+
+    it('normalizes Token instance', () => {
+      const token = new Token(1, WETH_ADDRESS, 18, 'WETH', 'Wrapped Ether')
+      const result = normalizeToken(token)
+      expect(result).toEqual({
+        chainId: 1,
+        address: WETH_ADDRESS.toLowerCase(),
+      })
+    })
+  })
+
+  describe('createPriceKey', () => {
+    it('creates key with format chainId-address', () => {
+      const key = createPriceKey(1, WETH_ADDRESS)
+      expect(key).toBe(`1-${WETH_ADDRESS.toLowerCase()}`)
+    })
+
+    it('lowercases address', () => {
+      const key = createPriceKey(1, '0xABC')
+      expect(key).toBe('1-0xabc')
+    })
+  })
+
+  describe('createPriceKeyFromToken', () => {
+    it('creates key from TokenIdentifier', () => {
+      const identifier: TokenIdentifier = { chainId: 1, address: WETH_ADDRESS }
+      const key = createPriceKeyFromToken(identifier)
+      expect(key).toBe(`1-${WETH_ADDRESS.toLowerCase()}`)
+    })
+
+    it('creates key from Token', () => {
+      const token = new Token(1, WETH_ADDRESS, 18, 'WETH', 'Wrapped Ether')
+      const key = createPriceKeyFromToken(token)
+      expect(key).toBe(`1-${WETH_ADDRESS.toLowerCase()}`)
+    })
+  })
+
+  describe('parsePriceKey', () => {
+    it('parses key back to TokenIdentifier', () => {
+      const key = `1-${WETH_ADDRESS.toLowerCase()}`
+      const result = parsePriceKey(key)
+      expect(result).toEqual({
+        chainId: 1,
+        address: WETH_ADDRESS.toLowerCase(),
+      })
+    })
+
+    it('returns null for missing address', () => {
+      expect(parsePriceKey('1')).toBeNull()
+    })
+
+    it('returns null for invalid chainId', () => {
+      expect(parsePriceKey('abc-0x123')).toBeNull()
+    })
+
+    it('returns null for empty key', () => {
+      expect(parsePriceKey('')).toBeNull()
+    })
+  })
+
+  describe('toSubscriptionParams', () => {
+    it('converts to subscription params format', () => {
+      const identifier: TokenIdentifier = { chainId: 1, address: WETH_ADDRESS }
+      const params = toSubscriptionParams(identifier)
+      expect(params).toEqual({
+        chainId: 1,
+        tokenAddress: WETH_ADDRESS.toLowerCase(),
+      })
+    })
+  })
+
+  describe('filterValidTokens', () => {
+    it('filters out invalid addresses', () => {
+      const tokens: TokenIdentifier[] = [
+        { chainId: 1, address: WETH_ADDRESS },
+        { chainId: 1, address: 'invalid' },
+        { chainId: 1, address: USDC_ADDRESS },
+      ]
+      const result = filterValidTokens(tokens)
+      expect(result).toHaveLength(2)
+      expect(result[0]?.address).toBe(WETH_ADDRESS.toLowerCase())
+      expect(result[1]?.address).toBe(USDC_ADDRESS.toLowerCase())
+    })
+  })
+})

package/src/utils/tokenIdentifier.ts

@@ -0,0 +1,111 @@
+import type { Currency, Token } from '@uniswap/sdk-core'
+import type { PriceKey, TokenIdentifier, TokenInput, TokenSubscriptionParams } from '@luxexchange/prices'
+import { isEVMAddress } from '@luxfi/utilities/src/addresses/evm/evm'
+
+/** Address that represents native currencies on ETH, Arbitrum, etc. */
+const DEFAULT_NATIVE_ADDRESS_LEGACY = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
+
+/**
+ * Type guard to check if input is a Currency object (from @uniswap/sdk-core).
+ * Currency objects have isNative and isToken properties from the SDK.
+ */
+export function isCurrency(token: TokenInput): token is Currency {
+  return (
+    typeof token === 'object' &&
+    'chainId' in token &&
+    typeof (token as Currency).chainId === 'number' &&
+    // Currency from SDK always has isNative property (true for native, false for tokens)
+    'isNative' in token &&
+    typeof (token as Currency).isNative === 'boolean'
+  )
+}
+
+/**
+ * Type guard to check if input is a TokenIdentifier.
+ */
+export function isTokenIdentifier(token: TokenInput): token is TokenIdentifier {
+  return (
+    typeof token === 'object' &&
+    'chainId' in token &&
+    'address' in token &&
+    typeof (token as TokenIdentifier).chainId === 'number' &&
+    typeof (token as TokenIdentifier).address === 'string' &&
+    !('isNative' in token)
+  )
+}
+
+/**
+ * Normalizes any token input to a TokenIdentifier.
+ */
+export function normalizeToken(token: TokenInput): TokenIdentifier {
+  if (isTokenIdentifier(token)) {
+    return {
+      chainId: token.chainId,
+      address: token.address.toLowerCase(),
+    }
+  }
+
+  // It's a Currency
+  const currency = token as Currency
+  if (currency.isNative) {
+    return {
+      chainId: currency.chainId,
+      address: DEFAULT_NATIVE_ADDRESS_LEGACY,
+    }
+  }
+
+  // It's a Token
+  const tokenCurrency = currency as Token
+  return {
+    chainId: tokenCurrency.chainId,
+    address: tokenCurrency.address.toLowerCase(),
+  }
+}
+
+/**
+ * Creates a unique price key from chainId and address.
+ * Format matches CurrencyId convention: "chainId-address"
+ */
+export function createPriceKey(chainId: number, address: string): PriceKey {
+  return `${chainId}-${address.toLowerCase()}`
+}
+
+/**
+ * Creates a price key from a token input.
+ */
+export function createPriceKeyFromToken(token: TokenInput): PriceKey {
+  const { chainId, address } = normalizeToken(token)
+  return createPriceKey(chainId, address)
+}
+
+/**
+ * Parses a price key back to chainId and address.
+ * Returns null if the key is malformed (missing chainId or address).
+ */
+export function parsePriceKey(key: PriceKey): TokenIdentifier | null {
+  const [chainIdStr, address] = key.split('-')
+  const chainId = Number(chainIdStr)
+
+  if (Number.isNaN(chainId) || !address) {
+    return null
+  }
+
+  return { chainId, address }
+}
+
+/**
+ * Converts a TokenIdentifier to the format expected by the subscription API.
+ */
+export function toSubscriptionParams(token: TokenIdentifier): TokenSubscriptionParams {
+  return {
+    chainId: token.chainId,
+    tokenAddress: token.address.toLowerCase(),
+  }
+}
+
+/**
+ * Filters tokens to only those valid for subscription.
+ */
+export function filterValidTokens(tokens: TokenInput[]): TokenIdentifier[] {
+  return tokens.map(normalizeToken).filter((t) => isEVMAddress(t.address))
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../config/tsconfig/app.json",
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.json", "src/global.d.ts"],
+  "exclude": ["src/**/*.spec.ts", "src/**/*.spec.tsx", "src/**/*.test.ts", "src/**/*.test.tsx"],
+  "compilerOptions": {
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "types": ["node", "vitest/globals"],
+    "paths": {}
+  },
+  "references": [
+    {
+      "path": "../utilities"
+    },
+    {
+      "path": "../websocket"
+    },
+    {
+      "path": "../api"
+    }
+  ]
+}

package/tsconfig.lint.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "preserveSymlinks": true
+  },
+  "include": ["**/*.ts", "**/*.tsx", "**/*.json"],
+  "exclude": ["node_modules"]
+}

package/vitest.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    server: {
+      deps: {
+        inline: ['@tanstack/react-query', 'partysocket'],
+      },
+    },
+    coverage: {
+      exclude: [
+        '**/__generated__/**',
+        '**/node_modules/**',
+        '**/dist/**',
+        '**/*.config.*',
+        '**/scripts/**',
+        '**/.eslintrc.*',
+      ],
+    },
+  },
+})