Skip to main content

​
Requirements

  • React 18+ or Next.js 13+
  • Node.js 18+
  • A Cavos App ID from the Dashboard

​
Installation

npm install @cavos/react starknet

​
Configuration

​
CavosProvider

Wrap your application with CavosProvider at the root level: 
import { CavosProvider } from '@cavos/react';

  appId: 'your-app-id',
  network: 'sepolia', // 'sepolia' | 'mainnet'
  session: {
    defaultPolicy: {
      allowedContracts: ['0x049d...'],
      spendingLimits: [{ token: '0x049d...', limit: 10n * 10n**18n }],
      maxCallsPerTx: 10
    }
  }
};

export default function App({ children }) {
  return (
    <CavosProvider config={config}>
      {children}
    </CavosProvider>
  );
}

​
Configuration Options

PropertyTypeRequiredDefaultDescription
appIdstringYes-Your Cavos App ID
network’sepolia’ | ‘mainnet’No’sepolia’Target Starknet network
paymasterApiKeystringNoCavos shared keyCustom AVNU Paymaster API key
starknetRpcUrlstringNoAlchemy RPCCustom Starknet RPC URL
enableLoggingbooleanNofalseEnable SDK debug logging
sessionSessionConfigNo-Session duration and default policy

​
Next.js App Router

For Next.js 13+ with App Router, mark the provider as a client component: 
// app/providers.tsx
'use client';

import { CavosProvider } from '@cavos/react';

export function Providers({ children }) {
  return (
    <CavosProvider 
      config={{ 
        appId: 'your-app-id',
        session: {
          defaultPolicy: {
            allowedContracts: ['0x049d...'],
            spendingLimits: [{ token: '0x049d...', limit: 10n * 10n**18n }],
            maxCallsPerTx: 10
          }
        }
      }}
    >
      {children}
    </CavosProvider>
  );
}

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

​
Passkey Modal Customization

The SDK includes a built-in passkey modal for wallet creation. Customize it via config: 
const config = {
  appId: 'your-app-id',
  passkeyModal: {
    title: 'Secure Your Wallet',
    description: 'Use biometrics to protect your funds',
    buttonText: 'Enable Passkey',
  },
};

​
Exports

The package exports:
ExportDescription
CavosProviderReact context provider
useCavosMain hook for SDK access
CavosSDKDirect SDK class (advanced)
WalletManagerWallet operations (advanced)
TransactionManagerTransaction execution (advanced)