Quickstart: React

You’ll need: an app ID (Base URL, app IDs & API keys), your site’s origin in the app’s allowed origins, and React 18 or later. Result: a React app with AGG data, sign-in, and a buy that is tracked to a final state.

Install the packages you need. See the Packages overview for what each one does and its peer dependencies. Every layer uses the same client from @agg-build/sdk.

1. Create the client and provider

Pick the layer that fits your app.

Hooks (bring your own UI)
UI components

Hooks handle WebSocket subscriptions, caching, and cleanup.

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/ws",
});

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AggProvider client={client}>
        <MyApp />
      </AggProvider>
    </QueryClientProvider>
  );
}

Then use hooks in any component:

import { useLiveMarket, useMarketChart, useSmartRoute } from "@agg-build/hooks";

function MarketView({ venueMarketId, venueMarketOutcomeId }) {
  const { orderbook } = useLiveMarket(venueMarketId);
  const { data: chart } = useMarketChart({
    marketId: venueMarketOutcomeId,
    interval: "5m",
    startTs: Date.now() - 86_400_000,
    endTs: Date.now(),
  });
  const { data: route } = useSmartRoute({
    venueMarketOutcomeId,
    tradeSide: "buy",
    maxSpend: 50,
  });

  const primaryVenue = chart?.primaryVenue;
  const candles = primaryVenue ? chart.venues[primaryVenue]?.candles ?? [] : [];

  return <YourChart data={candles} orderbook={orderbook} route={route} />;
}

Hook	What it does
`useLiveMarket(id)`	Live orderbook via WebSocket
`useMarketChart({ marketId, interval, startTs, endTs, countBack })`	Outcome chart history, under `data.primaryVenue`
`useSmartRoute({ venueMarketOutcomeId, tradeSide, maxSpend/sellShares })`	Quote across available liquidity
`useLiveTrades(id)`	Real-time trade feed
`useMarketOrderbook({ marketId })`	Aggregated orderbook and venue breakdown
`useMarketArb(marketId)`	Live cross-venue arbitrage return for one market
`useArbFeed()`	Live arbitrage returns for many markets

Pre-built, themed components.

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

const client = createAggClient({
  baseUrl: "https://api.agg.market",
  appId: "your-app-id",
  wsUrl: "wss://ws.agg.market/ws",
});

const queryClient = new QueryClient();

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

Then use components:

import { EventMarketPage } from "@agg-build/ui/pages";
import { MarketDetails } from "@agg-build/ui/events";
import { LineChart } from "@agg-build/ui/primitives";

// Full event page: hero chart, market cards, orderbooks, all live
<EventMarketPage eventId="..." />

// Or individual components
<MarketDetails event={event} marketId={marketId} defaultTab="graph" />
<LineChart series={series} chartType="candlestick" height={320} live />

See the Event Market Page and Market Details references, and Customize UI for fonts, colors, copy, and slots.

2. Sign the user in

@agg-build/auth adds a connect button and sign-in methods on top of the provider. Trading calls need a signed-in user.

import "@agg-build/ui/styles.css";
import { QueryClient, QueryClientProvider } from "@agg-build/hooks";
import { createAggClient } from "@agg-build/sdk";
import { AggProvider } from "@agg-build/ui";
import { AggAuthProvider, ConnectButton, createGoogleAuthMethod } from "@agg-build/auth";
import { useSiweAuthMethod } from "@agg-build/auth/siwe";
import { WagmiProvider } from "wagmi";
import { wagmiConfig } from "./wagmi-config";

const client = createAggClient({
  baseUrl: "https://api.agg.market",
  appId: "your-app-id",
  wsUrl: "wss://ws.agg.market/ws",
});

const queryClient = new QueryClient();

function AuthButton() {
  const siwe = useSiweAuthMethod({ statement: "Sign in" });
  return (
    <AggAuthProvider methods={[siwe, createGoogleAuthMethod()]}>
      <ConnectButton />
    </AggAuthProvider>
  );
}

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <AggProvider client={client}>
          <AuthButton />
        </AggProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

See the Connect Button reference and Authentication & sessions for every provider.

3. Buy and track to a final state

The user needs a balance first. See Funding & withdrawals for deposit addresses. Then quote, fill, and poll the execution status until terminal is true.

import { useState } from "react";
import { useQuery } from "@tanstack/react-query";
import { useAggClient, useExecuteManaged, useSmartRoute } from "@agg-build/hooks";

function BuyButton({ venueMarketOutcomeId }: { venueMarketOutcomeId: string }) {
  const client = useAggClient();
  const [quoteId, setQuoteId] = useState<string | null>(null);

  const { data: quote } = useSmartRoute({ venueMarketOutcomeId, tradeSide: "buy", maxSpend: 5 });
  const execute = useExecuteManaged({ onSuccess: (fill) => setQuoteId(fill.quoteId) });

  const { data: status } = useQuery({
    queryKey: ["execution-status", quoteId],
    queryFn: () => client.getExecutionStatus({ quoteId: quoteId! }),
    enabled: !!quoteId,
    // Poll at the interval the API suggests; stop once the trade is terminal.
    refetchInterval: (query) =>
      query.state.data?.terminal ? false : (query.state.data?.pollAfterMs ?? 1000),
  });

  if (status?.terminal) return <p>Done: {status.overallState}</p>;
  if (quoteId) return <p>Executing: {status?.overallState ?? "created"}</p>;

  return (
    <button
      className="cursor-pointer disabled:cursor-not-allowed"
      disabled={quote?.status !== "ok" || execute.isPending}
      onClick={() => quote && execute.mutate({ quoteId: quote.quoteId })}
    >
      Buy $5
    </button>
  );
}

Stop polling when terminal is true. overallState then reads filled, partially_filled, failed, cancelled, or expired. Read Order lifecycle & statuses for what each state means.

WebSocket endpoint

The SDK and hooks manage the socket, reconnection, resnapshots, and orderbook integrity checks. If you open raw sockets yourself, connect to:

wss://ws.agg.market/ws?appId=YOUR_APP_ID

See WebSocket Protocol.

Next steps

Quickstart: REST

The same flow with curl, for backends and agents.

Order lifecycle

Every order status and how to track it.

Real-Time Orderbook

Live orderbook rendering with the SDK, hooks, and UI.

Customize UI

Brand AGG components with CSS variables, labels, formatting, and slots.

Start here

Core concepts

SDK reference

Account & identity

Trading guides

Market data & discovery

Security & compliance

Real-time

Webhooks

UI Kit

Releases

1. Create the client and provider

2. Sign the user in

3. Buy and track to a final state

WebSocket endpoint

Next steps

Quickstart: REST

Order lifecycle

Real-Time Orderbook

Customize UI

​1. Create the client and provider

​2. Sign the user in

​3. Buy and track to a final state

​WebSocket endpoint

​Next steps

Quickstart: REST

Order lifecycle

Real-Time Orderbook

Customize UI

1. Create the client and provider

2. Sign the user in

3. Buy and track to a final state

WebSocket endpoint

Next steps