Setup Guide

Choose your integration path and follow the setup for your layer. See the Packages overview for installation, package descriptions, and peer dependencies.

Need sign-in flows? Start with Authentication. For wire-level streaming details, see WebSocket Protocol. For end-to-end implementations, see Real-Time Orderbook and Real-Time Charts. For theming and partner branding, see Customize UI.

SDK (vanilla JS/TS)
React (hooks)
React (UI components)
React (with auth)

No framework dependency. Works in browsers, Node.js, and React Native.

import { createAggClient, CandleBuilder } from "@agg-build/sdk";

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

// REST: fetch events, orderbooks, charts
const events = await client.getVenueEvents({ limit: 10 });
const books = await client.getOrderbooks({
  venueMarketIds: ["your-market-id"],
  depth: 20,
});
const bars = await client.getChartBars({
  venueMarketOutcomeId: "...",
  resolution: "5m",
  to: Date.now(),
  countBack: 200,
});
const route = await client.getSmartRoute({ venueMarketId: "...", maxSpend: 50, side: "yes" });

const book = books.data[0];
if (book?.status !== "ok") {
  throw new Error(book?.error?.message ?? "No live orderbook available");
}

// WebSocket: real-time orderbook + trades
const builder = new CandleBuilder();
const ws = client.createWebSocket({
  onSnapshot: (id, book) => {
    if (book.midpoint != null) builder.addMidpoint(book.midpoint, book.timestamp);
  },
  onDelta: (id, book) => {
    if (book.midpoint != null) builder.addMidpoint(book.midpoint, book.timestamp);
  },
  onTrade: (trade) => {
    builder.addTrade(trade.price, trade.size, trade.timestamp);
  },
});

ws.subscribe("your-market-id");

// Read candles for any chart library
builder.onChange(() => {
  const candles = builder.getClosed("5m");
  const forming = builder.getForming("5m");
  yourChart.update(candles, forming);
});

Bring your own UI. Hooks handle WS 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({
    venueMarketId,
    maxSpend: 50,
    side: "yes",
  });

  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 WS
`useMarketChart({ marketId, interval, startTs, endTs, countBack })`	Outcome-id chart history, exposed under `data.primaryVenue`
`useSmartRoute({ venueMarketId, maxSpend, side })`	User-scoped route quote across available liquidity
`useLiveTrades(id)`	Real-time trade feed
`useMarketOrderbook({ marketId })`	Aggregated orderbook + venue breakdown
`useMarketArb(marketId)`	Live cross-venue arbitrage return for one market
`useArbFeed()`	Live arbitrage returns for many markets (`byMarket` map + event-level `byEvent` max)

Pre-built, themed components. Drop in and go.

import "@agg-build/ui/styles.css";
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}
        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 />

Browse the live Event Market Page reference and Market Details reference. Use Customize UI for fonts, colors, copy, formatting, and slot overrides.

Full stack with connect/sign-in UI. See Authentication for detailed flow examples.

import "@agg-build/ui/styles.css";
import { AggProvider, QueryClient, QueryClientProvider } from "@agg-build/hooks";
import { createAggClient } from "@agg-build/sdk";
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>
  );
}

Browse the live Connect Button reference.

WebSocket endpoint

If you create raw sockets yourself, connect to:

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

The SDK and hooks manage connection, reconnection, resnapshot requests, and orderbook integrity checks automatically.

Next steps

Authentication

Add wallet, OAuth, or email sign-in on top of the base client setup.

WebSocket Protocol

Review the wire format, auth upgrade flow, heartbeat, and reconnection behavior.

Real-Time Orderbook

SDK, hooks, and UI recipes for live orderbook rendering.

Real-Time Charts

Build live OHLCV charts from REST history and WebSocket updates.

Customize UI

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

​Setup Guide

​WebSocket endpoint

​Next steps