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 work with CHIPI wallets and with SHHH wallets whose signer is STARK or ED25519 (every SHHH wallet the SDK creates, including passkey wallets; SHHH needs 14.14.0 or later in this hook). READY wallets do not support session keys. Check supportsSession before offering sessions.

Prerequisites

Before using useChipiSession, you need:

A wallet that supports sessions: CHIPI, or SHHH with a STARK / ED25519 signer (check supportsSession, wallet.supportsSessionKeys or walletSupportsSessions(wallet))
The user’s encryption key: a PIN (encryptKey) or a function that resolves it on demand, such as a passkey (getEncryptKey, 14.14.0+)
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-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: "0x033068F6539f8e6e6b131e6B2B814e6c34A5224bC66947c47DaB9dFeE93b35fb",
      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>
  );
}

Passkey wallets and server-held sessions (14.14.0+)

For an agent that runs on your server, create the session key there and register it from the app with the user’s biometrics. The session and its spending caps go in one owner-signed transaction, so the user sees one prompt:

const { registerSession, revokeSession } = useChipiSession({
  wallet,
  // Face ID / fingerprint via expo-local-authentication
  getEncryptKey: () => getNativeWalletEncryptKey(userId),
  getBearerToken: () => getToken({ skipCache: true }),
});

// sessionPublicKey and validUntil come from your server (sdk.sessions.createSessionKey)
await registerSession({
  sessionPublicKey,
  validUntil,
  maxCalls: 500,
  allowedEntrypoints: ["transfer", "approve"],
  spendingPolicies: [
    { token: USDC, maxPerCall: 5_000_000n, maxPerWindow: 20_000_000n, windowSeconds: 86_400 },
  ],
});

// Later, to stop it:
await revokeSession(sessionPublicKey);

Function names in allowedEntrypoints are converted to selectors. The whole flow, server side included, is in Agent with a session key and a passkey.

Configuration Options

interface UseChipiSessionConfig {
  // Required
  wallet: SessionWallet | null | undefined;
  getBearerToken: () => Promise<string | null | undefined>;
  // One of these two
  encryptKey?: string;                                        // a PIN, or a key you already hold
  getEncryptKey?: () => Promise<string | null | undefined>;  // e.g. a passkey (14.14.0+)
  
  // 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	CHIPI, or SHHH with a STARK / ED25519 signer
`encryptKey`	`string`	-	PIN (or a key you already hold). Set this or `getEncryptKey`
`getEncryptKey`	`() => Promise<string>`	-	Resolves the key only when an action runs, e.g. `() => getNativeWalletEncryptKey(userId)`. Called before `getBearerToken`, so the token is fresh after the biometric prompt. Every action resolves it again, so `executeWithSession` prompts too. Ignored when `encryptKey` is set (14.14.0+)
`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). Pass `sessionPublicKey` + `validUntil` to register a key created elsewhere (e.g. on your server), and `spendingPolicies` to set its caps in the same transaction (14.14.0+)
`revokeSession(sessionPublicKey?)`	`Promise<string>`	Revoke on-chain (returns txHash). Defaults to the current session; pass a key to revoke one created elsewhere (14.14.0+)
`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 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);
    }
  }
};

Getting Started

Gasless

Expo Guides

SDK Hooks

Session Hooks

Overview

Prerequisites

Session Lifecycle

Quick Start

Passkey wallets and server-held sessions (14.14.0+)

Configuration Options

Return Values

Session Data

Actions

Loading States

Persisting Sessions with SecureStore

Using with Biometrics

Executing Transactions

Custom Session Configuration

Custom Duration

Custom Max Calls

Error Handling

​Overview

​Prerequisites

​Session Lifecycle

​Quick Start

​Passkey wallets and server-held sessions (14.14.0+)

​Configuration Options

​Return Values

​Session Data

​Actions

​Loading States

​Persisting Sessions with SecureStore

​Using with Biometrics

​Executing Transactions

​Custom Session Configuration

​Custom Duration

​Custom Max Calls

​Error Handling

Overview

Prerequisites

Session Lifecycle

Quick Start

Passkey wallets and server-held sessions (14.14.0+)

Configuration Options

Return Values

Session Data

Actions

Loading States

Persisting Sessions with SecureStore

Using with Biometrics

Executing Transactions

Custom Session Configuration

Custom Duration

Custom Max Calls

Error Handling