@agg-build/sdk

Vanilla TypeScript client for the AGG prediction market aggregator — one client, every surface (auth, markets, orderbooks, charts, trading, managed execution, WebSockets).

What it is

@agg-build/sdk is the lowest-level package partners install. It speaks to the AGG API over HTTPS and WebSockets, manages auth/session state, and exposes typed wrappers for every product endpoint (markets, orderbooks, charts, trade execution, deposits/withdrawals, managed wallets, admin and more). It has no framework dependency and works in browsers, Node.js, and React Native.

For React apps, layer @agg-build/hooks, @agg-build/ui, and @agg-build/auth on top — they all use this client under the hood.

When to use this package

• You are building a vanilla TS/JS app, React Native app, or server-side integration.
• You want a typed, batteries-included client for the AGG REST API and WebSocket gateway.
• You are authoring your own React layer and need the underlying auth/session/trade primitives.
• You need a server-only helper: SSR config fetching, webhook verification, external-ID signing, or the admin API client (see @agg-build/sdk/server).

If you are shipping a React app and want ready-made hooks or UI, install @agg-build/hooks, @agg-build/ui, and @agg-build/auth instead — those packages are built on top of @agg-build/sdk.

Install

npm install @agg-build/sdk

Quick start

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

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

// Health check
const hello = await client.getHello();

// Current auth state (persisted across reloads via localStorage)
console.log(client.isAuthenticated, client.user);

Authenticate a user (SIWE)

// 1. Start the auth flow
const { nonce } = await client.authStart({ provider: "siwe" });

// 2. Build the EIP-4361 message
const message = client.buildSiweMessage({
  address: "0x…",
  chainId: 1,
  nonce,
  domain: window.location.host,
  uri: window.location.origin,
});

// 3. Sign with the user's wallet (wagmi, viem, ethers, …)
const signature = await wallet.signMessage(message);

// 4. Verify → stores accessToken + user in the client
const { accessToken, user } = await client.verify({ message, signature });

SIWS (Solana) uses the same flow with buildSiwsMessage and a base58-encoded Ed25519 signature.

Redirect flows (Google, Apple, Twitter, email magic-link) return a URL to navigate to:

const response = await client.authStart({
  provider: "google",
  redirectUrl: "https://yourapp.com/auth/callback",
});

if (response.type === "redirect") {
  window.location.assign(response.url);
}

// …back on the callback page:
const code = new URLSearchParams(window.location.search).get("code");
if (code) {
  await client.exchangeAuthCode(code);
  window.history.replaceState(null, "", window.location.pathname);
}

HttpOnly cookie-refresh mode

For browser apps that prefer an HttpOnly refresh cookie over storing the refresh token in JS, construct the client with authDelivery: "cookie-refresh":

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

In this mode, verify() and exchangeAuthCode() may omit refreshToken from the returned object. The refresh cookie stays scoped to the AGG API host under /auth and is never exposed to partner frontend domains.

Streaming data (WebSocket)

const ws = client.createWebSocket({
  onSnapshot: (outcomeId, book) => console.log("snapshot", outcomeId, book),
  onDelta: (outcomeId, book) => console.log("delta", outcomeId, book),
  onTrade: (trade) => console.log("trade", trade.venue, trade.price, trade.size),
});

// Orderbooks are keyed by venueMarketOutcomeId (the `outcomes[].id` on REST).
const unsubscribe = ws.subscribe("venue-market-outcome-id");

// Optional: authenticate for user-scoped events (orders, balances)
ws.authenticate(accessToken);

// Cleanup
unsubscribe();
ws.destroy();

createWebSocket requires wsUrl to be passed to createAggClient. The underlying AggWebSocket can also be instantiated directly if you want finer control.

Server-side helpers

Import from the /server entrypoint for Node-only utilities:

import { AggAdminClient, signExternalId, verifyWebhook } from "@agg-build/sdk/server";

// Sign a partner external-ID assertion before sending to the browser
const assertion = signExternalId(process.env.AGG_APP_SECRET!, partnerUser.id);

// Verify an inbound webhook
verifyWebhook(rawBody, req.headers, process.env.AGG_WEBHOOK_SECRET!);

// Admin API client (uses x-app-api-key)
const admin = new AggAdminClient({
  baseUrl: "https://api.agg.market",
  apiKey: process.env.AGG_APP_API_KEY!,
});
const users = await admin.listUsers("your-app-id", { limit: 50 });

Client options

Call client.destroy() when you no longer need the client to release internal resources (BroadcastChannel used for cross-tab auth sync).

Main exports

AggClient methods

Auth & session

User profile & accounts

Market data

Correlated Markets

Orderbooks & routing

Chart data

