@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 configuredLiqClientinstanceuseLiqOnchain()— access the configuredLiqOnchaininstance
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)— live status updates of the listed orders, filtered from theorders:{accountId}channel (changing the list does not re-open the stream)useAccountOrderUpdates(onUpdate?)— one subscription to the account-wideorders:{accountId}stream; the callback gets the fullorder_updatewithreason/origin
Utilities
useWallet()— active wallet address + chain IDuseNetworkId()— current network IDuseDebounce(value, delay)— debounce hook
Stores (Zustand)
useGatewayStore/selectIsAuthenticated— JWT + auth stateuseTransactionStore/TransactionStatus/TransactionState/TransactionType— onchain tx lifecycle
Install
pnpm add @liq/react
Peer Dependencies
react^18 or ^19viem^2wagmi^2
Build
moon run liq-react:build # tsup → dist/