Setup Guide

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

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);
});

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:

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