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

# useChipiSession

> Unified session key management for gasless UX - create, register, execute, and revoke sessions with a single hook.

## Overview

`useChipiSession` provides a unified API for managing session keys, enabling gasless transactions without requiring the owner's signature for each operation.

This hook combines all session-related operations:

* **Session creation** (local keypair generation)
* **Session registration** (on-chain)
* **Transaction execution** (using session key)
* **Session revocation** (on-chain)
* **Status checking** (remaining calls, expiration)

<Warning>
  Session keys only work with **CHIPI wallets**. READY wallets do not support session keys.
</Warning>

## Prerequisites

Before using `useChipiSession`, you need:

1. A **CHIPI wallet** (check `wallet.walletType === "CHIPI"` or `wallet.supportsSessionKeys`)
2. The user's **encryption key (PIN)**
3. An **authentication token** (from Clerk, Firebase, etc.)

## Session Lifecycle

| State     | Description                                          |
| --------- | ---------------------------------------------------- |
| `none`    | No session exists                                    |
| `created` | Session created locally, not yet registered on-chain |
| `active`  | Session registered and usable                        |
| `expired` | Session has expired (time or call limit)             |
| `revoked` | Session has been revoked on-chain                    |

## Quick Start

```tsx theme={null}
import { useChipiWallet, useChipiSession } from "@chipi-stack/chipi-react";

function SessionComponent() {
  const { userId, getToken } = useYourAuthProvider();
  const [pin, setPin] = useState("");
  
  const { wallet } = useChipiWallet({
    externalUserId: userId,
    getBearerToken: getToken,
  });
  
  const {
    session,
    sessionState,
    hasActiveSession,
    remainingCalls,
    createSession,
    registerSession,
    executeWithSession,
    isCreating,
    isRegistering,
    isExecuting,
  } = useChipiSession({
    wallet,
    encryptKey: pin,
    getBearerToken: getToken,
  });

  // Setup session (create + register)
  const handleSetup = async () => {
    await createSession();
    await registerSession();
  };

  // Execute a transfer using the session
  const handleTransfer = async () => {
    await executeWithSession([{
      contractAddress: "0x033068F6539f8e6e6b131e6B2B814e6c34A5224bC66947c47DaB9dFeE93b35fb",
      entrypoint: "transfer",
      calldata: [recipientAddress, amount, "0x0"],
    }]);
  };

  return (
    <div>
      <p>Session: {sessionState}</p>
      {hasActiveSession && <p>Calls remaining: {remainingCalls}</p>}
      
      {!hasActiveSession ? (
        <button onClick={handleSetup} disabled={isCreating || isRegistering}>
          Setup Session
        </button>
      ) : (
        <button onClick={handleTransfer} disabled={isExecuting}>
          Transfer (Gasless)
        </button>
      )}
    </div>
  );
}
```

## Configuration Options

```typescript theme={null}
interface UseChipiSessionConfig {
  // Required
  wallet: SessionWallet | null | undefined;
  encryptKey: string;
  getBearerToken: () => Promise<string | null | undefined>;
  
  // Optional
  storedSession?: SessionKeyData | null;
  onSessionCreated?: (session: SessionKeyData) => void | Promise<void>;
  defaultDurationSeconds?: number;  // Default: 21600 (6 hours)
  defaultMaxCalls?: number;         // Default: 1000
  autoCheckStatus?: boolean;        // Default: true
}
```

| Option                   | Type                    | Default  | Description                      |
| ------------------------ | ----------------------- | -------- | -------------------------------- |
| `wallet`                 | `SessionWallet`         | Required | Wallet data (must be CHIPI type) |
| `encryptKey`             | `string`                | Required | User's PIN for signing           |
| `getBearerToken`         | `() => Promise<string>` | Required | Auth token function              |
| `storedSession`          | `SessionKeyData`        | `null`   | Previously stored session        |
| `onSessionCreated`       | `(session) => void`     | -        | Callback to persist new session  |
| `defaultDurationSeconds` | `number`                | `21600`  | Session duration (6 hours)       |
| `defaultMaxCalls`        | `number`                | `1000`   | Max calls per session            |
| `autoCheckStatus`        | `boolean`               | `true`   | Auto-fetch on-chain status       |

