---
title: Packages
description: "Four npm packages — pick the layer that fits your app"
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

# Packages

AGG ships four packages under `@agg-build`. Each builds on the one below it:

```
@agg-build/auth     → Auth UI + provider adapters
@agg-build/ui       → Pre-built React components (Liveline charts, orderbooks, pages)
@agg-build/hooks    → React hooks + providers (data fetching, WS, caching)
@agg-build/sdk      → Vanilla TypeScript client (REST + WebSocket + CandleBuilder)
```

Pick the highest layer you need. Lower layers are included as dependencies automatically.

| Package | Use when | Framework |
|---------|----------|-----------|
| `@agg-build/sdk` | Full control, or not using React (Node, React Native, vanilla JS) | None |
| `@agg-build/hooks` | React app, you build your own UI, you pick your own chart library | React |
| `@agg-build/ui` | You want drop-in components that work out of the box | React |
| `@agg-build/auth` | You want the connect/sign-in UI with pluggable auth methods | React |

---

## `@agg-build/sdk`

Framework-agnostic client for browsers, Node.js, and React Native. Zero peer dependencies and, as of
v4, zero runtime dependencies.

**REST client** — `createAggClient()` handles auth headers, in-memory session state, and request
helpers for the public REST API. Use `refreshAccessToken()` when you need to renew a user session.
Tokens are never persisted to storage — see
[Token storage](/recipes/authentication#token-storage) for what that means in React Native.

**WebSocket client** — `AggWebSocket` manages connection lifecycle, subscriptions, and live orderbook state for you.

**CandleBuilder** — Builds OHLCV candles from live orderbook and trade data so you can feed any chart library.

**Market aggregation** — `mergeCandles()` and `mergeClosedCandles()` merge per-venue candle data into a single aggregate view using volume-weighted averages.

[View on npm →](https://www.npmjs.com/package/@agg-build/sdk)

---

## `@agg-build/hooks`

React hooks and providers on top of `@agg-build/sdk`. Powered by TanStack React Query for caching, deduplication, and background refetch.

The hooks are **chart-library-agnostic** — they return generic data types (`LiveCandle[]`, `OrderbookState`, etc.) that you render however you want.

[View on npm →](https://www.npmjs.com/package/@agg-build/hooks)

---

## `@agg-build/ui`

Pre-built React components for charts, orderbooks, trading, and full page layouts. Styled with Tailwind CSS and fully themeable via CSS variables.

Components must be rendered inside `<AggProvider>`. They call hooks internally — no manual data fetching needed. Uses grouped entry points (`@agg-build/ui/pages`, `@agg-build/ui/events`, `@agg-build/ui/primitives`, etc.) for tree-shaking.

Browse the [components docs](/components/overview) for curated references, or open
[Storybook](https://storybook.agg.market) for the live component catalog and interactive states.
Use [Customize UI](/components/customization) for brand tokens, custom fonts, labels, formatting,
and layout slots.

[View on npm &rarr;](https://www.npmjs.com/package/@agg-build/ui)

---

## `@agg-build/auth`

Optional auth package with a modular adapter pattern and the `ConnectButton` chooser UI.

Auth stays separate so partners only install the wallet or OAuth dependencies they actually use,
while `@agg-build/ui` remains focused on market data and trading surfaces.

See the [Connect Button reference](/components/auth/connect-button) for the live auth surface.

### Built-in adapters

| Adapter | Import | Peer dependency |
|---------|--------|-----------------|
| SIWE (Ethereum) | `@agg-build/auth/siwe` | `wagmi` |
| SIWS (Solana) | `@agg-build/auth/siws` | `@solana/wallet-adapter-react`, `bs58` |
| Google OAuth | `@agg-build/auth` | None |
| Twitter/X OAuth | `@agg-build/auth` | None |
| Apple Sign In | `@agg-build/auth` | None |
| Email magic link | `@agg-build/auth` | None |

[View on npm &rarr;](https://www.npmjs.com/package/@agg-build/auth)

---

## Versioning

All packages use linked versioning. When one changes, the rest are versioned in lockstep so
compatible layers stay aligned.

See the [Changelog](/changelog) for the full release history and per-version notes across all four packages.

## Next steps

<Columns cols={2}>
  <Card title="Setup Guide" icon="gear" href="/api/setup">
    Provider configuration and code examples for each integration path.
  </Card>
  <Card title="Authentication" icon="key" href="/recipes/authentication">
    Wallet, OAuth, and email sign-in flows on top of the package stack.
  </Card>
  <Card title="Real-Time Charts" icon="cube" href="/recipes/websocket-charts">
    Use `CandleBuilder`, hooks, or UI components for live charting.
  </Card>
  <Card title="Component References" icon="grid-2" href="/components/overview">
    Browse the higher-touch AGG UI surfaces and jump to Storybook.
  </Card>
  <Card title="Customize UI" icon="paintbrush" href="/components/customization">
    Theme AGG components for your brand without forking UI internals.
  </Card>
  <Card title="Real-Time Orderbook" icon="brackets-curly" href="/recipes/websocket-orderbook">
    Build live orderbook views with venue attribution.
  </Card>
  <Card title="Funding & Withdrawals" icon="code" href="/recipes/deposits">
    Execution balances, deposit addresses, sync, and withdrawal workflows.
  </Card>
  <Card title="Changelog" icon="clock-rotate-left" href="/changelog">
    Release history and per-version notes across all four packages.
  </Card>
</Columns>