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

# SIWX Implementation

# Reown Authentication SIWX Usage

**Reown Authentication is our flagship SIWX (Sign In With X) solution** - the recommended way to handle user authentication for modern web3 applications. Built specifically for multi-chain environments, it abstracts away the complexity of validating wallets across **EVM, Solana, and Bitcoin networks**.

With Reown Authentication you will be able to see and control the sessions of your users, get insights and much more. Read more about [Reown Authentication](/cloud/reown-authentication) features in the dedicated documentation.

<Warning>
  `ReownAuthentication` was previously named `CloudAuthSIWX`, it has been renamed since version `1.7.13`. If you were using
  the previous class, you will not need to update your code, both class names work identically.
</Warning>

### Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @reown/appkit-siwx
  ```

  ```bash Yarn theme={null}
  yarn add @reown/appkit-siwx
  ```

  ```bash Bun theme={null}
  bun a @reown/appkit-siwx
  ```

  ```bash pnpm theme={null}
  pnpm add @reown/appkit-siwx
  ```
</CodeGroup>

### Usage

```typescript {3,10} theme={null}
import { createAppKit } from '@reown/appkit'
// Add the following code line
import { ReownAuthentication } from '@reown/appkit-siwx'

const appkit = createAppKit({
  projectId,
  networks,
  metadata,
  // Add the following code line
  siwx: new ReownAuthentication()
})
```

Now your Dapp is ready to use the **Reown Authentication** within your SIWX configuration.

### Extra configuration

With `ReownAuthentication` you don't need to do anything else, it will work out of the box, but you can configure some parameters to customize the experience.

#### Available Parameters

```typescript theme={null}
new ReownAuthentication({
  localAuthStorageKey?: string    // Default: '@appkit/siwx-auth-token'
  localNonceStorageKey?: string   // Default: '@appkit/siwx-nonce-token'
  required?: boolean              // Default: true
})
```

#### Examples

**Custom storage keys:**

```typescript theme={null}
new ReownAuthentication({
  localAuthStorageKey: 'my-app-auth',
  localNonceStorageKey: 'my-app-nonce'
})
```

**Optional authentication (wallet stays connected if user denies signing):**

```typescript theme={null}
new ReownAuthentication({
  required: false
})
```

## Interacting with Reown Authentication

AppKit provides a `useAppKitSIWX` hook that allows you to interact with Reown Authentication. This hook provides a set of methods to manage sessions, retrieve user information, and update session metadata.

```tsx theme={null}
import type { ReownAuthentication } from '@reown/appkit-siwx'
import { useAppKitSIWX } from '@reown/appkit-siwx/react'

function Component() {
  // ...
  const siwx = useAppKitSIWX<ReownAuthentication>()
  // ...
}
```

### Interactions

#### `getSessionAccount`

You can retrieve the session account data using the `getSessionAccount` method:

```tsx theme={null}
function Component() {
  // ...

  const siwx = useAppKitSIWX<ReownAuthentication>()
  const [sessionAccount, setSessionAccount] = useState<ReownAuthentication.SessionAccount>()

  useEffect(() => {
    if (!siwx) return

    siwx.getSessionAccount().then(setSessionAccount)
  }, [siwx])

  // ...
}
```

#### `setSessionAccountMetadata`

Reown Authentication provides a way for you to store arbitrary information about your users through the AppKit Account Metadata.

Updating the session account metadata is done using the `setSessionAccountMetadata` method:

```tsx theme={null}
function Component() {
  // ...

  const siwx = useAppKitSIWX<ReownAuthentication>()

  const mutateMetadata = async (metadata: object) => {
    if (!siwx) return

    await siwx.setSessionAccountMetadata(metadata)
  }
}
```

You may use the session metadata through the `getSessionAccount` method:

```tsx theme={null}
function Component() {
  // ...

  const siwx = useAppKitSIWX<ReownAuthentication>()

  const queryMetadata = async () => {
    if (!siwx) return

    const account = await siwx.getSessionAccount()

    return account.appKitAccount?.metadata
  }

  // ...
}
```

#### `events`

Reown Authentication provides events that you can listen to for session management and authentication state changes:

```tsx theme={null}
import type { SIWXSession, ReownAuthentication } from '@reown/appkit-siwx'
import { useAppKitSIWX } from '@reown/appkit-siwx/react'

function Component() {
  // ...

  const siwx = useAppKitSIWX<ReownAuthentication>()

  useEffect(() => {
    if (!siwx) return

    // Add event listeners
    const unsubscribe = siwx.on('sessionChanged', (session: SIWXSession | undefined) => {
      console.log('Session changed:', session)
    })

    // Cleanup listeners
    return () => {
      unsubscribe()
      // or
      siwx.removeAllListeners()
    }
  }, [siwx])

  // ...
}
```