## Return Values

### Session Data

| Property           | Type                     | Description                      |
| ------------------ | ------------------------ | -------------------------------- |
| `session`          | `SessionKeyData \| null` | Current session data             |
| `sessionStatus`    | `SessionDataResponse`    | On-chain session status          |
| `sessionState`     | `SessionState`           | Lifecycle state                  |
| `hasActiveSession` | `boolean`                | Whether session is usable        |
| `isSessionExpired` | `boolean`                | Whether session has expired      |
| `remainingCalls`   | `number \| undefined`    | Calls left in session            |
| `supportsSession`  | `boolean`                | Whether wallet supports sessions |

### Actions

| Method                      | Returns                   | Description                        |
| --------------------------- | ------------------------- | ---------------------------------- |
| `createSession(config?)`    | `Promise<SessionKeyData>` | Create new session locally         |
| `registerSession(config?)`  | `Promise<string>`         | Register on-chain (returns txHash) |
| `revokeSession()`           | `Promise<string>`         | Revoke on-chain (returns txHash)   |
| `executeWithSession(calls)` | `Promise<string>`         | Execute calls (returns txHash)     |
| `clearSession()`            | `void`                    | Clear local session state          |
| `refetchStatus()`           | `Promise<void>`           | Refresh on-chain status            |

### Loading States

| Property          | Description                  |
| ----------------- | ---------------------------- |
| `isCreating`      | Creating session locally     |
| `isRegistering`   | Registering session on-chain |
| `isRevoking`      | Revoking session on-chain    |
| `isExecuting`     | Executing transaction        |
| `isLoadingStatus` | Fetching on-chain status     |

## Persisting Sessions

Sessions should be persisted between page loads. Here's an example using local state:

```tsx theme={null}
import { useState, useEffect } from "react";
import { useChipiWallet, useChipiSession } from "@chipi-stack/chipi-react";

function PersistentSession() {
  const { wallet } = useChipiWallet({ ... });
  
  // Load session from storage
  const [storedSession, setStoredSession] = useState(() => {
    const saved = localStorage.getItem("chipi-session");
    return saved ? JSON.parse(saved) : null;
  });
  
  const {
    session,
    hasActiveSession,
    createSession,
    registerSession,
  } = useChipiSession({
    wallet,
    encryptKey: pin,
    getBearerToken: getToken,
    storedSession,
    onSessionCreated: (newSession) => {
      // Persist to localStorage
      localStorage.setItem("chipi-session", JSON.stringify(newSession));
      setStoredSession(newSession);
    },
  });

  // Session is automatically restored on mount!
}
```

## Executing Transactions

The `executeWithSession` method accepts an array of Starknet calls:

```typescript theme={null}
// Single transfer
await executeWithSession([{
  contractAddress: USDC_CONTRACT,
  entrypoint: "transfer",
  calldata: [recipient, amount, "0x0"],
}]);

// Batch multiple calls
await executeWithSession([
  {
    contractAddress: USDC_CONTRACT,
    entrypoint: "approve",
    calldata: [spender, amount, "0x0"],
  },
  {
    contractAddress: DEX_CONTRACT,
    entrypoint: "swap",
    calldata: [...],
  },
]);
```

## Custom Session Configuration

### Custom Duration

```typescript theme={null}
// Create session valid for 1 hour
await createSession({ durationSeconds: 3600 });
```

### Custom Max Calls

```typescript theme={null}
// Register with 500 max calls
await registerSession({ maxCalls: 500 });
```

## Error Handling

```tsx theme={null}
const { error, session } = useChipiSession({...});

// Check for errors
if (error) {
  console.error("Session error:", error.message);
}

// Handle specific errors
const handleSetup = async () => {
  try {
    await createSession();
    await registerSession();
  } catch (err) {
    if (err.message.includes("does not support sessions")) {
      alert("Please use a CHIPI wallet for sessions");
    } else {
      alert(`Error: ${err.message}`);
    }
  }
};
```