FloatingChat Documentation

Embeddable X402 payment widget for Solana - a beautiful floating chat interface with built-in USDC payment support.

Quick Start

Installation

ℹ️

Package Manager

This project uses pnpm as the package manager. Make sure you have it installed.

# Install the package (when published to npm)
npm install @askdolly/x402-embed-sdk

# Or use the local package in your monorepo
pnpm add @askdolly/x402-embed-sdk

Basic Usage

The FloatingChat component must be wrapped in a Solana WalletProvider. Here's a complete example:

app/layout.tsx

1import { WalletProvider } from '@/components/WalletProvider';
2
3export default function RootLayout({
4  children,
5}: {
6  children: React.ReactNode;
7}) {
8  return (
9    <html lang="en">
10      <body>
11        <WalletProvider>
12          {children}
13        </WalletProvider>
14      </body>
15    </html>
16  );
17}

app/page.tsx

1import { FloatingChat } from '@askdolly/x402-embed-sdk';
2
3export default function MyPage() {
4  return (
5    <div>
6      {/* Your page content */}
7      <h1>Welcome to my app</h1>
8
9      {/* Add FloatingChat widget */}
10      <FloatingChat
11        agentId="1"
12        agentName="Agent Alpha"
13        agentDescription="Specialized in DeFi trading"
14        position="bottom-right"
15        logoUrl="/logo.svg"
16        apiEndpoint="http://localhost:3000"
17      />
18    </div>
19  );
20}

✅

That's it!

The FloatingChat widget will now appear in the bottom-right corner of your page with full X402 payment integration.

API Reference

Complete list of props accepted by the FloatingChat component:

Property	Type	Default	Description
`agentId*`	`string`	-	Agent identifier for API requests
`agentName`	`string`	`'AI Agent'`	Display name for the agent
`agentAvatar`	`string`	`''`	Agent avatar image URL
`agentDescription`	`string`	`'How can I help you today?'`	Welcome message description
`position`	`'bottom-right' \| 'bottom-left'`	`'bottom-right'`	Position of the floating button
`logoUrl`	`string`	`'/logo.svg'`	Logo to display in floating button
`apiEndpoint`	`string`	`'http://localhost:3000'`	Backend API endpoint URL

ℹ️

Properties marked with * are required.

Configuration Guide

Environment Variables

Create a .env.local file in your app root:

.env.local

# Optional: Solana RPC URL (defaults to Devnet)
NEXT_PUBLIC_SOLANA_RPC_URL=https://api.devnet.solana.com

# Optional: Your API endpoint
NEXT_PUBLIC_API_ENDPOINT=http://localhost:3000

Wallet Provider Setup

The FloatingChat component requires a Solana wallet context. Create a WalletProvider component:

components/WalletProvider.tsx

1'use client';
2
3import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
4import {
5  ConnectionProvider,
6  WalletProvider as SolanaWalletProvider,
7} from '@solana/wallet-adapter-react';
8import { WalletModalProvider } from '@solana/wallet-adapter-react-ui';
9import { PhantomWalletAdapter } from '@solana/wallet-adapter-wallets';
10import { clusterApiUrl } from '@solana/web3.js';
11import { useMemo } from 'react';
12
13require('@solana/wallet-adapter-react-ui/styles.css');
14
15export function WalletProvider({ children }: { children: React.ReactNode }) {
16  const network = WalletAdapterNetwork.Devnet;
17  const endpoint = useMemo(() => clusterApiUrl(network), [network]);
18  const wallets = useMemo(() => [new PhantomWalletAdapter()], []);
19
20  return (
21    <ConnectionProvider endpoint={endpoint}>
22      <SolanaWalletProvider wallets={wallets} autoConnect>
23        <WalletModalProvider>{children}</WalletModalProvider>
24      </SolanaWalletProvider>
25    </ConnectionProvider>
26  );
27}

API Endpoint Configuration

The FloatingChat component communicates with your backend API for payment processing. You can configure the endpoint via the apiEndpoint prop:

1<FloatingChat
2  agentId="1"
3  apiEndpoint="https://api.yourdomain.com"
4  // ... other props
5/>

⚠️

Backend Requirements

Your API must implement the X402 payment protocol. The endpoint should accept 402 Payment Required responses and process Solana transactions.

Payment Flow

The FloatingChat component implements the complete X402 payment protocol for Solana:

1
Initial API Request
User sends a message, triggering an API request that returns 402 Payment Required
2
Transaction Building
Component builds a Solana SPL token transfer transaction (0.01 USDC) with compute budget instructions
3
User Signs Transaction
User approves and signs the transaction using their connected wallet (Phantom, Backpack, etc.)
4
Payment Submission
Signed transaction is sent back to API with X-PAYMENT header
5
Transaction Processing
Server validates and broadcasts the transaction to Solana network
6
Success Response
Server returns 200 OK with X-PAYMENT-RESPONSE header containing the transaction signature

Payment Configuration

Network:Solana Devnet

Token:USDC

Mint Address:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU

Amount per Request:0.01 USDC

Fee Payer (Gas Abstraction):CKPKJWNdJEqa81x7CkZ14GAgXhaHii3GnPAEERYPJgZJDncDU

