Build a Perps DEX on SYMMIO

Ship a perpetuals trading UI on @symmio/trading-react: connect a wallet, pick a market, open and close leveraged positions, manage TP/SL. This page maps each part of the app to the exact hooks, providers, and the gotchas that break integrations. Follow the cross-links for per-hook reference and snippets.

Architecture

A perps DEX is five parts plus a shared shell. Distribute them however you like — one dense trading page, or a route per part.

The shell — wallet connection and the SubAccount picker — is shared by every part and surfaces once: useWalletAccount, useConnectWallet, useDisconnectWallet, useSwitchToSymmioChain, useUserSubAccounts.

Page layout

Three rules that hold regardless of layout:

• Keep the market in the URL — /trade/BTCUSDT, /perps/BTC-USDT, or ?symbol=BTCUSDT. An addressable market survives refresh, back-button, and shared links; component state loses all three.
• The header opens a searchable selector, not a <select>. Back it with useMarkets().data and let the user filter by symbol.
• Trade-form field order is fixed: Side → Margin → Leverage → TP/SL → Slippage → Submit.

Setup

pnpm add @symmio/trading-core @symmio/trading-react @symmio/session-key @symmio/utils \
  @tanstack/react-query wagmi @wagmi/connectors viem next react react-dom

wagmi, viem, and React are peer dependencies of @symmio/trading-react — your app owns them and the SDK adopts whatever you install within range. Satisfy the range; you don’t pin an exact version. (next is not an SDK peer — it’s your app’s choice — but Next 16 is required in practice; see below.)

Import paths

Runtime (hooks, providers, selectors, calc helpers) comes from @symmio/trading-react. Chain config and quote value-types come from @symmio/trading-core.

• @symmio/trading-react — SymmioProvider, useSymmioConfig, useSymmioChainId, every use* hook, the delegation selector constants, the pure calc helpers (calculateTradeParams, validateInstantOpenAgainstMarket, …), and the enums PositionType / OrderType / QuoteStatus / NotificationType.
• @symmio/trading-core — SymmioSupportedChainId, CreateConfigParameters, SymbolContractSymbol, UnifiedQuote, QuoteLifecycle, SubAccountDetail, SubAccountIsolationType, getChainConfig, and the other chain-config / quote types.

Providers

Nest WagmiProvider → QueryClientProvider → SymmioProvider. The SDK reads both wagmi and TanStack Query from context.

• WagmiProvider — your createConfig({ chains, transports, connectors }) from wagmi. The host owns connectors and RPCs; the SDK never picks them.

• QueryClientProvider — one new QueryClient(), held in useState so it survives remounts.

• SymmioProvider — props are chainOverrides, defaultChainId, getWalletClient (plus children). There is no config or affiliateAddress prop. Set your affiliate through chainOverrides, which deep-merges onto the SDK’s built-in per-chain config:

  import { SymmioProvider } from "@symmio/trading-react";
  import { SymmioSupportedChainId, type CreateConfigParameters } from "@symmio/trading-core";
   
  const chainOverrides: CreateConfigParameters["chainOverrides"] = {
    [SymmioSupportedChainId.HYPER_EVM]: {
      // affiliate earns a fee cut on trades routed through your UI — set before shipping
      addresses: { affiliatesAddress: "0xYourAffiliate…" },
    },
  };
   
  <SymmioProvider chainOverrides={chainOverrides} getWalletClient={getWalletClient}>
    {children}
  </SymmioProvider>;

getWalletClient is the resolver the SDK calls to sign each write. For instant trading it returns a session-key viem client when the requested from matches your loaded session key, and falls back to the connected wallet otherwise (see §4). Omit it and every instant open/close falls back to a per-trade wallet popup. See the SymmioProvider reference for the full prop list.

The gate ladder

A trading page reveals one call-to-action at a time. Each gate hides everything below it:

Connect wallet          ← useWalletAccount.isConnected
Switch to HyperEVM       ← useWalletAccount.isOnExpectedChain
Select SubAccount        ← your SubAccount picker
Deposit collateral       ← useAccountBalanceOf > 0
Initialize session key   ← @symmio/session-key
Grant delegation         ← useIsDelegationActive ×3, useGrantDelegation
Open position            ← trade form renders

The sections below follow this order.

1. Wallet + chain

Every trading page starts with the same guard — connected, on the right chain, then render.

