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.

Testing mode limits

All new partner apps start in testing mode — a sandboxed state that lets you build and verify your integration without committing to the full live-mode agreement. Two hard caps apply while an app is in testing mode:

Limit	Cap	Applies to
Users	20	Unique users who sign in to your app
Trades	100	Orders placed (excluding failed orders)

Existing users can always sign in — the user cap only blocks new account creation once the limit is reached. No data is lost when the cap is hit.

How the limits work

When a new user tries to sign in and the app has already registered 20 users, the sign-in endpoint (POST /auth/verify) returns a 403 with a plain-language message explaining the situation. Likewise, when a new trade is submitted after 100 trades have been placed, the execution endpoint returns a 403. Both error responses use the message field of the standard { message: string } error body — you can surface this text directly in your UI without any special-casing.

// POST /auth/verify — over the user cap
{
  "statusCode": 403,
  "message": "This app has reached its testing limit of 20 users. Sign the partner agreement to enable live mode and continue adding users."
}

// POST /execution/fill — over the trade cap
{
  "statusCode": 403,
  "message": "This app has reached its testing limit of 100 trades. Sign the partner agreement to enable live mode and continue placing trades."
}

For OAuth and magic-link sign-in flows, the same error is surfaced as a message query parameter on the redirect URL (alongside an error=testing_user_limit_reached param your frontend can key off).

Lifting the limits — signing the partner agreement

Once you are ready to go live, sign the partner agreement from the admin dashboard (Apps → your app → Go Live). Signing sets partnerAgreementSigned = true on your app and immediately removes both caps — no restart or config change needed. The agreement is a one-time action; it cannot be reversed from the dashboard. After signing:

New users can sign in without restriction.
New trades can be placed without restriction.
Existing testing-mode users and trades are preserved; the historical counts are not reset.

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

​Testing mode limits

​How the limits work

​Lifting the limits — signing the partner agreement

​Next steps

Authentication

WebSocket Protocol

Real-Time Orderbook

Real-Time Charts

Customize UI

Setup Guide

WebSocket endpoint

Testing mode limits

How the limits work

Lifting the limits — signing the partner agreement

Next steps