Warning

B3 Global Accounts are deprecated. Upside and AnySpend now sign in with your own wallet. If you held funds in a Global Account and need help, ask in the B3 Discord. The team never DMs first and will never ask for your seed phrase or private key.

Overview

Session keys and permissions provide a secure way to allow applications to perform actions on behalf of users without requiring constant authentication. This is particularly useful for games and applications that need to execute transactions automatically.

Permission System

Permission Types

B3 Global Accounts support granular permissions that can be configured for different use cases:

  • Contract Interactions: Specify which smart contracts can be called
  • Token Limits: Set spending limits for native tokens and ERC-20 tokens
  • Time Restrictions: Define start and end dates for permissions
  • Transaction Limits: Control the maximum value per transaction

Permission Structure

typescript
interface Permissions { approvedTargets: string[]; // Contract addresses startDate: Date; // When permissions become active endDate: Date; // When permissions expire nativeTokenLimitPerTransaction: number; // ETH limit per tx // Additional ERC-20 token limits can be added}

Session Key Implementation

Basic Permission Request

tsx
import { RequestPermissionsButton } from "@b3dotfun/sdk/global-account/react";const b3Chain = { id: 8453, name: "Base", nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 }, rpc: "YOUR_BASE_RPC_URL",};function BasicPermissions() { const permissions = { approvedTargets: [ "0x...", // Your game contract ], startDate: new Date(), endDate: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days nativeTokenLimitPerTransaction: 0.01, // 0.01 ETH per transaction }; return ( <RequestPermissionsButton chain={b3Chain} sessionKeyAddress="0x..." // MetaMask or wallet address permissions={permissions} onSuccess={() => { console.log("Permissions granted successfully!"); }} onError={async (error) => { console.error("Permission request failed:", error); }} /> );}

Game-Specific Permissions

For gaming applications, you might need broader permissions:

tsx
function GamePermissions() { const gamePermissions = { approvedTargets: [ "0x...", // Game contract "0x...", // NFT marketplace "0x...", // Token contract ], startDate: new Date(), endDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days nativeTokenLimitPerTransaction: 0.001, // Small ETH limit for gas }; return ( <div className="game-permissions"> <h3>Grant Game Permissions</h3> <p>Allow this game to perform actions on your behalf for 7 days</p> <RequestPermissionsButton chain={b3Chain} sessionKeyAddress="0x..." permissions={gamePermissions} onSuccess={() => { // Redirect to game or update UI console.log("Game permissions granted!"); }} onError={async (error) => { console.error("Failed to grant game permissions:", error); }} /> </div> );}

Advanced Permission Patterns

Dynamic Permission Updates

tsx
import { useState } from "react";function DynamicPermissions() { const [permissionLevel, setPermissionLevel] = useState<'basic' | 'advanced'>('basic'); const getPermissions = (level: string) => { const basePermissions = { startDate: new Date(), endDate: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours }; if (level === 'basic') { return { ...basePermissions, approvedTargets: ["0x..."], // Limited contracts nativeTokenLimitPerTransaction: 0.001, }; } else { return { ...basePermissions, approvedTargets: ["0x...", "0x...", "0x..."], // More contracts nativeTokenLimitPerTransaction: 0.01, }; } }; return ( <div> <div className="permission-selector"> <button onClick={() => setPermissionLevel('basic')} className={permissionLevel === 'basic' ? 'active' : ''} > Basic Permissions </button> <button onClick={() => setPermissionLevel('advanced')} className={permissionLevel === 'advanced' ? 'active' : ''} > Advanced Permissions </button> </div> <RequestPermissionsButton chain={b3Chain} sessionKeyAddress="0x..." permissions={getPermissions(permissionLevel)} onSuccess={() => console.log(`${permissionLevel} permissions granted`)} /> </div> );}

Security Best Practices

Minimal Permissions

Only request the minimum permissions necessary for your application.

Short Duration

Use shorter permission durations for enhanced security.

Specific Targets

Specify exact contract addresses rather than broad permissions.

Regular Audits

Regularly audit and rotate session keys.

Error Handling

onError receives the Error from a failed request. The SDK defines no error codes, so handle every failure the same way:

tsx
function PermissionErrorHandling() { const handlePermissionError = async (error: Error) => { console.error("Permission request failed:", error.message); }; return ( <RequestPermissionsButton chain={b3Chain} sessionKeyAddress="0x..." onError={handlePermissionError} /> );}

Next Steps

React Hooks

Explore the available hooks.

Learn More
Examples

See the e-commerce and Next.js integration examples.

Learn More
Ask a question... ⌘I