@agentfish/react

React SDK for AgentFish - embedded non-custodial wallets with seamless x402 payment handling.

Overview

AgentFish React provides a complete authentication and wallet management solution for React applications. It enables:

• Embedded wallets - Non-custodial, secure key management
• Multiple auth methods - Email magic link, Passkey (WebAuthn), External Wallets (Phantom, MetaMask, etc.)
• Automatic x402 payments - Seamless payment handling for AI APIs
• Customizable UI - Full theming support with CSS variables
• Zero configuration - No external service setup required

Installation

npm install @agentfish/react
# or
pnpm add @agentfish/react

Quick Start

import { AgentFishProvider, SignIn, WalletButton, useAuth } from '@agentfish/react';
import '@agentfish/react/styles.css';

function App() {
  return (
    <AgentFishProvider>
      <YourApp />
    </AgentFishProvider>
  );
}

function YourApp() {
  const { isOnboarded } = useAuth();

  // isOnboarded = authenticated + has a wallet
  // If authenticated without a wallet, the provider auto-shows a wallet creation modal
  return (
    <div>
      {isOnboarded ? (
        <WalletButton />
      ) : (
        <SignIn providers={['email', 'passkey', 'wallet']} />
      )}
    </div>
  );
}

Components

<AgentFishProvider>

Wraps your app with AgentFish context. Required at the root level.

<AgentFishProvider
  config={{
    // Optional: API key for server wallet authorization
    apiKey: 'agentfish_live_xxx',
    
    // x402 Configuration (optional)
    facilitatorUrl: string,   // Custom x402 facilitator (default: AgentFish)
    x402Version: 1 | 2,       // x402 protocol version (default: 1)
    
    // Other options
    rpcUrl: string,           // Solana RPC URL
    theme: ThemeConfig,       // UI customization
  }}
>
  {children}
</AgentFishProvider>

Note: No configuration required for basic usage! The SDK automatically handles authentication and wallet management.

<SignIn>

Authentication component with support for email, passkey, and external wallet auth.

// Uncontrolled mode - shows built-in button
<SignIn 
  providers={['email', 'passkey', 'wallet']}
  onSuccess={(wallet) => console.log('Authenticated!', wallet.address)}
  onError={(error) => console.error(error)}
/>

// Controlled mode - use your own button
const [isOpen, setIsOpen] = useState(false);

<button onClick={() => setIsOpen(true)}>Sign In</button>
<SignIn 
  isOpen={isOpen}
  onOpenChange={setIsOpen}
  providers={['email', 'wallet']}
  onSuccess={(wallet) => console.log('Authenticated!')}
/>

Props:

• providers - Array of auth methods: 'email', 'passkey', 'wallet'
• isOpen / onOpenChange - Controlled mode for custom trigger buttons
• onSuccess - Callback with wallet address on successful auth
• onError - Error callback
• className / classNames - Custom styling

<WalletButton>

Displays wallet info with a dropdown for balance, address, and actions.

<WalletButton 
  variant="full"           // 'full' | 'compact' | 'icon-only'
  showBalance={true}       // Show balance in button
  dropdownAlign="right"    // 'left' | 'right'
  dropdownDirection="down" // 'up' | 'down'
  onAddFunds={() => {}}    // Callback when add funds clicked
  onDisconnect={() => {}}  // Callback on disconnect
/>

<AddFundsModal>

QR code modal for funding the wallet.

<AddFundsModal 
  isOpen={true}
  onClose={() => setIsOpen(false)}
  address="wallet-address"
/>

Hooks

useAuth()

Authentication state and actions.

const { 
  isAuthenticated,    // boolean - user has a valid session
  isOnboarded,        // boolean - user is authenticated AND has a wallet
  needsWalletSetup,   // boolean - user is authenticated but has no wallet yet
  isLoading,          // boolean
  user,               // User | null
  signOut,            // () => Promise<void>
} = useAuth();

Onboarding gate: When a user authenticates but doesn't have a wallet yet, the provider automatically displays a paywall modal prompting them to create one. Use isOnboarded instead of isAuthenticated to gate access to features that require a wallet.

useWallet()

Wallet information.

const { 
  wallet,           // Wallet | null
  balance,          // number (USDC)
  address,          // string | null
  refreshWallet,    // () => Promise<void>
} = useWallet();

useAgentFish()

Full context access including x402 payment functions.

const { 
  // Auth
  isAuthenticated,
  user,
  wallet,
  
  // Payments
  fetch,            // x402-aware fetch wrapper
  pay,              // Manual payment function
  
  // Wallet
  balance,
  refreshWallet,
  getPayments,
} = useAgentFish();

// x402-aware fetch - automatically handles 402 Payment Required
const response = await fetch('https://ai-api.com/chat', {
  method: 'POST',
  body: JSON.stringify({ message: 'Hello' }),
  maxPayment: 1.00, // Max $1 USDC
});

// Manual payment
const { signature } = await pay(0.50, 'https://merchant.com', 'merchant-address');

Theming

CSS Variables

Import the base styles and override CSS variables:

@import '@agentfish/react/styles.css';

:root {
  --af-primary: #0EA5E9;
  --af-primary-hover: #0284C7;
  --af-background: #0f0f1a;
  --af-surface: #1a1a2e;
  --af-border: #2d2d44;
  --af-text: #ffffff;
  --af-text-muted: #9ca3af;
  --af-radius: 12px;
}

Theme Config

Pass theme configuration to the provider:

<AgentFishProvider
  config={{
    theme: {
      mode: 'dark', // 'light' | 'dark'
      colors: {
        primary: '#0EA5E9',
        primaryHover: '#0284C7',
        background: '#0f0f1a',
        surface: '#1a1a2e',
        border: '#2d2d44',
        text: '#ffffff',
        textMuted: '#9ca3af',
      },
      radius: '12px',
      fontFamily: 'Inter, sans-serif',
    },
  }}
>

x402 Payment Protocol

The SDK supports both x402 v1 and v2 protocols:

• v1 (default): Uses X-PAYMENT header, JSON body for 402 responses
• v2: Uses PAYMENT-SIGNATURE header, PAYMENT-REQUIRED header

Facilitator Configuration

By default, AgentFish acts as the x402 facilitator - handling payment settlement automatically. You can optionally use an external facilitator:

<AgentFishProvider
  config={{
    // Use AgentFish as facilitator (default - recommended)
    // No facilitatorUrl needed
    
    // OR use external facilitator
    facilitatorUrl: 'https://x402.payai.network',
    
    x402Version: 1, // Protocol version
  }}
>

When to use an external facilitator:

• You're building a payment network with multiple providers
• You need custom payment routing logic
• You want to use a third-party settlement service

Supported Wallets

External Wallet Auth

• Solana: Phantom, Solflare
• EVM: MetaMask, Coinbase Wallet

The SDK detects installed wallets and shows appropriate options.

TypeScript

Full TypeScript support with exported types:

import type {
  AgentFishConfig,
  ThemeConfig,
  Wallet,
  User,
  Payment,
  SignInProps,
  WalletButtonProps,
  X402Version,
} from '@agentfish/react';

Development

# Build
pnpm nx build @agentfish/react

# Type check
pnpm nx typecheck @agentfish/react

# Test
pnpm nx test @agentfish/react

License

MIT