Installation

Install AomiWidget to add application-bound chat, wallet authentication, and transaction approval to your React app. Your frontend selects the App and sign-in method, and the connected wallet handles requests the user approves.

Prerequisites

Before you start, you need:

An activated Aomi App and its numeric Application ID.
An HTTPS origin for production, added to the selected wallet provider’s allowlist.
React 18 or 19 running in the browser.
A decision between browser-wallet, Para, or Privy authentication.

In Next.js, mount the widget from a client component. The widget uses browser wallet APIs and cannot render as a server-only component.

Install

npm install @aomi-labs/widget-lib

Provider integrations are separate entry points. Import only the provider your application uses so unrelated provider code stays out of the bundle.

File structure

The widget needs one client component and one environment file. It does not require a custom API route or transaction broadcaster.

Next.js
Vite

your-app/
├── app/
│   └── assistant/
│       └── page.tsx       # Client component that mounts AomiWidget
├── .env.local             # Public widget configuration
└── package.json

your-app/
├── src/
│   ├── App.tsx            # Mounts AomiWidget
│   └── main.tsx
├── .env.local             # Public widget configuration
└── package.json

Environment variables

Next.js
Vite

NEXT_PUBLIC_AOMI_API_URL=https://chat.aomi.dev
NEXT_PUBLIC_AOMI_APPLICATION_ID=123

# Add only the values required by your wallet mode
NEXT_PUBLIC_PARA_API_KEY=your_public_para_api_key
NEXT_PUBLIC_PRIVY_APP_ID=your_public_privy_app_id
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_public_walletconnect_project_id

VITE_AOMI_API_URL=https://chat.aomi.dev
VITE_AOMI_APPLICATION_ID=123

# Add only the values required by your wallet mode
VITE_PARA_API_KEY=your_public_para_api_key
VITE_PRIVY_APP_ID=your_public_privy_app_id
VITE_WALLETCONNECT_PROJECT_ID=your_public_walletconnect_project_id

Variable	Purpose
`AOMI_API_URL`	The Aomi origin that serves widget sessions, chat, and account APIs
`AOMI_APPLICATION_ID`	The deployed App selected by the widget
`PARA_API_KEY`	Para’s public browser identifier; required for Para mode
`PRIVY_APP_ID`	Privy’s public browser identifier; required for Privy mode
`WALLETCONNECT_PROJECT_ID`	Public WalletConnect project identifier; required only when WalletConnect is enabled

These names are conventions for your host application. Pass values to apiUrl, applicationId, and the selected auth object. In current source, Para accepts auth.apiKey and Privy accepts auth.appId; do not rely on a published package reading your framework’s environment variables internally. Use process.env.NEXT_PUBLIC_* in Next.js or import.meta.env.VITE_* in Vite at the call site. These identifiers are public; provider secrets stay on your server.

Explicit provider props describe the current source contract. Check your installed widget release and provider allowlists before using the example. See package and API compatibility.

Never put an App key, provider secret, paymaster URL, gas-policy credential, treasury address, or fee configuration in browser code.

Choose authentication

Authentication establishes the user session. Wallet ownership establishes which address may approve transactions. Aomi verifies these separately.

Mode	Use it when	User experience
Browser wallet	Users already have a compatible EVM or Solana wallet	Connect a wallet and sign SIWE or SIWS, depending on the wallet
Para	You want Para social login and embedded wallets	Sign in with Para, then use the active embedded or connected wallet
Privy	You want Privy login and embedded wallets	Sign in with Privy, then use the active embedded wallet

Browser wallet
Para
Privy

Browser mode authenticates an existing EVM or Solana wallet. It does not require a Para or Privy provider import.

"use client";

import { AomiWidget } from "@aomi-labs/widget-lib";
import "@aomi-labs/widget-lib/styles.css";

export default function AssistantPage() {
  return (
    <AomiWidget
      applicationId={process.env.NEXT_PUBLIC_AOMI_APPLICATION_ID!}
      apiUrl={process.env.NEXT_PUBLIC_AOMI_API_URL!}
      auth={{ kind: "browser_wallet" }}
      height="calc(100dvh - 32px)"
    />
  );
}

Importing the Para entry point registers Para authentication and its wallet signer.

"use client";

import { AomiWidget } from "@aomi-labs/widget-lib";
import "@aomi-labs/widget-lib/providers/para";
import "@aomi-labs/widget-lib/styles.css";

export default function AssistantPage() {
  return (
    <AomiWidget
      applicationId={process.env.NEXT_PUBLIC_AOMI_APPLICATION_ID!}
      apiUrl={process.env.NEXT_PUBLIC_AOMI_API_URL!}
      auth={{
        kind: "embedded_wallet",
        provider: "para",
        apiKey: process.env.NEXT_PUBLIC_PARA_API_KEY!,
        environment: "PROD",
      }}
      height="calc(100dvh - 32px)"
    />
  );
}

Importing the Privy entry point registers Privy authentication and its wallet signer.

"use client";

import { AomiWidget } from "@aomi-labs/widget-lib";
import "@aomi-labs/widget-lib/providers/privy";
import "@aomi-labs/widget-lib/styles.css";

export default function AssistantPage() {
  return (
    <AomiWidget
      applicationId={process.env.NEXT_PUBLIC_AOMI_APPLICATION_ID!}
      apiUrl={process.env.NEXT_PUBLIC_AOMI_API_URL!}
      auth={{
        kind: "embedded_wallet",
        provider: "privy",
        appId: process.env.NEXT_PUBLIC_PRIVY_APP_ID!,
        environment: "PROD",
      }}
      height="calc(100dvh - 32px)"
    />
  );
}

For Vite, use import.meta.env.VITE_AOMI_APPLICATION_ID and import.meta.env.VITE_AOMI_API_URL in the same component.

These examples intentionally include only public browser configuration. Quickstart explains how the widget exchanges a wallet or provider proof for an origin-bound access token. The current AomiWidget executes supported action requests with the connected client wallet; it does not enable account abstraction or sponsorship automatically.

Verify the setup

Open the page from the HTTPS origin configured with your wallet provider.
Sign in and connect or create a wallet.
Confirm the thread list and composer load without an App-key prompt.
Send a message and confirm a response appears.
Switch wallets or networks and confirm the widget updates the active owner.
For a transaction-enabled App, confirm the approval dialog shows the request, owner, and network before signing.

If setup fails, see Widget Troubleshooting.

​Prerequisites

​Install

​File structure

​Environment variables

​Choose authentication

​Verify the setup

Prerequisites

Install

File structure

Environment variables

Choose authentication

Verify the setup