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';

const config = {
  appId: 'your-app-id',
  network: 'sepolia', // 'sepolia' | 'mainnet'
  session: {
    defaultPolicy: {
      allowedContracts: ['0x049d...'],       // contracts the session key may call
      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
slotSlotConfigNo-Cartridge Slot (Katana) configuration — enables executeOnSlot()

​
Slot (Cartridge Katana) Configuration

If your app runs on a Cartridge Slot (a private, fee-free Katana chain forked from mainnet) or a local Katana node, add the slot key to your config. This unlocks executeOnSlot() — gasless transactions on the Slot chain with no paymaster needed.
[!WARNING] Important: Katana sequencers often report SN_MAIN via their RPC, but use a custom internal chain ID inside the Cairo VM. Because the Cavos session registration signature depends on this internal chain ID, you must manually set the chainId in your config to match the internal ID of your Katana genesis (e.g., WP_CAVOS / 0x57505f4341564f53). If you do not provide the correct internal chainId, you will encounter an “Invalid session key signature” error. 
const config = {
  appId: 'your-app-id',
  network: 'mainnet',       // Target network state
  paymasterApiKey: 'your-key',
  slot: {
    rpcUrl: 'https://api.cartridge.gg/x/your-project/katana',
    chainId: '0x57505f4341564f53',   // Override with internal Katana chain ID (e.g. WP_CAVOS)
  },
};
PropertyTypeRequiredDescription
rpcUrlstringYesRPC URL of your Cartridge Katana Slot instance
chainIdstringYesChain ID for the Slot chain. You must provide the exact internal VM chain ID to avoid signature mismatches.
[!NOTE] No relayer configuration is needed. The SDK uses a built-in Cavos relayer for the initial JWT session registration on Slot. Subsequent transactions use the session key directly.

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

​
Exports

The package exports:
ExportDescription
CavosProviderReact context provider
useCavosMain hook for SDK access
CavosSDKDirect SDK class (advanced)
JwtExpiredErrorError class for expired JWTs
OAuthWalletManagerIdentity & JWT handling (advanced)
OAuthTransactionManagerTransaction execution (advanced)
SessionManagerSession key lifecycle (advanced)
PaymasterIntegrationPaymaster wrapper (advanced)
WalletStatusTypeScript type for wallet state
SessionKeyPolicyTypeScript type for session policies