Getting Started with React

The fastest path to a working React app that reads from SYMMIO. @symmio/trading-react wraps every core call in a hook with caching, refetching, and invalidation already wired — mount the provider, call the hook, render the data.

1. Install


pnpm add @symmio/trading-react viem wagmi @tanstack/react-query

@symmio/trading-react is the umbrella package — it pulls in @symmio/trading-core, @symmio/utils, and zustand transitively. The other four are peer dependencies you control.

Local development — run on port 3000

Serve your dev app on http://localhost:3000. In development the backend’s CORS policy only allows the localhost:3000 origin — a dev server on any other port has its solver / price / notification requests blocked by CORS (they surface as opaque “Failed to fetch” errors in the browser, not as SDK errors). Next.js already defaults to 3000; if you changed it, change it back for local dev. This only affects browser apps — Node scripts on @symmio/trading-core are not subject to CORS.

2. Mount providers

The React SDK assumes the host app mounts wagmi and @tanstack/react-query itself. That keeps the host in control of connectors, RPC URLs, and the shared QueryClient.


"use client";
 
import { SymmioProvider, SymmioSupportedChainId } from "@symmio/trading-react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useState } from "react";
import { http, zeroAddress } from "viem";
import { hyperEvm } from "viem/chains";
import { createConfig, WagmiProvider } from "wagmi";
import { injected } from "wagmi/connectors";
 
const wagmiConfig = createConfig({
  chains: [hyperEvm],
  transports: { [hyperEvm.id]: http("https://rpc.hyperliquid.xyz/evm") },
  connectors: [injected()],
});
 
export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient());
 
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <SymmioProvider
          symmioConfig={{
            [SymmioSupportedChainId.HYPER_EVM]: {
              // `zeroAddress` works out of the box — trades open, you just earn no
              // fee share. Swap in your registered affiliate to collect fees.
              addresses: { affiliatesAddress: zeroAddress },
            },
          }}
        >
          {children}
        </SymmioProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

The order of providers matters. Wagmi outside QueryClient outside SymmioProvider — the SDK reads both wagmi and QueryClient from context. See SymmioProvider for chain overrides and the WebSocket constructor.

No affiliate yet? The zero address (as above) is the correct default — every flow works, you just earn no share of the trading fee. Registration is how you monetize, not a prerequisite: it lets your affiliate collect a share of trading fees. When ready, register and swap the zero address for the registered one. See Register an Affiliate .

3. Read on-chain data


"use client";
 
import { useUserSubAccounts, useWalletAccount } from "@symmio/trading-react";
 
export function Subaccounts() {
  const { address } = useWalletAccount();
  const { data, isLoading, error } = useUserSubAccounts({ user: address });
 
  if (!address) return <p>Connect a wallet first.</p>;
  if (isLoading) return <p>Loading…</p>;
  if (error) return <p>{error.message}</p>;
 
  return (
    <ul>
      {data?.map((sub) => (
        <li key={sub.accountAddress}>{sub.name}</li>
      ))}
    </ul>
  );
}

4. Send a transaction


"use client";
 
import { useEditAccountName } from "@symmio/trading-react";
 
export function RenameButton({ account }: { account: `0x${string}` }) {
  const { mutate, isPending, error } = useEditAccountName();
  return (
    <>
      <button onClick={() => mutate({ account, name: "Trading bot" })} disabled={isPending}>
        {isPending ? "Sending…" : "Rename"}
      </button>
      {error?.kind === "user-rejected" ? null : error && <p>{error.message}</p>}
    </>
  );
}

Next steps

Build a Perps DEX — the end-to-end guide: deposit, open, close, TP/SL, withdraw.
Balance Model — which balance funds trading (deposit → trade; no allocate), and the two decimal scales.
Overview — the full hook catalog and the wrapper guarantees (invalidation, refetch intervals, override knobs).
Hook pattern — the three-line shape every read and write hook follows.
Core — the framework-agnostic functions each hook wraps, for Node scripts or bypassing the hook layer.