@liq/react

React hooks, mutations, and state management for the Liq perpetuals trading frontend.

Overview

@liq/react wraps @liq/api-client and @liq/onchain in React Query queries, wagmi/viem mutations, and Zustand stores. It provides LiqProvider as the root context component, a set of data-fetching hooks for markets, positions, orders, and margin, and mutation hooks for order submission, cancellation, deposits, and gateway authentication. All async transaction flows are tracked via useTransactionStore.

Key Exports

Provider

• LiqProvider — root provider (wraps React Query + gateway client context)
• useLiqClient() — access the configured LiqClient instance
• useLiqOnchain() — access the configured LiqOnchain instance

Query hooks (TanStack Query)

| Hook | Description | | --------------------------- | ------------------------------------------ | | useMarketsQuery() | Fetch all markets | | useOpenOrdersQuery() | Fetch open orders for current account | | useAvailableMarginQuery() | Fetch available margin for current account | | useAccountId() | Read SNX account ID | | liqQueryKeys | Cache key factory for all queries |

Margin (since 0.67.0):

| Hook | Description | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | useAccountMargin(accountId) | Gateway margin — available, locked, free (free feeds validateOrder); needs the gateway session; refreshed on terminal order transitions too | | useMarginUsage(accountId) | { requiredInitialMargin, available, usage } read onchain; data undefined = no reading (isLoading in flight, fetchStatus === 'idle' disabled — not isPending), data.usage undefined = under water | | useOrderMarginPreview(accountId, market, size, price, orderCost?) | Protocol requiredMargin and estimated liquidation price at the tab's price (limit for LIMIT, mark for MARKET); the price moves the fees, the initial margin is valued at the contract's oracle; disabled without a connected wallet; re-reads every 10 s and goes stale on settle, deposit, withdraw and repay |

Mutation hooks

| Hook | Description | | ---------------------------- | ------------------------------------------------------------ | | useOrderSubmission() | Submit an order draft — nonce, signing, retry, invalidation | | useCancelOrderMutation() | Cancel an open order | | useDepositMutation() | USDC → sUSDC → collateral deposit (onchain) | | useWithdrawMutation() | Collateral withdraw, repaying debt first if needed (onchain) | | useCreateAccountMutation() | Create SNX account NFT (onchain) | | useClaimFaucetMutation() | Claim testnet faucet tokens (onchain) | | useGatewayAuthMutation() | SIWE authentication → JWT | | useTransactionMutation() | Generic onchain tx wrapper with status tracking |

Gasless relay (ADR-0063) — mount <LiqProvider relay> and the same mutation hooks above sign a Delegate7702 batch for the relayer to send and pay for, so the wallet never needs ETH. There is no separate set of hooks for this: the provider's sender picks wallet or relay, the hook doesn't know which.

SSE / realtime

• useSseOrderUpdates(orderIds, callback) — subscribe to live status updates of the listed orders (order:{id} channels)
• useAccountOrderUpdates(onUpdate?) — one subscription to the account-wide orders:{accountId} stream; the callback gets the full order_update with reason / origin

Utilities

• useWallet() — active wallet address + chain ID
• useNetworkId() — current network ID
• useDebounce(value, delay) — debounce hook

Stores (Zustand)

• useGatewayStore / selectIsAuthenticated — JWT + auth state
• useTransactionStore / TransactionStatus / TransactionState / TransactionType — onchain tx lifecycle

Install

pnpm add @liq/react

Peer Dependencies

• react ^18 or ^19
• viem ^2
• wagmi ^2

Build

moon run liq-react:build    # tsup → dist/