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

# useSession

> Drive the active Calm session, subscribe to its loading state, and clear it.

`useSession({ address })` calls the active modality's
session-creation callback on mount and on a 50-minute interval,
keeping the 1-hour `calm_session` cookie fresh ahead of expiry.

The same hook exposes a `clear()` method that deletes the server-side
`calm_session` cookie and drops the cached session.

## Import

```ts theme={null}
import { useSession } from "@calm-xyz/react";
```

## Usage

```tsx app/page.tsx theme={null}
"use client";
import { useCalm, useSession } from "@calm-xyz/react";

function SignedIn() {
  const { address } = useCalm();
  const { data, isPending, error } = useSession({ address });
  if (isPending) return <div>Loading…</div>;
  if (error) return <div>Auth error: {error.message}</div>;
  return <div>Signed in as {data?.wallet}</div>;
}
```

## Parameters

```ts theme={null}
import { type UseSessionParameters } from "@calm-xyz/react";
```

### `address`

`string`

The wallet address the session is bound to. Must match the wallet the
active provider is configured for.

## Return Type

```ts theme={null}
import { type UseSessionReturnType } from "@calm-xyz/react";
```

`UseQueryResult<SessionResponse, ApiError>` from
[@tanstack/react-query](https://tanstack.com/query) augmented with a
`clear()` method.

### `data`

`SessionResponse | undefined`

The session-creation response: `{ wallet, expires_at }`. `wallet` is
lowercased and 0x-prefixed; `expires_at` is the ISO timestamp the
`calm_session` cookie expires at (1 hour from creation).

### `isPending`

`boolean`

`true` until the first session-creation call resolves. Use to gate
loading UI.

### `error`

`ApiError | null`

The structured error from the modality's session creation. See
[Errors](/sdk/errors) for the full code table.

### `status`

`"pending" | "error" | "success"`

The react-query status.

### `refetch`

`() => Promise<UseQueryResult<SessionResponse, ApiError>>`

Manually trigger a session refresh.

### `clear`

`() => Promise<void>`

Clear the server-side session cookie and drop the cached `useSession`
entry so subsequent reads don't show stale `data`. See
[Sign out](#sign-out).

See the [@tanstack/react-query useQuery docs](https://tanstack.com/query/v5/docs/react/reference/useQuery)
for the full set of fields on the return type.

## Sign out

The SDK sits downstream of your wallet / identity stack — sign out at
that layer first (e.g. `usePrivy().logout()`, `useDisconnect()` from
wagmi, `handleLogOut()` from Dynamic). The provider observes the
address going away and unmounts naturally.

To also clear the server-side `calm_session` cookie immediately
(rather than waiting for the 1-hour TTL):

```tsx theme={null}
"use client";
import { useCallback } from "react";
import { useCalm, useSession } from "@calm-xyz/react";
import { useDisconnect } from "wagmi";

function SignOut() {
  const { address } = useCalm();
  const { clear } = useSession({ address });
  const { disconnect } = useDisconnect();
  const handle = useCallback(async () => {
    await clear();
    disconnect();
  }, [clear, disconnect]);
  return <button onClick={handle}>Sign out</button>;
}
```