useChipiSession

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)

Session keys only work with CHIPI wallets. READY wallets do not support session keys.

Prerequisites

Before using useChipiSession, you need:

A CHIPI wallet (check wallet.walletType === "CHIPI" or wallet.supportsSessionKeys)
The user’s encryption key (PIN)
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

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

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:

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:

// 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

// Create session valid for 1 hour
await createSession({ durationSeconds: 3600 });

Custom Max Calls

// Register with 500 max calls
await registerSession({ maxCalls: 500 });

Error Handling

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}`);
    }
  }
};

Getting Started

Gasless

React Guides

SDK Hooks

Session Hooks

Privacy

Overview

Prerequisites

Session Lifecycle

Quick Start

Configuration Options

Return Values

Session Data

Actions

Loading States

Persisting Sessions

Executing Transactions

Custom Session Configuration

Custom Duration

Custom Max Calls

Error Handling

​Overview

​Prerequisites

​Session Lifecycle

​Quick Start

​Configuration Options

​Return Values

​Session Data

​Actions

​Loading States

​Persisting Sessions

​Executing Transactions

​Custom Session Configuration

​Custom Duration

​Custom Max Calls

​Error Handling

Overview

Prerequisites

Session Lifecycle

Quick Start

Configuration Options

Return Values

Session Data

Actions

Loading States

Persisting Sessions

Executing Transactions

Custom Session Configuration

Custom Duration

Custom Max Calls

Error Handling