• useWalletAccount → { address, chainId, isConnected, isReconnecting, isOnExpectedChain }. isOnExpectedChain saves comparing chain IDs by hand.
• useConnectWallet → { connectors, connect, status, error }. Connectors come from your wagmi config.
• useDisconnectWallet → { disconnect }.
• useSwitchToSymmioChain → { switchChain, status, error }. Targets the SDK’s chain — no hardcoded id.

A single WalletButton renders three states off useWalletAccount(): not-connected, wrong-chain, connected.

2. SubAccount

SYMMIO trades happen against a SubAccount address, not the EOA. Every trading page needs a picker.

• useUserSubAccounts — takes { user }, returns the SubAccount list (accountAddress, name, …). The query auto-disables while user is undefined, so passing the connected address directly is safe — no manual enabled guard.

3. Collateral

The diamond keeps two balances per SubAccount. The instant (lowcap) flow this guide describes funds from available.

• Available (deallocated) — deposited collateral idle on the account. Read via useAccountBalanceOf ({ account } → bigint, 18 decimals). Instant open consumes this directly.
• Allocated — collateral moved into the classic-flow pool where CVA + LF locks sit. Read via useAccountBalanceInfo ({ account } → { allocatedBalance, lockedCVA, lockedLF, lockedPartyAMM, lockedPartyBMM, … }).

Show both. Wire the buttons to:

• useAllocate — available → allocated.
• useDeallocate — allocated → available. Fetches a fresh Muon uPnL signature for you. Subject to an on-chain debounce — a rapid second deallocate reverts.

4. Session key + delegation

Every instant open / close / margin-add is signed by a session key — a hot signer the user grants scoped, time-boxed permission to. Without it, every trade prompts the wallet. Without an active delegation, the on-chain call reverts.

Flow: mint or load a session key with @symmio/session-key (its SessionKeyManager owns the keystore) → check the delegation for each required selector → if any is missing, prompt one wallet transaction that grants all three → render the trade form only once all are active.

Selectors

From @symmio/trading-react:

Read + grant

• useIsDelegationActive({ account, delegate, selector }) → boolean. Call once per selector (account = SubAccount, delegate = session-key address). Compose them: allActive = addMarginActive && sendQuoteActive && closePositionActive.
• useDelegationExpiry({ account, delegate }) → bigint expiry timestamp, so you can render “expires in 6 days” and re-grant early.
• useGrantDelegation() — mutation. Variables: { account: { addr: subAccount, isPartyB: false }, delegatedSigner: sessionKeyAddress, selectors: INSTANT_TRADE_REQUIRED_SELECTORS, expiryTimestamp }. expiryTimestamp is Unix seconds (a 24h–30d TTL keeps returning users from re-granting). On success the three useIsDelegationActive queries auto-invalidate and the gate flips to true.

TP/SL needs a second delegation

TP/SL requests are signed by the session key, but the on-chain execution when a trigger fires is done by the solver’s COH wallet, not the session key. The SubAccount must delegate to two signers:

• Session key → INSTANT_TRADE_REQUIRED_SELECTORS (open, close, add margin).
• COH wallet → REQUEST_TO_CLOSE_POSITION_SELECTOR (executes the trigger).

Read the COH address from config — config.getChainConfig().solver.tpsl?.cohWalletAddress — then check and grant it exactly like the session-key delegation. A user can trade with only the session-key delegation, but cannot set TP/SL without the COH delegation. Gate the TP/SL panel on cohActive === true.

Reference: apps/web/src/features/integration/instant-open-flow.tsx and tpsl-flow.tsx.

5. Market data

• useMarkets — the solver catalog (SymbolContractSymbol[]) with precision, tick, and symbol metadata. Cached and deduped by TanStack Query — call it in any component. Prefer over useOnchainContractMarkets for anything user-facing.
• useLockedParams — CVA / LF percentages at a given leverage. Renders “at 10x you lock X USDC” hints.
• useNotionalCapBySymbolId — remaining notional the solver allows. Gate order size on this; the solver rejects over-cap opens.
• useOpenInterestBySymbolId / useNotionalCapAll — used-vs-cap per market, and all caps in one call for a table.

6. Open a position

Two orchestrators cover the open flow:

• useInstantOpenAuto — one-line open. Fetches market metadata, mark price, locked params, and fees inline, signs, and POSTs. Returns { tempQuoteId } (a negative int) that pins the pending row until it anchors on-chain. Use when the form has no TP/SL row.
• useInstantOpenWithTpSl — same, plus atomically attaches TP/SL against the returned tempQuoteId. Pass tpsl: undefined when both legs are empty.

