@agg-build/hooks

React hooks and providers for the AGG prediction market aggregator. Wraps @agg-build/sdk with React context, shared auth/session state, TanStack Query–powered data fetching, and live WebSocket streams.

What it is

@agg-build/hooks is the React bindings layer. It owns the AggClient inside a provider, keeps auth and balance state in sync across your component tree, and exposes hooks for every AGG surface — markets, orderbooks, charts, live trades, execution, managed wallets, deposits, search, and UI config. Data hooks are backed by TanStack Query, and live-data hooks are backed by the SDK's AggWebSocket.

When to use this package

• You are building a React app and want hooks instead of calling the SDK directly.
• You want a single provider that manages session, UI config, balances, and WebSocket lifecycle.
• You plan to render AGG trading UI with @agg-build/ui or the modular auth UI in @agg-build/auth — both require this package.

If you are not using React, use @agg-build/sdk directly.

Install

npm install @agg-build/sdk @agg-build/hooks

Quick start

import { AggProvider, QueryClient, QueryClientProvider } from "@agg-build/hooks";
import { createAggClient } from "@agg-build/sdk";

const client = createAggClient({
  baseUrl: "https://api.agg.market",
  appId: "your-app-id",
  wsUrl: "wss://ws.agg.market",
  // Optional: orderbookUrl: "wss://ob.agg.market", orderbookLatency: "realtime",
  // With orderbookUrl set, orderbook isLive follows that socket. Trades stay on wsUrl.
});
const queryClient = new QueryClient();

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AggProvider
        client={client}
        config={{
          general: { locale: "en-US", theme: "dark" },
          features: { enableAnimations: true, enableLiveUpdates: true },
        }}
      >
        <YourApp />
      </AggProvider>
    </QueryClientProvider>
  );
}

AggProvider composes the SDK, UI config, balance, and WebSocket contexts into one. If you prefer to compose them yourself, the individual providers (AggSdkProvider, AggUiProvider, AggBalanceProvider) are exported too.

AggProvider uses TanStack Query for shared request and live-data caches, so a QueryClientProvider ancestor is required. The package re-exports QueryClient and QueryClientProvider for hooks-only consumers.

Signing in with a wallet

useAggAuth is a lower-level hook for wiring your own wallet UI. Pass a signMessage callback from wagmi (Ethereum) or a Solana wallet adapter:

import { useAggAuth } from "@agg-build/hooks";
import { useAccount, useSignMessage } from "wagmi";

function SignIn() {
  const { address, chainId } = useAccount();
  const { signMessageAsync } = useSignMessage();
  const { signIn, signOut, isAuthenticated, user, isLoading, error } = useAggAuth({
    signMessage: (message) => signMessageAsync({ message }),
    address,
    chainId,
  });

  if (isAuthenticated) {
    return (
      <div>
        <p>Signed in as {user?.id}</p>
        <button onClick={() => signOut()}>Sign out</button>
      </div>
    );
  }

  return (
    <button disabled={isLoading} onClick={() => signIn("Sign in to AGG")}>
      Sign in with Ethereum
    </button>
  );
}

For Solana, pass a signMessage that signs the raw UTF-8 bytes and returns a base58-encoded signature:

import bs58 from "bs58";
import { useWallet } from "@solana/wallet-adapter-react";
import { useAggAuth } from "@agg-build/hooks";

function SolanaSignIn() {
  const { publicKey, signMessage } = useWallet();
  const { signIn, isLoading } = useAggAuth({
    address: publicKey?.toBase58(),
    chain: "solana",
    chainId: "mainnet",
    signMessage: async (message) => {
      const bytes = await signMessage!(new TextEncoder().encode(message));
      return bs58.encode(bytes);
    },
  });

  return (
    <button disabled={isLoading} onClick={() => signIn("Sign in to AGG")}>
      Sign in with Solana
    </button>
  );
}

For a fully packaged connect/sign-in UI with SIWE, SIWS, Google, Apple, Twitter/X, and email magic-link support, use @agg-build/auth.

Rendering market data

import { useVenueEvents, useMarketOrderbook } from "@agg-build/hooks";

function MarketList() {
  const { data, isLoading, fetchNextPage, hasNextPage } = useVenueEvents({
    limit: 20,
  });

  if (isLoading) return <p>Loading…</p>;

  return (
    <>
      {data?.pages
        .flatMap((page) => page.data)
        .map((event) => (
          <article key={event.id}>{event.title}</article>
        ))}
      {hasNextPage ? <button onClick={() => fetchNextPage()}>Load more</button> : null}
    </>
  );
}