ℹ️

Testnet USDC

Get free testnet USDC from the Circle Faucet: https://faucet.circle.com/

Styling & Customization

Position Options

The FloatingChat can be positioned in the bottom-right or bottom-left corner:

Bottom Right (Default)

<FloatingChat
  position="bottom-right"
  // ... other props
/>

Bottom Left

<FloatingChat
  position="bottom-left"
  // ... other props
/>

Custom Branding

Customize the chat interface with your own branding:

1<FloatingChat
2  agentId="1"
3  agentName="My Custom Agent"
4  agentAvatar="/my-avatar.png"
5  agentDescription="Welcome! How can I assist you today?"
6  logoUrl="/my-logo.svg"
7  // ... other props
8/>

ℹ️

The chat dialog size is fixed at 400x600px, and the floating button is 64x64px.

Integration Examples

Here are some common integration patterns:

Multiple Agents

1export default function MultiAgentPage() {
2  const [selectedAgent, setSelectedAgent] = useState('1');
3
4  return (
5    <div>
6      {/* Agent selector UI */}
7      <AgentSelector onSelect={setSelectedAgent} />
8
9      {/* FloatingChat with dynamic agent */}
10      <FloatingChat
11        agentId={selectedAgent}
12        agentName={getAgentName(selectedAgent)}
13        agentAvatar={getAgentAvatar(selectedAgent)}
14      />
15    </div>
16  );
17}

Conditional Rendering

1export default function ConditionalPage() {
2  const { user } = useAuth();
3
4  return (
5    <div>
6      {/* Only show chat to authenticated users */}
7      {user && (
8        <FloatingChat
9          agentId="1"
10          agentName="Support Agent"
11        />
12      )}
13    </div>
14  );
15}

Custom API Endpoint

1export default function CustomAPIPage() {
2  const apiEndpoint = process.env.NODE_ENV === 'production'
3    ? 'https://api.production.com'
4    : 'http://localhost:3000';
5
6  return (
7    <FloatingChat
8      agentId="1"
9      apiEndpoint={apiEndpoint}
10    />
11  );
12}

Troubleshooting

Wallet Not Connected

Error: "Please connect your wallet first"

Solution: Make sure:

You have a Solana wallet installed (Phantom, Backpack, etc.)
The WalletProvider is wrapping your app
You've clicked "Connect Wallet" before trying to send a message

Insufficient Balance

Error: "Insufficient USDC balance"

Solution: Get testnet USDC from Circle Faucet:

https://faucet.circle.com/

API Connection Failed

Error: "Failed to connect to API"

Solution:

Verify your API endpoint is correct and running
Check CORS configuration on your backend
Ensure the API implements the X402 payment protocol

Transaction Failed

Error: "Transaction failed"

Solution:

Check your wallet has enough SOL for transaction fees
Verify you're on Solana Devnet
Try again - sometimes Devnet is congested
Check the browser console for transaction signature and Solana Explorer link

Best Practices

✅ Use Environment Variables

Always store sensitive configuration like API endpoints in environment variables, not hardcoded in your components.

✅ Handle Errors Gracefully

The FloatingChat component includes built-in error handling, but make sure your backend also provides clear error messages.

✅ Test on Devnet First

Always test your integration thoroughly on Solana Devnet before moving to Mainnet. Use the Circle faucet to get testnet USDC.

✅ Monitor Transaction Logs

The component logs transaction signatures to the console. Use these to track payments and debug issues via Solana Explorer.

⚠️ Security Considerations

While the FloatingChat handles payment flow securely, remember:

Always validate transactions on your backend
Never trust client-side payment confirmations alone
Implement rate limiting to prevent abuse
Use HTTPS in production

FAQ

What is the X402 payment protocol?▼

X402 is a payment protocol that uses HTTP status code 402 (Payment Required) to request payment before providing a service. The FloatingChat component implements this protocol for Solana blockchain payments.

Can I use this on Solana Mainnet?▼

Yes! The component is configured for Devnet by default, but you can easily switch to Mainnet by updating your WalletProvider configuration and RPC endpoint. Make sure to update the USDC mint address for Mainnet.

How much does each request cost?▼

By default, each AI agent request costs 0.01 USDC (plus minimal SOL for transaction fees). This amount is configurable in your backend API.

Which wallets are supported?▼

The component works with any Solana wallet that supports the Wallet Adapter standard, including Phantom, Backpack, Solflare, and many others.

What is gas abstraction?▼

Gas abstraction means the transaction fees (in SOL) are paid by a facilitator, not the user. Users only need USDC to make payments, making the experience smoother.

Can I customize the chat UI?▼

Currently, the chat UI uses a fixed glassmorphism design. The size (400x600px) and core styling are not customizable, but you can configure the agent name, avatar, description, and logo.

How do I track payment history?▼

Transaction signatures are logged to the browser console and can be viewed on Solana Explorer. For complete payment history, implement tracking on your backend by storing transaction signatures from the X-PAYMENT-RESPONSE header.

Need help? Check out the live demo or visit the GitHub repository.