Skip to main content

​
CavosProvider

The provider component that initializes the SDK and provides context to child components. 
import { CavosProvider } from '@cavos/react';

<CavosProvider config={config}>
  <App />
</CavosProvider>

​
Config Props

interface CavosConfig {
  appId: string;                    // Required: Your Cavos App ID
  network?: 'sepolia' | 'mainnet';  // Default: 'sepolia'
  paymasterApiKey?: string;         // Custom paymaster key
  starknetRpcUrl?: string;          // Custom RPC URL
  enableLogging?: boolean;          // Enable debug logs
  passkeyModal?: {                  // Modal customization
    title?: string;
    description?: string;
    buttonText?: string;
  };
}

​
useCavos Hook

Access SDK functionality from any child component: 
import { useCavos } from '@cavos/react';

function MyComponent() {
  const {
    // State
    isAuthenticated,
    user,
    address,
    isLoading,
    hasActiveSession,
    requiresWalletCreation,
    
    // Actions
    login,
    createWallet,
    execute,
    signMessage,
    logout,
    deleteAccount,
    retryWalletUnlock,
    getOnramp,
    
    // SDK instance
    cavos,
  } = useCavos();

  return <div>...</div>;
}

​
State Properties

PropertyTypeDescription
isAuthenticatedbooleanUser is authenticated (OAuth or passkey)
userUserInfo | nullUser info from OAuth (or placeholder for passkey)
addressstring | nullWallet address if loaded
isLoadingbooleanSDK is initializing or processing
hasActiveSessionbooleanSession is active and not expired
requiresWalletCreationbooleanUser needs to create wallet (shows modal)

​
Action Methods

​
login(provider, redirectUri?)

Start OAuth authentication: 
await login('google');
await login('apple');
await login('google', 'https://myapp.com/callback');

​
createWallet()

Create or recover a wallet: 
await createWallet();
For passkey-only mode, call this without prior login().

​
execute(calls)

Execute transactions using session keys: 
// Requires active session!
const txHash = await execute({
  contractAddress: '0x...',
  entrypoint: 'transfer',
  calldata: ['0x...', '1000', '0'],
});
[!NOTE] All transactions are signed with the session key and are gasless. No signature prompt appears.

​
signMessage(messageHash)

Sign a message with the session key: 
const signature = await signMessage('0x123...'); // hex string message hash
// Returns { r: string, s: string }

​
logout()

Clear session and wallet: 
await logout();

​
deleteAccount()

Permanently delete account: 
await deleteAccount();

​
useSession Hook

Manage session keys for signature-free transactions: 
import { useSession } from '@cavos/react';

function SessionManager() {
  const {
    hasActiveSession,
    createSession,
    clearSession,
    executeWithSession,
  } = useSession();

  return <div>Session: {hasActiveSession ? 'Active' : 'Inactive'}</div>;
}

​
Session Properties

PropertyTypeDescription
hasActiveSessionbooleanSession is active and not expired

​
Session Methods

​
createSession(policy)

Create a session with a policy defining allowed actions: 
await createSession({
  allowedMethods: [
    { contractAddress: '0x...token', selector: 'transfer' },
    { contractAddress: '0x...token', selector: 'approve' },
    { contractAddress: '0x...nft', selector: 'mint' },
  ],
  expiresAt: Date.now() + 60 * 60 * 1000, // 1 hour
});
[!IMPORTANT] After createSession(), the user’s private key is cleared from memory. Only the session key remains.

​
clearSession()

Invalidate the current session: 
clearSession();

​
executeWithSession(calls)

Execute transactions with the session key: 
const txHash = await executeWithSession({
  contractAddress: '0x...',
  entrypoint: 'transfer',
  calldata: ['0x...', '1000', '0'],
});

​
Complete Example

import { useCavos, useSession } from '@cavos/react';

function App() {
  const { login, logout, address, isAuthenticated } = useCavos();
  const { hasActiveSession, createSession } = useSession();

  const handleSetup = async () => {
    // 1. Authenticate
    await login('google');
    
    // 2. Create session (user signs once)
    await createSession({
      allowedMethods: [
        { contractAddress: TOKEN_ADDRESS, selector: 'transfer' },
      ],
      expiresAt: Date.now() + 60 * 60 * 1000,
    });
    
    // ✓ Ready for signature-free transactions
  };

  const handleTransfer = async () => {
    const { execute } = useCavos();
    
    // No signature popup!
    const txHash = await execute({
      contractAddress: TOKEN_ADDRESS,
      entrypoint: 'transfer',
      calldata: [recipient, amount, '0'],
    });
  };

  if (!isAuthenticated) {
    return <button onClick={handleSetup}>Login</button>;
  }

  return (
    <div>
      <p>Address: {address}</p>
      <p>Session: {hasActiveSession ? '✅ Active' : '❌ Create session first'}</p>
      <button onClick={handleTransfer} disabled={!hasActiveSession}>
        Transfer
      </button>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

​
Session Policy Reference

interface SessionPolicy {
  allowedMethods: Array<{
    contractAddress: string;  // Contract address (hex)
    selector: string;         // Function name
  }>;
  expiresAt: number;          // Timestamp in milliseconds
  metadata?: string;          // Optional metadata
}

​
Best Practices

  1. Limit scope: Only include methods your app actually needs
  2. Short expiration: Use 1 hour or less for sensitive operations
  3. Re-create on demand: Create new sessions when needed rather than long-lived ones
  4. Check before execute: Always verify hasActiveSession before execute()