Trading

Venue keys

Managed execution & balances

To quote and fill a managed trade, target a venue market outcome. Buys are budgeted with maxSpend; sells specify the number of contracts with sellShares. Pass the returned quoteId to executeManaged():

const buyRoute = await client.getSmartRoute({
  venueMarketOutcomeId,
  tradeSide: "buy",
  maxSpend: 50,
});
await client.executeManaged({ quoteId: buyRoute.quoteId });

const sellRoute = await client.getSmartRoute({
  venueMarketOutcomeId,
  tradeSide: "sell",
  sellShares: 10,
});
await client.executeManaged({ quoteId: sellRoute.quoteId });

venueMarketId, outcomeId, and side: "yes" | "no" remain deprecated compatibility aliases; new integrations should use venueMarketOutcomeId and tradeSide.

Removed in v4. quoteManaged() was deleted — its endpoint, POST /execution/quote, does not exist on the API, so the call only ever returned 404. Use the two-step flow above.

Orders & positions

Leaderboard

Utilities

Standalone utilities

Error handling

Every non-2xx response is thrown as an AggApiError carrying status, and — when the API supplies them — code, retryable and per-field errors. Branch on status/code rather than matching message text; messages are human-facing and may be reworded.

import { isAggApiError } from "@agg-build/sdk";

try {
  await client.getPositions();
} catch (err) {
  if (isAggApiError(err)) {
    if (err.status === 401) return promptReconnect(); // session lapsed
    if (err.code === "unregistered_domain") {
      // The signed SIWE `domain` is not in the app's allowedOrigins.
      // Note this is NOT the Origin header — sign-in works with no Origin
      // at all, which is what makes Node and React Native work.
    }
  }
  throw err;
}

@agg-build/sdk/server

WebSocket callbacks

Orderbook books are keyed by outcome. OrderbookState.outcomeId is the identity of a book; the deprecated OrderbookState.marketId holds the same outcome id, not a venue market id, because orderbook frames carry no market id. Use the REST venueMarketId (e.g. from getOutcomeOrderbooks) or your own outcome → market mapping when you need the market.

Key behaviors:

• Single persistent connection with refcounted per-market subscriptions. orderbookUrl moves the orderbook channel onto a second socket and reports it through onOrderbookConnectionStateChange. An orderbook-only subscription does not keep wsUrl connected. Trades, arb, catalog, and user events stay on wsUrl.
• In-memory orderbook state per market (snapshot + delta with CRC32 verification).
• Sequence gap or checksum mismatch triggers automatic resnapshot.
• snapshot_unavailable retries only affected active outcomes, with up to three jittered retries and at most 20 outcomes retried per second per socket. Errors still reach onError; successful snapshots, unsubscribe, and socket closure cancel pending retries. Missing replies remain covered by the optional book watchdog.
• Auto-reconnect with exponential backoff (base 1s, max 30s).
• Liveness: no message for 45s triggers reconnect; server heartbeats every 30s.
• Bids always sorted descending, asks always sorted ascending.

Headers attached automatically

• x-app-id — from the appId option
• Authorization: Bearer <jwt> — after sign-in
• x-admin-key — if adminKey is provided
• x-auth-delivery: cookie-refresh + credentials: "include" on auth-only requests when authDelivery: "cookie-refresh" is enabled

Entrypoints

Peer dependencies

None — and as of v4, no runtime dependencies either. The only module the bundle imports is node:crypto (used by @agg-build/sdk/server), so a fresh install is under 1 MB with nothing transitive.

Bring your own wallet library. The SDK builds SIWE/SIWS message strings and never signs anything itself, so viem, ethers, or any other signer works — you pass in a signMessage function.

Changed in v4. Earlier versions declared viem, ethers@5, @polymarket/clob-client and @polymarket/builder-signing-sdk as runtime dependencies. No code path ever imported them, but installers still paid for them — roughly 100 MB of node_modules across their transitive trees. They were removed in v4; nothing in the SDK's behaviour changed.

Links

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

License

MIT

Venue event read admission

getVenueEventById shares concurrent identical reads within each client and auth session (including normalized cluster and minVolume query values). It retains no completed result cache. At most four distinct event reads run concurrently; up to 128 wait in FIFO order. A full queue rejects with AggApiError status 429, code client_read_queue_full, and a retry delay hint.

A server 429 still rejects the original call without an automatic retry. New and queued event reads honor its Retry-After delay plus up to 250ms positive jitter; missing hints use one second. Callers may cancel independently; the shared fetch is cancelled only after all callers leave. Queued reads reject with AbortError if authentication changed before admission. destroy() cancels pending reads. Other read methods and write methods keep their existing retry behavior.