Skip to main content

​
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:
  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

StateDescription
noneNo session exists
createdSession created locally, not yet registered on-chain
activeSession registered and usable
expiredSession has expired (time or call limit)
revokedSession has been revoked on-chain

​
Quick Start

import { useChipiWallet, useChipiSession } from "@chipi-stack/chipi-expo";
import { View, Text, TouchableOpacity, ActivityIndicator } from "react-native";

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: "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8",
      entrypoint: "transfer",
      calldata: [recipientAddress, amount, "0x0"],
    }]);
  };

  return (
    <View style={{ padding: 20, gap: 16 }}>
      <Text>Session: {sessionState}</Text>
      {hasActiveSession && <Text>Calls remaining: {remainingCalls}</Text>}
      
      {!hasActiveSession ? (
        <TouchableOpacity 
          onPress={handleSetup}
          disabled={isCreating || isRegistering}
        >
          <Text>Setup Session</Text>
        </TouchableOpacity>
      ) : (
        <TouchableOpacity onPress={handleTransfer} disabled={isExecuting}>
          <Text>Transfer (Gasless)</Text>
        </TouchableOpacity>
      )}
    </View>
  );
}

​
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
}
OptionTypeDefaultDescription
walletSessionWalletRequiredWallet data (must be CHIPI type)
encryptKeystringRequiredUser’s PIN for signing
getBearerToken() => Promise<string>RequiredAuth token function
storedSessionSessionKeyDatanullPreviously stored session
onSessionCreated(session) => void-Callback to persist new session
defaultDurationSecondsnumber21600Session duration (6 hours)
defaultMaxCallsnumber1000Max calls per session
autoCheckStatusbooleantrueAuto-fetch on-chain status

​
Return Values

​
Session Data

PropertyTypeDescription
sessionSessionKeyData | nullCurrent session data
sessionStatusSessionDataResponseOn-chain session status
sessionStateSessionStateLifecycle state
hasActiveSessionbooleanWhether session is usable
isSessionExpiredbooleanWhether session has expired
remainingCallsnumber | undefinedCalls left in session
supportsSessionbooleanWhether wallet supports sessions

​
Actions

MethodReturnsDescription
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()voidClear local session state
refetchStatus()Promise<void>Refresh on-chain status

​
Loading States

PropertyDescription
isCreatingCreating session locally
isRegisteringRegistering session on-chain
isRevokingRevoking session on-chain
isExecutingExecuting transaction
isLoadingStatusFetching on-chain status

​
Persisting Sessions with SecureStore

In Expo, use expo-secure-store to safely persist session data: 
import * as SecureStore from 'expo-secure-store';
import { useState, useEffect } from "react";
import { useChipiWallet, useChipiSession } from "@chipi-stack/chipi-expo";

const SESSION_KEY = "chipi-session";

function PersistentSession() {
  const { wallet } = useChipiWallet({ ... });
  const [storedSession, setStoredSession] = useState(null);
  
  // Load session on mount
  useEffect(() => {
    async function loadSession() {
      const saved = await SecureStore.getItemAsync(SESSION_KEY);
      if (saved) {
        setStoredSession(JSON.parse(saved));
      }
    }
    loadSession();
  }, []);
  
  const {
    session,
    hasActiveSession,
    createSession,
    registerSession,
  } = useChipiSession({
    wallet,
    encryptKey: pin,
    getBearerToken: getToken,
    storedSession,
    onSessionCreated: async (newSession) => {
      // Persist to SecureStore
      await SecureStore.setItemAsync(SESSION_KEY, JSON.stringify(newSession));
      setStoredSession(newSession);
    },
  });

  // Session is automatically restored on mount!
}

​
Using with Biometrics

Combine with useBiometrics hook for secure PIN-less UX: 
import { useBiometrics, useChipiWallet, useChipiSession } from "@chipi-stack/chipi-expo";

function BiometricSession() {
  const { authenticate, isAvailable } = useBiometrics();
  const { wallet } = useChipiWallet({ ... });
  
  // Store PIN securely and retrieve with biometrics
  const [encryptKey, setEncryptKey] = useState("");
  
  const {
    hasActiveSession,
    createSession,
    registerSession,
    executeWithSession,
  } = useChipiSession({
    wallet,
    encryptKey,
    getBearerToken: getToken,
  });

  const handleSetupWithBiometrics = async () => {
    // Authenticate with Face ID / Touch ID
    const success = await authenticate("Confirm to setup session");
    if (!success) return;
    
    // Retrieve stored PIN (implement your own secure storage)
    const pin = await getStoredPin();
    setEncryptKey(pin);
    
    await createSession();
    await registerSession();
  };

  // ...
}

​
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) {
  Alert.alert("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.alert("Error", "Please use a CHIPI wallet for sessions");
    } else {
      Alert.alert("Error", err.message);
    }
  }
};