# React (/docs/react)



`@cavos/kit` ships React bindings under the `@cavos/kit/react` subpath (same
package) for the Cavos [embedded wallet](https://cavos.xyz/embedded-wallet)
([embedded wallets](https://cavos.xyz/embedded-wallet),
[embedded wallet SDK](https://cavos.xyz/embedded-wallet)). Wrap your app once in
`<CavosProvider>` and every descendant can call `useCavos()` to read wallet
state and trigger actions: no prop drilling, no imperative `connect` calls. In
Next.js App Router, keep that provider in a `'use client'` module. The
[Next.js embedded wallet guide](https://cavos.xyz/blog/embedded-wallet-nextjs)
is that wiring. The generic React install is the
[how to add an embedded wallet](https://cavos.xyz/blog/how-to-add-an-embedded-wallet)
walkthrough.

```bash title="Terminal"
npm install @cavos/kit@^0.6.1
```

```tsx title="app/provider.tsx"
import { CavosProvider } from "@cavos/kit/react";

export function Providers({ children }) {
  return (
    <CavosProvider
      config={{
        appId: process.env.NEXT_PUBLIC_CAVOS_APP_ID,
        chains: ["solana", "stellar"],
        defaultChain: "solana",
        network: "testnet",
        appSalt: "my-app",
        socialRecovery: true,       // enclave DEK wrap (multi-chain OK)
        deviceApproval: "enclave",
      }}
      modal={{
        appName: "My App",
        theme: "light",
      }}
    >
      {children}
    </CavosProvider>
  );
}
```

The provider manages **one or more chains**. Behind the scenes it resolves the
identity, derives addresses for all configured chains, and keeps the wallet
handles ready for sponsored transactions. Deployment happens lazily on first
execute per chain: see [Concepts](/docs/concepts).

### Props [#props]

| Prop       | Description                                                                                                                                                                              |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config`   | Chains, network, `appSalt`, `deviceApproval` (`"enclave"` \| `"passkey"`; passkey is one chain), `socialRecovery`, `vault` (on by default with `appId`; see [Cavos vault](/docs/vault)). |
| `modal`    | Login modal appearance and providers. Omit to render no modal.                                                                                                                           |
| `identity` | **Bring your own auth.** Pass your signed-in user and Cavos login turns off. `null` while your auth loads or after sign-out. See [Authentication](/docs/auth#in-react).                  |

### `CavosConfig` [#cavosconfig]

| Field                       | Type                              | Description                                                                                                                                                      |
| --------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appId`                     | `string?`                         | App ID from the [dashboard](/docs/dashboard). Turns on the hosted registry, relayers, and the [vault](/docs/vault).                                              |
| `environment`               | `"development" \| "production"?`  | Dashboard environment. Defaults to `"production"`.                                                                                                               |
| `chains`                    | `Chain[]?`                        | Chains to connect. Addresses are derived for all of them; nothing deploys until the first `execute`.                                                             |
| `defaultChain`              | `Chain?`                          | Active chain at start. Must be in `chains`; defaults to `chains[0]`.                                                                                             |
| `chain`                     | `Chain?`                          | **Deprecated.** Single-chain form of `chains`.                                                                                                                   |
| `network`                   | `"testnet" \| "mainnet"`          | Required. Resolves to each chain's concrete network.                                                                                                             |
| `appSalt`                   | `string`                          | Required. HKDF salt for the account key. Never change it after users connect.                                                                                    |
| `paymasterApiKey`           | `string?`                         | Required for Starknet. Sponsors deploy and execute.                                                                                                              |
| `deviceApproval`            | `"enclave" \| "passkey"?`         | How a new device restores the MasterDEK. Defaults to `"enclave"` when `socialRecovery` is on, otherwise `"passkey"`. `"passkey"` supports one chain.             |
| `socialRecovery`            | `boolean \| AttestationPolicy?`   | Turn on [hardware-isolated recovery](/docs/hardware-isolated-recovery), or pass your own attestation policy. Also needs the environment toggle in the dashboard. |
| `socialRecoveryAttestation` | `AttestationPolicy?`              | **Deprecated.** Use `socialRecovery`. If set, it takes precedence.                                                                                               |
| `vault`                     | `boolean \| { url?: string }?`    | Keys live in the Cavos vault. On by default with `appId`.                                                                                                        |
| `persistSession`            | `boolean?`                        | Defaults to `true` (`localStorage`). `false` keeps the sign-in in `sessionStorage`, so it ends when the tab closes. Read once at mount.                          |
| `rpcUrl`                    | `string?`                         | RPC override. Only valid with one configured chain.                                                                                                              |
| `rpcUrls`                   | `Partial<Record<Chain, string>>?` | Per-chain RPC overrides. Use this with more than one chain.                                                                                                      |
| `tollUrl`                   | `string?`                         | Override where `fee: { token }` settles (Solana). Defaults to the hosted service.                                                                                |
| `authBackendUrl`            | `string?`                         | Override the Cavos auth backend (self-hosted or staging).                                                                                                        |
| `redirectUri`               | `string?`                         | Explicit OAuth callback. Optional on web, required in React Native.                                                                                              |
| `rpId`                      | `string?`                         | Passkey relying-party ID. Optional on web, required in React Native.                                                                                             |
| `minimumKeySecurity`        | `"os-protected" \| "hardware"?`   | React Native only; accepted on web so config objects stay portable.                                                                                              |

In development the provider checks the config when it mounts and reports
problems in the console: a missing `appSalt`, a paymaster key on a chain that
ignores it, and in particular an `appSalt` that changed since this browser last
connected, which silently moves every existing user to a new, empty wallet. Run
the same checks yourself with `validateCavosConfig(config)`.

## `useCavos()` [#usecavos]

The primary hook. Returns the full wallet surface:

```tsx
import { useCavos } from "@cavos/kit/react";

function Wallet() {
  const { address, isAuthenticated, walletStatus, openModal, logout } = useCavos();
  if (!isAuthenticated) return <button onClick={openModal}>Sign in</button>;
  return <div>{address} · ready={walletStatus.isReady}</div>;
}
```

### State [#state]

| Field                         | Description                                                                                                                                                                                           |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isAuthenticated: boolean`    | Whether a wallet is connected.                                                                                                                                                                        |
| `user: UserInfo \| null`      | `{ userId, email?, provider? }` from the login.                                                                                                                                                       |
| `wallet: CavosWallet \| null` | The connected wallet for the selected chain, discriminated by `wallet.chain`. Narrow on it before chain-native calls.                                                                                 |
| `session`                     | The full multi-chain session, or `null`: the default wallet plus `wallet(chain)`, `chainStatus`, and `chainAddress`. Use `session.wallet("stellar")` to access other chains.                          |
| `address: string \| null`     | The account address for the selected chain.                                                                                                                                                           |
| `chain: Chain`                | The active chain (`"starknet" \| "solana" \| "stellar"`).                                                                                                                                             |
| `configuredChains: Chain[]`   | All chains configured for this session.                                                                                                                                                               |
| `walletStatus: WalletStatus`  | Deployment / device-approval / passkey flags (see below).                                                                                                                                             |
| `isLoading: boolean`          | True during an in-flight login or connect.                                                                                                                                                            |
| `authError: string \| null`   | Last unrecoverable auth/connect error. Null while healthy. `CavosAuthModal` shows it on the sign-in screen; from 0.2.3 that includes a connect that fails while the "Connecting with…" spinner is up. |
| `passkeySupported: boolean`   | Whether this device/browser can use a platform passkey.                                                                                                                                               |

`WalletStatus`: `{ isDeploying, isReady, isUndeployed, needsDeviceApproval,
hasPasskey, isNewAccount, recovery }`.

* `isUndeployed`: True when the account has not been deployed on-chain yet.
  First execute will deploy + run atomically.
* `isReady`: True when status is `ready`: the account exists on-chain (always, on Solana) and this device holds its key.
* `needsDeviceApproval`: True when the wallet exists but this device holds no key yet.

<Callout type="info">
  Both `isUndeployed` and `isReady` allow execution. Only `needsDeviceApproval`
  blocks transactions. An undeployed wallet can sign messages and execute: the
  first execute deploys the account.
</Callout>

`walletStatus.recovery` is the one flag most apps actually read:
`{ protected: boolean; methods: ("passkey" | "social")[] }`. It answers one question: can this user get
back in from a device they do not have yet? The other flags describe work in
flight; this describes the standing guarantee.

```tsx
const { walletStatus } = useCavos();
if (walletStatus.isReady && !walletStatus.recovery.protected) {
  // Nudge: "Add a passkey so you can sign in on a new device."
}
```

<Callout type="info">
  `recovery.protected` starts `false` and flips once the lookup that fills it
  returns. Read it as "not known to be protected" during the first moments of a
  connect, not as "known to be unprotected": don't show a scary warning on frame one.
</Callout>

### Chain switching [#chain-switching]

Switch the selected chain without re-authenticating or remounting:

```tsx
const { chain, setChain, configuredChains, session } = useCavos();

// Switch to Stellar
await setChain("stellar");

// Now `chain` is "stellar", `wallet` is the Stellar wallet
// The walletStatus updates to reflect the Stellar account's state
```

`setChain` does not re-deploy or re-authenticate: it just changes which wallet
is active. The session keeps all chains connected.

### Login [#login]

| Method                                   | Description                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `login(provider)`                        | OAuth social login (`"google" \| "apple" \| "github" \| "telegram"`): opens the hosted flow. GitHub is optional (`providers` must include `'github'`), not recommended over Google, Apple, or email, and not available in React Native. Telegram is optional (`providers` must include `'telegram'`, kit 0.5.2), web only, and not available in React Native. |
| `sendOtp(email)`                         | Email a 9-character sign-in code.                                                                                                                                                                                                                                                                                                                             |
| `verifyOtp(email, code)`                 | Verify the emailed code and connect the wallet (nothing deploys until the first `execute`).                                                                                                                                                                                                                                                                   |
| `handleCallback(authData, redirectUri?)` | Resolve identity from an OAuth callback (`?cavos_auth_code=…`) and connect. Pass the callback URL as `redirectUri` if it differs from the current one.                                                                                                                                                                                                        |

### Transactions [#transactions]

| Method                  | Description                                                                                                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `execute(calls, opts?)` | **Starknet only.** Multicall signed by the stark key, gasless by default. Returns `{ transactionHash }`. Works on `undeployed` (deploys first) and `ready` wallets.               |
| `signMessage(message)`  | **All chains.** Sign an arbitrary message off-chain; returns a uniform `MessageSignature`. Works on `undeployed` and `ready` wallets. See [Wallet actions](/docs/wallet-actions). |

<Callout type="info">
  On **Solana and Stellar**, call the wallet directly for chain-native actions
  instead of the context's `execute`: narrow on `wallet.chain`, then
  `wallet.execute(amount, destination)`. For `signTransaction` (sign without
  submit), also call `wallet.signTransaction(...)` directly after narrowing:
  the args differ per chain. See [Wallet actions](/docs/wallet-actions).
</Callout>

### Device & recovery [#device--recovery]

| Method                               | Description                                                                                                                                                                                                                                  |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enrollPasskeyDefault()`             | Add a passkey **after** sign-up. Stores a PRF-encrypted copy of the MasterDEK. Sign-up never prompts.                                                                                                                                        |
| `approveDeviceWithPasskey()`         | New device with no wrap, when the user dismissed the prompt: opens the passkey's encrypted copy of the MasterDEK (every chain).                                                                                                              |
| `setupRecovery()`                    | **Deprecated.** Current wallets do not use recovery codes. Throws on Starknet and Solana; registers nothing on Stellar.                                                                                                                      |
| `recover(code)`                      | **Deprecated.** Current wallets do not use recovery codes. Restore with enclave login or `approveDeviceWithPasskey()`.                                                                                                                       |
| `submitSocialRecoveryToken(idToken)` | Drive enclave enroll/unwrap with the provider's raw `id_token`. Starknet, Solana, and Stellar. Since 0.2.6, not accepted for Google and Apple tokens. See [Hardware-isolated recovery](/docs/hardware-isolated-recovery#with-your-own-auth). |

When hardware-isolated social recovery is enabled, `<CavosProvider>` enrolls
after a fresh login (reseals the MasterDEK if this device already has it) and
unwraps on a device that does not. Passkey is opt-in via
`enrollPasskeyDefault()`: `secureStep` defaults to `'off'`.

These wrappers present a shared product flow across the current adapters. Their
cryptographic implementation and some availability constraints remain
chain-specific. See [Passkeys](/docs/passkeys) and [Recovery](/docs/recovery)
for the capability details.

### Modal & session [#modal--session]

| Method                         | Description                                                                                                                                                                                                                                 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `openModal()` / `closeModal()` | Open/close the built-in auth modal (the provider mounts it automatically when `modal` is set).                                                                                                                                              |
| `logout()`                     | Clears the persisted identity and session token, and tells the [vault](/docs/vault) to let go of the keys it unlocked. Stored keys stay, so the next login is silent. Does **not** sign the user out of Google, Apple, GitHub, or Telegram. |
| `clearAuthError()`             | Clear `authError` (e.g. when the user starts a new login attempt).                                                                                                                                                                          |

## `useCavosAuth()` [#usecavosauth]

A deliberately thin subset for components that only need to open the modal and
read basic auth state: no wallet, no transactions:

```ts
{
  openModal, closeModal,
  isAuthenticated, address, user, walletStatus, logout,
}
```

## `<CavosAuthModal>` [#cavosauthmodal]

A fully customizable, themeable login modal. The provider mounts it
automatically when you pass `modal={...}`; you can also render it directly (for
a live preview, or to control its lifecycle yourself).

```tsx
import { CavosAuthModal } from "@cavos/kit/react";

<CavosAuthModal
  open={open}
  onClose={() => setOpen(false)}
  appName="My App"
  appLogo="https://myapp.com/logo.png"
  appLogoSize={56}
  providers={["email", "google", "apple"]} // add "github" or "telegram" to offer them
  primaryColor="#402AFF"
  theme="light"
  radius={16}
  secureStep="optional"
/>
```

### Props [#props-1]

| Prop              | Type                                                            | Description                                                                                                                                                                                                                                                                             |
| ----------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open`            | `boolean`                                                       | Whether the modal is shown (ignored when `inline`).                                                                                                                                                                                                                                     |
| `onClose`         | `() => void`                                                    | Called when the user dismisses the modal.                                                                                                                                                                                                                                               |
| `appName`         | `string?`                                                       | Shown in the heading (`"Sign in to {appName}"`).                                                                                                                                                                                                                                        |
| `appLogo`         | `string?`                                                       | Image URL for the logo. If omitted, the Cavos star is shown. The provider also loads it from your app's dashboard config automatically; a local `appLogo` overrides that.                                                                                                               |
| `appLogoSize`     | `number?`                                                       | Logo height in px. Defaults to `40` (image) / `34` (Cavos star).                                                                                                                                                                                                                        |
| `providers`       | `("google" \| "apple" \| "email" \| "github" \| "telegram")[]?` | Which login buttons to show. Defaults to Google, Apple, and email. Add `"github"` to offer GitHub (kit 0.5.0, web only) or `"telegram"` to offer Telegram (kit 0.5.2, web only); see [Authentication → GitHub](/docs/auth#github) and [Authentication → Telegram](/docs/auth#telegram). |
| `primaryColor`    | `string?`                                                       | Accent color for buttons / focus rings (hex).                                                                                                                                                                                                                                           |
| `theme`           | `"light" \| "dark"?`                                            | Card theme. Defaults to `light`.                                                                                                                                                                                                                                                        |
| `backgroundColor` | `string?`                                                       | Override the card background (defaults to white / `#111` per theme).                                                                                                                                                                                                                    |
| `radius`          | `number?`                                                       | Card & button corner radius in px (card defaults to `16`).                                                                                                                                                                                                                              |
| `inline`          | `boolean?`                                                      | Render the card in-flow (no overlay/backdrop): for live previews. When `true`, `open` is ignored.                                                                                                                                                                                       |
| `secureStep`      | `"optional" \| "required" \| "off"?`                            | Passkey screen after a new account. **`'off'` is the default**: login never prompts.                                                                                                                                                                                                    |
| `onSuccess`       | `(address: string) => void?`                                    | Fired when sign-in and connect succeed.                                                                                                                                                                                                                                                 |

## `CavosModalConfig` [#cavosmodalconfig]

The object you pass as `modal={...}` to `<CavosProvider>`. Same fields as
`CavosAuthModalProps` except no `open` / `onClose` / `inline` (the provider
manages those), plus `onSuccess`.

## Theming [#theming]

All visual props (`primaryColor`, `theme`, `backgroundColor`, `radius`,
`appLogo`, `appLogoSize`) apply identically whether you set them on
`<CavosProvider modal={...}>` or on a direct `<CavosAuthModal ... />`.

```tsx
<CavosProvider
  config={{ chains: ["solana"], defaultChain: "solana", network: "testnet", appSalt: "my-app", appId }}
  modal={{
    appName: "My App",
    appLogo: "/logo.png",
    appLogoSize: 48,
    primaryColor: "#7C3AED",
    theme: "dark",
    backgroundColor: "#0A0A0F",
    radius: 20,
  }}
>
  <App />
</CavosProvider>
```

## Mobile: automatic bottom sheet [#mobile-automatic-bottom-sheet]

On viewports &#x2A;*`max-width: 640px`** the modal becomes a **bottom sheet**: it
slides up from the bottom with rounded top corners and a grab handle, overlaying
the page with a blurred backdrop. This is fully automatic; there is no prop to
toggle. On desktop the modal renders centered. The `inline` mode disables the
overlay/sheet entirely (the card is embedded in your layout).

## New devices [#new-devices]

There are no device approval or revocation pages to host. A new device restores
the MasterDEK with the enclave or a passkey and derives the same account key;
nothing is added on-chain. See [Multi-device](/docs/multi-device).

## Multi-chain in React [#multi-chain-in-react]

The provider handles multiple chains natively. Configure them all up front:

```tsx
<CavosProvider
  config={{
    chains: ["solana", "stellar", "starknet"],
    defaultChain: "solana",
    network: "testnet",
    appSalt: "my-app",
    appId,
    paymasterApiKey, // for Starknet
  }}
  modal={{ appName: "My App" }}
>
  <App />
</CavosProvider>
```

Then switch chains without remounting:

```tsx
import type { Chain } from "@cavos/kit";
import { useCavos } from "@cavos/kit/react";

function ChainSwitcher() {
  const { chain, setChain, configuredChains, walletStatus } = useCavos();

  return (
    <select value={chain} onChange={(e) => setChain(e.target.value as Chain)}>
      {configuredChains.map((c) => (
        <option key={c} value={c}>{c}</option>
      ))}
    </select>
  );
}
```

`setChain` updates the active chain, and `walletStatus` reflects the new
chain's status. No re-authentication, no remount, no lost state.

<Callout type="info">
  Each chain has its own address, deployment status, and device authorization.
  Switching chains may show a different `walletStatus`: one chain might be
  `ready` while another is `undeployed` or `needs-device-approval`.
</Callout>

<Callout type="info">
  `Chain` and `NetworkEnv` types are exported from the **core** entry
  (`import type { Chain } from "@cavos/kit"`), not from `@cavos/kit/react`.
</Callout>
