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

# React SDK

> @0xmonaco/react

The Monaco React SDK provides `MonacoProvider` and React hooks for authentication, trading, vault operations, market data, and real-time WebSocket feeds.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @0xmonaco/react @0xmonaco/core wagmi viem
  ```

  ```bash pnpm theme={null}
  pnpm add @0xmonaco/react @0xmonaco/core wagmi viem
  ```

  ```bash yarn theme={null}
  yarn add @0xmonaco/react @0xmonaco/core wagmi viem
  ```
</CodeGroup>

## Basic Setup

`MonacoProvider` initializes the SDK and makes Monaco hooks available to every child component. During private alpha, configure wallets for Sei testnet and use `network="staging"`.

<CodeGroup>
  ```tsx Wagmi theme={null}
  import { MonacoProvider } from "@0xmonaco/react";
  import { WagmiProvider, createConfig, http } from "wagmi";
  import { seiTestnet } from "wagmi/chains";

  const wagmiConfig = createConfig({
    chains: [seiTestnet],
    transports: {
      [seiTestnet.id]: http()
    }
  });

  export function App() {
    return (
      <WagmiProvider config={wagmiConfig}>
        <MonacoProvider
          clientId={import.meta.env.VITE_MONACO_CLIENT_ID}
          network="staging"
          seiRpcUrl={import.meta.env.VITE_SEI_RPC_URL}
        >
          <YourComponents />
        </MonacoProvider>
      </WagmiProvider>
    );
  }
  ```

  ```tsx Wallet Client theme={null}
  import { MonacoProvider } from "@0xmonaco/react";
  import { createWalletClient, custom } from "viem";
  import { seiTestnet } from "viem/chains";

  function App({ provider }: { provider: EIP1193Provider }) {
    const walletClient = createWalletClient({
      chain: seiTestnet,
      transport: custom(provider)
    });

    return (
      <MonacoProvider
        clientId={import.meta.env.VITE_MONACO_CLIENT_ID}
        network="staging"
        seiRpcUrl={import.meta.env.VITE_SEI_RPC_URL}
        walletClient={walletClient}
      >
        <YourComponents />
      </MonacoProvider>
    );
  }
  ```
</CodeGroup>

## Configuration Options

<ParamField path="clientId" type="string" required>
  Your Monaco application client ID.
</ParamField>

<ParamField path="network" type="'staging'" default="staging">
  Monaco network to connect to. Use `"staging"` for Sei testnet during private alpha. Mainnet support will use the mainnet network when access opens.
</ParamField>

<ParamField path="seiRpcUrl" type="string" required>
  Sei RPC endpoint URL used for on-chain reads and transaction confirmation. During private alpha, use a Sei testnet RPC. In production code, source `seiRpcUrl` from an environment variable rather than hardcoding it.
</ParamField>

<ParamField path="walletClient" type="WalletClient">
  Optional [Viem `WalletClient`](https://viem.sh/docs/clients/wallet) used to sign the authorization that creates the Monaco session key during `login()`. Pass this when your wallet connection is outside Wagmi's connector context, such as Privy, ConnectKit, RainbowKit without Wagmi context, or a hand-built Viem wallet client.
</ParamField>

<ParamField path="tokenLifecycle" type="TokenLifecycleConfig">
  Optional configuration for automatic session management. Despite the name, this manages the wallet-authorized ed25519 session-key lifecycle.

  * `autoRefresh`: Extend the session before it expires (default: `true`)
  * `persistTokens`: Store the session in localStorage so it survives reloads (default: `true`)
  * `refreshBufferSeconds`: Seconds before expiry to trigger a refresh (default: `300`)
  * `onRefreshError`: Callback when a session refresh fails
  * `onRefreshSuccess`: Callback when a session refresh succeeds
</ParamField>

<ParamField path="children" type="ReactNode" required>
  Your application components.
</ParamField>

## Accessing the SDK

Use `useMonacoSDK` to access the underlying SDK instance from any child component.

```tsx theme={null}
import { useMonacoSDK } from "@0xmonaco/react";

function SDKStatus() {
  const { sdk, error, clearError } = useMonacoSDK();

  if (error) {
    return <button onClick={clearError}>Dismiss {error.message}</button>;
  }

  return sdk ? "Ready" : "Initializing...";
}
```

## Session Persistence

By default, the provider stores the Monaco session in `localStorage` and restores it on reload. The persisted session includes the ed25519 session private key used to sign requests.

<Warning>
  `localStorage` is exposed to XSS. Harden production apps with a Content Security Policy, or disable persistence for security-sensitive apps.
</Warning>

```tsx theme={null}
<MonacoProvider
  clientId={import.meta.env.VITE_MONACO_CLIENT_ID}
  network="staging"
  seiRpcUrl={import.meta.env.VITE_SEI_RPC_URL}
  tokenLifecycle={{ persistTokens: false }}
>
  <YourComponents />
</MonacoProvider>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.