Skip to main content

​
Packages

AGG ships three npm packages under the @agg-market org. Pick the layer that fits your stack: 
@agg-market/ui       React components (drop-in trading UI)
  └── @agg-market/hooks  React hooks (auth, data fetching)
       └── @agg-market/sdk   Vanilla TypeScript client (any JS environment)
PackageUse whenPeer dependencies
@agg-market/sdkYou’re not using React, or you want full controlNone
@agg-market/hooksYou’re building a React app and want auth + data hooks@agg-market/sdk, react
@agg-market/uiYou want pre-built trading UI components@agg-market/hooks, react, react-dom

​
Installation

Install only what you need — each package declares its dependencies on the layers below.

​
@agg-market/sdk

Vanilla TypeScript client. Works in browsers, Node.js, and React Native — no framework dependency.

​
Setup

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

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

​
Key methods

MethodDescription
getNonce()Get a one-time nonce for SIWE sign-in
buildSiweMessage(params)Build an EIP-4361 message string
verifySignIn({ message, signature })Verify signature and get a JWT
signOut()Clear auth state
isAuthenticatedCheck if user is signed in
userGet the current user
onAuthStateChange(listener)Subscribe to auth state changes

​
Auth persistence

The SDK automatically persists auth sessions to localStorage (keyed by appId) and restores them on construction. Partners don’t need to manage tokens.

​
Headers

The SDK automatically attaches the correct headers on every request:
  • x-app-id — from the appId you provided
  • Authorization: Bearer <jwt> — after sign-in
  • x-admin-key — if you provided an adminKey

​
@agg-market/hooks

React hooks that wrap @agg-market/sdk. Provides auth flows and data fetching out of the box.

​
Provider setup

Wrap your app in <AggProvider>: 
import { AggProvider } from "@agg-market/hooks";
import { createAggClient } from "@agg-market/sdk";

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

function App() {
  return (
    <AggProvider client={client}>
      {/* your app */}
    </AggProvider>
  );
}

​
Hooks

HookDescription
useAggClient()Access the AggClient instance from context
useAggAuth({ signMessage, address, chainId })Full SIWE sign-in flow — returns { signIn, signOut, isAuthenticated, user, isLoading, error }
useHello()Health check — returns { data, error, isLoading }

​
SIWE sign-in flow

useAggAuth orchestrates the entire Sign-In with Ethereum flow:
  1. Fetches a one-time nonce from the API
  2. Builds an EIP-4361 message
  3. Prompts the user’s wallet to sign
  4. Sends the signature to the API for verification
  5. Stores the returned JWT
import { useAggAuth } from "@agg-market/hooks";
import { useAccount, useSignMessage } from "wagmi";

function SignIn() {
  const { address, chainId } = useAccount();
  const { signMessageAsync } = useSignMessage();
  const { signIn, signOut, isAuthenticated, user } = useAggAuth({
    signMessage: signMessageAsync,
    address,
    chainId,
  });

  if (isAuthenticated) {
    return (
      <div>
        <p>Signed in as {user?.address}</p>
        <button onClick={signOut}>Sign out</button>
      </div>
    );
  }

  return <button onClick={signIn}>Sign in with Ethereum</button>;
}

​
@agg-market/ui

Pre-built React components for prediction market UIs. Must be rendered inside an <AggProvider>.

​
Styling

Import the default theme CSS once at your app entrypoint: 
import "@agg-market/ui/styles.css";
Override theme tokens with CSS variables on your .agg-root container: 
.agg-root {
  --agg-color-primary: #your-brand-color;
  --agg-color-foreground: #1a1a1a;
  --agg-radius-md: 8px;
  --agg-font-family-sans: "Inter", sans-serif;
}

​
Tree-shaking

Each component is a separate entry point for optimal bundle size: 
// Good — only loads the button code
import { Button } from "@agg-market/ui/button";

// Avoid — loads everything
import { Button } from "@agg-market/ui";

​
Available components

Import pathComponentDescription
@agg-market/ui/buttonButtonBase button component
@agg-market/ui/connect-buttonConnectButtonWallet connection button
@agg-market/ui/hello-worldHelloWorldAPI health check display
@agg-market/ui/cardCardContent card
@agg-market/ui/chartChartPrice chart
@agg-market/ui/skeletonSkeletonLoading placeholder
@agg-market/ui/iconIconIcon set
@agg-market/ui/badgeBadgeStatus badge
@agg-market/ui/tabsTabsTab navigation
@agg-market/ui/selectSelectDropdown select
@agg-market/ui/searchSearchSearch input
@agg-market/ui/modalModalDialog/modal
@agg-market/ui/event-listEventListList of prediction market events
@agg-market/ui/event-list-itemEventListItemSingle event row
@agg-market/ui/market-detailsMarketDetailsFull market detail view
@agg-market/ui/place-orderPlaceOrderOrder entry form
@agg-market/ui/settlementSettlementSettlement status
@agg-market/ui/home-pageHomePageFull home page layout
@agg-market/ui/event-market-pageEventMarketPageFull event/market page
@agg-market/ui/onboarding-modalOnboardingModalUser onboarding flow

​
Versioning

All three packages use linked versioning — when any package changes, all three get the same version bump. Partners always see matching version numbers across the stack. We use Changesets for version management. Every PR that changes a published package must include a changeset describing the change and its semver impact.

​
Provenance

All packages are published with npm provenance via GitHub Actions OIDC. You can verify that any version was built from the source in this repository.