function LiveOrderbook({ venueMarketIds }: { venueMarketIds: string[] }) {
  const { book, isLoading } = useMarketOrderbook({ venueMarketIds });
  if (isLoading) return null;
  return <pre>{JSON.stringify(book, null, 2)}</pre>;
}

Linking an external partner user ID

Generate the signed assertion on your backend with signExternalId() from @agg-build/sdk/server, then call useExternalId() on the frontend:

import { useEffect, useRef } from "react";
import { useExternalId } from "@agg-build/hooks";

function LinkPartnerAccount({
  assertion,
}: {
  assertion: { externalId: string; timestamp: number; hmac: string } | null;
}) {
  const { linkExternalId } = useExternalId();
  const lastLinked = useRef<string | null>(null);

  useEffect(() => {
    if (!assertion) return;
    const key = `${assertion.externalId}:${assertion.timestamp}`;
    if (lastLinked.current === key) return;
    lastLinked.current = key;
    void linkExternalId(assertion).catch(() => {
      lastLinked.current = null;
    });
  }, [assertion, linkExternalId]);

  return null;
}

Main hooks

Core

Market data

Orderbooks & routing

Charts

Live data

WebSocket

Balances

Orders & positions

Managed execution

To quote and fill, take the quote from useSmartRoute and pass its quoteId to useExecuteManaged.

const buyRoute = useSmartRoute({
  venueMarketOutcomeId,
  tradeSide: "buy",
  maxSpend: 50,
});

const sellRoute = useSmartRoute({
  venueMarketOutcomeId,
  tradeSide: "sell",
  sellShares: 10,
});

Removed in v4. useQuoteManaged was deleted — it wrapped client.quoteManaged(), whose endpoint (POST /execution/quote) does not exist on the API, so the call only ever returned 404.

Deposits (subpath)

Import from @agg-build/hooks/deposit to keep wallet-heavy hooks out of your main bundle:

Ramps

UI config & utilities

Providers

UI config

AggProvider accepts a sectioned config object:

• enableLogs / enableWebsocketsLogs — turn on debug logging
• general — locale, theme ("light" | "dark"), rootClassName, labels
• features — UI behavior flags including enableAnimations, enableLiveUpdates, enableVenueEventDiscoveryFilters, and enableEventDiscoveryUrlPersistence
• market — arbitrageThreshold, maxMidpointIdsPerRequest for proxy/CDN-safe midpoint batching
• chart — defaultChartTimeRange, selectedChartTimeRange
• search — provider-owned search state + callbacks for host-app routing/analytics

locale, theme, and selectedChartTimeRange are automatically persisted to localStorage.

Query keys

For direct React Query cache access (e.g. queryClient.invalidateQueries()):

import { executionKeys } from "@agg-build/hooks";

queryClient.invalidateQueries({ queryKey: executionKeys.balances() });
queryClient.invalidateQueries({ queryKey: executionKeys.positions() });
queryClient.invalidateQueries({ queryKey: executionKeys.orders() });

executionKeys is the only key builder exported publicly — market data queries are managed internally by the WebSocket provider.

Behavior notes

• useOrderbookQuote debounces size changes by 300 ms before querying.
• useDepositAddresses polls every 3 s while the managed wallet is being provisioned (ready === false), then switches to 60 s stale time.
• useLiveCandles merges REST historical candles with live CandleBuilder output; on collision the live version wins.
• For binary markets, the first outcome gets the midpoint and the second gets 1 − midpoint.
• CandleBuilder batches onChange callbacks at ~16 ms (rAF in browsers, setTimeout otherwise).
• Execution mutations (useExecuteManaged, useWithdrawManaged, useSyncBalances) auto-invalidate related balance/position/order queries on success.

Entrypoints

Peer dependencies

Required:

• @agg-build/sdk
• react ^18.0.0 or ^19.0.0

Optional (only needed for wallet-based sign-in / deposits):

• wagmi ^2.0.0 (SIWE + ERC-20 deposits)
• viem ^2.0.0 (paired with wagmi)
• @solana/wallet-adapter-react ^0.15.0 (SIWS + SPL deposits)
• @solana/web3.js ^1.95.0

Links

• Documentation — https://docs.agg.market/
• Demo app — https://agg.market/
• Vanilla SDK — @agg-build/sdk
• Trading UI — @agg-build/ui
• Connect / sign-in UX — @agg-build/auth

License

MIT