> ## Documentation Index
> Fetch the complete documentation index at: https://aomi.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install AomiWidget, connect it to your App, and choose browser, Para, or Privy authentication.

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.

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

## Install

```bash theme={null}
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.

<Tabs>
  <Tab title="Next.js">
    ```text theme={null}
    your-app/
    ├── app/
    │   └── assistant/
    │       └── page.tsx       # Client component that mounts AomiWidget
    ├── .env.local             # Public widget configuration
    └── package.json
    ```
  </Tab>

  <Tab title="Vite">
    ```text theme={null}
    your-app/
    ├── src/
    │   ├── App.tsx            # Mounts AomiWidget
    │   └── main.tsx
    ├── .env.local             # Public widget configuration
    └── package.json
    ```
  </Tab>
</Tabs>

## Environment variables

<Tabs>
  <Tab title="Next.js">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Vite">
    ```bash theme={null}
    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
    ```
  </Tab>
</Tabs>

| 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.

<Note>
  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](/docs/integrate/client-sdk#check-compatibility).
</Note>

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

## 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             |

<Tabs>
  <Tab title="Browser wallet">
    Browser mode authenticates an existing EVM or Solana wallet. It does not require a Para or Privy provider import.

    ```tsx theme={null}
    "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)"
        />
      );
    }
    ```
  </Tab>

  <Tab title="Para">
    Importing the Para entry point registers Para authentication and its wallet signer.

    ```tsx theme={null}
    "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)"
        />
      );
    }
    ```
  </Tab>

  <Tab title="Privy">
    Importing the Privy entry point registers Privy authentication and its wallet signer.

    ```tsx theme={null}
    "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)"
        />
      );
    }
    ```
  </Tab>
</Tabs>

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

<Info>
  These examples intentionally include only public browser configuration.
  [Quickstart](/docs/guides/widget/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.
</Info>

## Verify the setup

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

If setup fails, see [Widget Troubleshooting](/docs/guides/widget/troubleshooting).