Both mutate with { from, subAccountAddress, market: { id }, positionType, initialMargin, leverage, slippage, tpsl? }. from is the session key. market.id is Number(row.symbol_id). positionType is PositionType.LONG / PositionType.SHORT.

For a low-latency path (pre-fetch on mount, one-shot submit), use useInstantOpen with a cached prepareInstantOpenParams — same inputs, you own the fetch.

Form details that matter:

• Side toggle is a colored segmented control (Long / Short), not a dropdown.
• Leverage bounds read from market.max_leverage, never a hardcoded value.
• useLockedParams({ symbol, leverage }) drives a live “Locks CVA X% + LF Y%” hint.
• Slippage is a chip row (0.1 / 0.5 / 1 / custom), never a raw number field.
• The submit button is smart-labeled from a single gate (see the gate ladder).

Available margin (the Max chip)

Raw available balance is not the safe max — the request must survive fees and, for SHORT, worst-case slippage fill. Shave it before writing to Max:

available = balance
          × max(0, 1 − slippageFactor)              // slippageFactor = slippage on SHORT, 0 on LONG
          × max(0, 1 − leverage × (openFee + closeFee))

1. Fees are charged on leveraged notional — subtract leverage × (openFee + closeFee).
2. Slippage (SHORT only) — quantity is sized off markPrice × (1 − s); a closer fill inflates notional, so cap usable balance at balance × (1 − s). LONG fills deflate notional, so no extra cap.

Inputs: balance = useAccountBalanceOf (1e18), openFee/closeFee = useFeeForUser (18-dec fixed-point), slippage as a wei fraction (slippage × 1e16). Do it all in BigInt with ONE_E18 = 10n ** 18n; formatUnits(_, 18) only at display time.

Pre-submit validation

Two pure helpers run the same math the solver runs, so you can block a doomed submit. Both are in @symmio/trading-react.

• calculateTradeParams({ markPrice, slippage, positionType, userInput, inputField, leverage, pricePrecision, quantityPrecision, cvaPercent, lfPercent, partyAmmPercent, partyBmmPercent }) → { quantity, requestedOpenPrice, cva, lf, partyAmm, partyBmm } as decimal strings, or null if an input is missing. The *Percent values come from useLockedParams; precisions from the market row.
• validateInstantOpenAgainstMarket({ market, quantity, markPrice, cva, lf, partyAmm, notionalCap?, positionType? }) → { ok, violations }. Each violation carries actual-vs-required numbers.

Pattern: on every input change run calculateTradeParams → if non-null run validateInstantOpenAgainstMarket → gate submit on violations.length === 0 && !exceedsAvailable → render violations inline. Each constraint fires only when the market publishes that field, so a partial constraint set still validates the rest.

7. Positions & close

useManagedQuotes is the one abstraction for the positions table. It reconciles four sources — on-chain reads, pending instant-opens, pending instant-closes, and the notifications WebSocket — into a reactive UnifiedQuote[], and accelerates polling during in-flight transitions.

• Inputs: { partyA, live?, extraAccounts?, chainId? }
• Outputs: { quotes, byKey, isLoading, isFetching, socketStatus, error }

Per-row: useQuoteUpnlAndPnl → { upnl, upnlPercent, markPrice }; useInstantCloseAuto to close; useQuotePlatformFee for a fee estimate.

Closing is WS-authoritative

A successful instant-close POST means only that the hedger accepted the request — the position is not closed yet. The on-chain settle (and the balance change) lands later over the notifications WebSocket, which useManagedQuotes folds into each UnifiedQuote.lifecycle. Drive the row from the lifecycle, not from mutation.isSuccess.

Close stages (QuoteLifecycle): OPTIMISTIC_CLOSE → CLOSE_PRICE_FILLED → WRITE_ONCHAIN_CLOSE → CLOSING → CLOSED. A row is “Closing…” while its lifecycle is any of the first four:

const CLOSING_STAGES = [
  QuoteLifecycle.OPTIMISTIC_CLOSE,
  QuoteLifecycle.CLOSE_PRICE_FILLED,
  QuoteLifecycle.WRITE_ONCHAIN_CLOSE,
  QuoteLifecycle.CLOSING,
];
const isClosing = CLOSING_STAGES.includes(quote.lifecycle);

Settlement is self-describing — no manual “done” flag:

• Full close → the quote leaves the active set; the row disappears from useManagedQuotes.
• Partial close → same row (same key / quoteId), lifecycle returns to ONCHAIN, openQuantity (quantity − closedAmount) shrinks.
• Failed close → lifecycle returns to ONCHAIN unchanged. Reading the spinner off the lifecycle means it clears on failure too — no stuck “Closing…”.

For a partial close, scale the amount in wei off the remaining openQuantity (basis points, floored) and pass the SDK a decimal string — it clamps to market.quantity_precision:

const remaining = quote.openQuantity; // wei (18-dec)
const closeWei = percent >= 100 ? remaining : (remaining * BigInt(Math.round(percent * 100))) / 10_000n;
// useInstantCloseAuto().mutate({ …, quantityToClose: formatUnits(closeWei, 18) })

Refetch margin after settle

Neither open nor close changes the SubAccount balance at POST time — margin locks/unlocks on the settle notification. Subscribe with useNotifications({ account: subAccount }) and, on a NotificationType.SUCCESS frame whose lastSeenAction is a settle action, invalidate the balance queries so Available / Allocated / the trade-form Max all refetch:

// open anchored (margin locked) + close filled (margin unlocked) — NOT the earlier request/price-fill frames
const SETTLE = new Set([
  "SendQuoteTransaction",
  "SendQuote",
  "FillLimitOrderOpen",
  "FillMarketOrderInstantClose",
  "FillLimitOrderClose",
]);
// onNotification(n): if (n.type === NotificationType.SUCCESS && SETTLE.has(n.lastSeenAction ?? "")) {
//   queryClient.invalidateQueries({ queryKey: ["getAccountBalanceOf"] });
//   queryClient.invalidateQueries({ queryKey: ["getAccountBalanceInfo"] });
// }

The balance query-key factories are not re-exported through react and the hooks expose no queryKey, so invalidate by the string tag (["getAccountBalanceOf"]) — TanStack prefix-matches it.

8. TP/SL

Prerequisites: session-key delegation and the second COH-wallet delegation for REQUEST_TO_CLOSE_POSITION_SELECTOR (see §4). Skip either and the on-chain trigger reverts.

• useQuoteTpSl — reads the current TP/SL record for a quote ({ quoteId } → { tp, sl, … }). Folds handler-side conditional orders and on-chain quotes into one record.
• useSetQuoteTpSl — mutates it. Pass tp: { price, priceType } and/or sl: { price, priceType }; undefined clears a leg.

See the TP/SL reference for the state machine, store shape, and the tempQuoteId ↔ quoteId linking rules.

Checklist

Setup & providers

• Exactly one wagmi copy resolves — automatic for a clean single-project install; force it with a package-manager override if two ever appear.
• Providers nested wagmi → QueryClient → Symmio, mounted client-only so next build doesn’t fail prerendering /_not-found.
• SymmioSupportedChainId, UnifiedQuote, QuoteLifecycle imported from @symmio/trading-core.
• Affiliate set via SymmioProvider chainOverrides, and a getWalletClient resolver wired for session-key signing.

Trade UX

• Market is addressable (URL / query / hash), not component state only.
• Header opens a searchable selector, not a <select>.
• Field order: Side → Margin → Leverage → TP/SL → Slippage → Submit.
• Colored Long / Short segmented control.
• Max reads useAccountBalanceOf (available), shaved for fees + slippage — not allocatedBalance.
• Leverage bounds from market.max_leverage.
• Slippage is a chip row with a custom field.
• Submit is smart-gated (Connect → Switch → Select SubAccount → Deposit → Insufficient → Open).
• Pre-submit validation runs calculateTradeParams + validateInstantOpenAgainstMarket.

Trading correctness

• Trade form blocks until a SubAccount is picked and all delegations are active.
• from is a session key in production, not the raw EOA.
• Delegation checked for all three selectors; granted at once via INSTANT_TRADE_REQUIRED_SELECTORS; expiry surfaced via useDelegationExpiry.
• TP/SL panel gates on the second (COH-wallet) delegation.
• Positions use useManagedQuotes; actions pick quote.quoteId ?? BigInt(quote.tempQuoteId).
• Close state is driven by UnifiedQuote.lifecycle (WS-authoritative), not the mutation’s isSuccess.
• Margin refetches after an open/close settles (on the settle notification), not just at POST time.

Pitfalls

Next steps

• Session keys — @symmio/session-key to remove the wallet popup from the hot path.
• Notional gating — clamp order size on useNotionalCapBySymbolId before submit.
• Withdraw — Withdraw hooks for request / cancel / finalize.
• Notifications — useNotifications for a toast stream of every state transition.