React Hooks

React hooks for the Dimes SDK — data fetching, the interactive quote flow, and live WebSocket updates, all on top of TanStack Query.

The @dimes-dot-fi/sdk/react entry point ships hooks for every read endpoint, two quote flows, and live WebSocket streams. They are thin wrappers over TanStack Query — every data hook returns a standard UseQueryResult, so data, isLoading, error, refetch, etc. all work as usual.

Peer dependencies: react >=19, @tanstack/react-query >=5.

Runnable examples: react/trade-panel.tsx (provider + useMarkets + useQuote) and react/streams.tsx (usePositions with live WebSocket reconciliation). Both are type-checked against the SDK in CI.

Provider setup

Wrap your app in both a QueryClientProvider and DimesProvider. The hooks read the DimesClient from DimesProvider and the query cache from whatever QueryClientProvider is in the tree.

import { DimesClient, JwtAuth } from "@dimes-dot-fi/sdk";
import { DimesProvider } from "@dimes-dot-fi/sdk/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();
const client = new DimesClient({
  auth: new JwtAuth({ tokenUrl: "https://your-backend.com/api/dimes-token" }),
});

function Root() {
  return (
    <QueryClientProvider client={queryClient}>
      <DimesProvider client={client}>
        <App />
      </DimesProvider>
    </QueryClientProvider>
  );
}

---

Data hooks

Hook	Returns	Endpoint
useMarkets(params?, qo?)	Paginated<Market>	GET /markets (pass query to search)
useMarket(ticker, qo?)	Market	GET /markets/:ticker
usePositions(params?, qo?, options?)	Position[]	GET /positions
useContractInfo(qo?)	ContractInfo	GET /contract-info
useLimits(qo?)	CustomerLimit	GET /limits

qo is an optional partial UseQueryOptions passed straight through (override enabled, staleTime, etc.).

import { useMarkets, usePositions } from "@dimes-dot-fi/sdk/react";

function Markets() {
  const { data, isLoading } = useMarkets({ status: "active", sort: "depth_desc" });
  if (isLoading) return <Spinner />;
  return <>{data!.data.map((m) => <MarketCard key={m.id} market={m} />)}</>;
}

usePositions options

The third argument tunes polling and cache behaviour — all opt-in, all off by default:

usePositions(
  { state: "active" },
  { enabled: !!wallet },               // standard query options
  {
    scope: wallet?.toLowerCase(),       // append to the cache key — avoids serving a previous wallet's positions
    adaptivePolling: true,              // poll fast (5s) while any position is transitioning, slow (15s) otherwise
    reconcile: true,                    // defer to fresher WebSocket data (pair with usePositionStream reconcile)
  },
);

adaptivePolling also accepts { fastMs, slowMs }; reconcile also accepts a window in milliseconds.

---

Quote hooks

Two flows sit on the same draft → promote pipeline. Pick by how much control your UI needs over the steps.

useQuote — one-shot

Runs draft → promote (with auto-retry on market-moved and auto-correction of leverage/collateral/slippage) in a single call. Best when you just want a signed quote back and surface progress from state.phase.

import { useQuote } from "@dimes-dot-fi/sdk/react";

const { state, execute } = useQuote();

const result = await execute(
  { marketTicker, side, collateralUsd, leverageBps, slippageBps },
  {
    onMarketMoved: () => true,   // return false to abort the retry
    onCorrection: () => true,    // return false to reject the adjustment
  },
);
// result.quote is the signed quote; state.phase walks idle → loading-draft → … → promoted

useQuoteMachine — interactive

The granular, user-in-the-loop flow: fetch a draft, let the user review it, then promote — pausing across renders at each step. On a market-moved promote failure it re-drafts and surfaces a market-moved state so the user can review and accept the new draft before it's promoted.

import { useQuoteMachine } from "@dimes-dot-fi/sdk/react";

const { state, getDraft, promote, acceptChanges, correctAndPromote, reset } = useQuoteMachine();

// 1. fetch + show a draft
await getDraft({ marketTicker, side, collateralUsd, leverageBps, slippageBps });

// 2. user confirms → promote the reviewed draft
if (state.phase === "draft-ready") await promote(state.draft);

// 3a. market moved → show state.newDraft, then on user confirm:
if (state.phase === "market-moved") await acceptChanges(state.newDraft, state.retryCount);

// 3b. a correctable error → apply a hint and promote adjusted params directly
//     (see quoteErrorHint / hintAdjustment in the core SDK)
await correctAndPromote(state.draft, adjustedParams);

state.phase is one of idle | loading-draft | draft-ready | promoting | promoted | market-moved | error. In the promoted phase, state.promotedQuote is the signed quote.

Building a fully custom flow instead? The same primitives are public: client.createDraftQuote() / promoteDraftQuote() / createQuote(), buildQuoteParams(), and isMarketMovedError().

Committed mode

Both flows accept riskMode: "committed" in the quote params and carry it through to promotion for you. Pass it again on any params you rebuild yourself — correctAndPromote replaces the params rather than merging them, so a correction that omits the mode re-quotes as adaptive. Read state.promotedQuote.riskMode to see which mode you actually got. See Committed Risk Mode.

Partial fill

Both flows accept partial-fill params. Pass allowPartialFill: true (and optionally minFillBps) in the quote params to let an order fill below the requested notional rather than rejecting atomically. The correction logic will also auto-raise minFillBps to the floor the API returns. See Partial-open (FAK).

---

Stream hooks

usePositionStream and useMarketStream subscribe to the user WebSocket gateways. Both default to reconcile mode — merging events straight into the usePositions / useMarkets caches so the UI updates live — but you can switch to raw mode and handle events yourself. App-specific side effects (toasts, your own stores) go in the callbacks; the SDK never reaches into your app.

import { usePositionStream, useMarketStream } from "@dimes-dot-fi/sdk/react";

function LiveUpdates() {
  usePositionStream({
    mode: "reconcile",                       // default — merges into ["dimes","positions"]
    onEvent: (e) => toastPositionEvent(e),   // always called, in both modes
    onNotification: (n) => toast(n.data.message),
  });

  useMarketStream({
    onEvent: (e) => {
      if (e.type === "market.discovered") addToLiveStrip(e.data); // discoveries are never auto-injected
    },
  });

  return null;
}

Shared options: enabled, mode ("reconcile" | "raw"), pauseOnHidden (disconnect while the tab is hidden, default true), invalidateOnReconnect (refetch on reconnect to catch missed events, default true), and the onEvent / onConnect / onDisconnect / onError callbacks (usePositionStream adds onNotification). Each returns { socket, connected }.

In reconcile mode, market eligibility / max-leverage deltas are deep-merged into cached markets (so the constant minBps / stepBps survive a leverage change); market.discovered events are deliberately left for you to route, since injecting them would pollute server-filtered list views.

For the raw protocol, gateways, event types, and payloads, see WebSocket Events.

---

What's next

• API Reference — every endpoint and its SDK method

• WebSocket Events — the underlying socket protocol

• On-Chain Integration — turning a signed quote into a position