@agg-build/auth

Modular connect / sign-in UI and auth-method adapters for the AGG prediction market aggregator. Drop in a ConnectButton, pick the auth methods you want to enable (SIWE, SIWS, Google, Apple, Twitter/X, email magic-link), and ship.

What it is

@agg-build/auth keeps provider-specific auth integrations out of @agg-build/ui. Each auth method ships as a separate adapter — wallet providers (SIWE, SIWS) stay behind subpath imports so their peer dependencies are only pulled in when you actually enable them. AggAuthProvider orchestrates the flow end-to-end: opening the chooser, driving wallet sign-in, redirecting to OAuth providers, emailing magic links, handling the post-redirect code exchange, and transparently solving Cloudflare Turnstile challenges when the API requires them.

When to use this package

• You want AGG's connect / sign-in UX without rebuilding it.
• You want to enable only the auth methods your app supports.
• You want redirect callback handling (OAuth + email magic-link) solved for you.
• You want Cloudflare Turnstile challenge handling built in.

If you prefer to roll your own wallet UI, skip this package and use useAggAuth from @agg-build/hooks directly.

Install

Core packages:

npm install @agg-build/sdk @agg-build/hooks @agg-build/ui @agg-build/auth liveline

Add only the optional peers you need:

# SIWE / Ethereum
npm install wagmi viem

# SIWS / Solana
npm install @solana/wallet-adapter-react bs58

Google, Apple, Twitter/X, and email magic-link flows don't require any extra peers — they are plain redirect-based flows driven by the SDK.

Quick start

import "@agg-build/ui/styles.css";
import { AggProvider } from "@agg-build/hooks";
import { createAggClient } from "@agg-build/sdk";
import {
  AggAuthProvider,
  ConnectButton,
  createAppleAuthMethod,
  createEmailAuthMethod,
  createGoogleAuthMethod,
  createTwitterAuthMethod,
} from "@agg-build/auth";
import { useSiweAuthMethod } from "@agg-build/auth/siwe";
import { useSiwsAuthMethod } from "@agg-build/auth/siws";
import { WagmiProvider } from "wagmi";
import { wagmiConfig } from "./wagmi-config";

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

function AuthActions() {
  const siwe = useSiweAuthMethod({ statement: "Sign in to AGG" });
  const siws = useSiwsAuthMethod({ cluster: "mainnet", statement: "Sign in to AGG" });

  return (
    <AggAuthProvider
      methods={[
        siwe,
        siws,
        createGoogleAuthMethod(),
        createAppleAuthMethod(),
        createTwitterAuthMethod(),
        createEmailAuthMethod(),
      ]}
    >
      <ConnectButton />
    </AggAuthProvider>
  );
}

export default function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <AggProvider client={client}>
        <AuthActions />
      </AggProvider>
    </WagmiProvider>
  );
}

AggAuthProvider watches the current URL on mount. For redirect-based methods it reads the code query parameter, calls client.exchangeAuthCode(code), then cleans the URL. No extra setup required if the user lands back on the same app.

Dedicated callback route

If your app routes redirects to a separate callback page, hydrate the exchange yourself with useAggAuthCallback:

import { useAggAuthCallback } from "@agg-build/auth";

export function AuthCallbackPage() {
  const { error, isHandled, isHandling, user } = useAggAuthCallback();

  if (isHandling) return <p>Finishing sign-in…</p>;
  if (error) return <p>{error.message}</p>;
  if (isHandled) return <p>Signed in as {user?.id}</p>;

  return <p>No AGG auth callback data was found.</p>;
}

The callback hook follows the same recipe:

1. Parse the code query parameter.
2. Call client.exchangeAuthCode(code).
3. Remove code from the URL via window.history.replaceState(...).

Turnstile challenges

When the AGG API returns challenge_required, AggAuthProvider automatically renders a Cloudflare Turnstile widget, submits the solved token, and retries the request. The widget is invisible on success and degrades gracefully if a user's environment blocks Turnstile. You do not need to render or configure the widget directly.

Available auth methods

| Import path | Export | Peer deps | Notes | | ---------------------- | --------------------------- | -------------------------------------- | ---------------------------------------- | | @agg-build/auth | createEmailAuthMethod() | — | Magic-link email flow | | @agg-build/auth | createGoogleAuthMethod() | — | Redirect-based OAuth | | @agg-build/auth | createAppleAuthMethod() | — | Redirect-based OAuth | | @agg-build/auth | createTwitterAuthMethod() | — | Redirect-based OAuth | | @agg-build/auth/siwe | useSiweAuthMethod() | wagmi | Ethereum wallet sign-in | | @agg-build/auth/siws | useSiwsAuthMethod() | @solana/wallet-adapter-react, bs58 | Solana wallet sign-in; Ledger-compatible |

