@liberfi.io/ui-perpetuals

@liberfi.io/ui-perpetuals provides perpetual trading UI widgets, container hooks, and typed client contracts for the Liberfi React SDK. It is designed for host apps that want ready-to-use perpetual modules (order book, trades, place order, positions, orders, history) while still controlling networking, side effects, and provider wiring.

Design Philosophy

• Keep data logic and presentation separated (*.script.tsx + *.ui.tsx + *.widget.tsx).
• Keep client integration explicit via PerpetualsProvider and usePerpetualsClient.
• Prefer typed hooks over ad-hoc data fetching to keep cache keys and API calls consistent.
• Expose building blocks (UI + hooks + types) so consumers can compose custom flows.

Installation

pnpm add @liberfi.io/ui-perpetuals

Required peer dependencies:

• react
• react-dom
• @tanstack/react-query
• react-hook-form

API Reference

Components

• CoinInfoWidget(props: CoinInfoWidgetProps)
• CoinInfoUI(props: CoinInfoUIProps)
• CoinInfoSkeletonsUI()
• CoinInfoNotFoundUI()
• SearchCoinsWidget(props: SearchCoinsWidgetProps)
• SearchCoinsUI(props: SearchCoinsUIProps)
• OrderBookWidget(props: OrderBookWidgetProps)
• OrderBookUI(props: OrderBookUIProps)
• TradesWidget(props: TradesWidgetProps)
• TradesUI(props: TradesUIProps)
• PlaceOrderFormWidget(props: PlaceOrderFormWidgetProps)
• PlaceOrderFormUI(props: PlaceOrderFormUIProps) (uses react-hook-form UseFormReturn)
• PositionsWidget(props: PositionsWidgetProps)
• PositionsUI(props: PositionsUIProps)
• PositionsSkeleton()
• PositionsEmpty()
• OpenOrdersWidget(props: OpenOrdersWidgetProps)
• OpenOrdersUI(props: OpenOrdersUIProps)
• OpenOrdersSkeleton()
• OpenOrdersEmpty()
• TradeHistoryWidget(props: TradeHistoryWidgetProps)
• TradeHistoryUI(props: TradeHistoryUIProps)
• TradeHistorySkeleton()
• TradeHistoryEmpty()
• PerpetualsProvider(props: PerpetualsProviderProps)

Hooks

• Context hook:
  • usePerpetualsClient()
• Query hooks:
  • useCoinsQuery, useMarketQuery, useMarketsQuery, useKlinesQuery
  • useOrderBookQuery, useRecentTradesQuery
  • usePositionsQuery, useOrdersQuery, useTradesQuery
• Mutation hooks:
  • useCreateOrderMutation, useCancelOrderMutation
• Subscription hooks:
  • useMarketDataSubscription, useCandlesSubscription, useUserDataSubscription
• Component script hooks:
  • useCoinInfo, useSearchCoinsScript, useOrderBookScript, useTradesScript
  • usePlaceOrderFormScript, usePositionsScript, useOpenOrdersScript, useTradeHistoryScript
• Also exported helpers from hook modules:
  • Query keys and fetchers such as coinsQueryKey/fetchCoins, marketQueryKey/fetchMarket, ordersQueryKey/fetchOrders, etc.
  • Trade operation helpers: createOrder, cancelOrder.

Functions / Utilities

• HyperliquidPerpetualsClient class implementing IPerpetualsClient.
• usePerpetualsClient() as the context accessor utility.

Types & Enums

• Client-related:
  • IPerpetualsClient, HyperliquidClientConfig, HyperliquidEnvironment, HyperliquidApiError
  • PerpetualsContextValue, PerpetualsProviderProps
• Domain enums/types:
  • Symbol, TradingProvider, OrderSide, OrderType, OrderStatus, KlineInterval, TradeSide
• Domain entities:
  • Coin, MarketData, Kline, OrderBookLevel, OrderBook, Trade, Account
  • Position, Order, TradeHistory
• Request/response contracts:
  • PlaceOrderParams, CancelOrderParams, GetPositionsParams, GetOpenOrdersParams, GetTradesParams
  • PlaceOrderResult, CancelOrderResult, GetPositionsResult, GetOpenOrdersResult, GetTradesResult
• UI and script props/result types:
  • All *Props, Use*Params, Use*Result types re-exported by each component/hook index.

Constants

• version (package version string).

Usage Examples

import {
  HyperliquidPerpetualsClient,
  PerpetualsProvider,
  PlaceOrderFormWidget,
  OrderBookWidget,
  TradesWidget,
} from "@liberfi.io/ui-perpetuals";

const client = new HyperliquidPerpetualsClient({ environment: "testnet" });

export function PerpsPanel() {
  return (
    <PerpetualsProvider client={client}>
      <OrderBookWidget symbol="BTC-USDC" />
      <TradesWidget symbol="BTC-USDC" />
      <PlaceOrderFormWidget symbol="BTC-USDC" userAddress="0x..." />
    </PerpetualsProvider>
  );
}

import { useForm } from "react-hook-form";
import {
  PlaceOrderFormUI,
  type PlaceOrderFormData,
} from "@liberfi.io/ui-perpetuals";

const methods = useForm<PlaceOrderFormData>({
  defaultValues: {
    amount: 0,
    leverage: 1,
    takeProfitPercent: 0,
    stopLossPercent: 0,
  },
});

// Pass methods directly to PlaceOrderFormUI if you build your own container.

Future Improvements

• Add integration tests for order submit/cancel and subscription lifecycle.
• Add i18n wiring for all user-facing strings in ui-perpetuals components.
• Replace placeholder account/margin values in place-order script with real account sources.