Pass the methods you want to enable to AggAuthProvider — the ConnectButton chooser only lists methods you include.

Custom redirect URL / navigation

Redirect-based adapters accept a redirectUrl and optional navigate function:

createGoogleAuthMethod({
  redirectUrl: "https://yourapp.com/auth/callback",
  navigate: (url) => window.top?.location.assign(url),
});

Custom wallet picker (SIWE)

useSiweAuthMethod accepts an optional connectorPicker to render your own wallet chooser modal instead of wagmi's default:

const siwe = useSiweAuthMethod({
  connectorPicker: async (connectors) => showMyWalletModal(connectors),
});

ConnectButton props

| Prop | Type | Description | | -------------------- | --------------------------------------------------- | -------------------------------------------- | | buttonProps | ConnectButtonButtonProps | Props passed to the inner Button component | | classNames | ConnectButtonClassNames | Style overrides for sub-elements | | disabled | boolean | Disable the button | | onAuthMethodSelect | (methodId: AuthMethodId) => void \| Promise<void> | Called when user picks an auth method | | onDepositClick | () => void \| Promise<void> | Called when user clicks deposit | | onDisconnect | () => void \| Promise<void> | Called on disconnect | | onProfileClick | () => void \| Promise<void> | Called when user clicks profile | | onWithdrawClick | () => void \| Promise<void> | Called when user clicks withdraw |

When authenticated, the button collapses into the user's profile chip with action buttons (deposit, withdraw, profile, disconnect). Use the callback props to wire them to your app's navigation or modal system.

Main exports

| Import path | Export | Description | | ---------------------- | ------------------------- | --------------------------------------------------------------- | | @agg-build/auth | AggAuthProvider | Orchestrates the chooser, redirect callback, and Turnstile | | @agg-build/auth | ConnectButton | Drop-in connect / account chip | | @agg-build/auth | useAggAuthFlow | Access the chooser/flow state (used by custom UIs) | | @agg-build/auth | useAggAuthCallback | Manually hydrate the redirect callback page | | @agg-build/auth | createEmailAuthMethod | Magic-link email adapter | | @agg-build/auth | createGoogleAuthMethod | Google OAuth adapter | | @agg-build/auth | createAppleAuthMethod | Apple OAuth adapter | | @agg-build/auth | createTwitterAuthMethod | Twitter/X OAuth adapter | | @agg-build/auth/siwe | useSiweAuthMethod | SIWE adapter (requires wagmi) | | @agg-build/auth/siws | useSiwsAuthMethod | SIWS adapter (requires @solana/wallet-adapter-react + bs58) |

Architecture

• @agg-build/sdk owns auth API calls and session-token storage.
• @agg-build/hooks owns shared auth/session state inside AggProvider.
• @agg-build/ui ships generic UI primitives only.
• @agg-build/auth ships auth-method adapters + the connect/sign-in UX.

Entrypoints

| Entry | Purpose | | -------------------------------- | ---------------------------------------------------------------------------- | | @agg-build/auth | AggAuthProvider, ConnectButton, OAuth + email adapters | | @agg-build/auth/connect-button | ConnectButton component only (narrow import) | | @agg-build/auth/oauth | createAppleAuthMethod, createGoogleAuthMethod, createTwitterAuthMethod | | @agg-build/auth/email | createEmailAuthMethod | | @agg-build/auth/siwe | useSiweAuthMethod (requires wagmi) | | @agg-build/auth/siws | useSiwsAuthMethod (requires Solana wallet adapter) |

Peer dependencies

Required:

• @agg-build/hooks
• @agg-build/ui
• react ^18.0.0 or ^19.0.0
• react-dom ^18.0.0 or ^19.0.0

Optional (tied to specific adapters):

• wagmi ^3.5.0 — SIWE
• @solana/wallet-adapter-react ^0.15.39 — SIWS
• bs58 ^6.0.0 — SIWS signature encoding

Links

• Documentation — https://docs.agg.market/
• Storybook — https://storybook.agg.market/
• Demo app — https://demo.agg.market/
• Vanilla SDK — @agg-build/sdk
• React hooks — @agg-build/hooks
• Trading UI — @agg-build/ui

License

MIT